agent-shim 7.13.1 → 7.14.0

package/dist/types/poolStore.d.ts

@@ -1,18 +0,0 @@
-import { CliError } from "./cliError";
-import { type Pool } from "./config/schema";
-import type { LayoutPaths } from "./paths";
-/** Raised when a command names a pool that is not defined in the global config. */
-export declare class PoolNotFoundError extends CliError {
-    readonly poolName: string;
-    constructor(poolName: string);
-}
-/** The pools defined in `~/.agent-shim/config.json`, by name. */
-export declare function readPools(paths: LayoutPaths): Readonly<Record<string, Pool>>;
-/** The pool named `name`; throws `PoolNotFoundError` when none is defined. */
-export declare function requirePool(paths: LayoutPaths, name: string): Pool;
-/** Defines a new pool. Throws `InvalidPoolNameError` for a name `PoolNameSchema` rejects and `PoolAlreadyExistsError` for one already defined. */
-export declare function addPool(paths: LayoutPaths, name: string, identities: readonly string[]): Pool;
-/** Replaces an existing pool's members. Throws `PoolNotFoundError` when it is not defined. */
-export declare function setPool(paths: LayoutPaths, name: string, identities: readonly string[]): Pool;
-/** Removes a pool. Throws `PoolNotFoundError` when it is not defined. Anything that selected it (an active-identity file, a directory rule) is left for `doctor` to report, as with a removed identity. */
-export declare function removePool(paths: LayoutPaths, name: string): void;

package/dist/types/providersStore.d.ts

@@ -1,137 +0,0 @@
-import { type PROVIDER_CREDENTIAL_TARGETS, type PROVIDER_KINDS, type CodexProviderConfig, type CredentialCache, type CredentialSource, type Provider } from "./config/schema";
-import { CliError, UsageError } from "./cliError";
-import { type CredentialPort } from "./credential";
-import type { ResolvedProvider } from "./launcher/flags";
-import type { FsPort } from "./launcher/ports";
-import { type CascadeInput } from "./resolve/walk";
-import type { LayoutPaths } from "./paths";
-/** Raised by any operation that requires a provider to already exist, when it does not. */
-export declare class ProviderNotFoundError extends CliError {
-    readonly name: string;
-    constructor(name: string);
-}
-/** Raised by `addProvider` when a provider with the given name already has a file. */
-export declare class ProviderAlreadyExistsError extends CliError {
-    readonly providerName: string;
-    constructor(providerName: string);
-}
-/**
- * Raised by `addProvider` when `name` fails the provider naming rule: the same rule `IdentitySchema` applies to identity names (start with a letter or number, then letters, numbers, dots, hyphens, underscores, and at signs). Keeping the two rules identical means a name that works for one works for the other, and neither vocabulary can ever produce a path segment that escapes `providers/` or `identities/`.
- */
-export declare class InvalidProviderNameError extends CliError {
-    readonly attemptedName: string;
-    constructor(attemptedName: string);
-}
-/** True when a provider file exists for `name`, regardless of whether it validates. */
-export declare function providerExists(paths: LayoutPaths, name: string): boolean;
-/** Written in a replacement in place of an old fixed `env.ANTHROPIC_AUTH_TOKEN` value, which is never printed: the person converting the file copies the value across themselves. */
-export declare const LEGACY_LITERAL_PLACEHOLDER = "<the value of env.ANTHROPIC_AUTH_TOKEN>";
-/** What converting one old-format provider file involves: the old fields it uses, and the whole file rewritten in the current format. */
-export interface LegacyProviderConversion {
-    readonly fields: readonly string[];
-    readonly replacement: Record<string, unknown>;
-}
-/**
- * Recognises a provider file written in the format before the credential block (a `tokenEnv`, `tokenCommand` or `authScheme` field, or a credential variable in `env`, and no `credential`) and builds its exact replacement: `tokenEnv` becomes an `env` source, `tokenCommand` a `command` source, a non-empty fixed `env.ANTHROPIC_AUTH_TOKEN` a `literal` source (its value replaced by `LEGACY_LITERAL_PLACEHOLDER`, never printed), `authScheme` the `target`, and the credential variables leave `env`. Undefined for anything else, including a file that is merely invalid.
- */
-export declare function legacyProviderConversion(raw: unknown): LegacyProviderConversion | undefined;
-/** Raised when a provider file is still in the format before the credential block, naming the old fields and giving the exact replacement. */
-export declare class LegacyProviderFileError extends CliError {
-    readonly filePath: string;
-    readonly conversion: LegacyProviderConversion;
-    constructor(filePath: string, conversion: LegacyProviderConversion);
-}
-/** Reads and validates one provider definition, or undefined when it does not exist. */
-export declare function readProvider(paths: LayoutPaths, name: string): Provider | undefined;
-/**
- * Reads and validates one provider definition through an injected `FsPort`, the same way `loadIdentity` reads an `identity.json`: the launcher never touches the real filesystem directly, so provider loading must flow through the port it is already handed.
- */
-export declare function loadProvider(providersDir: string, name: string, port: FsPort): Provider | undefined;
-/** One provider definition as reported by `listProviders`. */
-export interface ProviderListEntry {
-    readonly name: string;
-    readonly provider: Provider;
-}
-/** Lists every provider under `providersDir` that has a valid `<name>.json`. A file that fails validation is skipped here; `provider list` is the place a broken definition gets surfaced, not a launch. */
-export declare function listProviders(paths: LayoutPaths): readonly ProviderListEntry[];
-/** The credential targets a provider may use. */
-export type ProviderCredentialTarget = (typeof PROVIDER_CREDENTIAL_TARGETS)[number];
-/** The kinds of provider. */
-export type ProviderKind = (typeof PROVIDER_KINDS)[number];
-/** Where a provider sends its sessions, for display: an `http` provider's base URL, or the front door for a codex provider (whose address exists only at launch). */
-export declare function describeProviderEndpoint(provider: Provider): string;
-/** Everything `addProvider` writes into a fresh provider file. `baseUrl` is required for an `http` provider and refused for a codex one; `codex` applies only to a codex provider. */
-export interface AddProviderInput {
-    readonly kind?: ProviderKind;
-    readonly displayName: string;
-    readonly baseUrl?: string;
-    readonly sources: readonly CredentialSource[];
-    readonly target?: ProviderCredentialTarget;
-    readonly env?: Readonly<Record<string, string>>;
-    readonly codex?: CodexProviderConfig;
-}
-/** Raised when a provider option does not fit the provider's kind: a base URL for a codex provider, a missing one for an http provider, or codex settings for an http provider. */
-export declare class ProviderKindMismatchError extends UsageError {
-    constructor(message: string);
-}
-/**
- * Creates a new provider definition. Throws `ProviderAlreadyExistsError` when a provider with this name already has a file, `InvalidProviderNameError` when `name` fails the naming rule, and `ConfigValidationError` when the assembled definition fails `ProviderSchema` (e.g. a `baseUrl` that is not a URL) rather than letting the underlying `ZodError` escape as an unhandled crash.
- */
-export declare function addProvider(paths: LayoutPaths, name: string, input: AddProviderInput): Provider;
-/**
- * The fields `updateProvider` changes. `sources` replaces the whole ordered source list (a list is set, not patched, since its order is its meaning); `target` changes where the token goes and keeps the sources. `env` entries merge over the existing ones and `unsetEnv` keys are then deleted.
- */
-export interface UpdateProviderInput {
-    readonly displayName?: string;
-    readonly baseUrl?: string;
-    readonly sources?: readonly CredentialSource[];
-    readonly target?: ProviderCredentialTarget;
-    /** A new cache block, or false to remove it; undefined leaves the existing one. */
-    readonly cache?: CredentialCache | false;
-    readonly env?: Readonly<Record<string, string>>;
-    readonly unsetEnv?: readonly string[];
-    /** Merged over a codex provider's existing settings: a field given here replaces that field, and `models` entries merge per tier. */
-    readonly codex?: CodexProviderConfig;
-}
-/**
- * Updates an existing provider definition in place. Throws `ProviderNotFoundError` when it does not exist, and `ConfigValidationError` when the updated definition fails `ProviderSchema`, leaving the file untouched.
- */
-export declare function updateProvider(paths: LayoutPaths, name: string, input: UpdateProviderInput): Provider;
-/** Deletes a provider definition. Throws `ProviderNotFoundError` when it does not exist. */
-export declare function removeProvider(paths: LayoutPaths, name: string): void;
-/**
- * The provider name the cascade selects through `launch.provider`, if any layer sets one. Last layer wins, the same rule `flattenLayers` applies to every other launch flag.
- */
-export declare function cascadeProviderName(cascade: CascadeInput): string | undefined;
-/** Inputs to `resolveProvider`. */
-export interface ResolveProviderParams {
-    readonly paths: LayoutPaths;
-    readonly port: FsPort;
-    readonly env: Readonly<Record<string, string | undefined>>;
-    /** Resolves the provider's credential sources. Omitted by a caller that cannot read secret files or run commands; a selected provider is then refused rather than launched without its credential. */
-    readonly credentials?: CredentialPort;
-    /** The `--provider <name>` flag's value, when one was given. It outranks any cascade layer, matching how the cliOverride layer composes last everywhere else. */
-    readonly cliProvider?: string;
-    /** The assembled-but-unflattened cascade for this launch, when one was loaded. Its layers are scanned for a `launch.provider` selection so a profile, directory rule, portable file, or the global config can pin a provider exactly the way they pin the other launch flags. */
-    readonly cascade?: CascadeInput;
-}
-/**
- * The outcome of resolving this launch's provider: either a fully-resolved provider (definition plus its resolved credential), or a refusal the launcher turns into a stderr line and a non-zero exit.
- *
- * A provider whose credential block yields no token exits `CREDENTIAL_UNAVAILABLE_EXIT` (64), because the invocation cannot authenticate. An unknown provider name exits 1, matching every other "named thing not found" refusal in the launcher.
- */
-export type ProviderResolution = {
-    readonly ok: true;
-    readonly provider: ResolvedProvider;
-    readonly warnings: readonly string[];
-} | {
-    readonly ok: false;
-    readonly status: number;
-    readonly message: string;
-};
-/**
- * Resolves which API provider this launch routes through, if any: the `--provider` flag first, then the cascade's `launch.provider` selection. Returns undefined when nothing selected a provider at all.
- *
- * Pure over its injected ports, so the launcher's tests exercise refusals without touching a real providers directory, secret store or terminal: this function decides, and the caller owns the log/exit side effects.
- */
-export declare function resolveProvider(params: ResolveProviderParams): ProviderResolution | undefined;

package/dist/types/realCredentialCache.d.ts

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

@@ -1,109 +0,0 @@
-import type { CredentialPort } from "./credential";
-import { type DiscoveredClaudeBinary } from "./versionDiscovery";
-import type { LayoutPaths } from "./paths";
-import type { FarmFs, FsPort, HeadroomPort, LogPort, ProcPort, RunPort, SpawnPort } from "./launcher/ports";
-/** The real, `node:fs`-backed `FsPort` used by the actual `claude` launcher — never used in tests. */
-export declare const realFsPort: FsPort;
-export declare const realFarmFs: FarmFs;
-/**
- * Blocks the current thread for `ms` milliseconds.
- *
- * The launcher is synchronous end to end, right through to `spawnSync`, so waiting on another process's identity lock cannot be done with a promise. `Atomics.wait` on a private buffer is the one way to sleep synchronously without burning the CPU in a spin loop.
- */
-export declare function realSleepSync(ms: number): void;
-/**
- * Whether `pid` is a live, schedulable process: signal-0 alive AND not a zombie. This is the liveness notion every headroom coordination decision must use, because a defunct daemon holds no port and a defunct supervisor will never write state, yet both still "exist" as far as signal 0 is concerned.
- */
-export declare function realIsProcessRunning(pid: number): boolean;
-/** The real `RunPort`, used for auxiliary commands whose output this process needs to read — git branch detection for `when: { branch }` conditions, and `check.ts`'s macOS Keychain lookup. */
-export declare const realRunPort: RunPort;
-/**
- * The real `CredentialPort`. A secret file's mode is reported only where POSIX permission bits exist (not on Windows, whose ACLs Node's `stat` does not expose). A command runs with no shell under its timeout; a non-interactive one gets no stdin and has its stderr captured for the error message, while an interactive one inherits the terminal's stdin and stderr so its prompt reaches a person. stdout is always captured, since it is the token.
- */
-export declare const realCredentialPort: CredentialPort;
-/** Reads the git branch checked out at `cwd`, and whether the repository is in detached-HEAD state. Both undefined when `cwd` is not in a repository at all. */
-export declare function resolveGitBranch(run: RunPort, cwd: string): {
-    branch?: string;
-    branchDetached?: boolean;
-};
-/**
- * The spawn options every background daemon agent-shim starts shares. `detached: true` puts the child in a new session with no controlling terminal, so closing the terminal a launch started from (SIGHUP to that terminal's session) never reaches it: a second session still using the daemon keeps working after the first one's terminal is gone. Standard input is closed and both output streams go to the daemon's log file.
- */
-export declare function detachedDaemonSpawnOptions(logFd: number, env: NodeJS.ProcessEnv): {
-    readonly detached: true;
-    readonly stdio: ["ignore", number, number];
-    readonly env: NodeJS.ProcessEnv;
-};
-/**
- * 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.
- */
-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, 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)`). */
-export declare const realProcPort: ProcPort;
-/** The real `LogPort`, writing info/warn to stdout and errors to stderr. */
-export declare const realLogPort: LogPort;
-/**
- * The pure decision logic behind `findExecutableInDir`, taking `platform`/`pathext`/the mode-stat as explicit parameters so it's unit-testable against fake Windows/POSIX environments without touching real process globals or a real filesystem — this is exactly the kind of platform-dependent logic that's easy to get subtly wrong (confirmed: it was, twice, across two failed release attempts before this was extracted and actually tested).
- *
- * `statFileMode` returns the file's POSIX mode bits if `candidate` exists as a regular file, or `undefined` otherwise (ENOENT collapsed to `undefined`, every other error still propagated by the real implementation).
- *
- * On Windows, this can't rely on `fs.Stats.mode`'s execute bits at all (see the comment above `windowsPathExtensions`), so it instead mirrors what a real shell does resolving a bare command name: try `name` as given if it already carries a recognised extension (e.g. a `.exe` filename passed in explicitly, as `resolveOwnExecutablePath`'s Scoop-shim redirect does), otherwise try appending each `PATHEXT` extension in turn and return the first that exists as a file. Everywhere else, a file counts as executable only when its POSIX mode bits actually say so.
- */
-export declare function resolveExecutableCandidate(dir: string, name: string, env: {
-    readonly platform: string;
-    readonly pathext: string | undefined;
-    readonly statFileMode: (candidate: string) => number | undefined;
-}): string | undefined;
-/** Looks for a file literally named `name` inside `dir` and confirms it's runnable. Exported so `src/claudeShim.ts`'s PATH-shadow and shim-redirect checks can reuse the exact same semantics `discoverClaudeBinary`'s own PATH fallback already uses, rather than shelling out to a shell builtin like `command -v`. Real-wired convenience over `resolveExecutableCandidate` — see that function for the actual decision logic and its own tests. */
-export declare function findExecutableInDir(dir: string, name: string): string | undefined;
-/**
- * Resolves the absolute path to the currently-running agent-shim/claude executable from the raw process/env facts a call site would otherwise read directly off `process` — passed explicitly so this is unit-testable without touching real process globals.
- *
- * This exists because `process.argv[1]` is not a reliable "path to my own executable" for a Node single-executable-application (SEA) binary the way it is for an ordinary Node script. Per Node's own SEA documentation, a SEA binary's `argv[1]` merely echoes back whatever string appeared on the command line — verbatim, with no path or PATH resolution applied by Node or the OS — whereas a shebang-invoked script (the npm/plain-Node case) genuinely receives its resolved script path there, because the kernel's shebang handling substitutes the shell's already-PATH-resolved pathname before Node ever starts. Concretely: typing the bare word `agent-shim` at a shell prompt produces `argv[1] === "agent-shim"` for a SEA binary (no directory component at all), which previously got fed straight into `fs.realpathSync`/`path.dirname` as if it were a real path — resolving relative to `process.cwd()` instead of wherever PATH actually found the binary, and throwing ENOENT the moment cwd didn't happen to contain a same-named file. Confirmed via a minimal instrumented SEA binary reproducing exactly this, and matching the exact failure every release verification job hit once invoking `agent-shim`/`claude` as a bare PATH-resolved command rather than by absolute path.
- *
- * A second, separate wrinkle: some install channels invoke this binary through a re-exec wrapper rather than running it directly. Scoop's own shim (`~/scoop/shims/agent-shim.exe`) is a compiled proxy (confirmed from its source: https://github.com/ScoopInstaller/Shim/blob/main/cs/shim.cs) that calls `CreateProcessW(null, cmd, ...)` with the real target's absolute path as the first token of `cmd` — per the Win32 `CreateProcess` contract, passing `lpApplicationName = null` means that first token becomes both the module launched *and* what the child receives as its own command line — so this process ends up seeing the real target's absolute path, living in a versioned app directory Scoop deliberately keeps off PATH, not the shim's own PATH-visible location. Placing the new `claude` alongside that path (as the Homebrew/direct-invocation case correctly does) would create a file PATH can never find. Confirmed against a real Scoop install: `agent-shim shim enable` placed `claude.exe` next to the real target in the app directory, and the immediately following `claude --version` failed with "not recognized" because that directory was never on PATH.
- *
- * The redirect-if-not-on-PATH check below applies uniformly to whichever candidate we end up with — whether derived from a path-shaped `argv1`, or from the `execPath` fallback (`argv1` undefined) — since it's unconfirmed whether a Windows SEA binary duplicates `argv[0]` into `argv[1]` the same way the POSIX build does; treating both sources identically is strictly more robust either way and regresses nothing already confirmed working.
- *
- * The algorithm: if the raw candidate is a bare word with no path separator, it can only have been found via PATH lookup in the first place (Node/the OS applies no resolution to it at all), so search PATH ourselves for the first directory containing an executable of that name, reconstructing exactly what the shell already did. Otherwise, resolve it (or the `execPath` fallback) against cwd, then check whether the *resulting directory* is itself on PATH: if so, use it directly (the Homebrew/direct-invocation case — never realpath'd, since a package manager's PATH-visible entry is often a symlink elsewhere, e.g. Homebrew's `/opt/homebrew/bin/agent-shim` pointing at its own Cellar keg, and callers need that PATH-visible location, not the dereferenced target). If that directory is *not* on PATH (the Scoop re-exec case above), search PATH for a separately-installed entry sharing our own invoked basename before falling back to the direct candidate.
- */
-export declare function resolveOwnExecutablePath(env: {
-    readonly argv1: string | undefined;
-    readonly execPath: string;
-    readonly cwd: string;
-    readonly pathDirs: readonly string[];
-    readonly findExecutableInDir: (dir: string, name: string) => string | undefined;
-}): string;
-/** Real-wired convenience over `resolveOwnExecutablePath`, reading the actual process globals — this is what every real call site (`cli.ts`, `doctor.ts`, `claudeShim.ts`'s command wiring) should use instead of reading `process.argv[1]`/`process.execPath` directly. */
-export declare function realOwnExecutablePath(): string;
-/**
- * Resolves the path to the actual file whose *content* is this running process — never a PATH-visible location, which can differ from the real content entirely (Scoop's own shim, a compiled proxy binary, sits at the PATH-visible location while the genuine agent-shim binary lives elsewhere; see `resolveOwnExecutablePath`'s own doc comment for the full mechanism). This is what `enableClaudeShim`/`disableClaudeShim` must hardlink/copy from and compare inodes against — using `resolveOwnExecutablePath`'s redirected PATH-visible location for this would hardlink Scoop's generic shim proxy itself, not agent-shim's real content, which is exactly the bug this function exists to avoid (confirmed against a real Scoop install: `shim enable` correctly placed `claude.exe` in `shims/`, but invoking it failed with Scoop's own "Cannot open shim file for read" error, because the hardlink's source was Scoop's proxy, paired via a `.shim` config file keyed to its *original* filename).
- *
- * `node:sea`'s `isSea()` is the correct, documented way to distinguish the two operating modes this tool ships in, rather than inferring it from `argv1`'s shape: for a single-executable-application build, `process.execPath` is always the real, fully-resolved running binary (confirmed: Windows `CreateProcess` with `lpApplicationName = null` still resolves to the genuine target file, the same one `execPath` reports, regardless of Scoop's separate PATH-visible proxy). For a plain Node script (the npm-published bundle), `execPath` would instead point at the Node interpreter itself — useless — so `argv1` (the shebang-resolved script path, reliable in this mode) is used instead.
- */
-export declare function resolveContentSourcePath(env: {
-    readonly isSea: boolean;
-    readonly execPath: string;
-    readonly argv1: string | undefined;
-}): string;
-/** Real-wired convenience over `resolveContentSourcePath`. */
-export declare function realContentSourcePath(): string;
-/** Builds the real `resolveClaudeBinary` callback `runLauncher` needs: scans the real versions directory, then falls back to a real PATH search, excluding this tool's own install directory. */
-export declare function realResolveClaudeBinary(ownInstallDirs: readonly string[]): () => DiscoveredClaudeBinary;

package/dist/types/resolve/conditions.d.ts

@@ -1,37 +0,0 @@
-import { type WhenCondition } from "../config/schema";
-import type { EntryFact } from "./types";
-/** Parses a duration literal like `90d` or `500ms` into milliseconds. Throws on anything the schema's own regex would already have rejected, so a malformed value can never be silently treated as zero. */
-export declare function parseDuration(value: string): number;
-/** True when the value would satisfy the schema's duration regex. */
-export declare function isDuration(value: string): boolean;
-/** Everything a `when` condition can be evaluated against, injected rather than read. */
-export interface ConditionContext {
-    readonly nowMs: number;
-    /** Facts about the specific entry being decided. Absent when evaluating a rule-level condition that has no single entry (a directory rule's own `when`). */
-    readonly fact?: EntryFact;
-    /** The branch checked out at `cwd`, or undefined when `cwd` is not in a repository. */
-    readonly branch?: string;
-    /** True when the repository is in detached-HEAD state, in which case no `branch` condition can match. */
-    readonly branchDetached?: boolean;
-    readonly env: Readonly<Record<string, string | undefined>>;
-}
-/** The result of evaluating one `when` object. */
-export interface WhenEvaluation {
-    readonly passed: boolean;
-    /** Which condition fields were present and evaluated. */
-    readonly checked: readonly string[];
-    /** Which of those fields did not hold. Empty when `passed` is true. */
-    readonly failed: readonly string[];
-}
-/** True when `branch` matches `pattern`. The pattern is glob-capable (`client/*`); a detached HEAD or a non-repository directory never matches. */
-export declare function matchBranch(pattern: string, branch: string | undefined, detached?: boolean): boolean;
-/**
- * Evaluates a `when` object. Every present field must hold — conditions AND together within one object.
- *
- * An absent condition is vacuously true, so `when: {}` passes; `agent-shim check` warns about that rather than erroring, since an empty object is more likely a half-finished edit than an intentional statement.
- *
- * `newerThan`, `olderThan`, and `maxSizeBytes` read the subtree-aggregated facts (`latestMtimeMs`, `totalSizeBytes`), never the entry's own inode stat: a directory's own mtime does not change when a file three levels beneath it is rewritten, and its own size is a ~4KB inode figure that says nothing about what it contains.
- */
-export declare function evaluateWhen(when: WhenCondition | undefined, context: ConditionContext): WhenEvaluation;
-/** True when the `when` object is present but empty, which is vacuously true and therefore has no effect. */
-export declare function isVacuousWhen(when: WhenCondition | undefined): boolean;

package/dist/types/resolve/decide.d.ts

@@ -1,45 +0,0 @@
-import { type CategoryName } from "../config/schema";
-import type { CompiledRule, Decision, Diagnostic, EliminatedRule, EntryFact, EntryFacts, FlattenedCascade } from "./types";
-/** Everything phase two needs, all of it injected. */
-export interface DecideParams {
-    readonly flattened: FlattenedCascade;
-    readonly facts: EntryFacts;
-    /** Every top-level `~/.claude` entry name mapped to its category, or to null when nothing recognises it. */
-    readonly classification: ReadonlyMap<string, CategoryName | null>;
-}
-/** A rule chosen by `selectRule`, alongside the candidates eliminated on the way to it. */
-export interface RuleSelection {
-    readonly rule?: CompiledRule;
-    readonly eliminated: readonly EliminatedRule[];
-}
-/**
- * Picks the winning entries rule for one path.
- *
- * Candidates are ranked by `compareSpecificity` and taken in order. A candidate whose `when` condition **fails is eliminated** and resolution continues to the next-most-specific matching rule — it never falls straight through to the category default, and a failed condition never inverts the rule's boolean value, which would not have a coherent meaning anyway. Only when no candidate survives does the caller fall back to the category.
- */
-export declare function selectRule(relPath: string, flattened: FlattenedCascade, context: {
-    nowMs: number;
-    branch?: string;
-    branchDetached?: boolean;
-    env: Readonly<Record<string, string | undefined>>;
-    fact?: EntryFact;
-}): RuleSelection;
-/**
- * Resolves one path to a sharing decision, in exactly this order:
- *
- * 1. **The secret floor.** If the path's top-level entry classifies as `secret`, the answer is `false` unconditionally. This check sits *above* the entries lookup, not merely at the least-specific end of the cascade, and it fires on the path's **real classification**, never on a lexical reading of the key that matched it — so a glob written under a `runtime/` prefix that happens to reach `.credentials.json` is neutralised exactly like a deliberate `secret/` key would be.
- * 2. **Unclassified.** A top-level entry nothing recognises is not shared, and is reported rather than silently guessed at.
- * 3. **Entries rules**, most specific first, with a failing condition eliminating a candidate rather than ending the search.
- * 4. **The category**: a layer's own toggle if any layer set one, otherwise the shipped default.
- */
-export declare function resolveEntry(relPath: string, params: DecideParams): {
-    decision: Decision;
-    diagnostics: Diagnostic[];
-};
-/** Every decision the resolver reaches, plus every diagnostic raised along the way (phase-one diagnostics included, and de-duplicated). */
-export interface ResolveAllResult {
-    readonly decisions: ReadonlyMap<string, Decision>;
-    readonly diagnostics: readonly Diagnostic[];
-}
-/** Resolves every entry in the fact manifest. */
-export declare function resolveAll(params: DecideParams): ResolveAllResult;

package/dist/types/resolve/extends.d.ts

@@ -1,41 +0,0 @@
-import type { ConfigProfile } from "../config/schema";
-import type { Diagnostic, Layer, LayerId } from "./types";
-/** One configuration profile as loaded from disk, with its entries key order captured at load time. */
-export interface ProfileSource {
-    readonly name: string;
-    readonly profile: ConfigProfile;
-    readonly entryOrder?: readonly string[];
-    /** Where it was loaded from, for diagnostics. Defaults to the profile name. */
-    readonly filepath?: string;
-}
-/** Loads a profile by name. Injected, so nothing in the resolver reads a file. Returns undefined when no profile of that name exists. */
-export type ProfileLoader = (name: string) => ProfileSource | undefined;
-/** The linearised `extends` chain plus anything that went wrong resolving it. */
-export interface LinearisedProfiles {
-    /** Profile names, base-first: every profile appears exactly once, after everything it extends. */
-    readonly order: readonly string[];
-    readonly diagnostics: readonly Diagnostic[];
-}
-/**
- * Linearises a profile's `extends` graph into a base-first order.
- *
- * The walker keeps **two separate structures**, and the distinction is load-bearing rather than stylistic:
- *
- * - `stack` is the current depth-first path. A name already on it means the graph genuinely loops back on itself, which is the only real cycle.
- * - `visited` is every name already emitted anywhere in the walk. A name already in it is a diamond — two branches sharing a base — and must simply be skipped, not re-emitted.
- *
- * Collapsing the two into one shared set produces a silent wrong answer in either direction. Using `stack` alone re-emits a shared base a second time in a diamond, so the base's values get re-applied on top of an intermediate profile that deliberately overrode them — the override silently disappears. Using `visited` alone false-flags every legitimate diamond as a cycle. Neither failure crashes; both just resolve to the wrong configuration.
- *
- * Emission is **post-order**: a profile is appended only after everything it extends, so `c extends [a, b]` where both extend `base` linearises to `[base, a, b, c]` — never `[base, a, base, b, c]`.
- */
-export declare function lineariseProfile(rootName: string, load: ProfileLoader): LinearisedProfiles;
-/**
- * Turns a profile's `extends` chain into cascade layers, base-first, starting at `startId`.
- *
- * A resolved profile is not a separate mechanism from the outer cascade: its chain flattens through the same ordered-layer sequence everything else uses, so a profile's resolved patch is simply one more run of inputs to the same algorithm.
- */
-export declare function profileLayers(rootName: string, load: ProfileLoader, startId: LayerId): {
-    layers: Layer[];
-    nextId: LayerId;
-    diagnostics: readonly Diagnostic[];
-};

package/dist/types/resolve/flatten.d.ts

@@ -1,13 +0,0 @@
-import type { CompiledRule, FlattenedCascade, Layer } from "./types";
-/**
- * Cascade phase one: walk the ordered layer sequence once, spreading each layer's `categories` and `entries` over an accumulator. A later layer's value for the exact same category name, or the exact same key, replaces an earlier layer's value for that identical key. No path-specificity reasoning happens here — that is phase two's job.
- *
- * The entries accumulator is keyed by the **canonical** pattern, not the raw written key, so two differently-spelled but equivalent keys (`history/projects/~/work/x` and `history/projects/$HOME/work/x` after expansion) collapse into one rule here instead of racing as two separate candidates in phase two. Every surviving rule carries its own `{ layer, ordinal }`, which is what lets phase two tell a same-layer conflict from a cross-layer one without a separate provenance side-table.
- *
- * A key written under the `secret/` prefix is rejected outright with its own diagnostic and contributes no rule at all: `secret` is the one category no layer may open, and a deliberate attempt to name a secret path deserves a clearer error than the silent neutralisation the resolve-time floor check applies to a glob that reaches one incidentally.
- */
-export declare function flattenLayers(layers: readonly Layer[], options: Readonly<{
-    home: string;
-}>): FlattenedCascade;
-/** Every compiled rule that matches `relPath`, ranked most-specific first. */
-export declare function matchingRules(flattened: FlattenedCascade, relPath: string): CompiledRule[];

package/dist/types/resolve/match.d.ts

@@ -1,58 +0,0 @@
-import { type CategoryName } from "../config/schema";
-import { CliError } from "../cliError";
-import type { CompiledRule } from "./types";
-/** True when `pattern` contains no glob metacharacter, so it can only ever match one literal path. */
-export declare function isExactPattern(pattern: string): boolean;
-/** The pattern's leading run of characters before the first glob metacharacter — the part that is definitely literal. */
-export declare function literalPrefixOf(pattern: string): string;
-/** Normalises a relative path fragment: collapses repeated slashes, drops `./` segments, and strips a trailing slash. Deliberately case-preserving and case-sensitive. */
-export declare function normaliseRelative(fragment: string): string;
-/** The outcome of canonicalising one entries key. */
-export interface CanonicalKey {
-    readonly declaredCategory: CategoryName;
-    /** The pattern with its category prefix stripped, relative to `~/.claude`, with any `history/projects/` path fragment already encoded. */
-    readonly canonicalPattern: string;
-    /** The `history/projects/` path fragment as written, before encoding — retained so ambiguity reporting can name what the author actually typed. */
-    readonly projectFragment?: string;
-}
-/** Raised when an entries key cannot be canonicalised. Carries the offending key so the diagnostic can name it. */
-export declare class EntryKeyError extends CliError {
-    readonly key: string;
-    readonly reason: "unrooted-project-path" | "malformed";
-    constructor(key: string, message: string, reason: "unrooted-project-path" | "malformed");
-}
-/**
- * Canonicalises one entries key into a pattern over paths relative to `~/.claude`.
- *
- * Every key is `<category>/<real-relative-path>`, so the category prefix is stripped and the remainder kept as written — with one deliberately narrow exception. Anything written after the literal `history/projects/` prefix is a real absolute working directory (optionally globbed), not a literal child directory name, because that directory's only real children are Claude Code's own encoded names and there is nothing else meaningful to reference there. Those fragments get `~`-expanded and forward-encoded; every other key in the whole design is a plain literal path or an ordinary glob over one, matched exactly as written.
- */
-export declare function canonicaliseEntryKey(key: string, options: Readonly<{
-    home: string;
-}>): CanonicalKey;
-/**
- * Compiles a canonical pattern into a matcher that covers the pattern itself *and* everything beneath it, so a rule written as `knowledge/skills` decides `skills/commit/SKILL.md` too. Two picomatch matchers are needed rather than one: `skills/**` alone covers the subtree but `projects/*` does not match `projects/x/y`, and `projects/*` alone does not cover the files inside a matched project directory.
- *
- * Matching is deliberately case-sensitive (`nocase: false`) whatever the host filesystem does, so the same config behaves identically on a case-insensitive APFS volume and a case-sensitive one. `dot: true` so a glob can match a leading-dot entry.
- */
-export declare function compileMatcher(canonicalPattern: string): (relPath: string) => boolean;
-/**
- * True when some path *underneath* `dir` could match `canonicalPattern`, whether or not such a path exists today.
- *
- * This is what makes a conditional rule force materialisation: a directory Claude Code will write new children into cannot be symlinked wholesale if a rule might have something to say about those not-yet-existing children. Answering that from the pattern's structure rather than from the current file listing is the whole point — asking "does any existing child match" would pass the obvious test and fail the real one.
- */
-export declare function patternCouldReachUnder(canonicalPattern: string, dir: string): boolean;
-/**
- * Ranks two compiled rules that both match the same path. A positive result means `a` wins.
- *
- * The order, exactly:
- *
- * 1. **Different layers — the later layer wins, period.** This rank sits deliberately *above* exactness. Ranking exactness first would let an untrusted committed `.agent-shim.json`'s exact key beat your own later, personal glob override, breaking the design's stated trust property that a directory-scoped local rule can only ever tighten what a committed file opened, never the reverse. Nothing in the design asserts that an earlier exact key beats a later glob, so nothing is lost by closing that hole.
- * 2. Same layer: an exact literal beats a glob.
- * 3. Same layer: the longer literal prefix wins.
- * 4. Same layer: more path segments wins, which separates a one-wildcard pattern from a two-wildcard one at the same depth.
- * 5. Same layer: the later ordinal — source order within the file — wins.
- * 6. Canonical pattern, compared as a string, as a last-resort determinism guarantee.
- *
- * The order must be **total**: returning 0 for two distinct rules would make the winner depend on iteration order, which tests would only catch intermittently.
- */
-export declare function compareSpecificity(a: CompiledRule, b: CompiledRule): number;

package/dist/types/resolve/pipeline.d.ts

@@ -1,33 +0,0 @@
-import { type ClassifyResult } from "../config/classify";
-import type { CategoryClassification, CategoryClassificationOverlay } from "../config/schema";
-import { type ResolveAllResult } from "./decide";
-import { type FarmPlan } from "./plan";
-import { type DescendPolicy } from "./walkPolicy";
-import { type AssembledCascade, type CascadeInput } from "./walk";
-import type { Diagnostic, EntryFacts, FlattenedCascade } from "./types";
-/** Everything one launch needs resolved, in one call. */
-export interface ResolveDecisionsInput {
-    readonly facts: EntryFacts;
-    readonly cascade: CascadeInput;
-    readonly classification: {
-        readonly defaults: CategoryClassification;
-        readonly overlay?: CategoryClassificationOverlay;
-    };
-}
-/** The fully resolved state of one launch: the layers that composed it, every entry's decision, the farm layout, and everything worth reporting. */
-export interface ResolvedState {
-    readonly assembled: AssembledCascade;
-    readonly flattened: FlattenedCascade;
-    readonly classification: ClassifyResult;
-    readonly decisions: ResolveAllResult["decisions"];
-    readonly farm: FarmPlan;
-    readonly diagnostics: readonly Diagnostic[];
-}
-/** The top-level `~/.claude` entry names present in a fact manifest, in sorted order. */
-export declare function topLevelNames(facts: EntryFacts): string[];
-/** The walk policy `buildEntryFacts` needs for `cascade`: which directories of `~/.claude` the fact walk must enter, derived from the flattened rules (see `descendPolicy`). */
-export declare function descendPolicyFor(cascade: CascadeInput, home: string): DescendPolicy;
-/**
- * Runs the whole pipeline for one launch: assemble the ordered layer sequence, flatten it, classify the real `~/.claude` entries, decide every path, and plan the resulting farm.
- */
-export declare function resolveDecisions(input: ResolveDecisionsInput): ResolvedState;

package/dist/types/resolve/plan.d.ts

@@ -1,57 +0,0 @@
-import type { Decision, EntryFacts, FlattenedCascade } from "./types";
-/** What the farm should contain at one path. */
-type FarmPlanEntry = 
-/** A single symlink standing in for this whole path — always absolute, always under `claudeHome`. */
-{
-    readonly kind: "link";
-    readonly rel: string;
-    readonly target: string;
-}
-/** A real local directory the farm builds itself, because the decision beneath it is not uniform or because a conditional rule could touch it. */
- | {
-    readonly kind: "materialise";
-    readonly rel: string;
-    readonly reason: MaterialiseReason;
-}
-/** Nothing at all in the farm for this path. */
- | {
-    readonly kind: "omit";
-    readonly rel: string;
-};
-/** Why a directory has to be built rather than symlinked. */
-type MaterialiseReason = 
-/** Descendants of this directory resolve to different decisions, so a single symlink cannot express the outcome. */
-"split-decision"
-/** A conditional entries rule could match something under this directory, so the decision has to stay live. */
- | "conditional-rule";
-/** The full farm plan for one resolved cascade. */
-export interface FarmPlan {
-    /** Every planned path, parents before children. */
-    readonly entries: readonly FarmPlanEntry[];
-    /** Directories the farm builds itself, in plan order. Written into the farm manifest so the next resync can tell them apart from directories Claude Code created. */
-    readonly materialised: readonly string[];
-    readonly links: readonly {
-        readonly rel: string;
-        readonly target: string;
-    }[];
-}
-/** Everything `planFarm` needs, all of it already resolved. */
-export interface PlanFarmParams {
-    readonly facts: EntryFacts;
-    readonly decisions: ReadonlyMap<string, Decision>;
-    readonly flattened: FlattenedCascade;
-}
-/** Indexes the fact manifest by parent path, so the plan can descend the tree without touching a filesystem. */
-export declare function buildChildIndex(facts: EntryFacts): Map<string, string[]>;
-/**
- * Turns a resolved set of decisions into a concrete farm layout.
- *
- * A directory becomes one symlink when the decision is uniform across its whole subtree, which is what keeps the common resync cheap — a few dozen top-level symlinks rather than a rebuilt tree. It is materialised, and recursed into, when either:
- *
- * - its subtree's decisions genuinely disagree, so no single symlink can express the outcome; or
- * - **any** conditional entries rule could reach something under it, even when today's evaluation happens to be uniform. This second case is the one a naive "is the decision uniform right now" check gets wrong: a symlinked directory freezes the decision for every file Claude Code creates *after* the resync, so a `newerThan` condition meant to share recent sessions would never see a session written five minutes from now. The bug only surfaces for files that do not exist yet, which is precisely why the check has to be structural rather than observational.
- *
- * Every symlink target is `<claudeHome>/<rel>`, unconditionally. That matters for the entries inside a materialised directory that are themselves relative symlinks escaping `~/.claude` (a real condition, not a hypothetical one — a skills directory linked out to a separate dotfiles repository, for instance). Copying such a link's own relative target verbatim would resolve to a different place from the farm's own depth, and copying its resolved absolute target would pin the farm to wherever that link pointed at resync time. Linking at `<claudeHome>/<rel>` and letting the OS follow the remaining hops from there is the only form that stays correct.
- */
-export declare function planFarm(params: PlanFarmParams): FarmPlan;
-export {};