agent-shim 0.0.0 → 7.0.0

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

@@ -0,0 +1,107 @@
+import { type HeadroomGlobalConfig } from "../config/schema";
+import type { LayoutPaths } from "../paths";
+import { type HeadroomSettings } from "./settings";
+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;
+    /** The token-saving settings (`mode`, `targetRatio`, `ccr`, the rollout channel and its opt-ins), as configured; unset fields leave headroom on its own defaults. */
+    readonly settings: HeadroomSettings;
+}
+/** How the supervisor resolves the configured source against its defaults. */
+export declare function resolveSupervisorConfig(configured: Readonly<HeadroomGlobalConfig>): 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[], settings: Readonly<HeadroomSettings>) => number;
+    /** Reads the headroom config block as it stands on disk now. The supervisor calls it every tick, so a changed `source` or setting is noticed while the daemon runs and applied by the same quiet-registry restart an allowlist change gets. */
+    readonly readConfig: () => HeadroomSupervisorConfig;
+    /** 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;
+    /** The commit the installed headroom was built from, as the install itself records it (`direct_url.json`), or undefined when it was not installed from a git source. */
+    readonly installedCommit: () => string | undefined;
+    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 the daemon, start it, keep it alive (for crash or drift), and stop it 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(initialConfig: 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,21 @@
+/**
+ * The library surface of agent-shim: the pure, port-injected parts other tools can call in-process instead of shelling out to the CLI. Four 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;
+ * - routing: the front door's Remote-Control-preserving, capability-authenticated CONNECT surface and its certificate authority, the front-door supervisor and ensure lifecycle, and the headroom supervisor and ensure lifecycle, each pure over its injected ports;
+ * - the ambient-credential guard;
+ * - the per-identity usage snapshot a statusline or launcher reads: its schema and the reader over an injected filesystem.
+ *
+ * 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 { CONNECT_INTERCEPT_HOST, CONNECT_LIMITS, createLeafCache, ensureCa, forwardableHeaders, generateCa, isInterceptedHost, mintLeaf, parseConnectTarget, realConnectCertStore, realConnectEffects, ROUTED_PATH_PREFIX, servedByPipeline, startConnectServer, type CaMaterial, type ConnectCertStore, type ConnectEffects, type ConnectLimits, type ConnectServerConfig, type ConnectServerHandle, type ConnectTarget, type LeafCert, } from "./frontdoor/connect";
+export { ensureFrontDoor, FrontDoorStartError, type EnsureFrontDoorPorts } from "./frontdoor/ensure";
+export { runFrontDoorSupervisor, type FrontDoorSupervisorPorts, type RunFrontDoorSupervisorOptions } from "./frontdoor/supervisor";
+export { listUsageSnapshots, readUsageSnapshot, snapshotPath, UsageSnapshotError, type UsageReadFs } from "./usage/read";
+export { UsageSnapshotSchema, type UsageSnapshot } from "./usage/schema";
+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. A farm built under the former name carries `LEGACY_FARM_MANIFEST_FILENAME` instead, which is read as a fallback and never carried into the next farm, whose resync writes this name. */
+export declare const FARM_MANIFEST_FILENAME = ".agent-shim-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 `agent-shim 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;
+    /** `~/.agent-shim/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 `agent-shim 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[];

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

@@ -0,0 +1,57 @@
+import type { CredentialTargetVar } from "../config/schema";
+/**
+ * The environment variables that authenticate Claude Code directly from the process environment, ahead of any stored identity credential. If any of these is set, every identity would silently authenticate as the same key/token/backend while it's set — defeating the entire premise of separate identities. Order here is also lookup order: `detectAmbientCredential` reports the first one found.
+ */
+export declare const AMBIENT_CREDENTIAL_VARS: readonly ["ANTHROPIC_API_KEY", "ANTHROPIC_AUTH_TOKEN", "CLAUDE_CODE_OAUTH_TOKEN", "CLAUDE_CODE_USE_BEDROCK", "CLAUDE_CODE_USE_VERTEX", "CLAUDE_CODE_USE_FOUNDRY"];
+export type AmbientCredentialVar = (typeof AMBIENT_CREDENTIAL_VARS)[number];
+/** Which guarded variable was found set, and to what. */
+export interface AmbientCredentialDetection {
+    readonly variable: AmbientCredentialVar;
+}
+/** A credential this launch itself exports to the child: the variable it lands in and its value. */
+export interface InjectedCredential {
+    readonly variable: CredentialTargetVar;
+    readonly token: string;
+}
+/**
+ * Detects whether any of `AMBIENT_CREDENTIAL_VARS` is set to a non-empty value in `env`, returning the first one found in declared order, or undefined when none are set.
+ *
+ * An empty string counts as unset, not set — confirmed load-bearing: one of Joe's real wrapper scripts (`o`, running Claude Code against OpenRouter) does `export ANTHROPIC_API_KEY=""` specifically to *clear* it so `ANTHROPIC_AUTH_TOKEN` takes effect instead, and this must never trip the guard.
+ *
+ * `injected`, when given, is the credential this launch exports for its own identity. Its variable holding exactly that value is not ambient: it is what a agent-shim launch of the same identity left in the environment of the session this one starts from (a `claude @work` run inside a `claude @work` session). The same variable holding any other value still counts.
+ */
+export declare function detectAmbientCredential(env: Readonly<Record<string, string | undefined>>, injected?: InjectedCredential): AmbientCredentialDetection | undefined;
+/**
+ * Builds the exact refusal message: which variable was found, why it matters, and the two ways to opt in (a one-off env var, or a persistent per-identity setting). Mirrors the message documented in the project's README. `identityName` is included in the persistent-opt-in command when known; when no identity has been resolved yet (e.g. the `CLAUDE_CONFIG_DIR`-already-set escape hatch, or no identity resolved at all), a generic `<name>` placeholder is used instead, matching the README's own generic wording.
+ */
+export declare function formatAmbientCredentialGuardMessage(variable: AmbientCredentialVar, identityName?: string): string;
+/** Inputs to the ambient-credential guard evaluation. */
+export interface EvaluateAmbientCredentialGuardParams {
+    readonly env: Readonly<Record<string, string | undefined>>;
+    /** The active identity's own `allowAmbientCredential` setting from its `identity.json`, or false when no identity is known. */
+    readonly allowAmbientCredential: boolean;
+    /** True when `AGENT_SHIM_ALLOW_AMBIENT_CREDENTIAL=1` is set for this one invocation. */
+    readonly allowAmbientCredentialOverride: boolean;
+    /** The active identity's name, for the message's persistent-opt-in command. Undefined when no identity is known. */
+    readonly identityName?: string;
+    /**
+     * True when this launch routes through an API provider. The guard inspects the PARENT environment, before `buildEnv` runs; a provider launch has its `ANTHROPIC_AUTH_TOKEN` injected and its `ANTHROPIC_API_KEY` cleared by `buildEnv` itself, so an ambient credential in the parent environment never reaches the child and there is nothing left for this guard to protect against. Everything else about the guard (including `IdentitySchema.allowAmbientCredential`) is unchanged by this flag.
+     */
+    readonly providerSelected?: boolean;
+    /** The launching identity's own credential, when its credential block resolved: see `detectAmbientCredential`. */
+    readonly injectedCredential?: InjectedCredential;
+}
+/** The result of one guard evaluation: either launch may proceed, or it must be refused with an explanatory message. */
+export type AmbientCredentialGuardResult = {
+    readonly ok: true;
+} | {
+    readonly ok: false;
+    readonly variable: AmbientCredentialVar;
+    readonly message: string;
+};
+/**
+ * Evaluates the ambient-credential guard: refuses unless no guarded variable is set, or the active identity opted in (`allowAmbientCredential: true`), or this one invocation opted in (`AGENT_SHIM_ALLOW_AMBIENT_CREDENTIAL=1`), or a provider takes over the child's credential (see `providerSelected`).
+ *
+ * This guard is about credential isolation, not identity/config-dir selection — it must still run even when the `CLAUDE_CONFIG_DIR`-already-set escape hatch applies (callers pass `allowAmbientCredential: false` and no `identityName` in that case, since there is no active identity to consult).
+ */
+export declare function evaluateAmbientCredentialGuard(params: EvaluateAmbientCredentialGuardParams): AmbientCredentialGuardResult;

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

@@ -0,0 +1,41 @@
+import { CliError } from "../cliError";
+import type { FarmFs } from "./ports";
+/** A held identity lock. Releasing is idempotent and never removes a lock some other process has since taken. */
+export interface IdentityLock {
+    readonly path: string;
+    readonly token: string;
+    readonly release: () => void;
+}
+/** Raised when another process holds the identity's lock and did not release it within the retry budget. */
+export declare class IdentityLockBusyError extends CliError {
+    readonly identity: string;
+    readonly lockPath: string;
+    readonly holderPid: number | undefined;
+    constructor(identity: string, lockPath: string, holderPid: number | undefined);
+}
+/** Everything `acquireIdentityLock` needs, all of it injected so a test never sleeps for real, never reads a real pid table, and never writes outside its own fake filesystem. */
+export interface AcquireIdentityLockParams {
+    readonly identity: string;
+    /** The directory the lock file lives in — `~/.agent-shim/identities`, alongside (never inside) the farm the lock protects, so a farm swap can rename the farm root out from under itself without disturbing the lock. */
+    readonly dir: string;
+    readonly fs: FarmFs;
+    readonly nowMs: () => number;
+    readonly pid: number;
+    /** Answers whether a process is still running, so a lock left behind by a crash is recognised rather than waited out for the full staleness window. Zombie-aware: a holder that exited without being reaped still answers signal 0 as alive, but will never release the lock itself. */
+    readonly isRunning: (pid: number) => boolean;
+    /** Blocks for the given number of milliseconds. Synchronous by necessity: the whole launcher is synchronous, right through to `spawnSync`. */
+    readonly sleep: (ms: number) => void;
+    readonly staleAfterMs?: number;
+    readonly retryDelayMs?: number;
+    readonly maxAttempts?: number;
+}
+/** The path of one identity's lock file. */
+export declare function identityLockPath(dir: string, identity: string): string;
+/**
+ * Takes the per-identity resync lock, held for the whole of a resync and released before the real `claude` binary is spawned.
+ *
+ * Two terminals in two different client directories under one identity is exactly the pattern directory rules exist to support, and it is exactly the pattern that races: both launches resolve their own cascade and both want to rewrite the same identity's farm toward two different states. This serialises them.
+ *
+ * Mutual exclusion rests on one exclusive-create — a read-then-write pair would leave a window where both processes see no lock. A lock whose holder is no longer running, or whose record is older than the staleness window, or whose contents cannot be parsed at all, is removed and retaken: a machine that crashed mid-resync must not need manual cleanup before `claude` works again. A lock genuinely held by a live process is waited on, and only after the full retry budget does this give up — loudly, with the holder's pid, rather than proceeding unsynchronised.
+ */
+export declare function acquireIdentityLock(params: AcquireIdentityLockParams): IdentityLock;

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

@@ -0,0 +1,135 @@
+import type { ConfigFileReader } from "../config/load";
+/**
+ * Filesystem operations the launcher needs, injected so no test in this project ever touches a real filesystem — consistent with the resolver core's own injected-facts approach in `src/resolve/types.ts`.
+ */
+export interface FsPort {
+    /** Reads a file's contents as UTF-8 text, or returns undefined when it does not exist. Used for plain-text files like the persisted active-identity file. */
+    readonly readFileUtf8: (filePath: string) => string | undefined;
+    /** Reads and parses a config file (JSON/YAML/JS via cosmiconfig in the real implementation), returning undefined when it does not exist. Mirrors `src/config/load.ts`'s own injected reader shape so `loadIdentity` can compose directly with `loadConfigFile`. */
+    readonly readConfigFile: ConfigFileReader;
+    /** Lists one directory's immediate child names, or an empty list when it does not exist. Used to name the known providers in an unknown-provider refusal. */
+    readonly readdir: (dir: string) => readonly string[];
+}
+/** What one node of a tree is, as reported by an `lstat` that never follows symlinks. */
+type FarmNodeKind = "dir" | "file" | "symlink";
+/** The subset of stat information the farm builder and the fact builder actually read. */
+export interface FarmStat {
+    readonly kind: FarmNodeKind;
+    readonly mtimeMs: number;
+    readonly sizeBytes: number;
+}
+/**
+ * Every filesystem operation the farm resync performs, injected so the whole of `src/launcher/farm.ts` — symlink creation, materialisation, adoption copies, and the atomic swap itself — runs against an in-memory fake in tests and never against a real `~/.claude` or `~/.agent-shim`.
+ *
+ * `lstat` never follows symlinks: a `~/.claude` that contains a directory symlink escaping the tree (a skills directory linked out to a separate dotfiles repository, say) must be recorded as one symlink entry rather than recursed into, both to keep the fact manifest finite and because the farm links such an entry at `<claudeHome>/<rel>` and lets the OS resolve the remaining hops.
+ */
+export interface FarmFs {
+    /** Stats one path without following symlinks, or returns undefined when nothing is there. */
+    readonly lstat: (path: string) => FarmStat | undefined;
+    /** Lists one directory's immediate child names, or an empty list when it does not exist. */
+    readonly readdir: (path: string) => readonly string[];
+    /** Creates a directory and any missing parents, succeeding silently when it already exists. */
+    readonly mkdirp: (path: string) => void;
+    /** Creates a symbolic link at `linkPath` pointing at `target`. */
+    readonly symlink: (target: string, linkPath: string) => void;
+    /** Renames `from` to `to`. Both are always within one directory tree on one filesystem in this module's own usage, so this is the atomic primitive the farm swap is built on. */
+    readonly rename: (from: string, to: string) => void;
+    /** Removes a path and everything beneath it, succeeding silently when it does not exist. */
+    readonly removeRecursive: (path: string) => void;
+    /** Copies a file, symlink, or whole directory tree from `from` to `to`. */
+    readonly copyRecursive: (from: string, to: string) => void;
+    /** Reads a file's contents as UTF-8 text, or undefined when it does not exist. */
+    readonly readFileUtf8: (path: string) => string | undefined;
+    /** Writes a file's full contents as UTF-8 text, creating or truncating it. */
+    readonly writeFileUtf8: (path: string, contents: string) => void;
+    /** Creates a directory (and any missing parents) readable only by its owner: mode 0700, enforced on the leaf even when it already existed with a wider mode. For a directory holding capabilities another local account must never read. */
+    readonly mkdirPrivate: (path: string) => void;
+    /** Writes a file's full contents as UTF-8 text readable only by its owner (mode 0600), atomically: a temporary sibling is written at that mode and renamed into place, so no reader ever sees a partial file or a wider mode. */
+    readonly writeFilePrivate: (path: string, contents: string) => void;
+    /** Appends UTF-8 text to a file readable only by its owner (mode 0600), creating it at that mode when it is missing and narrowing an existing wider mode. The file is opened in append mode, so the text always lands at the end however the file grew; a reader running at the same moment can still see a trailing partial write. It is the primitive an append-only log with one writer per file is built on. */
+    readonly appendFilePrivate: (path: string, contents: string) => void;
+    /** Creates a file only if it does not already exist, returning false when it does. This is the exclusive-create the identity lock depends on for its mutual exclusion — a read-then-write pair would race. */
+    readonly writeFileExclusive: (path: string, contents: string) => boolean;
+    /** A stable content hash of one file, or undefined when it is missing or is not a regular file. Used only to recognise farm data that has already been adopted into the canonical tree. */
+    readonly hashFile: (path: string) => string | undefined;
+}
+/** The outcome of one `spawnSync` call, mirroring Node's own `SpawnSyncReturns` shape narrowly to what the launcher actually reads. */
+export interface SpawnResult {
+    /** The child's exit code, or null when it was terminated by a signal instead of exiting normally. */
+    readonly status: number | null;
+    /** The signal that terminated the child, or null when it exited normally. */
+    readonly signal: NodeJS.Signals | null;
+    /** Set when the child process could not even be spawned (e.g. the binary does not exist). */
+    readonly error?: Error;
+}
+/** Runs the real `claude` binary synchronously, injected so no test ever spawns a real process. The Node equivalent of the legacy bash tool's `exec` is `spawnSync` with `stdio: "inherit"` followed by propagating the child's own exit code — see `src/launcher/spawn.ts`. */
+export interface SpawnPort {
+    readonly spawnSync: (command: string, args: readonly string[], options: {
+        readonly stdio: "inherit";
+        readonly env: Readonly<Record<string, string | undefined>>;
+    }) => SpawnResult;
+}
+/** The outcome of one synchronous external-command run (distinct from `SpawnPort`, which is specifically for replacing this process with the real `claude` binary — `RunPort` is for auxiliary commands like `git rev-parse` for branch detection, or `security find-generic-password` for the macOS Keychain diagnostic in `check.ts`, whose output this process needs to keep running and read). */
+interface RunResult {
+    readonly status: number | null;
+    readonly stdout: string;
+    readonly stderr: string;
+}
+/** Runs an external command and captures its output, injected so no test ever shells out for real. Not used by this phase's own modules yet — declared here so every later module (branch-conditioned `when` evaluation, `check.ts`'s Keychain lookup) shares one injectable shape rather than each inventing its own. */
+export interface RunPort {
+    readonly run: (command: string, args: readonly string[]) => RunResult;
+}
+/**
+ * The running process itself: its environment, its logical argv, and the ability to terminate with an exit code.
+ *
+ * `argv` is the *logical* CLI arguments only — whatever the user typed after `claude`/`agent-shim`, already stripped of the Node executable path and the script path (`process.argv.slice(2)` in the real implementation). `exit` mirrors `process.exit`'s own `never` return type: a real process never returns from it, and a test fake enforces the same shape by throwing a marker so control flow unwinds the same way in both cases.
+ */
+export interface ProcPort {
+    readonly env: Readonly<Record<string, string | undefined>>;
+    readonly argv: readonly string[];
+    readonly exit: (code: number) => never;
+}
+/** Where the launcher reports what it decided and why — refusals, warnings about an identity that could not be loaded, and (per the "strictly-better than the legacy script" goal) which identity/profile ended up selected. */
+export interface LogPort {
+    readonly info: (message: string) => void;
+    readonly warn: (message: string) => void;
+    readonly error: (message: string) => void;
+}
+/** The running headroom daemon one launch routed through, as `HeadroomPort.ensure` reports it. The front door owns the session's routing; this names the daemon the door's headroom hop forwards to, and the project identity headroom scopes memory to. */
+export interface HeadroomUp {
+    /** The loopback port the headroom daemon listens on: what the door's headroom hop reads live and `HEADROOM_PROXY_URL` names for anything else that wants the daemon. */
+    readonly port: number;
+    /** The project identity headroom scopes memory state to: the git repo root of the launch directory, or the directory itself outside a repository. */
+    readonly projectId: string;
+}
+/**
+ * Everything the launcher needs from the headroom daemon, injected so its daemon-supervision side effects stay behind a port and the launcher's own logic stays pure over it (`src/realPorts.ts` wires the real one; tests wire fakes).
+ *
+ * `ensure` brings the daemon up (spawning the detached supervisor when nothing healthy is running) and registers this launch in its session registry; `release` removes that registration when the spawned `claude` exits.
+ */
+export interface HeadroomPort {
+    readonly ensure: () => HeadroomUp;
+    readonly release: () => void;
+}
+/**
+ * Everything the launcher needs from the front-door daemon, injected like `HeadroomPort`: `ensure` brings the door up (spawning its detached supervisor when nothing authenticated is serving), registers this launch in its session registry and returns both listeners' loopback ports plus the CA bundle the child must trust; `release` removes that registration when the spawned `claude` exits.
+ */
+export interface FrontDoorPort {
+    /** `inheritedExtraCaCerts` is the parent environment's own `NODE_EXTRA_CA_CERTS`, which the returned trust bundle keeps (see `resolveTrustBundle`). */
+    readonly ensure: (inheritedExtraCaCerts: string | undefined) => FrontDoorUp;
+    readonly release: () => void;
+}
+/** The running front door one launch routed through, as `FrontDoorPort.ensure` reports it. */
+export interface FrontDoorUp {
+    /** The loopback port the provider listener serves HTTPS on: the base URL every provider session points at. */
+    readonly port: number;
+    /** The loopback port the CONNECT surface listens on: what an OAuth launch points HTTPS_PROXY at. */
+    readonly connectPort: number;
+    /** The CA bundle every routed child points NODE_EXTRA_CA_CERTS at: agent-shim's CA (which signs both the provider listener's leaf and the CONNECT surface's), plus whatever the parent environment already trusted that way. */
+    readonly trustBundlePath: string;
+    /** Why the trust bundle dropped something the parent environment named, when it did; the launcher logs it. */
+    readonly trustWarning?: string;
+    /** This launch's capability token, injected alongside the session headers and required by the door before it routes anything. */
+    readonly sessionToken: string;
+}
+export {};

package/dist/types/legacy.d.ts

@@ -0,0 +1,24 @@
+/**
+ * Everything agent-shim still honours from its former name, `claude-use`, so an installation, a committed project config or an exported environment written for the old name keeps working. Nothing here is consulted when the current name's equivalent is present: a current name always wins, and the legacy form is only a fallback that `agent-shim doctor` reports so it can be retired.
+ */
+/** Prefix of every environment variable agent-shim reads. */
+export declare const ENV_PREFIX = "AGENT_SHIM_";
+/** The former prefix, still accepted wherever `ENV_PREFIX` is. */
+export declare const LEGACY_ENV_PREFIX = "CLAUDE_USE_";
+/** The state root directory name under the home directory. */
+export declare const HOME_DIRNAME = ".agent-shim";
+/**
+ * The former state root directory name. It is adopted in place rather than moved: macOS Claude Code keys each identity's Keychain login on the exact `CLAUDE_CONFIG_DIR` string (`<root>/identities/<name>`), so relocating the root would sign every identity out.
+ */
+export declare const LEGACY_HOME_DIRNAME = ".claude-use";
+/** Former committed and per-clone portable config file names. */
+export declare const LEGACY_PORTABLE_CONFIG_FILENAME = ".claude-use.json";
+export declare const LEGACY_PORTABLE_LOCAL_CONFIG_FILENAME = ".claude-use.local.json";
+/** The former farm manifest file name, read when a farm built by an older release has no current one. */
+export declare const LEGACY_FARM_MANIFEST_FILENAME = ".claude-use-farm.json";
+/** The former executable name, still installed beside the current one and still dispatched to the same program. */
+export declare const LEGACY_COMMAND_NAME = "claude-use";
+/**
+ * Copies every `CLAUDE_USE_*` variable in `env` to its `AGENT_SHIM_*` name unless that name is already set, mutating `env`. Returns the legacy names that supplied a value, in sorted order. An empty current value counts as set, so exporting `AGENT_SHIM_X=` still overrides a stale `CLAUDE_USE_X`.
+ */
+export declare function aliasLegacyEnv(env: NodeJS.ProcessEnv): string[];