@vibe-commit/capture 0.8.0 → 0.10.0

package/dist/session_targets.d.ts

@@ -0,0 +1,713 @@
+/**
+ * `session_targets.ts` — what does this session belong to? (any-folder capture, R1 · R2 · R5 · R6 · R13 · R16 · R18)
+ *
+ * One module owns three things that used to be one hard-wired derivation ("the repo the turn ended in"):
+ *
+ *   1. **THE READER** — `scanTranscriptKeys`, the ONLY code that reads a field out of a transcript for attribution.
+ *      D60 §D6 exception 1 was "one value (the first `cwd`), backfill only"; D2 · A widened it to two field kinds on
+ *      every new record (each record's folder, and the path keys redaction already parses), in hooks and backfill, and
+ *      D15 · A made that surface ONE function so one test file and one audit cover it. It parses only lines that name a
+ *      key, keeps nothing but the set of strings found, and sends none of them anywhere.
+ *   2. **THE RESOLVER** — `resolveTargets` turns evidence into `Target[]`: which granted repos (and, at the end of a
+ *      repo-free session, which granted folder) this session's bytes go to, under which slug, ledger key and redaction
+ *      roots.
+ *   3. **THE TARGET RECORD** — per-session state that is sticky across firings: scan cursors, resolved roots, deferred
+ *      roots, targets, undecided names.
+ *
+ * ## ⛔ What this module must never do
+ *
+ *   - **Never mint a fallback identity.** A spawn refused while naming a repo DEFERS that root to the next firing; it never
+ *     becomes `local:<hash of the developer's path>` (R16 · D18, `spawn_budget.ts`'s own warning).
+ *   - **Never write `grants.json`.** Hooks never write the consent file; this module only READS consent.
+ *   - **Never decide a folder target before the end** (R18 · D21): only SessionEnd, `finalize` and backfill, after every
+ *     line was read.
+ */
+import { CodexTracker, type CallInfo, type CodexFolderEnv, type IdEntry } from "./codex_folders.js";
+import type { CwdKey } from "./agents/types.js";
+import type { RedactionScope } from "./redact.js";
+import { type CaptureStanding } from "./consent.js";
+import { type ProjectKeys } from "./project.js";
+/**
+ * The most bytes a firing STARTS scanning per stream (R16 · D18). A line that begins before this window is completed even
+ * if it ends beyond it (R18 · D21: a long line is read whole), so a firing always advances at least one line.
+ *
+ * ⚠ ITS OWN CONSTANT, not `pending_bound.ts`'s: that one bounds a different scan (the promotion bound) with different
+ * reasoning. The reasoning here is the spawn window: scanning feeds root resolution, and an unbounded first scan after an
+ * upgrade (a 14 MB session) could spend a firing.
+ */
+export declare const EVIDENCE_SCAN_WINDOW_BYTES: number;
+/**
+ * The longest single line the reader will hold to parse. Above it the line is SKIPPED for evidence, counted, and the
+ * session becomes "unknown" for folder purposes (R18). Equal to the window by design: "a line over 8 MiB is unknown".
+ */
+export declare const EVIDENCE_MAX_LINE_BYTES: number;
+/** What the reader looks for. Built from the registry row, never hand-written here (A3: one list, redaction's). */
+export interface EvidenceSpec {
+    /** Where a record names its folder (the dialect's `cwdKeys`). */
+    readonly cwdKeys: readonly CwdKey[];
+    /** Keys whose string value is a path, at any depth (`RedactionRules.pathKeys`). */
+    readonly pathKeys: ReadonlySet<string>;
+    /** Keys whose string value is itself a JSON document to descend into (`RedactionRules.nestedJsonKeys`). */
+    readonly nestedJsonKeys: ReadonlySet<string>;
+    /**
+     * C40 (1): also record, per line, which tool calls NAMED A FILE (a Claude `tool_use` whose input holds a path key) and which calls got their result
+     * (a `tool_result`), with the line's byte offset. Set only for a dialect whose results can name no file themselves (Claude's image Read).
+     */
+    readonly trackCalls?: boolean;
+    /**
+     * Part (b): the dialect is Codex, whose records name a folder on few types. With it the scan also keeps the TURN-FOLDER timeline (every change of the
+     * `session_meta` / `turn_context` cwd, with its byte offset) and records EVERY call (its folders; `[]` when they cannot be told) and the output that
+     * closes it, so a record's effective folder can be told later from the checkpoint alone (`codex_folders.ts`). Implies `trackCalls`. Every line is parsed:
+     * a Codex record that names no folder is judged by the turn folder in force, so no line can be skipped on its text.
+     */
+    readonly codexFolders?: boolean;
+}
+/**
+ * ⛔ The spec backfill's folder check uses: a top-level `cwd` and NOTHING else (the 10-24 one-value reading of D60 §D6
+ * exception 1). The hook's resolver builds its own spec from the registry; backfill's gate must not widen when that does.
+ */
+export declare const TOP_LEVEL_CWD_ONLY: EvidenceSpec;
+export type KeyKind = "cwd" | "path";
+export interface KeyHit {
+    readonly kind: KeyKind;
+    readonly value: string;
+}
+export type KeyScan = {
+    readonly kind: "unreadable";
+} | {
+    readonly kind: "ok";
+    /** Distinct `(kind, value)` pairs found, in first-seen order. */
+    readonly hits: readonly KeyHit[];
+    /**
+     * The byte offset after the last line fully processed. Resume here. Equal to `from` when nothing complete was found
+     * (an unterminated tail), so a caller can never skip bytes it did not read.
+     */
+    readonly scannedTo: number;
+    /** Lines over `EVIDENCE_MAX_LINE_BYTES`, skipped. Any non-zero count makes the session unknown for R18. */
+    readonly oversizeLines: number;
+    /**
+     * Evidence was DROPPED: more distinct strings than the scan keeps, or a record nested past the depth limit. "Every line
+     * was read" no longer holds (R18), so the caller treats the session as unknown, like an oversize line.
+     */
+    readonly capped: boolean;
+    /** The read budget ended inside an oversize line being skipped: the next call passes `continueSkipping` from `scannedTo`. */
+    readonly skipping: boolean;
+    /** A FINAL file's unterminated tail did not parse, so it was not consumed (`includeUnterminatedTail`): the stream cannot finish. */
+    readonly torn: boolean;
+    /** The file's size when it was read. `scannedTo === size` means this stream is fully scanned. */
+    readonly size: number;
+    /** C40 (1), only when `spec.trackCalls`: the calls opened and closed by the lines read, in file order. */
+    readonly calls: CallEvents;
+    /** Part (b), meaningful only when `spec.codexFolders`: the turn-folder changes the lines read made, the turn folder at `scannedTo`, and whether a record's folder could not be told. */
+    readonly folders: FolderEvents;
+};
+export interface FolderEvents {
+    /** `dir: null`: an UNREADABLE header cwd, the turn folder is unknown from `at` until the next readable one (C49 (6)). */
+    readonly changes: readonly {
+        readonly at: number;
+        readonly dir: string | null;
+    }[];
+    /** The session map (process id -> folders and where each was learned) and the cell map (script id -> ...) as they stand at `scannedTo`. */
+    readonly sessions: readonly (readonly [string, IdEntry])[];
+    readonly cells: readonly (readonly [string, IdEntry])[];
+    /** A call whose folder could not be told, an output whose call is not known, or a record that cannot be placed: the session's folders are not all determined (a folder target needs them). */
+    readonly unknown: boolean;
+    /** C56 (8): the offset of the first line this read skipped (too long to read), when it skipped one. */
+    readonly skipped?: number;
+}
+/** A tool call that named files (`paths` is never empty) at the byte offset of its line, or a result that closed one. */
+export interface CallEvents {
+    readonly opens: readonly {
+        readonly id: string;
+        readonly at: number;
+        readonly paths: readonly string[];
+        readonly incomplete?: true;
+        readonly tool?: string;
+        readonly files?: readonly string[];
+        readonly named?: true;
+    }[];
+    readonly closes: readonly {
+        readonly id: string;
+        readonly at: number;
+    }[];
+    /** Reserved: a read that cannot vouch for every call. A call whose input was too deep is not this (C44 (4)): its entry is marked `incomplete` instead. */
+    readonly overflow: boolean;
+}
+export interface ScanOptions {
+    /** Stop at the first `cwd` hit and return only that (backfill's folder check). */
+    readonly first?: boolean;
+    /** Treat bytes after the last newline as a final record (a finished transcript with no trailing newline). */
+    readonly includeUnterminatedTail?: boolean;
+    /** Test seam: the longest line held. */
+    readonly maxLineBytes?: number;
+    /** Test seam: the most distinct strings kept. */
+    readonly maxDistinctHits?: number;
+    /** The most bytes READ from disk in this call (default `EVIDENCE_SCAN_WINDOW_BYTES`). A line the budget ends inside is left for the next call. */
+    readonly maxReadBytes?: number;
+    /** Resume skipping an oversize line the previous call's budget ended inside. */
+    readonly continueSkipping?: boolean;
+    /** Part (b), `spec.codexFolders` only: where a resumed scan picks up (the turn folder, the session and cell maps) and the calls the checkpoint already knows. */
+    readonly codex?: {
+        readonly turn: string | null;
+        readonly sessions: readonly (readonly [string, IdEntry])[];
+        readonly cells: readonly (readonly [string, IdEntry])[];
+        readonly calls: (id: string) => CallInfo | undefined;
+        /** C62 (3): has the checkpoint seen a call with this id? */
+        readonly seen?: (id: string) => boolean;
+        /** The calls still waiting for an output at the resume point, oldest first (the tracker's open-call bound counts them). */
+        readonly openCalls: readonly (readonly [string, CallInfo])[];
+    };
+}
+/**
+ * Read `[from, …)` of a transcript and return the folders and paths its records name. ⛔ **THE ONLY TRANSCRIPT-FIELD
+ * READER** (D15 · A). It starts a line only before `to`, finishes that line however long (up to `maxLineBytes`), and stops.
+ * A line is parsed only if it mentions one of the keys; everything but the matching string values is discarded.
+ *
+ * ## ⛔ Bounded in what it READS, not only in what it parses (P1 review of A-T2)
+ *
+ * `maxReadBytes` caps the bytes read from disk in one call. A line the budget ends inside is NOT consumed: the cursor stays at
+ * its start and a fresh firing re-reads it whole (every line up to `maxLineBytes` fits one fresh budget). A line over
+ * `maxLineBytes` is never buffered: it is SKIPPED, counted once, and the scan keeps going to its newline; if the budget ends
+ * first, `skipping` is returned with the cursor advanced, and the next call passes `continueSkipping` so it resumes the skip
+ * instead of re-reading the line.
+ *
+ * `unreadable` (cannot open or stat) and a result with no hits are different facts and are told apart: a caller keeping sticky
+ * targets treats `unreadable` as "no NEW targets this firing" and carries on (Q4).
+ *
+ * ⚠ Keys are matched by their plain names. A writer that escaped an ASCII key (`"file\u005fpath"`) would be missed: no real
+ * transcript writer does (they emit keys verbatim), and the redactor, which parses the same lines, has the same reach.
+ */
+export declare function scanTranscriptKeys(path: string, from: number, to: number, spec: EvidenceSpec, options?: ScanOptions): KeyScan;
+/** Returns true when it could NOT look at everything (the depth limit): the caller treats that like a capped scan. */
+/**
+ * The folders ONE parsed record names, by the dialect's `cwdKeys`. ⛔ **Part of the single transcript-field reader**: record
+ * isolation (R17) asks this same function which folder a record ran in, so "where a record ran" has one definition.
+ */
+export declare function cwdsOfRecord(record: Record<string, unknown>, cwdKeys: readonly CwdKey[]): string[];
+/**
+ * How many firings may fail to name a root that has a `.git` before it is recorded `nonrepo`. A `.git` that `git rev-parse`
+ * will not answer for (dubious ownership, a corrupt repo, a stale worktree file, a timeout) is evidence of a repo we cannot
+ * name; it is retried a few times (a timeout heals) and then stops costing a slot per firing. Either way it STILL counts as a
+ * named repo for R6's folder rule: `nonrepo` here means "unnameable", never "not a repo".
+ */
+export declare const MAX_NAMING_FAILURES = 3;
+/** Candidate roots resolved per firing (R16 · D18). Each costs up to four spawns; the rest wait for the next firing. */
+export declare const MAX_NEW_ROOTS_PER_FIRING = 8;
+/** One place a session's bytes go. */
+export interface Target {
+    readonly kind: "repo" | "folder";
+    /** How this repo's work trees were grouped (`groupKey`); the sticky key. Absent on a folder. */
+    readonly groupKey?: string;
+    /** The wire identity (`X-Repo-Slug`), exactly as resolved. Never a fallback (R16). */
+    readonly slug: string;
+    /** ⛔ The ledger bucket: `SessionKey.repoKey`. ONE per (repo slug, session) (R5 · D6). */
+    readonly ledgerKey: string;
+    /** The redaction roots for this target's stream: its repo's work trees and main clone, or the folder. */
+    readonly redactionRoots: readonly string[];
+    /** Every work tree of this repo this session was seen in, first-seen order. `[]` for a folder. */
+    readonly worktrees: readonly string[];
+    readonly commonDir: string | null;
+    /** The launch folder (folder targets only). */
+    readonly folder?: string;
+    /** Worktree ledgers for this (slug, session) that were NOT adopted (O6): left unread, never merged. */
+    readonly setAsideLedgers: readonly string[];
+    /**
+     * C27: this session has named a work tree other than this target's (or its status is unknown). Sticky and monotonic, computed only from scanned
+     * bytes: once true it never goes back, so a record cannot be sent in a "single-repo" copy after the session turned out to be multi. A copy
+     * delivered BEFORE the session first named another tree kept its records (the accepted residual).
+     */
+    readonly multi?: true;
+}
+/** A repo or folder the session's evidence named that capture was never told about (R8 · D11 · B). Names only. */
+export interface UndecidedName {
+    readonly kind: "repo" | "folder";
+    readonly name: string;
+    readonly at: number;
+}
+export type RootInfo = {
+    readonly state: "repo";
+    readonly toplevel: string;
+    readonly commonDir: string;
+    readonly slug: string;
+    /** `[worktree, main clone]` as `confinementRoots` computed them, resolved ONCE. */
+    readonly roots: readonly string[];
+} | {
+    readonly state: "nonrepo";
+};
+interface StreamCursor {
+    readonly offset: number;
+    readonly size: number;
+    /** The previous firing's read budget ended inside an oversize line: resume skipping it, never re-read it. */
+    readonly skipping?: true;
+}
+/** C40 (1): the most calls still waiting for a result that one stream's checkpoint keeps; the oldest is dropped (and the log is `overflowed`). */
+export declare const MAX_OPEN_CALLS = 256;
+/** C44 (7a): the most dropped open-call ids a log remembers before it falls back to the sticky `overflowed`. */
+export declare const MAX_DROPPED_IDS = 4096;
+/** Calls whose result was seen, kept until every copy is past them (a late target starts at offset 0); the oldest is dropped (the `horizon` rises). */
+export declare const MAX_CLOSED_CALLS = 4096;
+/** Part (b): the most turn-folder change points one stream's timeline keeps; the oldest is dropped, and a position before the first kept point is unknown. */
+export declare const MAX_FOLDER_CHANGES = 4096;
+/**
+ * C75 (9): the timeline keeps at most `MAX_FOLDER_CHANGES` change points AND `CALL_LOG_BUDGET_BYTES` of folder text (4,096 points of 4,096 bytes are 16 MiB): the OLDEST points are
+ * dropped, and a position before the first kept point is unknown (the existing rule), so nothing is silently judged by a point that is gone.
+ */
+export declare function boundedChanges(changes: readonly {
+    readonly at: number;
+    readonly dir: string | null;
+}[]): {
+    at: number;
+    dir: string | null;
+}[];
+/** Part (b): a Codex stream's turn-folder timeline, ascending by byte offset. Written only from bytes the resolver scanned. */
+export interface FolderLog {
+    /** `dir: null`: an unreadable header cwd, the turn folder is unknown from `at` (C49 (6)). */
+    readonly changes: readonly {
+        readonly at: number;
+        readonly dir: string | null;
+    }[];
+    /** The session map (a process an `exec_command` started -> the folders of that call and the offset each was learned at), oldest first, at most `MAX_ID_MAP`. An id not here is unknown. */
+    readonly sessions?: readonly (readonly [string, IdEntry])[];
+    /** The cell map (a script an `exec` program started -> the folders of that program), same bounds. */
+    readonly cells?: readonly (readonly [string, IdEntry])[];
+    /** C56 (8): the offset of the first line of this stream the scan SKIPPED (too long to read). Sticky: an output whose call is unknown after it is unjudged. */
+    readonly skipped?: number;
+}
+/** One tool call that named files (C40 (1)). The paths are LOCAL checkpoint state, never sent; the entry is removed once every copy is past its result. */
+export interface CallEntry {
+    readonly id: string;
+    /** The byte offset of the line holding the call. */
+    readonly at: number;
+    readonly paths: readonly string[];
+    /** The byte offset of the line holding its result, or null while it has none. */
+    readonly closedAt: number | null;
+    /** C44 (4): the call's input was nested past the walk's depth, so `paths` may be partial: its result is `unknown`, never judged by them. */
+    readonly incomplete?: true;
+    /** Part (b), Codex: the tool the call named (`exec_command`, `exec`, `write_stdin`, ...): what its output teaches depends on it. */
+    readonly tool?: string;
+    /** Part (b), Codex (C48 (11)): the subset of `paths` that are FILES the call named (a patch's headers, `view_image`'s path): judged like a Claude path, by each copy. */
+    readonly files?: readonly string[];
+    /** C56 (1), Codex: the call carried files or evidence (evidence is not kept, only that there was some): evicting the entry must leave a mark that its output is unjudged. */
+    readonly named?: true;
+}
+/**
+ * One stream's call checkpoint, written only from bytes the resolver scanned. A result whose id is not an entry is `none` (a call that named no
+ * file: a stated residual) only when the log is complete AND the result is past the horizon; otherwise it is `unknown` and withheld.
+ */
+export interface CallLog {
+    readonly entries: readonly CallEntry[];
+    /** A result at or below this offset whose id is not an entry may belong to an entry that was dropped: unknown. */
+    readonly horizon: number;
+    /** A line was not read, the log began mid-stream, or `droppedIds` itself overflowed: every unmatched result is unknown. */
+    readonly overflowed: boolean;
+    /**
+     * C44 (7a): the ids of open calls the 256-entry cap dropped (a call that never got a result, in the biggest sessions). A result with one of these ids is
+     * `unknown`; an unmatched id that is not here, above the horizon, is `none`. Bounded; past the bound the log is `overflowed` for good.
+     */
+    readonly droppedIds?: readonly string[];
+    /** C56 (1), Codex: the ids of EVICTED calls (open past the cap, or closed past it) that carried files or evidence. Their outputs are UNJUDGED. Bounded like `droppedIds`. */
+    readonly droppedNamed?: readonly string[];
+    /** C56 (1): `droppedNamed` overflowed: every output whose call is not an entry is unjudged from here on. */
+    readonly droppedNamedAll?: true;
+    /**
+     * C62 (4): the ids of EVERY entry `pruneCalls` removed (named or not), bounded at MAX_DROPPED_IDS (the oldest is forgotten; NOT sticky). A call that reopens one of
+     * them is a REPEATED id (poisoned), whichever view judges it. Costs at most MAX_DROPPED_IDS short strings per stream in the persisted record.
+     */
+    readonly prunedIds?: readonly string[];
+}
+/**
+ * The per-session state that is sticky across firings. ⛔ Separate from every target's upload offsets (those live in the
+ * ledgers): R19's factual correction puts the discovery cursor, the unresolved roots and the deferred roots HERE so "the
+ * rest next firing" has somewhere to resume from, and so a ledger never carries discovery state.
+ */
+export interface TargetRecord {
+    readonly v: 1;
+    readonly sessionId: string;
+    /** The first folder any record named (Claude's first `cwd`; Codex's `session_meta`/`turn_context`). R6's "launch folder". */
+    readonly launchFolder: string | null;
+    /** Scan cursor per stream file key (`main`, `agent-<id>`). */
+    readonly scan: Readonly<Record<string, StreamCursor>>;
+    /** C40 (1): the call checkpoint per stream file key. Absent for a stream scanned before it existed: that stream fails closed. */
+    readonly calls: Readonly<Record<string, CallLog>>;
+    /** Part (b): the turn-folder timeline per Codex stream file key. Absent for a dialect that does not need it. */
+    readonly folders: Readonly<Record<string, FolderLog>>;
+    /** Part (b), sticky: a Codex record's folder could not be told (a call whose folder is unreadable, an output whose call is unknown, a record before any turn folder). A folder target needs every folder determined. */
+    readonly folderUnknown?: true;
+    /** A line over `EVIDENCE_MAX_LINE_BYTES` was skipped, or hits were dropped past the cap: "no repo" can never be proven (R18). */
+    readonly oversize: boolean;
+    /** How many times naming a root failed for a reason other than the spawn window (git would not name it). Bounded: see `MAX_NAMING_FAILURES`. */
+    readonly failures: Readonly<Record<string, number>>;
+    /** Resolved candidate roots, in first-seen order (JS preserves string-key insertion order). */
+    readonly roots: Readonly<Record<string, RootInfo>>;
+    /** Collapsed candidate roots not yet resolved: over the per-firing cap, or the spawn window ran out (R16). */
+    readonly unresolved: readonly string[];
+    /**
+     * Roots known ONLY from a ledger note (a ledger for this session sits under that work tree's digest) and never named by this
+     * transcript's evidence. They may be adopted into a repo group that evidence DID name (R5: the ledger to keep), but they never
+     * create a target on their own: a ledger written for another transcript of the same session id is not evidence about this one.
+     */
+    readonly ledgerOnly: readonly string[];
+    /** Sticky: once granted and created, a target keeps its ledger key for the life of the session (R5). */
+    readonly targets: readonly Target[];
+    readonly undecided: readonly UndecidedName[];
+    /** Targets that must stop receiving bytes, by repo group or folder slug (C3: `folder_repository_forbidden`). Sticky; `status` names a stopped folder (`readStoppedFolders`). */
+    readonly stopped: Readonly<Record<string, {
+        readonly at: number;
+        readonly code: string;
+    }>>;
+    /** `Resolution.settled` as of the last resolve: discovery exhausted. The drain skips a settled session's discovery (R19). */
+    readonly settled: boolean;
+    /** The transcript this session's hooks were handed, so a LATER firing of another session can finish its owed bytes (R19). */
+    readonly transcriptPath: string | null;
+    /** When a real hook firing last resolved this session (the drain does not count): "idle for ≥10 min" is measured from it. */
+    readonly firedAt: number;
+    readonly updatedAt: number;
+}
+export declare function emptyTargetRecord(sessionId: string): TargetRecord;
+/** The record, or null when absent or unreadable. ⚠ Null is a RESYNC, not an error: the scan restarts and ledgers are adopted. */
+export declare function loadTargetRecord(home: string, sessionId: string): TargetRecord | null;
+/** Atomic (temp + rename), mode 0600. ⛔ The CALLER holds the one per-session lock (O5); this module never takes it. */
+export declare function saveTargetRecord(home: string, record: TargetRecord): boolean;
+/** Every session's record on this machine, with its file and mtime, for the idle-session drain (R19). Unreadable ones are skipped. */
+export declare function listTargetRecords(home: string): {
+    path: string;
+    mtimeMs: number;
+    record: TargetRecord;
+}[];
+/** Names recent sessions' evidence left undecided, for `vibecommit status` (names only: no transcript is opened). */
+export declare function readUndecidedNames(home: string, sinceMs: number): readonly UndecidedName[];
+/** A folder target the server refused for good (C3), as `status` names it. */
+export interface StoppedFolder {
+    /** The folder's real path, as the target recorded it. */
+    readonly folder: string;
+    readonly slug: string;
+    readonly at: number;
+    readonly code: string;
+}
+/**
+ * The folder targets that were stopped (C3: `folder_repository_forbidden`) in the last `sinceMs`, newest per folder, for
+ * `vibecommit status`. Reads only the per-session target records through the same directory listing the drain and
+ * `readUndecidedNames` use: no transcript is opened, and a record the drain has forgotten is simply not there.
+ */
+export declare function readStoppedFolders(home: string, sinceMs: number): readonly StoppedFolder[];
+/**
+ * ⛔ A FOLDER TARGET'S LEDGER KEY IS NAMESPACED (C17 #1): `folder:<realpath>`, never the bare path. A ledger is keyed by the string
+ * its digest is taken of, and a work tree's ledger key IS its path; if the folder later became a git repo and the session resumed,
+ * the repo target would have adopted the folder's ledger and sent its offsets to the repo's server stream. A prefixed key can never
+ * equal a work-tree path, so the two can never collide.
+ */
+export declare const FOLDER_LEDGER_PREFIX = "folder:";
+export declare function folderLedgerKey(realLaunchFolder: string): string;
+/** `local:folder:<first 12 lowercase hex of sha256(realpath(launch folder))>` — C2. A no-repo remote keeps `local:<12 hex>`. */
+export declare function folderSlug(realLaunchFolder: string): string;
+/** Everything `resolveTargets` needs from its caller. The `seams` are for tests; production passes none. */
+/** The caller's session lock was lost while it resolved targets (C25). Nothing was written. */
+export declare class LockLostError extends Error {
+    constructor();
+}
+export interface ResolveContext {
+    readonly home: string;
+    readonly env: NodeJS.ProcessEnv;
+    readonly sessionId: string;
+    readonly transcriptPath: string;
+    /** The cwd the hook was handed (Claude: the shell's current folder). Null for finalize/backfill, which have none. */
+    readonly turnEndCwd: string | null;
+    /**
+     * `end`: SessionEnd, `finalize` or backfill — the only callers that may decide a FOLDER target, and only after the whole
+     * file was read (R18 · D21). `turn`: any other hook firing.
+     */
+    readonly mode: "turn" | "end";
+    readonly nowMs: number;
+    /**
+     * A drain of an IDLE session by another session's firing (R19): consent and discovery proceed, but this is not a firing OF the
+     * session. The file is read as FINAL for tail purposes only, so a crashed session's torn last line settles it; it never makes a
+     * folder target (that stays `end` mode's).
+     */
+    readonly drain?: boolean;
+    /**
+     * The roots whose naming failure THIS INVOCATION has already counted (C21 iv). An interactive verb (`finalize`, `backfill`) calls the
+     * resolver in a loop; the failure count exists to give up on a root that fails across SEPARATE invocations, so within one loop a
+     * root counts at most once, the first time it fails, in whatever round. Counting every round made a single git timeout, retried
+     * three times in milliseconds, mark the repository `nonrepo` for the session for good; counting nothing after round 1 let roots first
+     * tried in a later round go uncounted. Absent (a hook: one call per firing): every failure counts.
+     */
+    readonly countedThisInvocation?: Set<string>;
+    /**
+     * C25: the caller's session-lock heartbeat (`finalize`, `backfill`), called before each root is named (the slow step: a few git
+     * calls, each with its own timeout). When it says the lock is gone, `LockLostError` is thrown BEFORE anything is written, so a
+     * holder that lost the session never persists a record over its new owner's. A hook passes none.
+     */
+    readonly heartbeat?: () => boolean;
+    /**
+     * The turn-end repo the hook ALREADY resolved (its keys and its memoized slug thunk). Reused when a candidate root IS that
+     * work tree, so the hook still spends exactly one `rev-parse --show-toplevel` and one `remote get-url` for the repo it is in
+     * (`TODOS[87]`), instead of resolving it again here.
+     */
+    readonly known?: {
+        readonly keys: ProjectKeys;
+        readonly slugOf: () => string | null;
+    };
+    readonly seams?: {
+        readonly resolveKeys?: (dir: string) => ProjectKeys | null;
+        /** `null` = git could not say (a timeout or error): the root is DEFERRED, never given a fallback identity. */
+        readonly slugOf?: (toplevel: string) => string | null;
+        readonly rootsOf?: (keys: ProjectKeys) => readonly string[];
+        /** False when the spawn window is spent (R16). Default: the real `spawn_budget`. */
+        readonly spawnOk?: () => boolean;
+        /** Where a folder stands. Default `undecided` until folder grants exist (A-T5 wires `consent.ts`). */
+        readonly folderStanding?: (realFolder: string) => CaptureStanding;
+        readonly scanWindowBytes?: number;
+        readonly maxNewRoots?: number;
+        readonly maxLineBytes?: number;
+        readonly maxDistinctHits?: number;
+    };
+}
+export interface Resolution {
+    /** What to deliver this firing: sticky targets whose consent still holds. Never contains an undecided or denied name. */
+    readonly targets: readonly Target[];
+    readonly undecided: readonly UndecidedName[];
+    /**
+     * Every stream read to its end, no unresolved or deferred root, no oversize line, nothing unreadable. R18's "no repo" is
+     * decided only when this holds; R19's drain keeps calling until it does.
+     */
+    readonly complete: boolean;
+    /**
+     * DISCOVERY IS EXHAUSTED: every stream is at the furthest point it can ever reach (its end; for a final file a torn tail or an
+     * oversize skip that ran to the end), no root is unresolved, nothing vanished unfinished. Nothing a later firing could still
+     * discover. `settled && !complete` is exactly "fully read, and the FOLDER decision is permanently blocked" (an oversize or
+     * capped scan, a torn tail, a spool no note maps). R19's drain retires a settled session's DISCOVERY (its repo targets still
+     * deliver owed bytes either way), so a session that can never be fully read is not re-picked every firing and cannot starve the
+     * others. NOT settled: a window is left, a root is deferred, or a stream is unreadable: a later firing may still find a repo.
+     */
+    readonly settled: boolean;
+    /** False when the record could not be written: targets that would have been NEW this firing were deferred. */
+    readonly persisted: boolean;
+    /** Normalised slug of the repo the turn ended in, when it resolved as one: R19's "a target named by its turn-end cwd". */
+    readonly turnEndSlug: string | null;
+    readonly record: TargetRecord;
+}
+/** A stream the resolver reads for evidence: the main transcript or one delegated transcript. */
+export interface EvidenceStream {
+    readonly fileKey: string;
+    readonly path: string;
+}
+/**
+ * Every `agent-*.jsonl` under this session's `subagents/`, oldest first, each confined to the transcript roots.
+ *
+ * ⛔ **THE ONE COPY of sub-agent discovery** (A-T3 deletes `hooks/entry.ts`'s and imports this): `agent-*.jsonl`, never
+ * `agent-*` (the `.meta.json` sidecar would double every upload); every entry gated by `isInsideAny` so a symlink cannot walk
+ * out; the glob runs only for a dialect that declares `discover`.
+ */
+export declare function findSubagentTranscripts(home: string, env: NodeJS.ProcessEnv, transcriptPath: string): {
+    path: string;
+    fileKey: string;
+    size: number;
+    mtimeMs: number;
+}[];
+/**
+ * `findSubagentTranscripts` that also says whether the directory could not be LISTED (C17 #2): ENOENT is "no delegated streams",
+ * but EACCES or EIO is "unknown", and the resolver must not read unknown as empty (a folder could be authorized over a stream it
+ * never saw).
+ */
+export declare function findSubagentTranscriptsChecked(home: string, env: NodeJS.ProcessEnv, transcriptPath: string): {
+    found: {
+        path: string;
+        fileKey: string;
+        size: number;
+        mtimeMs: number;
+    }[];
+    listFailed: boolean;
+};
+/**
+ * Whether the dialect that owns this transcript can keep one repository's copy free of another's records (`isolatesContentRecords`).
+ * A transcript outside every dialect's root, or inside more than one, is NOT isolatable: fail closed.
+ */
+export declare function dialectIsolates(home: string, env: NodeJS.ProcessEnv, transcriptPath: string): boolean;
+/** The evidence spec for a transcript: redaction's key lists (A3: one list) plus the dialect's `cwdKeys`. */
+export declare function evidenceSpecFor(home: string, env: NodeJS.ProcessEnv, transcriptPath: string): EvidenceSpec;
+/**
+ * What a target's stream may contain beyond the structured-path rule (A-T4). `repo`: records that ran inside a work tree other
+ * than `ownRoots` are isolated (R17). `folder`: nothing inside any git work tree is kept (R6's exclusion roots).
+ */
+export interface Isolation {
+    readonly kind: "repo" | "folder";
+    /** A repo target's own roots (its work trees and main clone). Empty for a folder. */
+    readonly ownRoots: readonly string[];
+    /**
+     * C27: this copy belongs to a session that named another work tree, or whose status is unknown (a record that could not be read counts as multi).
+     * Absent only for a caller that has no record at all (a test): then no record is aggregated and no call is judged.
+     */
+    readonly multi?: boolean;
+    /**
+     * C40 (1): the call checkpoint per stream file key, as the resolver last wrote it; `null` when the record was unreadable (every result is then
+     * unknown and withheld). Absent with `multi`: no call is judged.
+     */
+    readonly calls?: Readonly<Record<string, CallLog>> | null;
+    /** Part (b): the turn-folder timeline per Codex stream, as the resolver last wrote it. */
+    readonly folders?: Readonly<Record<string, FolderLog>>;
+    /**
+     * C42: the hook may deliver a REPO copy past the scan cursor. Per-record decisions stay exact there; the two facts the cursor's checkpoint cannot
+     * hold (a call opened past it, a second work tree first named past it) are learned IN-SPAN, in file order, by this observer. Absent for finalize and
+     * backfill (they resolve to the end of the file first) and for a folder (it never delivers past the cursor).
+     */
+    readonly past?: PastCursor;
+}
+/** What one delivery learns from the bytes the persisted checkpoint cannot judge (C42 past the scan cursor, C43 at or below the call horizon). Lives for one delivery; never persisted, never sent. */
+interface SpanFacts {
+    /** The first byte this observer saw. Below it the persisted call log and multi flag decide; from it, in order, every record is observed. */
+    readonly start: number;
+    readonly spec: EvidenceSpec;
+    /** Every byte in `[start, coveredTo)` has been observed, in order. */
+    coveredTo: number;
+    /** Part (b), Codex: this stream's in-order state (turn folder, session and cell maps, the calls seen), the same tracker the resolver's scan uses. Bounded like the checkpoint. Replaced by a copy of the snapshot when the same bytes are read again (C65 (1)). */
+    tracker?: CodexTracker;
+    /** EVERY tool call opened at or after `start` (id -> position and paths; empty `paths` is a call that named no file, C44 (7b); `incomplete` is a truncated input). */
+    calls: Map<string, {
+        readonly at: number;
+        readonly paths: readonly string[];
+        readonly incomplete?: true;
+    }>;
+    /** Some bytes after `start` could not be observed: every result whose call is not known fails closed. */
+    unreliable: boolean;
+    /**
+     * C65 (1): the stream's facts as they stood when the latest read began (`at` is where it began, never below `start`). `deliver()` reads `[from, to)` again from
+     * the same `from` after a frame split or a 413; each byte must be stepped ONCE and every record judged with exactly the state after `[start, record)`, so a read
+     * that begins at `at` again starts from a copy of this, and a read that begins anywhere else below `coveredTo` fails closed.
+     */
+    snap?: {
+        readonly at: number;
+        readonly tracker?: CodexTracker;
+        readonly calls: Map<string, {
+            readonly at: number;
+            readonly paths: readonly string[];
+            readonly incomplete?: true;
+        }>;
+        readonly unreliable: boolean;
+    };
+}
+export interface PastCursor {
+    readonly cursors: Readonly<Record<string, number>>;
+    readonly facts: Map<string, SpanFacts>;
+    /**
+     * C44 (3): the in-span multi flag is SESSION-wide within one delivery (call state stays per stream), monotonic: the first record of any stream that names
+     * another work tree makes the rest of THAT stream multi and every stream delivered after it multi from its start. A stream already delivered keeps what
+     * it was judged with (the C36 (6) "before the first naming" class).
+     */
+    multi(fileKey: string, position: number): boolean;
+    /** Part (b): what places a Codex record at `position` of this stream: this observer's live state from where it started, else the persisted checkpoint. */
+    codexEnv(fileKey: string, position: number): CodexFolderEnv;
+    /** Make the stream's facts current for a read of `[from, to)`; true when the read needs the observer (past the cursor, or at or below the call horizon). */
+    begin(spec: EvidenceSpec, path: string, fileKey: string, from: number, to: number): boolean;
+    /** The read is done: its bytes are observed. */
+    end(fileKey: string, to: number): void;
+    observe(fileKey: string, record: Record<string, unknown>, offset: number): void;
+}
+export interface PastCursorOptions {
+    /** Test seam: the most gap bytes re-read (default 64 MiB). */
+    readonly maxGapBytes?: number;
+    /** Test seam: the chunk size of the gap read (default 4 MiB). */
+    readonly chunkBytes?: number;
+    /** The hook's shared send deadline (epoch ms). Between chunks, a remaining budget that cannot cover the next one fails the stream closed for the firing. Absent: unbounded (finalize, backfill). */
+    readonly deadlineAtMs?: number;
+    /** Test seam: the clock. */
+    readonly nowMs?: () => number;
+    /** Test seam: the longest gap line the observer will parse (default 4 MiB). */
+    readonly maxGapLineBytes?: number;
+}
+/**
+ * C42/C43: the observer for one delivery. `foreign` is the same stat-only test as record isolation (`workTreeRootOf`, nearest existing ancestor for a
+ * gone path, no spawn, cached); a path outside every work tree (the global CLAUDE.md, /tmp) is NOT another work tree and sets nothing.
+ *
+ * A stream needs it when the read goes past the scan cursor (C42: calls and a second work tree the checkpoint never saw), and when the read reaches a
+ * position at or below the call HORIZON (C43: calls were pruned once every then-existing copy was past them, so a copy created later, a repo granted
+ * after the fact, cannot judge a result by the log). Then it observes its OWN delivered bytes from the first one it delivers, in order. A call seen
+ * earlier gives its paths; one not seen gives `none` only when the observer started at byte 0 of the stream (it saw every byte before the result);
+ * a copy that starts mid-stream below the horizon keeps the persisted verdict (`unknown`), so a call the 4,096-entry cap dropped stays withheld.
+ */
+export declare function pastCursorOf(isolation: Isolation, cursors: Readonly<Record<string, number>>, options?: PastCursorOptions): PastCursor;
+/** `record`: the session's target record. `undefined`: no facts (legacy callers, tests). `null`: unreadable, so the copy fails closed. */
+export declare function isolationOf(target: Target, record?: TargetRecord | null): Isolation;
+/**
+ * The redaction scope for one stream (A-T4). Pure `stat` walks, memoised for the span (`workTreeRootOf` caches per directory);
+ * no git spawn, so it is free against a hook's budget. A cwd that is gone, or outside every work tree, is NOT another work tree:
+ * the record is kept (the structured-path rule still covers a file read from there).
+ *
+ * `stream` (C40 (1)): the file key of the stream being cut, and whether the dialect tracks calls; with it the scope judges each tool result by the
+ * checkpoint's record of its call, by the position the span reports (`at`).
+ */
+export declare function redactionScopeFor(isolation: Isolation, cwdKeys: readonly CwdKey[], stream?: {
+    readonly fileKey: string;
+    readonly trackCalls: boolean; /** Part (b): the dialect is Codex: a record's folder is its EFFECTIVE folder (`codex_folders.ts`). */
+    readonly codex?: boolean;
+}): RedactionScope;
+/**
+ * What makes two work trees ONE repository for a target (R5). A remote repo is its normalised slug. A repo with NO remote has a
+ * `local:<hash of its path>` slug that differs per work tree, yet its work trees share one git common dir and are one
+ * repository; grouping by slug alone would split a main clone and its worktrees into two targets and send a session twice.
+ * The slug SENT is the preferred member's (the turn-end work tree first), exactly as 0.8.0 sent the turn-end tree's.
+ */
+export declare function groupKey(info: Extract<RootInfo, {
+    state: "repo";
+}>): string;
+/** The log with its oldest path-bearing entries evicted until `free` bytes of path TEXT are freed (the table's own budget). */
+export declare function shedCalls(log: CallLog, free: number, includePathless?: boolean, measure?: "text" | "full", keepNewest?: number): CallLog;
+/**
+ * C76 (3): ONE budget for a whole SESSION. Every stream (the main transcript and each subagent's) has its own tables, each held to its own bound, and a session can have any number of
+ * streams. After a firing has folded its events, the bytes the session's streams store (call entries, the three id lists, the Codex id maps and the folder timeline) may not pass
+ * `SESSION_BUDGET_BYTES`. C77: they are counted by an UPPER bound of their JSON size (the fixed cost of an entry, the escaped length of every string), so the record on disk is within the
+ * budget, not near it.
+ */
+export declare const SESSION_BUDGET_BYTES: number;
+/** What a call entry takes in the record (an upper bound). */
+export declare function callEntryBytes(entry: CallEntry): number;
+/** What a whole session's records take by the same measure. Exported for the cells. */
+export declare function sessionBytes(calls: Readonly<Record<string, CallLog>>, folders: Readonly<Record<string, FolderLog>>): number;
+/**
+ * Shed the session down to `budget`, in place on the two records. Returns true when a Codex id map lost evidence. The stream that holds the most sheds (a heap gives it in O(log streams)),
+ * down to the next largest, or its share of the excess when several tie, never more than the excess; so no stream is emptied while another keeps its oldest calls. Two phases:
+ *  A. each pass takes at least `MIN_SHED_CHUNK` and runs, stopping as soon as its chunk is freed, (i) the stream's call entries STRICTLY OLDEST FIRST by position, with or without path
+ *     text, each with its departure marks, except its `RECENT_CALLS` newest (a result arrives right after its call: without that floor, a stream whose id lists alone fill its share would
+ *     lose its newest calls too); (ii) the oldest ids of its id lists, prunedIds first (not sticky), then droppedNamed, then droppedIds, each list's sticky mark set ONLY when it lost ids;
+ *     (iii) the oldest Codex id-map tombstones (the whole map reads UNKNOWN from there); (iv) the oldest text of its id maps (collapse); (v) the oldest timeline points.
+ *  B. only when NO stream has anything older left to shed, (vi) the newest call entries, by plain water-filling with no floor: a stream never loses the calls it was just scanned for
+ *     while another still keeps older content.
+ * Every step returns the exact bytes it freed and the sizes are kept by subtraction, a growth (an eviction that adds a mark) booked as a negative amount; a stream is left out only when no
+ * step changed anything. A firing costs O(streams + evictions), plus one measure of every stream.
+ */
+export declare function shedSession(calls: Record<string, CallLog>, folders: Record<string, FolderLog>, budget?: number): boolean;
+/**
+ * C40 (1): fold the calls one scan read into a stream's checkpoint. Opens first, then closes (a result always follows its call in the file). More than
+ * `MAX_OPEN_CALLS` waiting drops the oldest and marks the log overflowed; more than `MAX_CLOSED_CALLS` closed drops the oldest and raises the horizon.
+ * `unread` (an oversize line, an input too deep to read) marks the log overflowed: a call may have been missed.
+ */
+export declare function applyCallEvents(log: CallLog, events: CallEvents, unread: boolean): CallLog;
+/**
+ * C40 (1): remove the entries whose result EVERY copy is already past (`lowWater` is the smallest sent offset of the stream over the session's
+ * targets): the paths are gone as soon as nobody can need them. A later copy that still needs one (a target created late starts at offset 0) finds
+ * the horizon raised and reads the call as unknown: withheld, never kept.
+ */
+export declare function pruneCalls(log: CallLog, lowWater: number): CallLog;
+/**
+ * C40 (1): what the checkpoint says about the result of call `id` found at byte `at` of its stream. The entry's paths (judged per copy by the
+ * caller), `none` (the call named no file: kept, a stated residual), or `unknown` (withheld, failing closed).
+ */
+export declare function lookupCall(log: CallLog | undefined, id: string, at: number): readonly string[] | "none" | "unknown";
+/**
+ * Turn a session's evidence into targets. ⛔ **The caller holds the one per-session lock** (O5); this reads the record,
+ * scans new bytes, resolves a bounded number of new roots, and saves the record.
+ *
+ * Evidence (R2 · D2 · A): the turn-end folder, each stream's new records' folders and path keys, and repos holding a spooled
+ * commit for this session. Nothing else is read, kept or sent. Granted repos become sticky repo targets; the rest are
+ * recorded by NAME as undecided (R8) and capture nothing. A folder target exists only in `end` mode, after every line was
+ * read, when no repo at all was named and the launch folder is granted (R6 · R18).
+ */
+export declare function resolveTargets(ctx: ResolveContext): Resolution;
+/** The key a target is stopped under (`TargetRecord.stopped`): its repo group, or its folder slug. */
+export declare function stopKeyOf(target: Target): string;
+/**
+ * Stop ONE target for the rest of the session (C3: `folder_repository_forbidden`). Sticky, per target, never credential-wide;
+ * `status` names it. Returns false when the record could not be written (the target then retries and is refused again, which
+ * costs a request, not a byte).
+ */
+export declare function stopTarget(home: string, sessionId: string, target: Target, code: string, nowMs: number): boolean;
+export {};