agent-shim 7.13.1 → 7.14.0

package/dist/types/identityStore.d.ts

@@ -1,85 +0,0 @@
-import { type CredentialCache, type CredentialSource, type CredentialTarget, type Identity } from "./config/schema";
-import { CliError } from "./cliError";
-import type { LayoutPaths } from "./paths";
-/** Raised by any operation that requires an identity to already exist, when it does not. */
-export 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`. */
-export 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). */
-export declare class InvalidIdentityNameError extends CliError {
-    readonly attemptedName: string;
-    constructor(attemptedName: string);
-}
-export declare function identityExists(paths: LayoutPaths, name: string): boolean;
-/** Reads and validates one identity's `identity.json`, or undefined when it does not exist. */
-export 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.
- */
-export 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.
- */
-export declare function useIdentity(paths: LayoutPaths, name: string): void;
-/** Reads the persisted active-identity file, or undefined when none is set. */
-export 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.
- */
-export declare function isIdentityDirectoryName(name: string): boolean;
-/** One identity as reported by `listIdentities`, whose `identity.json` parsed and validated cleanly. */
-export 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. */
-export 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. */
-export 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`.
- */
-export 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.
- */
-export declare function setDefaultConfigProfile(paths: LayoutPaths, identityName: string, profileName: string | undefined): Identity;
-/**
- * Patches `identity`'s `allowAmbientCredential` field. Throws `IdentityNotFoundError` when the identity does not exist.
- */
-export 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. */
-export 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.
- */
-export 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.
- */
-export declare function removeIdentity(paths: LayoutPaths, name: string): void;

package/dist/types/launchWiring.d.ts

@@ -1,49 +0,0 @@
-import { CliError } from "./cliError";
-import type { Pool } from "./config/schema";
-import { type FarmRuntime, type LaunchPlan, type PrepareLaunchParams } from "./launcher";
-import type { LogPort, ProcPort } from "./launcher/ports";
-import { type LayoutPaths } from "./paths";
-import { type DaemonSpawner } from "./realPorts";
-/** Builds the farm runtime the launcher's resync step needs for a launch in `cwd`, wired to real filesystem, clock, git, and process facilities, plus the directory-scoped selections the launcher needs before it can resync anything. */
-export declare function buildFarmRuntime(paths: LayoutPaths, cwd: string): {
-    runtime: FarmRuntime;
-    directoryIdentity?: string;
-    directoryConfigProfile?: string;
-    globalDefaultConfigProfile?: string;
-    pools?: Readonly<Record<string, Pool>>;
-};
-/** Everything `realPrepareLaunchParams` takes beyond the state root: the process facts to launch against, the farm runtime for the directory, and whether a missing configuration profile was knowingly chosen. */
-export interface RealLaunchOptions {
-    readonly proc: ProcPort;
-    readonly farm: ReturnType<typeof buildFarmRuntime>;
-    readonly log: LogPort;
-    /** Starts the front door and headroom daemons when a launch needs them: the command line spawns itself, a library host names the agent-shim executable. */
-    readonly spawnDaemon: DaemonSpawner;
-    readonly allowMissingConfigProfile?: boolean;
-}
-/** The launcher's inputs wired to this machine: the real filesystem, daemon ports, credential resolver and `claude` binary discovery. */
-export declare function realPrepareLaunchParams(paths: LayoutPaths, options: RealLaunchOptions): PrepareLaunchParams;
-/** 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. */
-export declare class LaunchRefusedError extends CliError {
-    readonly exitCode: number;
-    constructor(message: string, exitCode: number);
-}
-/** What `prepareClaudeLaunch` needs from its caller. */
-export 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.
- */
-export declare function prepareClaudeLaunch(options: PrepareClaudeLaunchOptions): LaunchPlan;

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

@@ -1,42 +0,0 @@
-import { UsageError } from "../cliError";
-/** The result of parsing the launcher's own argv: the identity selection, any one-off `agent-shim` flags, and everything left to forward. */
-export interface ParsedLauncherArgv {
-    /** The identity named by a leading `@name` positional at argv[0] or by `--identity <name>`, when either was present. */
-    readonly identity?: string;
-    /** An explicit `--config-profile <name>` flag, when one was present. */
-    readonly configProfile?: string;
-    /** The last `--provider <name>` or `--no-provider` occurrence: a provider name, or `false` when `--no-provider` opted this launch out of any provider the cascade selects. Undefined when neither was given. */
-    readonly provider?: string | false;
-    /** The last `--headroom`/`--no-headroom` occurrence, when either was given. */
-    readonly headroom?: boolean;
-    /** The last `--track-usage`/`--no-track-usage` occurrence, when either was given. */
-    readonly trackUsage?: boolean;
-    /** The last `--wait`/`--no-wait` occurrence, when either was given: with a pool selected and every member refused, sleep until the earliest returns instead of refusing the launch. */
-    readonly wait?: boolean;
-    /** The last `--skip-permissions`/`--no-skip-permissions` occurrence, when either was given. */
-    readonly skipPermissions?: boolean;
-    /** The last `--remote-control`/`--no-remote-control` occurrence, when either was given. */
-    readonly remoteControl?: boolean;
-    /** Every `--category <cat>=<bool>` flag's raw value, in the order given: later values win on key collision when merged. */
-    readonly categoryFlags: readonly string[];
-    /** Every `--share <path>` flag's value, in the order given. */
-    readonly shareFlags: readonly string[];
-    /** Every `--hide <path>` flag's value, in the order given. */
-    readonly hideFlags: readonly string[];
-    /** Everything else, unchanged and in order: every token from a `--` terminator onwards (the `--` included), and any `@`-prefixed token that appears anywhere other than argv[0]. */
-    readonly rest: readonly string[];
-}
-/** Raised when a launch names its identity twice, through both a leading `@name` and `--identity`, with different names. */
-export declare class ConflictingIdentityError extends UsageError {
-    readonly positional: string;
-    readonly flag: string;
-    constructor(positional: string, flag: string);
-}
-/** Every flag `parseLauncherArgv` consumes, both forms of each boolean included: what `agent-shim completion` offers after `run`. */
-export declare const LAUNCHER_FLAG_NAMES: readonly string[];
-/**
- * Parses the launcher's own argv for its identity selection and the one-off `agent-shim` launch flags (`--identity`, `--config-profile`, `--provider`/`--no-provider`, `--category`, `--share`, `--hide`, and the `--[no-]headroom`, `--[no-]track-usage`, `--[no-]skip-permissions`, `--[no-]remote-control`, `--[no-]wait` booleans). None of these are real Claude Code flags, so all are consumed here and never forwarded.
- *
- * `name` in `@name` and `--identity <name>` may also be `pool:<pool>`, which the launcher resolves to a member of that pool. The `@name` form is consumed ONLY at argv[0], never mid-argument-list; `--identity <name>` is its explicit form, and naming two different identities through both throws `ConflictingIdentityError`. The flags are recognised only before a `--` terminator: from `--` onwards every token is forwarded verbatim, so `claude mcp add n -- cmd --provider x` keeps `--provider x` for `cmd`. Valued flags accept both `--flag value` and `--flag=value` and take exactly one value per occurrence; `--category`, `--share` and `--hide` repeat to supply several, and every other flag's later occurrence wins. A valued flag with no value after it (the last token, or directly before `--`) is left in place, untouched, since there is nothing to pair it with.
- */
-export declare function parseLauncherArgv(argv: readonly string[]): ParsedLauncherArgv;

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

@@ -1,42 +0,0 @@
-import { type ConfigFileReader } from "../config/load";
-import { type GlobalConfig } from "../config/schema";
-import { type CascadeInput, type ReadablePredicate } from "../resolve/walk";
-import type { LayoutPaths } from "../paths";
-/** The committed, team-shared portable config file name. A level with none falls back to the former `.claude-use.json`, and likewise for the local file, see `src/legacy.ts`. */
-export declare const PORTABLE_CONFIG_FILENAME = ".agent-shim.json";
-/** Its gitignored, per-clone personal sibling. */
-export declare const PORTABLE_LOCAL_CONFIG_FILENAME = ".agent-shim.local.json";
-/** Inputs to `loadCascadeInput`. */
-export interface LoadCascadeInputParams {
-    readonly paths: LayoutPaths;
-    readonly home: string;
-    /** The directory the cascade is being resolved for — already a real path, since resolving symlinks is the caller's job. */
-    readonly cwd: string;
-    readonly read: ConfigFileReader;
-    readonly isReadable?: ReadablePredicate;
-    /** The configuration profile the launcher's own precedence rules chose. */
-    readonly baseConfigProfile?: string;
-    readonly cliOverride?: CascadeInput["cliOverride"];
-}
-/** An assembled cascade input plus the global config it was built from, which the caller also needs for its own defaults. */
-export interface LoadedCascade {
-    readonly input: CascadeInput;
-    readonly globalConfig?: GlobalConfig;
-}
-/**
- * Loads every configuration file one launch's cascade is built from, and assembles them into the `CascadeInput` the pure resolver consumes.
- *
- * This is the only place file reading and cascade composition meet. Everything it produces is already-loaded data: `src/resolve/` never opens a file, and this module never decides what any of it means.
- *
- * Files are read with `loadConfigFile`, which wraps cosmiconfig's `load(filepath)` — never its `search()`, which stops at the first config found while walking upward. This design needs the exact opposite: every ancestor collected, shallowest-first, each one composing on top of the last.
- */
-export declare function loadCascadeInput(params: LoadCascadeInputParams): LoadedCascade;
-/**
- * Reads the deepest directory-level `identity` pin and `configProfile` selection that apply to a directory, without resolving the cascade.
- *
- * The launcher needs both *before* it can resync a farm — which identity a directory pins decides which farm there is to resync, and which profile it selects is an input to resolving that farm's contents — so they cannot come out of the resolved cascade itself.
- */
-export declare function readDirectorySelections(loaded: LoadedCascade): {
-    identity?: string;
-    configProfile?: string;
-};

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

@@ -1,38 +0,0 @@
-import { type CategoryMap, type Entries } from "../config/schema";
-import { CliError } from "../cliError";
-/** Raised when a `--category`/`AGENT_SHIM_CATEGORY_OVERRIDE` key names something other than one of the four overridable categories. */
-export declare class InvalidCliCategoryError extends CliError {
-    readonly categoryName: string;
-    constructor(categoryName: string);
-}
-/** Raised when a `--share`/`--hide`/`AGENT_SHIM_ENTRY_OVERRIDE` path is missing its required `<category>/` prefix. */
-export declare class InvalidCliEntryKeyError extends CliError {
-    readonly key: string;
-    constructor(key: string);
-}
-/** Inputs to `buildCliOverride`: the raw, still-unparsed flag values `parseLauncherArgv` collected (one value per flag occurrence), plus the environment for their `AGENT_SHIM_*_OVERRIDE` alternatives. */
-export interface BuildCliOverrideParams {
-    readonly env: Readonly<Record<string, string | undefined>>;
-    readonly providerFlag?: string;
-    readonly categoryFlags: readonly string[];
-    readonly shareFlags: readonly string[];
-    readonly hideFlags: readonly string[];
-}
-/** 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. */
-export interface CliOverride {
-    readonly categories?: CategoryMap;
-    readonly entries?: Entries;
-    readonly launch?: {
-        readonly provider?: string;
-    };
-}
-/**
- * Builds this launch's one-off category/entry overrides from `--category`/`--share`/`--hide` flags and their `AGENT_SHIM_CATEGORY_OVERRIDE`/`AGENT_SHIM_ENTRY_OVERRIDE` environment-variable alternatives.
- *
- * Each flag occurrence carries exactly one value (`--category history=true`, `--share knowledge/skills/commit`); the flags repeat rather than taking comma lists. The environment variables cannot repeat, so each holds a comma-separated list of `<key>=<bool>` pairs instead.
- *
- * The environment variable provides a base and the flags merge on top, later flag winning on key collision: the same "later occurrence wins" convention `agent-shim profile set --category`/`--entry` use, applied here because the flag and the environment variable are documented as equally-weighted alternatives for the same one-off override, not two different precedence tiers.
- *
- * Returns `undefined` when nothing at all was supplied, so a launch with no overrides adds no `cliOverride` layer rather than an empty no-op one. A malformed flag or environment value throws `UsageError`.
- */
-export declare function buildCliOverride(params: BuildCliOverrideParams): CliOverride | undefined;

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

@@ -1,6 +0,0 @@
-/**
- * Splits `$CLAUDE_EXTRA_FLAGS` into multiple argv entries on whitespace — confirmed against Joe's real dotfiles wrapper scripts, not a hypothetical requirement.
- *
- * `"--continue continue"` splits into `["--continue", "continue"]`, matching what wrappers like `cccc`/`mcc`/`occ`/`zcc`/`scc` rely on. Unset or empty input produces zero argv entries — `splitExtraFlags(undefined) === []` and `splitExtraFlags("") === []` — a naive `.split(" ")` would yield `[""]` for the empty case, a real bug this avoids rather than a hypothetical one. No wrapper script surveyed ever embeds a literal space inside one intended argument, so a plain whitespace split (collapsing any run of whitespace, not just a single space) is correct and sufficient; adding quote-aware parsing would only risk changing the meaning of a future value that happens to contain a quote character, for zero real benefit.
- */
-export declare function splitExtraFlags(value: string | undefined): string[];

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

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

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

@@ -1,96 +0,0 @@
-import type { LaunchFlags, Provider } from "../config/schema";
-import { type ResolvedCredential } from "../credential";
-import type { FrontDoorUp, HeadroomUp } from "./ports";
-/** The fully resolved launch flags for one launch. */
-export interface ResolvedLaunchFlags {
-    readonly skipPermissions: boolean;
-    readonly remoteControl: boolean;
-    readonly headroom: boolean;
-    /** Whether the launch routes through the front door so its requests are recorded, even with no provider and no headroom. */
-    readonly trackUsage: boolean;
-}
-/** The one-off command-line forms of the four boolean launch flags, each undefined when neither its positive nor its `--no-` form was given. */
-interface LaunchFlagOverrides {
-    readonly skipPermissions?: boolean;
-    readonly remoteControl?: boolean;
-    readonly headroom?: boolean;
-    readonly trackUsage?: boolean;
-}
-/** Inputs to `resolveLaunchFlags`. */
-export interface ResolveLaunchFlagsParams {
-    /** The cascade's resolved `launch` block, when a cascade was loaded for this launch. */
-    readonly cascade?: LaunchFlags;
-    /** The launch's own `--[no-]skip-permissions`, `--[no-]remote-control`, `--[no-]headroom` and `--[no-]track-usage` flags. */
-    readonly flags?: LaunchFlagOverrides;
-    readonly env: Readonly<Record<string, string | undefined>>;
-    /** What `trackUsage` is when no flag, environment variable or cascade setting says: off, except for a pool launch, whose pick reads the usage the front door records. */
-    readonly trackUsageDefault?: boolean;
-}
-/**
- * Resolves `skipPermissions`/`remoteControl`/`headroom`/`trackUsage` for one launch. Each setting has the same three forms, decided in the same order: an explicit command-line flag outright, then its environment variable (`AGENT_SHIM_SKIP_PERMISSIONS`, `AGENT_SHIM_REMOTE_CONTROL`, `AGENT_SHIM_HEADROOM`, `AGENT_SHIM_TRACK_USAGE`), then the cascade, and OFF when none of them says otherwise (`trackUsageDefault` changes that one fallback). The flag outranks the environment variable because it is the more deliberate of the two one-off forms (typed on this very command line, not inherited from a shell profile), and both outrank the cascade because they are one-off overrides of it.
- *
- * Environment variables read with the shared boolean vocabulary (`true`/`1`, `false`/`0`), so `AGENT_SHIM_SKIP_PERMISSIONS=0` switches off a cascade's `skipPermissions: true` for one launch; any other value throws `InvalidEnvBoolError`.
- *
- * This default-off posture is a deliberate change from the legacy bash tool, which passed `--dangerously-skip-permissions` unconditionally on every launch.
- */
-export declare function resolveLaunchFlags(params: ResolveLaunchFlagsParams): ResolvedLaunchFlags;
-/**
- * Builds the tool's own flag arguments from resolved launch flags.
- *
- * `--remote-control=` always carries a literal trailing `=` with an empty value — never bare `--remote-control` — confirmed as a deliberate fix in the legacy script's own git history to stop the flag from consuming the next positional argument as its value.
- */
-export declare function buildFlagArgs(flags: ResolvedLaunchFlags): string[];
-/** Inputs to `buildArgv`. */
-export interface BuildArgvParams {
-    readonly toolFlags: readonly string[];
-    readonly extraFlags: readonly string[];
-    readonly passthrough: readonly string[];
-}
-/**
- * Assembles the final argv passed to the real `claude` binary: tool flags, then `$CLAUDE_EXTRA_FLAGS`, then the user's own forwarded arguments, in that exact order.
- *
- * Extra flags must land BEFORE the passthrough args — confirmed load-bearing against real wrapper scripts (`cpl`, `mp`, `zpl`) that set `CLAUDE_EXTRA_FLAGS="--print"` and then pass a positional prompt afterwards; reversing this order would feed the prompt to `--print` as if it were a flag value instead of a trailing positional.
- */
-export declare function buildArgv(params: BuildArgvParams): string[];
-/** The provider resolved for this launch, with its credential already resolved from the provider's credential block. */
-export interface ResolvedProvider {
-    readonly name: string;
-    readonly definition: Provider;
-    readonly credential: ResolvedCredential;
-}
-/** A resolved provider with the base URL its sessions are sent to: the front door's provider-scoped address, which exists only once the door is up and is the same shape for both kinds (the door is what decides where the request goes from there). */
-export interface RoutedProvider extends ResolvedProvider {
-    readonly baseUrl: string;
-}
-/** Inputs to `buildEnv`. */
-export interface BuildEnvParams {
-    readonly baseEnv: Readonly<Record<string, string | undefined>>;
-    /** True when `CLAUDE_CONFIG_DIR` was already set and the escape hatch applied — `buildEnv` must leave it untouched in that case. */
-    readonly configDirEscapeHatch: boolean;
-    /** The identity name resolved for this launch, when one was resolved. */
-    readonly resolvedIdentityName?: string;
-    readonly identitiesDir: string;
-    /** The provider resolved for this launch, when one was resolved, with the base URL it routes to. Its credential is resolved by the caller because refusing an unusable one needs the caller's log/exit ports. */
-    readonly provider?: RoutedProvider;
-    /** The launching identity's own resolved credential, when it has a credential block and no provider was selected. A provider's credential authenticates against the provider's endpoint, so the identity's is never applied alongside one. */
-    readonly identityCredential?: ResolvedCredential;
-    /** The front door this launch routes through, when one is engaged (a provider is selected, or headroom resolved on). It is what the child talks to: its provider listener for a provider session, its CONNECT surface for an OAuth one. */
-    readonly frontdoor?: FrontDoorUp;
-    /** The headroom daemon this launch's requests must pass through (as the door's headroom hop), when headroom resolved on. The child never talks to it directly. */
-    readonly headroom?: HeadroomUp;
-    /** The per-launch session id, stamped into the session header the door identifies this launch's requests by. */
-    readonly sessionId: string;
-}
-/**
- * Builds the environment the real `claude` binary is spawned with.
- *
- * When the `CLAUDE_CONFIG_DIR`-already-set escape hatch applied, or no identity was resolved at all (a bare launch with no active identity, matching the legacy script's own "no profile means plain `~/.claude`" behaviour), `CLAUDE_CONFIG_DIR` is left untouched. Otherwise `CLAUDE_CONFIG_DIR` is set to the resolved identity's own directory under `identitiesDir` — farm population into that directory is Phase 5's job, not this function's.
- *
- * A resolved provider is applied regardless of the identity outcome, because it selects which API endpoint the child talks to, not which login's data it sees: `ANTHROPIC_BASE_URL` points at the provider's routed base URL (always the front door's provider-scoped address), `AGENT_SHIM_PROVIDER` names the provider for the statusline, the provider's own `env` entries land verbatim, and its resolved credential is exported as its target's variable (`credentialVariables`), with the other credential variables removed so an ambient one inherited from the parent cannot outrank it. Without a provider, an identity's own resolved credential is exported the same way. The token only ever reaches this environment, never the child's argv or a log line.
- *
- * A resolved front door is the whole of the child's routing, on top of the provider: `ANTHROPIC_CUSTOM_HEADERS` gains the launcher-injected session headers (identity, session id, the launch's capability token, and, when headroom resolved on, the headroom flag and the project identity headroom scopes memory to), merged with any headers the provider's own `env` or the parent environment already set. The door strips every one of them before anything leaves the machine; the token is what authorises the session's requests at the door in the first place. `NODE_EXTRA_CA_CERTS` points at the door's trust bundle in both modes, because the child reaches the door over TLS signed by agent-shim's CA either way. With a provider, the child's HTTPS base URL already names the door's provider listener, so a process that merely binds that port cannot present a certificate the child accepts. Without one (an OAuth launch), the base URL is left exactly as the parent environment had it, because Claude Code enables Remote Control and connectors only against the real `api.anthropic.com`; routing happens one layer down instead, with `HTTPS_PROXY` pointing the child at the door's CONNECT surface and carrying the launch's capability as its proxy credential (the surface refuses any CONNECT without a live one), so the child still believes it is talking to the real `api.anthropic.com` while the surface's terminated TLS feeds the routed paths to the same pipeline. `HEADROOM_PROXY_URL` names the headroom daemon for anything else that wants it; the child never talks to that daemon directly, the door's hop does.
- *
- * `$CLAUDE_EXTRA_FLAGS` is never stripped from the child's environment: some wrappers set it two process-levels up and rely on inheritance through a `claude` invoked from inside a running session.
- */
-export declare function buildEnv(params: BuildEnvParams): Record<string, string | undefined>;
-export {};

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

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