What “Ready” Means—and What It Does Not
Agent Reach’s Doctor exists to answer a deceptively difficult question: is a route genuinely usable, or does it merely look installed? This chapter follows the diagnostic path from command discovery to executable behavior, then compares how the project handles public APIs, browser bridges, MCP configuration, and login-backed tools. The practical aim is to read a status report as evidence with a known strength—not as a universal guarantee that every requested page, post, or video will work.
A Command Can Exist and Still Be Broken
The most misleading failure is often the one that looks like success. A program name can be found on the system’s PATH even though the program cannot start. This happens, for example, when a command installed inside a virtual environment still points to an interpreter that disappeared after a system Python upgrade. A superficial check sees the file and concludes that the dependency is present. The first real invocation fails.
Agent Reach’s probing helper is designed around that distinction. It first looks for the command, but then actually executes a side-effect-free operation, normally a version check. The result separates several cases that would otherwise be collapsed into “not working”:
- Missing: no command can be found.
- Broken: a command is found but its executable or interpreter cannot run.
- Timeout: the process did not respond within the allowed interval.
- Error: the process ran but returned a non-success exit code.
- Success: the probe completed without an execution failure.
The difference is operational. A missing yt-dlp calls for installation. A broken shim calls for reinstalling the package or rebuilding its environment. A timeout may point toward a stalled process or constrained machine rather than a missing dependency. A nonzero result can require reading the command’s own error, not repeating an installation step. The probe therefore does not just grade the machine; it narrows the set of plausible causes.
This is why the project’s channel adapters do not treat shutil.which() as proof of health. The YouTube channel runs yt-dlp --version and then checks the JavaScript runtime and relevant configuration separately. The GitHub channel runs a version probe while suppressing update and telemetry behaviors that can write local state, then inspects credential metadata rather than invoking an authentication status command. These are small choices, but they preserve the causal order of diagnosis: first establish that the executable runs, then inspect the additional condition that may prevent the intended operation.
Doctor is the layer that collects those channel-level findings. If one adapter raises an exception, Doctor converts that failure into an error result instead of allowing one misbehaving platform to destroy the entire report. It also scrubs credential-bearing URL material at the output boundary. The report can consequently describe a problem and its likely remedy without turning diagnostic output into an accidental secret-disclosure channel.
The same caution applies to local configuration. Agent Reach reads bounded regular files without following symlinked path components. This limits both the amount of data a diagnostic pass will ingest and the possibility that a path silently redirects the checker to an unrelated target. It validates enough structure to determine whether a setting can be interpreted, but avoids treating the existence of a file as proof that the external service accepts its contents.
That restraint is important because health checking is not free of side effects by definition. A command named status may refresh a cookie, start a daemon, create a device identifier, or rewrite a configuration file. Agent Reach’s diagnostic code therefore chooses narrower observations when it can. The Reddit adapter inspects the saved credential file rather than running the upstream status command that may refresh browser data. The GitHub adapter avoids an authentication check that can create local state. The OpenCLI adapter avoids opencli doctor because the upstream command auto-starts its daemon.
A useful diagnosis is therefore a controlled experiment. It changes as little as possible, observes a bounded behavior, and reports what that observation can distinguish. The result is not a complete explanation of the platform, but it is more informative than a package inventory and safer than blindly running every available status command.
A Green Path Is Not a Verified Answer
The status labels in Doctor describe different kinds of readiness. off generally means that the required route is absent. error means the checker encountered a broken or failed condition. warn means there is a plausible path but a prerequisite, configuration step, or live verification is incomplete. ok is the strongest label, but its meaning still depends on what that channel actually tested. A public API probe can be stronger evidence of reachability than a configuration-file inspection, while neither necessarily proves that a particular content operation will succeed.
The OpenCLI route makes this distinction visible. Its status model separates the command being installed, the local daemon, files that look like an installed browser extension, and a live extension connection. An extension directory on disk is only disk evidence; the user may have disabled the extension, removed it from the browser, or never loaded it. A live response from the documented loopback status endpoint is stronger evidence that the bridge is present. Even then, the project deliberately stops short of claiming that the user is logged in to the target platform or that the requested site command will work. A connected bridge is not the same thing as verified content access.
The same principle governs MCP-backed channels. If a local configuration contains an Exa or LinkedIn server entry, Doctor can report that the route is configured. It does not automatically start a remote service or expand every editor import that might contain additional credentials. The configuration is evidence of an intended connection, not proof that the service is reachable, authenticated, or capable of answering the requested query. A warning in this situation is not a failure of the checker; it is an accurate refusal to turn static configuration into a live-service claim.
Other channels can make a stronger bounded test. The V2EX adapter calls a restricted public HTTPS API and parses a response within a size limit. The Bilibili adapter can test whether its search API responds successfully, and its command-line candidate can execute a lightweight version probe. These checks establish something real about the route. They still do not establish everything a user might mean by “Bilibili works.” Search, video details, subtitles, and audio may use different paths and have different conditions. A response to one endpoint cannot be generalized to all platform operations.
YouTube’s status is an especially clear example of layered evidence. A healthy yt-dlp executable and an available JavaScript runtime are necessary for the documented route, but Doctor does not request the user’s particular video. The skill reference therefore defines success at the content level: obtain non-empty subtitles or a transcript, not merely a zero exit code or an active_backend value. If the caption response is empty, a browser-backed transcript route may be tried; if captions do not exist or those attempts fail, audio transcription is a different fallback with its own limits and provider decision.
This distinction changes how repair messages should be read. A message that recommends installing a missing runtime, repairing a broken virtual environment, or adding a configuration entry is a prescription tied to an observed local condition. It is not a promise that a platform will accept subsequent requests. If a site has changed its anti-bot rules, reinstalling the client may leave the actual cause untouched. If an account is not logged in, a connected browser bridge does not supply that missing state. If a service is configured but unreachable, editing the local name does not make the network path exist.
The status report is best understood as an evidence ladder rather than a traffic light. At the bottom is discovery: a command or file exists. Above that is execution: the command can run. Next come configuration and connection: the relevant local state or bridge appears ready. Then comes backend selection: the channel has enough evidence to identify a route for the capability. At the top is content verification: the particular operation returned meaningful data. These levels can be reached by different paths, and some channels intentionally stop below the top to avoid unsafe side effects.
The ladder also explains why two channels with the same label are not necessarily making claims of equal strength. A bounded public API request can demonstrate that a particular endpoint responded and that its data had the expected shape. A version probe demonstrates that a local binary can execute, but says nothing about the network request it will make later. A local MCP configuration demonstrates that a name is registered, but not that the remote service is reachable. A live browser-bridge status demonstrates that a daemon and extension can communicate, but not that the user’s session grants access to the requested site. Doctor presents these results together because a user needs one operational picture, not because they are interchangeable measurements.
This is also why a missing or null active backend should be read carefully. It may mean that no candidate exists, but it may also mean that the checker deliberately refused to promote a candidate after observing only a warning-level condition. That conservatism is useful: it avoids turning “installed but not verified” into a routing instruction. A user who sees no active backend should ask which evidence is absent before installing another tool. The missing fact might be a JavaScript runtime, a browser extension connection, a saved session, a local service, or a successful content response. Each calls for a different remedy.
A disciplined diagnosis therefore proceeds from the least invasive explanation to the most external one. First ask whether the expected command or service exists. Then ask whether it can execute. If it can, check the local prerequisite that the channel documents. Only after those conditions hold should the investigation move to network reachability, login state, platform defenses, or content-specific behavior. This sequence prevents an agent from recommending a proxy for a broken executable, reinstalling a healthy tool because a platform returned 403, or asking a user to export credentials when the actual failure is a missing media runtime.
The sequence is not infallible. A platform can return a normal-looking response while silently omitting fields, a credential can be present but expired, and an endpoint can work during Doctor’s short probe but fail under a later request. That is why the project’s strongest guidance defines success using the requested content itself. A diagnostic layer can make the next action clearer; it cannot replace an operation-level acceptance test. The closer the check is to the user’s actual goal, the stronger the evidence—but also the more likely the check is to touch external state, consume quota, or expose credentials. The design tension is to increase evidence without turning health checking into an uncontrolled execution engine.
The diagram is a reasoning aid, not a claim that every channel follows one literal sequence. A public web reader may skip login configuration. A browser-backed route may be connected while its site account remains unverified. An MCP entry may be configured without being reachable. The point is to prevent one state from silently standing in for another.
For a reader deciding what to do next, three questions are more useful than “is it green?” What did the check actually execute? Which state did it observe—installation, execution, configuration, connection, or content? What additional condition belongs to the requested operation? Those questions distinguish a local repair from a user action and both from an external platform failure.
This is the operational meaning of the capability layer’s promise to be inspectable. Agent Reach cannot make every route stable, but it can expose the difference between a broken local tool and an unverified external capability. It can tell an agent when a fallback exists, when a user’s approval or login is required, and when the evidence stops. The next step is to use that evidence model as a judgment framework: before choosing a route, identify what must be true, who owns that state, and what result would count as success.