claude-use 4.4.0 → 4.5.0

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

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

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

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

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

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

package/dist/types/paths.d.ts

@@ -0,0 +1,67 @@
+/**
+ * The resolved set of paths claude-use reads and writes under its own root.
+ *
+ * `root` is always CLAUDE_USE_HOME when that environment variable is set (used by every test in this project, and by any real installation that wants to relocate its state), falling back to `~/.claude-use` only when the variable is unset. Every other field is derived from `root` so there is exactly one place a path can go wrong.
+ */
+export interface LayoutPaths {
+    /** The resolved root directory — CLAUDE_USE_HOME, or ~/.claude-use when unset. */
+    readonly root: string;
+    /** Directory holding one subdirectory per identity (symlink farm + local credentials/daemon state). */
+    readonly identitiesDir: string;
+    /** Directory holding named, reusable configuration profile JSON files. */
+    readonly configProfilesDir: string;
+    /** Directory holding one `<name>.json` provider definition per API provider. */
+    readonly providersDir: string;
+    /** Path to the directory-rules.json file describing directory-scoped identity/profile pins. */
+    readonly directoryRulesFile: string;
+    /** Path to the persisted active-identity file (the identity `claude-use identity use` selected). */
+    readonly activeIdentityFile: string;
+    /** Path to the global config.json (user-global override layer, and default profile/walk-limit settings). */
+    readonly globalConfigFile: string;
+    /** Path to the categories.local.json overlay recording answers to "unclassified entry" prompts. */
+    readonly categoriesLocalFile: string;
+    /** Path to the claude-shim.json marker recording where `claude-use shim enable` last placed a `claude`-named copy of this executable, and how. */
+    readonly claudeShimFile: string;
+    /** Directory holding the headroom daemon's coordination state: state.json, the start lock, and the session registry. */
+    readonly headroomDir: string;
+    /** Directory holding the MITM proxy's certificate authority: ca.pem (public, handed to children as NODE_EXTRA_CA_CERTS) and ca.key (mode 0600). */
+    readonly headroomCaDir: string;
+    /** Path to the MITM proxy's CA certificate, generated once and stable across restarts so children keep trusting it. */
+    readonly headroomCaCertFile: string;
+    /** Path to the MITM proxy's CA private key, mode 0600. */
+    readonly headroomCaKeyFile: string;
+    /** Path to the headroom supervisor's state.json: pids, port, version, allowlist hash, last error. */
+    readonly headroomStateFile: string;
+    /** Path to the exclusive-create marker guarding "who spawns the supervisor" so concurrent launches start at most one. */
+    readonly headroomLockFile: string;
+    /** Directory holding one `<launcher-pid>.json` session-registry entry per live launch routed through headroom. */
+    readonly headroomSessionsDir: string;
+    /** Directory holding daemon logs (the headroom proxy's stdout/stderr and the supervisor's own output). */
+    readonly logsDir: string;
+    /** Path to the headroom daemon's combined log, appended to by both the supervisor and the proxy it owns. */
+    readonly headroomLogPath: string;
+    /** Directory holding the front-door daemon's coordination state: state.json, the start lock, and the session registry. */
+    readonly frontdoorDir: string;
+    /** Path to the front door's state.json: its supervisor pid, its port, and the sticky port it last served on. */
+    readonly frontdoorStateFile: string;
+    /** Path to the exclusive-create marker guarding "who spawns the front-door supervisor" so concurrent launches start at most one. */
+    readonly frontdoorLockFile: string;
+    /** Directory holding one `<launcher-pid>.json` session-registry entry per live launch routed through the front door. */
+    readonly frontdoorSessionsDir: string;
+    /** Path to the front door's log: one line per lifecycle event and routed failure, never a token. */
+    readonly frontdoorLogPath: string;
+}
+/**
+ * Resolves the current CLAUDE_USE_HOME root: the environment variable when set to a non-empty string, otherwise `~/.claude-use`. An empty string counts as unset, consistent with how this project treats empty-string environment variables elsewhere (see the ambient-credential guard).
+ */
+export declare function resolveClaudeUseHome(): string;
+/**
+ * Resolves the canonical `~/.claude` directory every farm symlink points back into: `CLAUDE_USE_CLAUDE_HOME` when set to a non-empty string, otherwise `~/.claude`.
+ *
+ * The override exists for the same reason `CLAUDE_USE_HOME` does. Exercising a real resync end to end means building and swapping real directories, and doing that against a real, in-use `~/.claude` to find out whether the code is correct is not an acceptable way to find out. Pointing both variables at throwaway directories makes a full end-to-end run safe.
+ */
+export declare function resolveClaudeHome(): string;
+/** Builds the full LayoutPaths structure from a given root directory. */
+export declare function buildLayoutPaths(root: string): LayoutPaths;
+/** Resolves CLAUDE_USE_HOME and builds the full LayoutPaths structure in one call. */
+export declare function resolveLayoutPaths(): LayoutPaths;

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

@@ -0,0 +1,37 @@
+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; `claude-use 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

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

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

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

@@ -0,0 +1,58 @@
+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 `.claude-use.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

@@ -0,0 +1,30 @@
+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 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[];
+/**
+ * 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

@@ -0,0 +1,57 @@
+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 {};