@vibe-commit/capture 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 VibeCommit
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,66 @@
+# @vibe-commit/capture
+
+The VibeCommit capture client. Records Claude Code sessions against the commits they produced.
+
+```
+npm install -g @vibe-commit/capture
+vibecommit connect
+```
+
+MIT licensed. This is the client that runs on your machine.
+See [what we upload](https://vibecommit.ai/docs/what-we-upload).
+
+<!--
+The sentence that used to sit here claimed this client was open source so you could read
+exactly what leaves it. That is FALSE as of D64 (2026-08-09): the repo is private, with the
+MIT licence intact. The claim is BLOCKED by `docs/claims-register.md`, and this README ships
+inside the npm tarball, so it would have carried the claim to the registry on first publish.
+It is DELETED here rather than replaced — `CR-111` owns the replacement trust argument, and
+the approved direction points at `Vibe-Commit/claude-plugin`, which vendors the exact binary.
+"Inspect the build" is WEAKER than "read the source" and must not be dressed up as it.
+-->
+
+
+## Commands
+
+| Command | What it does |
+|---|---|
+| `vibecommit connect` | Connect this repo and capture the current session. |
+| `vibecommit status` | Show whether capture is on for this repo and when it last succeeded. |
+| `vibecommit off` | Stop capturing for this repo. |
+| `vibecommit why <file>:<line>` | Show the conversation turns recorded against the commit that last changed this line. |
+| `vibecommit report --since <when>` | Summarise capture coverage over a time window. |
+
+## Status
+
+**Implemented**, not a scaffold. All five commands above have real bodies — OAuth sign-in
+and credential storage, git inspection, redaction, and the Claude Code hook contract — backed
+by an extensive test suite. Beyond the five interactive commands, this binary also answers a
+hidden `hook` invocation (dispatched outside `--help`, since no one types it) for Claude Code's
+`Stop`, `PreCompact`, and `SessionEnd` events; that hook mode is what
+[`Vibe-Commit/claude-plugin`](https://github.com/Vibe-Commit/claude-plugin) vendors and wires up
+by default when you install the Claude Code plugin instead of this package directly.
+
+What is established, and what future changes must not undo:
+
+- **All user-facing copy lives in `src/copy/`.** No command body contains an inline user-facing
+  string literal. A claims gate can only check copy it can find.
+- **One commit-header renderer**, in `src/copy/grades.ts`, which takes the edge grade. Evidence
+  qualifiers are adjacent to the claim by construction rather than by review.
+- **The exit-code contract is split** (`src/exit.ts`): hook invocations always exit 0 and stay
+  silent; interactive verbs get normal CLI semantics.
+
+## Development
+
+```
+npm install
+npm test          # node --test --import tsx
+npm run typecheck
+npm run build
+```
+
+Node >= 22.15.0.
+
+## License
+
+MIT — see [LICENSE](./LICENSE).

package/dist/agents/claude_code.d.ts

@@ -0,0 +1,11 @@
+/**
+ * The `claude-code` dialect — `CR-183`.
+ *
+ * ⛔ **NOTHING ABOUT CLAUDE CODE'S BEHAVIOUR CHANGES HERE.** Every value below is
+ * the value the client already used, moved to where a second agent can be
+ * described beside it. The one function member, `locateCurrentTranscript`, is
+ * `commands/connect.ts`'s own `findCurrentTranscript` verbatim except for the
+ * confinement call, which now runs against the registry's union.
+ */
+import type { TranscriptDialect } from "./types.js";
+export declare const CLAUDE_CODE: TranscriptDialect;

package/dist/agents/claude_code.js

@@ -0,0 +1,162 @@
+/**
+ * The `claude-code` dialect — `CR-183`.
+ *
+ * ⛔ **NOTHING ABOUT CLAUDE CODE'S BEHAVIOUR CHANGES HERE.** Every value below is
+ * the value the client already used, moved to where a second agent can be
+ * described beside it. The one function member, `locateCurrentTranscript`, is
+ * `commands/connect.ts`'s own `findCurrentTranscript` verbatim except for the
+ * confinement call, which now runs against the registry's union.
+ */
+import { readdirSync, statSync } from "node:fs";
+import { basename, join } from "node:path";
+import { isInside, isTranscriptFile, transcriptRoot } from "../paths.js";
+/**
+ * The client-side backstop, per event.
+ *
+ * ⛔ **This is `hooks/entry.ts`'s `DEFAULT_HOOK_BUDGET_MS`, and the constant does
+ * not move.** It is restated as a literal here for one reason: `entry.ts`
+ * imports this registry, so importing the constant back would close an import
+ * cycle whose failure mode is a temporal-dead-zone `undefined` at module load —
+ * a budget of `NaN`, silently. `test/agent-registry.test.ts` asserts the two
+ * agree, which is the coupling the import would have provided.
+ */
+const CLAUDE_CLIENT_BUDGET_MS = 5_000;
+/**
+ * What `claude-plugin/hooks/hooks.json` registers, in MILLISECONDS.
+ *
+ * ⚠ **That file is hand-written in another repository and nothing generates it
+ * from here**, so these three numbers are a MIRROR, not a source. They are
+ * pinned as literals so the `clientBudgetMs < registeredTimeoutMs` relation can
+ * be asserted at all — see `test/agent-registry.test.ts`, which also states what
+ * the assertion cannot see: a drift in the file itself.
+ *
+ * Its own timeouts are in SECONDS (8, 8, 10). Every value is above the client
+ * budget above, which is the relation that lets the client's watchdog fire
+ * first; below that line the agent kills the process and the exit-0 contract
+ * goes with it.
+ */
+const CLAUDE_REGISTERED_STOP_MS = 8_000;
+const CLAUDE_REGISTERED_PRECOMPACT_MS = 8_000;
+const CLAUDE_REGISTERED_SESSION_END_MS = 10_000;
+/**
+ * The transcript for the session running right now.
+ *
+ * A hook is HANDED `transcript_path` on stdin. `connect` is typed by a human and
+ * gets nothing, so it has to find one: Claude Code stores transcripts at
+ * `<transcriptRoot>/<encoded-project-path>/<session-id>.jsonl`, where the
+ * encoding replaces `/` and `.` with `-`. That was derived by comparing every
+ * directory on this machine against the `cwd` its transcripts record — 15 of 17
+ * matched exactly, and both misses were sessions whose `cwd` MOVED mid-session,
+ * not a different encoding.
+ *
+ * Which is also why this looks up the directory for THIS project rather than
+ * taking the newest transcript anywhere: a session that started in another
+ * project and `cd`'d here lives under that project's directory, and uploading it
+ * would attach one project's session to another's repo — the same confusion
+ * `CR-017d`'s key exists to prevent.
+ *
+ * **Confined.** The result is gated, because this is a reader of transcript
+ * bytes and `/cso` finding 1 is about exactly this class of read. A candidate
+ * that resolves outside the root is not returned.
+ *
+ * ⛔ **Against THIS DIALECT'S OWN ROOT, and not against the registry union —
+ * which is a deliberate difference from the two hook call sites.** The union
+ * exists for a path that ARRIVES from outside, where which agent produced it is
+ * not known. This function BUILDS its candidates by joining its own root, so
+ * every other root in the registry is unreachable here by construction and
+ * admitting them would be a widening that buys nothing. (It is also what keeps
+ * this module out of an import cycle with the registry, whose failure mode is a
+ * temporal-dead-zone `undefined` at module load rather than an error.)
+ */
+function locateCurrentTranscript(home, env, projectKey) {
+    const root = transcriptRoot(home, env);
+    const dir = join(root, projectKey.replace(/[/.]/g, "-"));
+    let entries;
+    try {
+        entries = readdirSync(dir);
+    }
+    catch {
+        return null;
+    }
+    let best = null;
+    for (const entry of entries) {
+        if (!entry.endsWith(".jsonl"))
+            continue;
+        const path = join(dir, entry);
+        if (!isInside(root, path))
+            continue;
+        let stat;
+        try {
+            stat = statSync(path);
+        }
+        catch {
+            continue;
+        }
+        if (!stat.isFile() || stat.size === 0)
+            continue;
+        if (best === null || stat.mtimeMs > best.mtime) {
+            best = {
+                path,
+                sessionId: basename(entry, ".jsonl"),
+                size: stat.size,
+                mtime: stat.mtimeMs,
+            };
+        }
+    }
+    return best === null ? null : { path: best.path, sessionId: best.sessionId, size: best.size };
+}
+/**
+ * ⛔ **MEASURED (`M1`), 2026-08-21, BOTH ARMS.**
+ *
+ * Claude Code exports `CLAUDE_CODE_SESSION_ID` into the Bash tool's environment
+ * and git passes it through to `post-commit`:
+ *
+ *   - agent commit → the uuid, **byte-identical to the transcript filename**;
+ *   - human commit, the variable stripped → `<UNSET>`, so `null` here;
+ *   - commit from a linked worktree → **the same uuid**.
+ *
+ * That third row is why this is worth a member: the value survives the worktree
+ * boundary that the mtime heuristic in `spool.ts` cannot see across.
+ *
+ * ⚠ **`null` on empty or whitespace, not `""`.** An exported-but-empty variable
+ * is the shell's idea of unset, and a `""` session id would key a spool bucket
+ * every unset process shares.
+ */
+function claudeSessionIdFromEnv(env) {
+    const raw = env.CLAUDE_CODE_SESSION_ID;
+    if (raw === undefined)
+        return null;
+    const value = raw.trim();
+    return value === "" ? null : value;
+}
+export const CLAUDE_CODE = {
+    id: "claude-code",
+    transport: "ndjson",
+    transcriptRoot,
+    // ⛔ `CR-193`, D177 §2 — the lane's `.jsonl` gate, and NOTHING MORE under this
+    // root. `<projects>/<encoded-project-path>/` holds `<session-id>.jsonl` and a
+    // `subagents/` directory, so every file here is already a transcript; there is
+    // no interior shape to require, unlike Cursor's.
+    admitsFile: isTranscriptFile,
+    events: {
+        Stop: {
+            registeredTimeoutMs: CLAUDE_REGISTERED_STOP_MS,
+            clientBudgetMs: CLAUDE_CLIENT_BUDGET_MS,
+        },
+        PreCompact: {
+            registeredTimeoutMs: CLAUDE_REGISTERED_PRECOMPACT_MS,
+            clientBudgetMs: CLAUDE_CLIENT_BUDGET_MS,
+        },
+        SessionEnd: {
+            registeredTimeoutMs: CLAUDE_REGISTERED_SESSION_END_MS,
+            clientBudgetMs: CLAUDE_CLIENT_BUDGET_MS,
+        },
+    },
+    // `<session>/subagents/agent-*.jsonl`, globbed — the paths are never handed
+    // over. `CR-124`, D76.
+    delegatedTranscripts: "discover",
+    redaction: "claude-code",
+    sessionIdFromEnv: claudeSessionIdFromEnv,
+    locateCurrentTranscript,
+};
+//# sourceMappingURL=claude_code.js.map

package/dist/agents/claude_code.js.map

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

package/dist/agents/codex_cli.d.ts

@@ -0,0 +1,15 @@
+/**
+ * The `codex-cli` dialect — `CR-183`, D164.
+ *
+ * ⚠ **DATA, described here; the readers land in later tasks of this wave.** What
+ * this entry does today is put Codex's transcript root into the confinement
+ * union and give `connect` a truthful answer about having no locator. The
+ * scrubber it names is `CR-185`'s, and the delegated-transcript mechanism it
+ * declares has no reader at all yet (see `DelegatedTranscripts`).
+ *
+ * ⛔ **Every number and mechanism below is CARRIED FROM THE TASK BRIEF, not
+ * measured by this task.** They are recorded as the brief stated them so a later
+ * reader can check them against the product rather than against this file.
+ */
+import type { TranscriptDialect } from "./types.js";
+export declare const CODEX_CLI: TranscriptDialect;

package/dist/agents/codex_cli.js

@@ -0,0 +1,67 @@
+/**
+ * The `codex-cli` dialect — `CR-183`, D164.
+ *
+ * ⚠ **DATA, described here; the readers land in later tasks of this wave.** What
+ * this entry does today is put Codex's transcript root into the confinement
+ * union and give `connect` a truthful answer about having no locator. The
+ * scrubber it names is `CR-185`'s, and the delegated-transcript mechanism it
+ * declares has no reader at all yet (see `DelegatedTranscripts`).
+ *
+ * ⛔ **Every number and mechanism below is CARRIED FROM THE TASK BRIEF, not
+ * measured by this task.** They are recorded as the brief stated them so a later
+ * reader can check them against the product rather than against this file.
+ */
+import { codexTranscriptRoot, isTranscriptFile } from "../paths.js";
+/**
+ * `SessionEnd` is the tight one — 3 s registered, 2.2 s client.
+ *
+ * That cap is why `CR-182`'s gap-stamp reserve exists at all: at 2200 ms a slow
+ * send routinely consumed the whole budget and the honest hole went unrecorded,
+ * which is the one outcome D56 §D8 says this client may not produce.
+ */
+const CODEX_SESSION_END_REGISTERED_MS = 3_000;
+const CODEX_SESSION_END_CLIENT_MS = 2_200;
+/** `Stop` and `PreCompact` are registered far wider — 30 s, client 8 s. */
+const CODEX_TURN_REGISTERED_MS = 30_000;
+const CODEX_TURN_CLIENT_MS = 8_000;
+export const CODEX_CLI = {
+    id: "codex-cli",
+    transport: "ndjson",
+    transcriptRoot: codexTranscriptRoot,
+    // ⛔ `CR-193`, D177 §2 — the lane's `.jsonl` gate. `~/.codex/sessions` is
+    // date-nested rollout transcripts and nothing else, so there is no interior
+    // shape to require here either. ⚠ CARRIED FROM THE BRIEF like the numbers
+    // above: this task did not re-walk a Codex tree to confirm it.
+    admitsFile: isTranscriptFile,
+    events: {
+        Stop: {
+            registeredTimeoutMs: CODEX_TURN_REGISTERED_MS,
+            clientBudgetMs: CODEX_TURN_CLIENT_MS,
+        },
+        PreCompact: {
+            registeredTimeoutMs: CODEX_TURN_REGISTERED_MS,
+            clientBudgetMs: CODEX_TURN_CLIENT_MS,
+        },
+        SessionEnd: {
+            registeredTimeoutMs: CODEX_SESSION_END_REGISTERED_MS,
+            clientBudgetMs: CODEX_SESSION_END_CLIENT_MS,
+        },
+    },
+    // The delegated path ARRIVES on stdin as `agent_transcript_path` — there is no
+    // directory to glob. Nothing parses it yet; the discriminator is here so the
+    // Claude glob cannot run against a layout that has no `subagents/`.
+    delegatedTranscripts: "announce",
+    redaction: "codex-cli",
+    // ⛔ **UNMEASURED.** `null` here does NOT mean "Codex CLI has no session id in
+    // its environment" — it means nobody has run the measurement `M1` ran for
+    // Claude Code (agent commit, human commit, worktree commit) against Codex, so
+    // this client has no variable it can honestly name. ⚠ Read it as the absence
+    // of a measurement, not as a fact about the agent. Measuring it is a change to
+    // this line and nothing else.
+    sessionIdFromEnv: () => null,
+    // ⛔ NO `locateCurrentTranscript`, and the omission is the decision. Finding
+    // the repository would mean reading a `cwd` out of the transcript's own
+    // records — ANALYSIS, which D60 §D6 forbids this client. `connect` therefore
+    // skips the test-capture beat rather than guessing.
+};
+//# sourceMappingURL=codex_cli.js.map

package/dist/agents/codex_cli.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"codex_cli.js","sourceRoot":"","sources":["../../src/agents/codex_cli.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG;AAEH,OAAO,EAAE,mBAAmB,EAAE,gBAAgB,EAAE,MAAM,aAAa,CAAC;AAGpE;;;;;;GAMG;AACH,MAAM,+BAA+B,GAAG,KAAK,CAAC;AAC9C,MAAM,2BAA2B,GAAG,KAAK,CAAC;AAE1C,2EAA2E;AAC3E,MAAM,wBAAwB,GAAG,MAAM,CAAC;AACxC,MAAM,oBAAoB,GAAG,KAAK,CAAC;AAEnC,MAAM,CAAC,MAAM,SAAS,GAAsB;IAC1C,EAAE,EAAE,WAAW;IACf,SAAS,EAAE,QAAQ;IACnB,cAAc,EAAE,mBAAmB;IACnC,yEAAyE;IACzE,4EAA4E;IAC5E,0EAA0E;IAC1E,+DAA+D;IAC/D,UAAU,EAAE,gBAAgB;IAC5B,MAAM,EAAE;QACN,IAAI,EAAE;YACJ,mBAAmB,EAAE,wBAAwB;YAC7C,cAAc,EAAE,oBAAoB;SACrC;QACD,UAAU,EAAE;YACV,mBAAmB,EAAE,wBAAwB;YAC7C,cAAc,EAAE,oBAAoB;SACrC;QACD,UAAU,EAAE;YACV,mBAAmB,EAAE,+BAA+B;YACpD,cAAc,EAAE,2BAA2B;SAC5C;KACF;IACD,+EAA+E;IAC/E,6EAA6E;IAC7E,oEAAoE;IACpE,oBAAoB,EAAE,UAAU;IAChC,SAAS,EAAE,WAAW;IACtB,8EAA8E;IAC9E,0EAA0E;IAC1E,8EAA8E;IAC9E,6EAA6E;IAC7E,+EAA+E;IAC/E,8BAA8B;IAC9B,gBAAgB,EAAE,GAAG,EAAE,CAAC,IAAI;IAC5B,4EAA4E;IAC5E,wEAAwE;IACxE,6EAA6E;IAC7E,oDAAoD;CACrD,CAAC"}

package/dist/agents/cursor.d.ts

@@ -0,0 +1,21 @@
+/**
+ * The `cursor` dialect — `CR-193`, D177.
+ *
+ * ⛔ **THE ID IS `cursor`. NEVER `cursor-ide`, never `cursor-mcp`** (D177 §1).
+ * The server's client-name alias map already folds both of those spellings onto
+ * `cursor`, and a cell over there asserts that every producible id is one of
+ * that map's TARGETS — so a different spelling here reds a test in another
+ * repository, on day one, for a reason nothing on this side would report.
+ * ⚠ Cited from D177 §1 rather than read: this task has no access to that tree.
+ *
+ * ⛔ **`transport: "ndjson"` DOES NOT CHANGE, and the lock-out doing its job is
+ * it NOT FIRING** (D177 §1). D164 §2 installed that literal type precisely so
+ * *"an Aider or **Cursor** dialect cannot be registered without editing the
+ * interface"* — and Cursor turns out to meet D164 §1's membership rule exactly:
+ * it appends NDJSON to a file and hands a hook its path.
+ *
+ * ⚠ **What is DATA here and what is MEASURED is not the same set**, and the
+ * difference is marked on each member below rather than left to a reader.
+ */
+import type { TranscriptDialect } from "./types.js";
+export declare const CURSOR: TranscriptDialect;

package/dist/agents/cursor.js

@@ -0,0 +1,89 @@
+/**
+ * The `cursor` dialect — `CR-193`, D177.
+ *
+ * ⛔ **THE ID IS `cursor`. NEVER `cursor-ide`, never `cursor-mcp`** (D177 §1).
+ * The server's client-name alias map already folds both of those spellings onto
+ * `cursor`, and a cell over there asserts that every producible id is one of
+ * that map's TARGETS — so a different spelling here reds a test in another
+ * repository, on day one, for a reason nothing on this side would report.
+ * ⚠ Cited from D177 §1 rather than read: this task has no access to that tree.
+ *
+ * ⛔ **`transport: "ndjson"` DOES NOT CHANGE, and the lock-out doing its job is
+ * it NOT FIRING** (D177 §1). D164 §2 installed that literal type precisely so
+ * *"an Aider or **Cursor** dialect cannot be registered without editing the
+ * interface"* — and Cursor turns out to meet D164 §1's membership rule exactly:
+ * it appends NDJSON to a file and hands a hook its path.
+ *
+ * ⚠ **What is DATA here and what is MEASURED is not the same set**, and the
+ * difference is marked on each member below rather than left to a reader.
+ */
+import { cursorTranscriptRoot, isCursorTranscript } from "../paths.js";
+/**
+ * ⛔ **UNMEASURED, AND ADOPTED AS A FLOOR RATHER THAN GUESSED.**
+ *
+ * The plan's `D5` — the exact `hook_event_name` strings Cursor sends, and the
+ * timeouts its `~/.cursor/hooks.json` registers — is **founder-blocked and
+ * gates `CR-195`**, the unit that writes that file. Nothing installs a Cursor
+ * hook today, so no Cursor hook has ever fired and these numbers are currently
+ * unreachable in production.
+ *
+ * ⚠ **The direction of safety is what picks them.** Too WIDE and the agent
+ * kills the process before this client's watchdog fires — which loses the
+ * exit-0/silent-stdout contract, the one outcome DESIGN.md §13.7 forbids. Too
+ * TIGHT and an invocation sends less and the next one picks it up. So the
+ * registry's tightest existing pair is taken as a FLOOR: it holds whatever
+ * Cursor turns out to register, down to Codex's 3 s cap.
+ *
+ * ⛔ **This is a refusal to guess, not a measurement of Cursor**, and `CR-195`
+ * owns the real numbers once `D5` comes back.
+ */
+const CURSOR_REGISTERED_MS = 3_000;
+const CURSOR_CLIENT_MS = 2_200;
+export const CURSOR = {
+    id: "cursor",
+    transport: "ndjson",
+    // ⛔ `projects`, one level ABOVE the root D177 §2 names, because `<munged>` is
+    // the workspace fsPath and is derivable from neither `home` nor `env`. The
+    // measurement that rules out deriving it from the project key, and what that
+    // costs, are in `cursorTranscriptRoot`'s own docblock.
+    transcriptRoot: cursorTranscriptRoot,
+    // ⛔ THE GATE D177 §2 REQUIRES TO SHIP IN THIS UNIT — `.jsonl`, plus the
+    // `<workspace>/agent-transcripts/` shape that puts §2's boundary back.
+    admitsFile: isCursorTranscript,
+    events: {
+        Stop: {
+            registeredTimeoutMs: CURSOR_REGISTERED_MS,
+            clientBudgetMs: CURSOR_CLIENT_MS,
+        },
+        PreCompact: {
+            registeredTimeoutMs: CURSOR_REGISTERED_MS,
+            clientBudgetMs: CURSOR_CLIENT_MS,
+        },
+        SessionEnd: {
+            registeredTimeoutMs: CURSOR_REGISTERED_MS,
+            clientBudgetMs: CURSOR_CLIENT_MS,
+        },
+    },
+    // ⛔ DECLARED EXPLICITLY, and it is load-bearing now in a way it was not
+    // before (D177 §2, §9). `subagentsDir()` would compute
+    // `<root>/<cid>/<cid>/subagents` for a Cursor transcript — ONE LEVEL TOO DEEP,
+    // since the real layout is `<root>/<parentId>/subagents/<childId>.jsonl` — and
+    // that wrong directory is inert only because `announce` short-circuits before
+    // it. ⚠ `CR-204` made the selection ROOT-derived rather than flag-derived, so
+    // a wrong declaration here is no longer a line nobody reaches.
+    delegatedTranscripts: "announce",
+    redaction: "cursor",
+    // ⛔ **UNMEASURED.** `null` here does NOT mean "Cursor has no session id in its
+    // environment" — it means nobody has run the measurement `M1` ran for Claude
+    // Code (agent commit, human commit, worktree commit) against Cursor, so this
+    // client has no variable it can honestly name. ⚠ Read it as the absence of a
+    // measurement, not as a fact about the agent. Measuring it is a change to this
+    // line and nothing else.
+    sessionIdFromEnv: () => null,
+    // ⛔ NO `locateCurrentTranscript`, and the omission is the decision — the same
+    // one Codex made. Finding the conversation for THIS project would mean munging
+    // a workspace path this client is never told, or reading a `cwd` out of the
+    // transcript's own records, which is ANALYSIS (D60 §D6). `connect` skips the
+    // test-capture beat rather than guessing.
+};
+//# sourceMappingURL=cursor.js.map

package/dist/agents/cursor.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"cursor.js","sourceRoot":"","sources":["../../src/agents/cursor.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;GAkBG;AAEH,OAAO,EAAE,oBAAoB,EAAE,kBAAkB,EAAE,MAAM,aAAa,CAAC;AAGvE;;;;;;;;;;;;;;;;;;GAkBG;AACH,MAAM,oBAAoB,GAAG,KAAK,CAAC;AACnC,MAAM,gBAAgB,GAAG,KAAK,CAAC;AAE/B,MAAM,CAAC,MAAM,MAAM,GAAsB;IACvC,EAAE,EAAE,QAAQ;IACZ,SAAS,EAAE,QAAQ;IACnB,8EAA8E;IAC9E,2EAA2E;IAC3E,6EAA6E;IAC7E,uDAAuD;IACvD,cAAc,EAAE,oBAAoB;IACpC,wEAAwE;IACxE,uEAAuE;IACvE,UAAU,EAAE,kBAAkB;IAC9B,MAAM,EAAE;QACN,IAAI,EAAE;YACJ,mBAAmB,EAAE,oBAAoB;YACzC,cAAc,EAAE,gBAAgB;SACjC;QACD,UAAU,EAAE;YACV,mBAAmB,EAAE,oBAAoB;YACzC,cAAc,EAAE,gBAAgB;SACjC;QACD,UAAU,EAAE;YACV,mBAAmB,EAAE,oBAAoB;YACzC,cAAc,EAAE,gBAAgB;SACjC;KACF;IACD,wEAAwE;IACxE,uDAAuD;IACvD,+EAA+E;IAC/E,+EAA+E;IAC/E,8EAA8E;IAC9E,8EAA8E;IAC9E,+DAA+D;IAC/D,oBAAoB,EAAE,UAAU;IAChC,SAAS,EAAE,QAAQ;IACnB,+EAA+E;IAC/E,6EAA6E;IAC7E,6EAA6E;IAC7E,6EAA6E;IAC7E,+EAA+E;IAC/E,yBAAyB;IACzB,gBAAgB,EAAE,GAAG,EAAE,CAAC,IAAI;IAC5B,8EAA8E;IAC9E,+EAA+E;IAC/E,4EAA4E;IAC5E,6EAA6E;IAC7E,0CAA0C;CAC3C,CAAC"}

package/dist/agents/registry.d.ts

@@ -0,0 +1,184 @@
+/**
+ * The registry — `CR-183`, D164.
+ *
+ * The one place that knows which dialects exist. Two things are derived from it
+ * and from nothing else: which adapter a `--agent=` value selects, and the set
+ * of roots the confinement check runs over.
+ *
+ * ## ⛔ Why `--agent=` is the selector, and why two alternatives are SECURITY
+ * rejections rather than taste
+ *
+ *   - **an environment variable** — rejected because Codex exports
+ *     `CLAUDE_PLUGIN_ROOT` itself, so the obvious variable is set by the wrong
+ *     agent and says the wrong thing.
+ *   - **`hook_event_name`** — rejected because both members of this lane fire
+ *     the same three events. It discriminates nothing.
+ *   - ⛔ **the `transcript_path` prefix, as the PRIMARY selector** — rejected
+ *     because that is *the attacker-influenced input `isInside` exists to
+ *     constrain.* A path that CLAIMS to sit under a root may not be what
+ *     decides which root we will read from.
+ *
+ * ⚠ **`CR-185` picking the SCRUBBER by the containing root is not a
+ * contradiction — read D164 §5 before you think it is.** Choosing a STRICTER
+ * scrubber because a path sits outside every known root is fail-closed;
+ * choosing a WIDER root because a path claims to be there is not. The
+ * confinement boundary is computed from this registry either way, so a wrong
+ * SELECTION can pick a suboptimal redaction profile and can never widen the
+ * boundary.
+ */
+import { type AgentId, type SelectedAgentId, type TranscriptDialect } from "./types.js";
+/**
+ * Every dialect, in registration order.
+ *
+ * ⛔ **The ids are D164 §1's, spelled exactly.** `test/agent-registry.test.ts`
+ * pins them against the literal list, because the four-way cross-repo spelling
+ * fails silently in the direction that matters: emit `codex_cli` and the server
+ * does not recognise it, the default extractor runs, and the row lands `unknown`
+ * permanently with no error anywhere.
+ */
+export declare const DIALECTS: readonly TranscriptDialect[];
+/**
+ * What an invocation with no `--agent=` is.
+ *
+ * Claude Code, because that is what every install shipped before this flag
+ * existed — the `.claude-plugin` bundle's command carries no `--agent=` and
+ * must keep working unchanged.
+ */
+export declare const DEFAULT_AGENT_ID: AgentId;
+/**
+ * Read the adapter id off argv.
+ *
+ * ⛔ **CALLED FROM `index.ts`, beside `invocationMode`, and NOWHERE ELSE.** The
+ * hook path never sees argv: `runHook` takes a `HookEnvironment`, and the id
+ * reaches it as a field on that object — the same seam that already injects
+ * `home` and `nodeVersion` so the whole path can be driven by a test. ⛔ And
+ * `parseHookInput` must NOT select the adapter: stdin is the input the
+ * confinement boundary exists to constrain, and a selector read from there is
+ * the rejection above with an extra step.
+ *
+ * ⚠ **Resolving an id is NOT entering hook mode**, and the difference is the
+ * trap this wave is most likely to ship. `invocationMode` returns `"hook"` only
+ * when `argv[0] === "hook"` (or a legacy env var is set), and Codex sets
+ * neither — so a registered command whose FIRST argument is this flag runs the
+ * binary INTERACTIVELY, inside a hook. ⛔ **The registered command must lead
+ * with the `hook` verb.** `test/agent-registry.test.ts` holds both arms.
+ *
+ * Returns the LITERAL it was given. It is deliberately not narrowed to
+ * `AgentId`: an id we do not recognise still has to travel, and the honest thing
+ * to carry is what the operator wrote.
+ */
+export declare function resolveAgentId(argv: readonly string[]): string;
+/**
+ * The dialect an id selects.
+ *
+ * ⛔ **AN UNKNOWN ID FALLS BACK; IT NEVER STOPS CAPTURE (plan §D7, founder
+ * ruling).** The client still reads, still redacts and still sends. Refusing was
+ * considered and rejected: a misconfigured hook that captures NOTHING is a worse
+ * outcome than one that captures conservatively, and the server has an honest
+ * label (`unknown`, D164 §1) for a producer it does not recognise — so nothing
+ * downstream has to guess.
+ *
+ * ⚠ **The fallback is a BEHAVIOUR choice only.** The literal the operator gave
+ * is not rewritten by this function; callers that put the agent on the wire read
+ * the id, not the dialect.
+ */
+export declare function dialectFor(agentId: string | undefined): TranscriptDialect;
+/**
+ * Every transcript root, deduped — ⛔ **the confinement boundary, computed from
+ * the REGISTRY and never from input.**
+ *
+ * A union rather than "the selected dialect's root" on purpose. The selection
+ * comes from a flag an install may have got wrong; the boundary must not. With
+ * the union, a wrong selection costs a suboptimal redaction profile (D164 §5)
+ * and cannot make a file readable that was not readable before.
+ *
+ * Deduped because two dialects can be pointed at one directory by environment —
+ * `CODEX_HOME` and `CLAUDE_CONFIG_DIR` are both operator-set — and a duplicated
+ * root would make `isInsideAny` do the same `realpath` pair twice for no reason.
+ */
+export declare function transcriptRoots(home: string, env: NodeJS.ProcessEnv): readonly string[];
+/**
+ * ⛔ **MAY THIS PATH BE READ AS A TRANSCRIPT? — confinement, THEN the file
+ * gate (`CR-193`, D177 §2).**
+ *
+ * Two different questions, asked in an order that cannot be swapped:
+ *
+ *   1. `isInsideAny(transcriptRoots(...))` — *may this path be read at all.*
+ *      Registry-computed, never derived from input, byte-unchanged from
+ *      `CR-183`. `/cso` finding 1.
+ *   2. the containing dialect's `admitsFile` — *is this file a transcript.* A
+ *      root can be exactly right and still hold files that are not transcripts;
+ *      there are 112 of them under Cursor's.
+ *
+ * ⛔ **STEP 2 CAN ONLY REFUSE.** It runs over a path step 1 already admitted, so
+ * every outcome is a narrowing — D177 §7's direction test, which is what makes
+ * this the accepted shape rather than the rejected `transcript_path`-as-boundary
+ * one. The boundary is still the registry's.
+ *
+ * ⚠ **The `unknown` arm keeps step 1's answer, deliberately.** A path inside two
+ * roots is admitted by the boundary and is `unknown` to `agentForTranscript`;
+ * `dialectFor` then falls back to Claude, whose gate is the plain `.jsonl` test.
+ * Refusing on `unknown` here would be a THIRD boundary rule, and it would refuse
+ * captures D177 §7 decided to keep (the header is omitted, the bytes still go).
+ *
+ * ⚠ Two root resolutions rather than one — `isInsideAny` resolves, then
+ * `agentForTranscript` resolves again. Measured against the alternative, which
+ * is folding the two into one pass by editing `agentForTranscript`: that
+ * function is the wire's producer oracle and `test/wire-agent.test.ts` gates it,
+ * so a handful of `realpath` calls inside a multi-second budget is the cheaper
+ * side of that trade.
+ */
+export declare function admitsTranscript(home: string, env: NodeJS.ProcessEnv, transcriptPath: string): boolean;
+/**
+ * ⛔ **WHICH AGENT PRODUCED THIS TRANSCRIPT — the containing registry root's,
+ * NEVER the `--agent=` flag's (`CR-204`, D177 §7).**
+ *
+ * ## Why the flag cannot be the answer
+ *
+ * `DEFAULT_AGENT_ID` is `claude-code` and **no install passes the flag** — the
+ * `.claude-plugin` bundle's command is `node "…/bin/index.js" hook`, no flag, as
+ * the docblock above records. So a flag-derived wire value is `claude-code` for
+ * every path that did not remember to set it: a FALSE PROVENANCE CLAIM,
+ * permanent, in the artifact whose entire worth is faithfulness. The wire is not
+ * a place to be wrong in a plausible direction
+ * (`project_plausible_answer_hazard_class`).
+ *
+ * ## ⛔ This is `CR-185`'s shape, not `CR-183`'s rejected one
+ *
+ * `rulesForTranscript` in `redact.ts` is the same three lines with `RULES` in
+ * place of `id`, and its own docblock carries the distinction verbatim:
+ *
+ *   - choosing a **stricter scrubber** — or a LESS specific producer — because a
+ *     path sits outside every known root is **fail-closed**;
+ *   - choosing a **wider root** because a path *claims* to be there is not.
+ *
+ * ⛔ **The confinement boundary is untouched and still runs FIRST.** This is a
+ * LOOKUP AGAINST an already-computed boundary: `transcriptRoots` decides what
+ * may be read, `isInsideAny` refuses everything else, and only then does this
+ * ask which of the roots that already admitted the file names its producer. It
+ * can never widen anything, and its arity is 3 — ⛔ **the flag is not a
+ * parameter of it at all.**
+ *
+ * ## Zero or two → `unknown`, ⛔ which the wire step turns into an OMISSION
+ *
+ * Exactly one match names the agent. Two dialects can be pointed at one
+ * directory by environment (`CLAUDE_CONFIG_DIR` and `CODEX_HOME` are both
+ * operator-set and both sides resolve through `realpath`), and a path inside two
+ * roots is a path whose producer is not known. `unknown` is D164 §3's honest
+ * label for exactly that.
+ *
+ * ⛔ **It is not, however, what goes on the wire.** `buildIngestHeaders` OMITS
+ * `x-agent` for this answer, because the server treats an absent header and a
+ * present `unknown` as different facts: absent is *"nothing to say"* and leaves
+ * a stream's pinned agent alone, while a present `unknown` resolves and
+ * DISAGREES with any non-`unknown` pin — which drops the buffered tail and sheds
+ * the in-flight turn. Selecting `unknown` here is therefore a decision to say
+ * nothing, not a value to assert. `post.ts` carries the full argument.
+ *
+ * ⚠ **The zero-match arm has NO CLIENT CALLER on the hook path**, said plainly
+ * rather than left to be assumed (`feedback_unexercisable_branch_not_verified`):
+ * `isInsideAny(transcriptRoots(...))` refuses everything outside the union
+ * before a delta is ever built. It is a second independent line, and
+ * `test/agent-registry.test.ts` exercises it by calling this function directly.
+ */
+export declare function agentForTranscript(home: string, env: NodeJS.ProcessEnv, transcriptPath: string): SelectedAgentId;