agent-shim 7.8.0 → 7.10.0

package/dist/types/frontdoor/custody.d.ts

@@ -0,0 +1,32 @@
+import type { IncomingHttpHeaders } from "node:http";
+/** What stands in for a credential while its request crosses headroom: an opaque word that authenticates nothing anywhere. */
+export declare const SEQUESTERED_CREDENTIAL = "agent-shim-sequestered";
+/** The credential headers one custody record holds, exactly as the client sent them. */
+type HeldCredentials = Readonly<Record<string, string | readonly string[]>>;
+/** One request's headers with its credentials swapped out, and the id that redeems them. */
+interface Sequestered {
+    readonly hopId: string;
+    readonly headers: Record<string, string | string[] | undefined>;
+}
+/**
+ * Holds a provider session's real credentials in this process's memory while its request takes the headroom hop, so the credential never crosses headroom or the plain-HTTP leg back to the door.
+ *
+ * The hop calls `sequester`, sends headroom the placeholder headers plus the hop id, and calls `release` once its response to the client has finished or the client has gone. The direct listener calls `redeem` with the hop id and the provider its request path names: a live id recorded for that same provider yields the real headers, anything else yields nothing and the request is refused. A process that binds the direct port therefore receives only placeholders and an id that is worthless once the hop ends, and nothing outside this process can mint an id.
+ *
+ * An id stays redeemable for the whole hop rather than exactly once, because headroom legitimately sends one client request upstream more than once: it retries 429, 529 and 5xx answers, and its memory-tool and CCR continuations call the upstream again inside the same client turn, all with the headers it was handed.
+ */
+export interface CredentialCustody {
+    /** Takes custody of `headers`' credential headers for one hop to `provider`, returning the headers to send headroom (placeholders where the credentials were) and the hop id that redeems them. */
+    readonly sequester: (headers: Readonly<IncomingHttpHeaders>, provider: string) => Sequestered;
+    /** Ends a hop: its id stops redeeming. Idempotent. */
+    readonly release: (hopId: string) => void;
+    /** The real credential headers for a live hop to `provider`, or undefined for an unknown, released or mismatched id. */
+    readonly redeem: (hopId: string, provider: string) => HeldCredentials | undefined;
+}
+/** Creates an empty custody store. `randomId` must be unguessable (a v4 UUID or better): the id is the only thing that redeems a credential. */
+export declare function createCredentialCustody(randomId: () => string): CredentialCustody;
+/**
+ * The headers a redeemed request is routed with: every credential header headroom forwarded (placeholders, or anything else headroom chose to send) is dropped, and the held originals take their place. Whatever the hop's request carried in those headers is never trusted; only what the client sent is.
+ */
+export declare function restoreCredentials(headers: Readonly<IncomingHttpHeaders>, credentials: HeldCredentials): IncomingHttpHeaders;
+export {};

package/dist/types/frontdoor/headroomHop.d.ts

@@ -0,0 +1,22 @@
+import type { CredentialCustody } from "./custody";
+import { type RoutedRequest, type RoutedResponse } from "./route";
+/** Everything the headroom hop depends on, injected so the pipeline's ordering tests can point it at a scripted daemon. */
+export interface HeadroomHopDeps {
+    /**
+     * The headroom daemon's loopback port, read per request rather than captured at start-up: the daemon can crash and restart on a different port while this door keeps listening, and the hop must follow it. Undefined while the daemon is down (the restart window).
+     */
+    readonly headroomPort: () => number | undefined;
+    /**
+     * The per-generation secret the direct listener requires on what the hop forwards back. Headroom passes non-x-headroom headers through untouched, so the secret survives the round trip and arrives where this process can check it, while no loopback process outside this door ever holds it.
+     */
+    readonly hopSecret: string;
+    /** Holds a provider session's real credentials while its request crosses headroom; the direct listener redeems them by the hop id. */
+    readonly custody: CredentialCustody;
+    readonly log: (line: string) => void;
+}
+/**
+ * Applies the headroom hop: forwards the request, still Anthropic-shaped, to the headroom daemon as a backend hop and streams its response back to the client. The hop ALWAYS sits before the route's own serving (a translator needs the request headroom has compressed, never the reverse), which is why this runs in the pipeline and not inside any route.
+ *
+ * `upstream` is what headroom is told to forward to once it has done its work (its per-request base URL header). When it is set it is always this door's direct listener (every provider route declares exactly that), and the provider credential is then taken into custody for the hop: headroom receives placeholders and a hop id, and the direct listener restores the real headers when headroom forwards the request back. Neither headroom nor anything that binds a port on that plain-HTTP round trip ever holds the credential. Undefined leaves headroom's default upstream (Claude Code's API) in charge, which is exactly what an OAuth session wants, and the OAuth bearer then passes through untouched: headroom forwards it straight to that API, never back here, and uses it for its subscription tracking. The session's project identity is re-set here, and only here: the identity step stripped it from everything that leaves the machine, and headroom is the one consumer that needs it.
+ */
+export declare function applyHeadroomHop(request: RoutedRequest, response: RoutedResponse, upstream: string | undefined, deps: HeadroomHopDeps): Promise<void>;

package/dist/types/frontdoor/pipeline.d.ts

@@ -0,0 +1,109 @@
+import type { IncomingHttpHeaders, IncomingMessage, ServerResponse } from "node:http";
+import { type HeadroomHopDeps } from "./headroomHop";
+import { type FrontDoorRoute, type RoutedRequest, type RoutedResponse, type SessionIdentity } from "./route";
+/** What one routed response looked like as it started back to the client: the typed event response middleware observes. */
+export interface RoutedResponseEvent {
+    readonly session: SessionIdentity;
+    /** The route that served the response. */
+    readonly route: string;
+    /** The request's method. */
+    readonly method: string;
+    /** The request target's path, without its query string. */
+    readonly path: string;
+    /** When the pipeline received the request, in epoch milliseconds from the injected clock. */
+    readonly receivedAt: number;
+    readonly status: number;
+    readonly headers: Readonly<Record<string, string>>;
+}
+/** How a routed response's body finished: written to the end, or cut short (the client went away, or the route destroyed the response after an upstream failure). */
+export type ResponseOutcome = "completed" | "aborted";
+/**
+ * Follows one response's body as the client receives it. `chunk` sees each chunk after it has been handed to the client's socket, so observing never holds a byte back; `end` is called exactly once, when the body has finished either way. Like the observer that returned it, a body observer that throws is logged and dropped for the rest of that response, never allowed to break it.
+ */
+export interface ResponseBodyObserver {
+    readonly chunk: (chunk: Uint8Array) => void;
+    readonly end: (outcome: ResponseOutcome) => void;
+}
+/**
+ * Response middleware: called once per routed response, in registration order, once the route's response head is known and before any of it is written to the client. It returns a body observer when it wants to follow the body, or undefined when the head was all it needed. Observing must be side-effect-only: an observer that throws is logged and skipped, never allowed to break routing, and an observer must not block the response.
+ *
+ * Usage tracking registers here (see `src/usage/middleware.ts`): the head carries the rate-limit headers, and the body carries the token usage.
+ */
+export type ResponseObserver = (event: RoutedResponseEvent) => ResponseBodyObserver | undefined;
+/** The outcome of resolving a request's target to a route. */
+export type RouteResolution = {
+    readonly ok: true;
+    readonly route: FrontDoorRoute;
+} | {
+    readonly ok: false;
+    readonly status: number;
+    readonly message: string;
+};
+/** Everything the ordered pipeline depends on, injected so it runs against fakes in tests. */
+export interface PipelineDeps {
+    /** Resolves the route a request's target names, reading whatever configuration the route needs. */
+    readonly resolveRoute: (request: RoutedRequest) => Promise<RouteResolution>;
+    /** The response middleware chain, run in order at each response head. This is where usage capture registers. */
+    readonly responseObservers: readonly ResponseObserver[];
+    /**
+     * The headroom hop, applied BEFORE a route whose declaration admits it whenever the session's launch resolved headroom on: headroom needs the Anthropic-shaped request, so it always sits in front of a translator, never behind one. Omitted by a listener that serves routes directly (the direct listener headroom forwards an in-process route back to), or when no headroom is wired.
+     */
+    readonly headroom?: HeadroomHopDeps;
+    /** The clock response middleware times requests by, in epoch milliseconds. */
+    readonly now: () => number;
+    readonly log: (line: string) => void;
+    /**
+     * The listener's admission step, run after identification and before anything is routed: it decides whether the request may be routed at all and with which headers. A client-facing listener admits a request carrying the per-launch capability of a live registered session, unchanged; the direct listener admits only what this process's own headroom hop sent back (the generation's hop secret plus a live custody id for the provider the path names) and swaps the hop's placeholder credentials for the real ones. A refused request is answered 401 without ever reaching a route, so a loopback process that never launched through agent-shim cannot spend a session's credentials or quota.
+     */
+    readonly admit: (request: AdmissionRequest) => Admission;
+}
+/** What the admission step sees of one request. */
+interface AdmissionRequest {
+    /** The request target exactly as received. */
+    readonly url: string;
+    /** Every header as received, internal ones included: the capability and hop headers live here. */
+    readonly headers: Readonly<IncomingHttpHeaders>;
+    /** The headers the identity step judged forwardable, internal ones stripped. */
+    readonly forwardable: Readonly<IncomingHttpHeaders>;
+}
+/** The admission step's verdict: route with these headers, or refuse with this message. */
+type Admission = {
+    readonly ok: true;
+    readonly headers: IncomingHttpHeaders;
+} | {
+    readonly ok: false;
+    readonly message: string;
+};
+/** One request as a transport hands it to the pipeline, before anything has been identified or routed. */
+export interface PipelineRequest {
+    readonly method: string;
+    /** The request target exactly as received, path and query together. */
+    readonly url: string;
+    readonly headers: IncomingHttpHeaders;
+    /** The request's body stream. */
+    readonly body: IncomingMessage;
+    /** Aborted the moment the client goes away. */
+    readonly signal: AbortSignal;
+    readonly response: ServerResponse;
+}
+/** What the response middleware learns about the request a routed response answers. */
+interface ObservedRequest {
+    readonly method: string;
+    /** The request target's path, without its query string. */
+    readonly path: string;
+    readonly receivedAt: number;
+}
+/**
+ * Builds the response half a route writes through. The head is what runs the response middleware: `start` invokes every observer, in order, with the session, the request and the route's name before a byte reaches the client, and keeps the body observers they return. Each body chunk reaches those observers only after it has been handed to the client's socket, and their `end` runs once when the response ends, is destroyed, or the client goes away first, so following the body never holds a byte back and never misses how it finished. Body writes apply backpressure by waiting for the socket to drain, and resolve without writing once the client is gone, so a route streaming to a dead client finishes promptly rather than filling a buffer.
+ */
+export declare function createRoutedResponse(response: ServerResponse, context: {
+    readonly deps: PipelineDeps;
+    readonly session: SessionIdentity;
+    readonly route: string;
+    readonly request: ObservedRequest;
+}): RoutedResponse;
+/**
+ * The ordered pipeline every routed session's request runs through: identify the session (splitting the launcher-injected headers out of what may leave the machine), then route, with the response middleware running at each response head. A route that cannot be resolved is answered as an Anthropic-shaped error, and the observers see that error like any other response, since quota and rate-limit state lives in exactly those.
+ */
+export declare function serveRouted(request: PipelineRequest, deps: PipelineDeps): Promise<void>;
+export {};

package/dist/types/frontdoor/server.d.ts

@@ -0,0 +1,44 @@
+import http from "node:http";
+import type { IncomingMessage } from "node:http";
+import https from "node:https";
+import type { LeafCert } from "./connect";
+import type { PipelineRequest } from "./pipeline";
+/** A front-door listener: plain HTTP for the direct listener only headroom reaches, HTTPS for the provider listener every provider session's child connects to. */
+export type FrontDoorServer = http.Server | https.Server;
+/**
+ * A front-door listener: the transport a routed session's requests arrive on. It turns each Node request into a `PipelineRequest` (the raw request plus an abort signal that fires the moment the client goes away before the response finished) and hands it to the pipeline; the pipeline owns identification, admission, middleware and routing.
+ *
+ * With `tls`, the listener serves HTTPS with that leaf, which is how the provider listener authenticates itself to the child: the leaf is signed by agent-shim's CA, whose key only the owning user can read, and the only CA the child trusts for a 127.0.0.1 certificate is that one (no public CA issues certificates for a loopback address), so a process that merely binds the port cannot complete a handshake the child accepts and never receives the request (credentials and capability included). Without `tls` it serves plain HTTP, which only the direct listener does: nothing that reaches it carries a real credential (see the credential custody).
+ *
+ * The disconnect is read from the response's `close` event, not the request's: the request emits `close` as soon as its body has been read, long before the response ends. `GET /healthz` is answered here, before the pipeline, because a readiness probe is not a routed session and carries no session headers or capability.
+ */
+export declare function createFrontDoorServer(pipeline: (request: PipelineRequest) => Promise<void>, log: (line: string) => void, tls?: LeafCert): FrontDoorServer;
+/**
+ * Probes a listener's health endpoint once: the check the supervisor's start and the tests use to know the door is actually serving, not merely bound. With `ca`, the probe speaks HTTPS and accepts only a certificate chaining to that CA for 127.0.0.1, so a healthy answer also proves who is answering; without it, plain HTTP. No capability is ever sent: the health endpoint needs none.
+ */
+export declare function frontDoorHealthy(port: number, ca?: string): Promise<boolean>;
+/** How a listener is bound. */
+interface ListenOptions {
+    /** The sticky port to try first; any free port is used when it is taken or absent. */
+    readonly preferredPort?: number;
+    /** Receives the actual port the moment the bind succeeds, before the health probe. */
+    readonly onBound?: (port: number) => void;
+    /** The CA a TLS listener's leaf chains to, so its own start-up probe verifies the handshake a child will make; omitted for a plain-HTTP listener. */
+    readonly ca?: string;
+    /**
+     * Called for any error the listener emits once it is bound and serving. Attached only after the bind has settled: a server emits the sticky port's EADDRINUSE as an ordinary `error` event, and a handler attached before the bind would treat the fallback the bind is about to make as fatal.
+     */
+    readonly onError?: (error: Error) => void;
+}
+/**
+ * Binds the listener on `preferredPort` when it is free and any free port otherwise (bind, do not probe: check-then-bind races), probing its own health endpoint before resolving.
+ */
+export declare function listenFrontDoor(server: FrontDoorServer, options?: Readonly<ListenOptions>): Promise<{
+    readonly port: number;
+    readonly close: () => Promise<void>;
+}>;
+/**
+ * Iterates a forwarded response's body as typed chunks. Node types the async iteration of an `IncomingMessage` as `any`, so every consumer narrows here once rather than each carrying its own assertion.
+ */
+export declare function upstreamChunks(stream: IncomingMessage): AsyncGenerator<Uint8Array>;
+export {};

package/dist/types/index.d.ts

@@ -9,7 +9,9 @@
  *
  * Creating and changing identities, configuration profiles, providers, pools and directory rules: the `*Store` modules, which take the state root's `LayoutPaths`, return typed values and throw `CliError` subclasses.
  *
- * Everything the CLI alone needs (commander wiring, prompts, `doctor`, `check`) is deliberately not exported here.
+ * - `check` and `doctor` as data: `collectCheckReport` and `collectDoctorReport` read this machine and return the report, and the pure `runCheck` and `runDoctor` take the facts as parameters.
+ *
+ * Everything the CLI alone needs (commander wiring and prompts) is deliberately not exported here.
  */
 export { resolveDecisions, topLevelNames, type ResolveDecisionsInput, type ResolvedState } from "./resolve/pipeline";
 export type { CompiledRule, Decision, Diagnostic, EliminatedRule, EntryFact, EntryFacts, FlattenedCascade, Layer, LayerId } from "./resolve/types";
@@ -31,3 +33,5 @@ export { createProfile, InvalidCategoryNameError, listProfiles, ProfileAlreadyEx
 export { addProvider, describeProviderEndpoint, InvalidProviderNameError, LegacyProviderFileError, listProviders, ProviderAlreadyExistsError, ProviderKindMismatchError, ProviderNotFoundError, providerExists, readProvider, removeProvider, updateProvider, type AddProviderInput, type ProviderListEntry, type UpdateProviderInput, } from "./providersStore";
 export { addPool, PoolNotFoundError, readPools, removePool, requirePool, setPool } from "./poolStore";
 export { addDirectoryRule, DirectoryRuleAlreadyExistsError, DirectoryRuleMissingTargetError, DirectoryRuleNotFoundError, listDirectoryRules, readDirectoryRules, removeDirectoryRule, updateDirectoryRule, writeDirectoryRules, type AddDirectoryRuleOptions, type UpdateDirectoryRuleOptions, } from "./directoryRulesStore";
+export { checkReportHasWarnings, checkReportToJson, collectCheckReport, formatCheckReport, runCheck, type CheckReport, type CollectCheckReportParams, type RunCheckParams, } from "./checkReport";
+export { collectDoctorReport, formatDoctorReport, runDoctor, type CollectDoctorReportParams, type DoctorReport, type RunDoctorParams, } from "./doctorReport";

package/dist/types/launcher/cascade.d.ts

@@ -0,0 +1,42 @@
+import { type ConfigFileReader } from "../config/load";
+import { type GlobalConfig } from "../config/schema";
+import { type CascadeInput, type ReadablePredicate } from "../resolve/walk";
+import type { LayoutPaths } from "../paths";
+/** The committed, team-shared portable config file name. A level with none falls back to the former `.claude-use.json`, and likewise for the local file, see `src/legacy.ts`. */
+export declare const PORTABLE_CONFIG_FILENAME = ".agent-shim.json";
+/** Its gitignored, per-clone personal sibling. */
+export declare const PORTABLE_LOCAL_CONFIG_FILENAME = ".agent-shim.local.json";
+/** Inputs to `loadCascadeInput`. */
+export interface LoadCascadeInputParams {
+    readonly paths: LayoutPaths;
+    readonly home: string;
+    /** The directory the cascade is being resolved for — already a real path, since resolving symlinks is the caller's job. */
+    readonly cwd: string;
+    readonly read: ConfigFileReader;
+    readonly isReadable?: ReadablePredicate;
+    /** The configuration profile the launcher's own precedence rules chose. */
+    readonly baseConfigProfile?: string;
+    readonly cliOverride?: CascadeInput["cliOverride"];
+}
+/** An assembled cascade input plus the global config it was built from, which the caller also needs for its own defaults. */
+export interface LoadedCascade {
+    readonly input: CascadeInput;
+    readonly globalConfig?: GlobalConfig;
+}
+/**
+ * Loads every configuration file one launch's cascade is built from, and assembles them into the `CascadeInput` the pure resolver consumes.
+ *
+ * This is the only place file reading and cascade composition meet. Everything it produces is already-loaded data: `src/resolve/` never opens a file, and this module never decides what any of it means.
+ *
+ * Files are read with `loadConfigFile`, which wraps cosmiconfig's `load(filepath)` — never its `search()`, which stops at the first config found while walking upward. This design needs the exact opposite: every ancestor collected, shallowest-first, each one composing on top of the last.
+ */
+export declare function loadCascadeInput(params: LoadCascadeInputParams): LoadedCascade;
+/**
+ * Reads the deepest directory-level `identity` pin and `configProfile` selection that apply to a directory, without resolving the cascade.
+ *
+ * The launcher needs both *before* it can resync a farm — which identity a directory pins decides which farm there is to resync, and which profile it selects is an input to resolving that farm's contents — so they cannot come out of the resolved cascade itself.
+ */
+export declare function readDirectorySelections(loaded: LoadedCascade): {
+    identity?: string;
+    configProfile?: string;
+};

package/dist/types/launcher/pool.d.ts

@@ -0,0 +1,44 @@
+import type { Pool } from "../config/schema";
+import type { LayoutPaths } from "../paths";
+import { type PoolPickFs } from "../usage/poolPick";
+import type { FarmFs, FsPort, LogPort } from "./ports";
+/** Everything one pool pick needs, injected so it runs against the same fakes as the rest of the launcher. */
+export interface ResolvePoolParams {
+    readonly poolName: string;
+    /** Which precedence rule selected the pool, for the refusal messages. */
+    readonly selectedVia: string;
+    readonly pools: Readonly<Record<string, Pool>> | undefined;
+    readonly paths: LayoutPaths;
+    readonly fs: FsPort;
+    readonly usageFs: PoolPickFs & Pick<FarmFs, "writeFilePrivate" | "mkdirPrivate">;
+    /** The launch directory: the key of the last-pick record. */
+    readonly cwd: string;
+    readonly now: () => number;
+    readonly sleep: (ms: number) => void;
+    /** The arguments claude itself will receive. */
+    readonly passthrough: readonly string[];
+    /** Sleep until the earliest member returns, instead of refusing, when every member is refused. */
+    readonly wait: boolean;
+    readonly log: LogPort;
+}
+/** The pick, or why none could be made. */
+export type PoolResolution = {
+    readonly ok: true;
+    readonly identity: string;
+    /** The pool and the chosen member's leading reasons, for the launch's decision line. */
+    readonly explanation: string;
+} | {
+    readonly ok: false;
+    readonly message: string;
+};
+/** A pool's members split by whether each is an identity that exists: a pool may outlive an identity it names, since removing an identity does not rewrite the pools that list it. */
+export declare function splitMembers(pool: Pool, paths: Pick<LayoutPaths, "identitiesDir">, fs: FsPort): {
+    readonly present: readonly string[];
+    readonly missing: readonly string[];
+};
+/**
+ * Picks the identity a launch of pool `poolName` runs as.
+ *
+ * Members without an `identity.json` are skipped with a warning, since a pool may outlive an identity it names. When every remaining member is refused right now the launch is refused, naming the earliest return, unless `wait` is set, which sleeps until then and ranks again. The chosen member is recorded as this directory's last pick so the next launch here keeps its warm prompt cache.
+ */
+export declare function resolvePoolLaunch(params: ResolvePoolParams): PoolResolution;

package/dist/types/pathNorm.d.ts

@@ -0,0 +1,14 @@
+/**
+ * Expands a leading `~` against `home`.
+ *
+ * Only a leading `~` alone or followed by a separator is expanded — `~other` is a literal name (a directory really called that), not another user's home directory, which this tool has no business resolving.
+ */
+export declare function expandTilde(value: string, home: string): string;
+/**
+ * Normalises a directory rule's `path` into an absolute filesystem path for comparison against a real directory.
+ *
+ * Rules are written with `~`-rooted paths far more often than absolute ones, and a rule that fails to match because of a trailing slash or a `..` segment fails silently — the launch just quietly ignores the rule. Normalising both sides identically is what stops that.
+ */
+export declare function normaliseRulePath(rulePath: string, home: string): string;
+/** True when `ancestor` is `descendant` itself or one of its parent directories. Both are expected to be already normalised. */
+export declare function isAncestorOrSelf(ancestor: string, descendant: string): boolean;

package/dist/types/poolPickReport.d.ts

@@ -0,0 +1,44 @@
+import type { Pool } from "./config/schema";
+import type { FarmFs, FsPort } from "./launcher/ports";
+import type { LayoutPaths } from "./paths";
+import type { Candidate } from "./usage/pick";
+/** What `pool pick` reports: the ranking a launch from `directory` would act on right now. */
+export interface PoolPickReport {
+    readonly pool: string;
+    readonly directory: string;
+    /** The member a launch would run as, absent when every member is refused. */
+    readonly pick?: string;
+    readonly candidates: readonly PoolPickCandidateView[];
+    /** Members that name an identity that does not exist; a launch skips them. */
+    readonly missing: readonly string[];
+    /** When nothing can be picked, the soonest any member returns. */
+    readonly earliestReturn?: {
+        readonly identity: string;
+        readonly at: string;
+    };
+    /** Why the last-pick record could not be read, when that is the case. */
+    readonly stickyProblem?: string;
+}
+/** One ranked member as `pool pick --json` prints it. */
+interface PoolPickCandidateView {
+    readonly identity: string;
+    readonly class: Candidate["class"];
+    readonly score?: number;
+    readonly feasible: boolean;
+    readonly blockedUntil?: string;
+    readonly plan: Candidate["plan"];
+    readonly reasons: readonly string[];
+}
+/**
+ * Ranks a pool exactly as a launch from `directory` would right now, without recording a pick. Shares `rankPoolFromStore` with the launcher, so what this prints is what a launch does.
+ */
+export declare function collectPoolPick(params: Readonly<{
+    paths: LayoutPaths;
+    fs: FsPort;
+    usageFs: FarmFs;
+    poolName: string;
+    pool: Pool;
+    directory: string;
+    nowMs: number;
+}>): PoolPickReport;
+export {};

package/dist/types/realPorts.d.ts

@@ -0,0 +1,102 @@
+import type { CredentialPort } from "./credential";
+import { type DiscoveredClaudeBinary } from "./versionDiscovery";
+import type { LayoutPaths } from "./paths";
+import type { FarmFs, FsPort, HeadroomPort, LogPort, ProcPort, RunPort, SpawnPort } from "./launcher/ports";
+/** The real, `node:fs`-backed `FsPort` used by the actual `claude` launcher — never used in tests. */
+export declare const realFsPort: FsPort;
+export declare const realFarmFs: FarmFs;
+/**
+ * Blocks the current thread for `ms` milliseconds.
+ *
+ * The launcher is synchronous end to end, right through to `spawnSync`, so waiting on another process's identity lock cannot be done with a promise. `Atomics.wait` on a private buffer is the one way to sleep synchronously without burning the CPU in a spin loop.
+ */
+export declare function realSleepSync(ms: number): void;
+/**
+ * Whether `pid` is a live, schedulable process: signal-0 alive AND not a zombie. This is the liveness notion every headroom coordination decision must use, because a defunct daemon holds no port and a defunct supervisor will never write state, yet both still "exist" as far as signal 0 is concerned.
+ */
+export declare function realIsProcessRunning(pid: number): boolean;
+/** The real `RunPort`, used for auxiliary commands whose output this process needs to read — git branch detection for `when: { branch }` conditions, and `check.ts`'s macOS Keychain lookup. */
+export declare const realRunPort: RunPort;
+/**
+ * The real `CredentialPort`. A secret file's mode is reported only where POSIX permission bits exist (not on Windows, whose ACLs Node's `stat` does not expose). A command runs with no shell under its timeout; a non-interactive one gets no stdin and has its stderr captured for the error message, while an interactive one inherits the terminal's stdin and stderr so its prompt reaches a person. stdout is always captured, since it is the token.
+ */
+export declare const realCredentialPort: CredentialPort;
+/** Reads the git branch checked out at `cwd`, and whether the repository is in detached-HEAD state. Both undefined when `cwd` is not in a repository at all. */
+export declare function resolveGitBranch(run: RunPort, cwd: string): {
+    branch?: string;
+    branchDetached?: boolean;
+};
+/**
+ * The spawn options every background daemon agent-shim starts shares. `detached: true` puts the child in a new session with no controlling terminal, so closing the terminal a launch started from (SIGHUP to that terminal's session) never reaches it: a second session still using the daemon keeps working after the first one's terminal is gone. Standard input is closed and both output streams go to the daemon's log file.
+ */
+export declare function detachedDaemonSpawnOptions(logFd: number, env: NodeJS.ProcessEnv): {
+    readonly detached: true;
+    readonly stdio: ["ignore", number, number];
+    readonly env: NodeJS.ProcessEnv;
+};
+/**
+ * Spawns a detached supervisor: a background copy of this very executable running a hidden internal subcommand, its output appended to `logPath`, unref'd so the launcher never waits on it. `AGENT_SHIM_HOME` is passed explicitly so the supervisor lands on the same root as its spawner even when the launcher was started with the variable set only for itself.
+ */
+export declare function spawnDetachedSupervisor(paths: LayoutPaths, subcommand: string, logPath: string): number;
+/**
+ * Whether nothing is currently listening on one specific loopback port: binds it on 127.0.0.1 and releases, so the headroom supervisor can decide whether its sticky `lastPort` is still reusable. The same bind-and-release technique the supervisor's `freePort` uses, applied to a number the caller already cares about rather than asking the OS to pick one.
+ */
+export declare function realIsPortFree(port: number): Promise<boolean>;
+/**
+ * The real `HeadroomPort` for one launch: `ensure` runs the lock-and-poll coordination against the real filesystem and process table and derives the per-project identity from the real git repository containing the working directory; `release` removes this launcher's session-registry entry.
+ */
+export declare function realHeadroomPort(paths: LayoutPaths): HeadroomPort;
+/** The real `SpawnPort`, backed by `node:child_process`'s `spawnSync` — the Node equivalent of the legacy bash tool's `exec`. */
+export declare const realSpawnPort: SpawnPort;
+/** The real `ProcPort`, reading the actual process environment and logical CLI argv (`process.argv.slice(2)`). */
+export declare const realProcPort: ProcPort;
+/** The real `LogPort`, writing info/warn to stdout and errors to stderr. */
+export declare const realLogPort: LogPort;
+/**
+ * The pure decision logic behind `findExecutableInDir`, taking `platform`/`pathext`/the mode-stat as explicit parameters so it's unit-testable against fake Windows/POSIX environments without touching real process globals or a real filesystem — this is exactly the kind of platform-dependent logic that's easy to get subtly wrong (confirmed: it was, twice, across two failed release attempts before this was extracted and actually tested).
+ *
+ * `statFileMode` returns the file's POSIX mode bits if `candidate` exists as a regular file, or `undefined` otherwise (ENOENT collapsed to `undefined`, every other error still propagated by the real implementation).
+ *
+ * On Windows, this can't rely on `fs.Stats.mode`'s execute bits at all (see the comment above `windowsPathExtensions`), so it instead mirrors what a real shell does resolving a bare command name: try `name` as given if it already carries a recognised extension (e.g. a `.exe` filename passed in explicitly, as `resolveOwnExecutablePath`'s Scoop-shim redirect does), otherwise try appending each `PATHEXT` extension in turn and return the first that exists as a file. Everywhere else, a file counts as executable only when its POSIX mode bits actually say so.
+ */
+export declare function resolveExecutableCandidate(dir: string, name: string, env: {
+    readonly platform: string;
+    readonly pathext: string | undefined;
+    readonly statFileMode: (candidate: string) => number | undefined;
+}): string | undefined;
+/** Looks for a file literally named `name` inside `dir` and confirms it's runnable. Exported so `src/claudeShim.ts`'s PATH-shadow and shim-redirect checks can reuse the exact same semantics `discoverClaudeBinary`'s own PATH fallback already uses, rather than shelling out to a shell builtin like `command -v`. Real-wired convenience over `resolveExecutableCandidate` — see that function for the actual decision logic and its own tests. */
+export declare function findExecutableInDir(dir: string, name: string): string | undefined;
+/**
+ * Resolves the absolute path to the currently-running agent-shim/claude executable from the raw process/env facts a call site would otherwise read directly off `process` — passed explicitly so this is unit-testable without touching real process globals.
+ *
+ * This exists because `process.argv[1]` is not a reliable "path to my own executable" for a Node single-executable-application (SEA) binary the way it is for an ordinary Node script. Per Node's own SEA documentation, a SEA binary's `argv[1]` merely echoes back whatever string appeared on the command line — verbatim, with no path or PATH resolution applied by Node or the OS — whereas a shebang-invoked script (the npm/plain-Node case) genuinely receives its resolved script path there, because the kernel's shebang handling substitutes the shell's already-PATH-resolved pathname before Node ever starts. Concretely: typing the bare word `agent-shim` at a shell prompt produces `argv[1] === "agent-shim"` for a SEA binary (no directory component at all), which previously got fed straight into `fs.realpathSync`/`path.dirname` as if it were a real path — resolving relative to `process.cwd()` instead of wherever PATH actually found the binary, and throwing ENOENT the moment cwd didn't happen to contain a same-named file. Confirmed via a minimal instrumented SEA binary reproducing exactly this, and matching the exact failure every release verification job hit once invoking `agent-shim`/`claude` as a bare PATH-resolved command rather than by absolute path.
+ *
+ * A second, separate wrinkle: some install channels invoke this binary through a re-exec wrapper rather than running it directly. Scoop's own shim (`~/scoop/shims/agent-shim.exe`) is a compiled proxy (confirmed from its source: https://github.com/ScoopInstaller/Shim/blob/main/cs/shim.cs) that calls `CreateProcessW(null, cmd, ...)` with the real target's absolute path as the first token of `cmd` — per the Win32 `CreateProcess` contract, passing `lpApplicationName = null` means that first token becomes both the module launched *and* what the child receives as its own command line — so this process ends up seeing the real target's absolute path, living in a versioned app directory Scoop deliberately keeps off PATH, not the shim's own PATH-visible location. Placing the new `claude` alongside that path (as the Homebrew/direct-invocation case correctly does) would create a file PATH can never find. Confirmed against a real Scoop install: `agent-shim shim enable` placed `claude.exe` next to the real target in the app directory, and the immediately following `claude --version` failed with "not recognized" because that directory was never on PATH.
+ *
+ * The redirect-if-not-on-PATH check below applies uniformly to whichever candidate we end up with — whether derived from a path-shaped `argv1`, or from the `execPath` fallback (`argv1` undefined) — since it's unconfirmed whether a Windows SEA binary duplicates `argv[0]` into `argv[1]` the same way the POSIX build does; treating both sources identically is strictly more robust either way and regresses nothing already confirmed working.
+ *
+ * The algorithm: if the raw candidate is a bare word with no path separator, it can only have been found via PATH lookup in the first place (Node/the OS applies no resolution to it at all), so search PATH ourselves for the first directory containing an executable of that name, reconstructing exactly what the shell already did. Otherwise, resolve it (or the `execPath` fallback) against cwd, then check whether the *resulting directory* is itself on PATH: if so, use it directly (the Homebrew/direct-invocation case — never realpath'd, since a package manager's PATH-visible entry is often a symlink elsewhere, e.g. Homebrew's `/opt/homebrew/bin/agent-shim` pointing at its own Cellar keg, and callers need that PATH-visible location, not the dereferenced target). If that directory is *not* on PATH (the Scoop re-exec case above), search PATH for a separately-installed entry sharing our own invoked basename before falling back to the direct candidate.
+ */
+export declare function resolveOwnExecutablePath(env: {
+    readonly argv1: string | undefined;
+    readonly execPath: string;
+    readonly cwd: string;
+    readonly pathDirs: readonly string[];
+    readonly findExecutableInDir: (dir: string, name: string) => string | undefined;
+}): string;
+/** Real-wired convenience over `resolveOwnExecutablePath`, reading the actual process globals — this is what every real call site (`cli.ts`, `doctor.ts`, `claudeShim.ts`'s command wiring) should use instead of reading `process.argv[1]`/`process.execPath` directly. */
+export declare function realOwnExecutablePath(): string;
+/**
+ * Resolves the path to the actual file whose *content* is this running process — never a PATH-visible location, which can differ from the real content entirely (Scoop's own shim, a compiled proxy binary, sits at the PATH-visible location while the genuine agent-shim binary lives elsewhere; see `resolveOwnExecutablePath`'s own doc comment for the full mechanism). This is what `enableClaudeShim`/`disableClaudeShim` must hardlink/copy from and compare inodes against — using `resolveOwnExecutablePath`'s redirected PATH-visible location for this would hardlink Scoop's generic shim proxy itself, not agent-shim's real content, which is exactly the bug this function exists to avoid (confirmed against a real Scoop install: `shim enable` correctly placed `claude.exe` in `shims/`, but invoking it failed with Scoop's own "Cannot open shim file for read" error, because the hardlink's source was Scoop's proxy, paired via a `.shim` config file keyed to its *original* filename).
+ *
+ * `node:sea`'s `isSea()` is the correct, documented way to distinguish the two operating modes this tool ships in, rather than inferring it from `argv1`'s shape: for a single-executable-application build, `process.execPath` is always the real, fully-resolved running binary (confirmed: Windows `CreateProcess` with `lpApplicationName = null` still resolves to the genuine target file, the same one `execPath` reports, regardless of Scoop's separate PATH-visible proxy). For a plain Node script (the npm-published bundle), `execPath` would instead point at the Node interpreter itself — useless — so `argv1` (the shebang-resolved script path, reliable in this mode) is used instead.
+ */
+export declare function resolveContentSourcePath(env: {
+    readonly isSea: boolean;
+    readonly execPath: string;
+    readonly argv1: string | undefined;
+}): string;
+/** Real-wired convenience over `resolveContentSourcePath`. */
+export declare function realContentSourcePath(): string;
+/** Builds the real `resolveClaudeBinary` callback `runLauncher` needs: scans the real versions directory, then falls back to a real PATH search, excluding this tool's own install directory. */
+export declare function realResolveClaudeBinary(ownInstallDirs: readonly string[]): () => DiscoveredClaudeBinary;

package/dist/types/usage/middleware.d.ts

@@ -0,0 +1,17 @@
+import type { ResponseObserver } from "../frontdoor/pipeline";
+import { type UsageRecord } from "./schema";
+/** The provider name an OAuth session's requests are recorded under: they go to Claude Code's own API. */
+export declare const ANTHROPIC_PROVIDER = "anthropic";
+/** Everything the usage middleware depends on, injected so it runs against fakes in tests. */
+export interface UsageMiddlewareDeps {
+    /** Persists one finished request's record. It may throw; the middleware catches and logs, so a store failure never reaches a request. */
+    readonly record: (record: UsageRecord) => void;
+    /** Runs work after the current turn of the event loop, so recording never sits between a route's `end` and whatever the route does next (production: `setImmediate`). */
+    readonly defer: (task: () => void) => void;
+    readonly now: () => number;
+    readonly log: (line: string) => void;
+}
+/**
+ * The usage-tracking response middleware: registered at the front door's hook point, it records one metadata-only `UsageRecord` per routed response once its body has finished. The head gives the status, latency and rate-limit headers; the body, scanned incrementally as the client receives it (decompressing a copy when the upstream compressed it), gives the model and token usage. The response the client receives is never touched: the middleware sees each chunk only after the socket has it, keeps no body, and does its recording on a deferred turn. Every failure (a scanner, a decompressor, the store) is caught and logged, never thrown into the request.
+ */
+export declare function createUsageMiddleware(deps: UsageMiddlewareDeps): ResponseObserver;

package/dist/types/usage/pick.d.ts

@@ -0,0 +1,62 @@
+import { type PlanClass } from "./plan";
+import type { AccountMetadata, UsageRecord, UsageSnapshot } from "./schema";
+/** The lengths of Anthropic's two subscription windows, used when a window reported no reset time of its own. */
+export declare const FIVE_HOUR_WINDOW_MS: number;
+/** Anthropic's longest prompt-cache lifetime (the one-hour tier): a conversation resumed within it still has a warm cache on the account that served it, and the cache is per organisation, so it is lost by switching. */
+export declare const PROMPT_CACHE_TTL_MS: number;
+/** The state a member's ranking was built from. */
+export interface PoolMember {
+    readonly identity: string;
+    /** The identity's usage snapshot, when it has one. */
+    readonly snapshot?: UsageSnapshot;
+    /** Why the member's recorded state could not be read (a corrupt or newer-schema snapshot, an unreadable login file), when that is the case. */
+    readonly readError?: string;
+    readonly account?: AccountMetadata;
+    /** The member's usage-log records from the current five-hour window on. */
+    readonly records: readonly UsageRecord[];
+}
+/** The member last picked for this directory, kept so a conversation stays on the account whose prompt cache is warm. */
+export interface StickyPick {
+    readonly identity: string;
+    readonly at: string;
+}
+export interface RankPoolInput {
+    readonly members: readonly PoolMember[];
+    readonly nowMs: number;
+    readonly sticky?: StickyPick;
+    /** True when the launch continues or resumes a conversation, which belongs on the account it started on whatever the cache lifetime. */
+    readonly resuming: boolean;
+}
+/** In pick order. `scored` has usable quota data; `unknown` has none (never recorded, or unreadable); `pay-per-use` bills by use instead of drawing on a plan; `ineligible` is refused right now. */
+type CandidateClass = "scored" | "unknown" | "pay-per-use" | "ineligible";
+export interface Candidate {
+    readonly identity: string;
+    readonly class: CandidateClass;
+    /** Plan-size-weighted remaining quota per hour until its reset: higher is more wasted if left unused. Present for `scored` only. */
+    readonly score?: number;
+    /** False when the five-hour window would run dry, at the observed pace, before it resets. A `scored` candidate that is not feasible ranks below every feasible one. */
+    readonly feasible: boolean;
+    /** When an `ineligible` candidate can be used again. */
+    readonly blockedUntilMs?: number;
+    readonly plan: PlanClass;
+    /** Human-readable facts behind the class and score, in the order they matter. */
+    readonly reasons: readonly string[];
+}
+export interface PoolRanking {
+    /** Every member, best first. */
+    readonly candidates: readonly Candidate[];
+    /** The member to launch on: the best one that is not refused. Undefined when every member is refused. */
+    readonly pick?: Candidate;
+    /** When nothing can be picked, the soonest any member comes back. */
+    readonly earliestReturn?: {
+        readonly identity: string;
+        readonly atMs: number;
+    };
+}
+/**
+ * Ranks `members` for a launch.
+ *
+ * A member is `ineligible` while a window of its plan, or a refusal it last hit, still binds; it is `unknown` without recorded quota, `pay-per-use` when its usage bills by use, and otherwise `scored`. Scored members order by how much plan-size-weighted quota would expire unused per hour of runway, with any whose five-hour window would run dry at the observed pace (their own, or the person's pace on another member rescaled by plan size) placed behind those that would not. The member last picked for this directory then moves to the front if it is still usable and either the launch resumes a conversation or its prompt cache is still warm.
+ */
+export declare function rankPool(input: RankPoolInput): PoolRanking;
+export {};

package/dist/types/usage/plan.d.ts

@@ -0,0 +1,18 @@
+import type { AccountMetadata } from "./schema";
+/** What an account's plan means for picking it: a subscription with a capacity relative to the smallest paid tier, or an account billed by use. */
+export type PlanClass = {
+    readonly kind: "subscription";
+    /** The plan's size as a multiple of the smallest subscription tier (Max 5x is 5, Max 20x is 20). */
+    readonly capacity: number;
+    /** False when the tier string named no multiplier and no tier this project knows, so `capacity` is the neutral 1 rather than a reading. */
+    readonly recognised: boolean;
+    /** The tier string the classification rests on, when the account had one. */
+    readonly tier?: string;
+} | {
+    readonly kind: "pay-per-use";
+    readonly tier?: string;
+};
+/**
+ * Classifies an account from the rate-limit tier of its stored login (`organizationRateLimitTier`, which decides the organisation's limits, then `userRateLimitTier`). The tier strings are free text on Anthropic's side, so only the shapes seen are read: a trailing `<n>x` is that multiple, a bare `pro` is 1, a `zero` tier is pay-per-use. Anything else is a subscription of unrecognised size, counted as 1 and marked so the ranking can say it guessed.
+ */
+export declare function planOf(account: AccountMetadata | undefined): PlanClass;