agent-shim 7.8.0 → 7.10.0

package/dist/types/checkReport.d.ts

@@ -0,0 +1,154 @@
+import { type CategoryClassification, type CategoryClassificationOverlay, type Identity, type Provider } from "./config/schema";
+import { type CredentialSummary } from "./credential";
+import { type AmbientCredentialGuardResult } from "./launcher/guard";
+import type { ConfigProfileDecisionSource, IdentityDecisionSource } from "./launcher/identity";
+import type { FarmFs, RunPort } from "./launcher/ports";
+import type { LayoutPaths } from "./paths";
+import type { PoolPickReport } from "./poolPickReport";
+import { type EncodingAmbiguity } from "./resolve/projects";
+import { type ResolvedState } from "./resolve/pipeline";
+import type { CascadeInput } from "./resolve/walk";
+import type { Decision, EntryFacts, FlattenedCascade } from "./resolve/types";
+/**
+ * Flags every `history/projects/` entries rule in scope whose encoded form could plausibly correspond to more than one real path.
+ *
+ * Reuses `src/resolve/projects.ts`'s own `detectEncodingAmbiguity` rather than reimplementing the detection — this function's whole job is recovering the as-written fragments from the flattened cascade's compiled rules and handing them to that function, plus the real project directory names already present in the fact manifest so the report can say how many a pattern actually matches today.
+ */
+export declare function flagAmbiguousEncodings(flattened: FlattenedCascade, facts: EntryFacts): EncodingAmbiguity[];
+/** Renders one entry's resolved decision as a single explanatory line, for `agent-shim check`'s printout. */
+export declare function formatDecision(decision: Decision): string;
+/** The result of looking up the macOS Keychain service name Claude Code is actually using for one identity's farm. */
+export interface KeychainLookupResult {
+    readonly checked: true;
+    readonly found: boolean;
+    readonly serviceName?: string;
+    readonly note: string;
+}
+/**
+ * Looks up the macOS Keychain entry Claude Code is using for one identity's configuration directory, via `security find-generic-password`, run through the injected `RunPort` so no test ever shells out for real.
+ *
+ * This is real OS state: the exact account/service naming Claude Code uses in the Keychain is empirically observed (per this project's README), not a documented contract, so genuinely exercising this against a real Keychain is a manual/integration check on a macOS runner, never something a unit test fakes convincingly — a unit test here can only prove that this function parses `security`'s own output shape correctly, not that the shape matches what a real installation produces.
+ */
+export declare function lookupKeychainService(run: RunPort, farmRoot: string): KeychainLookupResult;
+/** One file's reported settings exposure: names and counts only, never the underlying values. */
+export interface SettingsExposureReport {
+    readonly file: string;
+    readonly envKeyNames: readonly string[];
+    readonly hookEventNames: readonly string[];
+    readonly hookCommandCount: number;
+}
+/** Inputs to `inspectSettingsExposure`. */
+export interface InspectSettingsExposureParams {
+    /** Whether the `settings` category resolves shared for this launch — the advisory only has anything to report when it does. */
+    readonly settingsShared: boolean;
+    /** Raw file contents keyed by filename (`settings.json`, `settings.local.json`), undefined when the file does not exist. */
+    readonly files: Readonly<Record<string, string | undefined>>;
+}
+/**
+ * Reports how many `env` keys and `hooks` commands `settings.json`/`settings.local.json` would share, by name and count only — never a value, per the README's own warning that a hook command or an `env` entry there can easily hold a real secret with nothing in Claude Code's own documentation warning against it.
+ *
+ * Returns nothing at all when `settingsShared` is false, and nothing for a file whose `env`/`hooks` fields are both empty or absent — the whole point of this advisory is to be silent unless there is something worth a second look.
+ */
+export declare function inspectSettingsExposure(params: InspectSettingsExposureParams): SettingsExposureReport[];
+/** The provider the cascade selects for this directory, as the wiring layer loaded it: its definition, or why it could not be used (no such provider, an invalid or old-format file). */
+type CheckProviderInput = {
+    readonly name: string;
+    readonly definition: Provider;
+    readonly problem?: never;
+} | {
+    readonly name: string;
+    readonly definition?: never;
+    readonly problem: string;
+};
+/**
+ * Which credential a launch here would use, by source kind and target only: a selected provider's credential block always wins; otherwise the identity's own credential block; otherwise the login stored in the identity's directory.
+ */
+interface CredentialReport {
+    readonly applies: "provider" | "identity" | "stored-login";
+    readonly provider?: {
+        readonly name: string;
+        readonly credential?: CredentialSummary;
+        readonly problem?: string;
+    };
+    readonly identity?: CredentialSummary;
+}
+/** Inputs to `runCheck` — everything already loaded/injected, exactly like the resolver core and the launcher: nothing in this function touches a real filesystem, git repository, clock, or environment itself. */
+export interface RunCheckParams {
+    readonly cwd: string;
+    readonly home: string;
+    readonly claudeHome: string;
+    readonly env: Readonly<Record<string, string | undefined>>;
+    readonly branch?: string;
+    readonly branchDetached?: boolean;
+    readonly nowMs: number;
+    /** Used only to build the fact manifest by reading the canonical `~/.claude` tree — `runCheck` never mutates the farm and never spawns anything. */
+    readonly farmFs: FarmFs;
+    readonly cascade: CascadeInput;
+    readonly classification: {
+        readonly defaults: CategoryClassification;
+        readonly overlay?: CategoryClassificationOverlay;
+    };
+    readonly identityName?: string;
+    readonly identitySource: IdentityDecisionSource;
+    /** The pool the launch selected and how it ranks right now, when it named a pool instead of an identity; `identityName` is then the member it would pick. */
+    readonly poolPick?: PoolPickReport;
+    readonly configProfileName?: string;
+    readonly configProfileSource: ConfigProfileDecisionSource;
+    /** The resolved identity's own `identity.json`, when one was found. */
+    readonly identity?: Identity;
+    /** Raw `settings.json`/`settings.local.json` contents, keyed by filename, undefined when a file does not exist. */
+    readonly settingsFiles: Readonly<Record<string, string | undefined>>;
+    /** Runs `security find-generic-password` for the Keychain diagnostic. Omit to skip that diagnostic entirely (e.g. off macOS, or when no identity/farm root is known). */
+    readonly run?: RunPort;
+    /** The identity's own farm root — `security`'s lookup account. Required alongside `run` for the Keychain diagnostic to run at all. */
+    readonly farmRoot?: string;
+    /** `process.platform` in real use; the Keychain diagnostic only ever runs when this is `"darwin"`. */
+    readonly platform: string;
+    /** The provider a launch here would route through (`launch.provider` in the cascade), when one is selected. */
+    readonly provider?: CheckProviderInput;
+}
+/** Everything `agent-shim check` reports about one directory/identity, without touching the farm or spawning anything. */
+export interface CheckReport {
+    readonly identityName?: string;
+    readonly identitySource: IdentityDecisionSource;
+    readonly poolPick?: PoolPickReport;
+    readonly configProfileName?: string;
+    readonly configProfileSource: ConfigProfileDecisionSource;
+    readonly resolved: ResolvedState;
+    readonly decisionLines: readonly string[];
+    readonly projectEncodingAmbiguities: readonly EncodingAmbiguity[];
+    readonly ambientCredential: AmbientCredentialGuardResult;
+    readonly keychain?: KeychainLookupResult;
+    readonly settingsExposure: readonly SettingsExposureReport[];
+    readonly credential: CredentialReport;
+}
+/**
+ * Resolves the full cascade for one directory/identity and reports everything `agent-shim check` documents: every entry's resolved state and which layer/condition decided it, any ambiguous `history/projects/` encoding in scope, and the three always-on diagnostics (ambient-credential exposure, macOS Keychain service name, settings-secrets exposure).
+ *
+ * Deliberately reuses the same cascade machinery a real launch uses — `resolveDecisions` and `buildEntryFacts` — rather than reimplementing any part of resolution. The one thing this function never does that a launch does is touch the farm or spawn anything: it only reads the canonical `~/.claude` tree to build the fact manifest resolution needs, and every other input (cascade, classification, settings file contents, the Keychain lookup) is handed in already loaded.
+ */
+export declare function runCheck(params: RunCheckParams): CheckReport;
+/** Renders a full `CheckReport` as plain text lines, in the order `agent-shim check` prints them. */
+export declare function formatCheckReport(report: CheckReport): string[];
+/**
+ * The `check --json` form of a report: every field the text form prints, as plain data (no `Map`s, no compiled matchers), so a script can read the same verdicts a person would.
+ */
+export declare function checkReportToJson(report: CheckReport): Record<string, unknown>;
+/**
+ * Whether a report carries anything `check --strict` fails on: a resolver diagnostic of warning or error severity, an ambiguous `history/projects/` encoding, an ambient credential a launch would refuse, or a selected provider a launch could not use. Informational diagnostics and the settings-exposure advisory (names and counts only, for a person to review) never fail it.
+ */
+export declare function checkReportHasWarnings(report: CheckReport): boolean;
+/** What `collectCheckReport` needs from its caller. */
+export interface CollectCheckReportParams {
+    readonly paths: LayoutPaths;
+    /** The directory a launch would run in; resolved against the working directory by the caller. */
+    readonly cwd: string;
+    /** The identity to check, as `--identity` names it; absent means the identity a launch there would resolve. */
+    readonly identity?: string;
+    readonly env: NodeJS.ProcessEnv;
+}
+/**
+ * Resolves what a launch in `params.cwd` would share or hide, and why, against this machine: the edge adapter that reads the real filesystem, clock, git and keychain, resolves the identity, configuration profile and cascade exactly as a launch does, and hands the facts to the pure `runCheck`. Never touches the farm or spawns claude.
+ */
+export declare function collectCheckReport(params: CollectCheckReportParams): CheckReport;
+export {};

package/dist/types/claudeShim.d.ts

@@ -0,0 +1,114 @@
+import type { Command } from "commander";
+import { z } from "zod";
+import { type CommandDeps } from "./cli/commandDeps";
+import { CliError } from "./cliError";
+import type { LayoutPaths } from "./paths";
+export declare const ClaudeShimStateSchema: z.ZodObject<{
+    targetPath: z.ZodString;
+    method: z.ZodEnum<{
+        copy: "copy";
+        hardlink: "hardlink";
+    }>;
+    installedAtMs: z.ZodNumber;
+}, z.core.$strict>;
+export type ClaudeShimState = z.infer<typeof ClaudeShimStateSchema>;
+/** Raised by enableClaudeShim/disableClaudeShim when the target path exists but doesn't look like agent-shim's own doing (no matching claude-shim.json marker, and not a hardlink of the currently-running executable) — refuses rather than silently clobbering or deleting something an installer never created. Bypassed by --force. */
+export declare class ForeignClaudeEntryError extends CliError {
+    readonly targetPath: string;
+    readonly action: "enable" | "disable";
+    constructor(targetPath: string, action: "enable" | "disable");
+}
+/** Raised by enableClaudeShim when the running executable cannot possibly be turned into a directly-runnable `claude` command: an npm/Node install of agent-shim on Windows, which has no bundled .exe and no shebang-based dispatch the way POSIX does. Not bypassed by --force — this isn't a safety refusal, it's "this would produce a broken file." */
+export declare class UnsupportedShimSourceError extends CliError {
+    readonly contentSourcePath: string;
+    constructor(contentSourcePath: string);
+}
+/**
+ * The exact filename to create: `claude.exe` when the running executable is itself a `.exe` (Windows needs the extension to recognise it as directly executable at all), `claude` for every other case.
+ *
+ * Deliberately not "preserve whatever extension the source has" — an npm install's own file is `cli.cjs`, and a bare `claude` (not `claude.cjs`) is what makes it invocable as the expected command on POSIX, where a shebang plus the executable bit is what matters, not the filename's extension.
+ */
+export declare function claudeTargetFilename(ownExecutablePath: string): string;
+/** The same rule generalised to any command name this tool owns, so `doctor`'s PATH-resolution check can ask "what filename would a bare `agent-shim` be" without restating the Windows `.exe` condition and letting the two drift apart. */
+export declare function commandFilename(ownExecutablePath: string, commandName: string): string;
+/**
+ * `cli.ts`'s own name-dispatch check: is `invokedName` (the basename of however this binary was invoked) one of the two names `shim enable` ever creates, per `claudeTargetFilename` above? `path.basename` includes the file extension, so a bare `=== "claude"` comparison never matches the Windows case, where the file must be named `claude.exe` to be directly invocable at all.
+ *
+ * Confirmed as a real, previously-undetected bug against an actual Scoop install: the shim-placement and hardlink-source bugs fixed in prior releases had never let a Windows `claude.exe` invocation reach this far before, so this exact mismatch never surfaced until the shim itself finally worked end-to-end — invoking the newly-created `claude.exe` fell through to agent-shim's own CLI (printing its own `--version`) instead of the launcher.
+ */
+export declare function isInvokedAsClaude(invokedName: string): boolean;
+/**
+ * The directories `discoverClaudeBinary`'s PATH-fallback search must exclude to avoid recursively discovering/spawning this very tool: wherever the running executable itself lives, plus wherever `shim enable` last placed a `claude`-named copy, when that's a *different* directory (i.e. `--dir` was used). Without folding the recorded shim directory in here too, `agent-shim run`/`agent-shim doctor` would only exclude their own directory, not a `--dir`-placed shim living elsewhere on PATH.
+ */
+export declare function resolveOwnInstallDirs(paths: LayoutPaths, ownExecutablePath: string): string[];
+/** Where `shim enable` places `claude` absent a --dir override: alongside the running executable. */
+export declare function resolveClaudeTargetPath(ownExecutablePath: string, dir?: string): string;
+/** The two low-level fs calls the hardlink-then-copy-fallback needs, matching `src/config/store.ts`'s own `StoreFs`/`nodeStoreFs`-with-a-real-default pattern — the one seam in this file that isn't plain `node:fs`, added so the EXDEV fallback branch gets real unit coverage without a genuine cross-filesystem test rig. */
+export interface LinkFs {
+    readonly link: (existingPath: string, newPath: string) => void;
+    readonly copyFile: (src: string, dest: string) => void;
+    readonly chmod: (target: string, mode: number) => void;
+}
+/** Inputs to `enableClaudeShim`. */
+export interface EnableShimParams {
+    readonly paths: LayoutPaths;
+    /** `realOwnExecutablePath()` (see realPorts.ts) — the PATH-visible location `claude` should be placed alongside, supplied by the wiring layer. Deliberately separate from `contentSourcePath` below: for a Scoop install, this is `~/scoop/shims/agent-shim.exe` (Scoop's own proxy binary, not agent-shim's real content), and using it as the link/copy source would hardlink that proxy instead of the genuine executable. */
+    readonly ownExecutablePath: string;
+    /** `realContentSourcePath()` (see realPorts.ts) — the actual file whose content is this running process, used as the hardlink/copy source and for "is the existing target mine" inode comparisons. */
+    readonly contentSourcePath: string;
+    /** process.platform, supplied by the wiring layer — only used for the Windows/npm-source guard. */
+    readonly platform: string;
+    readonly dir?: string;
+    readonly force: boolean;
+}
+type EnableShimAction = "enabled" | "reenabled";
+export interface EnableShimResult {
+    readonly action: EnableShimAction;
+    readonly targetPath: string;
+    readonly method: "hardlink" | "copy";
+}
+/**
+ * Creates a `claude`-named hardlink (falling back to a copy on a cross-device filesystem) of the currently running `agent-shim` executable, so `claude @<name>` works directly instead of needing `agent-shim run`.
+ *
+ * A target that already exists is only ever overwritten when it's provably agent-shim's own doing — either it shares an inode with the currently-running executable (covers a pre-existing install from before this feature existed, where no marker could possibly exist yet), or claude-shim.json records this exact target path (covers refreshing after a agent-shim upgrade, when the old target's inode no longer matches the new binary's content). Anything else is refused unless `force` is set — this could otherwise silently delete or overwrite someone's genuine, unrelated `claude` binary.
+ */
+export declare function enableClaudeShim(params: EnableShimParams, linkFs?: LinkFs): EnableShimResult;
+type DisableShimAction = "disabled" | "not-enabled";
+export interface DisableShimResult {
+    readonly action: DisableShimAction;
+    readonly targetPath: string;
+}
+export interface DisableShimParams {
+    readonly paths: LayoutPaths;
+    /** `realOwnExecutablePath()` — the PATH-visible location, used to derive the default target path. */
+    readonly ownExecutablePath: string;
+    /** `realContentSourcePath()` — used for the "is the existing target mine" inode comparison; see `EnableShimParams` for why this must be separate from `ownExecutablePath`. */
+    readonly contentSourcePath: string;
+    readonly dir?: string;
+    readonly force: boolean;
+}
+/** The inverse of `enableClaudeShim`: removes the `claude` command it created, using the same "is this ours" safety check. A no-op, not an error, when nothing is enabled — including clearing a dangling marker whose target has since been deleted by other means. */
+export declare function disableClaudeShim(params: DisableShimParams): DisableShimResult;
+export type PathShadowStatus = {
+    readonly status: "ok";
+} | {
+    readonly status: "not-on-path";
+} | {
+    readonly status: "shadowed";
+    readonly by: string;
+};
+export interface FindPathShadowParams {
+    readonly pathDirs: readonly string[];
+    readonly targetDir: string;
+    readonly targetFilename: string;
+    readonly findExecutableInDir: (dir: string, name: string) => string | undefined;
+}
+/** Would something else on PATH run before the just-enabled `claude`? Reuses the exact PATH-scan semantics `discoverClaudeBinary`'s own fallback already uses (via the injected `findExecutableInDir`), rather than shelling out to `command -v` — this answers a more directly relevant question ("would this tool's own binary discovery find this file first") without spawning a process at all. */
+export declare function findPathShadow(params: FindPathShadowParams): PathShadowStatus;
+/**
+ * Registers `agent-shim shim enable`/`agent-shim shim disable` onto `program`.
+ *
+ * `shim` is a deliberate noun-group, matching `identity`/`profile`/`rule`: it names the actual mechanism (a PATH-level executable that dispatches by invoked name, the same concept Scoop itself calls a "shim"), so `enable`/`disable` read as toggling one clearly-scoped thing rather than "installing"/"uninstalling" software, which could be misread as installing Claude Code itself.
+ */
+export declare function registerShimCommand(program: Command, deps: CommandDeps): void;
+export {};

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

@@ -0,0 +1,28 @@
+import type { Command } from "commander";
+import type { PromptsPort } from "../configure";
+import type { LayoutPaths } from "../paths";
+/**
+ * What every `agent-shim` command's registration needs from `buildProgram`: where the config tree lives, the prompt surface, whether standard input is a terminal those prompts can run on, and how to end the process.
+ *
+ * `isInteractive` is a function rather than a snapshot so the real wiring reads `process.stdin.isTTY` at the moment a command runs, and a test can script both answers against the same program.
+ */
+export interface CommandDeps {
+    readonly paths: LayoutPaths;
+    readonly prompts: PromptsPort;
+    readonly isInteractive: () => boolean;
+    /** Ends the process with `code` immediately. Only the long-running `__headroom-supervisor` and `__codex-supervisor` need it (a signal must terminate it, and its servers would otherwise keep the event loop alive); every other command sets `process.exitCode` or throws, so its output is never truncated. */
+    readonly exit: (code: number) => never;
+}
+/** Prints `value` as indented JSON on standard output: the one `--json` output format every `list`, `show`, `check`, `doctor` and `headroom status` command shares. */
+export declare function printJson(value: unknown): void;
+/**
+ * Appends an `Examples:` block to `command`'s help output, one `$ agent-shim ...` line per entry. Every command registers at least one, so `--help` on any of them shows a runnable invocation, not just its option list.
+ */
+export declare function withExamples(command: Command, examples: readonly string[]): Command;
+/**
+ * The confirmation every destructive `remove` verb shares. `--yes` skips it; otherwise a terminal gets a yes/no prompt (declining throws `PromptCancelledError`), and a non-terminal throws `MissingInputError` naming `--yes`, since deleting without either would be a silent destructive default.
+ * @param deps - The prompt surface and terminal check.
+ * @param yes - Whether `--yes` was passed.
+ * @param description - What would be removed, phrased to follow "Remove ", e.g. `identity "work" and its directory`.
+ */
+export declare function confirmRemoval(deps: CommandDeps, yes: boolean | undefined, description: string): Promise<void>;

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

@@ -0,0 +1,11 @@
+import { UsageError } from "../cliError";
+/** Raised when a boolean environment variable holds something outside the shared vocabulary. */
+export declare class InvalidEnvBoolError extends UsageError {
+    readonly variable: string;
+    readonly value: string;
+    constructor(variable: string, value: string);
+}
+/**
+ * Reads a boolean environment variable with the same vocabulary a CLI flag value uses. Unset and the empty string both mean "not given" (undefined), consistent with how every other agent-shim environment variable treats the empty string; anything outside the vocabulary throws `InvalidEnvBoolError` rather than silently reading as false.
+ */
+export declare function parseEnvBool(variable: string, value: string | undefined): boolean | undefined;

package/dist/types/codex/http.d.ts

@@ -0,0 +1,15 @@
+/** The HTTP statuses the codex route and its listener answer with, named so every use says what it means. */
+export declare const HTTP_STATUS: {
+    readonly ok: 200;
+    readonly badRequest: 400;
+    readonly unauthorized: 401;
+    readonly forbidden: 403;
+    readonly notFound: 404;
+    readonly methodNotAllowed: 405;
+    readonly payloadTooLarge: 413;
+    readonly tooManyRequests: 429;
+    /** Not sent to anyone: the client is gone. Recorded for a response abandoned because the client disconnected, following the convention nginx uses for the same case. */
+    readonly clientClosedRequest: 499;
+    readonly internalServerError: 500;
+    readonly badGateway: 502;
+};

package/dist/types/configure.d.ts

@@ -0,0 +1,170 @@
+import type { Command } from "commander";
+import { type CommandDeps } from "./cli/commandDeps";
+import { CliError, UsageError } from "./cliError";
+import type { LogPort } from "./launcher/ports";
+import { type LayoutPaths } from "./paths";
+/** Raised by `configure` when no configuration profile resolves for the identity at the working directory, so there is no tier-three file for a toggle to land in. */
+export declare class NoConfigProfileResolvedError extends CliError {
+    readonly identityName: string;
+    readonly cwd: string;
+    constructor(identityName: string, cwd: string);
+}
+/** Raised by `configure` when standard input is not a terminal: every step of it is a prompt, so there is no non-interactive form to fall back to. */
+export declare class ConfigureNeedsTerminalError extends UsageError {
+    constructor();
+}
+/** Raised by `configure` when no `--identity` was given and nothing else (the environment, a directory pin, the active identity) resolves one. */
+export declare class NoIdentityResolvedError extends UsageError {
+    readonly cwd: string;
+    constructor(cwd: string);
+}
+/** One selectable option, shared by `select` and `multiselect`. */
+interface PromptOption<Value extends string> {
+    readonly value: Value;
+    readonly label: string;
+    readonly hint?: string;
+    /** Visible but not selectable — used for the `secret` category, which no configuration layer may ever toggle. */
+    readonly disabled?: boolean;
+}
+/** Parameters shared by a single-select prompt. */
+export interface SelectParams<Value extends string> {
+    readonly message: string;
+    readonly options: readonly PromptOption<Value>[];
+    /** Which option the cursor starts on. Omit to let the prompt library fall back to its own default (the first option) — pass this explicitly whenever the safest or most common answer isn't the first one listed, so the on-screen reading order and the default-on-Enter answer can differ deliberately rather than being forced to match. */
+    readonly initialValue?: Value;
+}
+/** Parameters for a multi-select prompt. */
+export interface MultiselectParams<Value extends string> {
+    readonly message: string;
+    readonly options: readonly PromptOption<Value>[];
+    readonly initialValues?: readonly Value[];
+}
+/** Parameters for a free-text prompt. */
+export interface TextParams {
+    readonly message: string;
+    readonly placeholder?: string;
+    /** Returns an error string to reject the value and re-prompt, or `undefined` to accept it. */
+    readonly validate?: (value: string) => string | undefined;
+}
+/**
+ * The interactive-prompt surface `runConfigure` needs, abstracted so it can be driven by a scripted sequence of pre-programmed answers in tests instead of a real TTY — the same injected-ports pattern `src/launcher/ports.ts` already uses for the filesystem, spawn, and clock.
+ *
+ * `select`/`multiselect`/`text` resolve to a `symbol` when the user cancels (Ctrl-C), mirroring `@clack/prompts`' own cancellation contract exactly, so `isCancel` is the one place that distinguishes a real answer from a cancellation.
+ */
+export interface PromptsPort {
+    readonly select: <Value extends string>(params: SelectParams<Value>) => Promise<Value | symbol>;
+    readonly multiselect: <Value extends string>(params: MultiselectParams<Value>) => Promise<readonly Value[] | symbol>;
+    readonly text: (params: TextParams) => Promise<string | symbol>;
+    /** A type guard, mirroring `@clack/prompts`' own `isCancel` exactly, so a passing check narrows `Value | symbol` down to `Value` at every call site without a further cast. */
+    readonly isCancel: (value: unknown) => value is symbol;
+    readonly cancel: (message?: string) => void;
+    readonly intro: (message?: string) => void;
+    readonly outro: (message?: string) => void;
+}
+export declare const realPromptsPort: PromptsPort;
+/** Where one toggle should be written, per the README's "agent-shim configure: which file it writes to" precedence. */
+export type WriteTarget = {
+    readonly tier: "portable-local";
+    readonly localConfigPath: string;
+} | {
+    readonly tier: "directory-rule";
+    readonly rulePath: string;
+} | {
+    readonly tier: "config-profile";
+    readonly profileName: string;
+};
+/** One directory level's portable-config presence, shallowest-first — as produced by `walkDirectoryAncestors` plus a filesystem existence check at each level. */
+export interface DirectoryLevelPresence {
+    readonly dir: string;
+    /** Whether a committed `.agent-shim.json` already exists at this level. */
+    readonly hasPortable: boolean;
+    /** Whether a gitignored `.agent-shim.local.json` already exists at this level, independent of whether a committed sibling does — this is what makes tier one apply even when only a personal local override was ever created, with no committed file alongside it. */
+    readonly hasPortableLocal: boolean;
+    /** The personal local file a toggle at this level is written into: the former `.claude-use.local.json` when that is the only one that exists, so its settings are not shadowed by a new file, otherwise `.agent-shim.local.json`. */
+    readonly portableLocalFilename: string;
+}
+/** Inputs to `chooseWriteTarget`. */
+export interface ChooseWriteTargetParams {
+    readonly cwd: string;
+    readonly home: string;
+    /** `cwd`'s ancestor levels, shallowest-first, each flagged with whether a portable/portable-local file already exists there. */
+    readonly levels: readonly DirectoryLevelPresence[];
+    /** Every directory rule's own `path` field, exactly as written in `~/.agent-shim/directory-rules.json` (not yet normalised). */
+    readonly directoryRulePaths: readonly string[];
+    /** The identity's resolved active configuration profile — the tier-three fallback. */
+    readonly activeConfigProfile: string;
+}
+/**
+ * Decides which file a `configure` toggle should be written into, in the exact three-tier precedence the README documents:
+ *
+ * 1. If `$PWD` is inside a directory covered by a committed `.agent-shim.json`, or a `.agent-shim.local.json` already exists there (even without a committed sibling), the toggle goes into `.agent-shim.local.json` in that same directory — the deepest such directory, when more than one ancestor qualifies.
+ * 2. Otherwise, if an existing directory rule in the user's own `directory-rules.json` already applies to `$PWD` (its `path`, once resolved, is an ancestor of or equal to `$PWD`), the toggle is written into that rule — the most specific (longest-resolved-path) matching rule, when more than one applies.
+ * 3. Otherwise, the toggle is written into the identity's own active configuration profile.
+ *
+ * Never touches a filesystem or a config file itself — every input is already gathered by the caller, which is what makes this function directly unit-testable with synthetic levels and rule paths.
+ */
+export declare function chooseWriteTarget(params: ChooseWriteTargetParams): WriteTarget;
+/** Renders a `WriteTarget` as a short, human-readable description for `configure`'s own confirmation output. */
+export declare function describeWriteTarget(target: WriteTarget): string;
+/** Everything `runConfigure` needs beyond the identity/path the user typed. */
+export interface RunConfigureDeps {
+    readonly paths: LayoutPaths;
+    readonly prompts: PromptsPort;
+    readonly log: Pick<LogPort, "info">;
+}
+/** Inputs to `runConfigure` beyond its injected dependencies. */
+export interface RunConfigureParams {
+    readonly identityName: string;
+    /** A real `~/.claude`-relative path (never category-prefixed — that prefix is an entries-*key* convention, not a filesystem path). Given: entries mode. Omitted: categories mode. */
+    readonly path?: string;
+    readonly cwd: string;
+    readonly home: string;
+    readonly claudeHome: string;
+}
+/** Validates a candidate profile name for the wizard's text prompt: non-empty, matches the allowed shape, and (only when `existingNames` is given) not already taken. */
+export declare function validateProfileName(value: string, existingNames?: readonly string[]): string | undefined;
+/**
+ * Inputs to `runProfileWizard` beyond the injected prompt/log ports. Split out so the launch path (which only has a `LayoutPaths`, not a full `ConfigureContext`) can call the wizard too.
+ *
+ * A discriminated union over three modes:
+ * - `{ existingName }`: edit an existing profile's categories.
+ * - `{ createName }`: create a new profile with this exact name (no name prompt), then choose categories. Used by the launch path, where the name is already decided.
+ * - `{ defaultNewName? }`: create a new profile, prompting for a name first (with an optional pre-filled default). Used by the manual commands.
+ */
+export type RunProfileWizardParams = {
+    readonly paths: LayoutPaths;
+    readonly existingName: string;
+} | {
+    readonly paths: LayoutPaths;
+    readonly createName: string;
+} | {
+    readonly paths: LayoutPaths;
+    readonly defaultNewName?: string;
+};
+/** What `runProfileWizard` produced. */
+export interface ProfileWizardResult {
+    readonly name: string;
+    readonly created: boolean;
+}
+/**
+ * The unified create-or-edit flow for a configuration profile: one guided prompt sequence covering both cases that would otherwise split across a bare `profile add` (empty, no categories) and `configure`'s "edit a profile directly" branch (categories only, profile must already exist).
+ *
+ * Given an `existingName`: edits that profile's categories in place via a multiselect, seeded from its current values. Given a `createName`: creates the empty file with that exact name, no name prompt, then runs the category multiselect. Given neither: prompts for a name first (validated against the allowed shape and against every existing profile name), creates the empty file, then runs the same multiselect. Either way, a cancel at any prompt writes nothing and returns `undefined` — the caller decides what to do (e.g. the launch path proceeds without the profile, the manual command just stops).
+ *
+ * Driven entirely by the injected `PromptsPort` so the whole flow is unit-testable with a scripted sequence of answers, the same way `runConfigure` already is.
+ */
+export declare function runProfileWizard(prompts: PromptsPort, params: RunProfileWizardParams): Promise<ProfileWizardResult | undefined>;
+/**
+ * Runs `agent-shim configure [path] --identity <name>`'s interactive flow.
+ *
+ * Two modes, exactly per the README's "agent-shim configure: which file it writes to" section:
+ *
+ * - No `path`: shows the identity's resolved top-level categories (the only mode that ever touches categories), plus an option to edit a named configuration profile's own stored values directly instead.
+ * - Given a `path` (a real `~/.claude`-relative path, never category-prefixed): shows that path's direct children with their resolved sharing state, for fine-grained entries overrides. Never shows or edits categories.
+ *
+ * Every actual toggle (in either mode, other than the "edit a profile directly" branch, which is an explicit target the user chose) is written via `chooseWriteTarget`'s three-tier precedence.
+ */
+export declare function runConfigure(deps: RunConfigureDeps, params: RunConfigureParams): Promise<void>;
+/** Registers `agent-shim configure [path] [--identity <name>]` onto `program`. */
+export declare function registerConfigureCommand(program: Command, deps: CommandDeps): void;
+export {};

package/dist/types/doctorReport.d.ts

@@ -0,0 +1,117 @@
+import { type ClaudeShimState, type PathShadowStatus } from "./claudeShim";
+import type { LayoutPaths } from "./paths";
+import type { RunPort } from "./launcher/ports";
+import type { DiscoveredClaudeBinary } from "./versionDiscovery";
+type DoctorSeverity = "pass" | "warn" | "fail";
+type DoctorSection = "ambient-credential" | "binary-discovery" | "claude-shim" | "path-resolution" | "legacy-name" | "config-profile" | "identity" | "pool" | "provider" | "keychain" | "directory-rules" | "global-config" | "categories-local" | "active-identity" | "headroom";
+/** One line of `agent-shim doctor`'s report. `subject` names the identity/profile/rule the finding is about, when the section has more than one of those. */
+interface DoctorFinding {
+    readonly section: DoctorSection;
+    readonly subject?: string;
+    readonly severity: DoctorSeverity;
+    readonly message: string;
+}
+/** The full result of `runDoctor`. `ok` is false iff any finding is a `fail` — a `warn` never fails the report on its own. */
+export interface DoctorReport {
+    readonly findings: readonly DoctorFinding[];
+    readonly ok: boolean;
+}
+/** One identity's raw `identity.json`, unparsed — `runDoctor` does its own JSON.parse/schema validation so one malformed file never aborts the rest of the report. */
+export interface DoctorIdentityInput {
+    readonly name: string;
+    readonly path: string;
+    readonly raw: string | undefined;
+    /** The identity's own farm root (`identitiesDir/<name>`) — the account name the Keychain lookup uses. */
+    readonly farmRoot: string;
+}
+/** One configuration profile's raw `<name>.json`, unparsed. */
+export interface DoctorConfigProfileInput {
+    readonly name: string;
+    readonly path: string;
+    readonly raw: string | undefined;
+}
+/** One provider's raw `<name>.json`, unparsed. */
+export interface DoctorProviderInput {
+    readonly name: string;
+    readonly path: string;
+    readonly raw: string | undefined;
+}
+/** A single optional top-level file `runDoctor` validates against a schema when present — absent is a legitimate, unconfigured state, not a failure. */
+interface DoctorFileInput {
+    readonly path: string;
+    readonly raw: string | undefined;
+}
+/** The outcome of resolving the real Claude Code binary, pre-resolved by the wiring layer since `discoverClaudeBinary` is not itself a parse-shaped pure operation and already has its own dedicated test coverage. */
+type DoctorBinaryDiscovery = {
+    readonly ok: true;
+    readonly binary: DiscoveredClaudeBinary;
+} | {
+    readonly ok: false;
+    readonly message: string;
+};
+/**
+ * Where a bare command name resolves for the two names this tool owns.
+ *
+ * `ownExecutablePath` is this process's own PATH-visible location (`realOwnExecutablePath()`); `agentShim` is `findPathShadow`'s verdict for a bare `agent-shim` against the directory that executable lives in. `claude` is only populated when a shim is actually enabled — without one, a `claude` on PATH is Claude Code's own binary, which is not a shadow of anything.
+ */
+interface DoctorPathResolution {
+    readonly ownExecutablePath: string;
+    readonly agentShim: PathShadowStatus;
+    readonly claude?: PathShadowStatus;
+}
+/**
+ * Collapses a `shadowed` verdict back to `ok` when the shadowing entry and this executable are literally the same file reached by two names — `findPathShadow` compares *directories*, so a symlink on PATH pointing at the running executable's own real location otherwise reads as a shadow of itself.
+ *
+ * `realpath` must resolve symlinks, and must return its argument unchanged rather than throwing when the path cannot be resolved (a broken symlink, a race with an uninstall), so an unresolvable path simply stays unequal and the shadow verdict stands.
+ */
+export declare function refinePathShadow(status: PathShadowStatus, ownExecutablePath: string, realpath: (target: string) => string): PathShadowStatus;
+/** Everything `runDoctor` needs, all of it already loaded/injected — nothing in `runDoctor` itself reads a file, shells out, or touches the farm. */
+export interface RunDoctorParams {
+    readonly env: Readonly<Record<string, string | undefined>>;
+    readonly identities: readonly DoctorIdentityInput[];
+    readonly configProfiles: readonly DoctorConfigProfileInput[];
+    readonly providers: readonly DoctorProviderInput[];
+    readonly directoryRules: DoctorFileInput;
+    readonly globalConfig: DoctorFileInput;
+    readonly categoriesLocal: DoctorFileInput;
+    readonly activeIdentity: DoctorFileInput;
+    readonly binaryDiscovery: DoctorBinaryDiscovery;
+    /** Whether `agent-shim shim enable` has been run, and whether its recorded target still exists on disk — pre-resolved by the wiring layer, since checking a file's existence is real I/O, not a parse-shaped pure operation. */
+    readonly claudeShim: {
+        readonly state: ClaudeShimState | undefined;
+        readonly targetExists: boolean;
+    };
+    /** Which executables a bare `agent-shim` (and, when the shim is enabled, a bare `claude`) would actually run — pre-resolved by the wiring layer, since scanning PATH is real I/O. */
+    readonly pathResolution: DoctorPathResolution;
+    /** The resolved state root (`paths.root`), whose directory name says whether this installation still lives under the former `.claude-use` name. */
+    readonly rootPath: string;
+    /** Runs `security find-generic-password` for the per-identity Keychain check. Omit to skip that check entirely (e.g. off macOS). */
+    readonly run?: RunPort;
+    /** `process.platform` in real use; the Keychain check only ever runs when this is `"darwin"`. */
+    readonly platform: string;
+    /** The headroom daemon's state.json plus a zombie-aware liveness predicate for the pids it names (a defunct daemon holds no port but still answers signal 0). Omit the raw text when the daemon has never run; that is a pass, not a failure. */
+    readonly headroom: {
+        readonly state: DoctorFileInput;
+        readonly isRunning: (pid: number) => boolean;
+    };
+}
+/**
+ * Audits the whole `~/.agent-shim` config graph for internal consistency: every identity, every configuration profile's own `extends` chain, every provider, `directory-rules.json`, `config.json`, `categories.local.json`, `active-identity`, plus real Claude Code binary discoverability and ambient-credential exposure.
+ *
+ * Deliberately identity/directory-agnostic, unlike `runCheck` — there is no single cascade to resolve `doctor` against, so it never touches settings-exposure (which only means anything relative to one resolved cascade).
+ *
+ * Every check aggregates rather than throws: a malformed file becomes one `fail` finding for that file, not an aborted report. This is the one place in the codebase that deliberately breaks the "throw a validation error and let it propagate" convention every other command relies on — `doctor`'s whole purpose is to survive a broken file and keep auditing everything else.
+ */
+export declare function runDoctor(params: RunDoctorParams): DoctorReport;
+/** Renders a full `DoctorReport` as plain text lines, one section header at a time, in the order `agent-shim doctor` prints them. */
+export declare function formatDoctorReport(report: DoctorReport): string[];
+/** What `collectDoctorReport` needs from its caller. */
+export interface CollectDoctorReportParams {
+    readonly paths: LayoutPaths;
+    readonly env: NodeJS.ProcessEnv;
+}
+/**
+ * Audits the whole state root against this machine: the edge adapter that enumerates every identity, configuration profile and provider on disk, reads every top-level config file as raw text (never pre-parsing, so one malformed file cannot abort the report), discovers the real Claude Code binary and resolves where a bare command name runs from, and hands the facts to the pure `runDoctor`.
+ */
+export declare function collectDoctorReport(params: CollectDoctorReportParams): DoctorReport;
+export {};