agent-shim 7.13.1 → 7.14.0

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

@@ -1,61 +0,0 @@
-/**
- * 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

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

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

@@ -1,159 +0,0 @@
-import type { CategoryMap, CategoryName, Entries, LaunchFlags, OverridableCategory, WhenCondition } from "../config/schema";
-/** A layer's index in the assembled cascade. Strictly ascending in composition order: a higher id was composed later and therefore wins on the comparator's first rank. */
-export type LayerId = number;
-/** Where a cascade layer came from. Purely descriptive — precedence is carried by `LayerId`, never by kind. */
-type LayerKind = "global-config" | "config-profile" | "directory-rule" | "portable" | "portable-local" | "cli-override";
-/** One composable layer of the cascade: its own category toggles and entries overrides, plus the entries key order captured at load time. */
-export interface Layer {
-    readonly id: LayerId;
-    readonly kind: LayerKind;
-    /** Human-readable origin (a file path, or a profile name) used by `agent-shim check` to explain a decision. */
-    readonly source: string;
-    readonly categories?: CategoryMap;
-    readonly entries?: Entries;
-    /** The entries object's own key insertion order, from `src/config/load.ts`. Falls back to `Object.keys(entries)` when absent. */
-    readonly entryOrder?: readonly string[];
-    readonly launch?: LaunchFlags;
-}
-/** Facts about one entry under `~/.claude`, relative to `~/.claude` itself. */
-export interface EntryFact {
-    /** Path relative to `~/.claude`, forward-slash separated, never leading or trailing slash. */
-    readonly relPath: string;
-    readonly isDirectory: boolean;
-    /** True when the entry is itself a symlink (including the relative, tree-escaping symlinks that already exist inside a real `~/.claude`). */
-    readonly isSymlink: boolean;
-    /** The entry's own mtime. */
-    readonly mtimeMs: number;
-    /** The most recent mtime anywhere in this entry's subtree — its own mtime for a plain file. A directory-scoped `newerThan` must read this, never the directory's own inode mtime, which does not change when a file three levels down is rewritten. */
-    readonly latestMtimeMs: number;
-    /** The entry's own size. */
-    readonly sizeBytes: number;
-    /** The recursive total size of this entry's subtree — its own size for a plain file. A directory-scoped `maxSizeBytes` must read this, never the directory's own ~4KB inode size. */
-    readonly totalSizeBytes: number;
-}
-/**
- * Every fact the resolver needs, injected rather than read. Nothing in `src/resolve/` ever touches a real filesystem, git repository, clock, or environment: something else builds this structure and hands it over, which is what makes the whole resolver unit-testable with fake mtimes, a fake branch, and a fake environment.
- */
-export interface EntryFacts {
-    readonly nowMs: number;
-    /** The real home directory, used to expand `~` in `history/projects/` patterns. */
-    readonly home: string;
-    /** The canonical `~/.claude` directory every relative path in `entries` is relative to. */
-    readonly claudeHome: string;
-    /** The working directory the cascade was resolved for. */
-    readonly cwd: string;
-    /** The git branch checked out at `cwd`, or undefined when `cwd` is not in a repository. */
-    readonly branch?: string;
-    /** True when `cwd`'s repository is in detached-HEAD state, in which case no `branch` condition can match. */
-    readonly branchDetached?: boolean;
-    readonly env: Readonly<Record<string, string | undefined>>;
-    /** Every entry under `~/.claude`, keyed by its path relative to `~/.claude`. Directories appear alongside their descendants. */
-    readonly entries: ReadonlyMap<string, EntryFact>;
-}
-/** A single entries override, compiled into the form the resolver actually matches against. */
-export interface CompiledRule {
-    /** The key exactly as written in its source file, for diagnostics. */
-    readonly rawKey: string;
-    /** The category prefix the key declared. Cross-checked against the real classification of every path it matches. */
-    readonly declaredCategory: CategoryName;
-    /** The key with its category prefix stripped and (under `history/projects/`) its path fragment encoded — a pattern over paths relative to `~/.claude`. Two differently-spelled but equivalent keys share one canonical pattern and therefore collapse to one rule. */
-    readonly canonicalPattern: string;
-    readonly value: boolean;
-    readonly when?: WhenCondition;
-    readonly layer: LayerId;
-    /** The key's position within its own layer's entries object, used only by the comparator's final same-layer tie-break. */
-    readonly ordinal: number;
-    /** True when the canonical pattern contains no glob metacharacter. */
-    readonly isExact: boolean;
-    /** The pattern's leading run of literal (non-wildcard) characters. */
-    readonly literalPrefix: string;
-    /** How many `/`-separated segments the canonical pattern has. */
-    readonly segmentCount: number;
-    /** Matches the pattern itself and everything beneath it, so a rule on `skills` covers `skills/commit/SKILL.md`. */
-    readonly matches: (relPath: string) => boolean;
-}
-/** How a decision was reached, for `agent-shim check`'s "which layer decided this" output. */
-type DecisionVia = 
-/** The unconditional pre-cascade floor: the path's real classification is `secret`. */
-"secret-floor"
-/** Nothing in the classification map recognises the path's top-level entry. */
- | "unclassified"
-/** An entries rule matched and its condition (if any) held. */
- | "entry-rule"
-/** No entries rule survived; a layer's category toggle decided it. */
- | "category-override"
-/** No entries rule and no category toggle; the shipped default for the category decided it. */
- | "category-default";
-/** One entry's resolved sharing decision plus the reasoning behind it. */
-export interface Decision {
-    readonly relPath: string;
-    readonly shared: boolean;
-    readonly via: DecisionVia;
-    readonly category: CategoryName | null;
-    /** The winning entries rule, when `via` is "entry-rule". */
-    readonly rule?: CompiledRule;
-    /** Rules that matched but whose `when` condition failed, in descending specificity — each was eliminated and resolution continued to the next candidate. */
-    readonly eliminated?: readonly EliminatedRule[];
-}
-/** A candidate rule that matched the path but was eliminated because its `when` condition did not hold. */
-export interface EliminatedRule {
-    readonly rule: CompiledRule;
-    readonly failed: readonly string[];
-}
-/** Every diagnostic the resolver can raise. Codes are stable strings so `agent-shim check` and tests can assert on them. */
-type DiagnosticCode = 
-/** A profile's `extends` graph contains a cycle. */
-"EXTENDS_CYCLE"
-/** An `extends` entry names a profile that does not exist. */
- | "MISSING_PROFILE"
-/** An entries key was written under the `secret/` prefix. Rejected at compile time — `secret` can never be overridden by any layer. */
- | "SECRET_ENTRY_KEY"
-/** An entries key under some other prefix matched a path whose real classification is `secret`. Neutralised at resolve time by the floor check. */
- | "SECRET_PATH_NEUTRALISED"
-/** An entries key's declared category prefix disagrees with the real classification of a path it matched. */
- | "CATEGORY_PREFIX_MISMATCH"
-/** An entries key is not of the form `<category>/<path>`. The schema rejects these at parse time; this fires only for a layer built in code. */
- | "MALFORMED_ENTRY_KEY"
-/** An earlier layer's exact key lost to a later layer's glob. Correct per the comparator, but worth surfacing rather than resolving silently. */
- | "EXACT_ENTRY_OVERRIDDEN_BY_LATER_GLOB"
-/** A `history/projects/` pattern's encoded form could plausibly correspond to more than one real path. */
- | "AMBIGUOUS_PROJECT_ENCODING"
-/** A `history/projects/` key's path fragment is neither home-rooted nor absolute, so it cannot be encoded. */
- | "UNROOTED_PROJECT_PATH"
-/** A `~/.claude` entry nothing in the classification map recognises. */
- | "UNCLASSIFIED_ENTRY"
-/** An empty `when: {}` object, which is vacuously true and therefore has no effect. */
- | "EMPTY_WHEN"
-/** The previous farm's manifest is missing or unreadable, so reconciliation ran in conservative mode. */
- | "FARM_MANIFEST_MISSING"
-/** A file Claude Code wrote into a materialised farm directory differs from the canonical copy of the same path. */
- | "RECONCILE_CONFLICT"
-/** Reconciliation proposed adopting a path whose real classification is `secret`. Refused: the secret floor applies to data moving into `~/.claude` exactly as it applies to data moving out. */
- | "RECONCILE_SECRET_BLOCKED"
-/** A previous launch was interrupted mid-swap and this launch completed or undid the half-finished work. */
- | "FARM_SWAP_RECOVERED"
-/** A superseded farm could not be discarded because it still held data the new farm has its own entry for, so it was left on disk for the user to look at. */
- | "FARM_PREVIOUS_RETAINED";
-/** Severity of a diagnostic. An `error` means a configuration layer asked for something the tool refused to do. */
-type DiagnosticSeverity = "error" | "warning" | "info";
-/** One structured diagnostic. */
-export interface Diagnostic {
-    readonly code: DiagnosticCode;
-    readonly severity: DiagnosticSeverity;
-    readonly message: string;
-    /** The config key, profile name, or entry path the diagnostic concerns. */
-    readonly subject?: string;
-    /** The layer that raised it, when the diagnostic is attributable to one. */
-    readonly layer?: LayerId;
-}
-/** The flattened result of cascade phase one. */
-export interface FlattenedCascade {
-    /** The last value each overridable category was set to across every layer. Categories no layer touched are absent. */
-    readonly categories: ReadonlyMap<OverridableCategory, boolean>;
-    /** One compiled rule per canonical pattern — later layers having already overwritten earlier ones for identical patterns. */
-    readonly rules: ReadonlyMap<string, CompiledRule>;
-    /** Launch flags, last layer wins per field. */
-    readonly launch: LaunchFlags;
-    readonly diagnostics: readonly Diagnostic[];
-}
-export {};

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

@@ -1,85 +0,0 @@
-import type { DirectoryRule, GlobalConfig, PortableConfig } from "../config/schema";
-import { type ProfileLoader } from "./extends";
-import type { Diagnostic, Layer } from "./types";
-/** Injected predicate answering whether a directory can be read, so the walk stays pure. */
-export type ReadablePredicate = (dir: string) => boolean;
-/** Options for the upward directory walk. */
-export interface WalkOptions {
-    /** The user's home directory, the walk's default stopping point. */
-    readonly home: string;
-    /** Where to stop walking upward, inclusive. Defaults to `home`, and is what `walkUpLimit` in the global config sets. */
-    readonly limit?: string;
-    /** Answers whether a directory is readable. A directory that is not stops the walk there rather than failing the launch. */
-    readonly isReadable?: ReadablePredicate;
-}
-/**
- * Collects `cwd` and every ancestor of it, shallowest-first, the way Claude Code itself resolves nested `CLAUDE.md` files.
- *
- * The walk stops at (and includes) the limit directory — `$HOME` by default — or at the filesystem root when `cwd` is not beneath the limit at all. An ancestor that cannot be read stops the walk there rather than failing the launch: a directory you cannot read cannot carry a config file you were meant to obey.
- *
- * `cwd` is expected to already be a real path; resolving symlinks is the caller's job, so this stays free of filesystem access.
- */
-export declare function walkDirectoryAncestors(cwd: string, options: WalkOptions): string[];
-/** The up-to-three configuration sources that can apply at one directory level. */
-export interface DirectoryLevelSources {
-    readonly dir: string;
-    /** The committed, team-shared `.agent-shim.json` at this level. */
-    readonly portable?: {
-        readonly config: PortableConfig;
-        readonly entryOrder?: readonly string[];
-        readonly filepath: string;
-    };
-    /** Every rule in this user's own `~/.agent-shim/directory-rules.json` whose path is exactly this level, in file order. */
-    readonly rules?: readonly {
-        readonly rule: DirectoryRule;
-        readonly entryOrder?: readonly string[];
-        readonly filepath: string;
-    }[];
-    /** The gitignored `.agent-shim.local.json` at this level. */
-    readonly portableLocal?: {
-        readonly config: PortableConfig;
-        readonly entryOrder?: readonly string[];
-        readonly filepath: string;
-    };
-}
-/** Everything needed to assemble the full ordered layer sequence, all of it already loaded by the caller. */
-export interface CascadeInput {
-    readonly home: string;
-    /** The user-global `~/.agent-shim/config.json`, the least-specific layer above the shipped defaults. */
-    readonly globalConfig?: {
-        readonly config: GlobalConfig;
-        readonly entryOrder?: readonly string[];
-        readonly filepath: string;
-    };
-    /** The configuration profile chosen by the caller's own precedence rules: explicit flag, then the active identity's default, then the global default. */
-    readonly baseConfigProfile?: string;
-    readonly loadProfile: ProfileLoader;
-    /** Directory levels, shallowest-first, as produced by `walkDirectoryAncestors`. */
-    readonly levels?: readonly DirectoryLevelSources[];
-    /** One-off overrides from the command line or environment, composed last so they beat everything. */
-    readonly cliOverride?: {
-        readonly categories?: Layer["categories"];
-        readonly entries?: Layer["entries"];
-        readonly entryOrder?: readonly string[];
-        readonly launch?: Layer["launch"];
-    };
-}
-/** The assembled cascade: an ordered layer sequence plus what the walk itself decided. */
-export interface AssembledCascade {
-    readonly layers: readonly Layer[];
-    readonly diagnostics: readonly Diagnostic[];
-    /** The deepest directory-level `identity` pin encountered, which the launcher uses as a safety net beneath an explicit `@name`. */
-    readonly identityPin?: string;
-    /** The deepest directory-level `configProfile` selection encountered, which is what `agent-shim configure` treats as the active profile for a path. */
-    readonly directoryConfigProfile?: string;
-}
-/**
- * Assembles the full ordered layer sequence.
- *
- * Order is: the user-global config, then the base configuration profile's own `extends` chain, then every directory level shallowest-to-deepest, then one-off command-line overrides.
- *
- * Within one directory level, up to three sources fold most-personal-last: the committed `.agent-shim.json` (team-shared), then this user's own `directory-rules.json` entries for that exact path, then `.agent-shim.local.json` (this clone, this user, never committed). That three-source fold happens once per level, and the whole shallowest-to-deepest walk is one continuous sequence through those folded levels — a deeper level's three-source result composes on top of a shallower level's, never gathered per-source across the whole tree first.
- *
- * A level source that names a `configProfile` composes that profile's whole chain in *before* its own inline overrides, so the source reads as "everything that profile says, plus what is additionally true this far down the tree" rather than swapping the base profile out wholesale.
- */
-export declare function assembleCascade(input: CascadeInput): AssembledCascade;

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

@@ -1,15 +0,0 @@
-import type { CompiledRule } from "./types";
-/**
- * Whether the walk that builds entry facts must enter the directory at `dirRel` (relative to `~/.claude`). A directory it does not enter is one entry: nothing recorded below it, because nothing below it can be decided differently from the directory itself.
- */
-export type DescendPolicy = (dirRel: string) => boolean;
-/**
- * The walk policy for a flattened cascade. A directory is entered only when some rule can decide a path inside it differently from the directory itself, so a configuration with no rule below a top-level entry reads that entry with one `lstat`; with a rule that reads subtree aggregates anywhere, every directory is entered.
- *
- * Why this is safe: a rule matching a directory also matches everything beneath it (see `compileMatcher`), and the category toggles decide by top-level entry, so a subtree no rule reaches into resolves to one uniform decision, which the farm plan collapses to a single link either way.
- */
-export declare function descendPolicy(rules: Readonly<Iterable<CompiledRule>>): DescendPolicy;
-/**
- * `policy`, widened to also enter `target` and every directory on the way to it, for a caller that needs the direct children of that path recorded (the interactive picker). With no `target` it is `policy` itself.
- */
-export declare function enterRulesAnd(policy: DescendPolicy, target: string | undefined): DescendPolicy;

package/dist/types/usage/account.d.ts

@@ -1,20 +0,0 @@
-import { CliError } from "../cliError";
-import type { FarmFs } from "../launcher/ports";
-import { type AccountMetadata } from "./schema";
-/** Raised when an identity's `.claude.json` exists but cannot be read as account metadata (not a JSON object, or an `oauthAccount` field of an unexpected type): reported, never read as "no account". */
-export declare class AccountMetadataError extends CliError {
-    readonly file: string;
-    constructor(file: string, detail: string);
-}
-/** Whether `name` is a valid identity name, which is also what makes it safe as one path component under the identities and snapshots directories (no separator, no leading dot). */
-export declare function isIdentityName(name: string): boolean;
-/** The path of an identity's `.claude.json`. */
-export declare function claudeJsonPath(identitiesDir: string, identity: string): string;
-/**
- * Reads an identity's account metadata from the `oauthAccount` block Claude Code writes into the identity's `.claude.json` when it logs in: the fields `AccountMetadataSchema` names and nothing else (the token is never in this file; Claude Code keeps it in the Keychain or `.credentials.json`). Undefined when the identity has no `.claude.json` or no `oauthAccount` (a setup-token identity, or one never logged in). Throws `AccountMetadataError` for a file that is not a JSON object, and on an invalid identity name, which could otherwise name a path outside the identities directory.
- */
-export declare function readAccountMetadata(fs: Pick<FarmFs, "readFileUtf8">, identitiesDir: string, identity: string): AccountMetadata | undefined;
-/**
- * An account reader for the long-running door: re-reads an identity's `.claude.json` only when its modification time or size has changed, since the door records every request and the file (which also holds Claude Code's per-project history) can be large while its account block rarely changes.
- */
-export declare function createAccountReader(fs: Pick<FarmFs, "readFileUtf8" | "lstat">, identitiesDir: string): (identity: string) => AccountMetadata | undefined;

package/dist/types/usage/middleware.d.ts

@@ -1,17 +0,0 @@
-import type { ResponseObserver } from "../frontdoor/pipeline";
-import { type UsageRecord } from "./schema";
-/** The provider name an OAuth session's requests are recorded under: they go to Claude Code's own API. */
-export declare const ANTHROPIC_PROVIDER = "anthropic";
-/** Everything the usage middleware depends on, injected so it runs against fakes in tests. */
-export interface UsageMiddlewareDeps {
-    /** Persists one finished request's record. It may throw; the middleware catches and logs, so a store failure never reaches a request. */
-    readonly record: (record: UsageRecord) => void;
-    /** Runs work after the current turn of the event loop, so recording never sits between a route's `end` and whatever the route does next (production: `setImmediate`). */
-    readonly defer: (task: () => void) => void;
-    readonly now: () => number;
-    readonly log: (line: string) => void;
-}
-/**
- * The usage-tracking response middleware: registered at the front door's hook point, it records one metadata-only `UsageRecord` per routed response once its body has finished. The head gives the status, latency and rate-limit headers; the body, scanned incrementally as the client receives it (decompressing a copy when the upstream compressed it), gives the model and token usage. The response the client receives is never touched: the middleware sees each chunk only after the socket has it, keeps no body, and does its recording on a deferred turn. Every failure (a scanner, a decompressor, the store) is caught and logged, never thrown into the request.
- */
-export declare function createUsageMiddleware(deps: UsageMiddlewareDeps): ResponseObserver;

package/dist/types/usage/pick.d.ts

@@ -1,62 +0,0 @@
-import { type PlanClass } from "./plan";
-import type { AccountMetadata, UsageRecord, UsageSnapshot } from "./schema";
-/** The lengths of Anthropic's two subscription windows, used when a window reported no reset time of its own. */
-export declare const FIVE_HOUR_WINDOW_MS: number;
-/** Anthropic's longest prompt-cache lifetime (the one-hour tier): a conversation resumed within it still has a warm cache on the account that served it, and the cache is per organisation, so it is lost by switching. */
-export declare const PROMPT_CACHE_TTL_MS: number;
-/** The state a member's ranking was built from. */
-export interface PoolMember {
-    readonly identity: string;
-    /** The identity's usage snapshot, when it has one. */
-    readonly snapshot?: UsageSnapshot;
-    /** Why the member's recorded state could not be read (a corrupt or newer-schema snapshot, an unreadable login file), when that is the case. */
-    readonly readError?: string;
-    readonly account?: AccountMetadata;
-    /** The member's usage-log records from the current five-hour window on. */
-    readonly records: readonly UsageRecord[];
-}
-/** The member last picked for this directory, kept so a conversation stays on the account whose prompt cache is warm. */
-export interface StickyPick {
-    readonly identity: string;
-    readonly at: string;
-}
-export interface RankPoolInput {
-    readonly members: readonly PoolMember[];
-    readonly nowMs: number;
-    readonly sticky?: StickyPick;
-    /** True when the launch continues or resumes a conversation, which belongs on the account it started on whatever the cache lifetime. */
-    readonly resuming: boolean;
-}
-/** In pick order. `scored` has usable quota data; `unknown` has none (never recorded, or unreadable); `pay-per-use` bills by use instead of drawing on a plan; `ineligible` is refused right now. */
-type CandidateClass = "scored" | "unknown" | "pay-per-use" | "ineligible";
-export interface Candidate {
-    readonly identity: string;
-    readonly class: CandidateClass;
-    /** Plan-size-weighted remaining quota per hour until its reset: higher is more wasted if left unused. Present for `scored` only. */
-    readonly score?: number;
-    /** False when the five-hour window would run dry, at the observed pace, before it resets. A `scored` candidate that is not feasible ranks below every feasible one. */
-    readonly feasible: boolean;
-    /** When an `ineligible` candidate can be used again. */
-    readonly blockedUntilMs?: number;
-    readonly plan: PlanClass;
-    /** Human-readable facts behind the class and score, in the order they matter. */
-    readonly reasons: readonly string[];
-}
-export interface PoolRanking {
-    /** Every member, best first. */
-    readonly candidates: readonly Candidate[];
-    /** The member to launch on: the best one that is not refused. Undefined when every member is refused. */
-    readonly pick?: Candidate;
-    /** When nothing can be picked, the soonest any member comes back. */
-    readonly earliestReturn?: {
-        readonly identity: string;
-        readonly atMs: number;
-    };
-}
-/**
- * Ranks `members` for a launch.
- *
- * A member is `ineligible` while a window of its plan, or a refusal it last hit, still binds; it is `unknown` without recorded quota, `pay-per-use` when its usage bills by use, and otherwise `scored`. Scored members order by how much plan-size-weighted quota would expire unused per hour of runway, with any whose five-hour window would run dry at the observed pace (their own, or the person's pace on another member rescaled by plan size) placed behind those that would not. The member last picked for this directory then moves to the front if it is still usable and either the launch resumes a conversation or its prompt cache is still warm.
- */
-export declare function rankPool(input: RankPoolInput): PoolRanking;
-export {};

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

@@ -1,18 +0,0 @@
-import type { AccountMetadata } from "./schema";
-/** What an account's plan means for picking it: a subscription with a capacity relative to the smallest paid tier, or an account billed by use. */
-export type PlanClass = {
-    readonly kind: "subscription";
-    /** The plan's size as a multiple of the smallest subscription tier (Max 5x is 5, Max 20x is 20). */
-    readonly capacity: number;
-    /** False when the tier string named no multiplier and no tier this project knows, so `capacity` is the neutral 1 rather than a reading. */
-    readonly recognised: boolean;
-    /** The tier string the classification rests on, when the account had one. */
-    readonly tier?: string;
-} | {
-    readonly kind: "pay-per-use";
-    readonly tier?: string;
-};
-/**
- * Classifies an account from the rate-limit tier of its stored login (`organizationRateLimitTier`, which decides the organisation's limits, then `userRateLimitTier`). The tier strings are free text on Anthropic's side, so only the shapes seen are read: a trailing `<n>x` is that multiple, a bare `pro` is 1, a `zero` tier is pay-per-use. Anything else is a subscription of unrecognised size, counted as 1 and marked so the ranking can say it guessed.
- */
-export declare function planOf(account: AccountMetadata | undefined): PlanClass;

package/dist/types/usage/poolPick.d.ts

@@ -1,31 +0,0 @@
-import type { FarmFs } from "../launcher/ports";
-import type { LayoutPaths } from "../paths";
-import { type PoolMember, type PoolRanking, type StickyPick } from "./pick";
-import { type UsageReadFs } from "./read";
-/**
- * The store-backed side of pool picking: loads each member's recorded state and ranks it with `rankPool`, and keeps the per-directory record of the last pick. The launcher and `agent-shim pool pick` both go through `rankPoolFromStore`, so the command shows exactly what a launch would choose.
- */
-/** The reads a pool ranking needs: snapshots, the log and each member's login file. */
-export type PoolPickFs = UsageReadFs & Pick<FarmFs, "readFileUtf8">;
-type PoolPickPaths = Pick<LayoutPaths, "identitiesDir" | "usageLogDir" | "usageSnapshotsDir">;
-/** Reads each member's snapshot, login metadata and the part of the log that reaches into the current five-hour window. A member whose state cannot be read is carried with the reason instead of failing the pick. */
-export declare function loadPoolMembers(fs: PoolPickFs, paths: PoolPickPaths, identities: readonly string[], nowMs: number): readonly PoolMember[];
-/** Ranks `identities` from what the usage store recorded, as of `nowMs`. */
-export declare function rankPoolFromStore(params: Readonly<{
-    fs: PoolPickFs;
-    paths: PoolPickPaths;
-    identities: readonly string[];
-    nowMs: number;
-    sticky?: StickyPick;
-    resuming: boolean;
-}>): PoolRanking;
-/** The identity last picked from a pool for `directory`, with a note when the picks file was unreadable (a hint lost, never a launch blocked). */
-export declare function readStickyPick(fs: Pick<FarmFs, "readFileUtf8">, picksFile: string, directory: string): {
-    readonly sticky?: StickyPick;
-    readonly problem?: string;
-};
-/**
- * Records that `identity` was picked for `directory` at `nowMs`, dropping entries older than the usage log's retention so the file stays bounded by what the rest of the store keeps. The write is a whole-file atomic replace; two launches finishing together can lose one entry, which only costs a cache hint.
- */
-export declare function recordStickyPick(fs: Pick<FarmFs, "readFileUtf8" | "writeFilePrivate" | "mkdirPrivate">, picksFile: string, directory: string, identity: string, nowMs: number): void;
-export {};

package/dist/types/usage/preflight.d.ts

@@ -1,20 +0,0 @@
-import type { QuotaWindow, UsageSnapshot } from "./schema";
-/** A duration as its largest whole unit, such as `3h` or `2d`. */
-export declare function formatAge(ms: number): string;
-/** A quota window as it stands at a given instant. */
-export interface EffectiveWindow {
-    /** True when the window's reset time has passed, so the recorded observation describes a window that no longer exists. */
-    readonly reset: boolean;
-    /** The fraction used: 0 for a reset window, otherwise what was last observed (a lower bound, since utilisation only rises within a window), or undefined when none was reported. */
-    readonly utilization?: number;
-    /** The reset instant, for a window that has not reset yet and reported one. */
-    readonly resetsAtMs?: number;
-    /** The window's own status, for a window that has not reset yet. */
-    readonly status?: string;
-}
-/** Reads a recorded window at `nowMs`: a window whose reset has passed is empty and carries no status, so every consumer agrees on what an old observation still means. */
-export declare function effectiveWindow(window: Readonly<QuotaWindow>, nowMs: number): EffectiveWindow;
-/**
- * The launch-time warnings for an identity's quota, from the last rate-limit state the front door recorded for the provider this launch will use (`anthropic` for an OAuth launch). A window is reported when the API itself last marked it `allowed_warning` or `rejected`, and only while that window has not reset since: a reset time in the past means the observation describes a window that no longer exists. Each warning states how old the observation is, because the snapshot only changes when a request goes through the front door. Warnings never block a launch.
- */
-export declare function quotaWarnings(snapshot: UsageSnapshot | undefined, provider: string, nowMs: number): string[];

package/dist/types/usage/rateLimit.d.ts

@@ -1,25 +0,0 @@
-import { type LimitClassification, type UnifiedRateLimit } from "./schema";
-/** What a refused response's error body said, as far as classification needs: its machine-readable type and code, and its message, which is read here and never stored. */
-export interface ErrorInfo {
-    readonly type?: string;
-    readonly code?: string;
-    readonly message?: string;
-}
-/** Keeps a response's rate-limit headers (see `isRateLimitHeader`), names lowercased; undefined when there are none. */
-export declare function rateLimitHeadersOf(headers: Readonly<Record<string, string>>): Record<string, string> | undefined;
-/**
- * Parses Anthropic's unified subscription rate-limit headers, from `rateLimitHeadersOf`'s lowercased map. These were captured from a real `api.anthropic.com` response to an OAuth (subscription) session through the front door: `-status`, `-5h-status`, `-5h-utilization` (a fraction), `-5h-reset` (epoch seconds), the same three for `7d`, `-representative-claim`, `-reset`, `-overage-status`, `-overage-disabled-reason`, `-fallback` and `-fallback-percentage`. Undefined when the response carried none of them (an API-key or third-party provider response).
- */
-export declare function parseUnifiedRateLimit(headers: Readonly<Record<string, string>>): UnifiedRateLimit | undefined;
-/**
- * Classifies a refused response as a short rate limit or an exhausted quota, the distinction the credential fallback acts on (a short limit retries the same credential once its wait has passed, an exhausted quota moves to the next one). Only a 429 or a 402 is classified; anything else is undefined.
- *
- * An exhausted quota is any of: a 402 (OpenRouter's "insufficient credits"); Anthropic's unified status `rejected` with no extra usage to fall back on (`overage-status` absent or `rejected`), the rule Claude Code itself applies before it waits for the plan's reset; an error type or code in `QUOTA_EXHAUSTED_ERRORS`; or an error message naming a usage limit. Every other 429 is a short rate limit. `resetAt` comes from the unified reset header, `retryAfterSeconds` from `retry-after`.
- */
-export declare function classifyLimit(params: {
-    readonly status: number;
-    /** The response's rate-limit headers, as `rateLimitHeadersOf` returns them. */
-    readonly headers: Readonly<Record<string, string>>;
-    readonly error: ErrorInfo | undefined;
-    readonly nowMs: number;
-}): LimitClassification | undefined;