@vibe-commit/capture 0.1.0

package/dist/paths.js

@@ -0,0 +1,460 @@
+/**
+ * The `~/.vibecommit/` layout.
+ *
+ * One module so the fifteen tasks that build on this one do not each invent a
+ * path. Every function takes `home` explicitly rather than calling `os.homedir()`
+ * internally — the contract test runs the real binary against a temp HOME, and a
+ * module that reads the real one cannot be tested without touching the
+ * developer's own credentials.
+ *
+ * `CR-017d` added the repo to the binding key and hangs per-repo send state off
+ * `stateDir` — see `sessionStatePath` and `SessionKey` below.
+ *
+ * @provenance vibecommit-schema 20260809150000_cr017a_repo_binding_key.sql — PK shape, mirrored
+ * @provenance vibecommit-schema ingest_sessions.file_key — CHECK bound 1..128, retyped
+ */
+import { createHash } from "node:crypto";
+import { realpathSync } from "node:fs";
+import { join, sep } from "node:path";
+/** Root of the client's own state. Never Claude Code's — see the plan's keychain note. */
+export function rootDir(home) {
+    return join(home, ".vibecommit");
+}
+/** The ingest credential envelope. Mode 0600, enforced on read (`credential.ts`). */
+export function credentialsPath(home) {
+    return join(rootDir(home), "credentials.json");
+}
+/** The per-project consent allow list. Consulted BEFORE any transcript read (D56 §D19). */
+export function projectsPath(home) {
+    return join(rootDir(home), "projects.json");
+}
+/**
+ * The HUMAN lane's signed-in session — `CR-084d`. Mode 0600, enforced on read by
+ * the same `readSecretFile` the ingest credential goes through.
+ *
+ * A SECOND FILE and not a second field in `credentials.json`, deliberately. The
+ * two hold different privilege classes on different lanes: `credentials.json`
+ * holds the machine's opaque ingest credential and is read by every hook, and
+ * this holds a user-principal refresh token read only by interactive verbs. One
+ * file would mean the hook path opens the more powerful secret on every turn for
+ * no reason, and `VIBECOMMIT_TOKEN` (which overrides the ingest credential and
+ * nothing else) would acquire a meaning it does not have.
+ */
+export function sessionPath(home) {
+    return join(rootDir(home), "session.json");
+}
+/**
+ * Client state. `CR-023`'s capture-confirmed key lives here under `(repo, day)`;
+ * the three negative `systemMessage` states use a per-session file.
+ */
+export function stateDir(home) {
+    return join(rootDir(home), "state");
+}
+/**
+ * Once-per-session marker for a `systemMessage` state.
+ *
+ * Keyed on `(session, state)` and NOT on the transcript file: `ER23` keys client
+ * state per file, which would fire the same message once for `main` and once for
+ * every `subagents/agent-*.jsonl` in the same session.
+ */
+export function sessionNoticePath(home, sessionId, state) {
+    return join(stateDir(home), "notices", sanitise(sessionId), `${sanitise(state)}.json`);
+}
+/**
+ * Once-per-`(repo, day)` marker for the capture-confirmed notice — `CR-023d`.
+ *
+ * **The key is neither the session nor "ever", and both alternatives are wrong
+ * in a way you can feel.** `PreCompact` mints a fresh `session_id` mid-task, so
+ * a per-session key fires the one positive message twice in an afternoon and
+ * reads as a bug. A key with no day component fires it exactly once ever, which
+ * under-communicates on a tool used daily — and this is the single positive beat
+ * in a channel that is otherwise silent by design (style guide §10.1).
+ *
+ * A per-FILE key would be wrong too, once `CR-124` (W6) starts producing
+ * `agent-*` file keys: it would fire once for `main` and once per sub-agent
+ * transcript in the same session. The key is deliberately chosen so that landing
+ * `CR-124` cannot change how often this message appears.
+ *
+ * `repo-day/` namespaces this away from `sessionNoticePath`'s
+ * `notices/<session>/<state>.json`: the two live at different depths under
+ * `notices/`, so no session id can ever resolve onto a repo-day file.
+ *
+ * The repo is the same SHA-256 digest `sessionStatePath` uses, for the same
+ * reason — `sanitise` truncates at 128 characters, so two deep checkouts sharing
+ * a prefix would land on one key and the second repo would never see its
+ * confirmation. `day` is supplied by the caller as a UTC `YYYY-MM-DD`
+ * (`system_message.ts`'s `utcDay`), never read from a local clock here.
+ */
+export function repoDayNoticePath(home, repoKey, day, state) {
+    return join(stateDir(home), "notices", "repo-day", repoDigest(repoKey), sanitise(day), `${sanitise(state)}.json`);
+}
+/**
+ * Per-`(repo, session)` send state — `CR-018`'s offset ledger, backlog and
+ * terminal stop, keyed by `CR-017d`.
+ *
+ * **Returns null when there is no repo identity, and that is the fix.** D58: *"The
+ * server key gains repo; the client offset state did not, so a `prefix_sha256`
+ * resync would duplicate repo 1's turns into repo 2."* Keyed on the session alone
+ * this file was machine-wide, so one Claude Code session whose `cwd` moved between
+ * two repos read and wrote the same offsets for both. A caller with no repo must
+ * therefore get NO path at all rather than a shared bucket — a placeholder key is
+ * the bleed with an extra step (D72's "required from day one", mirrored).
+ *
+ * The repo is a SHA-256 digest and not the sanitised path: `sanitise` truncates at
+ * 128 characters, and two work trees sharing a long prefix would land in one
+ * directory — a silent collision at exactly the boundary being defended.
+ *
+ * Still one file per session rather than one per `(session, file)`, because `seq`
+ * is monotonic per SESSION across the main transcript and every sub-agent's, so
+ * splitting the store would split the counter that has to stay single.
+ */
+export function sessionStatePath(home, key) {
+    const dir = repoSessionsDir(home, key.repoKey);
+    if (dir === null)
+        return null;
+    return join(dir, `${sanitise(key.sessionId)}.json`);
+}
+/**
+ * Every session file for ONE repo — the directory `sessionStatePath` writes into.
+ *
+ * `status` needs this and a hook does not: a hook is handed a `session_id` on
+ * stdin, but `vibecommit status` is interactive and has none, so the only way it
+ * can answer "when did this repo last send?" is to look at every session under
+ * the repo (`CR-021`). Exposed rather than duplicated so there is still exactly
+ * one place that knows the layout, and the digest stays private.
+ *
+ * Null on no repo, for the same reason `sessionStatePath` is: there is no
+ * repo-less bucket, and a caller with no repo has nothing to scan.
+ */
+export function repoSessionsDir(home, repoKey) {
+    if (repoKey === "")
+        return null;
+    return join(stateDir(home), "sessions", repoDigest(repoKey));
+}
+/** A fixed-length, collision-free filename component for a work-tree path. */
+function repoDigest(repoKey) {
+    return createHash("sha256").update(repoKey).digest("hex").slice(0, 32);
+}
+/**
+ * Where Claude Code writes transcripts.
+ *
+ * `CLAUDE_CONFIG_DIR` is honoured because Claude Code honours it; hard-coding
+ * `~/.claude` would silently capture nothing for anyone who relocated it.
+ */
+export function transcriptRoot(home, env) {
+    const configured = env.CLAUDE_CONFIG_DIR;
+    const root = configured !== undefined && configured.trim() !== ""
+        ? configured.trim()
+        : join(home, ".claude");
+    return join(root, "projects");
+}
+/**
+ * Where Codex CLI writes transcripts — `CR-183`, D164.
+ *
+ * BESIDE `transcriptRoot` rather than inside it, because the two roots are two
+ * facts about two products: `CODEX_HOME ?? ~/.codex` plus `sessions`, against
+ * `CLAUDE_CONFIG_DIR ?? ~/.claude` plus `projects`. Folding them into one
+ * function taking a discriminant would make the union below read as a branch on
+ * a flag rather than as an enumeration of the registry, which is the property
+ * the confinement check depends on.
+ *
+ * ⚠ **The env var is honoured on the same evidence the Claude one is: because
+ * the product honours it.** Hard-coding `~/.codex` would silently capture
+ * nothing for anyone who relocated it.
+ */
+export function codexTranscriptRoot(home, env) {
+    const configured = env.CODEX_HOME;
+    const root = configured !== undefined && configured.trim() !== ""
+        ? configured.trim()
+        : join(home, ".codex");
+    return join(root, "sessions");
+}
+/**
+ * Where Cursor writes transcripts — `CR-193`, D177 §2.
+ *
+ * ⛔ **`projects`, and NOT the `agent-transcripts` directory D177 §2 names —
+ * because that root IS NOT EXPRESSIBLE HERE, and the reason is measured rather
+ * than argued.**
+ *
+ * One conversation's transcript lives at
+ * `~/.cursor/projects/<munged>/agent-transcripts/<cid>/<cid>.jsonl`, where
+ * `<munged>` is the WORKSPACE fsPath with every non-alphanumeric run collapsed
+ * to `-`. A `transcriptRoot` member is handed `home` and `env` and nothing else,
+ * and `<munged>` is derivable from neither: this machine already carries two of
+ * them, `Users-acohan-Documents-VibeCommit` and `empty-window`.
+ *
+ * ⚠ **And the obvious rescue — derive it from the consented project key — is
+ * measured WRONG, not merely awkward.** `resolveProjectKey` is
+ * `git rev-parse --show-toplevel`, and the workspace that produced the D177 §10
+ * corpus, `/Users/acohan/Documents/VibeCommit`, is **not a git repository at
+ * all**. The repository that IS one sits a directory below it, so its project
+ * key munges to that workspace's name with the child directory appended — a
+ * name with no directory under `projects/` — and a project-key-derived root
+ * would refuse the one real transcript there is.
+ *
+ * ⇒ ⛔ **The interior shape is enforced by `isCursorTranscript` instead**, which
+ * runs AFTER the registry-computed boundary and can only refuse. Read that
+ * function's docblock for what this changes about D177 §2's stated reason: it
+ * inverts it.
+ *
+ * ⚠ **No environment override, and that is an absence rather than an
+ * oversight.** `CLAUDE_CONFIG_DIR` and `CODEX_HOME` are honoured because those
+ * products honour them. No Cursor equivalent has been measured, and inventing
+ * one would be a configuration surface this client reads and nothing writes.
+ */
+export function cursorTranscriptRoot(home) {
+    return join(home, ".cursor", "projects");
+}
+/**
+ * The one child of a Cursor workspace directory that holds transcripts.
+ *
+ * Its three measured siblings are `agent-tools/` (scraped web content),
+ * `canvases/` (a React/TypeScript scratch project, `node_modules` and all) and
+ * `mcps/` (per-server tool schemas). D177 §2.
+ */
+const CURSOR_TRANSCRIPTS_DIR = "agent-transcripts";
+/**
+ * ⛔ **THE `.jsonl` GATE — `CR-193`, D177 §2**, which supersedes `CR-183`'s
+ * exclusion of `transcriptExtension`.
+ *
+ * The lane's file gate: `transport: "ndjson"` says every member appends NDJSON
+ * to a file, and `.jsonl` is what that file is called. Confinement answers
+ * *"may this path be read at all"*; this answers *"is this a transcript"*, and
+ * the two are different questions — a root can be exactly right and still
+ * contain files that are not transcripts.
+ *
+ * ⚠ **`root` is unused HERE and is a parameter of the member, because Cursor's
+ * answer needs it.** Under Claude's and Codex's roots every file is a
+ * transcript, so the suffix is the whole test; under Cursor's it is not.
+ *
+ * ⚠ **No `realpath`, deliberately, and only here.** A symlink whose name ends
+ * `.jsonl` and whose target does not is a real shape, and `isCursorTranscript`
+ * resolves for exactly that reason — but under these two roots there is nothing
+ * to point at: every file under them is a transcript already. Paying two
+ * syscalls per hook to defend a set with no members is the cost this note exists
+ * to decline.
+ */
+export function isTranscriptFile(_root, path) {
+    return path.endsWith(TRANSCRIPT_SUFFIX);
+}
+/**
+ * The lane's gate PLUS the interior shape Cursor's root cannot declare —
+ * `CR-193`, D177 §2.
+ *
+ * ⛔ **AND THIS IS WHERE D177 §2's STATED REASON INVERTS. Say it in these
+ * words, because the polarity is the whole point.** §2 records that the ROOT is
+ * what excludes the 32 KB scraped-web-content `.txt`, and that the gate
+ * therefore ships as fail-closed defence with **no corpus witness** —
+ * `agent-tools/` being a SIBLING of `agent-transcripts/`. That is true of the
+ * root §2 names. It is **false of the root that is expressible** (see
+ * `cursorTranscriptRoot`): rooted at `projects`, `find -type f` returns **113
+ * files, exactly 1 of them the transcript** — 66 `.json`, 34 `.ts`, 8 `.md`,
+ * 3 extensionless, 1 `.txt`. ⇒ ⛔ **the gate has 112 corpus witnesses and IS
+ * what excludes the `.txt`.** It is not defence in depth here; it is the
+ * mechanism.
+ *
+ * ⚠ **THOSE FIGURES ARE A CORRECTION.** This docblock first said 112/111. The
+ * total was summed from a per-extension HISTOGRAM rather than read from
+ * `find … | wc -l`, and the histogram's own `.jsonl` row was dropped in the
+ * addition — `feedback_bounded_output_is_not_a_count`, on the very measurement
+ * that motivates this function. Re-measured three ways that must agree:
+ * `-type f` = 113, `-name '*.jsonl'` = 1, `-not -name '*.jsonl'` = 112.
+ *
+ * ⛔ **The segment test is what puts D177 §2's boundary back.** A `.jsonl`
+ * anywhere under `projects` would otherwise be admitted for upload, and
+ * `agent-tools/` is precisely where Cursor spills whatever the agent
+ * downloaded. Requiring `<root>/<workspace>/agent-transcripts/…` reconstructs
+ * the root §2 asked for, as a narrowing applied AFTER the registry-computed
+ * boundary — so it can only refuse, never widen (D177 §7's direction test).
+ *
+ * ⚠ **`M0.3` measured ZERO non-`.jsonl` files INSIDE `agent-transcripts/`** (the
+ * whole directory holds one file). So the suffix half of this test still has no
+ * witness under the segment half, and absence from a corpus is not absence from
+ * the product — `D172 §2`'s `notebook_path` reasoning, unchanged.
+ *
+ * ⛔ **Resolved, because the segment names are the thing being trusted.**
+ * `isInside` already resolves both sides, so a path claiming to be under this
+ * root cannot be outside it; what a string test would still miss is a symlink
+ * INSIDE the root — `…/agent-transcripts/x.jsonl` pointing at
+ * `…/agent-tools/scrape.txt`, which passes confinement on the real path and
+ * passes a naive segment test on the claimed one. `isInside` is reused rather
+ * than re-implemented (`CR-183`); the resolution below exists only to locate the
+ * segments within it.
+ */
+export function isCursorTranscript(root, path) {
+    if (!isInside(root, path))
+        return false;
+    let realRoot;
+    let realPath;
+    try {
+        realRoot = realpathSync(root);
+        realPath = realpathSync(path);
+    }
+    catch {
+        return false;
+    }
+    if (!realPath.endsWith(TRANSCRIPT_SUFFIX))
+        return false;
+    const segments = realPath.slice(realRoot.length + 1).split(sep);
+    // `<workspace>` / `agent-transcripts` / at least one thing under it.
+    return segments.length >= 3 && segments[1] === CURSOR_TRANSCRIPTS_DIR;
+}
+/**
+ * Where Claude Code writes DELEGATED work — `CR-124`, D76.
+ *
+ * `<dir>/<session-id>/subagents/`, beside `<dir>/<session-id>.jsonl`. Derived
+ * from `transcript_path` because there is no environment variable for it and
+ * the hook is never handed one: the session id is the transcript's own basename.
+ *
+ * Measured on this machine rather than read from documentation — and the
+ * measurement carries a trap. The directory holds an `agent-<id>.meta.json`
+ * sidecar beside every `agent-<id>.jsonl`, **636 of each**, exactly 1:1. A
+ * `agent-*` glob would therefore double every upload and send metadata as if it
+ * were transcript content. The caller globs `agent-*.jsonl`.
+ *
+ * Returns null for a path that is not a `.jsonl`, rather than inventing a
+ * directory next to something that was never a transcript.
+ */
+export function subagentsDir(transcriptPath) {
+    if (!transcriptPath.endsWith(TRANSCRIPT_SUFFIX))
+        return null;
+    return join(transcriptPath.slice(0, -TRANSCRIPT_SUFFIX.length), "subagents");
+}
+const TRANSCRIPT_SUFFIX = ".jsonl";
+/**
+ * The `file_key` a sub-agent transcript travels under: its basename, minus
+ * `.jsonl`.
+ *
+ * From the FILENAME, deliberately. Every record inside also carries `agentId`,
+ * but reading a value out of a file to name that file is analysis this client is
+ * not licensed to do (D60 §D6 / §D1a) and does not need.
+ *
+ * Null when the key would breach the server's 1..128 bound
+ * (`ingest_sessions.file_key`'s CHECK, `CR-008`): a delta the server 400s is
+ * classed `never` and would advance the offset past bytes it never stored.
+ * Longest key measured on this machine is 49 characters, so this is a bound
+ * being respected rather than one being hit.
+ */
+export function subagentFileKey(fileName) {
+    if (!fileName.startsWith("agent-") || !fileName.endsWith(TRANSCRIPT_SUFFIX))
+        return null;
+    const key = fileName.slice(0, -TRANSCRIPT_SUFFIX.length);
+    return key.length >= 1 && key.length <= 128 ? key : null;
+}
+/**
+ * The `file_key` an ANNOUNCED sub-agent transcript travels under — `CR-196`,
+ * D177 §9. ⛔ **`agent-<childId>`, SYNTHESIZED HERE, CLIENT-SIDE.**
+ *
+ * ## ⛔ Why this sits BESIDE `subagentFileKey` and not inside it
+ *
+ * They are opposite jobs on opposite layouts, and one function doing both would
+ * be strictly worse at each:
+ *
+ *   `subagentFileKey`  a FILTER. Claude's `subagents/` directory is globbed, so
+ *                      the caller sees `agent-<id>.jsonl`, `agent-<id>.meta.json`
+ *                      and anything else that is in there — and the prefix test
+ *                      is what REFUSES the sidecar and `main.jsonl`. Relaxing it
+ *                      to "mint a prefix if one is missing" would make the
+ *                      discover path accept every one of those.
+ *   this               a CONSTRUCTOR. Cursor's children are `<childId>.jsonl`
+ *                      with **no prefix at all**, and the path was HANDED over
+ *                      rather than found, so there is nothing to filter — the
+ *                      only question is what to call the stream.
+ *
+ * ## ⛔ The key stays FILENAME-derived, which is what keeps D60 §D6 intact
+ *
+ * `<childId>` is the announced path's BASENAME. It is not read out of any
+ * record inside the file, so *"do not read a value out of a file to name that
+ * file"* still holds — the same rule `subagentFileKey`'s own docblock states
+ * about `agentId`. What arrives on stdin is a PATH; this reads its name.
+ *
+ * ## ⛔ WIDENING `ingest_sessions.file_key` WAS CONSIDERED AND DECLINED (D177 §9)
+ *
+ * Five independent layers refuse a bare `<childId>`, and a DB-only widening
+ * would not have worked at all: `subagentFileKey`'s own prefix test, `post.ts`'s
+ * `FileKey` type, `cr008`'s CHECK (whose C5/C6/C7 cells pin more than the CHECK
+ * line shows), the server's family check — where a 400 classes `never`, advances
+ * the offset and stamps a PERMANENT gap — and the health classifier, which
+ * would silently reclassify every sub-agent stream as a MAIN stream. Synthesis
+ * touches none of them: no migration, no production deploy.
+ *
+ * ## The prefix is added UNCONDITIONALLY, and that is what makes it injective
+ *
+ * A child literally named `agent-x.jsonl` becomes `agent-agent-x`, which is
+ * ugly and is the only answer that cannot collide: `x` → `agent-x` and
+ * `agent-x` → `agent-agent-x` stay distinct, where "prefix only if missing"
+ * maps both onto `agent-x` — two streams sharing one offset ledger.
+ *
+ * Null when the key would breach the server's 1..128 bound, exactly as
+ * `subagentFileKey` is, and null for an empty `<childId>`: a bare `agent-` is
+ * REJECTED by `cr008`'s CHECK (`like 'agent-_%'`), and its C5 cell pins that.
+ */
+export function announcedSubagentFileKey(fileName) {
+    if (!fileName.endsWith(TRANSCRIPT_SUFFIX))
+        return null;
+    const childId = fileName.slice(0, -TRANSCRIPT_SUFFIX.length);
+    if (childId === "")
+        return null;
+    const key = `agent-${childId}`;
+    return key.length <= 128 ? key : null;
+}
+/**
+ * Is `candidate` really inside `root`?
+ *
+ * `/cso` finding 1 (2026-08-09), HIGH. `transcript_path` arrives on hook stdin
+ * and was read and uploaded verbatim under the user's ingest credential, with no
+ * check that it was a transcript at all. Anything that could put a hook
+ * definition in front of Claude Code could therefore point the client at
+ * `~/.ssh/id_rsa` and have it shipped off the machine — and the hook contract's
+ * exit-0 silence meant nothing would show on any stream. The silence that makes
+ * the hook safe for the developer's turn is what made that quiet.
+ *
+ * `realpathSync` on BOTH sides, so a symlink cannot walk out of the root: a
+ * string prefix test on the unresolved path is exactly the check that misses
+ * `~/.claude/projects/x -> /etc`. A missing path resolves to "outside", because
+ * a transcript we cannot resolve is not one we should read.
+ */
+export function isInside(root, candidate) {
+    let realRoot;
+    let realCandidate;
+    try {
+        realRoot = realpathSync(root);
+        realCandidate = realpathSync(candidate);
+    }
+    catch {
+        return false;
+    }
+    return realCandidate === realRoot || realCandidate.startsWith(realRoot + sep);
+}
+/**
+ * Is `candidate` inside ANY of `roots`? — `CR-183`, D164 §5.
+ *
+ * ⛔ **A WRAPPER, and `isInside` above is byte-unchanged.** The union is a
+ * second agent's root being added to the SET the check runs over; it is not a
+ * loosening of what "inside" means, and rewriting the resolved-path comparison
+ * to take a list would have put the `/cso` finding-1 remediation back on the
+ * table for a change that is about membership.
+ *
+ * ⛔ **`roots` comes from the REGISTRY. It must never be derived from input.**
+ * A caller that built this list out of anything on hook stdin would have handed
+ * the confinement boundary to the value the boundary exists to constrain.
+ *
+ * Empty `roots` refuses everything, which is the right direction: no known root
+ * means nothing is known to be inside one.
+ */
+export function isInsideAny(roots, candidate) {
+    return roots.some((root) => isInside(root, candidate));
+}
+/**
+ * Reduce an untrusted id to a filename component.
+ *
+ * `session_id` arrives on hook stdin and is attacker-influenced in the sense that
+ * matters here: it reaches `path.join`. Whitelisting is the only safe direction —
+ * a blacklist of `..` and `/` misses NUL, backslash on Windows, and the empty
+ * string, each of which resolves somewhere other than intended.
+ */
+function sanitise(value) {
+    const cleaned = value.replace(/[^A-Za-z0-9._-]/g, "_").slice(0, 128);
+    return cleaned === "" || /^\.+$/.test(cleaned) ? "_" : cleaned;
+}
+//# sourceMappingURL=paths.js.map

package/dist/paths.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"paths.js","sourceRoot":"","sources":["../src/paths.ts"],"names":[],"mappings":"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"}

package/dist/policy.d.ts

@@ -0,0 +1,195 @@
+/**
+ * The failure policy — CR-018, D58 (plan §ER22/§ER10/§ER11/§ER4).
+ *
+ * The defect this replaces, verbatim from the register: *"5xx was unclassified
+ * and fell through to advance-and-discard; 401/413 never succeed."* Every failed
+ * POST used to reach the same code, so the offset moved forward as if the bytes
+ * had been delivered. They had not.
+ *
+ * ## Three classes, and why `never` and `fatal` are not the same class
+ *
+ *   later   Hold the offset. The NEXT hook invocation retries from the same
+ *           point. Transient: 5xx, no-response, 429, and 403 — a 403 here is
+ *           org-approval-pending, which means later, not failed (D60 §D12).
+ *   never   Advance PAST the failing bytes and stamp a gap, so the record shows
+ *           an honest hole instead of pretending nothing happened. Per-PAYLOAD:
+ *           resending the identical bytes cannot work (413, structurally
+ *           malformed 4xx).
+ *   fatal   Stop attempting further sends for this session until the user
+ *           reconnects. Per-CREDENTIAL, which is the whole difference from
+ *           `never`: 401 does not describe these bytes, it describes the token.
+ *
+ * **`later` never means a synchronous retry inside one hook invocation.** D56
+ * plan §D8 is a founder override that is not to be re-argued: the hook must never
+ * block or slow a developer's turn. "Later" means the bytes stay in the
+ * transcript file — which is where they already are — and the hook that fires on
+ * the next turn picks them up from the same offset.
+ *
+ * ## The table is data on purpose
+ *
+ * The title's word "table" is load-bearing. The classification is a literal data
+ * structure, so it is auditable by reading it and testable without exercising a
+ * real network failure. The original bug was an UNCLASSIFIED status silently
+ * defaulting to lossy behaviour, so the default here is explicit and it is
+ * `later` — the safe direction. A status nobody enumerated holds its bytes; it
+ * never discards them.
+ *
+ * This module is PURE. No fs, no network, no clock — `state.ts` persists, and the
+ * caller supplies `nowMs`. That is what lets both backlog caps be tested at their
+ * boundaries without waiting a day for one of them.
+ */
+import type { SendOutcome } from "./post.js";
+export type FailureClass = "later" | "never" | "fatal";
+/** What a completed attempt means. `ok` is the only non-failure. */
+export type Disposition = "ok" | FailureClass;
+/**
+ * THE TABLE. Status codes named one by one, because a family rule that swept up
+ * a whole `4xx` would be the implicit fallthrough this task exists to remove.
+ *
+ * Adding a row is how a new structurally-invalid status becomes `never`. Until
+ * someone does, an unnamed `4xx` resolves to `DEFAULT_CLASS` and HOLDS its bytes:
+ * a status we have not reasoned about is not one we discard data for.
+ */
+export declare const STATUS_CLASSES: ReadonlyMap<number, FailureClass>;
+/** `5xx` — the server's problem, not the payload's. */
+export declare const SERVER_ERROR_CLASS: FailureClass;
+/** No HTTP response at all: DNS, refused, TLS, timeout, abort. */
+export declare const NETWORK_CLASS: FailureClass;
+/**
+ * The explicit default. **It is `later` and it must stay `later`.** An implicit
+ * fallthrough to advance-and-discard is the original defect at a smaller scale.
+ */
+export declare const DEFAULT_CLASS: FailureClass;
+/** Classify one HTTP status. `2xx` is the only success. */
+export declare function classifyStatus(status: number): Disposition;
+/** Classify one attempt, response or not. */
+export declare function classify(outcome: SendOutcome): Disposition;
+/**
+ * The §13.6 copy for a class.
+ *
+ * `ERRORS` was scaffolded for this task and carries exactly these three lines, so
+ * this is the one place a class becomes a sentence. Nothing in the HOOK path
+ * calls it — a hook speaks only through `systemMessage` (§13.7) — but `CR-021`'s
+ * `status` needs a class-to-copy mapping and this is where it belongs rather than
+ * as a fourth `switch` in a verb body.
+ */
+export declare function failureCopy(cls: FailureClass): string;
+/**
+ * One undelivered span of a transcript file.
+ *
+ * The bytes themselves are not copied anywhere: the transcript is append-only and
+ * still on disk, so a span is a coordinate pair, not a spool. `at` is when this
+ * span was FIRST left undelivered, which is what the age cap measures.
+ */
+export interface BacklogEntry {
+    /** Byte offset, inclusive. */
+    readonly from: number;
+    /** Byte offset, exclusive. */
+    readonly to: number;
+    /** Epoch ms of the first failed attempt covering this span. */
+    readonly at: number;
+}
+/** Per-(session, file) send state. `state.ts` persists it; this module decides it. */
+export interface FileState {
+    /** Everything below this is delivered, or deliberately gapped. */
+    readonly sentOffset: number;
+    /** Contiguous undelivered spans, oldest first. `[0].from === sentOffset`. */
+    readonly backlog: readonly BacklogEntry[];
+    /** Bytes we advanced past without delivering. Counters, never a growing list. */
+    readonly gapBytes: number;
+    readonly gapCount: number;
+    /**
+     * Epoch ms of the last DELIVERED span, or 0 for "never" — `CR-021`.
+     *
+     * The only success clock in the store. `BacklogEntry.at` stamps a HELD span,
+     * i.e. a failure, so `status` had nothing honest to render before this.
+     *
+     * **0 means unknown, not the epoch.** A state file written before this field
+     * existed parses to 0 (`nonNegative`), and rendering that as 1 January 1970
+     * would be a confident lie about a value we simply do not have.
+     */
+    readonly lastSentAt: number;
+}
+export declare const EMPTY_FILE_STATE: FileState;
+/**
+ * The caps.
+ *
+ * ⚠ **Neither the register nor `DECISIONS.md` specifies an eviction policy once a
+ * cap is hit.** What is decided is only that both caps exist. The rule below is
+ * this task's choice, stated rather than smuggled: **drop the oldest span,
+ * advance past it, stamp a gap, continue.** It is the `never` class's own shape
+ * applied to our own storage, and it is the only option that neither grows
+ * unbounded nor blocks — the two things D56 §D8 forbids outright.
+ *
+ * `entries` is not a third policy. It is the same drop-oldest rule guarding the
+ * degenerate shape where a file grows one byte at a time: the byte cap alone
+ * would permit `MAX_BACKLOG_BYTES` single-byte entries.
+ */
+export declare const BACKLOG_CAPS: {
+    readonly bytes: number;
+    readonly ageMs: number;
+    readonly entries: 512;
+};
+export interface BacklogCaps {
+    readonly bytes: number;
+    readonly ageMs: number;
+    readonly entries: number;
+}
+/**
+ * Read the caps from the environment.
+ *
+ * Same shape as `hookBudgetMs`: an unset or unparseable value takes the default
+ * rather than disabling the cap, because a cap that an empty string can switch
+ * off is not a cap. Present for operators with unusual transcript volumes and
+ * for the tests, which have to reach a boundary they cannot otherwise reach.
+ */
+export declare function resolveCaps(env: NodeJS.ProcessEnv): BacklogCaps;
+/** Undelivered bytes currently held. */
+export declare function pendingBytes(state: FileState): number;
+/**
+ * The span the next attempt should carry: everything from the offset to `eof`.
+ *
+ * A file SHORTER than the offset means the transcript was replaced or truncated —
+ * a new file at a path we have state for. Resync from 0 rather than reading a
+ * negative-length slice; the server is idempotent on `(session, offset)`.
+ */
+export declare function nextSpan(state: FileState, eof: number): {
+    from: number;
+    to: number;
+} | null;
+/**
+ * Everything up to `to` arrived. The backlog clears, and the success is STAMPED.
+ *
+ * `nowMs` is a parameter rather than a `Date.now()` call because this module is
+ * pure — that is what lets both backlog caps be tested at their boundaries
+ * without waiting a day, and the same property now covers the `last sent` row.
+ */
+export declare function markDelivered(state: FileState, to: number, nowMs: number): FileState;
+/**
+ * `never` — advance PAST the attempted span exactly once, stamping a gap.
+ *
+ * Exactly once is the point: the offset lands at `to`, so the next invocation
+ * starts on the next, unrelated chunk. It neither loops on the poisoned bytes nor
+ * swallows what comes after them.
+ */
+export declare function markSkipped(state: FileState, from: number, to: number): FileState;
+/**
+ * `later` — hold the offset and remember when this span first failed.
+ *
+ * The span is appended only when the file has actually grown past what is already
+ * held. A hook that fires twice on an unchanged file retries the same span rather
+ * than minting a second entry with a newer timestamp, which would keep resetting
+ * the age cap and make it unreachable.
+ */
+export declare function markHeld(state: FileState, span: {
+    from: number;
+    to: number;
+}, nowMs: number, caps: BacklogCaps): FileState;
+/**
+ * Shed the oldest spans until every cap holds.
+ *
+ * Never blocks, never grows. Each shed span advances the offset past itself and
+ * stamps a gap, so what the server sees is a discontinuity in `byteOffset` — an
+ * honest hole — and not a silent renumbering.
+ */
+export declare function enforceCaps(state: FileState, nowMs: number, caps: BacklogCaps): FileState;