testing.md

Testing strategy

The full list of cases the resolver, launcher, check, doctor and shim test suites cover. Verbatim from an earlier README.md.

Testing strategy

the resolver's cascade and materialisation logic is exactly the kind of thing that's easy to get subtly wrong, so it gets thorough unit tests before anything else is built on it:

• Each cascade layer overriding the last; path overrides beating their parent category
• Directory rules folding correctly for nested paths, and correctly composing configuration profiles mid-tree
• The secret category being unconditionally un-overridable — including an explicit entries override attempt targeting a secret-category file, not only a bare categories: { secret: true } toggle, since the two-phase algorithm's usual "entries beat categories" rule does not apply to this one category
• ~/.claude/backups/ never symlinked in under any configuration, matching secret; ~/.claude.json (a sibling of ~/.claude, not a descendant) never appearing in the resolver's entry manifest at all, confirming it's structurally excluded rather than merely defaulted off
• Committed .agent-shim.json/.agent-shim.local.json files at different tree depths folding shallowest-to-deepest like local directory rules, composing correctly when both apply to the same directory
• Glob patterns matching correctly against literal ~/.claude/projects/ directory names, never attempting to decode a name back to a real path
• Multi-level and diamond extends chains resolving correctly, and a circular extends definition (a → b → a) being detected and rejected by the walker rather than looping or stack-overflowing
• One identity producing different resolved states under two different configuration profiles, with no leakage between them
• The exact two-phase merge algorithm: a shallow layer's specific entry surviving a later, deeper layer's blanket category flip on the same category; an exact literal key beating a glob from an earlier layer; two globs from different layers resolving to the later layer's value; two globs from the same layer resolving by longest-literal-prefix and then source order; two layers setting the identical category resolving to plain last-layer-wins
• Conditional entries with injectable/fake mtimes, a fake resolved branch, and a fake env snapshot (never real filesystem/git/environment state, so tests aren't time-dependent, git-dependent, or slow) — a newerThan condition including a fresh file and excluding a stale one under the same glob, a branch condition applying only on a matching branch, an env condition applying only when the right variable is set, and a conditionally-matched subtree always being materialised rather than symlinked
• A materialised directory reconciling any real (non-symlink) children written since the last resync back into ~/.claude before re-deciding, and collapsing back into a plain symlink once its split condition no longer holds
• A runtime-category collision between a superseded farm and the current one resolving automatically (carryOver's own classification parameter, covered directly, and end-to-end through both resyncFarm's crash-recovery path and resolveFarmConflicts's interactive one) — the decision never calling the caller's decide/prompt at all, a genuinely ambiguous collision alongside it in the same superseded farm still reaching that prompt, and the whole auto-resolution falling back to the old fully-manual behaviour when no classification is given

identityManager.ts, configProfiles.ts, directoryRules.ts, and configure.ts stay thin adapters over the resolver, so most of their correctness rides on the resolver's own test coverage above. The one exception is listIdentities, whose own tests cover a deliberate departure from the "throw a validation error and let it propagate" convention: an identity.json that is present but unreadable — malformed JSON, or valid JSON this version's IdentitySchema rejects — is reported as that one identity's own unreadable entry, so a single bad file never hides every other identity from agent-shim identity list at the moment they most need to be visible. Only those two content-shaped failures are absorbed; a permission error still propagates. A wholly absent identity.json remains a silent skip rather than a problem, and both it and doctor's own enumeration filter out directories whose name starts with ., since IdentitySchema requires an identity name to start with a letter or digit and a resync's own .<identity>.scratch.<suffix>/.<identity>.previous.<suffix> directories are therefore never identities to report on. launcher.ts carries three separately-testable responsibilities of its own that aren't covered by the resolver's purity, and need their own coverage: translating a resolved Map<path, boolean> into real filesystem side effects (creating/removing symlinks, materialising/collapsing directories, diffing against the farm's prior state, the per-identity lock and atomic-swap behaviour from Directory rules) against a fake/in-memory filesystem; invoking the real claude binary via an injected spawn function (argv/env construction, exit-code propagation), never a real subprocess in a unit test; and the ambient-credential guard — given a fake process.env, refusing to proceed when any of the six named variables is set and the active identity's allowAmbientCredential is unset/false, proceeding when it's true, and proceeding when AGENT_SHIM_ALLOW_AMBIENT_CREDENTIAL=1 is set for that one call regardless of the identity's own setting. Provider selection gets the same launcher-level coverage against a fake providers map: the child env gaining the provider's base URL, token, static env entries, and no other credential variable; an unknown provider refusing with the known names listed (exit 1); a credential block with no usable source refusing with exit 64; a --provider flag beating a cascade-pinned provider; and the guard standing aside for a provider launch (agent-shim supplies the child's credential itself) while still refusing an ambient ANTHROPIC_AUTH_TOKEN with no provider selected. Those launcher-level provider cases live in launcherProvider.test.ts, which shares its fakes with launcher.test.ts through test-helpers.ts, and also cover command-backed sources (a fake CredentialPort supplies the command's output; a non-zero exit refuses with exit 64 without logging the output, and an interactive source with nobody present refuses without running) and target apiKey against https://api.anthropic.com with ambient credentials present, with and without headroom. launcherCredential.test.ts covers an identity's own credential block the same way: its token exported as CLAUDE_CODE_OAUTH_TOKEN and never logged, the guard standing aside for exactly that token already in the environment and still refusing a different one, the block left unresolved when a provider is selected or under the CLAUDE_CONFIG_DIR escape hatch, and exit 64 naming the identity and source. credential.test.ts covers the resolver itself over the fake port: source order, fall-through, the preset argv, interactive detection (including a 1Password service account), timeouts, a secret file refused for loose permissions with a warning, and summaries that never carry a value; realPorts.test.ts runs the real port against a temp file and real child processes for the mode, stderr, timeout and missing-program cases. providers.test.ts covers the manager functions (addProvider/listProviders/removeProvider/loadProvider) over real temp directories per identityManager.test.ts's convention, plus resolveProvider itself as a pure decision over an injected FsPort and CredentialPort, and the conversion of an old-format provider file into its exact replacement.

Headroom routing keeps the same shape: no real process, port, clock, or HTTP call ever happens in a test. headroom/ensure.test.ts drives the launcher-side bring-up against a fake filesystem and scripted supervisor behaviour (first launch spawns the supervisor and waits for its ready state; a healthy daemon is reused without spawning; a dead supervisor pid is replaced, including one that is an unreaped zombie signal 0 still reports alive; a live start lock held by another launcher is waited on while a dead holder's lock is taken over; a fatal lastError refuses immediately; a daemon that never appears times out naming the log path; a provider launch is not registered until the allowlist file, recorded as served, lists the serving door's direct origin; a daemon from an earlier release is joined when its recorded hash is that release's own hash for the providers and door on disk and refused at once otherwise; otherwise the launch waits, whatever sessions are live on the daemon, until the supervisor records it, re-reading the required upstreams on every poll and the daemon's command line once per wait, and timing out naming the allowlist file, the log and any recorded lastError, and timing out as a daemon that is not up, with its supervisor's recorded error, once the daemon it waited on has died, with a launch that routes no provider not held to the hash at all). headroom/supervisor.test.ts runs the whole supervisor loop over injected ports with a clock that only advances when the supervisor sleeps and a process model that keeps signal-0 existence, zombification, and the ChildProcess exit event distinct: install invoked when the binary is missing or the source changed and skipped when the installed version satisfies the source, crash restart driven by the exit event while a session is live, a zombie daemon treated as dead and restarted even though existence alone would still report it, the daemon fields cleared from state the moment a crash is detected, an orphan daemon left by a dead predecessor stopped before the successor starts its own, every restart in a generation served on the same socket inside a socket directory created mode 0700, the sockets of dead supervisor generations pruned while a live one's is kept, a refusal recorded as lastError (with nothing installed or spawned) on a platform without unix sockets, for a symlinked socket directory, one owned by another user or left group accessible, and a state root too deep for a unix socket path, the backoff schedule and retry budget ending in a recorded lastError, settings drift restarts deferred until the session registry empties, idle shutdown timing (and its reset while sessions are live), and session pruning of dead and zombie launcher pids. headroom/supervisorAllowlist.test.ts runs the same loop, over the fake world both files share from headroom/supervisorTestWorld.ts, for the allowlist file: written owner-only with the live doors' direct origins and nothing for any provider before the daemon starts, and the daemon pointed at it; rewritten and its hash recorded with no restart when the door's origin moves under a live session; never rewritten for a provider file added, saved half-written or deleted; a removed or hand-edited file restored on the next tick; a failed write ending the supervisor with a recorded lastError (stopping a running daemon, and never starting one); a group-readable file, a symlink at the file's path, a widened run directory and a group-writable headroom directory repaired with no restart; a group-writable home directory above the root ending the supervisor with a lastError that names it, with nothing written outside the root; every recorded hash already backed by the file's content at the moment it is written; the file left alone by a superseded supervisor; a superseded door's origin kept while that door lives and withdrawn the tick after it exits; a crashed door's record and a reused pid's record pruned; every record kept while the process table cannot be read; and one read of the table per tick. frontdoor/supervisorProcesses.test.ts covers that read: a door, not a door, gone, and unknown with the reason; only lines led by an asked pid, the first for each; and a failed batch falling back to one read per pid. headroom/earlierRelease.test.ts covers recognising a daemon started by an earlier release by its command line and by that release's own allowlist hash. stopSupervisedProcess gets its own table: never escalating when the process exits on SIGTERM, escalating to SIGKILL once the SIGTERM grace expires, reporting still-running when even SIGKILL does not clear it, and sending nothing further when the target is already gone. headroom/headers.test.ts covers the ANTHROPIC_CUSTOM_HEADERS merge, headroom/state.test.ts the state/registry/allowlist primitives (the state file round-tripping the socket path, and a record carrying a TCP port read as malformed), plus the single-name resolution and migration around the previous release's file (the shared record resolving as the serving one, a live legacy supervisor's record resolving from the legacy name with neither file touched, nothing resolved while the shared file is absent and the legacy record's supervisor is not live, a dead generation's legacy record rewritten onto the shared name in place with the legacy file removed, a legacy file deleted once the shared name serves, an unparseable legacy file removed, and the TCP-port era's content claimed over), and headroom/ensure.test.ts gains the launcher joining a live previous-release supervisor through the legacy name without spawning or migrating; the supervisor suite pins the start-time migration of a dead generation's legacy record and the ownership exit when a live legacy supervisor holds one; the read-only consumers are covered where the wiring lives (collectHeadroomStatus resolving the live legacy record, collectDoctorReport over a real root reporting that record and passing the TCP-port era's content as claimable rather than malformed, and the hop in frontdoor/headroomHop.test.ts dialling a daemon recorded only under the legacy name), headroom/socket.test.ts every refusal the door's socket check makes (another owner, a group or world bit, a symlink, a wrong kind or a missing path, for both the directory and the socket, and a platform without unix sockets) and every refusal the allowlist file's path check makes (a group-writable home directory and a sticky /tmp above the root refused, naming the directory, its mode and the remedy; owner-only and root-owned ancestors accepted; the directories a symlinked ancestor resolves to judged; agent-shim's own directories and the file refused as repairable), headroom/commands.test.ts the spawn arguments (--uds and --allowed-base-urls-file, never --host or --port), the spawn environment (an ambient HEADROOM_ALLOWED_BASE_URLS or HEADROOM_ALLOWED_BASE_URLS_FILE removed) and the status report's allowlist drift (a file lagging a moved door, a missing file, a provider edit that is not drift, a door the process table could not answer for), headroom/allowlistDrift.test.ts the drift comparison itself, and doctor.test.ts gains the headroom audit cases (never run, malformed state, healthy pids, dead supervisor, a lastError warning alongside a running replacement). The launcher's own headroom tests inject a fake HeadroomPort to cover the env wiring with and without a provider, the loud refusal when headroom resolved on with no port wired, and that the port is never touched when headroom resolved off.

The credential cache's reported state is tested as a pure function over a fake cache port (credentialCache.test.ts: empty, fresh, expired, no expiry, an entry stamped in the future, a store that cannot be read, and that the token never appears in the result) and through check and doctor (the clause in the text and JSON, a provider's cache alongside an identity's, a block that does not cache and a run with no cache port adding nothing, an unreadable store failing doctor). check.ts's three always-on diagnostics get their own tests too, independent of path/cascade resolution: the ambient-credential check against a fake process.env (same fixture as launcher.ts's guard, since they share the same detection logic); the settings-secrets advisory against a fake settings.json with populated env/hooks fields, confirming it reports counts and key names only, never values; and — since Keychain access is real OS state, not something to fake — a manual/integration-only note that the Keychain-name lookup is exercised against a real security call in CI on macOS runners, not unit-tested with a mock.

doctor.ts deliberately breaks the "throw a validation error and let it propagate" convention every other command file follows, since aggregating every check into one report — rather than aborting on the first broken file — is the whole point of the command. Its own tests cover this directly: every input (identities, configuration profiles, directory-rules.json, config.json, categories.local.json, active-identity) fed simultaneously malformed at once, asserting runDoctor still returns a full report with one fail finding per broken input rather than throwing, plus a genuine extends cycle correctly failing and a genuine diamond correctly not being mistaken for one. The PATH-resolution section gets its own coverage for each of its three verdicts at each of the two names it reports on (a shadowed agent-shim failing and naming both paths, a not-on-PATH executable warning instead, and an enabled-but-shadowed claude shim warning rather than failing), alongside refinePathShadow's own unit tests for the symlink case a directory comparison alone would misreport as a shadow of itself. Its wiring layer sets process.exitCode rather than throwing or calling process.exit() when the report contains any failure — this is new to the codebase and not unit-tested, matching registerCheckCommand's own I/O wiring being untested for the same reason.

claudeShim.test.ts follows identityManager.test.ts's real-temp-directory convention (a fake "own executable" file standing in for the running agent-shim binary), rather than doctor.ts's pure-function style, since enableClaudeShim/disableClaudeShim are themselves real filesystem operations, not something to keep separate from a thin wiring layer. Coverage includes the version-drift case that motivates persisting claude-shim.json at all (the source file overwritten in place between two shim enable runs, proving the marker — not the inode — is what lets the second run refresh cleanly instead of refusing), a foreign file at the target being refused without --force and accepted with it, and the cross-device (EXDEV) copy-fallback path via a small injectable LinkFs seam (mirroring config/store.ts's own StoreFs/nodeStoreFs pattern), since a real cross-filesystem rig isn't practical in CI. One test also reproduces Homebrew's actual layout (a symlink into a separate "Cellar" directory) to confirm the shim lands next to the symlink users invoke, not buried in the directory its realpath resolves to. resolveOwnBinaryCheck, which feeds discoverClaudeBinary's PATH fallback, is covered in the same file over the same temp layout: a different package's claude beside agent-shim (one npm global prefix) reads as foreign, a shim enable hardlink and a symlink to the running binary read as this tool with or without a marker, the recorded target still reads as this tool after version drift, and a --dir marker elsewhere does not tar a foreign claude next to agent-shim. The fallback's own loop is covered purely in versionDiscovery.test.ts, including the co-location case (a claude in agent-shim's own directory must be found) and the self-reference case (a candidate that is this tool must be skipped, and loud failure when it is the only one), and doctor.test.ts runs the real wiring once end to end over a temp prefix to prove collectDoctorReport reports the co-located claude.

The codex translation and the front-door daemon that serves it keep the same discipline: no real network (beyond loopback listeners the test itself starts), file, clock or process in a test. codex/translate.test.ts covers the pure core against the script it replaces (text, images both ways, tool calls and results linked by call id, long tool names shortened and restored, system turns folded into user turns, the tier mapping's order and overrides, effort levels including omitting reasoning for none, the prompt cache key from metadata.user_id). codex/auth.test.ts drives the ~/.codex/auth.json store over an injected filesystem and token endpoint: one refresh for any number of concurrent 401s, a re-read before every refresh that reuses a token the Codex CLI already refreshed, rotated tokens merged into the file as it stands, the rotated refresh token on disk before the new access token is handed out, and a refusal that leaves a valid file behind when the persist is killed before the rename. codex/route.test.ts covers the translation route itself against a scripted upstream (a stream failure answered as an Anthropic-shaped error, a 429 mapped onto the Anthropic rate-limit surface with retry-after, per-provider translation settings), and codex/agent.test.ts pins the keep-alive ceiling at ten seconds against a server whose hint asks for longer. frontdoor/route.test.ts covers the identity step (the session split out of the headers, exactly the named internal headers stripped, case-insensitively) and the provider path space; frontdoor/pipeline.test.ts covers the ordered pipeline over fakes (backpressure waiting for drain and settling when the client goes away, observers run in order at each response head including unrouted errors, an unauthorized request refused as an Anthropic-shaped 401 before any route is asked, a throwing observer dropped without breaking routing, a route failure answered as an Anthropic-shaped 500 before the head and a destroy after it); frontdoor/providerRoute.test.ts covers the per-request provider resolution (a codex provider mounted headroom-eligible with its own address as the hop's upstream, an http provider refused by name until the pass-through route exists, unknown and invalid providers, paths naming no provider), the credential an http provider's route attaches (whatever the child presented replaced by the provider file's own resolved token in the bearer target's header form, an apiKey target answered with x-api-key and the presented bearer dropped, an unresolvable block answered as an Anthropic-shaped 502 naming the provider with nothing forwarded, and a re-resolution after a provider file edit applying to the next request with no restart). frontdoor/server.test.ts runs the real listener end to end against a scripted codex upstream: the translation served through the whole stack, the identity and session headers stripped before any route sees the request, a request with no or a wrong launch capability refused 401 without any route being asked, streaming delivered chunk by chunk rather than buffered, the client's disconnect aborting the route, an unrouted target answered as an Anthropic-shaped error, the health probe, and a closed door rebinding the same sticky port so a frozen base URL works again, while a sticky port something else holds is left for a free one without the bind failure reaching the listener's fatal error handler (which used to exit the door, so a replacement could never come up beside a squatter). Its TLS cases use real certificates issued by x509.ts: a client that trusts only agent-shim's CA completes a handshake with the provider listener serving the loopback leaf (and the CA-verified health probe passes only against that CA), while the same client cannot talk to a complete door whose leaf a different CA signed, which never sees the request or its credential. frontdoor/x509.test.ts checks the certificate encoder against Node's own parser (chain verification, issuer matching, host and IP SAN matching, the validity encoding either side of 2050, positive serials, IPv6 address forms) and mutating the issuer name was confirmed to fail the tests that name it. frontdoor/headroomHop.test.ts builds the door from the production createDoorPipelines, with the provider listener on TLS, and runs the hop against a scripted daemon serving on a real unix socket inside a real mode 0700 directory under a throwaway root, reached through the production path from the state file through the socket check to socketPath, which forwards by x-headroom-base-url the way the real one does (its own x-headroom-* controls stripped, every other header verbatim): a streamed response relayed event by event, a process squatting on the old TCP port (named by an earlier release's state file, or by a current state file rewritten with a port) never offered a connection whether the daemon is down or serving, a socket directory left world accessible, a symlinked socket directory and a symlinked socket each refused with a 502 naming the reason and nothing sent to the daemon, headroom receiving the Anthropic-shaped request and the translator serving what the daemon forwards back through the direct listener (exactly one daemon request and one upstream call, so the loop cannot double-apply), the project identity re-set on the hop with no session header reaching it, a 502 while the daemon is between restarts, a client disconnect unwinding the hop's own request, and a flag-less session served directly. The credential custody cases: for an http provider, headroom sees only Bearer agent-shim-sequestered or agent-shim-sequestered and a distinct hop id per request, never the credential, while the provider's upstream receives the door-attached credential from the provider file and neither the client's own presentations nor any of the door's hop headers; with the daemon holding a hop open, the direct listener refuses an unknown hop id, the wrong generation secret, a live id presented for another provider and a missing id, the upstream seeing none of them, and refuses the same id again once the hop has ended; an OAuth session's bearer reaches the daemon untouched with no hop id. frontdoor/passthrough.test.ts runs the pass-through against a fake upstream (the provider prefix stripped with the query kept, the host replaced, internal headers absent, an unreachable upstream answered as an Anthropic-shaped 502), frontdoor/connect.test.ts keeps the moved TLS round-trip suite (termination, streaming, blind tunnels, port release), every client in it now presenting a live capability the way a real one derives it from HTTPS_PROXY, and adds the surface's authentication and limits over real sockets with the tunnel dialler recording every target: a CONNECT with no credential, a wrong capability, a non-Basic scheme, a repeated header or a credential with no password is answered 407 with the Basic challenge, for the intercept host and a blind-tunnel host alike, and nothing is dialled, intercepted or routed for it; a client that has not finished its head by the deadline gets 408 and is closed while a tunnel established earlier still carries bytes past that deadline; an oversized head gets 431; with the pending cap full of half-sent heads, a newcomer evicts the oldest (408) and a live launch's connection still gets through; an authenticated CONNECT beyond the tunnel cap gets 503 without a dial, and is admitted again once a tunnel closes; and a launch whose registry record is pruned has its open tunnel closed at the next revalidation and its capability refused 407 from then on, using the production check over the real registry functions. Each of those guarantees was checked to discriminate by mutating connect.ts (skipping the capability check, never arming the deadline, dropping the eviction, the tunnel cap, the revalidation or the size check on a head whose terminator has arrived): every mutant fails the case naming it. frontdoor/capability.test.ts covers the credential itself: the proxy URL percent-encodes a token holding every userinfo delimiter and a client's Basic credential carries it back exactly, the password half is read scheme case-insensitively with colons kept, other schemes and empty or missing passwords present nothing, and only an exact live token is accepted, and frontdoor/latency.test.ts bounds the added hop: the median through-door request may cost at most two milliseconds over the direct one, a bound two orders of magnitude above a loopback hop's real cost and still small enough to fail if the hop ever grows a request's worth of work. The ordering test discriminates by construction: mutating the pipeline to serve the route before the hop fails three hop tests at once. The authentication and custody tests were checked the same way: letting the probe skip certificate verification, making ensureFrontDoor skip the probe, sending the credential to headroom unsequestered, admitting any hop id, and serving the provider listener without TLS each fail the tests that name that guarantee. The launcher suites cover both launch shapes ending at the right place: a provider session keeps the OAuth shape (no base URL, HTTPS_PROXY on the door's CONNECT surface carrying the launch's capability as its proxy credential, the provider named in the session headers, and no credential variable at all) with NODE_EXTRA_CA_CERTS on the door's trust bundle, and an OAuth session keeps its base URL untouched with the same proxy, capability and trust bundle. Both shapes gain NO_PROXY and its lowercase spelling exempting every loopback name, appended to a parent's own exclusions without replacing them and with a repeat entry folded away. The parent's own NODE_EXTRA_CA_CERTS reaches the door port, and a bundle warning is logged. frontdoor/supervisor.test.ts runs the listener-host lifecycle over injected ports with a clock advanced only by sleeps: all three sticky ports bound and inherited by a successor generation after a crash, moves off occupied ports logged per listener, failed listener starts recorded as lastError with the start lock cleared and the already-bound listeners closed, dead sessions pruned, the idle shutdown closing all three listeners and keeping the sticky addresses (the Remote Control stream hub closed exactly once after the last listener, which a startup failure path performs as well, and never while the door is still serving), the stream hub's close idempotent (a second close persists nothing, asserted in the stream suite's boundary-save case), and the idle clock reset by a new session, the binary turnover at the first empty registry once the executable the door serves as is replaced on disk (before the idle window elapses, through the same graceful shutdown and with the sticky addresses kept), a replaced binary still served while a session is live, the turnover firing at the first empty registry tick after a session live at the replacement ends rather than after fresh idle minutes, and no turnover while the executable is unstatable at startup, gone mid-run, or returning to the exact captured identity after an absent window (the removal window a remove-then-link install leaves), a door superseded by another live supervisor exiting on the first tick after the last session it served ends while a launch made against the owner is still live, leaving the owner's state record exactly as the owner wrote it, a launch registering in the tick after the takeover counted as the superseded door's own, the sessions keyed by either door's own pid ignored so a superseded door with no launches exits at the grace tick, a state file naming a dead supervisor leaving the door serving as the owner, and the supersession and drained exit published on the backbone, with the launch lifecycle published on the event backbone as the registry changes between ticks (a registration, an end by the launcher's own exit hook, a prune of a dead launch, and nothing for the baseline a generation inherits). frontdoor/ensure.test.ts covers the launcher bring-up (one supervisor under the lock, a dead holder's lock cleared, joining a serving door, a fatal lastError refused immediately, a timeout naming the daemon log) and its listener authentication: the listener is verified before anything is registered, a listener failing verification behind a supervisor this launch spawned is refused with the reason and the log named and no session written, and a recorded live pid whose listener fails is distrusted and replaced by a verified supervisor on another port. usage/identityClaude.inDoor.test.ts drives the helper the door's background work plans its launches with (withIdentityClaude) from inside the front door's role, over the real launch wiring with a stand-in claude on PATH and a throwaway state root, and requires the launch to fail with the named error at its first wait without running anything; with the role guard disabled the same test blocks for the launch's whole wait and fails, which is the stall it exists to catch. frontdoor/watchdog.test.ts runs the real watchdog thread with a short cadence and bound (a loop that never beats reported with the stall recorded in lastError and the rest of the state record kept, a loop that beats within the bound left alone, the stall recorded and reported while the main thread is blocked in a synchronous wait, and nothing after a stop), pins its derived constants against the launcher's probe patience, and covers the stall's replacement (a replacement always started, naming the stalled pid and the next generation however young the stalled door, the generation stepped per replacement, and none started once the chain has run through every generation, the start lock taken with the replacement as holder, no replacement while a live process holds the lock, and a dead holder's lock cleared); the supervisor suite adds that the watchdog starts after the listeners bind, is beaten each tick, is stopped before the first listener closes, and never starts for a door whose bind failed. processRole.test.ts pins the guard that keeps the door's event loop unblocked: a process with no role sleeps and probes as the launcher does, a process holding the front door role has its synchronous sleep and synchronous probe refuse with a named error before any wait or worker starts, and the role is put back when left; the ensure suite adds that a launch which would have to wait fails at its first wait inside the role and that a launch planned inside its own door still takes its shortcut. frontdoor/probe.test.ts runs the real synchronous probe against listeners on worker threads (the probe blocks its own thread, so a listener there could never answer): it accepts the loopback leaf from agent-shim's CA and rejects a leaf from another CA for the same names, a leaf from the right CA that does not name 127.0.0.1, a plain-HTTP listener, a closed port, and a squatter that accepts the connection and never answers (failed by the probe's own deadline, not the launcher's outer wait). frontdoor/trust.test.ts covers the child's CA bundle: the CA alone when the parent set nothing, a combined bundle that keeps the parent's certificates and is written once per combination, an inherited bundle that already holds the CA reused unchanged, and an unreadable inherited file replaced by the CA alone with a warning naming it. frontdoor/detach.test.ts the daemon's independence from the launcher's terminal, and frontdoor/commands.test.ts plus codex/commands.test.ts the two status commands' output over a fake filesystem, and frontdoor/commands.test.ts also runs the real turnover stat against a real temporary directory: the entry's identity reported and followed through a symlink, a staged-then-renamed replacement seen as a different identity (the updater's own install shape), and a missing entry or a directory reported as undefined. watchedInstallEntry's own table lives in the supervisor suite: the resolved entry watched as-is when it is named agent-shim (with or without Windows' .exe), and the agent-shim sibling watched when the door was spawned through the claude hardlink, the legacy claude-use symlink or any other name, and the own entry watched when no sibling exists (the npm bundle's dist/cli.cjs shape). The launcher's own front-door tests inject a fake FrontDoorPort to cover the child's base URL, the bring-up order (front door before headroom, since headroom's allowlist needs the door's address), the loud refusal when no port is wired, and that an http provider's launch goes through the door too. frontdoor/state.test.ts covers the front-door session registry: a launch whose record carries a capability token is listed (the supervisor's idle decision depends on it, and the supervisor tests register sessions through the real writer for the same reason), the token never appears in a listing, malformed and token-less records are skipped, dead launches are pruned along with their capability, and the registry directory and records are written owner-only; realPorts.test.ts proves the real filesystem port produces mode 0700 and 0600 under a permissive umask and narrows entries that already existed wider. frontdoor/eventHub.test.ts covers the door's event backbone: delivery to two subscribers of one source and an every-source subscriber with a detached one receiving nothing further, per-source filtering with each source's sequence stamped independently and monotonically (and one name's re-registration publishing through the same sequence), the registered-source listing, the bounded drop-oldest stream bridge whose first survivor's sequence names the gap the dropped events left, a closed stream resolving done and delivering nothing published after the close, and the wrap that puts the Remote Control fan-out on as the backbone's first publisher beside its own unchanged delivery, session filtering included. frontdoor/quotaExpiringEvents.test.ts covers the expiring-quota publisher against a fake clock: one event when an unspent window enters its final span and silence on the ticks inside it, nothing for a window outside the span, past its reset or fully used, a re-notice for the next window instance's new reset instant, and the backbone-fed freshness (a written usage event alone moves a window into a span the next check publishes, with no file read). src/usage/store.test.ts gains the store's publish dep: every written snapshot is handed to the caller's callback exactly as it stands on disk, a record without an identity writes no snapshot so publishes nothing, and the store runs with no dep wired at all. The supervisor suite gains the door's own sources: the generation and idle-shutdown health events in the order the supervisor lives them, the binary-turnover event before the exit a replaced binary causes, the listener-failure event naming which listener and why, and the expiring-quota check called on every tick. The pool ranking's yielding stickiness is covered in usage/pick.test.ts: a member whose seven-day window would run dry at its own observed pace is demoted below one that would not (and a five-hour pace is never converted into seven-day fractions, so a member with only five-hour readings stays unprojected), and the move a resumed conversation makes is named with its reason for the run-dry tail and the extra-usage billing tail, while a kept member and a fresh launch report no move; launcherPool.test.ts drives the same move through the real launch and asserts the decision line says which member the conversation moved off and why. frontdoor/launchEvents.test.ts covers the launch lifecycle publisher: the silent baseline, the register, end and prune classification carrying the registry's own start times and the observing clock, the departures-before-arrivals ordering with pid order inside each group, and a launch dead on arrival pruned and never registered. frontdoor/eventsApi.test.ts mounts the door's whole typed API on the real listener shape over TLS and drives a registry mutation through the real writer, asserting a typed subscriber receives the source-tagged event over the wire, that a caller without the generation's token and a filter naming an unknown source are each refused having delivered no event, and that a source-filtered subscriber receives only the source it named. frontdoor/listenerReadings.test.ts reads both listeners of a live door through scripted probes and a stepped clock (provider first, each timed alone, a failing listener's reason carried while the other is still read, nothing probed when no supervisor is alive, a port the state does not record skipped) and formats them for frontdoor status; frontdoor/probe.test.ts runs the real accept probe against a listener on a worker thread and a closed port; doctorFrontDoor.test.ts gains the listener findings (a pass stating the probe's time, a failure naming the sessions the listener cuts off and the restart that replaces it).

The self-hosted Remote Control surface's worker web proxies are covered at two layers. frontdoor/rcWebFetch.test.ts drives the fetch's bounds over an injected dial and resolver: the private-address rule itself (every refused block, the v4-mapped form, and the fail-closed non-address), the environment lift's exact-value vocabulary, the redirect walk answering the final hop's facts with the requested url, the scheme gate that refuses without dialling, the private refusal by name, by literal and mid-redirect (and the lift that dials it), the unresolvable and malformed refusals, the redirect bound (a chain exactly at it settling, one past it refused), the byte cap, the deadline against a hanging dial, the non-2xx refusal naming its status, and the content-type gate carrying the readable families as text while refusing binary; its last case runs the production dial itself against a loopback stand-in, fetching through the door's own agents with the lift set and refusing the loopback without it. frontdoor/rcSelfHost.test.ts covers the serving of both endpoints: the worker web-fetch handing the request's one url to the injected fetch and answering the fetched facts, the OAuth bearer refused where the bridge's own JWT is required, the refusal shape answered as a 200 error object (the form the CLI surfaces as the tool's own failure), the framed answer that escapes the reader cap refused rather than sent to be dropped, and the web-search family (the clear refusal naming that no backend ships, the query and domain-filter validation, a wired backend's results, and a wired backend's refusal). The e2e in frontdoor/rcSelfHost.e2e.test.ts adds the real mount: a redirected TLS client speaking the 2.1.289 request shape (worker JWT bearer, anthropic-version, one url) has its fetch served through the transparent surface, the door's own dial following the stand-in's redirect to the final page, and the scheme gate refusing live on the same served path. Breaking the wiring was confirmed to fail the tests that name it: renaming the served branch fails the three serving cases at once, and disabling the private-address check inside the target gate fails the four refusal cases that name it.

The self-hosted surface's conversation layer (the event log keyed above the cse_ sessions, its sessions attachments) is covered in the same two files. frontdoor/rcSelfHost.test.ts covers: every attachment's writes numbering in the one shared sequence space whatever half or family they rode (worker batch, session client write, conversation write), with a payload uuid repeated through a second attachment flagged duplicate and both sessions' reads paging the same log; the delivery rule both directions (one attachment's client write reaching every stream, its worker's own reply reaching the other attachment's worker and client streams and never its own, and the other worker's reply reaching the first's worker stream); the joining handshake (a create naming a conversation attaches and is answered with that conversation's id, a create naming none this door holds is refused, the session rows carry their conversation ids, and a create naming no conversation numbers independently from one, the discrimination the shared space rests on); the conversation family a sessionless client joins through (the list and read, the shared stream receiving the same live events and resuming after the named cursor, a write joining the shared numbering, presence and a receipt fanned to the worker in the session channels' own shape, and the family's collection refusing a create); and the conversation surviving the first attachment's archive with its log, numbering and the second attachment's stream intact. The e2e adds the two-client journey through the door's real transparent surface: a second session created naming the first's conversation (observed by the tracker through the same wrapper as any create), a prompt written through the second session's client half reaching the first's worker stream and its own client stream under one sequence number, the first's worker reply and approval request reaching the second client's stream and never the worker's own, and the approval answered from the second client retiring the pending request on the first, which is only possible because the response crosses attachments through the conversation. Breaking the linkage was confirmed to fail the tests that name it: making the create ignore the named conversation fails the four unit cases that attach and the e2e join case at its first conversation assertion, and renaming the conversation family's path prefix fails the sessionless-client case.

The Remote Control typed API and the control plane mounted beside it are covered at two layers. frontdoor/connect.rc.test.ts mounts the real listener shape (the door's server builder, TLS signed by a freshly generated CA, the oRPC node handler beside the bespoke control routes) and drives it with the pinned client: the observed session listed, the wrong control token refused by the typed surface exactly as the bespoke routes refuse it, the stream subscription delivering the fan-out's events with each sequence number as the SSE id, and the drop-resume pair. frontdoor/controlApi.test.ts mounts the control-plane router on plain loopback HTTP through the same node handler and covers each procedure's shape and refusal: the snapshot list through the store's own schema, the effective-window read at the door's clock (a window past its reset reading as reset and empty, a named provider with no observation answering nothing observed, an unknown identity refused as not found rather than empty), the live quota read (an observation round-tripping through the output schema with the payload's own fields and extras verbatim, the door-wide latest beside the filtered per-session list, an empty answer while no rate_limit_event has been filed, a named session refused rather than answered empty with the two causes told apart through the tracker's list, and the wrong token refused), the front door status and the session registry alone, the check report equal to check --json's own conversion of a real runCheck product (so the procedure's output validation proves the schema matches the collector), the named identity handed through, a relative path refused, the doctor report as data, and the wrong token refused by every router; the pool read returns a real collectPoolPick product through the report's own schema (so the procedure's output validation proves the schema matches the collector, the check case's own proof), refuses an unknown pool naming the live ones rather than an empty ranking, and refuses a relative path for the same reason the check query refuses one. frontdoor/controlApi.e2e.test.ts mounts the merged router (Remote Control and control plane together) on the door's own TLS listener and drives it with the whole-door client: rc.list still answers beside the new procedures, every control-plane read returns across real transport, and the wrong token is refused on both surfaces; its live quota case publishes a rate_limit envelope through the wrapped fan-out exactly as the held client stream publishes and reads it back through usage.live, after first publishing an assistant envelope and a status-less rate_limit one that must both leave the state empty, which is the discrimination the filing itself has to carry. Breaking usage.effectiveWindow's wiring (answering the seven-day window with the five-hour one) was confirmed to fail exactly the test that names it. frontdoor/rcLiveUsage.test.ts covers the state itself against the real backbone: nothing held until the first rate_limit_event (a busy backbone of other envelopes and other sources files nothing), a published envelope filed as the session's latest observation stamped with the door's clock and carrying the payload's fields verbatim, a newer envelope replacing its session's while every session keeps its own and latestOf naming the freshest across them, and the narrowing refusing another payload type, a missing rate_limit_info, one without the family's own required status, and a backbone payload that is not a stream event at all. Breaking the filing itself (the subscriber returning before it stores the observation) was confirmed to fail exactly the four cases that name a filed observation, the three unit filings and the e2e read. frontdoor/rcApiOpenapi.test.ts mounts the merged router through the same node handler on plain loopback HTTP and drives the REST surface exactly as a consumer with no TypeScript client would, one plain fetch per call: the annotated reads answering JSON, a missing or wrong control token refused with the same oRPC error shape the RPC protocol answers with, a body failing the shared schema refused naming the field, a write delivered over its flat verb path, the query-parameter decode with the named-session refusal rule kept, the OpenAPI document refused without the token and served behind it with its paths asserted equal to exactly the annotated surface (so a procedure losing its annotation and an unannotated one leaking its router-segment path both fail it), the RPC protocol still answering beside the REST routes on the procedure paths the typed clients use, a method with no annotated route falling through to the listener's own 404, and the SSE route streaming one published event as one data: frame.

The Sign in with ChatGPT flow follows the same discipline. codex/siwc.test.ts covers the protocol steps against fakes (the S256 challenge, the first-sign-in and returning authorise URLs, callback parsing that never echoes a code, the token calls with their resource parameter and error bodies, and ID-token verification with a real RSA key: a wrong key, alg: none, a wrong issuer, audience, expiry or nonce each fail). codex/siwcStore.test.ts covers the grant store (refresh ahead of expiry, the rotated token written before the new one is handed out, one refresh for concurrent callers, a token another process already replaced, and the refusals that name the login command), and codex/siwcLogin.test.ts runs the whole login and logout over a fake browser and listener, with the real loopback listener tested on a free port. codex/route.test.ts checks that a provider's login chooses its upstream, and doctor.test.ts and codex/commands.test.ts cover the sign-in findings and status.

The headroom measurement harness keeps its logic in scripts/headroom-measure-core.ts, tested by scripts/headroom-measure-core.test.ts without a daemon: transcript parsing that tolerates a partial last line, the main-chain walk that drops abandoned branches and sidechains, the merge of Claude Code's per-block lines into Messages-API messages (including dropping orphaned tool results and stripping tool references and images from results), the request windows that each extend the one before, the prefix-preservation score (identical segments from the front, ignoring cache_control placement and key order, with changed tools losing everything), the cache-weighted cost and the baseline it is compared with (a variant that changes nothing must cost exactly what the unmodified conversation does, even though a request's newest messages are never cached yet), the aggregation, and the table rendering. See headroom-measurement.md.

The command surface itself is tested through buildProgram (src/program.test.ts) against a throwaway AGENT_SHIM_HOME layout, scripted prompts and a fake launcher: the verb set each noun exposes, every removed spelling (rules, profile create, identity set-default-profile, rules add --profile, profile set --headroom and the rest) rejected as a usage error, a runnable example in every command's --help, each noun's add/set/list/show/remove/use verbs including --json output and remove's --yes requirement without a terminal, the terminal-versus-no-terminal split for every prompt, and completion scripts for each shell (the bash one parsed by bash -n). cliError.test.ts covers reportFatalError's exit statuses and AGENT_SHIM_DEBUG; argv.test.ts covers --identity, --no-provider, --native (consumed before a terminator, Claude Code's own --bare left alone), the boolean launch flags and the -- terminator; launcher/claudeVersion.test.ts covers the version pin's resolution (flag, then environment, then cascade; an empty variable counts as unset; a malformed flag or variable refused naming its origin), versionDiscovery.test.ts runs exactly the pinned version and fails with the installed versions listed, never falling back, for a missing, non-executable, empty or non-file entry, and check and doctor report a pin and warn about one that is not installed; launcher/native.test.ts covers the native launch (the discovered binary run with every argument verbatim and the caller's environment untouched, and each conflicting launch flag refused by name with nothing spawned); flags.test.ts covers the flag, then environment variable, then cascade precedence and the shared boolean vocabulary; and launcher.test.ts/launcherProvider.test.ts cover the refusal of a missing identity or configuration profile and --identity combined with --provider.

The usage tracking under src/usage/ is tested over injected filesystems and a throwaway layout, never the real home. The parsers are covered against real captured header shapes (the unified five-hour and seven-day windows, epoch-second resets, a missing or unparseable field) and the SSE and JSON body scanners against chunk boundaries at every offset, including a split multi-byte character. The store tests assert the new on-disk state: a record appended to its writer's day segment, the snapshot updated with the account's metadata, the newest observation winning whichever order records arrive in, whole-day pruning at the retention boundary, and owner-only modes. The middleware tests assert that a store failure never reaches a request, that door-answered routes are not recorded, that gzip, deflate and brotli bodies are scanned, and that a serialised record holds no prompt, reply or credential content. The command tests drive usage and account show through the real program, text and --json, and an unknown --identity fails rather than reading as no usage.

Pool selection is tested at three layers. rankPool is a pure function over snapshots, account metadata, log records and a clock, so its tests build UsageSnapshot values directly and cover each rule on its own: a window refused until a future reset excludes a member and one past its reset does not, a refusal lapses once a later request went through, a sooner reset outranks more raw headroom, plan size weights the score, an unreadable or missing snapshot ranks as unknown with a reason, pay-per-use ranks after both, the five-hour projection demotes a member at its own pace and at another member's rescaled pace, the last pick holds while its prompt cache is warm and for a resumed conversation, and ties order by name. poolPick.test.ts covers loading over a fake filesystem and the last-pick file (round trip, pruning, an unreadable file reported instead of blocking). launcherPool.test.ts drives runLauncher with @pool:, --identity, the environment variable and the active-identity file and asserts the spawned CLAUDE_CONFIG_DIR, that the front door is engaged by default and by --no-track-usage is not, the refusal text and --wait against an injected clock and sleep, and the sticky behaviour across two launches over one filesystem. The pool command tests run the real program against a throwaway layout, including that pool pick records nothing, and doctor and check have cases for pool members and selectors.