agent-shim 0.0.0 → 7.1.0

package/dist/types/config/store.d.ts

@@ -0,0 +1,46 @@
+import type { z } from "zod";
+/**
+ * Filesystem primitives `store.ts` needs, injected so tests can simulate a crash between the temp-file write and the rename without touching real process semantics (e.g. actually killing the process mid-write). The default implementation (`nodeStoreFs`) is real `node:fs`, used by every CLI adapter in normal operation and by this module's own tests when exercising the real atomic-rename behaviour end to end.
+ */
+export interface StoreFs {
+    /** Reads a file's contents as UTF-8 text, or returns undefined when it does not exist. */
+    readonly readFileUtf8: (filePath: string) => string | undefined;
+    /** Writes a file's full contents as UTF-8 text, creating or truncating it. */
+    readonly writeFileUtf8: (filePath: string, contents: string) => void;
+    /** Atomically renames `from` to `to` (same filesystem — both are always in the same directory in this module's own usage). */
+    readonly renameSync: (from: string, to: string) => void;
+    /** Creates a directory (and any missing parents), succeeding silently if it already exists. */
+    readonly mkdirSync: (dirPath: string) => void;
+    /** Removes a file, succeeding silently if it does not exist — used to clean up a stray temp file after a failed rename. */
+    readonly unlinkSync: (filePath: string) => void;
+}
+/** The real `node:fs`-backed implementation of `StoreFs`, used by every CLI adapter in normal operation. */
+export declare const nodeStoreFs: StoreFs;
+/**
+ * Reads and validates one JSON config file against `schema`.
+ *
+ * Returns undefined when the file does not exist. Throws `ConfigValidationError` (the same error type `src/config/load.ts` throws for every other config file in this project) when it exists but fails validation.
+ */
+export declare function readJson<S extends z.ZodType>(filePath: string, schema: S, storeFs?: StoreFs): z.infer<S> | undefined;
+/**
+ * Writes `contents` as UTF-8 text to `filePath` atomically: writes to a temp file in the *same directory* first, then renames it into place. A crash (or thrown error) between the write and the rename leaves the original file at `filePath` completely untouched — the failure mode this exists to prevent is a config file left half-written after an interrupted process.
+ *
+ * The temp file's name includes the destination's own basename, the process id, and a random UUID, so two concurrent writers (even to the same file, even from two processes) never collide on the same temp path.
+ */
+export declare function writeTextAtomic(filePath: string, contents: string, storeFs?: StoreFs): void;
+/** Writes `data` as pretty-printed JSON to `filePath`, via `writeTextAtomic`. */
+export declare function writeJsonAtomic(filePath: string, data: unknown, storeFs?: StoreFs): void;
+/** Inputs to `applyPatch`. */
+export interface ApplyPatchOptions<T> {
+    /** Used as the base to merge `patch` into when `filePath` does not exist yet. Required for a file that may not exist yet (e.g. a config profile's own first `set` before it was ever written by `create`); omit only when the file is guaranteed to already exist. */
+    readonly defaults?: T;
+    readonly storeFs?: StoreFs;
+}
+/**
+ * Reads `filePath` (or falls back to `options.defaults` when it does not exist), shallow-merges `patch` over the top-level keys of the result, re-validates the merged object against `schema`, and writes it back atomically.
+ *
+ * The merge is deliberately shallow — only top-level keys of the parsed config are replaced wholesale by the corresponding key in `patch`. A caller that wants to add one key to a nested object (e.g. one more category inside `categories`) must read the existing nested object itself and pass the already-merged nested object as part of `patch`; `applyPatch` does not recurse into nested objects on its own.
+ *
+ * Throws when the file does not exist and no `defaults` were given, and re-throws `ConfigValidationError` (via the underlying `schema.parse`) when the merged result does not validate.
+ */
+export declare function applyPatch<S extends z.ZodType>(filePath: string, schema: S, patch: Readonly<Partial<z.infer<S>>>, options?: ApplyPatchOptions<z.infer<S>>): z.infer<S>;

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

@@ -0,0 +1,19 @@
+/**
+ * How a launch's capability token is presented and checked. The token reaches the child twice: as the `x-agent-shim-auth` header on every request it sends (see `AUTH_HEADER`), and as the password in the `HTTPS_PROXY` URL an OAuth launch gets, which every proxy-aware client turns into `Proxy-Authorization: Basic ...` on its CONNECT request. Both are checked against the same live registry with the same constant-time comparison.
+ */
+/** The user name in the proxy URL. A label only: the surface checks the password, which is the capability, and ignores the user name, so nothing depends on how a client spells it. */
+export declare const CONNECT_PROXY_USER = "agent-shim";
+/** The realm the CONNECT surface's 407 challenge names, so a client that waits for a challenge before sending credentials knows which ones to send. */
+export declare const CONNECT_PROXY_REALM = "agent-shim front door";
+/**
+ * The `HTTPS_PROXY` value for a launch: the CONNECT surface's loopback address with the capability as the URL's password. Both userinfo halves are percent-encoded, because a client percent-decodes userinfo before it builds the `Proxy-Authorization` value, so the surface receives exactly the token whatever characters it holds.
+ */
+export declare function connectProxyUrl(port: number, token: string): string;
+/**
+ * The capability a `Proxy-Authorization` header value presents: the password half of a Basic credential (everything after the first colon of the decoded user-pass, since RFC 7617 forbids a colon in the user name and permits one in the password). Undefined for any other scheme, a credential with no colon, or an empty password.
+ */
+export declare function capabilityFromProxyAuthorization(value: string): string | undefined;
+/**
+ * Whether `presented` is one of the live capabilities, compared in constant time: every live token is compared against the presented one in full, with no early exit on a match or a mismatching prefix, so the time a check takes reveals neither which token matched nor how much of a guess was right.
+ */
+export declare function isLiveCapability(presented: string, live: Readonly<Iterable<string>>): boolean;

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

@@ -0,0 +1,179 @@
+import type { IncomingHttpHeaders, IncomingMessage, ServerResponse } from "node:http";
+import * as net from "node:net";
+/**
+ * The front door's CONNECT surface, so an OAuth session can have agent-shim's routing AND Claude Code's Remote Control at once: Remote Control refuses any `ANTHROPIC_BASE_URL` other than the real API, but happily honours `HTTPS_PROXY`, so OAuth launches route at the proxy layer instead.
+ *
+ * Nothing is tunnelled or intercepted for a client that has not authenticated: every CONNECT request must present a live launch's capability as its proxy credential (`Proxy-Authorization: Basic`, which clients derive from the credential in the `HTTPS_PROXY` URL the launcher sets), or it is answered 407 before any target is dialled, so the port is no open proxy for other local processes. Pending and authenticated connections are bounded by `ConnectLimits`.
+ *
+ * Every authenticated CONNECT target is blind-tunnelled byte for byte EXCEPT the intercept host (Claude Code's own API), whose TLS this surface terminates with a leaf certificate signed by a locally generated CA. On the terminated session, the paths the front door routes (`/v1/`) are handed to the same ordered pipeline the provider listener serves (the client's Authorization header passes through untouched), and every other path is piped by this surface to the real upstream over TLS, so Remote Control's streaming, OAuth refreshes, and unknown endpoints bypass the pipeline entirely.
+ */
+/** The one CONNECT host whose TLS gets terminated: Claude Code's own API, the upstream every OAuth session is really talking to. */
+export declare const CONNECT_INTERCEPT_HOST = "api.anthropic.com";
+/** Paths under this prefix are what the routed pipeline serves; everything else on the terminated session goes to the real upstream. */
+export declare const ROUTED_PATH_PREFIX = "/v1/";
+/** The port HTTPS is served on, both the default when a CONNECT authority names none and the port non-headroom paths are piped to on the real upstream. */
+export declare const HTTPS_PORT = 443;
+/** Largest CONNECT request head accepted before the connection is refused: a real head is a request line and a few short headers (Host, the proxy credential, a User-Agent), so anything this size is a confused or hostile client. 8 KiB is also the per-header-line limit common HTTP servers apply by default (nginx's `large_client_header_buffers` buffer, Apache's `LimitRequestFieldSize` of 8190 bytes), so no client is built to need a longer line, and a CONNECT head is a few such lines at most. */
+export declare const MAX_CONNECT_HEAD_BYTES = 8192;
+/**
+ * The surface's connection deadlines and caps. Production passes `CONNECT_LIMITS`; tests pass small values so a deadline or a cap is reached in milliseconds.
+ *
+ * A connection is pending from accept until its CONNECT head has arrived, and authenticated once that head presented a live launch's capability. Pending connections are bounded twice, by `headDeadlineMs` and by `maxPendingHeads` (reaching the cap evicts the oldest pending connection rather than refusing the newest, so a squatter holding open half-sent heads cannot lock live launches out: a real client's head arrives in its first segment and is authenticated long before that many newer connections could push it out). Authenticated connections are bounded by `maxTunnels` and revoked when their launch ends; they have no idle timeout (see `CONNECT_LIMITS`).
+ */
+export interface ConnectLimits {
+    /** How long a connection may take to deliver its whole CONNECT head before it is answered 408 and closed. */
+    readonly headDeadlineMs: number;
+    /** How many connections may be waiting for their head at once; one more evicts the oldest. */
+    readonly maxPendingHeads: number;
+    /** How many authenticated connections (blind tunnels and terminated sessions together) may be open at once; one more is answered 503 and closed. */
+    readonly maxTunnels: number;
+    /** How often every authenticated connection's capability is re-checked, closing the connections of any launch that has since ended. */
+    readonly revalidateMs: number;
+}
+/**
+ * The production limits, each derived from what the surface's real clients do.
+ *
+ * `headDeadlineMs`: every client checked (Claude Code, curl, Node's own proxy support, Python's urllib) sends its whole CONNECT head, credential included, the moment the TCP connection opens, without waiting for anything from the proxy, so on loopback the head arrives within milliseconds. The deadline only has to outlast a door process stalled by a loaded machine, and ten seconds is three orders of magnitude above any such stall while still ending a slowloris connection quickly.
+ *
+ * `maxPendingHeads`: since a real head arrives in the first segment, the pending set at any instant holds only connections opened in the same instant. The largest real burst is a package manager or similar running inside a session, which opens its parallel downloads through HTTPS_PROXY at once; 64 covers the defaults of npm (`maxsockets` 15) and pnpm (`network-concurrency` 16) several times over, and eviction means even a larger burst only costs a retry, never a lockout.
+ *
+ * `maxTunnels`: each authenticated connection holds two descriptors (the client's and the upstream's). Node raises its soft descriptor limit to the hard limit at start, and 4096 is the smallest hard limit common Linux distributions ship (macOS's is far higher), so 1024 tunnels keep the surface to half of it, leaving the provider and direct listeners room to serve rather than all three failing with EMFILE. It is still many times what concurrent sessions hold: each keeps a handful of tunnels plus whatever bursts its tools make.
+ *
+ * `revalidateMs`: the supervisor prunes dead launches from the registry once per `FRONTDOOR_POLL_MS`, so re-checking more often than that could never find anything newly dead.
+ *
+ * There is deliberately no idle timeout on an authenticated connection: Remote Control and other long-lived streams can sit silent for as long as the far end chooses between events, at an interval the surface cannot know, so any idle timeout would cut legitimate sessions. Authenticated connections are bounded instead by who can open them (only a live launch's process tree holds the capability), by `maxTunnels`, and by revocation: a launch that ends loses every connection it opened at the next revalidation.
+ */
+export declare const CONNECT_LIMITS: ConnectLimits;
+/** One parsed CONNECT authority, the host lowercased and the port defaulted. */
+export interface ConnectTarget {
+    readonly host: string;
+    readonly port: number;
+}
+/** Parses a CONNECT authority (`host:port`, or a bare `host` meaning 443), or undefined when it names no host or a non-numeric port. */
+export declare function parseConnectTarget(authority: string): ConnectTarget | undefined;
+/** Whether a CONNECT target's host (port already stripped) is the one whose TLS this proxy terminates. */
+export declare function isInterceptedHost(host: string, interceptHost: string): boolean;
+/** Whether a request path on the terminated session is one the routed pipeline serves. The query string stays part of the path: `/v1/messages?beta=true` is still the pipeline's. */
+export declare function servedByPipeline(path: string | undefined): boolean;
+/**
+ * Headers a forwarded HTTP message keeps: everything except the hop-by-hop set, which belongs to whichever connection carried it and must not leak onto the next one. The `Connection` header's own value can name further hop-by-hop headers (RFC 9110 section 7.6.1), so those go too. Returns a fresh object; the input is the live parser's map and is never mutated.
+ */
+export declare function forwardableHeaders(headers: Readonly<IncomingHttpHeaders>): IncomingHttpHeaders;
+/** A CA certificate and its private key, both as PEM. */
+export interface CaMaterial {
+    readonly certPem: string;
+    readonly keyPem: string;
+}
+/** A TLS leaf certificate and its private key, both as PEM. */
+export interface LeafCert {
+    readonly certPem: string;
+    readonly keyPem: string;
+}
+/** Generates the local CA: one RSA keypair, self-signed, CA-only by basicConstraints and keyUsage, with a random serial. Built on `node:crypto` alone (see `x509.ts`), no openssl, so the same code works on every platform agent-shim ships to. */
+export declare function generateCa(now: Readonly<Date>): CaMaterial;
+/** The names the front door's provider listener answers to: the loopback address every provider session's base URL names, plus the loopback hostname for a client that spells it that way. */
+export declare const LOOPBACK_LEAF_NAMES: readonly string[];
+/**
+ * Mints a TLS leaf signed by the CA: its own RSA keypair, server-auth usage only, the first name as the subject's common name and every name in the SAN. A name that parses as an IP address goes in as an IP SAN, because TLS clients match an IP host only against IP SANs, never against a DNS SAN spelling the same digits.
+ */
+export declare function mintLeaf(ca: CaMaterial, names: readonly string[], now: Readonly<Date>): LeafCert;
+/** Mints each host's leaf once from the CA and reuses it, because generating a 2048-bit RSA keypair costs noticeable time and nothing about the certificate changes between sessions. */
+export declare function createLeafCache(ca: CaMaterial, now: () => Date): (host: string) => LeafCert;
+/**
+ * Persistence for the CA: generated once on the machine's first headroom start and reused forever after, because regenerating it would invalidate every child's `NODE_EXTRA_CA_CERTS` pointing at the old file. The real implementation writes the key with mode 0600; injected fakes keep it in memory.
+ */
+export interface ConnectCertStore {
+    /** The persisted CA, or undefined when none exists yet (or only half of it does: a cert without its key can sign nothing, so it counts as absent). */
+    readonly loadCa: () => CaMaterial | undefined;
+    /** Persists both halves of the CA, the key unreadable to other users. */
+    readonly writeCa: (ca: CaMaterial) => void;
+}
+/**
+ * Loads the persisted CA, generating and persisting one when no usable CA exists. A stored pair that `node:crypto` cannot parse is treated as absent and replaced: a truncated write is the one failure mode a regeneration can actually repair, and every child that trusted the old file needs a new `NODE_EXTRA_CA_CERTS` anyway once its CA stops parsing.
+ */
+export declare function ensureCa(store: ConnectCertStore, generate: () => CaMaterial): CaMaterial;
+/** Where one forwarded request goes, and how: the connect surface's own forwards go to the real upstream over TLS, while a local hop over plain HTTP is what tests redirect to. */
+interface ConnectForwardTarget {
+    readonly host: string;
+    readonly port: number;
+    readonly tls: boolean;
+    /** The SNI name to present; defaults to `host`. Separated so a test can connect to a local fake while presenting the production hostname. */
+    readonly servername?: string;
+    /** Extra trust anchors for the target's certificate, when it is not system-trusted (a test's local fake upstream). */
+    readonly ca?: readonly string[];
+    /** Overrides certificate verification; production leaves it at the Node default (verify against system trust or `ca`). */
+    readonly rejectUnauthorized?: boolean;
+}
+/** Handles one parsed HTTP request on a terminated TLS session. */
+type ConnectRequestHandler = (request: IncomingMessage, response: ServerResponse) => void;
+/** A bound loopback listener and how to stop it. */
+interface ConnectListenerHandle {
+    readonly port: number;
+    /** Stops accepting, ends every live connection, and resolves once the port is released. */
+    readonly close: () => Promise<void>;
+}
+/** Presents one leaf's server-side TLS on CONNECTed sockets. */
+interface TlsAcceptor {
+    /** Starts the TLS handshake on a socket that has just received its CONNECT response. */
+    readonly accept: (socket: net.Socket) => void;
+    /** Drops every session this acceptor is terminating. */
+    readonly close: () => void;
+}
+/** Parses HTTP over terminated sockets and serves each request through the handler, keep-alive included. */
+interface HttpParserSession {
+    readonly serve: (socket: net.Socket) => void;
+    readonly close: () => void;
+}
+/**
+ * Every effect the MITM proxy performs, injected so the routing decisions and lifecycle run against fakes in unit tests (the SupervisorPorts pattern): TCP listening, TLS termination, HTTP parsing, plain TCP tunnels, and request forwarding. The real implementation is `realConnectEffects`; the TLS round-trip test uses it with redirected targets.
+ */
+export interface ConnectEffects {
+    /** Binds a loopback TCP listener; `preferredPort` is tried first and any free port used when it is taken (bind, do not probe: check-then-bind races). Resolves with the bound port and a close handle. */
+    readonly listenLoopback: (preferredPort: number | undefined, onSocket: (socket: net.Socket) => void) => Promise<ConnectListenerHandle>;
+    /** Builds the TLS terminator for one leaf, handing each successfully handshaked session to `onSecure`. */
+    readonly createTlsAcceptor: (leaf: LeafCert, onSecure: (secure: net.Socket) => void) => TlsAcceptor;
+    /** Builds the HTTP parser bound to one request handler. */
+    readonly createHttpSession: (handler: ConnectRequestHandler) => HttpParserSession;
+    /** Opens a raw TCP connection for a blind tunnel. */
+    readonly connectTcp: (host: string, port: number) => Promise<net.Socket>;
+    /** Streams one request to `target` and the response back, never buffering a body. */
+    readonly forwardHttp: (target: ConnectForwardTarget, request: IncomingMessage, response: ServerResponse) => void;
+}
+/** Everything the connect surface needs to route, resolved before it starts. */
+export interface ConnectServerConfig {
+    /** The CONNECT host whose TLS gets terminated. */
+    readonly interceptHost: string;
+    /**
+     * Serves one routed path (`/v1/...`) from the terminated session: the same ordered pipeline the provider listener hands requests to, so an OAuth session and a provider session run identical identification, middleware and routing.
+     */
+    readonly serveRouted: ConnectRequestHandler;
+    /** The leaf to terminate `interceptHost` with, minted and cached per host. */
+    readonly leafFor: (host: string) => LeafCert;
+    /** Where non-routed paths on the terminated session are piped: the real upstream over TLS. */
+    readonly upstream: ConnectForwardTarget;
+    /** Whether a capability presented as a CONNECT request's proxy credential belongs to a live launch: the same constant-time check against the same registry the routed pipeline's admission makes, read fresh on every call because launches come and go. */
+    readonly isLiveCapability: (token: string) => boolean;
+    /** The connection deadlines and caps; production passes `CONNECT_LIMITS`. */
+    readonly limits: ConnectLimits;
+}
+/** A running connect surface. */
+export interface ConnectServerHandle {
+    readonly port: number;
+    /** Stops the listener, drops every live tunnel and terminated session, and resolves once the port is released. */
+    readonly close: () => Promise<void>;
+}
+/**
+ * Starts the connect surface: binds the listener, mints the intercept host's leaf, and wires the per-connection routing. Resolves once the listener is bound.
+ *
+ * The connection flow: read the CONNECT head within the deadline (never more of the stream than that, so an early ClientHello glued to the head is pushed back with `unshift` and still seen by whatever consumes the socket next), authenticate it, then either blind-tunnel the target or terminate its TLS and parse HTTP on the session. Every network effect flows through `effects`; nothing here touches the network or filesystem itself.
+ */
+export declare function startConnectServer(config: ConnectServerConfig, effects: ConnectEffects, preferredPort: number | undefined): Promise<ConnectServerHandle>;
+/** The real `ConnectEffects` over node's own net, tls, and http. `connectTcp` opens real connections to the CONNECTed host, so tests that want a blind tunnel redirect it. */
+export declare function realConnectEffects(): ConnectEffects;
+/** The real `ConnectCertStore` on the filesystem: `ca.pem` world-readable (it is public material), `ca.key` mode 0600 exactly, chmod'ed after the write because a create's mode bits pass through the process umask. */
+export declare function realConnectCertStore(paths: {
+    readonly frontdoorCaDir: string;
+    readonly frontdoorCaCertFile: string;
+    readonly frontdoorCaKeyFile: string;
+}): ConnectCertStore;
+export {};

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

@@ -0,0 +1,34 @@
+import { CliError } from "../cliError";
+import type { LayoutPaths } from "../paths";
+import { type HeadroomFs } from "../headroom/state";
+import type { ListenerVerdict } from "./probe";
+/** Raised when the front door cannot be brought up in time or has recorded a fatal error: a routed launch has no other way to reach its provider, so it must fail rather than start a session that can never answer. */
+export declare class FrontDoorStartError extends CliError {
+    constructor(message: string);
+}
+/** Every effect the ensure step performs, injected so it runs against fakes in tests. */
+export interface EnsureFrontDoorPorts {
+    readonly fs: HeadroomFs;
+    /** Zombie-aware liveness (see `realIsProcessRunning`). */
+    readonly isRunning: (pid: number) => boolean;
+    readonly now: () => number;
+    readonly sleep: (ms: number) => void;
+    /** Spawns the detached front-door supervisor, returning its pid. */
+    readonly spawnSupervisor: (paths: LayoutPaths) => number;
+    /** Authenticates the provider listener on `port`: a TLS handshake chaining to agent-shim's CA and a healthy answer, with no capability sent (see `probeFrontDoorSync`). */
+    readonly verifyListener: (port: number) => ListenerVerdict;
+}
+/**
+ * Brings the front door up for this launch, or finds it serving, and registers this launcher pid in its session registry: the fact that keeps the door from idling out while this session lives, and the record that holds this launch's capability token. The same lock-and-poll coordination as headroom's and the old codex daemon's ensure: the exclusive-create start lock decides which of several concurrent launches spawns the one supervisor, everyone waits on state.json, and a lock whose holder died is removed and retried. Ready means state names a live supervisor and both listeners' ports, which the supervisor writes only after both have bound (and the provider listener has answered its own health probe).
+ *
+ * A live pid in state proves nothing about who holds the port it names: the door may have crashed and left the port to anyone, or the pid may have been reused by an unrelated process. So before anything is registered or returned, the provider listener is authenticated over TLS against agent-shim's CA. A listener that fails (wrong certificate, nothing answering, a bad answer) is treated as a stale or hostile owner: its pid is distrusted for the rest of this call and a replacement supervisor is spawned, which binds a free port when the sticky one is held and is then verified in turn. If a supervisor this call spawned also fails verification, the launch is refused naming the reason and the daemon log; no capability is written and no address is handed to the child.
+ */
+export declare function ensureFrontDoor(params: {
+    readonly paths: LayoutPaths;
+    readonly launcherPid: number;
+    readonly ports: EnsureFrontDoorPorts;
+}): {
+    readonly port: number;
+    readonly connectPort: number;
+    readonly token: string;
+};

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

@@ -0,0 +1,13 @@
+/** The outcome of authenticating the listener a front-door state file names. */
+export type ListenerVerdict = {
+    readonly ok: true;
+} | {
+    readonly ok: false;
+    readonly reason: string;
+};
+/**
+ * Authenticates the front door's provider listener before a launch trusts it: a TLS handshake that must chain to agent-shim's CA (whose key only this user can read) for 127.0.0.1, then a healthy answer. A process that merely holds the port (a stale state file's port re-bound by someone else, or a reused pid's listener) cannot complete that handshake, so it fails here and the launch never hands its child that address.
+ *
+ * Synchronous because the launcher is synchronous right through to `spawnSync`: the HTTPS request runs on a worker thread and this thread blocks on a shared buffer until the worker posts its verdict.
+ */
+export declare function probeFrontDoorSync(port: number, caPem: string): ListenerVerdict;

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

@@ -0,0 +1,50 @@
+import { z } from "zod";
+import type { HeadroomFs } from "../headroom/state";
+/** The record held in one front-door session-registry file: the launcher's pid plus the per-launch capability token its child presents on every request. */
+declare const FrontDoorSessionSchema: z.ZodObject<{
+    pid: z.ZodNumber;
+    startedAt: z.ZodNumber;
+    token: z.ZodString;
+}, z.core.$strict>;
+export type FrontDoorSession = z.infer<typeof FrontDoorSessionSchema>;
+/**
+ * The front-door supervisor's state.json under `<home>/frontdoor/`. Every field is optional because the file exists in stages, exactly like headroom's and the old codex daemon's: a fresh supervisor writes its own pid before the listener is up, and a shut-down front door leaves only the sticky `lastPort` and any `lastError` worth surfacing.
+ */
+declare const FrontDoorStateSchema: z.ZodObject<{
+    supervisorPid: z.ZodOptional<z.ZodNumber>;
+    port: z.ZodOptional<z.ZodNumber>;
+    lastPort: z.ZodOptional<z.ZodNumber>;
+    connectPort: z.ZodOptional<z.ZodNumber>;
+    lastConnectPort: z.ZodOptional<z.ZodNumber>;
+    directPort: z.ZodOptional<z.ZodNumber>;
+    lastDirectPort: z.ZodOptional<z.ZodNumber>;
+    lastError: z.ZodOptional<z.ZodString>;
+}, z.core.$strict>;
+export type FrontDoorState = z.infer<typeof FrontDoorStateSchema>;
+/** Reads state.json, or undefined when absent or malformed: a malformed file is overwritten by the next supervisor rather than failing every launch over one bad write. */
+export declare function readFrontDoorState(fs: HeadroomFs, stateFile: string): FrontDoorState | undefined;
+/** Writes state.json. A plain write, for the reason headroom's is: the file is advisory coordination read tolerantly, and the exclusive-create start lock is the actual mutual exclusion. */
+export declare function writeFrontDoorState(fs: HeadroomFs, stateFile: string, state: Readonly<FrontDoorState>): void;
+/**
+ * The origin the headroom hop forwards routed traffic back to (the direct listener's), or undefined before the front door has ever served: what the headroom allowlist must admit for a provider routed through headroom, since headroom reaches the door's routes at exactly this address.
+ */
+export declare function frontDoorOrigin(state: FrontDoorState | undefined): string | undefined;
+/**
+ * Writes one launch's session record: the registry entry that both keeps the door from idling out and holds the token that launch's requests must present. The token is a bearer capability, so the directory is created owner-only (0700) and the record written owner-only (0600): on a multi-user host another local account must be able neither to list nor to read it, since presenting it to a listener would spend the victim's provider credential or Codex login.
+ */
+export declare function writeFrontDoorSession(fs: HeadroomFs, sessionsDir: string, session: Readonly<FrontDoorSession>): void;
+/** A registered launch as status and the idle decision see it: the pid and start time, never the token, so nothing that prints or serialises a session can leak the capability. */
+export type FrontDoorSessionSummary = Pick<FrontDoorSession, "pid" | "startedAt">;
+/**
+ * Every registered launch, unreadable or malformed files skipped, sorted by pid. Read through `FrontDoorSessionSchema`, which carries the token: headroom's token-less `listSessions` is strict and rejects every front-door record, which would make a live session invisible to the supervisor's idle decision and close the listeners (releasing the sticky ports) under a running child.
+ */
+export declare function listFrontDoorSessions(fs: HeadroomFs, sessionsDir: string): readonly FrontDoorSessionSummary[];
+/** Removes one launcher's registry entry, and with it that launch's capability. Idempotent. */
+export declare function removeFrontDoorSession(fs: HeadroomFs, sessionsDir: string, pid: number): void;
+/** Removes every entry whose launcher is no longer running, so a dead launch's capability stops being accepted and cannot keep the door awake. The predicate must be zombie-aware, as for headroom's. */
+export declare function pruneDeadFrontDoorSessions(fs: HeadroomFs, sessionsDir: string, isRunning: (pid: number) => boolean): readonly number[];
+/**
+ * Every live session's token, read fresh: what a client-facing listener checks a request's capability against. Malformed files are skipped for the same reason `readFrontDoorState` tolerates them.
+ */
+export declare function liveSessionTokens(fs: HeadroomFs, sessionsDir: string): ReadonlySet<string>;
+export {};

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

@@ -0,0 +1,48 @@
+import type { HeadroomFs } from "../headroom/state";
+import type { LayoutPaths } from "../paths";
+/** A bound front-door listener in this process, and how to stop it. */
+interface FrontDoorListenerHandle {
+    readonly port: number;
+    /** Stops accepting, ends every live connection, and resolves once the port is released. */
+    readonly close: () => Promise<void>;
+}
+/** Every effect the front-door supervisor performs, injected so its whole lifecycle runs against fakes: no real process, port, clock or listener in a unit test. */
+export interface FrontDoorSupervisorPorts {
+    readonly fs: HeadroomFs;
+    readonly paths: LayoutPaths;
+    readonly ownPid: number;
+    readonly now: () => number;
+    /** An event-loop-yielding wait, for the same reason headroom's is: nothing else would ever run between ticks. */
+    readonly sleep: (ms: number) => Promise<void>;
+    /** Zombie-aware liveness, the notion every coordination decision in this project uses. */
+    readonly isRunning: (pid: number) => boolean;
+    /**
+     * Starts the provider listener in this process on `preferredPort` (falling back to any free port when the sticky one is taken, decided at bind time rather than by a racy check-then-bind probe) and resolves once it has bound and answered its own health probe over TLS. This is the HTTPS listener every provider session's base URL points at, serving a loopback leaf signed by agent-shim's CA.
+     */
+    readonly startProviderListener: (preferredPort: number | undefined) => Promise<FrontDoorListenerHandle>;
+    /**
+     * Starts the CONNECT surface in this process on `preferredPort` (same bind-time fallback): the TLS-terminating listener an OAuth session's HTTPS_PROXY points at. Bound before any state names it, so an OAuth launch never finds one listener up without the other.
+     */
+    readonly startConnectListener: (preferredPort: number | undefined) => Promise<FrontDoorListenerHandle>;
+    /**
+     * Starts the direct listener on `preferredPort` (same bind-time fallback): the same routes as the provider listener, minus the headroom hop, over plain HTTP because headroom is what connects to it. Headroom forwards routed traffic back here, which is what keeps the hop from looping, and the port is sticky like the others because headroom's allowlist admits its exact origin. It admits only the hop's own requests and holds no credential until it redeems one from the hop's custody.
+     */
+    readonly startDirectListener: (preferredPort: number | undefined) => Promise<FrontDoorListenerHandle>;
+    readonly log: (line: string) => void;
+}
+/** Options for `runFrontDoorSupervisor`. */
+export interface RunFrontDoorSupervisorOptions {
+    /** Bounds the loop's iterations so a test can observe steady state; such a run returns `FRONTDOOR_SUPERVISOR_STILL_RUNNING`. */
+    readonly tickLimit?: number;
+}
+/** Returned by a tick-bounded run that reached its limit while still serving. Never an exit code. */
+export declare const FRONTDOOR_SUPERVISOR_STILL_RUNNING = -1;
+/** The supervisor's tick rate for the idle clock. */
+export declare const FRONTDOOR_POLL_MS = 1000;
+/**
+ * Runs the front-door supervisor: binds all three listeners (the HTTPS provider listener, the CONNECT surface and the plain-HTTP direct listener, each on its sticky port), records the serving state, and shuts down after `idleShutdownMinutes` with an empty session registry. Returns the exit code: 0 for an idle shutdown, 1 for a fatal start failure.
+ *
+ * The listeners live in this process, so there is no child to keep alive: a crash of this process is a crash of every routed session's door at once, and recovery is the next launch's ensure spawning a replacement on the same sticky ports, which is exactly the failure model the issue asks to settle with tests. Keeping the headroom daemon alive is the headroom supervisor's job, not this one's; the two daemons idle out independently.
+ */
+export declare function runFrontDoorSupervisor(idleShutdownMinutes: number, ports: FrontDoorSupervisorPorts, options?: RunFrontDoorSupervisorOptions): Promise<number>;
+export {};

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

@@ -0,0 +1,11 @@
+/** An IP address as the 4 or 16 octets an iPAddress GeneralName carries. */
+export declare function ipBytes(address: string): Buffer;
+/** A key pair in the PEM forms agent-shim persists. */
+export interface PemKeyPair {
+    readonly certPem: string;
+    readonly keyPem: string;
+}
+/** Generates a self-signed CA certificate, CA-only by basicConstraints and keyUsage, with a random serial. */
+export declare function issueCaCertificate(commonName: string, notBefore: Readonly<Date>, notAfter: Readonly<Date>): PemKeyPair;
+/** Issues a server-auth leaf under a CA: its own RSA key, the first name as the common name, every name in the subjectAltName (an IP address as an iPAddress entry, because TLS clients match an IP host only against those). */
+export declare function issueLeafCertificate(ca: PemKeyPair, names: readonly string[], notBefore: Readonly<Date>, notAfter: Readonly<Date>): PemKeyPair;

package/dist/types/headroom/ensure.d.ts

@@ -0,0 +1,31 @@
+import { CliError } from "../cliError";
+import type { LayoutPaths } from "../paths";
+import { type HeadroomFs } from "./state";
+/** Raised when the daemon cannot be brought up in time, or reports a fatal `lastError`: a launch that asked for headroom must never silently fall back to a direct connection. */
+export declare class HeadroomStartError extends CliError {
+    constructor(message: string);
+}
+/** Every effect the ensure step performs, injected so it runs against fakes in tests. */
+export interface EnsureHeadroomPorts {
+    readonly fs: HeadroomFs;
+    /** Zombie-aware liveness: a supervisor or daemon that exited without being reaped still answers signal 0 as alive, but will never serve a request or write state, so it must read as dead here (see `realIsProcessRunning`). */
+    readonly isRunning: (pid: number) => boolean;
+    readonly now: () => number;
+    readonly sleep: (ms: number) => void;
+    /** Spawns the detached supervisor process that owns the headroom daemon, returning its pid. */
+    readonly spawnSupervisor: (paths: LayoutPaths) => number;
+}
+/**
+ * Brings the headroom daemon up for this launch, or finds it already running, and registers this launcher pid in its session registry (the fact that keeps the daemon alive and defers drift restarts until this launch is done).
+ *
+ * The exclusive-create start lock decides which of several concurrent launches spawns the one supervisor: its holder spawns and keeps waiting like everyone else, everyone else waits on state.json, and a lock whose holder has died is removed and retried. Readiness is "state names a live supervisor, a live headroom pid, and a port", which the supervisor only writes after its own `/readyz` probe has passed, so polling state alone never mistakes a bound-but-not-ready port for a usable daemon.
+ *
+ * Throws `HeadroomStartError` (naming the daemon log path and any recorded `lastError`) when the daemon is not up within `HEADROOM_START_TIMEOUT_MS`, or when a live supervisor has recorded a fatal error.
+ */
+export declare function ensureHeadroom(params: {
+    readonly paths: LayoutPaths;
+    readonly launcherPid: number;
+    readonly ports: EnsureHeadroomPorts;
+}): {
+    readonly port: number;
+};

package/dist/types/headroom/settings.d.ts

@@ -0,0 +1,13 @@
+import type { HeadroomGlobalConfig } from "../config/schema";
+/** The token-saving settings of the `headroom` config block, without its install and lifecycle fields (`source`, `idleShutdownMinutes`). */
+export type HeadroomSettings = Pick<HeadroomGlobalConfig, "mode" | "targetRatio" | "ccr" | "rolloutChannel" | "interceptToolResults" | "readMaturation">;
+/** Picks the settings out of a headroom config block, leaving unset fields unset. */
+export declare function settingsOf(config: Readonly<HeadroomGlobalConfig>): HeadroomSettings;
+/**
+ * The `headroom proxy` arguments the settings ask for, after the supervisor's own `--host` and `--port`. Only settings that are set produce a flag, so an empty settings object leaves headroom on its own defaults. `ccr: "default"` is headroom's default and likewise adds nothing.
+ */
+export declare function settingsArgs(settings: Readonly<HeadroomSettings>): string[];
+/** The environment the settings add to the daemon's: only the rollout channel, which headroom reads from `HEADROOM_ROLLOUT_CHANNEL` and has no flag for. */
+export declare function settingsEnv(settings: Readonly<HeadroomSettings>): Record<string, string>;
+/** A stable hash of the settings, so drift detection compares one short string against what the running daemon was started with. The same settings hash the same whatever order the config file wrote its keys in. */
+export declare function hashSettings(settings: Readonly<HeadroomSettings>): string;

package/dist/types/headroom/source.d.ts

@@ -0,0 +1,8 @@
+/**
+ * Whether an install spec resolves through a git ref that can move underneath it. A full commit SHA never moves; a branch name, a tag a maintainer can re-point, or no ref at all (the remote's default branch) can, and a rebased, renamed or deleted branch changes or breaks every fresh install. A registry requirement is not a git source.
+ */
+export declare function isMovingGitSource(spec: string): boolean;
+/** The full commit SHA an install spec pins, lowercased, or undefined when the spec is a registry requirement or follows a moving ref. */
+export declare function pinnedGitCommit(spec: string): string | undefined;
+/** The commit an install was built from, read from the text of its `direct_url.json`, or undefined when the file records no VCS commit (a registry install) or is not valid JSON. */
+export declare function parseInstalledCommit(directUrlJson: string): string | undefined;

package/dist/types/headroom/state.d.ts

@@ -0,0 +1,77 @@
+import { z } from "zod";
+import { type Provider } from "../config/schema";
+import type { FarmFs } from "../launcher/ports";
+/** The upstream headroom serves when no provider's base URL claims the request: Claude Code's own API. */
+export declare const HEADROOM_ANTHROPIC_UPSTREAM = "https://api.anthropic.com";
+/**
+ * The headroom supervisor's state.json under `<home>/headroom/`. Every field is optional because the file exists in stages: a fresh supervisor writes only `supervisorPid` before the daemon is up, and a shut-down daemon leaves the file with everything cleared except any `lastError` worth surfacing.
+ */
+export declare const HeadroomStateSchema: z.ZodObject<{
+    supervisorPid: z.ZodOptional<z.ZodNumber>;
+    headroomPid: z.ZodOptional<z.ZodNumber>;
+    port: z.ZodOptional<z.ZodNumber>;
+    lastPort: z.ZodOptional<z.ZodNumber>;
+    version: z.ZodOptional<z.ZodString>;
+    allowlistHash: z.ZodOptional<z.ZodString>;
+    settingsHash: z.ZodOptional<z.ZodString>;
+    installedSource: z.ZodOptional<z.ZodString>;
+    lastError: z.ZodOptional<z.ZodString>;
+}, z.core.$strict>;
+export type HeadroomState = z.infer<typeof HeadroomStateSchema>;
+/** The filesystem operations headroom coordination needs: the same shape as `FarmFs`, injected so every decision over state, sessions, and the start lock runs against an in-memory fake in tests. */
+export type HeadroomFs = Pick<FarmFs, "mkdirp" | "mkdirPrivate" | "readFileUtf8" | "writeFileUtf8" | "writeFilePrivate" | "writeFileExclusive" | "readdir" | "removeRecursive">;
+/**
+ * The record held in one session-registry file. `supervisorPid` names the supervisor whose daemon the launch connected to: several supervisors can be alive at once (a superseded one keeps serving the sessions it already has), and each must judge idle shutdown and drift restarts by its own sessions only, or none would ever retire.
+ */
+declare const HeadroomSessionSchema: z.ZodObject<{
+    pid: z.ZodNumber;
+    startedAt: z.ZodNumber;
+    supervisorPid: z.ZodNumber;
+}, z.core.$strict>;
+export type HeadroomSession = z.infer<typeof HeadroomSessionSchema>;
+/** The exclusive-create start lock's recorded holder. */
+declare const HeadroomLockSchema: z.ZodObject<{
+    pid: z.ZodNumber;
+    at: z.ZodNumber;
+}, z.core.$strict>;
+export type HeadroomLock = z.infer<typeof HeadroomLockSchema>;
+/** Reads state.json, or undefined when absent. A malformed file is treated as absent: the lock-and-spawn flow below overwrites it with a fresh supervisor's state rather than crashing every future launch over one bad write. */
+export declare function readHeadroomState(fs: HeadroomFs, stateFile: string): HeadroomState | undefined;
+/**
+ * Writes state.json atomically (a temporary sibling renamed into place), so a concurrent reader never sees a partial file. A reader treats a malformed file as absent, and a launcher that finds no supervisor in state spawns one, so a torn write read mid-flight started a redundant supervisor and daemon.
+ */
+export declare function writeHeadroomState(fs: HeadroomFs, stateFile: string, state: Readonly<HeadroomState>): void;
+/** The allowlist the daemon is started with: every provider's base URL plus Claude Code's own API, so a session with no provider selected reaches the real Anthropic upstream through the same proxy. */
+export declare function headroomAllowlist(providers: readonly {
+    readonly baseUrl: string;
+}[]): readonly string[];
+/**
+ * The upstreams a set of providers routes to through headroom: every `http` provider's base URL, plus the front door's direct origin once the door has ever served. A provider session routed through headroom is forwarded by the door's hop back through its own direct listener (whatever route serves there, the in-process translator or the pass-through), so headroom must admit that address like any provider's; the direct port is sticky, so its origin stays stable across restarts. Before the front door has ever served there is no address to admit, and the first routed launch starts it before bringing headroom up, so a freshly started headroom daemon already sees it.
+ */
+export declare function headroomUpstreams(providers: readonly Provider[], frontDoorOrigin: string | undefined): readonly {
+    readonly baseUrl: string;
+}[];
+/** A stable hash of an allowlist, so drift detection compares one short string instead of recomputing set equality against a running process it cannot interrogate. */
+export declare function hashAllowlist(allowlist: readonly string[]): string;
+/** Every provider definition under `providersDir`, best-effort: unreadable files are skipped, because the allowlist's job is to open every upstream a launch might use, not to fail a launch over one broken file. */
+export declare function readAllProviders(fs: HeadroomFs, providersDir: string): readonly {
+    name: string;
+    provider: Provider;
+}[];
+/** One live session-registry entry, or undefined when the launcher pid has no file. */
+export declare function readSession(fs: HeadroomFs, sessionsDir: string, pid: number): HeadroomSession | undefined;
+/** Registers this launch in the session registry: the fact the daemon must keep serving, and the fact whose disappearance starts the idle shutdown clock. */
+export declare function writeSession(fs: HeadroomFs, sessionsDir: string, session: Readonly<HeadroomSession>): void;
+/** Removes a launcher's registry entry. Idempotent: an absent entry is not an error, because the supervisor's own pruning may have removed it first. */
+export declare function removeSession(fs: HeadroomFs, sessionsDir: string, pid: number): void;
+/** Every registry entry on disk, unreadable files skipped, sorted by pid: what `headroom status` prints and what the supervisor's idle and drift decisions read. */
+export declare function listSessions(fs: HeadroomFs, sessionsDir: string): readonly HeadroomSession[];
+/** The registry entries recorded against one supervisor: the sessions whose daemon that supervisor is responsible for keeping up. */
+export declare function sessionsForSupervisor(fs: HeadroomFs, sessionsDir: string, supervisorPid: number): readonly HeadroomSession[];
+/**
+ * Removes every registry entry whose pid is no longer running: a launcher that died without releasing its entry must not keep the daemon awake or block a drift restart forever. The predicate must be zombie-aware (see `realIsProcessRunning`): a launcher that exited but was never reaped still answers signal 0 as alive, which would keep its session registered indefinitely.
+ */
+export declare function pruneDeadSessions(fs: HeadroomFs, sessionsDir: string, isRunning: (pid: number) => boolean): readonly number[];
+/** Reads the start lock, or undefined when absent or unreadable. */
+export declare function readStartLock(fs: HeadroomFs, lockFile: string): HeadroomLock | undefined;
+export {};