claude-use 4.4.0 → 5.0.0

package/dist/types/index.d.ts

@@ -0,0 +1,18 @@
+/**
+ * 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;
+ * - 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.
+ *
+ * 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 { 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[];

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 claude-use 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 `CLAUDE_USE_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 (`CLAUDE_USE_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 — `~/.claude-use/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,133 @@
+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 `~/.claude-use`.
+ *
+ * `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;
+    /** 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`/`claude-use`, 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: claude-use'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/paths.d.ts

@@ -0,0 +1,69 @@
+/**
+ * The resolved set of paths claude-use reads and writes under its own root.
+ *
+ * `root` is always CLAUDE_USE_HOME when that environment variable is set (used by every test in this project, and by any real installation that wants to relocate its state), falling back to `~/.claude-use` only when the variable is unset. Every other field is derived from `root` so there is exactly one place a path can go wrong.
+ */
+export interface LayoutPaths {
+    /** The resolved root directory — CLAUDE_USE_HOME, or ~/.claude-use when unset. */
+    readonly root: string;
+    /** Directory holding one subdirectory per identity (symlink farm + local credentials/daemon state). */
+    readonly identitiesDir: string;
+    /** Directory holding named, reusable configuration profile JSON files. */
+    readonly configProfilesDir: string;
+    /** Directory holding one `<name>.json` provider definition per API provider. */
+    readonly providersDir: string;
+    /** Path to the directory-rules.json file describing directory-scoped identity/profile pins. */
+    readonly directoryRulesFile: string;
+    /** Path to the persisted active-identity file (the identity `claude-use identity use` selected). */
+    readonly activeIdentityFile: string;
+    /** Path to the global config.json (user-global override layer, and default profile/walk-limit settings). */
+    readonly globalConfigFile: string;
+    /** Path to the categories.local.json overlay recording answers to "unclassified entry" prompts. */
+    readonly categoriesLocalFile: string;
+    /** Path to the claude-shim.json marker recording where `claude-use shim enable` last placed a `claude`-named copy of this executable, and how. */
+    readonly claudeShimFile: string;
+    /** Directory holding the headroom daemon's coordination state: state.json, the start lock, and the session registry. */
+    readonly headroomDir: string;
+    /** Path to the headroom supervisor's state.json: pids, port, version, allowlist hash, last error. */
+    readonly headroomStateFile: string;
+    /** Path to the exclusive-create marker guarding "who spawns the supervisor" so concurrent launches start at most one. */
+    readonly headroomLockFile: string;
+    /** Directory holding one `<launcher-pid>.json` session-registry entry per live launch routed through headroom. */
+    readonly headroomSessionsDir: string;
+    /** Directory holding daemon logs (the headroom proxy's stdout/stderr and the supervisor's own output). */
+    readonly logsDir: string;
+    /** Path to the headroom daemon's combined log, appended to by both the supervisor and the proxy it owns. */
+    readonly headroomLogPath: string;
+    /** Directory holding the front-door daemon's coordination state: state.json, the start lock, and the session registry. */
+    readonly frontdoorDir: string;
+    /** Directory holding the front door's certificate authority, which signs both the provider listener's loopback leaf and the CONNECT surface's intercept leaf: ca.pem (public, handed to children through NODE_EXTRA_CA_CERTS) and ca.key (mode 0600). */
+    readonly frontdoorCaDir: string;
+    /** Path to the front door's CA certificate, generated once and stable across restarts so children keep trusting it. */
+    readonly frontdoorCaCertFile: string;
+    /** Path to the front door's CA private key, mode 0600: whoever can read it can impersonate the door to every routed child. */
+    readonly frontdoorCaKeyFile: string;
+    /** Directory of combined CA bundles: a parent environment's own NODE_EXTRA_CA_CERTS file plus the front door's CA, one file per distinct combination, for children that must keep trusting both. */
+    readonly frontdoorCaBundlesDir: string;
+    /** Path to the front door's state.json: its supervisor pid, its port, and the sticky port it last served on. */
+    readonly frontdoorStateFile: string;
+    /** Path to the exclusive-create marker guarding "who spawns the front-door supervisor" so concurrent launches start at most one. */
+    readonly frontdoorLockFile: string;
+    /** Directory holding one `<launcher-pid>.json` session-registry entry per live launch routed through the front door. */
+    readonly frontdoorSessionsDir: string;
+    /** Path to the front door's log: one line per lifecycle event and routed failure, never a token. */
+    readonly frontdoorLogPath: string;
+}
+/**
+ * Resolves the current CLAUDE_USE_HOME root: the environment variable when set to a non-empty string, otherwise `~/.claude-use`. An empty string counts as unset, consistent with how this project treats empty-string environment variables elsewhere (see the ambient-credential guard).
+ */
+export declare function resolveClaudeUseHome(): string;
+/**
+ * Resolves the canonical `~/.claude` directory every farm symlink points back into: `CLAUDE_USE_CLAUDE_HOME` when set to a non-empty string, otherwise `~/.claude`.
+ *
+ * The override exists for the same reason `CLAUDE_USE_HOME` does. Exercising a real resync end to end means building and swapping real directories, and doing that against a real, in-use `~/.claude` to find out whether the code is correct is not an acceptable way to find out. Pointing both variables at throwaway directories makes a full end-to-end run safe.
+ */
+export declare function resolveClaudeHome(): string;
+/** Builds the full LayoutPaths structure from a given root directory. */
+export declare function buildLayoutPaths(root: string): LayoutPaths;
+/** Resolves CLAUDE_USE_HOME and builds the full LayoutPaths structure in one call. */
+export declare function resolveLayoutPaths(): LayoutPaths;

package/dist/types/resolve/conditions.d.ts

@@ -0,0 +1,37 @@
+import { type WhenCondition } from "../config/schema";
+import type { EntryFact } from "./types";
+/** Parses a duration literal like `90d` or `500ms` into milliseconds. Throws on anything the schema's own regex would already have rejected, so a malformed value can never be silently treated as zero. */
+export declare function parseDuration(value: string): number;
+/** True when the value would satisfy the schema's duration regex. */
+export declare function isDuration(value: string): boolean;
+/** Everything a `when` condition can be evaluated against, injected rather than read. */
+export interface ConditionContext {
+    readonly nowMs: number;
+    /** Facts about the specific entry being decided. Absent when evaluating a rule-level condition that has no single entry (a directory rule's own `when`). */
+    readonly fact?: EntryFact;
+    /** The branch checked out at `cwd`, or undefined when `cwd` is not in a repository. */
+    readonly branch?: string;
+    /** True when the repository is in detached-HEAD state, in which case no `branch` condition can match. */
+    readonly branchDetached?: boolean;
+    readonly env: Readonly<Record<string, string | undefined>>;
+}
+/** The result of evaluating one `when` object. */
+export interface WhenEvaluation {
+    readonly passed: boolean;
+    /** Which condition fields were present and evaluated. */
+    readonly checked: readonly string[];
+    /** Which of those fields did not hold. Empty when `passed` is true. */
+    readonly failed: readonly string[];
+}
+/** True when `branch` matches `pattern`. The pattern is glob-capable (`client/*`); a detached HEAD or a non-repository directory never matches. */
+export declare function matchBranch(pattern: string, branch: string | undefined, detached?: boolean): boolean;
+/**
+ * Evaluates a `when` object. Every present field must hold — conditions AND together within one object.
+ *
+ * An absent condition is vacuously true, so `when: {}` passes; `claude-use check` warns about that rather than erroring, since an empty object is more likely a half-finished edit than an intentional statement.
+ *
+ * `newerThan`, `olderThan`, and `maxSizeBytes` read the subtree-aggregated facts (`latestMtimeMs`, `totalSizeBytes`), never the entry's own inode stat: a directory's own mtime does not change when a file three levels beneath it is rewritten, and its own size is a ~4KB inode figure that says nothing about what it contains.
+ */
+export declare function evaluateWhen(when: WhenCondition | undefined, context: ConditionContext): WhenEvaluation;
+/** True when the `when` object is present but empty, which is vacuously true and therefore has no effect. */
+export declare function isVacuousWhen(when: WhenCondition | undefined): boolean;

package/dist/types/resolve/decide.d.ts

@@ -0,0 +1,45 @@
+import { type CategoryName } from "../config/schema";
+import type { CompiledRule, Decision, Diagnostic, EliminatedRule, EntryFact, EntryFacts, FlattenedCascade } from "./types";
+/** Everything phase two needs, all of it injected. */
+export interface DecideParams {
+    readonly flattened: FlattenedCascade;
+    readonly facts: EntryFacts;
+    /** Every top-level `~/.claude` entry name mapped to its category, or to null when nothing recognises it. */
+    readonly classification: ReadonlyMap<string, CategoryName | null>;
+}
+/** A rule chosen by `selectRule`, alongside the candidates eliminated on the way to it. */
+export interface RuleSelection {
+    readonly rule?: CompiledRule;
+    readonly eliminated: readonly EliminatedRule[];
+}
+/**
+ * Picks the winning entries rule for one path.
+ *
+ * Candidates are ranked by `compareSpecificity` and taken in order. A candidate whose `when` condition **fails is eliminated** and resolution continues to the next-most-specific matching rule — it never falls straight through to the category default, and a failed condition never inverts the rule's boolean value, which would not have a coherent meaning anyway. Only when no candidate survives does the caller fall back to the category.
+ */
+export declare function selectRule(relPath: string, flattened: FlattenedCascade, context: {
+    nowMs: number;
+    branch?: string;
+    branchDetached?: boolean;
+    env: Readonly<Record<string, string | undefined>>;
+    fact?: EntryFact;
+}): RuleSelection;
+/**
+ * Resolves one path to a sharing decision, in exactly this order:
+ *
+ * 1. **The secret floor.** If the path's top-level entry classifies as `secret`, the answer is `false` unconditionally. This check sits *above* the entries lookup, not merely at the least-specific end of the cascade, and it fires on the path's **real classification**, never on a lexical reading of the key that matched it — so a glob written under a `runtime/` prefix that happens to reach `.credentials.json` is neutralised exactly like a deliberate `secret/` key would be.
+ * 2. **Unclassified.** A top-level entry nothing recognises is not shared, and is reported rather than silently guessed at.
+ * 3. **Entries rules**, most specific first, with a failing condition eliminating a candidate rather than ending the search.
+ * 4. **The category**: a layer's own toggle if any layer set one, otherwise the shipped default.
+ */
+export declare function resolveEntry(relPath: string, params: DecideParams): {
+    decision: Decision;
+    diagnostics: Diagnostic[];
+};
+/** Every decision the resolver reaches, plus every diagnostic raised along the way (phase-one diagnostics included, and de-duplicated). */
+export interface ResolveAllResult {
+    readonly decisions: ReadonlyMap<string, Decision>;
+    readonly diagnostics: readonly Diagnostic[];
+}
+/** Resolves every entry in the fact manifest. */
+export declare function resolveAll(params: DecideParams): ResolveAllResult;

package/dist/types/resolve/extends.d.ts

@@ -0,0 +1,41 @@
+import type { ConfigProfile } from "../config/schema";
+import type { Diagnostic, Layer, LayerId } from "./types";
+/** One configuration profile as loaded from disk, with its entries key order captured at load time. */
+export interface ProfileSource {
+    readonly name: string;
+    readonly profile: ConfigProfile;
+    readonly entryOrder?: readonly string[];
+    /** Where it was loaded from, for diagnostics. Defaults to the profile name. */
+    readonly filepath?: string;
+}
+/** Loads a profile by name. Injected, so nothing in the resolver reads a file. Returns undefined when no profile of that name exists. */
+export type ProfileLoader = (name: string) => ProfileSource | undefined;
+/** The linearised `extends` chain plus anything that went wrong resolving it. */
+export interface LinearisedProfiles {
+    /** Profile names, base-first: every profile appears exactly once, after everything it extends. */
+    readonly order: readonly string[];
+    readonly diagnostics: readonly Diagnostic[];
+}
+/**
+ * Linearises a profile's `extends` graph into a base-first order.
+ *
+ * The walker keeps **two separate structures**, and the distinction is load-bearing rather than stylistic:
+ *
+ * - `stack` is the current depth-first path. A name already on it means the graph genuinely loops back on itself, which is the only real cycle.
+ * - `visited` is every name already emitted anywhere in the walk. A name already in it is a diamond — two branches sharing a base — and must simply be skipped, not re-emitted.
+ *
+ * Collapsing the two into one shared set produces a silent wrong answer in either direction. Using `stack` alone re-emits a shared base a second time in a diamond, so the base's values get re-applied on top of an intermediate profile that deliberately overrode them — the override silently disappears. Using `visited` alone false-flags every legitimate diamond as a cycle. Neither failure crashes; both just resolve to the wrong configuration.
+ *
+ * Emission is **post-order**: a profile is appended only after everything it extends, so `c extends [a, b]` where both extend `base` linearises to `[base, a, b, c]` — never `[base, a, base, b, c]`.
+ */
+export declare function lineariseProfile(rootName: string, load: ProfileLoader): LinearisedProfiles;
+/**
+ * Turns a profile's `extends` chain into cascade layers, base-first, starting at `startId`.
+ *
+ * A resolved profile is not a separate mechanism from the outer cascade: its chain flattens through the same ordered-layer sequence everything else uses, so a profile's resolved patch is simply one more run of inputs to the same algorithm.
+ */
+export declare function profileLayers(rootName: string, load: ProfileLoader, startId: LayerId): {
+    layers: Layer[];
+    nextId: LayerId;
+    diagnostics: readonly Diagnostic[];
+};