agent-shim 7.13.1 → 7.14.0

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

@@ -1,95 +0,0 @@
-import { type LoadedFile } from "../config/load";
-import { type Identity } from "../config/schema";
-import type { FsPort } from "./ports";
-/** Which precedence rule produced an identity decision. */
-export 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";
-/** The pool a `pool:<name>` selector names, or undefined when `selector` names an identity directly. */
-export declare function poolNameOf(selector: string): string | undefined;
-/** The result of deciding which identity applies to this launch. */
-export interface IdentityDecision {
-    /** The resolved identity name. Absent when the escape hatch applied, when nothing resolved one, or when a pool was selected (the launcher picks a member from `pool`). */
-    readonly name?: string;
-    /** The pool selected by a `pool:<name>` selector, when the launch named a pool instead of an identity. */
-    readonly pool?: string;
-    readonly source: IdentityDecisionSource;
-    /** True when `CLAUDE_CONFIG_DIR` was already set and every step below was skipped as a result. */
-    readonly configDirEscapeHatch: boolean;
-}
-/** Inputs to `decideIdentity`, in the exact precedence order the README's CLI reference table documents. */
-export interface DecideIdentityParams {
-    readonly env: Readonly<Record<string, string | undefined>>;
-    /** The identity `parseLauncherArgv` found in a leading `@name` or an `--identity <name>` flag, if either was given. */
-    readonly argv0Identity?: string;
-    /** An identity pinned to `$PWD` by a directory rule. Accepted as an already-resolved value here — the rules-loading code that produces it lands in Phase 4/5. */
-    readonly directoryPinnedIdentity?: string;
-    /** Reads the persisted active-identity file, returning undefined when it does not exist or is empty. Injected so this stays pure. */
-    readonly readActiveIdentityFile: () => string | undefined;
-}
-/**
- * Decides which identity applies to this launch, in precedence order:
- *
- * 1. If `CLAUDE_CONFIG_DIR` is already set, skip identity/cascade resolution entirely: a deliberate carry-forward of the legacy script's own "don't override an explicit launcher" escape hatch.
- * 2. A leading `@name` argv[0] positional, or `--identity <name>`.
- * 3. The `AGENT_SHIM_IDENTITY` environment variable.
- * 4. A directory-pinned identity from a directory rule.
- * 5. The persisted `~/.agent-shim/active-identity` file.
- *
- * Each of steps 2 to 5 may name `pool:<name>` instead of an identity; the decision then carries `pool` and no `name`, and the launcher picks the member.
- *
- * An empty string counts as unset for `CLAUDE_CONFIG_DIR` and `AGENT_SHIM_IDENTITY`, consistent with how this project treats empty-string environment variables everywhere else (see `src/paths.ts` and the ambient-credential guard).
- */
-export declare function decideIdentity(params: DecideIdentityParams): IdentityDecision;
-/** Which precedence rule produced a configuration-profile decision. */
-export 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";
-/** The result of deciding which configuration profile applies to this launch. */
-export interface ConfigProfileDecision {
-    readonly name?: string;
-    readonly source: ConfigProfileDecisionSource;
-}
-/** Inputs to `decideConfigProfile`, in the exact precedence order the README's "Configuration profiles" section documents. */
-export interface DecideConfigProfileParams {
-    readonly env: Readonly<Record<string, string | undefined>>;
-    readonly cliFlagConfigProfile?: string;
-    readonly directoryRuleConfigProfile?: string;
-    readonly identityDefaultConfigProfile?: string;
-    readonly globalDefaultConfigProfile?: string;
-}
-/**
- * Decides which configuration profile applies to this launch, in precedence order:
- *
- * 1. An explicit `--config-profile` flag or `AGENT_SHIM_CONFIG_PROFILE` environment variable (this run only).
- * 2. A directory rule's `configProfile` selection for `$PWD`.
- * 3. The active identity's own declared default (`defaultConfigProfile` in its `identity.json`).
- * 4. A global default (`~/.agent-shim/config.json`).
- */
-export declare function decideConfigProfile(params: DecideConfigProfileParams): ConfigProfileDecision;
-/**
- * Reads and validates one identity's `identity.json` from `<identitiesDir>/<name>/identity.json`, via `IdentitySchema`.
- *
- * Returns undefined when the file does not exist (e.g. the identity was resolved by name but never actually created — `agent-shim identity add` is Phase 4's job, not this one's). Throws `ConfigValidationError` when the file exists but fails validation, the same as any other config file in this project.
- */
-export declare function loadIdentity(identitiesDir: string, name: string, fs: FsPort): LoadedFile<Identity> | undefined;

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

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

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

@@ -1,44 +0,0 @@
-import type { Pool } from "../config/schema";
-import type { LayoutPaths } from "../paths";
-import { type PoolPickFs } from "../usage/poolPick";
-import type { FarmFs, FsPort, LogPort } from "./ports";
-/** Everything one pool pick needs, injected so it runs against the same fakes as the rest of the launcher. */
-export interface ResolvePoolParams {
-    readonly poolName: string;
-    /** Which precedence rule selected the pool, for the refusal messages. */
-    readonly selectedVia: string;
-    readonly pools: Readonly<Record<string, Pool>> | undefined;
-    readonly paths: LayoutPaths;
-    readonly fs: FsPort;
-    readonly usageFs: PoolPickFs & Pick<FarmFs, "writeFilePrivate" | "mkdirPrivate">;
-    /** The launch directory: the key of the last-pick record. */
-    readonly cwd: string;
-    readonly now: () => number;
-    readonly sleep: (ms: number) => void;
-    /** The arguments claude itself will receive. */
-    readonly passthrough: readonly string[];
-    /** Sleep until the earliest member returns, instead of refusing, when every member is refused. */
-    readonly wait: boolean;
-    readonly log: LogPort;
-}
-/** The pick, or why none could be made. */
-export type PoolResolution = {
-    readonly ok: true;
-    readonly identity: string;
-    /** The pool and the chosen member's leading reasons, for the launch's decision line. */
-    readonly explanation: string;
-} | {
-    readonly ok: false;
-    readonly message: string;
-};
-/** A pool's members split by whether each is an identity that exists: a pool may outlive an identity it names, since removing an identity does not rewrite the pools that list it. */
-export declare function splitMembers(pool: Pool, paths: Pick<LayoutPaths, "identitiesDir">, fs: FsPort): {
-    readonly present: readonly string[];
-    readonly missing: readonly string[];
-};
-/**
- * Picks the identity a launch of pool `poolName` runs as.
- *
- * Members without an `identity.json` are skipped with a warning, since a pool may outlive an identity it names. When every remaining member is refused right now the launch is refused, naming the earliest return, unless `wait` is set, which sleeps until then and ranks again. The chosen member is recorded as this directory's last pick so the next launch here keeps its warm prompt cache.
- */
-export declare function resolvePoolLaunch(params: ResolvePoolParams): PoolResolution;

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

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

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

@@ -1,20 +0,0 @@
-import type { ProcPort, SpawnPort } from "./ports";
-/** Inputs to `spawnClaude`. */
-export interface SpawnClaudeParams {
-    /** Full path to the real `claude` binary to run, as discovered by `src/versionDiscovery.ts`. */
-    readonly bin: string;
-    readonly args: readonly string[];
-    readonly env: Readonly<Record<string, string | undefined>>;
-    readonly spawn: SpawnPort;
-    readonly proc: ProcPort;
-    /**
-     * Runs immediately before the child's exit code propagates. The real `process.exit` never unwinds a `finally` block, so a caller with cleanup to do on the success path (releasing a headroom session registration, say) cannot rely on one; it passes the cleanup here instead.
-     */
-    readonly beforeExit?: () => void;
-}
-/**
- * Runs the real `claude` binary and propagates its exit code faithfully, the Node equivalent of the legacy bash tool's `exec` (process replacement): `spawnSync(bin, args, { stdio: "inherit" })` followed by `process.exit(status)`.
- *
- * Throws when the child could not even be spawned (e.g. `bin` does not exist) rather than silently exiting — a spawn failure is a real problem, not a clean exit code to propagate.
- */
-export declare function spawnClaude(params: SpawnClaudeParams): never;

package/dist/types/launcher.d.ts

@@ -1,98 +0,0 @@
-import type { LayoutPaths } from "./paths";
-import { type CliOverride } from "./launcher/cliOverride";
-import type { FarmFs, FsPort, FrontDoorPort, HeadroomPort, LogPort, ProcPort, SpawnPort } from "./launcher/ports";
-import { type CategoryClassification, type CategoryClassificationOverlay, type Pool } from "./config/schema";
-import { type CredentialPort } from "./credential";
-import type { CascadeInput } from "./resolve/walk";
-import type { DiscoveredClaudeBinary } from "./versionDiscovery";
-/**
- * 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.
- */
-export 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. */
-export 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;
-}
-/** Inputs to `runLauncher`: a launch's inputs plus the port that spawns the child. */
-export interface RunLauncherParams extends PrepareLaunchParams {
-    readonly spawn: SpawnPort;
-}
-/**
- * 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.
- */
-export 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.
- */
-export declare function prepareLaunch(params: PrepareLaunchParams): LaunchPlan;
-/**
- * Runs one `claude` launch: `prepareLaunch`, then the child under `params.spawn`, whose exit code becomes this process's.
- *
- * The session registrations are released twice by design: `beforeExit` covers the real success path (where `process.exit` never unwinds a `finally`), and the `finally` below covers a thrown spawn error, where it does.
- */
-export declare function runLauncher(params: RunLauncherParams): void;

package/dist/types/legacy.d.ts

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

package/dist/types/pathNorm.d.ts

@@ -1,14 +0,0 @@
-/**
- * Expands a leading `~` against `home`.
- *
- * Only a leading `~` alone or followed by a separator is expanded — `~other` is a literal name (a directory really called that), not another user's home directory, which this tool has no business resolving.
- */
-export declare function expandTilde(value: string, home: string): string;
-/**
- * Normalises a directory rule's `path` into an absolute filesystem path for comparison against a real directory.
- *
- * Rules are written with `~`-rooted paths far more often than absolute ones, and a rule that fails to match because of a trailing slash or a `..` segment fails silently — the launch just quietly ignores the rule. Normalising both sides identically is what stops that.
- */
-export declare function normaliseRulePath(rulePath: string, home: string): string;
-/** True when `ancestor` is `descendant` itself or one of its parent directories. Both are expected to be already normalised. */
-export declare function isAncestorOrSelf(ancestor: string, descendant: string): boolean;

package/dist/types/paths.d.ts

@@ -1,79 +0,0 @@
-/**
- * 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.
- */
-export 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.
- */
-export 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.
- */
-export declare function resolveClaudeHome(): string;
-/** Builds the full LayoutPaths structure from a given root directory. */
-export declare function buildLayoutPaths(root: string): LayoutPaths;
-/** Resolves AGENT_SHIM_HOME and builds the full LayoutPaths structure in one call. */
-export declare function resolveLayoutPaths(): LayoutPaths;

package/dist/types/poolPickReport.d.ts

@@ -1,44 +0,0 @@
-import type { Pool } from "./config/schema";
-import type { FarmFs, FsPort } from "./launcher/ports";
-import type { LayoutPaths } from "./paths";
-import type { Candidate } from "./usage/pick";
-/** What `pool pick` reports: the ranking a launch from `directory` would act on right now. */
-export 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[];
-}
-/**
- * Ranks a pool exactly as a launch from `directory` would right now, without recording a pick. Shares `rankPoolFromStore` with the launcher, so what this prints is what a launch does.
- */
-export declare function collectPoolPick(params: Readonly<{
-    paths: LayoutPaths;
-    fs: FsPort;
-    usageFs: FarmFs;
-    poolName: string;
-    pool: Pool;
-    directory: string;
-    nowMs: number;
-}>): PoolPickReport;
-export {};