claude-use 4.3.0 → 4.5.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/state.d.ts

@@ -0,0 +1,19 @@
+import { z } from "zod";
+import type { HeadroomFs } from "../headroom/state";
+/**
+ * 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>;
+    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 a routed session's base URL sits under, or undefined before the front door has ever served: what the headroom allowlist must admit for a codex provider routed through headroom, since headroom forwards codex traffic back to this address. */
+export declare function frontDoorOrigin(state: FrontDoorState | undefined): string | undefined;
+export {};

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

@@ -0,0 +1,32 @@
+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, a port, and a MITM port", which the supervisor only writes after its own `/readyz` probe has passed and its proxy is bound, 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;
+    readonly mitmPort: number;
+};

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

@@ -0,0 +1,138 @@
+import type { IncomingHttpHeaders, IncomingMessage, ServerResponse } from "node:http";
+import * as net from "node:net";
+/**
+ * A CONNECT proxy the headroom supervisor runs as a second server in its own process, so an OAuth session can have headroom's compression 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.
+ *
+ * Every CONNECT target is blind-tunnelled byte for byte EXCEPT the intercept host (Claude Code's own API), whose TLS this proxy terminates with a leaf certificate signed by a locally generated CA. On the terminated session, paths headroom serves are forwarded to headroom's existing loopback port over plain HTTP (compression, per-session stats, and upstream auth unchanged; the client's Authorization header passes through untouched), and every other path is piped by this proxy to the real upstream over TLS, so Remote Control's streaming, OAuth refreshes, and unknown endpoints bypass headroom entirely.
+ */
+/** The one CONNECT host whose TLS gets terminated: Claude Code's own API, the upstream headroom compresses. */
+export declare const MITM_INTERCEPT_HOST = "api.anthropic.com";
+/** Paths under this prefix are what headroom serves; everything else on the terminated session goes to the real upstream. */
+export declare const HEADROOM_SERVED_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;
+/** 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 headroom serves. The query string stays part of the path: `/v1/messages?beta=true` is still headroom's. */
+export declare function servedByHeadroom(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. Pure node-forge, no openssl, so the same code works on every platform claude-use ships to. */
+export declare function generateCa(now: Readonly<Date>): CaMaterial;
+/** Mints the TLS leaf for one host, signed by the CA: its own RSA keypair, the host in the SAN, server-auth usage only. */
+export declare function mintLeaf(ca: CaMaterial, host: string, now: Readonly<Date>): LeafCert;
+/** Mints each host's leaf once from the CA and reuses it, because a 2048-bit keypair in pure JS costs seconds 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 MitmCertStore {
+    /** 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-forge 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: MitmCertStore, generate: () => CaMaterial): CaMaterial;
+/** Where one forwarded request goes, and how. Headroom's loopback port is plain HTTP; the real upstream is TLS. */
+interface MitmForwardTarget {
+    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 MitmRequestHandler = (request: IncomingMessage, response: ServerResponse) => void;
+/** A bound loopback listener and how to stop it. */
+interface MitmListenerHandle {
+    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 `realMitmEffects`; the TLS round-trip test uses it with redirected targets.
+ */
+export interface MitmEffects {
+    /** 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<MitmListenerHandle>;
+    /** 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: MitmRequestHandler) => 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: MitmForwardTarget, request: IncomingMessage, response: ServerResponse) => void;
+}
+/** Everything the proxy needs to route, resolved before it starts. */
+export interface MitmServerConfig {
+    /** The CONNECT host whose TLS gets terminated. */
+    readonly interceptHost: string;
+    /**
+     * Headroom's loopback port, read per request rather than captured at start-up: the daemon can crash and restart on a different port while this proxy keeps listening, and headroom-served paths must follow it. While it reads undefined (the restart window), headroom-served paths fail fast with 502 rather than silently bypassing headroom to the real upstream.
+     */
+    readonly headroomPort: () => number | undefined;
+    /** The leaf to terminate `interceptHost` with, minted and cached per host. */
+    readonly leafFor: (host: string) => LeafCert;
+    /** Where non-headroom paths on the terminated session are piped: the real upstream over TLS. */
+    readonly upstream: MitmForwardTarget;
+}
+/** A running MITM proxy. */
+export interface MitmServerHandle {
+    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 MITM proxy: 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 (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), then either blind-tunnel the target or terminate its TLS and parse HTTP on the session. Every effect flows through `effects`; nothing here touches the network or filesystem itself.
+ */
+export declare function startMitmServer(config: MitmServerConfig, effects: MitmEffects, preferredPort: number | undefined): Promise<MitmServerHandle>;
+/** The real `MitmEffects` 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 realMitmEffects(): MitmEffects;
+/** The real `MitmCertStore` 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 realMitmCertStore(paths: {
+    readonly headroomCaDir: string;
+    readonly headroomCaCertFile: string;
+    readonly headroomCaKeyFile: string;
+}): MitmCertStore;
+export {};

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

@@ -0,0 +1,73 @@
+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>;
+    mitmPort: z.ZodOptional<z.ZodNumber>;
+    lastMitmPort: z.ZodOptional<z.ZodNumber>;
+    lastPort: z.ZodOptional<z.ZodNumber>;
+    version: z.ZodOptional<z.ZodString>;
+    allowlistHash: 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" | "readFileUtf8" | "writeFileUtf8" | "writeFileExclusive" | "readdir" | "removeRecursive">;
+/** The record held in one session-registry file. */
+declare const HeadroomSessionSchema: z.ZodObject<{
+    pid: z.ZodNumber;
+    startedAt: 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. A plain write rather than the write-then-rename most config files get: state.json is advisory coordination, read tolerantly (`readHeadroomState` treats a malformed file as absent) and rewritten constantly by the supervisor, and the exclusive-create start lock below, not this file, is the actual mutual exclusion.
+ */
+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 origin when there is a codex provider and the front door has ever served. A codex session routed through headroom is forwarded back to the front door's own listener (the codex translation is one of its routes), so headroom must admit that address like any provider's; the front door's 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 codex 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[];
+/**
+ * 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 {};

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

@@ -0,0 +1,107 @@
+import type { LayoutPaths } from "../paths";
+import type { MitmServerHandle } from "./mitm";
+import { type HeadroomFs } from "./state";
+/** Everything the supervisor needs to run the daemon, resolved from the global config and the filesystem before it starts. */
+export interface HeadroomSupervisorConfig {
+    /** The install spec as configured (`headroom.source`), already defaulted. */
+    readonly source: string;
+    /** `headroom.idleShutdownMinutes`, already defaulted. */
+    readonly idleShutdownMinutes: number;
+}
+/** How the supervisor resolves the configured source against its defaults. */
+export declare function resolveSupervisorConfig(configured: {
+    readonly source?: string;
+    readonly idleShutdownMinutes?: number;
+}): HeadroomSupervisorConfig;
+/**
+ * Every effect the supervisor performs, injected so the whole lifecycle is testable against fakes: no real process, port, clock, or HTTP call ever happens in a unit test.
+ */
+export interface SupervisorPorts {
+    readonly fs: HeadroomFs;
+    readonly paths: LayoutPaths;
+    readonly ownPid: number;
+    readonly now: () => number;
+    /**
+     * Waits `ms`, yielding to the event loop while it does. Deliberately NOT a synchronous Atomics.wait-style sleep: the real supervisor learns of its child's death through the ChildProcess exit event, and a blocking sleep would stop the event loop from ever delivering it (the exact failure that left an unreaped zombie answering liveness checks as alive).
+     */
+    readonly sleep: (ms: number) => Promise<void>;
+    /**
+     * Zombie-aware liveness, and for a daemon this supervisor spawned, exit-event-backed: the implementation keeps the spawned ChildProcess handle, consumes its exit event (which is also what reaps it), and reports the pid as not running from that moment. A bare signal-0 check is not enough, because a defunct process still answers it.
+     */
+    readonly isRunning: (pid: number) => boolean;
+    /** Returns a free loopback port. Async because the only reliable way to reserve one is to bind and release a socket. */
+    readonly freePort: () => Promise<number>;
+    /** Whether nothing is currently listening on one specific loopback port: the check that decides whether the sticky `lastPort` can be reused. The same bind-and-release technique `freePort` uses, applied to a number the caller already cares about. */
+    readonly isPortFree: (port: number) => Promise<boolean>;
+    /**
+     * Starts `headroom proxy` bound to `port` with the given allowlist, returning its pid. Output goes to the daemon log. The implementation must keep the ChildProcess handle and attach an exit listener (detaching the process is fine; unref'ing a child you still need events from is not, since without the listener nothing reaps it and it lingers as a zombie).
+     */
+    readonly spawnHeadroom: (port: number, allowlist: readonly string[]) => number;
+    /** Stops a process the supervisor owns, escalating SIGTERM to SIGKILL on a bounded timeout (see `stopSupervisedProcess`). */
+    readonly stopProcess: (pid: number) => void;
+    /** True once `GET /readyz` on the port succeeds. */
+    readonly ready: (port: number) => Promise<boolean>;
+    /** Runs `uv tool install <spec>`, logging output to the daemon log. Returns ok=false with the error when `uv` is absent or the install fails. */
+    readonly install: (spec: string) => {
+        readonly ok: boolean;
+        readonly error?: string;
+    };
+    /** The installed `headroom --version` output, or undefined when the binary is not on PATH. */
+    readonly headroomVersion: () => string | undefined;
+    /**
+     * Starts this supervisor's second server: the in-process MITM CONNECT proxy on a loopback port, binding `preferredPort` when it is free and any free port otherwise. The proxy forwards the intercept host's headroom-served paths to `headroomPort()` (read live, because the daemon can crash and restart on a different port while the proxy keeps listening) and tunnels everything else untouched. Resolves once listening; rejects when no port can be bound.
+     */
+    readonly startMitm: (preferredPort: number | undefined, headroomPort: () => number | undefined) => Promise<MitmServerHandle>;
+    readonly log: (line: string) => void;
+}
+/** First retry delay after a failed start. Half a second keeps a transient blip invisible to the next launch. */
+export declare const HEADROOM_BACKOFF_BASE_MS = 500;
+/** Ceiling for the retry delay: with no live sessions there is no user waiting, so half a minute between attempts is the most the daemon log should grow. */
+export declare const HEADROOM_BACKOFF_CAP_MS = 30000;
+/** Consecutive failed starts before the supervisor gives up, records `lastError`, and exits: a proxy that cannot come up five times in a row is broken, not unlucky. */
+export declare const HEADROOM_START_RETRY_BUDGET = 5;
+/** The supervisor's own tick rate for crash detection, drift checks, and idle shutdown. */
+export declare const HEADROOM_POLL_MS = 1000;
+/** The process-control primitives the escalating stop needs, injected so the escalation itself is unit-testable against a process that ignores SIGTERM. */
+export interface StopProcessPrimitives {
+    /** Delivers a signal; throws when the target is already gone. */
+    readonly signal: (pid: number, signal: NodeJS.Signals) => void;
+    /** Zombie-aware liveness: a defunct process is not running. */
+    readonly isRunning: (pid: number) => boolean;
+    /** Synchronous wait between liveness polls; blocking is correct here, since nothing productive can happen until the target is gone or the grace expires. */
+    readonly waitMs: (ms: number) => void;
+    readonly now: () => number;
+}
+/** How `stopSupervisedProcess` ended. `still-running` means even SIGKILL did not clear the pid within its grace (an uninterruptible process); callers log it loudly. */
+export type StopOutcome = "exited-on-term" | "killed" | "still-running";
+/** Grace after SIGTERM before escalating to SIGKILL: enough for a proxy to drain an in-flight request, short enough that a restart is not visibly stalled. This proxy's server has been observed to ignore SIGTERM outright, so the escalation is not optional. */
+export declare const TERM_GRACE_MS = 1500;
+/** Grace after SIGKILL before declaring the process unkillable. SIGKILL is immediate at the kernel level; this only bounds the wait for the scheduler to reap it. */
+export declare const KILL_GRACE_MS = 1500;
+/**
+ * Stops a process the supervisor owns: SIGTERM, wait up to `TERM_GRACE_MS`; SIGKILL, wait up to `KILL_GRACE_MS`; then report. Liveness during the waits must be zombie-aware: an unreaped target still answers signal 0, which would read as "survived SIGKILL".
+ */
+export declare function stopSupervisedProcess(pid: number, primitives: StopProcessPrimitives): StopOutcome;
+/** The backoff for attempt `attempt` (1-based): base doubled per failure, capped. */
+export declare function backoffForAttempt(attempt: number): number;
+/**
+ * Whether an installed `headroom --version` string satisfies the configured source. A source carrying a PEP 440 specifier (`headroom>=0.39`, `headroom==0.39.1`) is checked against the version; anything else (a bare git URL, the default) carries no version to check and is satisfied by any install, with drift handled by comparing `installedSource` instead.
+ */
+export declare function versionSatisfies(version: string | undefined, source: string): boolean;
+/** Options for `runSupervisor`. */
+export interface RunSupervisorOptions {
+    /**
+     * Bounds the supervisor loop's iterations. The real supervisor runs until it exits on its own (idle shutdown or fatal error); a bounded run is how tests observe steady-state behaviour (drift deferral, restart-on-crash, pruning) without an infinite loop, and such a run returns `HEADROOM_SUPERVISOR_STILL_RUNNING` instead of an exit code.
+     */
+    readonly tickLimit?: number;
+}
+/** Returned by a tick-bounded `runSupervisor` that reached its limit while still managing the daemon: not an exit code, and never produced without `tickLimit`. */
+export declare const HEADROOM_SUPERVISOR_STILL_RUNNING = -1;
+/**
+ * Runs the headroom supervisor loop: install, bind this process's MITM proxy, start the daemon, keep both alive (the proxy lives in this process, so only the daemon needs restarting, for crash or drift), and shut both down after the configured idle period with an empty session registry. Returns the process exit code (0 for an idle shutdown, 1 for a fatal setup failure).
+ *
+ * Every effect flows through `ports`, so the whole loop is unit-testable with a fake clock, filesystem, and processes. The loop awaits its sleeps, which in the real implementation run on a timer: between ticks the event loop turns, the spawned child's exit event is delivered (and the child thereby reaped), and the next tick's liveness check reads the truth.
+ */
+export declare function runSupervisor(config: HeadroomSupervisorConfig, ports: SupervisorPorts, options?: RunSupervisorOptions): Promise<number>;
+/** The allowlist as it stands right now: every provider's upstream (the front door's origin for a codex provider, which headroom forwards codex traffic back to) plus Claude Code's own API. */
+export declare function currentHeadroomAllowlist(fs: HeadroomFs, paths: LayoutPaths): readonly string[];

package/dist/types/index.d.ts

@@ -0,0 +1,16 @@
+/**
+ * The library surface of claude-use: the pure, port-injected parts other tools can call in-process instead of shelling out to the CLI. Three groups, none of which imports interactive prompting or argument parsing:
+ *
+ * - identity and configuration-profile resolution and farm sync (`resolveDecisions`, `resyncFarm`, `buildEntryFacts`, ...), pure over facts and ports passed in;
+ * - headroom routing: the Remote-Control-preserving MITM CONNECT proxy and its certificate authority, and the supervisor and ensure lifecycle, pure over `SupervisorPorts`;
+ * - the ambient-credential guard.
+ *
+ * Everything the CLI alone needs (commander wiring, prompts, `doctor`, `check`) 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";
+export { buildEntryFacts, carryOver, FARM_MANIFEST_FILENAME, readFarmManifest, recoverFarm, recoveryDiagnostics, resyncFarm, type BuildEntryFactsParams, type CarryOverParams, type CarryOverResult, type RecoverFarmParams, type RecoveryResult, type ResyncFarmParams, type ResyncFarmResult, } from "./launcher/farm";
+export { createLeafCache, ensureCa, forwardableHeaders, generateCa, HEADROOM_SERVED_PATH_PREFIX, isInterceptedHost, MITM_INTERCEPT_HOST, mintLeaf, parseConnectTarget, realMitmCertStore, realMitmEffects, servedByHeadroom, startMitmServer, type CaMaterial, type ConnectTarget, type LeafCert, type MitmCertStore, type MitmEffects, type MitmServerConfig, type MitmServerHandle, } from "./headroom/mitm";
+export { ensureHeadroom, HeadroomStartError, type EnsureHeadroomPorts } from "./headroom/ensure";
+export { resolveSupervisorConfig, runSupervisor, type HeadroomSupervisorConfig, type RunSupervisorOptions, type SupervisorPorts } from "./headroom/supervisor";
+export { AMBIENT_CREDENTIAL_VARS, detectAmbientCredential, evaluateAmbientCredentialGuard, formatAmbientCredentialGuardMessage, type AmbientCredentialDetection, type AmbientCredentialGuardResult, type AmbientCredentialVar, type EvaluateAmbientCredentialGuardParams, type InjectedCredential, } from "./launcher/guard";

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

@@ -0,0 +1,165 @@
+import type { CategoryClassification, CategoryClassificationOverlay } from "../config/schema";
+import { type FarmManifest } from "../resolve/reconcile";
+import { type ResolvedState } from "../resolve/pipeline";
+import type { CascadeInput } from "../resolve/walk";
+import type { Diagnostic, EntryFacts } from "../resolve/types";
+import type { FarmFs } from "./ports";
+/** The manifest file each farm carries at its own root, recording what that resync built. Named distinctly from anything Claude Code itself writes into a config directory. */
+export declare const FARM_MANIFEST_FILENAME = ".claude-use-farm.json";
+/** Reads and validates the manifest at a farm root, or undefined when it is missing, unparseable, or does not validate. */
+export declare function readFarmManifest(fs: FarmFs, farmRoot: string): FarmManifest | undefined;
+/** Everything `buildEntryFacts` needs. Everything except the tree itself is injected, so the fact manifest is reproducible from a fake filesystem, a fake clock, and a fake branch. */
+export interface BuildEntryFactsParams {
+    readonly fs: FarmFs;
+    readonly claudeHome: string;
+    readonly home: string;
+    readonly cwd: string;
+    readonly nowMs: number;
+    readonly env: Readonly<Record<string, string | undefined>>;
+    readonly branch?: string;
+    readonly branchDetached?: boolean;
+}
+/**
+ * Walks the canonical `~/.claude` and builds the `EntryFacts` manifest the pure resolver consumes.
+ *
+ * Two properties matter more than the walk itself. Symlinks are never followed: a directory symlink escaping the tree is one entry, not a subtree, which keeps the walk finite and matches how the farm links such an entry back. And every directory's `latestMtimeMs`/`totalSizeBytes` aggregate over its whole subtree rather than reporting its own inode, because a directory-scoped `newerThan` or `maxSizeBytes` condition asks about the data inside the directory — a directory's own mtime does not move when a file three levels down is rewritten.
+ */
+export declare function buildEntryFacts(params: BuildEntryFactsParams): EntryFacts;
+/** Inputs to `carryOver`. */
+export interface CarryOverParams {
+    readonly fs: FarmFs;
+    /** The superseded farm, already renamed aside. */
+    readonly previousRoot: string;
+    /** The new farm, already swapped into place. */
+    readonly farmRoot: string;
+    /**
+     * When given, a colliding name classified as `runtime` is resolved automatically rather than reported — see `CarryOverResult.autoResolved` for why that is always safe. Optional because a caller with no classification loaded (there is none, today) should get the old, fully-manual behaviour rather than a crash; every real call site passes it.
+     */
+    readonly classification?: {
+        readonly defaults: CategoryClassification;
+        readonly overlay?: CategoryClassificationOverlay;
+    };
+}
+/** What `carryOver` moved, resolved on its own, and could not. */
+export interface CarryOverResult {
+    /** Top-level names moved from the superseded farm into the new one. */
+    readonly carried: readonly string[];
+    /** Top-level names that collided but were resolved automatically because their category is `runtime` — see the doc comment on `carryOver` for why discarding the old copy is always safe here. */
+    readonly autoResolved: readonly string[];
+    /** Top-level names left behind because the new farm has its own entry of that name, and resolving them needs a human — everything that collided but was not classified `runtime`. */
+    readonly collided: readonly string[];
+}
+/**
+ * Moves an identity's own locally-written state out of a superseded farm and into the new one.
+ *
+ * This is what makes a whole-directory swap safe at all. The farm root *is* `CLAUDE_CONFIG_DIR`, so it holds more than symlinks: the identity's own `identity.json`, the credentials file Claude Code writes on Linux and Windows, its `.claude.json`, its daemon and runtime state. None of that is shared, none of it is rebuildable, and a swap that simply replaced the directory would destroy all of it.
+ *
+ * Anything the previous resync built itself is skipped rather than carried: a symlink is a view of the canonical tree with no data of its own, and a directory the manifest records as materialised had its real children adopted into `~/.claude` before the swap ever started. Everything else is real local data and moves across by rename, so a credential file is relocated rather than duplicated — never briefly existing as two copies on disk.
+ *
+ * A name that exists in both is genuinely ambiguous in general — overwriting the new farm's own entry would discard whatever the resync just decided; overwriting the old one would discard data — so by default it is reported rather than resolved here, and the caller keeps the superseded farm on disk in that case.
+ *
+ * One category is not ambiguous, though: `runtime`'s own definition (see `config/categories.default.json`'s category table in the README) is specifically "live per-process or per-machine artifacts" — daemon locks, an MCP auth-needed cache, an update-check result — that make no sense being preserved across a swap at all, let alone fought over. When `classification` is given, a colliding name whose category resolves to `runtime` is discarded from the superseded copy and left exactly as the new farm already has it, with no data ever moved: `keep-new` is not a judgement call for this category, it is what the category already means. This needs only the name's *static* classification, never the resolved shared/not-shared decision for the current directory — a `runtime` entry is disposable whether or not this identity currently chooses to share it, so no cascade resolution is needed to make the call.
+ *
+ * Exported so `launcher/farmResolve.ts` can reuse this exact collision detection (and the same `runtime` auto-resolution) for `claude-use identity resolve-conflicts`'s interactive pass, rather than a second implementation that could drift from this one.
+ */
+export declare function carryOver(params: CarryOverParams): CarryOverResult;
+/** What recovery found and did. */
+export interface RecoveryResult {
+    /** Abandoned scratch trees removed. */
+    readonly removedScratch: readonly string[];
+    /** Set when the farm root was missing and a superseded farm was restored into its place. */
+    readonly restoredFrom?: string;
+    /** Superseded farms whose carry-over was completed and which were then discarded. */
+    readonly completed: readonly string[];
+    /** Top-level names, across every superseded farm processed, resolved automatically because their category is `runtime` — see `carryOver`'s own doc comment for why that needs no human decision. */
+    readonly autoResolved: readonly string[];
+    /** Superseded farms left on disk because they still held colliding data a human still needs to decide. */
+    readonly retained: readonly string[];
+    /** True when recovery changed anything, in which case the farm cannot be assumed to match its own manifest. */
+    readonly recovered: boolean;
+}
+/** Inputs to `recoverFarm`: the lock-taking wrapper around `recoverInterruptedSwap`. */
+export interface RecoverFarmParams {
+    readonly fs: FarmFs;
+    readonly identitiesDir: string;
+    readonly identity: string;
+    readonly now: () => number;
+    readonly lock: ResyncFarmParams["lock"];
+    readonly classification?: {
+        readonly defaults: CategoryClassification;
+        readonly overlay?: CategoryClassificationOverlay;
+    };
+}
+/**
+ * Runs `recoverInterruptedSwap` under the identity's own lock.
+ *
+ * This exists as its own entry point because recovery has to happen *before* the identity's `identity.json` is read, not merely before the farm is rebuilt: that file lives inside the farm root, so a crash between the swap's two renames leaves it sitting in a superseded directory where nothing will find it. Reading the identity first would silently launch with its `defaultConfigProfile` and `allowAmbientCredential` unset — the first of which decides what the farm is about to share.
+ *
+ * `resyncFarm` calls `recoverInterruptedSwap` directly rather than calling this, since it already holds the lock; taking it a second time from the same process would block against itself.
+ */
+export declare function recoverFarm(params: RecoverFarmParams): RecoveryResult;
+/** Inputs to `resyncFarm`. */
+export interface ResyncFarmParams {
+    readonly fs: FarmFs;
+    /** `~/.claude-use/identities` — the farm root's parent, and where the lock, scratch trees, and superseded farms all live. */
+    readonly identitiesDir: string;
+    readonly identity: string;
+    /** The configuration profile this launch resolved to, recorded in the manifest for `claude-use check`. */
+    readonly configProfile?: string;
+    /** The canonical `~/.claude` every farm symlink points back into. */
+    readonly claudeHome: string;
+    readonly home: string;
+    readonly cwd: string;
+    readonly env: Readonly<Record<string, string | undefined>>;
+    readonly branch?: string;
+    readonly branchDetached?: boolean;
+    readonly cascade: CascadeInput;
+    readonly classification: {
+        readonly defaults: CategoryClassification;
+        readonly overlay?: CategoryClassificationOverlay;
+    };
+    /** Reads the current time. Called repeatedly while waiting on the lock, then once more to stamp the build. */
+    readonly now: () => number;
+    /** Distinguishes this resync's scratch and superseded directory names from any other process's. `${pid}.${uuid}` in real use; a fixed string in tests. */
+    readonly uniqueSuffix: string;
+    readonly lock: {
+        readonly pid: number;
+        readonly isRunning: (pid: number) => boolean;
+        readonly sleep: (ms: number) => void;
+        readonly staleAfterMs?: number;
+        readonly retryDelayMs?: number;
+        readonly maxAttempts?: number;
+    };
+}
+/** The outcome of one resync. */
+export interface ResyncFarmResult {
+    readonly farmRoot: string;
+    /** True when the resolved decision already matched what the farm's own manifest recorded, so nothing was written. */
+    readonly noOp: boolean;
+    /** The manifest the farm now carries — the newly written one, or the existing one on a no-op. */
+    readonly manifest: FarmManifest;
+    /** The fully resolved state, including the flattened cascade's launch flags, which the launcher goes on to use. */
+    readonly resolved: ResolvedState;
+    readonly adopted: readonly string[];
+    readonly recovery: RecoveryResult;
+    readonly diagnostics: readonly Diagnostic[];
+    readonly retainedPrevious?: string;
+}
+/**
+ * Brings one identity's farm into line with the cascade resolved for the current directory, and hands back everything the launcher needs to go on and spawn the real binary.
+ *
+ * The order below is fixed and each step depends on the one before it:
+ *
+ * 1. Take the per-identity lock, so two sessions under one identity in two directories cannot rewrite the same farm toward two different states at once.
+ * 2. Finish or undo any swap a previous launch was killed in the middle of, so everything after this point sees a coherent farm.
+ * 3. Read the previous manifest and, guided by it, list the parts of the still-live farm reconciliation is allowed to look at. This step only reads the farm; nothing mutates it.
+ * 4. Adopt anything Claude Code wrote into a materialised directory back into the canonical `~/.claude`.
+ * 5. **Then** build the fact manifest, from a canonical tree that now includes everything step 4 adopted. Building facts before adoption would make newly adopted data invisible to this resync and only visible on the next launch — the single most important ordering constraint in this module.
+ * 6. Resolve the cascade and plan the farm, both of them pure functions over those facts.
+ * 7. If the plan matches what the farm's manifest already records and step 4 adopted nothing, stop: no filesystem write happens at all. Launching repeatedly from the same directory with no configuration change is the overwhelmingly common case and it must stay cheap.
+ * 8. Otherwise build a scratch tree, write its manifest, and swap it into place.
+ * 9. Release the lock — before the real binary is spawned, never held across it.
+ */
+export declare function resyncFarm(params: ResyncFarmParams): ResyncFarmResult;
+/** Turns a recovery result into the one diagnostic worth reporting about it, or nothing when there was nothing to recover. */
+export declare function recoveryDiagnostics(recovery: RecoveryResult, identity: string): Diagnostic[];