agent-shim 7.12.0 → 7.13.0

package/dist/types/cli/pairs.d.ts

@@ -0,0 +1,19 @@
+/** One `<key>=<value>` pair, as parsed by `parsePair`. */
+export interface ParsedPair {
+    readonly key: string;
+    readonly value: string;
+}
+/**
+ * Splits `input` on its *first* `=` into a key and a value. The value may itself contain further `=` characters (they stay part of the value); only the first `=` is treated as the separator.
+ *
+ * Throws when there is no `=` at all, or when the key half is empty (`=true`, or a leading `=`).
+ */
+export declare function parsePair(input: string): ParsedPair;
+/** Parses `input` as a boolean in the shared vocabulary (`true`/`1`, `false`/`0`); throws on anything else. */
+export declare function parseBool(input: string): boolean;
+/**
+ * Parses a comma-separated list of `<key>=<bool>` pairs into a plain object, e.g. `"history=true,knowledge=false"` becomes `{ history: true, knowledge: false }`. Used only for the list-valued environment variables; flags repeat instead.
+ *
+ * An empty string parses to `{}`. A key repeated within the same list is not an error: the later occurrence wins, matching how a plain object literal with a repeated key behaves.
+ */
+export declare function parseBoolPairList(input: string): Record<string, boolean>;

package/dist/types/frontdoor/realFrontDoorPort.d.ts

@@ -0,0 +1,5 @@
+import type { FrontDoorPort } from "../launcher/ports";
+import type { LayoutPaths } from "../paths";
+import { type DaemonSpawner } from "../realPorts";
+/** The real `FrontDoorPort` for one launch: `ensure` runs the lock-and-poll coordination, authenticates the listener and registers this launcher; `release` removes its registration. */
+export declare function realFrontDoorPort(paths: LayoutPaths, spawnDaemon: DaemonSpawner): FrontDoorPort;

package/dist/types/frontdoor/trust.d.ts

@@ -0,0 +1,30 @@
+/** The file effects resolving a trust bundle needs, injected so the decision runs against fakes. */
+export interface TrustBundleFs {
+    /** Reads a file as UTF-8 text; throws when it cannot be read. */
+    readonly readFileUtf8: (file: string) => string;
+    /** Whether a file exists. */
+    readonly exists: (file: string) => boolean;
+    /** Creates a directory and any missing parents. */
+    readonly mkdirp: (dir: string) => void;
+    /** Writes a file atomically (a reader never sees a partial bundle). */
+    readonly writeFileAtomic: (file: string, contents: string) => void;
+}
+/** The CA bundle a routed child is pointed at through `NODE_EXTRA_CA_CERTS`, and why it differs from what the parent environment set, when it does. */
+export interface TrustBundle {
+    readonly path: string;
+    readonly warning?: string;
+}
+/**
+ * Decides the `NODE_EXTRA_CA_CERTS` a routed child gets. Node reads exactly one file from that variable, so a user who already set it (a corporate proxy's CA, say) would lose that trust if the launcher simply pointed it at agent-shim's CA. Instead:
+ *
+ * - nothing inherited: agent-shim's CA file itself;
+ * - an inherited file that already contains agent-shim's CA (a launch from inside a routed session): that file, unchanged;
+ * - any other readable inherited file: a combined bundle (the inherited certificates, then agent-shim's CA) written once under `bundlesDir`, named by its content hash so concurrent launches agree on it and a live child's file is never rewritten under it;
+ * - an inherited file that cannot be read: agent-shim's CA alone, with a warning naming the file. Node itself would have ignored that file with a warning, so the child loses no trust it would otherwise have had.
+ */
+export declare function resolveTrustBundle(params: {
+    readonly caCertFile: string;
+    readonly bundlesDir: string;
+    readonly inherited: string | undefined;
+    readonly fs: TrustBundleFs;
+}): TrustBundle;

package/dist/types/index.d.ts

@@ -11,6 +11,8 @@
  *
  * - `check` and `doctor` as data: `collectCheckReport` and `collectDoctorReport` read this machine and return the report, and the pure `runCheck` and `runDoctor` take the facts as parameters.
  *
+ * - launching: `prepareClaudeLaunch` resolves a launch for a directory on this machine and returns the binary, arguments and environment to spawn (performing the farm resync and daemon registration the child depends on), and `prepareLaunch` does the same over injected ports.
+ *
  * Everything the CLI alone needs (commander wiring and prompts) is deliberately not exported here.
  */
 export { resolveDecisions, topLevelNames, type ResolveDecisionsInput, type ResolvedState } from "./resolve/pipeline";
@@ -35,3 +37,5 @@ export { addPool, PoolNotFoundError, readPools, removePool, requirePool, setPool
 export { addDirectoryRule, DirectoryRuleAlreadyExistsError, DirectoryRuleMissingTargetError, DirectoryRuleNotFoundError, listDirectoryRules, readDirectoryRules, removeDirectoryRule, updateDirectoryRule, writeDirectoryRules, type AddDirectoryRuleOptions, type UpdateDirectoryRuleOptions, } from "./directoryRulesStore";
 export { checkReportHasWarnings, checkReportToJson, collectCheckReport, formatCheckReport, runCheck, type CheckReport, type CollectCheckReportParams, type RunCheckParams, } from "./checkReport";
 export { collectDoctorReport, formatDoctorReport, runDoctor, type CollectDoctorReportParams, type DoctorReport, type RunDoctorParams, } from "./doctorReport";
+export { prepareLaunch, type LaunchPlan, type PrepareLaunchParams } from "./launcher";
+export { LaunchRefusedError, prepareClaudeLaunch, type PrepareClaudeLaunchOptions } from "./launchWiring";

package/dist/types/launchWiring.d.ts

@@ -0,0 +1,49 @@
+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

@@ -0,0 +1,42 @@
+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/cliOverride.d.ts

@@ -0,0 +1,38 @@
+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

@@ -0,0 +1,6 @@
+/**
+ * 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/spawn.d.ts

@@ -0,0 +1,20 @@
+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

@@ -0,0 +1,98 @@
+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/realCredentialCache.d.ts

@@ -0,0 +1,11 @@
+import type { CredentialCacheEnv } from "./credential";
+import type { LayoutPaths } from "./paths";
+import { type CredentialCachePort } from "./credentialCache";
+/** A file name for an owner such as `identity work`: every character outside letters, digits, `.`, `_` and `-` becomes `_`, so no owner can name a path outside the cache directory. */
+export declare function cacheFileNameFor(owner: string): string;
+/**
+ * The real `CredentialCachePort`. The file store keeps one JSON file per owner under `<root>/credential-cache`, directory 0700 and file 0600. The Keychain store keeps the entry (base64 of its JSON, which has no spaces or quotes to escape) as a generic password under `KEYCHAIN_CACHE_SERVICE`, written through `security -i` on standard input so the token is never an argument. Both treat a missing or malformed entry as no entry.
+ */
+export declare function createRealCredentialCache(root: string): CredentialCachePort;
+/** The cache environment the real launcher hands the resolver: the real stores under this layout's root, this platform, and the wall clock. */
+export declare function realCredentialCacheEnv(paths: LayoutPaths): CredentialCacheEnv;

package/dist/types/realPorts.d.ts

@@ -38,6 +38,10 @@ export declare function detachedDaemonSpawnOptions(logFd: number, env: NodeJS.Pr
  * Spawns a detached supervisor: a background copy of this very executable running a hidden internal subcommand, its output appended to `logPath`, unref'd so the launcher never waits on it. `AGENT_SHIM_HOME` is passed explicitly so the supervisor lands on the same root as its spawner even when the launcher was started with the variable set only for itself.
  */
 export declare function spawnDetachedSupervisor(paths: LayoutPaths, subcommand: string, logPath: string): number;
+/** Starts a background daemon: `paths`, `subcommand` and `logPath` as for `spawnDetachedSupervisor`, which a caller that is not the agent-shim command line process supplies in place of it. */
+export type DaemonSpawner = (paths: LayoutPaths, subcommand: string, logPath: string) => number;
+/** A `DaemonSpawner` that starts daemons through the agent-shim executable at `executable`, for a caller (a library host) whose own process is not it. */
+export declare function spawnDaemonThrough(executable: string): DaemonSpawner;
 /**
  * Whether nothing is currently listening on one specific loopback port: binds it on 127.0.0.1 and releases, so the headroom supervisor can decide whether its sticky `lastPort` is still reusable. The same bind-and-release technique the supervisor's `freePort` uses, applied to a number the caller already cares about rather than asking the OS to pick one.
  */
@@ -45,7 +49,10 @@ export declare function realIsPortFree(port: number): Promise<boolean>;
 /**
  * The real `HeadroomPort` for one launch: `ensure` runs the lock-and-poll coordination against the real filesystem and process table and derives the per-project identity from the real git repository containing the working directory; `release` removes this launcher's session-registry entry.
  */
-export declare function realHeadroomPort(paths: LayoutPaths): HeadroomPort;
+export declare function realHeadroomPort(paths: LayoutPaths, options: {
+    readonly spawnDaemon: DaemonSpawner;
+    readonly cwd: string;
+}): HeadroomPort;
 /** The real `SpawnPort`, backed by `node:child_process`'s `spawnSync` — the Node equivalent of the legacy bash tool's `exec`. */
 export declare const realSpawnPort: SpawnPort;
 /** The real `ProcPort`, reading the actual process environment and logical CLI argv (`process.argv.slice(2)`). */

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "agent-shim",
-  "version": "7.12.0",
+  "version": "7.13.0",
   "description": "A profile manager and launcher for Claude Code that lets one person run multiple logins from one machine while controlling what gets shared between them.",
   "license": "MIT",
   "author": "Joseph Mearman <joseph@mearman.co.uk>",