agent-shim 7.13.1 → 7.14.0

package/dist/types/index.d.ts

@@ -1,41 +1,2790 @@
+import { z } from 'zod';
+import { IncomingHttpHeaders, IncomingMessage, ServerResponse } from 'node:http';
+import * as net from 'node:net';
+import { Duplex } from 'node:stream';
+
 /**
- * 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;
- * - the state root's layout (`resolveAgentShimHome`, `resolveLayoutPaths`, `buildLayoutPaths`), which includes adopting an existing `~/.claude-use` in place, and the Zod schema and inferred type of every configuration file (identity, configuration profile, provider, pool, directory rules, global config, credential), so a tool can validate or generate them with the same definitions the CLI uses.
- *
- * Creating and changing identities, configuration profiles, providers, pools and directory rules: the `*Store` modules, which take the state root's `LayoutPaths`, return typed values and throw `CliError` subclasses.
- *
- * - `check` and `doctor` as data: `collectCheckReport` and `collectDoctorReport` read this machine and return the report, and the pure `runCheck` and `runDoctor` take the facts as parameters.
- *
- * - launching: `prepareClaudeLaunch` resolves a launch for a directory on this machine and returns the binary, arguments and environment to spawn (performing the farm resync and daemon registration the child depends on), and `prepareLaunch` does the same over injected ports.
- *
- * Everything the CLI alone needs (commander wiring and prompts) is deliberately not exported here.
- */
-export { resolveDecisions, topLevelNames, type ResolveDecisionsInput, type ResolvedState } from "./resolve/pipeline";
-export type { CompiledRule, Decision, Diagnostic, EliminatedRule, EntryFact, EntryFacts, FlattenedCascade, Layer, LayerId } from "./resolve/types";
-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_INTERCEPT_HOSTS, CONNECT_LIMITS, createLeafCache, ensureCa, forwardableHeaders, generateCa, isInterceptedHost, mintLeaf, parseConnectTarget, realConnectCertStore, 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 { realConnectEffects } from "./frontdoor/connectEffects";
-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";
-export { buildLayoutPaths, resolveAgentShimHome, resolveClaudeHome, resolveLayoutPaths, type LayoutPaths } from "./paths";
-export { CliError, EXIT_FAILURE, EXIT_USAGE, UsageError } from "./cliError";
-export { CategoryClassificationOverlaySchema, CategoryClassificationSchema, CategoryMapSchema, ConfigProfileSchema, CredentialCacheSchema, CredentialSchema, CredentialSourceSchema, DirectoryRuleSchema, DirectoryRulesSchema, EntryValueSchema, GlobalConfigSchema, IdentitySchema, PoolNameSchema, PoolSchema, PortableConfigSchema, ProviderSchema, WhenSchema, type CategoryMap, type ConfigProfile, type Credential, type CredentialSource, type DirectoryRule, type DirectoryRules, type EntryValue, type GlobalConfig, type Identity, type Pool, type PortableConfig, type Provider, type WhenCondition, } from "./config/schema";
-export { addIdentity, IdentityAlreadyExistsError, IdentityNotFoundError, identityExists, InvalidIdentityNameError, isIdentityDirectoryName, listIdentities, readActiveIdentity, readIdentity, removeIdentity, setAllowAmbientCredential, setDefaultConfigProfile, setIdentityCredential, useIdentity, type IdentityCredentialChange, type IdentityListEntry, type IdentityListing, type UnreadableIdentityListEntry, } from "./identityStore";
-export { createProfile, InvalidCategoryNameError, listProfiles, ProfileAlreadyExistsError, ProfileNotFoundError, profileExists, readGlobalConfig, readProfile, removeProfile, setGlobalDefaultProfile, setProfileCategories, setProfileEntries, setProfileLaunchFlags, setProfileMetadata, type ProfileListEntry, } from "./configProfilesStore";
-export { addProvider, describeProviderEndpoint, InvalidProviderNameError, LegacyProviderFileError, listProviders, ProviderAlreadyExistsError, ProviderKindMismatchError, ProviderNotFoundError, providerExists, readProvider, removeProvider, updateProvider, type AddProviderInput, type ProviderListEntry, type UpdateProviderInput, } from "./providersStore";
-export { addPool, PoolNotFoundError, readPools, removePool, requirePool, setPool } from "./poolStore";
-export { addDirectoryRule, DirectoryRuleAlreadyExistsError, DirectoryRuleMissingTargetError, DirectoryRuleNotFoundError, listDirectoryRules, readDirectoryRules, removeDirectoryRule, updateDirectoryRule, writeDirectoryRules, type AddDirectoryRuleOptions, type UpdateDirectoryRuleOptions, } from "./directoryRulesStore";
-export { checkReportHasWarnings, checkReportToJson, collectCheckReport, formatCheckReport, runCheck, type CheckReport, type CollectCheckReportParams, type RunCheckParams, } from "./checkReport";
-export { collectDoctorReport, formatDoctorReport, runDoctor, type CollectDoctorReportParams, type DoctorReport, type RunDoctorParams, } from "./doctorReport";
-export { prepareLaunch, type LaunchPlan, type PrepareLaunchParams } from "./launcher";
-export { LaunchRefusedError, prepareClaudeLaunch, type PrepareClaudeLaunchOptions } from "./launchWiring";
+ * Every category a `~/.claude` entry can be classified into. `secret` is deliberately part of this list — it is a real classification the resolver acts on — but it is NOT part of `CategoryMapSchema`'s shape, because no configuration layer may ever toggle it. See OVERRIDABLE_CATEGORIES.
+ */
+declare const CATEGORY_NAMES: readonly ["secret", "runtime", "history", "knowledge", "settings"];
+type CategoryName = (typeof CATEGORY_NAMES)[number];
+/** The four categories a configuration layer is allowed to toggle. `secret` is absent by design. */
+declare const OVERRIDABLE_CATEGORIES: readonly ["runtime", "history", "knowledge", "settings"];
+type OverridableCategory = (typeof OVERRIDABLE_CATEGORIES)[number];
+/**
+ * The category toggle map's resolved shape — always exactly the four overridable categories, never the `all` pseudo-key `CategoryMapSchema` also accepts on input. Derived directly from `OverridableCategory` rather than `z.infer`red from a schema, since `CategoryMapSchema` itself carries a `.transform()` (whose inferred type follows the transform's *output*, so it can't be used to define its own output type without circularity) and a schema built solely to be `typeof`'d, never actually parsed with, would be dead weight at runtime for no benefit over a plain mapped type.
+ */
+type CategoryMap = Partial<Record<OverridableCategory, boolean>>;
+/**
+ * The category toggle map as written by hand: the four overridable categories, plus `all` as shorthand for "every shareable category at once" (expanded by `expandAllCategoryKey` above). `secret` is omitted from the shape entirely, so `{ "categories": { "secret": true } }` is rejected at parse time rather than relying solely on the resolver's runtime floor check. The closed shape is also what lets the published JSON Schema offer real key-name autocomplete, which an open record type cannot.
+ */
+declare const CategoryMapSchema: z.ZodPipe<z.ZodObject<{
+    all: z.ZodOptional<z.ZodBoolean>;
+    runtime: z.ZodOptional<z.ZodBoolean>;
+    history: z.ZodOptional<z.ZodBoolean>;
+    knowledge: z.ZodOptional<z.ZodBoolean>;
+    settings: z.ZodOptional<z.ZodBoolean>;
+}, z.core.$strict>, z.ZodTransform<Partial<Record<"runtime" | "history" | "knowledge" | "settings", boolean>>, {
+    all?: boolean | undefined;
+    runtime?: boolean | undefined;
+    history?: boolean | undefined;
+    knowledge?: boolean | undefined;
+    settings?: boolean | undefined;
+}>>;
+/**
+ * A conditional guard on an entries value or a whole directory rule. Every field present within one `when` object must hold (AND logic). An empty object is vacuously true — `agent-shim check` warns about it, it is never an error.
+ */
+declare const WhenSchema: z.ZodObject<{
+    newerThan: z.ZodOptional<z.ZodString>;
+    olderThan: z.ZodOptional<z.ZodString>;
+    maxSizeBytes: z.ZodOptional<z.ZodInt>;
+    branch: z.ZodOptional<z.ZodString>;
+    env: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodString>>;
+}, z.core.$strict>;
+type WhenCondition = z.infer<typeof WhenSchema>;
+/** An entries value: a flat boolean, or a boolean guarded by a `when` condition. */
+declare const EntryValueSchema: z.ZodUnion<readonly [z.ZodBoolean, z.ZodObject<{
+    value: z.ZodBoolean;
+    when: z.ZodObject<{
+        newerThan: z.ZodOptional<z.ZodString>;
+        olderThan: z.ZodOptional<z.ZodString>;
+        maxSizeBytes: z.ZodOptional<z.ZodInt>;
+        branch: z.ZodOptional<z.ZodString>;
+        env: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodString>>;
+    }, z.core.$strict>;
+}, z.core.$strict>]>;
+type EntryValue = z.infer<typeof EntryValueSchema>;
+declare const EntriesSchema: z.ZodRecord<z.ZodString, z.ZodUnion<readonly [z.ZodBoolean, z.ZodObject<{
+    value: z.ZodBoolean;
+    when: z.ZodObject<{
+        newerThan: z.ZodOptional<z.ZodString>;
+        olderThan: z.ZodOptional<z.ZodString>;
+        maxSizeBytes: z.ZodOptional<z.ZodInt>;
+        branch: z.ZodOptional<z.ZodString>;
+        env: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodString>>;
+    }, z.core.$strict>;
+}, z.core.$strict>]>>;
+type Entries = z.infer<typeof EntriesSchema>;
+/** Launch flags, resolved through the same cascade as categories and entries. */
+declare const LaunchSchema: z.ZodObject<{
+    skipPermissions: z.ZodOptional<z.ZodBoolean>;
+    remoteControl: z.ZodOptional<z.ZodBoolean>;
+    provider: z.ZodOptional<z.ZodString>;
+    headroom: z.ZodOptional<z.ZodBoolean>;
+    trackUsage: z.ZodOptional<z.ZodBoolean>;
+}, z.core.$strict>;
+type LaunchFlags = z.infer<typeof LaunchSchema>;
+/**
+ * Where a resolved credential lands in the child's environment. `bearer` exports it as `ANTHROPIC_AUTH_TOKEN` (what relays and aggregators expect, and the default), `apiKey` as `ANTHROPIC_API_KEY` (sent as `x-api-key`, what a regular Anthropic API key needs), and `oauthToken` as `CLAUDE_CODE_OAUTH_TOKEN` (a long-lived subscription token from `claude setup-token`). `oauthToken` authenticates a login, not an endpoint, so only an identity may use it; see `PROVIDER_CREDENTIAL_TARGETS`.
+ */
+declare const CREDENTIAL_TARGETS: readonly ["bearer", "apiKey", "oauthToken"];
+type CredentialTarget = (typeof CREDENTIAL_TARGETS)[number];
+/** The targets a provider's credential may use: every target except `oauthToken`, which only an identity can carry. */
+declare const PROVIDER_CREDENTIAL_TARGETS: readonly ["bearer", "apiKey"];
+/** The environment variable each credential target exports the token as. These are also the variables no provider `env` block may set, since agent-shim sets and clears them itself. */
+declare const CREDENTIAL_TARGET_VARS: {
+    readonly bearer: "ANTHROPIC_AUTH_TOKEN";
+    readonly apiKey: "ANTHROPIC_API_KEY";
+    readonly oauthToken: "CLAUDE_CODE_OAUTH_TOKEN";
+};
+type CredentialTargetVar = (typeof CREDENTIAL_TARGET_VARS)[CredentialTarget];
+/**
+ * One place a credential can come from. Each kind is an object with exactly one kind-naming key, so the kinds are told apart by which key is present rather than by a separate tag, and `strictObject` rejects an object naming two.
+ *
+ * - `env`: the NAME of an environment variable in the launching shell, never its value.
+ * - `file`: an absolute or `~`-rooted path to a file holding the token, which must not be readable or writable by group or others (mode 600 or stricter).
+ * - `command`: an argv run at launch whose trimmed stdout is the token, so the credential exists only in the child.
+ * - `op`: a 1Password secret reference, run as `op read <ref>`. A 1Password service account needs nothing here: `OP_SERVICE_ACCOUNT_TOKEN` in the launching environment is inherited by the command.
+ * - `keychain`: a macOS Keychain generic password, run as `security find-generic-password -s <service> [-a <account>] -w`.
+ * - `literal`: a fixed value written in the file itself. It is NOT a place for a secret: it exists for local proxies that accept any placeholder token (a codex-translation proxy, say) and so have no real credential to keep out of committed config. Anything with a real credential must use one of the other kinds.
+ */
+declare const CredentialSourceSchema: z.ZodUnion<readonly [z.ZodObject<{
+    env: z.ZodString;
+}, z.core.$strict>, z.ZodObject<{
+    file: z.ZodString;
+}, z.core.$strict>, z.ZodObject<{
+    interactive: z.ZodOptional<z.ZodBoolean>;
+    timeoutMs: z.ZodOptional<z.ZodInt>;
+    command: z.ZodTuple<[z.ZodString], z.ZodString>;
+}, z.core.$strict>, z.ZodObject<{
+    interactive: z.ZodOptional<z.ZodBoolean>;
+    timeoutMs: z.ZodOptional<z.ZodInt>;
+    op: z.ZodString;
+}, z.core.$strict>, z.ZodObject<{
+    interactive: z.ZodOptional<z.ZodBoolean>;
+    timeoutMs: z.ZodOptional<z.ZodInt>;
+    keychain: z.ZodObject<{
+        service: z.ZodString;
+        account: z.ZodOptional<z.ZodString>;
+    }, z.core.$strict>;
+}, z.core.$strict>, z.ZodObject<{
+    literal: z.ZodString;
+}, z.core.$strict>]>;
+type CredentialSource = z.infer<typeof CredentialSourceSchema>;
+/** Where a cached credential is kept: the macOS login Keychain, or a mode-0600 file under the agent-shim home. */
+declare const CREDENTIAL_CACHE_STORES: readonly ["keychain", "file"];
+type CredentialCacheStore = (typeof CREDENTIAL_CACHE_STORES)[number];
+/**
+ * An optional cache on a credential block: the resolved token is kept for `ttl` (a whole number followed by `s`, `m`, `h` or `d`, for example `12h`) so a launch does not re-run a source that needs a person, such as a desktop-unlocked `op`. With no `ttl` the cached token never expires and is replaced only by `credential warm` or removed by `credential forget`. `store` defaults to the Keychain on macOS and a file elsewhere. A block with no `cache` stores nothing and fetches on every launch.
+ */
+declare const CredentialCacheSchema: z.ZodObject<{
+    ttl: z.ZodOptional<z.ZodString>;
+    store: z.ZodOptional<z.ZodEnum<{
+        file: "file";
+        keychain: "keychain";
+    }>>;
+}, z.core.$strict>;
+type CredentialCache = z.infer<typeof CredentialCacheSchema>;
+/**
+ * The credential block providers and identities share: an ordered list of sources, tried in turn until one yields a non-empty token, and the target that token is exported as. `target` defaults to `bearer`.
+ */
+declare const CredentialSchema: z.ZodObject<{
+    sources: z.ZodArray<z.ZodUnion<readonly [z.ZodObject<{
+        env: z.ZodString;
+    }, z.core.$strict>, z.ZodObject<{
+        file: z.ZodString;
+    }, z.core.$strict>, z.ZodObject<{
+        interactive: z.ZodOptional<z.ZodBoolean>;
+        timeoutMs: z.ZodOptional<z.ZodInt>;
+        command: z.ZodTuple<[z.ZodString], z.ZodString>;
+    }, z.core.$strict>, z.ZodObject<{
+        interactive: z.ZodOptional<z.ZodBoolean>;
+        timeoutMs: z.ZodOptional<z.ZodInt>;
+        op: z.ZodString;
+    }, z.core.$strict>, z.ZodObject<{
+        interactive: z.ZodOptional<z.ZodBoolean>;
+        timeoutMs: z.ZodOptional<z.ZodInt>;
+        keychain: z.ZodObject<{
+            service: z.ZodString;
+            account: z.ZodOptional<z.ZodString>;
+        }, z.core.$strict>;
+    }, z.core.$strict>, z.ZodObject<{
+        literal: z.ZodString;
+    }, z.core.$strict>]>>;
+    target: z.ZodOptional<z.ZodEnum<{
+        bearer: "bearer";
+        apiKey: "apiKey";
+        oauthToken: "oauthToken";
+    }>>;
+    cache: z.ZodOptional<z.ZodObject<{
+        ttl: z.ZodOptional<z.ZodString>;
+        store: z.ZodOptional<z.ZodEnum<{
+            file: "file";
+            keychain: "keychain";
+        }>>;
+    }, z.core.$strict>>;
+}, z.core.$strict>;
+type Credential = z.infer<typeof CredentialSchema>;
+/** The kinds of provider: `http` is an Anthropic Messages endpoint at a fixed `baseUrl` (the default when `kind` is absent), and `codex` is ChatGPT's Codex backend reached through agent-shim's own supervised translation daemon. */
+declare const PROVIDER_KINDS: readonly ["http", "codex"];
+/**
+ * How a codex provider translates Claude Code's requests. Every field is optional and defaults to the shipped mapping (`CODEX_DEFAULT_MODEL`, `CODEX_DEFAULT_TIER_MODELS`, `CODEX_DEFAULT_EFFORT`), so an absent block means the stock behaviour. A requested model that already names a codex model (`gpt-...`) passes through untouched whatever this says.
+ */
+declare const CodexProviderConfigSchema: z.ZodObject<{
+    defaultModel: z.ZodOptional<z.ZodString>;
+    models: z.ZodOptional<z.ZodObject<{
+        fable: z.ZodOptional<z.ZodString>;
+        opus: z.ZodOptional<z.ZodString>;
+        sonnet: z.ZodOptional<z.ZodString>;
+        haiku: z.ZodOptional<z.ZodString>;
+    }, z.core.$strict>>;
+    effort: z.ZodOptional<z.ZodEnum<{
+        none: "none";
+        low: "low";
+        medium: "medium";
+        high: "high";
+    }>>;
+}, z.core.$strict>;
+type CodexProviderConfig = z.infer<typeof CodexProviderConfigSchema>;
+/** Either kind of provider; see `HttpProviderSchema` for the shared fields. */
+declare const ProviderSchema: z.ZodDiscriminatedUnion<[z.ZodObject<{
+    $schema: z.ZodOptional<z.ZodString>;
+    kind: z.ZodOptional<z.ZodLiteral<"http">>;
+    displayName: z.ZodString;
+    baseUrl: z.ZodURL;
+    credential: z.ZodObject<{
+        sources: z.ZodArray<z.ZodUnion<readonly [z.ZodObject<{
+            env: z.ZodString;
+        }, z.core.$strict>, z.ZodObject<{
+            file: z.ZodString;
+        }, z.core.$strict>, z.ZodObject<{
+            interactive: z.ZodOptional<z.ZodBoolean>;
+            timeoutMs: z.ZodOptional<z.ZodInt>;
+            command: z.ZodTuple<[z.ZodString], z.ZodString>;
+        }, z.core.$strict>, z.ZodObject<{
+            interactive: z.ZodOptional<z.ZodBoolean>;
+            timeoutMs: z.ZodOptional<z.ZodInt>;
+            op: z.ZodString;
+        }, z.core.$strict>, z.ZodObject<{
+            interactive: z.ZodOptional<z.ZodBoolean>;
+            timeoutMs: z.ZodOptional<z.ZodInt>;
+            keychain: z.ZodObject<{
+                service: z.ZodString;
+                account: z.ZodOptional<z.ZodString>;
+            }, z.core.$strict>;
+        }, z.core.$strict>, z.ZodObject<{
+            literal: z.ZodString;
+        }, z.core.$strict>]>>;
+        cache: z.ZodOptional<z.ZodObject<{
+            ttl: z.ZodOptional<z.ZodString>;
+            store: z.ZodOptional<z.ZodEnum<{
+                file: "file";
+                keychain: "keychain";
+            }>>;
+        }, z.core.$strict>>;
+        target: z.ZodOptional<z.ZodEnum<{
+            bearer: "bearer";
+            apiKey: "apiKey";
+        }>>;
+    }, z.core.$strict>;
+    env: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodString>>;
+}, z.core.$strict>, z.ZodObject<{
+    $schema: z.ZodOptional<z.ZodString>;
+    kind: z.ZodLiteral<"codex">;
+    displayName: z.ZodString;
+    credential: z.ZodObject<{
+        sources: z.ZodArray<z.ZodUnion<readonly [z.ZodObject<{
+            env: z.ZodString;
+        }, z.core.$strict>, z.ZodObject<{
+            file: z.ZodString;
+        }, z.core.$strict>, z.ZodObject<{
+            interactive: z.ZodOptional<z.ZodBoolean>;
+            timeoutMs: z.ZodOptional<z.ZodInt>;
+            command: z.ZodTuple<[z.ZodString], z.ZodString>;
+        }, z.core.$strict>, z.ZodObject<{
+            interactive: z.ZodOptional<z.ZodBoolean>;
+            timeoutMs: z.ZodOptional<z.ZodInt>;
+            op: z.ZodString;
+        }, z.core.$strict>, z.ZodObject<{
+            interactive: z.ZodOptional<z.ZodBoolean>;
+            timeoutMs: z.ZodOptional<z.ZodInt>;
+            keychain: z.ZodObject<{
+                service: z.ZodString;
+                account: z.ZodOptional<z.ZodString>;
+            }, z.core.$strict>;
+        }, z.core.$strict>, z.ZodObject<{
+            literal: z.ZodString;
+        }, z.core.$strict>]>>;
+        cache: z.ZodOptional<z.ZodObject<{
+            ttl: z.ZodOptional<z.ZodString>;
+            store: z.ZodOptional<z.ZodEnum<{
+                file: "file";
+                keychain: "keychain";
+            }>>;
+        }, z.core.$strict>>;
+        target: z.ZodOptional<z.ZodEnum<{
+            bearer: "bearer";
+            apiKey: "apiKey";
+        }>>;
+    }, z.core.$strict>;
+    env: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodString>>;
+    codex: z.ZodOptional<z.ZodObject<{
+        defaultModel: z.ZodOptional<z.ZodString>;
+        models: z.ZodOptional<z.ZodObject<{
+            fable: z.ZodOptional<z.ZodString>;
+            opus: z.ZodOptional<z.ZodString>;
+            sonnet: z.ZodOptional<z.ZodString>;
+            haiku: z.ZodOptional<z.ZodString>;
+        }, z.core.$strict>>;
+        effort: z.ZodOptional<z.ZodEnum<{
+            none: "none";
+            low: "low";
+            medium: "medium";
+            high: "high";
+        }>>;
+    }, z.core.$strict>>;
+}, z.core.$strict>], "kind">;
+type Provider = z.infer<typeof ProviderSchema>;
+/**
+ * A named, reusable configuration profile at `~/.agent-shim/config-profiles/<name>.json`.
+ *
+ * `extends` is a flat array of other profiles' *names*, deliberately not a self-referential `z.lazy()` schema: nothing in this shape points back at a profile object, so each file validates in isolation and the extends graph is walked at resolve time. That also means Zod cannot detect a circular `extends` definition — the walker in `src/resolve/extends.ts` carries its own cycle guard.
+ */
+declare const ConfigProfileSchema: z.ZodObject<{
+    $schema: z.ZodOptional<z.ZodString>;
+    description: z.ZodOptional<z.ZodString>;
+    extends: z.ZodOptional<z.ZodArray<z.ZodString>>;
+    categories: z.ZodOptional<z.ZodPipe<z.ZodObject<{
+        all: z.ZodOptional<z.ZodBoolean>;
+        runtime: z.ZodOptional<z.ZodBoolean>;
+        history: z.ZodOptional<z.ZodBoolean>;
+        knowledge: z.ZodOptional<z.ZodBoolean>;
+        settings: z.ZodOptional<z.ZodBoolean>;
+    }, z.core.$strict>, z.ZodTransform<Partial<Record<"runtime" | "history" | "knowledge" | "settings", boolean>>, {
+        all?: boolean | undefined;
+        runtime?: boolean | undefined;
+        history?: boolean | undefined;
+        knowledge?: boolean | undefined;
+        settings?: boolean | undefined;
+    }>>>;
+    entries: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodUnion<readonly [z.ZodBoolean, z.ZodObject<{
+        value: z.ZodBoolean;
+        when: z.ZodObject<{
+            newerThan: z.ZodOptional<z.ZodString>;
+            olderThan: z.ZodOptional<z.ZodString>;
+            maxSizeBytes: z.ZodOptional<z.ZodInt>;
+            branch: z.ZodOptional<z.ZodString>;
+            env: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodString>>;
+        }, z.core.$strict>;
+    }, z.core.$strict>]>>>;
+    launch: z.ZodOptional<z.ZodObject<{
+        skipPermissions: z.ZodOptional<z.ZodBoolean>;
+        remoteControl: z.ZodOptional<z.ZodBoolean>;
+        provider: z.ZodOptional<z.ZodString>;
+        headroom: z.ZodOptional<z.ZodBoolean>;
+        trackUsage: z.ZodOptional<z.ZodBoolean>;
+    }, z.core.$strict>>;
+}, z.core.$strict>;
+type ConfigProfile = z.infer<typeof ConfigProfileSchema>;
+/** A pool's own name: the identity alphabet minus `@`, since a pool is never an email address. */
+declare const PoolNameSchema: z.ZodString;
+/** A named, explicit set of identities to choose among at launch. Never implicit: a pool lists its members, so an identity that bills a client is only ever picked when someone put it there. */
+declare const PoolSchema: z.ZodObject<{
+    identities: z.ZodArray<z.ZodString>;
+}, z.core.$strict>;
+type Pool = z.infer<typeof PoolSchema>;
+/** One directory rule in `~/.agent-shim/directory-rules.json`, scoped to an explicit absolute (or `~`-rooted) path. */
+declare const DirectoryRuleSchema: z.ZodObject<{
+    entries: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodUnion<readonly [z.ZodBoolean, z.ZodObject<{
+        value: z.ZodBoolean;
+        when: z.ZodObject<{
+            newerThan: z.ZodOptional<z.ZodString>;
+            olderThan: z.ZodOptional<z.ZodString>;
+            maxSizeBytes: z.ZodOptional<z.ZodInt>;
+            branch: z.ZodOptional<z.ZodString>;
+            env: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodString>>;
+        }, z.core.$strict>;
+    }, z.core.$strict>]>>>;
+    $schema: z.ZodOptional<z.ZodString>;
+    extends: z.ZodOptional<z.ZodArray<z.ZodString>>;
+    categories: z.ZodOptional<z.ZodPipe<z.ZodObject<{
+        all: z.ZodOptional<z.ZodBoolean>;
+        runtime: z.ZodOptional<z.ZodBoolean>;
+        history: z.ZodOptional<z.ZodBoolean>;
+        knowledge: z.ZodOptional<z.ZodBoolean>;
+        settings: z.ZodOptional<z.ZodBoolean>;
+    }, z.core.$strict>, z.ZodTransform<Partial<Record<"runtime" | "history" | "knowledge" | "settings", boolean>>, {
+        all?: boolean | undefined;
+        runtime?: boolean | undefined;
+        history?: boolean | undefined;
+        knowledge?: boolean | undefined;
+        settings?: boolean | undefined;
+    }>>>;
+    launch: z.ZodOptional<z.ZodObject<{
+        skipPermissions: z.ZodOptional<z.ZodBoolean>;
+        remoteControl: z.ZodOptional<z.ZodBoolean>;
+        provider: z.ZodOptional<z.ZodString>;
+        headroom: z.ZodOptional<z.ZodBoolean>;
+        trackUsage: z.ZodOptional<z.ZodBoolean>;
+    }, z.core.$strict>>;
+    path: z.ZodString;
+    configProfile: z.ZodOptional<z.ZodString>;
+    identity: z.ZodOptional<z.ZodString>;
+    when: z.ZodOptional<z.ZodObject<{
+        newerThan: z.ZodOptional<z.ZodString>;
+        olderThan: z.ZodOptional<z.ZodString>;
+        maxSizeBytes: z.ZodOptional<z.ZodInt>;
+        branch: z.ZodOptional<z.ZodString>;
+        env: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodString>>;
+    }, z.core.$strict>>;
+}, z.core.$strict>;
+type DirectoryRule = z.infer<typeof DirectoryRuleSchema>;
+/** The `~/.agent-shim/directory-rules.json` file. */
+declare const DirectoryRulesSchema: z.ZodObject<{
+    $schema: z.ZodOptional<z.ZodString>;
+    rules: z.ZodArray<z.ZodObject<{
+        entries: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodUnion<readonly [z.ZodBoolean, z.ZodObject<{
+            value: z.ZodBoolean;
+            when: z.ZodObject<{
+                newerThan: z.ZodOptional<z.ZodString>;
+                olderThan: z.ZodOptional<z.ZodString>;
+                maxSizeBytes: z.ZodOptional<z.ZodInt>;
+                branch: z.ZodOptional<z.ZodString>;
+                env: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodString>>;
+            }, z.core.$strict>;
+        }, z.core.$strict>]>>>;
+        $schema: z.ZodOptional<z.ZodString>;
+        extends: z.ZodOptional<z.ZodArray<z.ZodString>>;
+        categories: z.ZodOptional<z.ZodPipe<z.ZodObject<{
+            all: z.ZodOptional<z.ZodBoolean>;
+            runtime: z.ZodOptional<z.ZodBoolean>;
+            history: z.ZodOptional<z.ZodBoolean>;
+            knowledge: z.ZodOptional<z.ZodBoolean>;
+            settings: z.ZodOptional<z.ZodBoolean>;
+        }, z.core.$strict>, z.ZodTransform<Partial<Record<"runtime" | "history" | "knowledge" | "settings", boolean>>, {
+            all?: boolean | undefined;
+            runtime?: boolean | undefined;
+            history?: boolean | undefined;
+            knowledge?: boolean | undefined;
+            settings?: boolean | undefined;
+        }>>>;
+        launch: z.ZodOptional<z.ZodObject<{
+            skipPermissions: z.ZodOptional<z.ZodBoolean>;
+            remoteControl: z.ZodOptional<z.ZodBoolean>;
+            provider: z.ZodOptional<z.ZodString>;
+            headroom: z.ZodOptional<z.ZodBoolean>;
+            trackUsage: z.ZodOptional<z.ZodBoolean>;
+        }, z.core.$strict>>;
+        path: z.ZodString;
+        configProfile: z.ZodOptional<z.ZodString>;
+        identity: z.ZodOptional<z.ZodString>;
+        when: z.ZodOptional<z.ZodObject<{
+            newerThan: z.ZodOptional<z.ZodString>;
+            olderThan: z.ZodOptional<z.ZodString>;
+            maxSizeBytes: z.ZodOptional<z.ZodInt>;
+            branch: z.ZodOptional<z.ZodString>;
+            env: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodString>>;
+        }, z.core.$strict>>;
+    }, z.core.$strict>>;
+}, z.core.$strict>;
+type DirectoryRules = z.infer<typeof DirectoryRulesSchema>;
+/**
+ * A committed `.agent-shim.json` (or its gitignored `.agent-shim.local.json` sibling). Structurally a directory rule without the `path` field: its scope is implicit — wherever the file lives, and everything below it — which is exactly what makes it portable across clone locations.
+ */
+declare const PortableConfigSchema: z.ZodObject<{
+    entries: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodUnion<readonly [z.ZodBoolean, z.ZodObject<{
+        value: z.ZodBoolean;
+        when: z.ZodObject<{
+            newerThan: z.ZodOptional<z.ZodString>;
+            olderThan: z.ZodOptional<z.ZodString>;
+            maxSizeBytes: z.ZodOptional<z.ZodInt>;
+            branch: z.ZodOptional<z.ZodString>;
+            env: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodString>>;
+        }, z.core.$strict>;
+    }, z.core.$strict>]>>>;
+    $schema: z.ZodOptional<z.ZodString>;
+    extends: z.ZodOptional<z.ZodArray<z.ZodString>>;
+    categories: z.ZodOptional<z.ZodPipe<z.ZodObject<{
+        all: z.ZodOptional<z.ZodBoolean>;
+        runtime: z.ZodOptional<z.ZodBoolean>;
+        history: z.ZodOptional<z.ZodBoolean>;
+        knowledge: z.ZodOptional<z.ZodBoolean>;
+        settings: z.ZodOptional<z.ZodBoolean>;
+    }, z.core.$strict>, z.ZodTransform<Partial<Record<"runtime" | "history" | "knowledge" | "settings", boolean>>, {
+        all?: boolean | undefined;
+        runtime?: boolean | undefined;
+        history?: boolean | undefined;
+        knowledge?: boolean | undefined;
+        settings?: boolean | undefined;
+    }>>>;
+    launch: z.ZodOptional<z.ZodObject<{
+        skipPermissions: z.ZodOptional<z.ZodBoolean>;
+        remoteControl: z.ZodOptional<z.ZodBoolean>;
+        provider: z.ZodOptional<z.ZodString>;
+        headroom: z.ZodOptional<z.ZodBoolean>;
+        trackUsage: z.ZodOptional<z.ZodBoolean>;
+    }, z.core.$strict>>;
+    configProfile: z.ZodOptional<z.ZodString>;
+    identity: z.ZodOptional<z.ZodString>;
+    when: z.ZodOptional<z.ZodObject<{
+        newerThan: z.ZodOptional<z.ZodString>;
+        olderThan: z.ZodOptional<z.ZodString>;
+        maxSizeBytes: z.ZodOptional<z.ZodInt>;
+        branch: z.ZodOptional<z.ZodString>;
+        env: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodString>>;
+    }, z.core.$strict>>;
+}, z.core.$strict>;
+type PortableConfig = z.infer<typeof PortableConfigSchema>;
+declare const HeadroomGlobalConfigSchema: z.ZodObject<{
+    source: z.ZodOptional<z.ZodString>;
+    idleShutdownMinutes: z.ZodOptional<z.ZodNumber>;
+    mode: z.ZodOptional<z.ZodEnum<{
+        cache: "cache";
+        token: "token";
+    }>>;
+    targetRatio: z.ZodOptional<z.ZodNumber>;
+    ccr: z.ZodOptional<z.ZodEnum<{
+        default: "default";
+        none: "none";
+        lossless: "lossless";
+    }>>;
+    rolloutChannel: z.ZodOptional<z.ZodEnum<{
+        beta: "beta";
+        canary: "canary";
+        dev: "dev";
+    }>>;
+    interceptToolResults: z.ZodOptional<z.ZodBoolean>;
+    readMaturation: z.ZodOptional<z.ZodBoolean>;
+}, z.core.$strict>;
+type HeadroomGlobalConfig = z.infer<typeof HeadroomGlobalConfigSchema>;
+/** The user-global `~/.agent-shim/config.json`. */
+declare const GlobalConfigSchema: z.ZodObject<{
+    $schema: z.ZodOptional<z.ZodString>;
+    defaultConfigProfile: z.ZodOptional<z.ZodString>;
+    walkUpLimit: z.ZodOptional<z.ZodString>;
+    categories: z.ZodOptional<z.ZodPipe<z.ZodObject<{
+        all: z.ZodOptional<z.ZodBoolean>;
+        runtime: z.ZodOptional<z.ZodBoolean>;
+        history: z.ZodOptional<z.ZodBoolean>;
+        knowledge: z.ZodOptional<z.ZodBoolean>;
+        settings: z.ZodOptional<z.ZodBoolean>;
+    }, z.core.$strict>, z.ZodTransform<Partial<Record<"runtime" | "history" | "knowledge" | "settings", boolean>>, {
+        all?: boolean | undefined;
+        runtime?: boolean | undefined;
+        history?: boolean | undefined;
+        knowledge?: boolean | undefined;
+        settings?: boolean | undefined;
+    }>>>;
+    entries: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodUnion<readonly [z.ZodBoolean, z.ZodObject<{
+        value: z.ZodBoolean;
+        when: z.ZodObject<{
+            newerThan: z.ZodOptional<z.ZodString>;
+            olderThan: z.ZodOptional<z.ZodString>;
+            maxSizeBytes: z.ZodOptional<z.ZodInt>;
+            branch: z.ZodOptional<z.ZodString>;
+            env: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodString>>;
+        }, z.core.$strict>;
+    }, z.core.$strict>]>>>;
+    launch: z.ZodOptional<z.ZodObject<{
+        skipPermissions: z.ZodOptional<z.ZodBoolean>;
+        remoteControl: z.ZodOptional<z.ZodBoolean>;
+        provider: z.ZodOptional<z.ZodString>;
+        headroom: z.ZodOptional<z.ZodBoolean>;
+        trackUsage: z.ZodOptional<z.ZodBoolean>;
+    }, z.core.$strict>>;
+    headroom: z.ZodOptional<z.ZodObject<{
+        source: z.ZodOptional<z.ZodString>;
+        idleShutdownMinutes: z.ZodOptional<z.ZodNumber>;
+        mode: z.ZodOptional<z.ZodEnum<{
+            cache: "cache";
+            token: "token";
+        }>>;
+        targetRatio: z.ZodOptional<z.ZodNumber>;
+        ccr: z.ZodOptional<z.ZodEnum<{
+            default: "default";
+            none: "none";
+            lossless: "lossless";
+        }>>;
+        rolloutChannel: z.ZodOptional<z.ZodEnum<{
+            beta: "beta";
+            canary: "canary";
+            dev: "dev";
+        }>>;
+        interceptToolResults: z.ZodOptional<z.ZodBoolean>;
+        readMaturation: z.ZodOptional<z.ZodBoolean>;
+    }, z.core.$strict>>;
+    frontdoor: z.ZodOptional<z.ZodObject<{
+        idleShutdownMinutes: z.ZodOptional<z.ZodNumber>;
+    }, z.core.$strict>>;
+    pools: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodObject<{
+        identities: z.ZodArray<z.ZodString>;
+    }, z.core.$strict>>>;
+}, z.core.$strict>;
+type GlobalConfig = z.infer<typeof GlobalConfigSchema>;
+/**
+ * An identity's own `identity.json`. `credential`, when present, authenticates the identity from a token instead of (or ahead of) its stored login: the launcher resolves it and exports it as its target (typically `oauthToken`, a `claude setup-token` token) in the child's environment only. Without it the identity uses the login stored in its own directory.
+ */
+declare const IdentitySchema: z.ZodObject<{
+    $schema: z.ZodOptional<z.ZodString>;
+    name: z.ZodString;
+    defaultConfigProfile: z.ZodOptional<z.ZodString>;
+    allowAmbientCredential: z.ZodDefault<z.ZodBoolean>;
+    credential: z.ZodOptional<z.ZodObject<{
+        sources: z.ZodArray<z.ZodUnion<readonly [z.ZodObject<{
+            env: z.ZodString;
+        }, z.core.$strict>, z.ZodObject<{
+            file: z.ZodString;
+        }, z.core.$strict>, z.ZodObject<{
+            interactive: z.ZodOptional<z.ZodBoolean>;
+            timeoutMs: z.ZodOptional<z.ZodInt>;
+            command: z.ZodTuple<[z.ZodString], z.ZodString>;
+        }, z.core.$strict>, z.ZodObject<{
+            interactive: z.ZodOptional<z.ZodBoolean>;
+            timeoutMs: z.ZodOptional<z.ZodInt>;
+            op: z.ZodString;
+        }, z.core.$strict>, z.ZodObject<{
+            interactive: z.ZodOptional<z.ZodBoolean>;
+            timeoutMs: z.ZodOptional<z.ZodInt>;
+            keychain: z.ZodObject<{
+                service: z.ZodString;
+                account: z.ZodOptional<z.ZodString>;
+            }, z.core.$strict>;
+        }, z.core.$strict>, z.ZodObject<{
+            literal: z.ZodString;
+        }, z.core.$strict>]>>;
+        target: z.ZodOptional<z.ZodEnum<{
+            bearer: "bearer";
+            apiKey: "apiKey";
+            oauthToken: "oauthToken";
+        }>>;
+        cache: z.ZodOptional<z.ZodObject<{
+            ttl: z.ZodOptional<z.ZodString>;
+            store: z.ZodOptional<z.ZodEnum<{
+                file: "file";
+                keychain: "keychain";
+            }>>;
+        }, z.core.$strict>>;
+    }, z.core.$strict>>;
+}, z.core.$strict>;
+type Identity = z.infer<typeof IdentitySchema>;
+/**
+ * The OTHER "categories" concept, and a different shape from CategoryMapSchema entirely: this maps each category name to the list of literal names and globs whose top-level `~/.claude` entries belong to it. CategoryMapSchema says *whether* a category is shared; this says *which entries are in* a category. Do not conflate them.
+ */
+declare const CategoryClassificationSchema: z.ZodObject<{
+    $schema: z.ZodOptional<z.ZodString>;
+    secret: z.ZodArray<z.ZodString>;
+    runtime: z.ZodArray<z.ZodString>;
+    history: z.ZodArray<z.ZodString>;
+    knowledge: z.ZodArray<z.ZodString>;
+    settings: z.ZodArray<z.ZodString>;
+}, z.core.$strict>;
+type CategoryClassification = z.infer<typeof CategoryClassificationSchema>;
+/** The gitignored `~/.agent-shim/categories.local.json` overlay: any subset of the classification lists, answering "what category is this new entry?" without editing the shipped default map. */
+declare const CategoryClassificationOverlaySchema: z.ZodObject<{
+    $schema: z.ZodOptional<z.ZodString>;
+    secret: z.ZodOptional<z.ZodArray<z.ZodString>>;
+    runtime: z.ZodOptional<z.ZodArray<z.ZodString>>;
+    history: z.ZodOptional<z.ZodArray<z.ZodString>>;
+    knowledge: z.ZodOptional<z.ZodArray<z.ZodString>>;
+    settings: z.ZodOptional<z.ZodArray<z.ZodString>>;
+}, z.core.$strict>;
+type CategoryClassificationOverlay = z.infer<typeof CategoryClassificationOverlaySchema>;
+
+/**
+ * The resolved set of paths agent-shim reads and writes under its own root.
+ *
+ * `root` is always AGENT_SHIM_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 `~/.agent-shim` (or the former `~/.claude-use`, see `resolveAgentShimHome`) only when the variable is unset. Every other field is derived from `root` so there is exactly one place a path can go wrong.
+ */
+interface LayoutPaths {
+    /** The resolved root directory, see `resolveAgentShimHome`. */
+    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 `agent-shim 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 `agent-shim 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;
+    /** Directory holding the usage store, mode 0700: the request log and the per-identity snapshots. Metadata only, never content or credentials. */
+    readonly usageDir: string;
+    /** Directory of the append-only usage log: one `<YYYY-MM-DD>.<writer-pid>.jsonl` segment per writing process per UTC day. */
+    readonly usageLogDir: string;
+    /** Directory of the latest-state snapshots, one `<identity>.json` per identity: the stable file other tools read. */
+    readonly usageSnapshotsDir: string;
+    /** The last identity picked from a pool for each directory, so a conversation stays on the account whose prompt cache is warm. */
+    readonly usagePicksFile: string;
+}
+/**
+ * Resolves the state root: `AGENT_SHIM_HOME` when set to a non-empty string (an empty string counts as unset, consistent with how this project treats empty-string environment variables elsewhere, see the ambient-credential guard), otherwise `~/.agent-shim`, or the former `~/.claude-use` when only that exists.
+ *
+ * The former root is used where it stands, never moved: macOS Claude Code names each identity's Keychain entry after a hash of its exact `CLAUDE_CONFIG_DIR`, so any relocation would sign every identity out. A fresh installation, or one that already has `~/.agent-shim`, uses the current name.
+ */
+declare function resolveAgentShimHome(env?: NodeJS.ProcessEnv, home?: string, isDirectory?: (candidate: string) => boolean): string;
+/**
+ * Resolves the canonical `~/.claude` directory every farm symlink points back into: `AGENT_SHIM_CLAUDE_HOME` when set to a non-empty string, otherwise `~/.claude`.
+ *
+ * The override exists for the same reason `AGENT_SHIM_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.
+ */
+declare function resolveClaudeHome(): string;
+/** Builds the full LayoutPaths structure from a given root directory. */
+declare function buildLayoutPaths(root: string): LayoutPaths;
+/** Resolves AGENT_SHIM_HOME and builds the full LayoutPaths structure in one call. */
+declare function resolveLayoutPaths(): LayoutPaths;
+
+/** Which map a classification pattern came from. A `local` pattern is an answer the user gave to an "unclassified entry" prompt; a `default` pattern is shipped with the tool. */
+type ClassificationSource = "default" | "local";
+/** One compiled classification pattern: which category it assigns, where it came from, and how specific it is. */
+interface ClassificationPattern {
+    readonly pattern: string;
+    readonly category: CategoryName;
+    readonly source: ClassificationSource;
+    /** True when the pattern contains no glob metacharacter, so it can only ever match one literal name. */
+    readonly isExact: boolean;
+    /** Position of the pattern within its own category list, used only as the final deterministic tie-break. */
+    readonly ordinal: number;
+    readonly matches: (name: string) => boolean;
+}
+/** The outcome of classifying a set of real top-level `~/.claude` entry names. */
+interface ClassifyResult {
+    /** Every input name mapped to its category, or to null when nothing in either map recognises it. */
+    readonly classification: ReadonlyMap<string, CategoryName | null>;
+    /** The input names that nothing recognised, in input order. These are the names `agent-shim configure` prompts about. */
+    readonly unclassified: readonly string[];
+    /** For each classified name, the pattern that decided it — used by `agent-shim check` to explain a classification. */
+    readonly decidedBy: ReadonlyMap<string, ClassificationPattern>;
+}
+
+/** A layer's index in the assembled cascade. Strictly ascending in composition order: a higher id was composed later and therefore wins on the comparator's first rank. */
+type LayerId = number;
+/** Where a cascade layer came from. Purely descriptive — precedence is carried by `LayerId`, never by kind. */
+type LayerKind = "global-config" | "config-profile" | "directory-rule" | "portable" | "portable-local" | "cli-override";
+/** One composable layer of the cascade: its own category toggles and entries overrides, plus the entries key order captured at load time. */
+interface Layer {
+    readonly id: LayerId;
+    readonly kind: LayerKind;
+    /** Human-readable origin (a file path, or a profile name) used by `agent-shim check` to explain a decision. */
+    readonly source: string;
+    readonly categories?: CategoryMap;
+    readonly entries?: Entries;
+    /** The entries object's own key insertion order, from `src/config/load.ts`. Falls back to `Object.keys(entries)` when absent. */
+    readonly entryOrder?: readonly string[];
+    readonly launch?: LaunchFlags;
+}
+/** Facts about one entry under `~/.claude`, relative to `~/.claude` itself. */
+interface EntryFact {
+    /** Path relative to `~/.claude`, forward-slash separated, never leading or trailing slash. */
+    readonly relPath: string;
+    readonly isDirectory: boolean;
+    /** True when the entry is itself a symlink (including the relative, tree-escaping symlinks that already exist inside a real `~/.claude`). */
+    readonly isSymlink: boolean;
+    /** The entry's own mtime. */
+    readonly mtimeMs: number;
+    /** The most recent mtime anywhere in this entry's subtree — its own mtime for a plain file. A directory-scoped `newerThan` must read this, never the directory's own inode mtime, which does not change when a file three levels down is rewritten. */
+    readonly latestMtimeMs: number;
+    /** The entry's own size. */
+    readonly sizeBytes: number;
+    /** The recursive total size of this entry's subtree — its own size for a plain file. A directory-scoped `maxSizeBytes` must read this, never the directory's own ~4KB inode size. */
+    readonly totalSizeBytes: number;
+}
+/**
+ * Every fact the resolver needs, injected rather than read. Nothing in `src/resolve/` ever touches a real filesystem, git repository, clock, or environment: something else builds this structure and hands it over, which is what makes the whole resolver unit-testable with fake mtimes, a fake branch, and a fake environment.
+ */
+interface EntryFacts {
+    readonly nowMs: number;
+    /** The real home directory, used to expand `~` in `history/projects/` patterns. */
+    readonly home: string;
+    /** The canonical `~/.claude` directory every relative path in `entries` is relative to. */
+    readonly claudeHome: string;
+    /** The working directory the cascade was resolved for. */
+    readonly cwd: string;
+    /** The git branch checked out at `cwd`, or undefined when `cwd` is not in a repository. */
+    readonly branch?: string;
+    /** True when `cwd`'s repository is in detached-HEAD state, in which case no `branch` condition can match. */
+    readonly branchDetached?: boolean;
+    readonly env: Readonly<Record<string, string | undefined>>;
+    /** Every entry under `~/.claude`, keyed by its path relative to `~/.claude`. Directories appear alongside their descendants. */
+    readonly entries: ReadonlyMap<string, EntryFact>;
+}
+/** A single entries override, compiled into the form the resolver actually matches against. */
+interface CompiledRule {
+    /** The key exactly as written in its source file, for diagnostics. */
+    readonly rawKey: string;
+    /** The category prefix the key declared. Cross-checked against the real classification of every path it matches. */
+    readonly declaredCategory: CategoryName;
+    /** The key with its category prefix stripped and (under `history/projects/`) its path fragment encoded — a pattern over paths relative to `~/.claude`. Two differently-spelled but equivalent keys share one canonical pattern and therefore collapse to one rule. */
+    readonly canonicalPattern: string;
+    readonly value: boolean;
+    readonly when?: WhenCondition;
+    readonly layer: LayerId;
+    /** The key's position within its own layer's entries object, used only by the comparator's final same-layer tie-break. */
+    readonly ordinal: number;
+    /** True when the canonical pattern contains no glob metacharacter. */
+    readonly isExact: boolean;
+    /** The pattern's leading run of literal (non-wildcard) characters. */
+    readonly literalPrefix: string;
+    /** How many `/`-separated segments the canonical pattern has. */
+    readonly segmentCount: number;
+    /** Matches the pattern itself and everything beneath it, so a rule on `skills` covers `skills/commit/SKILL.md`. */
+    readonly matches: (relPath: string) => boolean;
+}
+/** How a decision was reached, for `agent-shim check`'s "which layer decided this" output. */
+type DecisionVia = 
+/** The unconditional pre-cascade floor: the path's real classification is `secret`. */
+"secret-floor"
+/** Nothing in the classification map recognises the path's top-level entry. */
+ | "unclassified"
+/** An entries rule matched and its condition (if any) held. */
+ | "entry-rule"
+/** No entries rule survived; a layer's category toggle decided it. */
+ | "category-override"
+/** No entries rule and no category toggle; the shipped default for the category decided it. */
+ | "category-default";
+/** One entry's resolved sharing decision plus the reasoning behind it. */
+interface Decision {
+    readonly relPath: string;
+    readonly shared: boolean;
+    readonly via: DecisionVia;
+    readonly category: CategoryName | null;
+    /** The winning entries rule, when `via` is "entry-rule". */
+    readonly rule?: CompiledRule;
+    /** Rules that matched but whose `when` condition failed, in descending specificity — each was eliminated and resolution continued to the next candidate. */
+    readonly eliminated?: readonly EliminatedRule[];
+}
+/** A candidate rule that matched the path but was eliminated because its `when` condition did not hold. */
+interface EliminatedRule {
+    readonly rule: CompiledRule;
+    readonly failed: readonly string[];
+}
+/** Every diagnostic the resolver can raise. Codes are stable strings so `agent-shim check` and tests can assert on them. */
+type DiagnosticCode = 
+/** A profile's `extends` graph contains a cycle. */
+"EXTENDS_CYCLE"
+/** An `extends` entry names a profile that does not exist. */
+ | "MISSING_PROFILE"
+/** An entries key was written under the `secret/` prefix. Rejected at compile time — `secret` can never be overridden by any layer. */
+ | "SECRET_ENTRY_KEY"
+/** An entries key under some other prefix matched a path whose real classification is `secret`. Neutralised at resolve time by the floor check. */
+ | "SECRET_PATH_NEUTRALISED"
+/** An entries key's declared category prefix disagrees with the real classification of a path it matched. */
+ | "CATEGORY_PREFIX_MISMATCH"
+/** An entries key is not of the form `<category>/<path>`. The schema rejects these at parse time; this fires only for a layer built in code. */
+ | "MALFORMED_ENTRY_KEY"
+/** An earlier layer's exact key lost to a later layer's glob. Correct per the comparator, but worth surfacing rather than resolving silently. */
+ | "EXACT_ENTRY_OVERRIDDEN_BY_LATER_GLOB"
+/** A `history/projects/` pattern's encoded form could plausibly correspond to more than one real path. */
+ | "AMBIGUOUS_PROJECT_ENCODING"
+/** A `history/projects/` key's path fragment is neither home-rooted nor absolute, so it cannot be encoded. */
+ | "UNROOTED_PROJECT_PATH"
+/** A `~/.claude` entry nothing in the classification map recognises. */
+ | "UNCLASSIFIED_ENTRY"
+/** An empty `when: {}` object, which is vacuously true and therefore has no effect. */
+ | "EMPTY_WHEN"
+/** The previous farm's manifest is missing or unreadable, so reconciliation ran in conservative mode. */
+ | "FARM_MANIFEST_MISSING"
+/** A file Claude Code wrote into a materialised farm directory differs from the canonical copy of the same path. */
+ | "RECONCILE_CONFLICT"
+/** Reconciliation proposed adopting a path whose real classification is `secret`. Refused: the secret floor applies to data moving into `~/.claude` exactly as it applies to data moving out. */
+ | "RECONCILE_SECRET_BLOCKED"
+/** A previous launch was interrupted mid-swap and this launch completed or undid the half-finished work. */
+ | "FARM_SWAP_RECOVERED"
+/** A superseded farm could not be discarded because it still held data the new farm has its own entry for, so it was left on disk for the user to look at. */
+ | "FARM_PREVIOUS_RETAINED";
+/** Severity of a diagnostic. An `error` means a configuration layer asked for something the tool refused to do. */
+type DiagnosticSeverity = "error" | "warning" | "info";
+/** One structured diagnostic. */
+interface Diagnostic {
+    readonly code: DiagnosticCode;
+    readonly severity: DiagnosticSeverity;
+    readonly message: string;
+    /** The config key, profile name, or entry path the diagnostic concerns. */
+    readonly subject?: string;
+    /** The layer that raised it, when the diagnostic is attributable to one. */
+    readonly layer?: LayerId;
+}
+/** The flattened result of cascade phase one. */
+interface FlattenedCascade {
+    /** The last value each overridable category was set to across every layer. Categories no layer touched are absent. */
+    readonly categories: ReadonlyMap<OverridableCategory, boolean>;
+    /** One compiled rule per canonical pattern — later layers having already overwritten earlier ones for identical patterns. */
+    readonly rules: ReadonlyMap<string, CompiledRule>;
+    /** Launch flags, last layer wins per field. */
+    readonly launch: LaunchFlags;
+    readonly diagnostics: readonly Diagnostic[];
+}
+
+/** Every decision the resolver reaches, plus every diagnostic raised along the way (phase-one diagnostics included, and de-duplicated). */
+interface ResolveAllResult {
+    readonly decisions: ReadonlyMap<string, Decision>;
+    readonly diagnostics: readonly Diagnostic[];
+}
+
+/** What the farm should contain at one path. */
+type FarmPlanEntry = 
+/** A single symlink standing in for this whole path — always absolute, always under `claudeHome`. */
+{
+    readonly kind: "link";
+    readonly rel: string;
+    readonly target: string;
+}
+/** A real local directory the farm builds itself, because the decision beneath it is not uniform or because a conditional rule could touch it. */
+ | {
+    readonly kind: "materialise";
+    readonly rel: string;
+    readonly reason: MaterialiseReason;
+}
+/** Nothing at all in the farm for this path. */
+ | {
+    readonly kind: "omit";
+    readonly rel: string;
+};
+/** Why a directory has to be built rather than symlinked. */
+type MaterialiseReason = 
+/** Descendants of this directory resolve to different decisions, so a single symlink cannot express the outcome. */
+"split-decision"
+/** A conditional entries rule could match something under this directory, so the decision has to stay live. */
+ | "conditional-rule";
+/** The full farm plan for one resolved cascade. */
+interface FarmPlan {
+    /** Every planned path, parents before children. */
+    readonly entries: readonly FarmPlanEntry[];
+    /** Directories the farm builds itself, in plan order. Written into the farm manifest so the next resync can tell them apart from directories Claude Code created. */
+    readonly materialised: readonly string[];
+    readonly links: readonly {
+        readonly rel: string;
+        readonly target: string;
+    }[];
+}
+
+/**
+ * Whether the walk that builds entry facts must enter the directory at `dirRel` (relative to `~/.claude`). A directory it does not enter is one entry: nothing recorded below it, because nothing below it can be decided differently from the directory itself.
+ */
+type DescendPolicy = (dirRel: string) => boolean;
+
+/** One configuration profile as loaded from disk, with its entries key order captured at load time. */
+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. */
+type ProfileLoader = (name: string) => ProfileSource | undefined;
+
+/** The up-to-three configuration sources that can apply at one directory level. */
+interface DirectoryLevelSources {
+    readonly dir: string;
+    /** The committed, team-shared `.agent-shim.json` at this level. */
+    readonly portable?: {
+        readonly config: PortableConfig;
+        readonly entryOrder?: readonly string[];
+        readonly filepath: string;
+    };
+    /** Every rule in this user's own `~/.agent-shim/directory-rules.json` whose path is exactly this level, in file order. */
+    readonly rules?: readonly {
+        readonly rule: DirectoryRule;
+        readonly entryOrder?: readonly string[];
+        readonly filepath: string;
+    }[];
+    /** The gitignored `.agent-shim.local.json` at this level. */
+    readonly portableLocal?: {
+        readonly config: PortableConfig;
+        readonly entryOrder?: readonly string[];
+        readonly filepath: string;
+    };
+}
+/** Everything needed to assemble the full ordered layer sequence, all of it already loaded by the caller. */
+interface CascadeInput {
+    readonly home: string;
+    /** The user-global `~/.agent-shim/config.json`, the least-specific layer above the shipped defaults. */
+    readonly globalConfig?: {
+        readonly config: GlobalConfig;
+        readonly entryOrder?: readonly string[];
+        readonly filepath: string;
+    };
+    /** The configuration profile chosen by the caller's own precedence rules: explicit flag, then the active identity's default, then the global default. */
+    readonly baseConfigProfile?: string;
+    readonly loadProfile: ProfileLoader;
+    /** Directory levels, shallowest-first, as produced by `walkDirectoryAncestors`. */
+    readonly levels?: readonly DirectoryLevelSources[];
+    /** One-off overrides from the command line or environment, composed last so they beat everything. */
+    readonly cliOverride?: {
+        readonly categories?: Layer["categories"];
+        readonly entries?: Layer["entries"];
+        readonly entryOrder?: readonly string[];
+        readonly launch?: Layer["launch"];
+    };
+}
+/** The assembled cascade: an ordered layer sequence plus what the walk itself decided. */
+interface AssembledCascade {
+    readonly layers: readonly Layer[];
+    readonly diagnostics: readonly Diagnostic[];
+    /** The deepest directory-level `identity` pin encountered, which the launcher uses as a safety net beneath an explicit `@name`. */
+    readonly identityPin?: string;
+    /** The deepest directory-level `configProfile` selection encountered, which is what `agent-shim configure` treats as the active profile for a path. */
+    readonly directoryConfigProfile?: string;
+}
+
+/** Everything one launch needs resolved, in one call. */
+interface ResolveDecisionsInput {
+    readonly facts: EntryFacts;
+    readonly cascade: CascadeInput;
+    readonly classification: {
+        readonly defaults: CategoryClassification;
+        readonly overlay?: CategoryClassificationOverlay;
+    };
+}
+/** The fully resolved state of one launch: the layers that composed it, every entry's decision, the farm layout, and everything worth reporting. */
+interface ResolvedState {
+    readonly assembled: AssembledCascade;
+    readonly flattened: FlattenedCascade;
+    readonly classification: ClassifyResult;
+    readonly decisions: ResolveAllResult["decisions"];
+    readonly farm: FarmPlan;
+    readonly diagnostics: readonly Diagnostic[];
+}
+/** The top-level `~/.claude` entry names present in a fact manifest, in sorted order. */
+declare function topLevelNames(facts: EntryFacts): string[];
+/**
+ * Runs the whole pipeline for one launch: assemble the ordered layer sequence, flatten it, classify the real `~/.claude` entries, decide every path, and plan the resulting farm.
+ */
+declare function resolveDecisions(input: ResolveDecisionsInput): ResolvedState;
+
+/** The manifest the farm builder writes into each scratch tree before the atomic swap. */
+interface FarmManifest {
+    readonly version: 1;
+    readonly builtAtMs: number;
+    readonly identity: string;
+    readonly configProfile?: string;
+    readonly cwd: string;
+    readonly claudeHome: string;
+    /** Directories the previous resync built itself. Without this list, a directory the farm materialised and a directory Claude Code created are indistinguishable on disk — both are real, both contain real children. */
+    readonly materialised: readonly string[];
+    readonly links: readonly {
+        readonly rel: string;
+        readonly target: string;
+    }[];
+}
+
+/** Exit status for every expected failure that is not a usage error: a missing identity, an invalid config file, a refused launch. */
+declare const EXIT_FAILURE = 1;
+/** Exit status for a usage error: an unknown command or option, a malformed flag value, or required input missing with no terminal to prompt on. */
+declare const EXIT_USAGE = 2;
+/**
+ * Base class for every error this CLI throws to represent an expected, user-facing failure: bad input, a missing identity/profile/rule, a malformed config file. `reportFatalError` prints this class as `agent-shim: <message>` with no stack trace and exits with `exitCode`; anything that does not extend it is an unexpected bug, reported by message alone unless `AGENT_SHIM_DEBUG` asks for the stack.
+ */
+declare abstract class CliError extends Error {
+    /** The process exit status this failure maps to. `EXIT_FAILURE` unless a subclass says otherwise. */
+    readonly exitCode: number;
+}
+/** A usage error: the command line itself is wrong or incomplete. Exits `EXIT_USAGE`. */
+declare class UsageError extends CliError {
+    readonly exitCode: number;
+    constructor(message: string);
+}
+
+/** Injected reader for a single config file, so tests never touch a real filesystem. Returns undefined when the file does not exist. */
+type ConfigFileReader = (filepath: string) => unknown;
+
+/**
+ * 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`.
+ */
+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. */
+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.
+ */
+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 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. */
+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.
+ */
+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. */
+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. */
+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.
+ */
+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.
+ */
+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. */
+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;
+}
+
+/** 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. */
+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. */
+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. */
+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;
+    /** Which directories the walk enters; see `descendPolicy`. A directory not entered is recorded as one entry with its own size and mtime only, so a caller that needs subtree aggregates passes a policy that enters everything. */
+    readonly descend: DescendPolicy;
+}
+/**
+ * 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.
+ */
+declare function buildEntryFacts(params: BuildEntryFactsParams): EntryFacts;
+/** Inputs to `carryOver`. */
+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. */
+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.
+ */
+declare function carryOver(params: CarryOverParams): CarryOverResult;
+/** What recovery found and did. */
+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`. */
+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.
+ */
+declare function recoverFarm(params: RecoverFarmParams): RecoveryResult;
+/** Inputs to `resyncFarm`. */
+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. */
+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.
+ */
+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. */
+declare function recoveryDiagnostics(recovery: RecoveryResult, identity: string): Diagnostic[];
+
+/** The request facts a capture sees, shaped so both a real `IncomingMessage` and a test's plain object satisfy it. */
+interface CapturedRequestShape {
+    readonly method?: string;
+    readonly url?: string;
+    readonly headers: IncomingHttpHeaders;
+}
+/** The callbacks one piped request's forwarding drives, all optional callers except, so a fake or a partial observer fits the same seam. */
+interface PassthroughObserver {
+    readonly onRequestChunk: (chunk: Buffer) => void;
+    readonly onResponse: (status: number, headers: IncomingHttpHeaders) => void;
+    readonly onResponseChunk: (chunk: Buffer) => void;
+    readonly onEnd: () => void;
+}
+/** The direction one tapped byte chunk flowed, named from the session's point of view. */
+type StreamDirection = "client-to-server" | "server-to-client";
+/** The byte-level tap for one terminated stream whose protocol the surface does not parse: every chunk both directions, then the end. */
+interface StreamTap {
+    readonly onChunk: (direction: StreamDirection, chunk: Readonly<Buffer>) => void;
+    readonly onEnd: () => void;
+}
+/** The tap the connect surface drives. `undefined` everywhere means "not capturing"; one object covers the whole door process. */
+interface ConnectCapture {
+    /** Opens the byte-level tap for one host's terminated stream, whose chunks are recorded verbatim (text, or base64 when not valid UTF-8) under the same caps as piped bodies. Optional because a capture can be stream-silent by construction. */
+    readonly tapStream?: (host: string) => StreamTap;
+    /** Records one authenticated CONNECT target: the host and port only, since a blind tunnel's bytes are unreadable by construction. */
+    readonly connect: (target: {
+        readonly host: string;
+        readonly port: number;
+    }, intercepted: boolean) => void;
+    /** Records one non-routed request's head and returns the observer its forwarding drives, so the capture correlates every later chunk with the request it belongs to. */
+    readonly observePassthrough: (request: CapturedRequestShape) => PassthroughObserver;
+    /** Records one HTTP upgrade request arriving on a terminated session. The surface destroys the socket afterwards either way, with or without a capture, matching Node's own no-listener behaviour exactly. */
+    readonly upgrade: (request: CapturedRequestShape) => void;
+}
+
+/**
+ * The front door's CONNECT surface, so an OAuth session can have agent-shim's routing AND Claude Code's Remote Control at once: Remote Control refuses any `ANTHROPIC_BASE_URL` other than the real API, but happily honours `HTTPS_PROXY`, so OAuth launches route at the proxy layer instead.
+ *
+ * Nothing is tunnelled or intercepted for a client that has not authenticated: every CONNECT request must present a live launch's capability as its proxy credential (`Proxy-Authorization: Basic`, which clients derive from the credential in the `HTTPS_PROXY` URL the launcher sets), or it is answered 407 before any target is dialled, so the port is no open proxy for other local processes. Pending and authenticated connections are bounded by `ConnectLimits`.
+ *
+ * Every authenticated CONNECT target is blind-tunnelled byte for byte EXCEPT the intercept hosts (Claude Code's own API and the claude.ai control plane), whose TLS this surface terminates with leaf certificates signed by a locally generated CA. On the API host's terminated session, the paths the front door routes (`/v1/`) are handed to the same ordered pipeline the provider listener serves (the client's Authorization header passes through untouched), and every other path there, and every path on the control plane's session, is piped by this surface to that session's own real upstream over TLS, so Remote Control's streaming, OAuth refreshes, and unknown endpoints bypass the pipeline entirely. When a `capture` is configured, those piped exchanges and every CONNECT target are recorded through it (see `./capture.ts`); the forwarding itself is identical either way.
+ */
+/** The API host: Claude Code's own upstream, the one host whose `/v1/` paths the routed pipeline serves. */
+declare const CONNECT_INTERCEPT_HOST = "api.anthropic.com";
+/**
+ * Every CONNECT host whose TLS this surface terminates, each with its own leaf and its own HTTP parser: the API host above, and `platform.claude.com`, the claude.ai control plane where Remote Control's long-lived channel and its handshake live. Terminating the second one is what makes a Remote Control login rejection observable at all: its bytes cross this surface either way, and blind-tunnelling them hides exactly the exchange that failed. Only the API host's `/v1/` paths ever reach the routed pipeline; everything else on either session is piped to that session's own real upstream, so the pipeline's identification and authorisation are never asked to serve another host's traffic.
+ */
+declare const CONNECT_INTERCEPT_HOSTS: readonly string[];
+/** Paths under this prefix are what the routed pipeline serves; everything else on the terminated session goes to the real upstream. */
+declare const ROUTED_PATH_PREFIX = "/v1/";
+/**
+ * The surface's connection deadlines and caps. Production passes `CONNECT_LIMITS`; tests pass small values so a deadline or a cap is reached in milliseconds.
+ *
+ * A connection is pending from accept until its CONNECT head has arrived, and authenticated once that head presented a live launch's capability. Pending connections are bounded twice, by `headDeadlineMs` and by `maxPendingHeads` (reaching the cap evicts the oldest pending connection rather than refusing the newest, so a squatter holding open half-sent heads cannot lock live launches out: a real client's head arrives in its first segment and is authenticated long before that many newer connections could push it out). Authenticated connections are bounded by `maxTunnels` and revoked when their launch ends; they have no idle timeout (see `CONNECT_LIMITS`).
+ */
+interface ConnectLimits {
+    /** How long a connection may take to deliver its whole CONNECT head before it is answered 408 and closed. */
+    readonly headDeadlineMs: number;
+    /** How many connections may be waiting for their head at once; one more evicts the oldest. */
+    readonly maxPendingHeads: number;
+    /** How many authenticated connections (blind tunnels and terminated sessions together) may be open at once; one more is answered 503 and closed. */
+    readonly maxTunnels: number;
+    /** How often every authenticated connection's capability is re-checked, closing the connections of any launch that has since ended. */
+    readonly revalidateMs: number;
+}
+/**
+ * The production limits, each derived from what the surface's real clients do.
+ *
+ * `headDeadlineMs`: every client checked (Claude Code, curl, Node's own proxy support, Python's urllib) sends its whole CONNECT head, credential included, the moment the TCP connection opens, without waiting for anything from the proxy, so on loopback the head arrives within milliseconds. The deadline only has to outlast a door process stalled by a loaded machine, and ten seconds is three orders of magnitude above any such stall while still ending a slowloris connection quickly.
+ *
+ * `maxPendingHeads`: since a real head arrives in the first segment, the pending set at any instant holds only connections opened in the same instant. The largest real burst is a package manager or similar running inside a session, which opens its parallel downloads through HTTPS_PROXY at once; 64 covers the defaults of npm (`maxsockets` 15) and pnpm (`network-concurrency` 16) several times over, and eviction means even a larger burst only costs a retry, never a lockout.
+ *
+ * `maxTunnels`: each authenticated connection holds two descriptors (the client's and the upstream's). Node raises its soft descriptor limit to the hard limit at start, and 4096 is the smallest hard limit common Linux distributions ship (macOS's is far higher), so 1024 tunnels keep the surface to half of it, leaving the provider and direct listeners room to serve rather than all three failing with EMFILE. It is still many times what concurrent sessions hold: each keeps a handful of tunnels plus whatever bursts its tools make.
+ *
+ * `revalidateMs`: the supervisor prunes dead launches from the registry once per `FRONTDOOR_POLL_MS`, so re-checking more often than that could never find anything newly dead.
+ *
+ * There is deliberately no idle timeout on an authenticated connection: Remote Control and other long-lived streams can sit silent for as long as the far end chooses between events, at an interval the surface cannot know, so any idle timeout would cut legitimate sessions. Authenticated connections are bounded instead by who can open them (only a live launch's process tree holds the capability), by `maxTunnels`, and by revocation: a launch that ends loses every connection it opened at the next revalidation.
+ */
+declare const CONNECT_LIMITS: ConnectLimits;
+/** One parsed CONNECT authority, the host lowercased and the port defaulted. */
+interface ConnectTarget {
+    readonly host: string;
+    readonly port: number;
+}
+/** Parses a CONNECT authority (`host:port`, or a bare `host` meaning 443), or undefined when it names no host or a non-numeric port. */
+declare function parseConnectTarget(authority: string): ConnectTarget | undefined;
+/** Whether a CONNECT target's host (port already stripped) is one whose TLS this proxy terminates. */
+declare function isInterceptedHost(host: string, interceptHosts: readonly string[]): boolean;
+/** Whether a request path on the terminated session is one the routed pipeline serves. The query string stays part of the path: `/v1/messages?beta=true` is still the pipeline's. */
+declare function servedByPipeline(path: string | undefined): boolean;
+/**
+ * Headers a forwarded HTTP message keeps: everything except the hop-by-hop set, which belongs to whichever connection carried it and must not leak onto the next one. The `Connection` header's own value can name further hop-by-hop headers (RFC 9110 section 7.6.1), so those go too. Returns a fresh object; the input is the live parser's map and is never mutated.
+ */
+declare function forwardableHeaders(headers: Readonly<IncomingHttpHeaders>): IncomingHttpHeaders;
+/** A CA certificate and its private key, both as PEM. */
+interface CaMaterial {
+    readonly certPem: string;
+    readonly keyPem: string;
+}
+/** A TLS leaf certificate and its private key, both as PEM. */
+interface LeafCert {
+    readonly certPem: string;
+    readonly keyPem: string;
+}
+/** Generates the local CA: one RSA keypair, self-signed, CA-only by basicConstraints and keyUsage, with a random serial. Built on `node:crypto` alone (see `x509.ts`), no openssl, so the same code works on every platform agent-shim ships to. */
+declare function generateCa(now: Readonly<Date>): CaMaterial;
+/**
+ * Mints a TLS leaf signed by the CA: its own RSA keypair, server-auth usage only, the first name as the subject's common name and every name in the SAN. A name that parses as an IP address goes in as an IP SAN, because TLS clients match an IP host only against IP SANs, never against a DNS SAN spelling the same digits.
+ */
+declare function mintLeaf(ca: CaMaterial, names: readonly string[], now: Readonly<Date>): LeafCert;
+/** Mints each host's leaf once from the CA and reuses it, because generating a 2048-bit RSA keypair costs noticeable time and nothing about the certificate changes between sessions. */
+declare function createLeafCache(ca: CaMaterial, now: () => Date): (host: string) => LeafCert;
+/**
+ * Persistence for the CA: generated once on the machine's first headroom start and reused forever after, because regenerating it would invalidate every child's `NODE_EXTRA_CA_CERTS` pointing at the old file. The real implementation writes the key with mode 0600; injected fakes keep it in memory.
+ */
+interface ConnectCertStore {
+    /** The persisted CA, or undefined when none exists yet (or only half of it does: a cert without its key can sign nothing, so it counts as absent). */
+    readonly loadCa: () => CaMaterial | undefined;
+    /** Persists both halves of the CA, the key unreadable to other users. */
+    readonly writeCa: (ca: CaMaterial) => void;
+}
+/**
+ * Loads the persisted CA, generating and persisting one when no usable CA exists. A stored pair that `node:crypto` cannot parse is treated as absent and replaced: a truncated write is the one failure mode a regeneration can actually repair, and every child that trusted the old file needs a new `NODE_EXTRA_CA_CERTS` anyway once its CA stops parsing.
+ */
+declare function ensureCa(store: ConnectCertStore, generate: () => CaMaterial): CaMaterial;
+/** Where one forwarded request goes, and how: the connect surface's own forwards go to the real upstream over TLS, while a local hop over plain HTTP is what tests redirect to. */
+interface ConnectForwardTarget {
+    readonly host: string;
+    readonly port: number;
+    readonly tls: boolean;
+    /** The SNI name to present; defaults to `host`. Separated so a test can connect to a local fake while presenting the production hostname. */
+    readonly servername?: string;
+    /** Extra trust anchors for the target's certificate, when it is not system-trusted (a test's local fake upstream). */
+    readonly ca?: readonly string[];
+    /** Overrides certificate verification; production leaves it at the Node default (verify against system trust or `ca`). */
+    readonly rejectUnauthorized?: boolean;
+}
+/** Handles one parsed HTTP request on a terminated TLS session. */
+type ConnectRequestHandler = (request: IncomingMessage, response: ServerResponse) => void;
+/** A bound loopback listener and how to stop it. */
+interface ConnectListenerHandle {
+    readonly port: number;
+    /** Stops accepting, ends every live connection, and resolves once the port is released. */
+    readonly close: () => Promise<void>;
+}
+/** Presents one leaf's server-side TLS on CONNECTed sockets. */
+interface TlsAcceptor {
+    /** Starts the TLS handshake on a socket that has just received its CONNECT response, carrying `context` to the handshake's completion untouched: whatever the caller knows about this connection (its tunnel's capability) reaches `onSecure` without the acceptor interpreting it. */
+    readonly accept: (socket: net.Socket, context: string) => void;
+    /** Drops every session this acceptor is terminating. */
+    readonly close: () => void;
+}
+/** Parses HTTP over terminated sockets and serves each request through the handler, keep-alive included. */
+interface HttpParserSession {
+    readonly serve: (socket: net.Socket) => void;
+    readonly close: () => void;
+}
+/**
+ * Every effect the MITM proxy performs, injected so the routing decisions and lifecycle run against fakes in unit tests (the SupervisorPorts pattern): TCP listening, TLS termination, HTTP parsing, plain TCP tunnels, and request forwarding. The real implementation is `realConnectEffects`; the TLS round-trip test uses it with redirected targets.
+ */
+interface ConnectEffects {
+    /** Binds a loopback TCP listener; `preferredPort` is tried first and any free port used when it is taken (bind, do not probe: check-then-bind races). Resolves with the bound port and a close handle. */
+    readonly listenLoopback: (preferredPort: number | undefined, onSocket: (socket: net.Socket) => void) => Promise<ConnectListenerHandle>;
+    /** Builds the TLS terminator for one leaf, handing each successfully handshaked session to `onSecure` together with the context its `accept` call carried. `alpnProtocols`, when given, is advertised during the handshake, which is how a tap host's session can offer HTTP/2 the way its real server does. */
+    readonly createTlsAcceptor: (leaf: LeafCert, onSecure: (secure: net.Socket, context: string) => void, alpnProtocols?: readonly string[]) => TlsAcceptor;
+    /** Opens a TLS connection to a real host, presenting its name as SNI, for a tap session's upstream half. `clientAlpn`, when given, is the protocol the client negotiated with the surface and the only one offered upstream, so the tap never changes the channel's protocol. */
+    readonly connectTlsUpstream: (host: string, port: number, clientAlpn: string | undefined) => Promise<net.Socket>;
+    /** Builds the HTTP parser bound to one request handler. `onUpgrade`, when given, owns every HTTP upgrade request arriving on a terminated session, socket and already-read bytes included; a session without one lets Node destroy the upgrade, its own no-listener behaviour. */
+    readonly createHttpSession: (handler: ConnectRequestHandler, onUpgrade?: (request: IncomingMessage, socket: Duplex, head: Buffer) => void) => HttpParserSession;
+    /** Opens a raw TCP connection for a blind tunnel. */
+    readonly connectTcp: (host: string, port: number) => Promise<net.Socket>;
+    /** Streams one request to `target` and the response back, never buffering a body. When `observer` is given, the forwarding drives it with additive listeners (request and response chunks arrive to both the pipe and the observer) so capturing never changes the forwarding's own flow control. */
+    readonly forwardHttp: (target: ConnectForwardTarget, request: IncomingMessage, response: ServerResponse, observer?: PassthroughObserver) => void;
+}
+/** Everything the connect surface needs to route, resolved before it starts. */
+interface ConnectServerConfig {
+    /** The CONNECT hosts whose TLS get terminated, each with its own leaf, its own HTTP parser and its own upstream. */
+    readonly interceptHosts: readonly string[];
+    /**
+     * The one intercept host whose `/v1/` paths `serveRouted` handles: the API host, whose pipeline identification, authorisation and headroom hop are about Anthropic sessions and no other host's traffic.
+     */
+    readonly routedHost: string;
+    /**
+     * Serves one routed path (`/v1/...`) from the terminated session: the same ordered pipeline the provider listener hands requests to, so an OAuth session and a provider session run identical identification, middleware and routing.
+     */
+    readonly serveRouted: ConnectRequestHandler;
+    /** The leaf to terminate each intercept host with, minted and cached per host. */
+    readonly leafFor: (host: string) => LeafCert;
+    /** Where non-routed paths on one host's terminated session are piped: that host's own real upstream over TLS. */
+    readonly upstreamFor: (host: string) => ConnectForwardTarget;
+    /** Whether a capability presented as a CONNECT request's proxy credential belongs to a live launch: the same constant-time check against the same registry the routed pipeline's admission makes, read fresh on every call because launches come and go. */
+    readonly isLiveCapability: (token: string) => boolean;
+    /**
+     * Binds a second listener that serves the intercept hosts' sessions to connections arriving pre-established, with no CONNECT handshake to authenticate: what an operating-system redirect (a pf rule sending the real hosts' address to this port) delivers. Only the API host's session is reachable this way, never a tap host's, because a redirect can name only addresses and the control plane shares the API host's address today; if that ever splits, the transparent listener must not follow it blindly. There is no capability to check on this surface: the connection carried no proxy credential, so every request rides the pipeline anonymously, admitted the way a tunnel's own header-less requests are (by nothing, which is exactly what they present), and the surface exists solely for clients that ignore proxies and would otherwise be invisible to the door entirely.
+     */
+    readonly transparentPort?: number;
+    /**
+     * The capability the transparent surface's sessions carry: a real, registered token minted by the door for its own pid, so header-less traffic that arrives by redirect is admitted and attributed like any launch's instead of being refused for a credential it cannot possibly present. Absent along with `transparentPort`.
+     */
+    readonly transparentCapability?: string;
+    /** The intercept hosts that are never HTTP-parsed: terminated, tapped at the byte level, and pumped to their real host. */
+    readonly tapHosts: readonly string[];
+    /** The connection deadlines and caps; production passes `CONNECT_LIMITS`. */
+    readonly limits: ConnectLimits;
+    /** The diagnostic tap, when capturing is enabled; absent means nothing is recorded. */
+    readonly capture?: ConnectCapture;
+}
+/** A running connect surface. */
+interface ConnectServerHandle {
+    readonly port: number;
+    /** The transparent listener's port, when one was requested: what an operating-system redirect should point at. */
+    readonly transparentPort?: number;
+    /** Stops the listener, drops every live tunnel and terminated session, and resolves once the port is released. */
+    readonly close: () => Promise<void>;
+}
+/**
+ * Starts the connect surface: binds the listener, mints the intercept host's leaf, and wires the per-connection routing. Resolves once the listener is bound.
+ *
+ * The connection flow: read the CONNECT head within the deadline (never more of the stream than that, so an early ClientHello glued to the head is pushed back with `unshift` and still seen by whatever consumes the socket next), authenticate it, then either blind-tunnel the target or terminate its TLS and parse HTTP on the session. Every network effect flows through `effects`; nothing here touches the network or filesystem itself.
+ */
+declare function startConnectServer(config: ConnectServerConfig, effects: ConnectEffects, preferredPort: number | undefined): Promise<ConnectServerHandle>;
+/** The real `ConnectCertStore` on the filesystem: `ca.pem` world-readable (it is public material), `ca.key` mode 0600 exactly, chmod'ed after the write because a create's mode bits pass through the process umask. */
+declare function realConnectCertStore(paths: {
+    readonly frontdoorCaDir: string;
+    readonly frontdoorCaCertFile: string;
+    readonly frontdoorCaKeyFile: string;
+}): ConnectCertStore;
+
+declare function realConnectEffects(): ConnectEffects;
+
+/** The filesystem operations headroom coordination needs: the same shape as `FarmFs`, injected so every decision over state, sessions, and the start lock runs against an in-memory fake in tests. */
+type HeadroomFs = Pick<FarmFs, "mkdirp" | "mkdirPrivate" | "readFileUtf8" | "writeFileUtf8" | "writeFilePrivate" | "writeFileExclusive" | "readdir" | "removeRecursive">;
+
+/** The outcome of authenticating the listener a front-door state file names. */
+type ListenerVerdict = {
+    readonly ok: true;
+} | {
+    readonly ok: false;
+    readonly reason: string;
+};
+
+/** Raised when the front door cannot be brought up in time or has recorded a fatal error: a routed launch has no other way to reach its provider, so it must fail rather than start a session that can never answer. */
+declare class FrontDoorStartError extends CliError {
+    constructor(message: string);
+}
+/** Every effect the ensure step performs, injected so it runs against fakes in tests. */
+interface EnsureFrontDoorPorts {
+    readonly fs: HeadroomFs;
+    /** Zombie-aware liveness (see `realIsProcessRunning`). */
+    readonly isRunning: (pid: number) => boolean;
+    readonly now: () => number;
+    readonly sleep: (ms: number) => void;
+    /** Spawns the detached front-door supervisor, returning its pid. */
+    readonly spawnSupervisor: (paths: LayoutPaths) => number;
+    /** Authenticates the provider listener on `port`: a TLS handshake chaining to agent-shim's CA and a healthy answer, with no capability sent (see `probeFrontDoorSync`). */
+    readonly verifyListener: (port: number) => ListenerVerdict;
+    /** Asks a running front-door supervisor to exit, without waiting for it to: the caller polls `isRunning`. Only ever called for a pid whose recorded listener has just authenticated as agent-shim's own. */
+    readonly stopSupervisor: (pid: number) => void;
+}
+/**
+ * Brings the front door up for this launch, or finds it serving, and registers this launcher pid in its session registry: the fact that keeps the door from idling out while this session lives, and the record that holds this launch's capability token. The same lock-and-poll coordination as headroom's and the old codex daemon's ensure: the exclusive-create start lock decides which of several concurrent launches spawns the one supervisor, everyone waits on state.json, and a lock whose holder died is removed and retried. Ready means state names a live supervisor and both listeners' ports, which the supervisor writes only after both have bound (and the provider listener has answered its own health probe).
+ *
+ * A live pid in state proves nothing about who holds the port it names: the door may have crashed and left the port to anyone, or the pid may have been reused by an unrelated process. So before anything is registered or returned, the provider listener is authenticated over TLS against agent-shim's CA. A listener that fails (wrong certificate, nothing answering, a bad answer) is treated as a stale or hostile owner: its pid is distrusted for the rest of this call and a replacement supervisor is spawned, which binds a free port when the sticky one is held and is then verified in turn. If a supervisor this call spawned also fails verification, the launch is refused naming the reason and the daemon log; no capability is written and no address is handed to the child.
+ */
+declare function ensureFrontDoor(params: {
+    readonly paths: LayoutPaths;
+    readonly launcherPid: number;
+    readonly ports: EnsureFrontDoorPorts;
+}): {
+    readonly port: number;
+    readonly connectPort: number;
+    readonly token: string;
+};
+
+/** A bound front-door listener in this process, and how to stop it. */
+interface FrontDoorListenerHandle {
+    readonly port: number;
+    /** Stops accepting, ends every live connection, and resolves once the port is released. */
+    readonly close: () => Promise<void>;
+}
+/** Every effect the front-door supervisor performs, injected so its whole lifecycle runs against fakes: no real process, port, clock or listener in a unit test. */
+interface FrontDoorSupervisorPorts {
+    readonly fs: HeadroomFs;
+    readonly paths: LayoutPaths;
+    readonly ownPid: number;
+    readonly now: () => number;
+    /** An event-loop-yielding wait, for the same reason headroom's is: nothing else would ever run between ticks. */
+    readonly sleep: (ms: number) => Promise<void>;
+    /** Zombie-aware liveness, the notion every coordination decision in this project uses. */
+    readonly isRunning: (pid: number) => boolean;
+    /**
+     * Starts the provider listener in this process on `preferredPort` (falling back to any free port when the sticky one is taken, decided at bind time rather than by a racy check-then-bind probe) and resolves once it has bound and answered its own health probe over TLS. This is the HTTPS listener every provider session's base URL points at, serving a loopback leaf signed by agent-shim's CA.
+     */
+    readonly startProviderListener: (preferredPort: number | undefined) => Promise<FrontDoorListenerHandle>;
+    /**
+     * Starts the CONNECT surface in this process on `preferredPort` (same bind-time fallback): the TLS-terminating listener an OAuth session's HTTPS_PROXY points at. Bound before any state names it, so an OAuth launch never finds one listener up without the other.
+     */
+    readonly startConnectListener: (preferredPort: number | undefined) => Promise<FrontDoorListenerHandle>;
+    /**
+     * Starts the direct listener on `preferredPort` (same bind-time fallback): the same routes as the provider listener, minus the headroom hop, over plain HTTP because headroom is what connects to it. Headroom forwards routed traffic back here, which is what keeps the hop from looping, and the port is sticky like the others because headroom's allowlist admits its exact origin. It admits only the hop's own requests and holds no credential until it redeems one from the hop's custody.
+     */
+    readonly startDirectListener: (preferredPort: number | undefined) => Promise<FrontDoorListenerHandle>;
+    readonly log: (line: string) => void;
+}
+/** Options for `runFrontDoorSupervisor`. */
+interface RunFrontDoorSupervisorOptions {
+    /** Bounds the loop's iterations so a test can observe steady state; such a run returns `FRONTDOOR_SUPERVISOR_STILL_RUNNING`. */
+    readonly tickLimit?: number;
+}
+/**
+ * Runs the front-door supervisor: binds all three listeners (the HTTPS provider listener, the CONNECT surface and the plain-HTTP direct listener, each on its sticky port), records the serving state, and shuts down after `idleShutdownMinutes` with an empty session registry. Returns the exit code: 0 for an idle shutdown, 1 for a fatal start failure.
+ *
+ * The listeners live in this process, so there is no child to keep alive: a crash of this process is a crash of every routed session's door at once, and recovery is the next launch's ensure spawning a replacement on the same sticky ports, which is exactly the failure model the issue asks to settle with tests. Keeping the headroom daemon alive is the headroom supervisor's job, not this one's; the two daemons idle out independently.
+ */
+declare function runFrontDoorSupervisor(idleShutdownMinutes: number, ports: FrontDoorSupervisorPorts, options?: RunFrontDoorSupervisorOptions): Promise<number>;
+
+/**
+ * The latest state for one identity, rewritten atomically after each recorded response: the snapshot file other tools read (`~/.agent-shim/usage/snapshots/<identity>.json`) without shelling out to `agent-shim`.
+ */
+declare const UsageSnapshotSchema: z.ZodObject<{
+    schemaVersion: z.ZodLiteral<1>;
+    identity: z.ZodString;
+    updatedAt: z.ZodISODateTime;
+    account: z.ZodOptional<z.ZodObject<{
+        accountUuid: z.ZodOptional<z.ZodString>;
+        emailAddress: z.ZodOptional<z.ZodString>;
+        displayName: z.ZodOptional<z.ZodString>;
+        organizationUuid: z.ZodOptional<z.ZodString>;
+        organizationName: z.ZodOptional<z.ZodString>;
+        organizationType: z.ZodOptional<z.ZodString>;
+        organizationRole: z.ZodOptional<z.ZodString>;
+        workspaceRole: z.ZodOptional<z.ZodString>;
+        billingType: z.ZodOptional<z.ZodString>;
+        seatTier: z.ZodOptional<z.ZodString>;
+        organizationRateLimitTier: z.ZodOptional<z.ZodString>;
+        userRateLimitTier: z.ZodOptional<z.ZodString>;
+        hasExtraUsageEnabled: z.ZodOptional<z.ZodBoolean>;
+        subscriptionCreatedAt: z.ZodOptional<z.ZodString>;
+        accountCreatedAt: z.ZodOptional<z.ZodString>;
+    }, z.core.$strict>>;
+    providers: z.ZodRecord<z.ZodString, z.ZodObject<{
+        lastRequestAt: z.ZodISODateTime;
+        lastStatus: z.ZodNumber;
+        lastModel: z.ZodOptional<z.ZodString>;
+        rateLimit: z.ZodOptional<z.ZodObject<{
+            observedAt: z.ZodISODateTime;
+            headers: z.ZodRecord<z.ZodString, z.ZodString>;
+            unified: z.ZodOptional<z.ZodObject<{
+                status: z.ZodOptional<z.ZodString>;
+                fiveHour: z.ZodOptional<z.ZodObject<{
+                    utilization: z.ZodOptional<z.ZodNumber>;
+                    resetsAt: z.ZodOptional<z.ZodISODateTime>;
+                    status: z.ZodOptional<z.ZodString>;
+                }, z.core.$strict>>;
+                sevenDay: z.ZodOptional<z.ZodObject<{
+                    utilization: z.ZodOptional<z.ZodNumber>;
+                    resetsAt: z.ZodOptional<z.ZodISODateTime>;
+                    status: z.ZodOptional<z.ZodString>;
+                }, z.core.$strict>>;
+                representativeClaim: z.ZodOptional<z.ZodString>;
+                resetAt: z.ZodOptional<z.ZodISODateTime>;
+                overageStatus: z.ZodOptional<z.ZodString>;
+            }, z.core.$strict>>;
+        }, z.core.$strict>>;
+        lastLimit: z.ZodOptional<z.ZodObject<{
+            kind: z.ZodEnum<{
+                "rate-limited": "rate-limited";
+                "quota-exhausted": "quota-exhausted";
+            }>;
+            retryAfterSeconds: z.ZodOptional<z.ZodNumber>;
+            resetAt: z.ZodOptional<z.ZodISODateTime>;
+            window: z.ZodOptional<z.ZodString>;
+            evidence: z.ZodArray<z.ZodString>;
+            observedAt: z.ZodISODateTime;
+            status: z.ZodNumber;
+        }, z.core.$strict>>;
+        quota: z.ZodOptional<z.ZodObject<{
+            observedAt: z.ZodISODateTime;
+            source: z.ZodString;
+            level: z.ZodOptional<z.ZodString>;
+            windows: z.ZodArray<z.ZodObject<{
+                measures: z.ZodString;
+                periodMs: z.ZodOptional<z.ZodNumber>;
+                period: z.ZodOptional<z.ZodString>;
+                utilization: z.ZodNumber;
+                resetsAt: z.ZodOptional<z.ZodISODateTime>;
+                limit: z.ZodOptional<z.ZodNumber>;
+                used: z.ZodOptional<z.ZodNumber>;
+                remaining: z.ZodOptional<z.ZodNumber>;
+            }, z.core.$strict>>;
+        }, z.core.$strict>>;
+    }, z.core.$strict>>;
+}, z.core.$strict>;
+type UsageSnapshot = z.infer<typeof UsageSnapshotSchema>;
+
+/**
+ * The read side of the usage store: pure over an injected filesystem, so the CLI, the library surface and tests all read the same way, and nothing here writes.
+ */
+/** The filesystem reads the usage store's readers need. */
+type UsageReadFs = Pick<FarmFs, "readFileUtf8" | "readdir">;
+/** Raised for a snapshot file that exists but does not hold a snapshot of this schema version. */
+declare class UsageSnapshotError extends Error {
+    readonly file: string;
+    constructor(file: string, detail: string);
+}
+/** The path of an identity's snapshot. Throws for an invalid identity name, which could otherwise name a path outside the snapshots directory. */
+declare function snapshotPath(snapshotsDir: string, identity: string): string;
+/** Reads one identity's snapshot: undefined when it has none yet, `UsageSnapshotError` when the file is there but unreadable. */
+declare function readUsageSnapshot(fs: Pick<FarmFs, "readFileUtf8">, snapshotsDir: string, identity: string): UsageSnapshot | undefined;
+/** Reads every identity's snapshot, by identity name. */
+declare function listUsageSnapshots(fs: UsageReadFs, snapshotsDir: string): readonly UsageSnapshot[];
+
+/** Raised when the daemon cannot be brought up in time, or reports a fatal `lastError`: a launch that asked for headroom must never silently fall back to a direct connection. */
+declare class HeadroomStartError extends CliError {
+    constructor(message: string);
+}
+/** Every effect the ensure step performs, injected so it runs against fakes in tests. */
+interface EnsureHeadroomPorts {
+    readonly fs: HeadroomFs;
+    /** Zombie-aware liveness: a supervisor or daemon that exited without being reaped still answers signal 0 as alive, but will never serve a request or write state, so it must read as dead here (see `realIsProcessRunning`). */
+    readonly isRunning: (pid: number) => boolean;
+    readonly now: () => number;
+    readonly sleep: (ms: number) => void;
+    /** Spawns the detached supervisor process that owns the headroom daemon, returning its pid. */
+    readonly spawnSupervisor: (paths: LayoutPaths) => number;
+}
+/**
+ * Brings the headroom daemon up for this launch, or finds it already running, and registers this launcher pid in its session registry (the fact that keeps the daemon alive and defers drift restarts until this launch is done).
+ *
+ * The exclusive-create start lock decides which of several concurrent launches spawns the one supervisor: its holder spawns and keeps waiting like everyone else, everyone else waits on state.json, and a lock whose holder has died is removed and retried. Readiness is "state names a live supervisor, a live headroom pid, and a port", which the supervisor only writes after its own `/readyz` probe has passed, so polling state alone never mistakes a bound-but-not-ready port for a usable daemon.
+ *
+ * Throws `HeadroomStartError` (naming the daemon log path and any recorded `lastError`) when the daemon is not up within `HEADROOM_START_TIMEOUT_MS`, or when a live supervisor has recorded a fatal error.
+ */
+declare function ensureHeadroom(params: {
+    readonly paths: LayoutPaths;
+    readonly launcherPid: number;
+    readonly ports: EnsureHeadroomPorts;
+}): {
+    readonly port: number;
+};
+
+/** The token-saving settings of the `headroom` config block, without its install and lifecycle fields (`source`, `idleShutdownMinutes`). */
+type HeadroomSettings = Pick<HeadroomGlobalConfig, "mode" | "targetRatio" | "ccr" | "rolloutChannel" | "interceptToolResults" | "readMaturation">;
+
+/** Everything the supervisor needs to run the daemon, resolved from the global config and the filesystem before it starts. */
+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. */
+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.
+ */
+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;
+}
+/** Options for `runSupervisor`. */
+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;
+}
+/**
+ * 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.
+ */
+declare function runSupervisor(initialConfig: HeadroomSupervisorConfig, ports: SupervisorPorts, options?: RunSupervisorOptions): Promise<number>;
+
+/**
+ * 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.
+ */
+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"];
+type AmbientCredentialVar = (typeof AMBIENT_CREDENTIAL_VARS)[number];
+/** Which guarded variable was found set, and to what. */
+interface AmbientCredentialDetection {
+    readonly variable: AmbientCredentialVar;
+}
+/** A credential this launch itself exports to the child: the variable it lands in and its value. */
+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.
+ */
+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.
+ */
+declare function formatAmbientCredentialGuardMessage(variable: AmbientCredentialVar, identityName?: string): string;
+/** Inputs to the ambient-credential guard evaluation. */
+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. */
+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).
+ */
+declare function evaluateAmbientCredentialGuard(params: EvaluateAmbientCredentialGuardParams): AmbientCredentialGuardResult;
+
+/** Raised by any operation that requires an identity to already exist, when it does not. */
+declare class IdentityNotFoundError extends CliError {
+    readonly name: string;
+    constructor(name: string);
+}
+/** Raised by `addIdentity` when an identity with the given name already has an `identity.json`. */
+declare class IdentityAlreadyExistsError extends CliError {
+    readonly identityName: string;
+    constructor(identityName: string);
+}
+/** Raised by `addIdentity` when `name` fails `IdentitySchema`'s own naming rule — it must start with a letter or number and may then contain letters, numbers, dots, hyphens, underscores, and at signs, so an email address names an identity directly while a *leading* `@` stays invalid (it would collide with the `@name` selector syntax's first-`@` split). */
+declare class InvalidIdentityNameError extends CliError {
+    readonly attemptedName: string;
+    constructor(attemptedName: string);
+}
+declare function identityExists(paths: LayoutPaths, name: string): boolean;
+/** Reads and validates one identity's `identity.json`, or undefined when it does not exist. */
+declare function readIdentity(paths: LayoutPaths, name: string): Identity | undefined;
+/**
+ * Creates a new identity: validates `name` against `IdentitySchema`'s own naming rule and writes a fresh `identity.json` with `allowAmbientCredential: false` and no `defaultConfigProfile`.
+ *
+ * Throws `IdentityAlreadyExistsError` if an identity with this name already has an `identity.json` — `add` never silently overwrites an existing identity. Throws `InvalidIdentityNameError` when `name` fails `IdentitySchema`'s naming rule, rather than letting the underlying `ZodError` escape as an unhandled crash.
+ */
+declare function addIdentity(paths: LayoutPaths, name: string): Identity;
+/**
+ * Persists `name` as the active identity, written atomically as plain text (not JSON — this file is read by `decideIdentity` in `src/launcher/identity.ts` via a simple UTF-8 read-and-trim, matching the README's documented `~/.agent-shim/active-identity` file).
+ *
+ * `name` may be a `pool:<name>` selector, which makes launches pick a member of that pool. Throws `IdentityNotFoundError` when no identity with this name exists yet, and `PoolNotFoundError` for a pool that is not defined: selecting either would silently persist a name nothing else can ever load.
+ */
+declare function useIdentity(paths: LayoutPaths, name: string): void;
+/** Reads the persisted active-identity file, or undefined when none is set. */
+declare function readActiveIdentity(paths: LayoutPaths): string | undefined;
+/**
+ * Whether a directory name directly under `identitiesDir` names an actual identity, rather than one of agent-shim's own farm directories.
+ *
+ * `IdentitySchema` requires an identity name to start with a letter or digit, so a leading `.` can only be a resync's own bookkeeping: a `.<identity>.scratch.<suffix>` tree still being built, or a `.<identity>.previous.<suffix>` superseded farm retained for `agent-shim identity resolve-conflicts`. Neither is an identity, and neither should be reported as a broken one for lacking an `identity.json` a resync never put there.
+ */
+declare function isIdentityDirectoryName(name: string): boolean;
+/** One identity as reported by `listIdentities`, whose `identity.json` parsed and validated cleanly. */
+interface IdentityListEntry {
+    readonly name: string;
+    readonly identity: Identity;
+    readonly isActive: boolean;
+    readonly problem?: never;
+}
+/** One identity whose `identity.json` is present but unreadable — malformed JSON, or valid JSON this version's `IdentitySchema` rejects. `problem` carries the reason, already flattened onto a single line. */
+interface UnreadableIdentityListEntry {
+    readonly name: string;
+    readonly identity?: never;
+    readonly isActive: boolean;
+    readonly problem: string;
+}
+/** Either shape `listIdentities` can report, discriminated by which of `identity`/`problem` is present rather than by a tag field — the two are never simultaneously satisfiable. */
+type IdentityListing = IdentityListEntry | UnreadableIdentityListEntry;
+/**
+ * Lists every identity under `identitiesDir`, marking which one (if any) is currently active.
+ *
+ * One identity whose `identity.json` cannot be read is reported as its own `UnreadableIdentityListEntry` rather than aborting the whole listing. A single bad file blocking `identity list` outright is exactly the failure mode that hides every *other* identity from view at the moment the user most needs to see them — and the file need not even be corrupt to land here, since a name written by a newer agent-shim whose naming rule has since widened is rejected outright by an older binary's own copy of `IdentitySchema`.
+ */
+declare function listIdentities(paths: LayoutPaths): readonly IdentityListing[];
+/**
+ * Sets `identity`'s `defaultConfigProfile` field, or clears it when `profileName` is undefined. Throws `IdentityNotFoundError` when the identity does not exist. Whether the profile exists is the caller's concern: `identity set --default-profile` checks it first.
+ */
+declare function setDefaultConfigProfile(paths: LayoutPaths, identityName: string, profileName: string | undefined): Identity;
+/**
+ * Patches `identity`'s `allowAmbientCredential` field. Throws `IdentityNotFoundError` when the identity does not exist.
+ */
+declare function setAllowAmbientCredential(paths: LayoutPaths, identityName: string, allow: boolean): Identity;
+/** The change `setIdentityCredential` makes: new sources and/or a new target for the credential block, or `false` to remove the block and return the identity to its stored login. */
+type IdentityCredentialChange = {
+    readonly sources?: readonly CredentialSource[];
+    readonly target?: CredentialTarget;
+    readonly cache?: CredentialCache | false;
+} | false;
+/**
+ * Sets, changes or removes `identityName`'s credential block. New `sources` replace the whole ordered list (the order is the meaning); a `target` alone keeps the existing sources, and so needs a credential block to exist already. Throws `IdentityNotFoundError` when the identity does not exist, and `UsageError` when only a target is given for an identity with no credential yet.
+ */
+declare function setIdentityCredential(paths: LayoutPaths, identityName: string, change: IdentityCredentialChange): Identity;
+/**
+ * Deletes identity `name` entirely: its directory under `identitiesDir` (the farm, its `identity.json`, and whatever that farm holds unshared, credentials included), its resync lock, any scratch or superseded farm a resync left behind, and the active-identity selection when it names this identity. Data shared into `~/.claude` stays there, since the farm only ever symlinks to it. Throws `IdentityNotFoundError` when the identity does not exist.
+ */
+declare function removeIdentity(paths: LayoutPaths, name: string): void;
+
+/** Raised by any operation that requires a configuration profile to already exist, when it does not. */
+declare class ProfileNotFoundError extends CliError {
+    readonly profileName: string;
+    constructor(profileName: string);
+}
+/** Raised by `createProfile` (`profile add`) when a profile with the given name already has a file. */
+declare class ProfileAlreadyExistsError extends CliError {
+    readonly profileName: string;
+    constructor(profileName: string);
+}
+/** Raised when a `--category` patch names something other than one of the four overridable categories (e.g. `secret`, or a typo). */
+declare class InvalidCategoryNameError extends CliError {
+    readonly categoryName: string;
+    constructor(categoryName: string);
+}
+/** True when a profile file exists for `name`, regardless of whether it validates. */
+declare function profileExists(paths: LayoutPaths, name: string): boolean;
+/** Reads and validates one configuration profile, or undefined when it does not exist. */
+declare function readProfile(paths: LayoutPaths, name: string): ConfigProfile | undefined;
+/**
+ * Creates a new configuration profile, empty apart from the optional `extends` list and description. Throws `ProfileAlreadyExistsError` if a profile with this name already has a file, and `ConfigValidationError` when the result fails `ConfigProfileSchema` (e.g. an empty `--extends ""` name), rather than letting the underlying `ZodError` escape as an unhandled crash.
+ */
+declare function createProfile(paths: LayoutPaths, name: string, extendsList?: readonly string[], description?: string): ConfigProfile;
+/** One profile as reported by `listProfiles`. */
+interface ProfileListEntry {
+    readonly name: string;
+    readonly profile: ConfigProfile;
+}
+/** Lists every configuration profile under `configProfilesDir` that has a valid `<name>.json`. */
+declare function listProfiles(paths: LayoutPaths): readonly ProfileListEntry[];
+/** Reads the user-global `~/.agent-shim/config.json`, or undefined when it does not exist. */
+declare function readGlobalConfig(paths: LayoutPaths): GlobalConfig | undefined;
+/** Sets the user-global default configuration profile in `~/.agent-shim/config.json`, creating the file if it doesn't exist yet. Whether the profile exists is the caller's concern: `profile use` checks it first. */
+declare function setGlobalDefaultProfile(paths: LayoutPaths, name: string): GlobalConfig;
+/**
+ * Merges `patch` (from one or more `--category cat=bool` flags) into `profile`'s own `categories` object and writes it back.
+ *
+ * Throws `InvalidCategoryNameError` for any key that isn't one of the four overridable categories — `secret` can never be toggled by any configuration layer, this included.
+ */
+declare function setProfileCategories(paths: LayoutPaths, name: string, patch: Readonly<Record<string, boolean>>): ConfigProfile;
+/**
+ * Merges `patch` (from one or more `--entry "path"=bool` flags) into `profile`'s own `entries` object and writes it back.
+ *
+ * Key validity (the `<category>/<real-relative-path>` prefix requirement) is enforced by `ConfigProfileSchema`'s own `EntriesSchema` at write time — an invalid key surfaces as the usual `ConfigValidationError`.
+ */
+declare function setProfileEntries(paths: LayoutPaths, name: string, patch: Readonly<Record<string, boolean>>): ConfigProfile;
+/**
+ * Merges `patch` into `profile`'s own `launch` object and writes it back. A key present in `patch` with the value `undefined` removes that setting outright (a `--no-launch-provider`, say) rather than overwriting it, and a `launch` object left with no settings is removed too.
+ */
+declare function setProfileLaunchFlags(paths: LayoutPaths, name: string, patch: Readonly<LaunchFlags>): ConfigProfile;
+/** Replaces `profile`'s own `extends` list and/or description; an empty list or an undefined description removes the field. */
+declare function setProfileMetadata(paths: LayoutPaths, name: string, patch: Readonly<{
+    extends?: readonly string[];
+    description?: string | false;
+}>): ConfigProfile;
+/** Deletes a configuration profile's file. Throws `ProfileNotFoundError` when it does not exist. Nothing that references it by name is rewritten; `agent-shim doctor` reports any identity default, directory rule or `extends` left pointing at it. */
+declare function removeProfile(paths: LayoutPaths, name: string): void;
+
+/** What a cache stores for one credential: the token, when it was fetched, and the source that produced it (a non-secret descriptor, kept so `check` and the launch log can still say where the token came from). */
+declare const CachedCredentialSchema: z.ZodObject<{
+    token: z.ZodString;
+    fetchedAt: z.ZodNumber;
+    source: z.ZodUnion<readonly [z.ZodObject<{
+        env: z.ZodString;
+    }, z.core.$strict>, z.ZodObject<{
+        file: z.ZodString;
+    }, z.core.$strict>, z.ZodObject<{
+        interactive: z.ZodOptional<z.ZodBoolean>;
+        timeoutMs: z.ZodOptional<z.ZodInt>;
+        command: z.ZodTuple<[z.ZodString], z.ZodString>;
+    }, z.core.$strict>, z.ZodObject<{
+        interactive: z.ZodOptional<z.ZodBoolean>;
+        timeoutMs: z.ZodOptional<z.ZodInt>;
+        op: z.ZodString;
+    }, z.core.$strict>, z.ZodObject<{
+        interactive: z.ZodOptional<z.ZodBoolean>;
+        timeoutMs: z.ZodOptional<z.ZodInt>;
+        keychain: z.ZodObject<{
+            service: z.ZodString;
+            account: z.ZodOptional<z.ZodString>;
+        }, z.core.$strict>;
+    }, z.core.$strict>, z.ZodObject<{
+        literal: z.ZodString;
+    }, z.core.$strict>]>;
+}, z.core.$strict>;
+type CachedCredential = z.infer<typeof CachedCredentialSchema>;
+/**
+ * Where cached credentials live, injected so resolution and its tests need neither the Keychain nor a real directory. `owner` names what the credential belongs to (`identity work`, `provider z`) and is the entry's key; `store` picks the backing store. `read` returns undefined for a missing or unreadable entry, since an entry that cannot be used is the same as no entry.
+ */
+interface CredentialCachePort {
+    readonly read: (store: CredentialCacheStore, owner: string) => CachedCredential | undefined;
+    readonly write: (store: CredentialCacheStore, owner: string, entry: CachedCredential) => void;
+    readonly remove: (store: CredentialCacheStore, owner: string) => void;
+}
+
+/** What reading one `file` source found: nothing at that path, or its contents and permission bits. `mode` is undefined on a platform with no POSIX permission bits (Windows), where the looseness check cannot apply. */
+type SecretFileRead = {
+    readonly found: false;
+} | {
+    readonly found: true;
+    readonly content: string;
+    readonly mode: number | undefined;
+};
+/** The outcome of one credential command. `stderr` is empty for an interactive run, whose stderr goes to the terminal so a person sees any prompt. */
+interface CredentialCommandResult {
+    readonly status: number | null;
+    readonly stdout: string;
+    readonly stderr: string;
+    readonly timedOut: boolean;
+}
+/**
+ * Everything resolving a credential needs from the outside world, injected so the resolver (and every launcher test) runs without `op`, the Keychain, real secret files or a terminal. `src/realPorts.ts` wires the real one; tests wire a fake.
+ */
+interface CredentialPort {
+    /** Reads a `file` source's path (absolute or `~`-rooted). */
+    readonly readSecretFile: (filePath: string) => SecretFileRead;
+    /** Runs a command source's argv directly (no shell) under a timeout, capturing stdout. An interactive run inherits the terminal's stdin and stderr so a person can answer a prompt. */
+    readonly runCommand: (argv: readonly [string, ...string[]], options: {
+        readonly timeoutMs: number;
+        readonly interactive: boolean;
+    }) => CredentialCommandResult;
+    /** Whether a person can answer a prompt now: standard input is a terminal, or there is a desktop session to show a dialog in. */
+    readonly personPresent: () => boolean;
+    /** Where cached credentials live, used only for a credential block that asks for caching. Omit to resolve every launch from the sources. */
+    readonly cache?: CredentialCacheEnv;
+}
+/** One source as `check`, `doctor` and every `--json` output report it: its kind plus the same non-secret identifying detail `describeSource` prints. */
+type CredentialSourceSummary = {
+    readonly kind: "env";
+    readonly variable: string;
+} | {
+    readonly kind: "file";
+    readonly path: string;
+} | {
+    readonly kind: "command";
+    readonly program: string;
+} | {
+    readonly kind: "op";
+    readonly reference: string;
+} | {
+    readonly kind: "keychain";
+    readonly service: string;
+    readonly account?: string;
+} | {
+    readonly kind: "literal";
+};
+/** A credential block as it is reported: its effective target and each source's summary, in order. */
+interface CredentialSummary {
+    readonly target: CredentialTarget;
+    readonly sources: readonly CredentialSourceSummary[];
+    /** The block's cache setting when it asks for caching: how long a token is kept (absent for no expiry) and where. */
+    readonly cache?: {
+        readonly ttl?: string;
+        readonly store?: string;
+    };
+}
+/** What caching a credential needs beyond the block's own `cache` setting: the port holding entries, the platform that picks the default store, and the clock the TTL is measured on. */
+interface CredentialCacheEnv {
+    readonly port: CredentialCachePort;
+    readonly platform: NodeJS.Platform;
+    readonly now: () => number;
+}
+
+/** Raised by any operation that requires a provider to already exist, when it does not. */
+declare class ProviderNotFoundError extends CliError {
+    readonly name: string;
+    constructor(name: string);
+}
+/** Raised by `addProvider` when a provider with the given name already has a file. */
+declare class ProviderAlreadyExistsError extends CliError {
+    readonly providerName: string;
+    constructor(providerName: string);
+}
+/**
+ * Raised by `addProvider` when `name` fails the provider naming rule: the same rule `IdentitySchema` applies to identity names (start with a letter or number, then letters, numbers, dots, hyphens, underscores, and at signs). Keeping the two rules identical means a name that works for one works for the other, and neither vocabulary can ever produce a path segment that escapes `providers/` or `identities/`.
+ */
+declare class InvalidProviderNameError extends CliError {
+    readonly attemptedName: string;
+    constructor(attemptedName: string);
+}
+/** True when a provider file exists for `name`, regardless of whether it validates. */
+declare function providerExists(paths: LayoutPaths, name: string): boolean;
+/** What converting one old-format provider file involves: the old fields it uses, and the whole file rewritten in the current format. */
+interface LegacyProviderConversion {
+    readonly fields: readonly string[];
+    readonly replacement: Record<string, unknown>;
+}
+/** Raised when a provider file is still in the format before the credential block, naming the old fields and giving the exact replacement. */
+declare class LegacyProviderFileError extends CliError {
+    readonly filePath: string;
+    readonly conversion: LegacyProviderConversion;
+    constructor(filePath: string, conversion: LegacyProviderConversion);
+}
+/** Reads and validates one provider definition, or undefined when it does not exist. */
+declare function readProvider(paths: LayoutPaths, name: string): Provider | undefined;
+/** One provider definition as reported by `listProviders`. */
+interface ProviderListEntry {
+    readonly name: string;
+    readonly provider: Provider;
+}
+/** Lists every provider under `providersDir` that has a valid `<name>.json`. A file that fails validation is skipped here; `provider list` is the place a broken definition gets surfaced, not a launch. */
+declare function listProviders(paths: LayoutPaths): readonly ProviderListEntry[];
+/** The credential targets a provider may use. */
+type ProviderCredentialTarget = (typeof PROVIDER_CREDENTIAL_TARGETS)[number];
+/** The kinds of provider. */
+type ProviderKind = (typeof PROVIDER_KINDS)[number];
+/** Where a provider sends its sessions, for display: an `http` provider's base URL, or the front door for a codex provider (whose address exists only at launch). */
+declare function describeProviderEndpoint(provider: Provider): string;
+/** Everything `addProvider` writes into a fresh provider file. `baseUrl` is required for an `http` provider and refused for a codex one; `codex` applies only to a codex provider. */
+interface AddProviderInput {
+    readonly kind?: ProviderKind;
+    readonly displayName: string;
+    readonly baseUrl?: string;
+    readonly sources: readonly CredentialSource[];
+    readonly target?: ProviderCredentialTarget;
+    readonly env?: Readonly<Record<string, string>>;
+    readonly codex?: CodexProviderConfig;
+}
+/** Raised when a provider option does not fit the provider's kind: a base URL for a codex provider, a missing one for an http provider, or codex settings for an http provider. */
+declare class ProviderKindMismatchError extends UsageError {
+    constructor(message: string);
+}
+/**
+ * Creates a new provider definition. Throws `ProviderAlreadyExistsError` when a provider with this name already has a file, `InvalidProviderNameError` when `name` fails the naming rule, and `ConfigValidationError` when the assembled definition fails `ProviderSchema` (e.g. a `baseUrl` that is not a URL) rather than letting the underlying `ZodError` escape as an unhandled crash.
+ */
+declare function addProvider(paths: LayoutPaths, name: string, input: AddProviderInput): Provider;
+/**
+ * The fields `updateProvider` changes. `sources` replaces the whole ordered source list (a list is set, not patched, since its order is its meaning); `target` changes where the token goes and keeps the sources. `env` entries merge over the existing ones and `unsetEnv` keys are then deleted.
+ */
+interface UpdateProviderInput {
+    readonly displayName?: string;
+    readonly baseUrl?: string;
+    readonly sources?: readonly CredentialSource[];
+    readonly target?: ProviderCredentialTarget;
+    /** A new cache block, or false to remove it; undefined leaves the existing one. */
+    readonly cache?: CredentialCache | false;
+    readonly env?: Readonly<Record<string, string>>;
+    readonly unsetEnv?: readonly string[];
+    /** Merged over a codex provider's existing settings: a field given here replaces that field, and `models` entries merge per tier. */
+    readonly codex?: CodexProviderConfig;
+}
+/**
+ * Updates an existing provider definition in place. Throws `ProviderNotFoundError` when it does not exist, and `ConfigValidationError` when the updated definition fails `ProviderSchema`, leaving the file untouched.
+ */
+declare function updateProvider(paths: LayoutPaths, name: string, input: UpdateProviderInput): Provider;
+/** Deletes a provider definition. Throws `ProviderNotFoundError` when it does not exist. */
+declare function removeProvider(paths: LayoutPaths, name: string): void;
+
+/** Raised when a command names a pool that is not defined in the global config. */
+declare class PoolNotFoundError extends CliError {
+    readonly poolName: string;
+    constructor(poolName: string);
+}
+/** The pools defined in `~/.agent-shim/config.json`, by name. */
+declare function readPools(paths: LayoutPaths): Readonly<Record<string, Pool>>;
+/** The pool named `name`; throws `PoolNotFoundError` when none is defined. */
+declare function requirePool(paths: LayoutPaths, name: string): Pool;
+/** Defines a new pool. Throws `InvalidPoolNameError` for a name `PoolNameSchema` rejects and `PoolAlreadyExistsError` for one already defined. */
+declare function addPool(paths: LayoutPaths, name: string, identities: readonly string[]): Pool;
+/** Replaces an existing pool's members. Throws `PoolNotFoundError` when it is not defined. */
+declare function setPool(paths: LayoutPaths, name: string, identities: readonly string[]): Pool;
+/** Removes a pool. Throws `PoolNotFoundError` when it is not defined. Anything that selected it (an active-identity file, a directory rule) is left for `doctor` to report, as with a removed identity. */
+declare function removePool(paths: LayoutPaths, name: string): void;
+
+/** Raised by `removeDirectoryRule`, `updateDirectoryRule` and `rule show` when no rule matches the given path exactly. */
+declare class DirectoryRuleNotFoundError extends CliError {
+    readonly rulePath: string;
+    constructor(rulePath: string);
+}
+/** Raised by `addDirectoryRule` when neither `--config-profile` nor `--identity` is given, and by `updateDirectoryRule` when an update would leave a rule that sets nothing at all: a rule that pins and overrides nothing would do nothing. */
+declare class DirectoryRuleMissingTargetError extends CliError {
+    constructor();
+}
+/** Raised by `addDirectoryRule` when a rule for the exact path already exists: `rule add` creates, `rule set` updates. */
+declare class DirectoryRuleAlreadyExistsError extends CliError {
+    readonly rulePath: string;
+    constructor(rulePath: string);
+}
+/** Reads `~/.agent-shim/directory-rules.json`, or an empty rule set when the file does not exist yet. */
+declare function readDirectoryRules(paths: LayoutPaths): DirectoryRules;
+/** Validates and writes the whole `~/.agent-shim/directory-rules.json` file. Exported so `src/configure.ts` can update a single rule's `categories`/`entries` in place without duplicating this validate-then-write step. Throws `ConfigValidationError` when `rules` fails `DirectoryRulesSchema`, rather than letting the underlying `ZodError` escape as an unhandled crash. */
+declare function writeDirectoryRules(paths: LayoutPaths, rules: DirectoryRules): void;
+/** Lists every directory rule, in file order. */
+declare function listDirectoryRules(paths: LayoutPaths): readonly DirectoryRule[];
+/** Inputs to `addDirectoryRule` beyond the path itself. */
+interface AddDirectoryRuleOptions {
+    readonly configProfile?: string;
+    readonly identity?: string;
+}
+/**
+ * Adds a new directory rule for `rulePath`. Throws `DirectoryRuleAlreadyExistsError` when a rule for that exact path already exists (`updateDirectoryRule` changes one), and `DirectoryRuleMissingTargetError` when neither `configProfile` nor `identity` is given, since a rule that pins neither would do nothing.
+ */
+declare function addDirectoryRule(paths: LayoutPaths, rulePath: string, options: AddDirectoryRuleOptions): DirectoryRule;
+/** The fields `updateDirectoryRule` changes. A value of `false` removes that field from the rule. */
+interface UpdateDirectoryRuleOptions {
+    readonly configProfile?: string | false;
+    readonly identity?: string | false;
+}
+/**
+ * Updates the existing directory rule for `rulePath` in place, keeping its position in the file and every field not named. Throws `DirectoryRuleNotFoundError` when no rule matches that exact path, and `DirectoryRuleMissingTargetError` when the update would leave a rule that does nothing (remove it with `removeDirectoryRule` instead).
+ */
+declare function updateDirectoryRule(paths: LayoutPaths, rulePath: string, options: UpdateDirectoryRuleOptions): DirectoryRule;
+/** Removes the directory rule for `rulePath`. Throws `DirectoryRuleNotFoundError` when no rule matches that exact path. */
+declare function removeDirectoryRule(paths: LayoutPaths, rulePath: string): void;
+
+/** Which precedence rule produced an identity decision. */
+type IdentityDecisionSource = 
+/** `CLAUDE_CONFIG_DIR` was already set: identity resolution is skipped entirely and the real binary uses whatever it already points to. */
+"config-dir-escape-hatch"
+/** A leading `@name` argv[0] positional, or its explicit form `--identity <name>`. */
+ | "argv"
+/** The `AGENT_SHIM_IDENTITY` environment variable. */
+ | "env"
+/** A directory rule pinning an identity to the current path. */
+ | "directory-pin"
+/** The persisted `~/.agent-shim/active-identity` file. */
+ | "active-identity-file"
+/** Nothing resolved an identity at all — a bare launch with no active identity. */
+ | "none";
+/** Which precedence rule produced a configuration-profile decision. */
+type ConfigProfileDecisionSource = 
+/** An explicit `--config-profile` CLI flag. */
+"cli-flag"
+/** The `AGENT_SHIM_CONFIG_PROFILE` environment variable. */
+ | "env"
+/** A directory rule's `configProfile` selection for `$PWD`. */
+ | "directory-rule"
+/** The active identity's own declared `defaultConfigProfile`. */
+ | "identity-default"
+/** The user-global `~/.agent-shim/config.json` default. */
+ | "global-default"
+/** Nothing resolved a configuration profile at all. */
+ | "none";
+
+/** What an account's plan means for picking it: a subscription with a capacity relative to the smallest paid tier, or an account billed by use. */
+type PlanClass = {
+    readonly kind: "subscription";
+    /** The plan's size as a multiple of the smallest subscription tier (Max 5x is 5, Max 20x is 20). */
+    readonly capacity: number;
+    /** False when the tier string named no multiplier and no tier this project knows, so `capacity` is the neutral 1 rather than a reading. */
+    readonly recognised: boolean;
+    /** The tier string the classification rests on, when the account had one. */
+    readonly tier?: string;
+} | {
+    readonly kind: "pay-per-use";
+    readonly tier?: string;
+};
+
+/** In pick order. `scored` has usable quota data; `unknown` has none (never recorded, or unreadable); `pay-per-use` bills by use instead of drawing on a plan; `ineligible` is refused right now. */
+type CandidateClass = "scored" | "unknown" | "pay-per-use" | "ineligible";
+interface Candidate {
+    readonly identity: string;
+    readonly class: CandidateClass;
+    /** Plan-size-weighted remaining quota per hour until its reset: higher is more wasted if left unused. Present for `scored` only. */
+    readonly score?: number;
+    /** False when the five-hour window would run dry, at the observed pace, before it resets. A `scored` candidate that is not feasible ranks below every feasible one. */
+    readonly feasible: boolean;
+    /** When an `ineligible` candidate can be used again. */
+    readonly blockedUntilMs?: number;
+    readonly plan: PlanClass;
+    /** Human-readable facts behind the class and score, in the order they matter. */
+    readonly reasons: readonly string[];
+}
+
+/** What `pool pick` reports: the ranking a launch from `directory` would act on right now. */
+interface PoolPickReport {
+    readonly pool: string;
+    readonly directory: string;
+    /** The member a launch would run as, absent when every member is refused. */
+    readonly pick?: string;
+    readonly candidates: readonly PoolPickCandidateView[];
+    /** Members that name an identity that does not exist; a launch skips them. */
+    readonly missing: readonly string[];
+    /** When nothing can be picked, the soonest any member returns. */
+    readonly earliestReturn?: {
+        readonly identity: string;
+        readonly at: string;
+    };
+    /** Why the last-pick record could not be read, when that is the case. */
+    readonly stickyProblem?: string;
+}
+/** One ranked member as `pool pick --json` prints it. */
+interface PoolPickCandidateView {
+    readonly identity: string;
+    readonly class: Candidate["class"];
+    readonly score?: number;
+    readonly feasible: boolean;
+    readonly blockedUntil?: string;
+    readonly plan: Candidate["plan"];
+    readonly reasons: readonly string[];
+}
+
+/**
+ * Forward-only encoding of a real working directory into the single directory name Claude Code gives it under `~/.claude/projects/`.
+ *
+ * The encoding collapses the *entire* non-alphanumeric character class to `-`, not just the path separator: `.`, `_`, ` `, `@`, and `/` all become `-`, while letters and digits pass through with their case preserved. This was confirmed against a real installation's project directories, not assumed from the one `/`-becomes-`-` sample the README quotes.
+ *
+ * The encoding is therefore many-to-one: `~/work/clients/acme`, `~/work/clients-acme`, and `~/work-clients/acme` all produce the identical name. That makes it impossible to invert, so this module never tries: there is no decode function here, and `projects.test.ts` asserts the module's export list to keep it that way. Only the forward direction — real path to encoded name — is ever computed, and `detectEncodingAmbiguity` reports when a pattern's encoded form could plausibly correspond to more than one real path rather than resolving it silently.
+ */
+
+/** Why a pattern's encoded form might not identify the real path its author had in mind. */
+type EncodingAmbiguityReason = 
+/** The literal portion contains a character other than `/` that encodes to `-`, so a sibling path differing only in that character encodes identically. */
+"lossy-characters"
+/** Two different patterns in the same configuration encode to the identical form. */
+ | "collides-with-sibling-pattern";
+/** One reported ambiguity in a `history/projects/` pattern. */
+interface EncodingAmbiguity {
+    readonly fragment: string;
+    readonly encoded: string;
+    readonly reason: EncodingAmbiguityReason;
+    readonly detail: string;
+}
+
+/** The result of looking up the macOS Keychain service name Claude Code is actually using for one identity's farm. */
+interface KeychainLookupResult {
+    readonly checked: true;
+    readonly found: boolean;
+    readonly serviceName?: string;
+    readonly note: string;
+}
+/** One file's reported settings exposure: names and counts only, never the underlying values. */
+interface SettingsExposureReport {
+    readonly file: string;
+    readonly envKeyNames: readonly string[];
+    readonly hookEventNames: readonly string[];
+    readonly hookCommandCount: number;
+}
+/** The provider the cascade selects for this directory, as the wiring layer loaded it: its definition, or why it could not be used (no such provider, an invalid or old-format file). */
+type CheckProviderInput = {
+    readonly name: string;
+    readonly definition: Provider;
+    readonly problem?: never;
+} | {
+    readonly name: string;
+    readonly definition?: never;
+    readonly problem: string;
+};
+/**
+ * Which credential a launch here would use, by source kind and target only: a selected provider's credential block always wins; otherwise the identity's own credential block; otherwise the login stored in the identity's directory.
+ */
+interface CredentialReport {
+    readonly applies: "provider" | "identity" | "stored-login";
+    readonly provider?: {
+        readonly name: string;
+        readonly credential?: CredentialSummary;
+        readonly problem?: string;
+    };
+    readonly identity?: CredentialSummary;
+}
+/** Inputs to `runCheck` — everything already loaded/injected, exactly like the resolver core and the launcher: nothing in this function touches a real filesystem, git repository, clock, or environment itself. */
+interface RunCheckParams {
+    readonly cwd: string;
+    readonly home: string;
+    readonly claudeHome: string;
+    readonly env: Readonly<Record<string, string | undefined>>;
+    readonly branch?: string;
+    readonly branchDetached?: boolean;
+    readonly nowMs: number;
+    /** Used only to build the fact manifest by reading the canonical `~/.claude` tree — `runCheck` never mutates the farm and never spawns anything. */
+    readonly farmFs: FarmFs;
+    readonly cascade: CascadeInput;
+    readonly classification: {
+        readonly defaults: CategoryClassification;
+        readonly overlay?: CategoryClassificationOverlay;
+    };
+    readonly identityName?: string;
+    readonly identitySource: IdentityDecisionSource;
+    /** The pool the launch selected and how it ranks right now, when it named a pool instead of an identity; `identityName` is then the member it would pick. */
+    readonly poolPick?: PoolPickReport;
+    readonly configProfileName?: string;
+    readonly configProfileSource: ConfigProfileDecisionSource;
+    /** The resolved identity's own `identity.json`, when one was found. */
+    readonly identity?: Identity;
+    /** Raw `settings.json`/`settings.local.json` contents, keyed by filename, undefined when a file does not exist. */
+    readonly settingsFiles: Readonly<Record<string, string | undefined>>;
+    /** Runs `security find-generic-password` for the Keychain diagnostic. Omit to skip that diagnostic entirely (e.g. off macOS, or when no identity/farm root is known). */
+    readonly run?: RunPort;
+    /** The identity's own farm root — `security`'s lookup account. Required alongside `run` for the Keychain diagnostic to run at all. */
+    readonly farmRoot?: string;
+    /** `process.platform` in real use; the Keychain diagnostic only ever runs when this is `"darwin"`. */
+    readonly platform: string;
+    /** The provider a launch here would route through (`launch.provider` in the cascade), when one is selected. */
+    readonly provider?: CheckProviderInput;
+}
+/** Everything `agent-shim check` reports about one directory/identity, without touching the farm or spawning anything. */
+interface CheckReport {
+    readonly identityName?: string;
+    readonly identitySource: IdentityDecisionSource;
+    readonly poolPick?: PoolPickReport;
+    readonly configProfileName?: string;
+    readonly configProfileSource: ConfigProfileDecisionSource;
+    readonly resolved: ResolvedState;
+    readonly decisionLines: readonly string[];
+    readonly projectEncodingAmbiguities: readonly EncodingAmbiguity[];
+    readonly ambientCredential: AmbientCredentialGuardResult;
+    readonly keychain?: KeychainLookupResult;
+    readonly settingsExposure: readonly SettingsExposureReport[];
+    readonly credential: CredentialReport;
+}
+/**
+ * Resolves the full cascade for one directory/identity and reports everything `agent-shim check` documents: every entry's resolved state and which layer/condition decided it, any ambiguous `history/projects/` encoding in scope, and the three always-on diagnostics (ambient-credential exposure, macOS Keychain service name, settings-secrets exposure).
+ *
+ * Deliberately reuses the same cascade machinery a real launch uses — `resolveDecisions` and `buildEntryFacts` — rather than reimplementing any part of resolution. The one thing this function never does that a launch does is touch the farm or spawn anything: it only reads the canonical `~/.claude` tree to build the fact manifest resolution needs, and every other input (cascade, classification, settings file contents, the Keychain lookup) is handed in already loaded.
+ */
+declare function runCheck(params: RunCheckParams): CheckReport;
+/** Renders a full `CheckReport` as plain text lines, in the order `agent-shim check` prints them. */
+declare function formatCheckReport(report: CheckReport): string[];
+/**
+ * The `check --json` form of a report: every field the text form prints, as plain data (no `Map`s, no compiled matchers), so a script can read the same verdicts a person would.
+ */
+declare function checkReportToJson(report: CheckReport): Record<string, unknown>;
+/**
+ * Whether a report carries anything `check --strict` fails on: a resolver diagnostic of warning or error severity, an ambiguous `history/projects/` encoding, an ambient credential a launch would refuse, or a selected provider a launch could not use. Informational diagnostics and the settings-exposure advisory (names and counts only, for a person to review) never fail it.
+ */
+declare function checkReportHasWarnings(report: CheckReport): boolean;
+/** What `collectCheckReport` needs from its caller. */
+interface CollectCheckReportParams {
+    readonly paths: LayoutPaths;
+    /** The directory a launch would run in; resolved against the working directory by the caller. */
+    readonly cwd: string;
+    /** The identity to check, as `--identity` names it; absent means the identity a launch there would resolve. */
+    readonly identity?: string;
+    readonly env: NodeJS.ProcessEnv;
+}
+/**
+ * Resolves what a launch in `params.cwd` would share or hide, and why, against this machine: the edge adapter that reads the real filesystem, clock, git and keychain, resolves the identity, configuration profile and cascade exactly as a launch does, and hands the facts to the pure `runCheck`. Never touches the farm or spawns claude.
+ */
+declare function collectCheckReport(params: CollectCheckReportParams): CheckReport;
+
+declare const ClaudeShimStateSchema: z.ZodObject<{
+    targetPath: z.ZodString;
+    method: z.ZodEnum<{
+        hardlink: "hardlink";
+        copy: "copy";
+    }>;
+    installedAtMs: z.ZodNumber;
+}, z.core.$strict>;
+type ClaudeShimState = z.infer<typeof ClaudeShimStateSchema>;
+type PathShadowStatus = {
+    readonly status: "ok";
+} | {
+    readonly status: "not-on-path";
+} | {
+    readonly status: "shadowed";
+    readonly by: string;
+};
+
+/** The result of a successful discovery. */
+interface DiscoveredClaudeBinary {
+    /** Full path to the discovered `claude` executable. */
+    path: string;
+    /** Which strategy found it. */
+    source: "versions-dir" | "path-fallback";
+    /** The version string, when discovered via the versions directory. */
+    version?: string;
+}
+
+type DoctorSeverity = "pass" | "warn" | "fail";
+type DoctorSection = "ambient-credential" | "binary-discovery" | "claude-shim" | "path-resolution" | "legacy-name" | "config-profile" | "identity" | "pool" | "provider" | "keychain" | "directory-rules" | "global-config" | "categories-local" | "active-identity" | "headroom";
+/** One line of `agent-shim doctor`'s report. `subject` names the identity/profile/rule the finding is about, when the section has more than one of those. */
+interface DoctorFinding {
+    readonly section: DoctorSection;
+    readonly subject?: string;
+    readonly severity: DoctorSeverity;
+    readonly message: string;
+}
+/** The full result of `runDoctor`. `ok` is false iff any finding is a `fail` — a `warn` never fails the report on its own. */
+interface DoctorReport {
+    readonly findings: readonly DoctorFinding[];
+    readonly ok: boolean;
+}
+/** One identity's raw `identity.json`, unparsed — `runDoctor` does its own JSON.parse/schema validation so one malformed file never aborts the rest of the report. */
+interface DoctorIdentityInput {
+    readonly name: string;
+    readonly path: string;
+    readonly raw: string | undefined;
+    /** The identity's own farm root (`identitiesDir/<name>`) — the account name the Keychain lookup uses. */
+    readonly farmRoot: string;
+}
+/** One configuration profile's raw `<name>.json`, unparsed. */
+interface DoctorConfigProfileInput {
+    readonly name: string;
+    readonly path: string;
+    readonly raw: string | undefined;
+}
+/** One provider's raw `<name>.json`, unparsed. */
+interface DoctorProviderInput {
+    readonly name: string;
+    readonly path: string;
+    readonly raw: string | undefined;
+}
+/** A single optional top-level file `runDoctor` validates against a schema when present — absent is a legitimate, unconfigured state, not a failure. */
+interface DoctorFileInput {
+    readonly path: string;
+    readonly raw: string | undefined;
+}
+/** The outcome of resolving the real Claude Code binary, pre-resolved by the wiring layer since `discoverClaudeBinary` is not itself a parse-shaped pure operation and already has its own dedicated test coverage. */
+type DoctorBinaryDiscovery = {
+    readonly ok: true;
+    readonly binary: DiscoveredClaudeBinary;
+} | {
+    readonly ok: false;
+    readonly message: string;
+};
+/**
+ * Where a bare command name resolves for the two names this tool owns.
+ *
+ * `ownExecutablePath` is this process's own PATH-visible location (`realOwnExecutablePath()`); `agentShim` is `findPathShadow`'s verdict for a bare `agent-shim` against the directory that executable lives in. `claude` is only populated when a shim is actually enabled — without one, a `claude` on PATH is Claude Code's own binary, which is not a shadow of anything.
+ */
+interface DoctorPathResolution {
+    readonly ownExecutablePath: string;
+    readonly agentShim: PathShadowStatus;
+    readonly claude?: PathShadowStatus;
+}
+/** Everything `runDoctor` needs, all of it already loaded/injected — nothing in `runDoctor` itself reads a file, shells out, or touches the farm. */
+interface RunDoctorParams {
+    readonly env: Readonly<Record<string, string | undefined>>;
+    readonly identities: readonly DoctorIdentityInput[];
+    readonly configProfiles: readonly DoctorConfigProfileInput[];
+    readonly providers: readonly DoctorProviderInput[];
+    readonly directoryRules: DoctorFileInput;
+    readonly globalConfig: DoctorFileInput;
+    readonly categoriesLocal: DoctorFileInput;
+    readonly activeIdentity: DoctorFileInput;
+    readonly binaryDiscovery: DoctorBinaryDiscovery;
+    /** Whether `agent-shim shim enable` has been run, and whether its recorded target still exists on disk — pre-resolved by the wiring layer, since checking a file's existence is real I/O, not a parse-shaped pure operation. */
+    readonly claudeShim: {
+        readonly state: ClaudeShimState | undefined;
+        readonly targetExists: boolean;
+    };
+    /** Which executables a bare `agent-shim` (and, when the shim is enabled, a bare `claude`) would actually run — pre-resolved by the wiring layer, since scanning PATH is real I/O. */
+    readonly pathResolution: DoctorPathResolution;
+    /** The resolved state root (`paths.root`), whose directory name says whether this installation still lives under the former `.claude-use` name. */
+    readonly rootPath: string;
+    /** Runs `security find-generic-password` for the per-identity Keychain check. Omit to skip that check entirely (e.g. off macOS). */
+    readonly run?: RunPort;
+    /** `process.platform` in real use; the Keychain check only ever runs when this is `"darwin"`. */
+    readonly platform: string;
+    /** The headroom daemon's state.json plus a zombie-aware liveness predicate for the pids it names (a defunct daemon holds no port but still answers signal 0). Omit the raw text when the daemon has never run; that is a pass, not a failure. */
+    readonly headroom: {
+        readonly state: DoctorFileInput;
+        readonly isRunning: (pid: number) => boolean;
+    };
+}
+/**
+ * Audits the whole `~/.agent-shim` config graph for internal consistency: every identity, every configuration profile's own `extends` chain, every provider, `directory-rules.json`, `config.json`, `categories.local.json`, `active-identity`, plus real Claude Code binary discoverability and ambient-credential exposure.
+ *
+ * Deliberately identity/directory-agnostic, unlike `runCheck` — there is no single cascade to resolve `doctor` against, so it never touches settings-exposure (which only means anything relative to one resolved cascade).
+ *
+ * Every check aggregates rather than throws: a malformed file becomes one `fail` finding for that file, not an aborted report. This is the one place in the codebase that deliberately breaks the "throw a validation error and let it propagate" convention every other command relies on — `doctor`'s whole purpose is to survive a broken file and keep auditing everything else.
+ */
+declare function runDoctor(params: RunDoctorParams): DoctorReport;
+/** Renders a full `DoctorReport` as plain text lines, one section header at a time, in the order `agent-shim doctor` prints them. */
+declare function formatDoctorReport(report: DoctorReport): string[];
+/** What `collectDoctorReport` needs from its caller. */
+interface CollectDoctorReportParams {
+    readonly paths: LayoutPaths;
+    readonly env: NodeJS.ProcessEnv;
+}
+/**
+ * Audits the whole state root against this machine: the edge adapter that enumerates every identity, configuration profile and provider on disk, reads every top-level config file as raw text (never pre-parsing, so one malformed file cannot abort the report), discovers the real Claude Code binary and resolves where a bare command name runs from, and hands the facts to the pure `runDoctor`.
+ */
+declare function collectDoctorReport(params: CollectDoctorReportParams): DoctorReport;
+
+/** What a launch's one-off command-line/environment overrides resolve to: the `cliOverride` layer `src/resolve/walk.ts`'s `assembleCascade` composes last, so it beats every other layer. */
+interface CliOverride {
+    readonly categories?: CategoryMap;
+    readonly entries?: Entries;
+    readonly launch?: {
+        readonly provider?: string;
+    };
+}
+
+/**
+ * Everything the farm resync needs that the launcher itself has no way to produce: a real filesystem, a real clock, the working directory, and a way to load the cascade for it.
+ *
+ * Supplied by `src/cli.ts` in normal operation. A caller that omits it launches with no farm at all, which is the right behaviour in exactly the cases where there is no agent-shim-managed farm to resync — and is what the launcher's own pre-farm tests exercise.
+ */
+interface FarmRuntime {
+    readonly fs: FarmFs;
+    /** The canonical `~/.claude` every farm symlink points back into. */
+    readonly claudeHome: string;
+    readonly home: string;
+    readonly cwd: string;
+    /** The git branch at `cwd`, for `when: { branch }` conditions. Undefined when `cwd` is not in a repository. */
+    readonly branch?: string;
+    readonly branchDetached?: boolean;
+    readonly classification: {
+        readonly defaults: CategoryClassification;
+        readonly overlay?: CategoryClassificationOverlay;
+    };
+    /** Loads and assembles the cascade for `cwd` under the given configuration profile and one-off command-line/environment overrides. Injected so the launcher never reads a config file itself. */
+    readonly loadCascade: (baseConfigProfile: string | undefined, cliOverride: CliOverride | undefined) => CascadeInput;
+    readonly now: () => number;
+    /** Distinguishes this process's scratch and superseded farm directories from any other's. */
+    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;
+    };
+}
+/** Inputs to `prepareLaunch`: everything a launch needs except the means of spawning the child. */
+interface PrepareLaunchParams {
+    readonly paths: LayoutPaths;
+    readonly fs: FsPort;
+    readonly proc: ProcPort;
+    readonly log: LogPort;
+    /** Discovers the real `claude` binary to spawn. Injected so `runLauncher` never depends on `src/versionDiscovery.ts`'s own filesystem/PATH inputs directly — the caller (`src/cli.ts`) wires the real discovery, tests wire a fake that returns a fixed path. */
+    readonly resolveClaudeBinary: () => DiscoveredClaudeBinary;
+    /** An identity pinned to `$PWD` by a directory rule. Accepted as an already-resolved value — the rules-loading code that produces it lands in Phase 4/5. */
+    readonly directoryPinnedIdentity?: string;
+    /** A directory rule's `configProfile` selection for `$PWD`. Accepted as an already-resolved value for the same reason. */
+    readonly directoryRuleConfigProfile?: string;
+    /** An explicit `--config-profile` value, when the caller wants to force one regardless of argv — normal operation instead relies on `parseLauncherArgv` finding `--config-profile` in `proc.argv` itself, so this is only needed to override that. */
+    readonly cliFlagConfigProfile?: string;
+    /** The user-global `~/.agent-shim/config.json` default configuration profile, when one is configured. */
+    readonly globalDefaultConfigProfile?: string;
+    /** The user-global `pools`, which a `pool:<name>` selector picks a member of. */
+    readonly pools?: Readonly<Record<string, Pool>>;
+    /** Wires the farm resync. Omitted only by a caller that has no farm to manage. */
+    readonly farm?: FarmRuntime;
+    /** Wires headroom routing. Omitted by a caller that cannot route through the daemon; a launch that resolves `headroom` on with no port wired is refused loudly rather than silently bypassing it. */
+    readonly headroom?: HeadroomPort;
+    /** Wires the front-door daemon. Omitted by a caller that cannot run it; a launch that routes anything (a provider, or headroom) with no port wired is refused rather than started against an address nothing serves. */
+    readonly frontdoor?: FrontDoorPort;
+    /** Resolves credential blocks (a provider's, or the launching identity's own). Omitted by a caller that cannot read secret files or run commands; a launch that needs a credential is then refused rather than started without it. */
+    readonly credentials?: CredentialPort;
+    /** True when the user was asked on a terminal whether to create the selected configuration profile and chose to launch without it. Without that explicit choice, a selected profile with no file is refused rather than silently skipped. */
+    readonly allowMissingConfigProfile?: boolean;
+}
+/**
+ * What one launch resolved to, once every effect its child depends on is in place (the identity's farm resynced, the front door and headroom up and this launch registered with them): the real binary, its arguments and its environment.
+ */
+interface LaunchPlan {
+    readonly bin: string;
+    readonly args: readonly string[];
+    readonly env: Readonly<Record<string, string | undefined>>;
+    /** Releases the daemon session registrations this launch holds. Call it when the child has exited; it is safe to call more than once. */
+    readonly release: () => void;
+}
+/**
+ * Prepares one `claude` launch, in order:
+ *
+ * `CLAUDE_CONFIG_DIR` escape-hatch check, then the identity/config-profile decision, the provider decision, the identity's own credential, the ambient-credential guard, farm resync, version discovery, flag resolution (and, when headroom resolved on, daemon bring-up), the extra-flags split, and the final argument list and environment, returned as a `LaunchPlan` for the caller to spawn. It refuses through `params.proc.exit`, so a caller that is not a command line process passes a `proc` whose `exit` throws.
+ *
+ * A launch that resolves an identity with no `identity.json`, or a configuration profile with no file, is refused with exit 1 naming the missing name and how it was selected: silently proceeding would create a brand-new login for a mistyped `@name`, or launch with a whole cascade layer missing. On a terminal, `src/runClaude.ts` offers to create either before this runs.
+ *
+ * The farm resync is skipped when `CLAUDE_CONFIG_DIR` was already set (the escape hatch means the user has named a configuration directory explicitly, and agent-shim manages neither its contents nor its lifetime) and when no identity resolved at all (a bare launch against plain `~/.claude`, matching the legacy tool's own behaviour). In both cases there is no agent-shim-managed farm for a resync to act on.
+ */
+declare function prepareLaunch(params: PrepareLaunchParams): LaunchPlan;
+
+/** Raised by `prepareClaudeLaunch` when the launch is refused: no identity, a missing profile, an ambient credential, an unresolvable credential and the like. `message` is what the launcher logged; `exitCode` is the status the command line would have exited with. */
+declare class LaunchRefusedError extends CliError {
+    readonly exitCode: number;
+    constructor(message: string, exitCode: number);
+}
+/** What `prepareClaudeLaunch` needs from its caller. */
+interface PrepareClaudeLaunchOptions {
+    /** The arguments after `agent-shim run`, exactly as the command line takes them: `@name`, launch flags, then the arguments for `claude`. */
+    readonly argv: readonly string[];
+    /** The directory the launch is for. */
+    readonly cwd: string;
+    /** The environment the launch inherits; a variable it sets is what the child sees. */
+    readonly env: Readonly<Record<string, string | undefined>>;
+    /** The state root; defaults to the one the command line resolves. */
+    readonly paths?: LayoutPaths;
+    /** The path of the agent-shim executable, used to start the front door and headroom daemons when the launch routes through them. Without it such a launch is refused: this process is not agent-shim, and re-running it would run the host program again. */
+    readonly agentShim?: string;
+}
+/**
+ * Resolves a launch for `options.cwd` on this machine and returns what to spawn, so another tool can start `claude` as an identity, through a provider, with the same sharing rules the command line applies, without shelling out. It performs the effects the child depends on: the identity's farm is resynced, and the front door and headroom are brought up and this process registered with them. Call `release` on the plan when the child has exited.
+ *
+ * A refused launch throws `LaunchRefusedError` carrying the launcher's own message. Interactive offers (creating a missing identity or profile on a terminal) belong to the command line and are not made here.
+ */
+declare function prepareClaudeLaunch(options: PrepareClaudeLaunchOptions): LaunchPlan;
+
+export { AMBIENT_CREDENTIAL_VARS, CONNECT_INTERCEPT_HOST, CONNECT_INTERCEPT_HOSTS, CONNECT_LIMITS, CategoryClassificationOverlaySchema, CategoryClassificationSchema, CategoryMapSchema, CliError, ConfigProfileSchema, CredentialCacheSchema, CredentialSchema, CredentialSourceSchema, DirectoryRuleAlreadyExistsError, DirectoryRuleMissingTargetError, DirectoryRuleNotFoundError, DirectoryRuleSchema, DirectoryRulesSchema, EXIT_FAILURE, EXIT_USAGE, EntryValueSchema, FARM_MANIFEST_FILENAME, FrontDoorStartError, GlobalConfigSchema, HeadroomStartError, IdentityAlreadyExistsError, IdentityNotFoundError, IdentitySchema, InvalidCategoryNameError, InvalidIdentityNameError, InvalidProviderNameError, LaunchRefusedError, LegacyProviderFileError, PoolNameSchema, PoolNotFoundError, PoolSchema, PortableConfigSchema, ProfileAlreadyExistsError, ProfileNotFoundError, ProviderAlreadyExistsError, ProviderKindMismatchError, ProviderNotFoundError, ProviderSchema, ROUTED_PATH_PREFIX, UsageError, UsageSnapshotError, UsageSnapshotSchema, WhenSchema, addDirectoryRule, addIdentity, addPool, addProvider, buildEntryFacts, buildLayoutPaths, carryOver, checkReportHasWarnings, checkReportToJson, collectCheckReport, collectDoctorReport, createLeafCache, createProfile, describeProviderEndpoint, detectAmbientCredential, ensureCa, ensureFrontDoor, ensureHeadroom, evaluateAmbientCredentialGuard, formatAmbientCredentialGuardMessage, formatCheckReport, formatDoctorReport, forwardableHeaders, generateCa, identityExists, isIdentityDirectoryName, isInterceptedHost, listDirectoryRules, listIdentities, listProfiles, listProviders, listUsageSnapshots, mintLeaf, parseConnectTarget, prepareClaudeLaunch, prepareLaunch, profileExists, providerExists, readActiveIdentity, readDirectoryRules, readFarmManifest, readGlobalConfig, readIdentity, readPools, readProfile, readProvider, readUsageSnapshot, realConnectCertStore, realConnectEffects, recoverFarm, recoveryDiagnostics, removeDirectoryRule, removeIdentity, removePool, removeProfile, removeProvider, requirePool, resolveAgentShimHome, resolveClaudeHome, resolveDecisions, resolveLayoutPaths, resolveSupervisorConfig, resyncFarm, runCheck, runDoctor, runFrontDoorSupervisor, runSupervisor, servedByPipeline, setAllowAmbientCredential, setDefaultConfigProfile, setGlobalDefaultProfile, setIdentityCredential, setPool, setProfileCategories, setProfileEntries, setProfileLaunchFlags, setProfileMetadata, snapshotPath, startConnectServer, topLevelNames, updateDirectoryRule, updateProvider, useIdentity, writeDirectoryRules };
+export type { AddDirectoryRuleOptions, AddProviderInput, AmbientCredentialDetection, AmbientCredentialGuardResult, AmbientCredentialVar, BuildEntryFactsParams, CaMaterial, CarryOverParams, CarryOverResult, CategoryMap, CheckReport, CollectCheckReportParams, CollectDoctorReportParams, CompiledRule, ConfigProfile, ConnectCertStore, ConnectEffects, ConnectLimits, ConnectServerConfig, ConnectServerHandle, ConnectTarget, Credential, CredentialSource, Decision, Diagnostic, DirectoryRule, DirectoryRules, DoctorReport, EliminatedRule, EnsureFrontDoorPorts, EnsureHeadroomPorts, EntryFact, EntryFacts, EntryValue, EvaluateAmbientCredentialGuardParams, FlattenedCascade, FrontDoorSupervisorPorts, GlobalConfig, HeadroomSupervisorConfig, Identity, IdentityCredentialChange, IdentityListEntry, IdentityListing, InjectedCredential, LaunchPlan, Layer, LayerId, LayoutPaths, LeafCert, Pool, PortableConfig, PrepareClaudeLaunchOptions, PrepareLaunchParams, ProfileListEntry, Provider, ProviderListEntry, RecoverFarmParams, RecoveryResult, ResolveDecisionsInput, ResolvedState, ResyncFarmParams, ResyncFarmResult, RunCheckParams, RunDoctorParams, RunFrontDoorSupervisorOptions, RunSupervisorOptions, SupervisorPorts, UnreadableIdentityListEntry, UpdateDirectoryRuleOptions, UpdateProviderInput, UsageReadFs, UsageSnapshot, WhenCondition };