agent-shim 0.0.0 → 7.1.0

package/dist/types/paths.d.ts

@@ -0,0 +1,79 @@
+/**
+ * The resolved set of paths agent-shim reads and writes under its own root.
+ *
+ * `root` is always AGENT_SHIM_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 `~/.agent-shim` (or the former `~/.claude-use`, see `resolveAgentShimHome`) 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, see `resolveAgentShimHome`. */
+    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 `agent-shim 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 `agent-shim 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;
+    /** 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;
+    /** Directory holding the front door's certificate authority, which signs both the provider listener's loopback leaf and the CONNECT surface's intercept leaf: ca.pem (public, handed to children through NODE_EXTRA_CA_CERTS) and ca.key (mode 0600). */
+    readonly frontdoorCaDir: string;
+    /** Path to the front door's CA certificate, generated once and stable across restarts so children keep trusting it. */
+    readonly frontdoorCaCertFile: string;
+    /** Path to the front door's CA private key, mode 0600: whoever can read it can impersonate the door to every routed child. */
+    readonly frontdoorCaKeyFile: string;
+    /** Directory of combined CA bundles: a parent environment's own NODE_EXTRA_CA_CERTS file plus the front door's CA, one file per distinct combination, for children that must keep trusting both. */
+    readonly frontdoorCaBundlesDir: 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;
+    /** Directory holding the usage store, mode 0700: the request log and the per-identity snapshots. Metadata only, never content or credentials. */
+    readonly usageDir: string;
+    /** Directory of the append-only usage log: one `<YYYY-MM-DD>.<writer-pid>.jsonl` segment per writing process per UTC day. */
+    readonly usageLogDir: string;
+    /** Directory of the latest-state snapshots, one `<identity>.json` per identity: the stable file other tools read. */
+    readonly usageSnapshotsDir: string;
+    /** The last identity picked from a pool for each directory, so a conversation stays on the account whose prompt cache is warm. */
+    readonly usagePicksFile: string;
+}
+/**
+ * Resolves the state root: `AGENT_SHIM_HOME` when set to a non-empty string (an empty string counts as unset, consistent with how this project treats empty-string environment variables elsewhere, see the ambient-credential guard), otherwise `~/.agent-shim`, or the former `~/.claude-use` when only that exists.
+ *
+ * The former root is used where it stands, never moved: macOS Claude Code names each identity's Keychain entry after a hash of its exact `CLAUDE_CONFIG_DIR`, so any relocation would sign every identity out. A fresh installation, or one that already has `~/.agent-shim`, uses the current name.
+ */
+export declare function resolveAgentShimHome(env?: NodeJS.ProcessEnv, home?: string, isDirectory?: (candidate: string) => boolean): string;
+/**
+ * Resolves the canonical `~/.claude` directory every farm symlink points back into: `AGENT_SHIM_CLAUDE_HOME` when set to a non-empty string, otherwise `~/.claude`.
+ *
+ * The override exists for the same reason `AGENT_SHIM_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 AGENT_SHIM_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; `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

@@ -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 `.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

@@ -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 {};

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

@@ -0,0 +1,61 @@
+/**
+ * Forward-only encoding of a real working directory into the single directory name Claude Code gives it under `~/.claude/projects/`.
+ *
+ * The encoding collapses the *entire* non-alphanumeric character class to `-`, not just the path separator: `.`, `_`, ` `, `@`, and `/` all become `-`, while letters and digits pass through with their case preserved. This was confirmed against a real installation's project directories, not assumed from the one `/`-becomes-`-` sample the README quotes.
+ *
+ * The encoding is therefore many-to-one: `~/work/clients/acme`, `~/work/clients-acme`, and `~/work-clients/acme` all produce the identical name. That makes it impossible to invert, so this module never tries: there is no decode function here, and `projects.test.ts` asserts the module's export list to keep it that way. Only the forward direction — real path to encoded name — is ever computed, and `detectEncodingAmbiguity` reports when a pattern's encoded form could plausibly correspond to more than one real path rather than resolving it silently.
+ */
+import { CliError } from "../cliError";
+/** Encodes one real, fully-literal path into the directory name Claude Code would give it under `~/.claude/projects/`. */
+export declare function encodeProjectPath(realPath: string): string;
+/** One piece of a pattern split on its wildcard tokens: either a literal run to encode, or a wildcard to leave alone. */
+export interface PatternFragment {
+    readonly kind: "literal" | "wildcard";
+    readonly text: string;
+}
+/**
+ * Splits a pattern into alternating literal runs and wildcard tokens. Encoding the whole pattern string in one pass would turn `*` into `-` along with everything else, silently converting a glob into a literal that matches nothing.
+ */
+export declare function splitOnWildcards(pattern: string): PatternFragment[];
+/** Raised when a `history/projects/` pattern's path fragment is neither `~`-rooted nor absolute, so there is no real path to encode. */
+export declare class UnrootedProjectPathError extends CliError {
+    readonly fragment: string;
+    constructor(fragment: string);
+}
+/** Expands a leading `~` to the given home directory. A `~` anywhere else in the path is an ordinary character. */
+export declare function expandHome(fragment: string, home: string): string;
+/**
+ * Encodes a possibly-globbed real path into a pattern that matches Claude Code's own `~/.claude/projects/` directory names.
+ *
+ * Order matters and is fixed: expand `~` to the real home first (encoding `~` would turn it into `-` and lose the reference), reject anything not home-or-root-rooted, then split on wildcard tokens and encode only the literal runs.
+ */
+export declare function encodeProjectPattern(fragment: string, options: Readonly<{
+    home: string;
+}>): string;
+/** Why a pattern's encoded form might not identify the real path its author had in mind. */
+export type EncodingAmbiguityReason = 
+/** The literal portion contains a character other than `/` that encodes to `-`, so a sibling path differing only in that character encodes identically. */
+"lossy-characters"
+/** Two different patterns in the same configuration encode to the identical form. */
+ | "collides-with-sibling-pattern";
+/** One reported ambiguity in a `history/projects/` pattern. */
+export interface EncodingAmbiguity {
+    readonly fragment: string;
+    readonly encoded: string;
+    readonly reason: EncodingAmbiguityReason;
+    readonly detail: string;
+}
+/**
+ * Reports, for a set of `history/projects/` path fragments, every case where the encoded form could plausibly correspond to more than one real path.
+ *
+ * Two signals, both actionable:
+ *
+ * - `lossy-characters` — the fragment's literal portion contains a character besides `/` that encodes to `-`. Because encoding is many-to-one, a sibling path with that character replaced by a separator (or vice versa) produces the identical name, so this pattern may match a directory belonging to a different real path.
+ * - `collides-with-sibling-pattern` — two distinct fragments in the same configuration encode identically, which proves a collision outright rather than merely suggesting one.
+ *
+ * When `existingNames` is supplied, `detail` also names how many real project directories the encoded form currently matches, so the report says what actually happened rather than only what could.
+ */
+export declare function detectEncodingAmbiguity(fragments: readonly string[], options: {
+    home: string;
+    existingNames?: readonly string[];
+}): EncodingAmbiguity[];

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

@@ -0,0 +1,80 @@
+import type { Diagnostic } from "./types";
+/** The manifest the farm builder writes into each scratch tree before the atomic swap. */
+export interface FarmManifest {
+    readonly version: 1;
+    readonly builtAtMs: number;
+    readonly identity: string;
+    readonly configProfile?: string;
+    readonly cwd: string;
+    readonly claudeHome: string;
+    /** Directories the previous resync built itself. Without this list, a directory the farm materialised and a directory Claude Code created are indistinguishable on disk — both are real, both contain real children. */
+    readonly materialised: readonly string[];
+    readonly links: readonly {
+        readonly rel: string;
+        readonly target: string;
+    }[];
+}
+/** One node of a directory listing, relative to the tree's own root. */
+export interface ListingEntry {
+    /** Path relative to the tree root, forward-slash separated. */
+    readonly rel: string;
+    readonly kind: "dir" | "file" | "symlink";
+    /** A content hash for a file, used to recognise data that has already been adopted. Absent for directories and symlinks. */
+    readonly contentHash?: string;
+}
+/** What to do about one path found in the old farm. */
+export type ReconcileAction = 
+/** New data Claude Code wrote that the canonical tree does not have. Copy it to `to`. */
+{
+    readonly kind: "adopt";
+    readonly rel: string;
+    readonly reason: "absent-from-canonical";
+}
+/** New data whose canonical counterpart exists but differs. The canonical copy is authoritative; the farm copy is preserved alongside it for the user to reconcile. */
+ | {
+    readonly kind: "adopt-conflict";
+    readonly rel: string;
+}
+/** Nothing to do, with the reason recorded so `agent-shim check` can explain a no-op. */
+ | {
+    readonly kind: "skip";
+    readonly rel: string;
+    readonly reason: SkipReason;
+};
+/** Why a path in the old farm needs no action. */
+type SkipReason = 
+/** A symlink the previous resync placed. It is a view of the canonical tree, so there is nothing to write back. */
+"is-symlink"
+/** A directory the previous resync materialised. Not new data itself; its children are examined individually. */
+ | "tracked-materialised-dir"
+/** Real data whose canonical counterpart already holds identical content — already adopted, possibly by an earlier run that then crashed before the swap. */
+ | "identical-content";
+/** The result of planning a reconciliation pass. */
+export interface ReconciliationPlan {
+    readonly actions: readonly ReconcileAction[];
+    readonly diagnostics: readonly Diagnostic[];
+    /** True when the manifest was missing or unusable and every real directory in the farm was treated as materialised. */
+    readonly conservative: boolean;
+}
+/** Everything the reconciliation planner reads. It performs no I/O of its own — the launcher executes the actions it returns. */
+export interface ReconcileParams {
+    /** The previous resync's manifest, or undefined when it is missing or failed to parse. */
+    readonly manifest?: FarmManifest;
+    /** A flat listing of the old, still-live farm. */
+    readonly farmListing: readonly ListingEntry[];
+    /** A flat listing of the canonical `~/.claude`. */
+    readonly canonicalListing: readonly ListingEntry[];
+}
+/**
+ * Plans the write-through reconciliation pass that runs before each resync builds its new scratch tree.
+ *
+ * A materialised directory stops being a live view of `~/.claude` and becomes a locally-built directory of symlinks frozen at resync time. Anything Claude Code writes into it afterwards — a brand-new project subdirectory, a new session file inside an existing one — lands as a real, untracked child: invisible to every other identity, and liable to be read as stale scaffolding and pruned by a later resync. This pass finds that data and copies it back into the canonical `~/.claude`, where it belongs, before anything else happens.
+ *
+ * The manifest is what makes this possible at all. A directory the farm materialised and a directory Claude Code created look identical on disk, so without the previous resync's own record of what it built, there is no way to tell the two apart. When the manifest is missing or unreadable, the pass falls back to **conservative mode** — every real directory in the farm is treated as materialised, so every real child anywhere becomes an adopt candidate — and reports it. That is deliberately over-eager rather than a silent no-op: over-adopting copies data into the place it was always meant to live, while under-adopting loses it.
+ *
+ * The pass is deliberately independent of the *new* resolved state. A directory whose new decision is `omit`, or one collapsing back from materialised to a plain symlink, still gets reconciled first — those are precisely the cases where the data would otherwise be discarded, which is the whole reason this exists.
+ *
+ * It is also idempotent: re-running against the same old farm after a crash mid-resync produces only `skip("identical-content")` for anything the interrupted run already copied across.
+ */
+export declare function planReconciliation(params: ReconcileParams): ReconciliationPlan;
+export {};