@vibe-commit/capture 0.1.0 → 0.2.1

package/dist/agents/cursor.js

@@ -17,15 +17,19 @@
  * ⚠ **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";
+import { cursorHooksPath, 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.
+ * ⚠ **`D5` HAD TWO HALVES AND ONLY ONE OF THEM IS ANSWERED (D205).** It asked
+ * for the exact `hook_event_name` strings Cursor sends *and* the timeouts its
+ * `~/.cursor/hooks.json` registers. The STRINGS are now measured — see
+ * `eventNames` below, read out of the shipped app bundle, which is what
+ * discharged `CR-195`'s block. ⛔ **The TIMEOUTS below are still not measured**,
+ * and are deliberately left as the floor they always were rather than quietly
+ * promoted on the strength of the other half. Nothing installs a Cursor hook
+ * today, so no Cursor hook has ever fired and these numbers remain 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
@@ -50,6 +54,28 @@ export const CURSOR = {
     // ⛔ 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,
+    // ⛔ **THE MEASUREMENT THAT DISCHARGED `D5`'s FIRST HALF — camelCase, and this
+    // is the defect `CR-195` exists to fix** (D205). Read out of the SHIPPED app
+    // bundle at `/Applications/Cursor.app/Contents/Resources/app`, whose `*.js`
+    // carry the event object as literals: seventeen events, of which
+    // `stop`/`preCompact`/`sessionEnd` are ours and `subagentStart`/`subagentStop`
+    // are the pair `delegatedTranscripts: "announce"` would want next.
+    //
+    // ⚠ **No live Cursor session was needed**, which is what `D5` had assumed and
+    // what kept this unit blocked. The bundle is the same artifact a user runs.
+    //
+    // ⛔ Against the client's `SessionEnd`, `sessionEnd` matched NOTHING — not an
+    // error, a `false` — so a Cursor session took no settle on its final turn and
+    // lost it permanently. That is the whole of the bug.
+    eventNames: { Stop: "stop", PreCompact: "preCompact", SessionEnd: "sessionEnd" },
+    // ⛔ `~/.cursor/hooks.json`, and the `cursor` SHAPE — the two are a pair.
+    // Read out of the shipped bundle's validator: a top-level numeric `version`
+    // is REQUIRED, entries are a FLAT array of hook scripts each needing a
+    // `command`, and an unrecognised event key is a validation ERROR rather than
+    // something ignored. The `claude` shape written here would be rejected for
+    // having no `command` — silently, registering nothing.
+    // ⚠ No env override: none has been measured, per `cursorTranscriptRoot`.
+    hookConfig: { path: (home) => cursorHooksPath(home), shape: "cursor" },
     events: {
         Stop: {
             registeredTimeoutMs: CURSOR_REGISTERED_MS,

package/dist/agents/cursor.js.map

@@ -1 +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"}
+{"version":3,"file":"cursor.js","sourceRoot":"","sources":["../../src/agents/cursor.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;GAkBG;AAEH,OAAO,EAAE,eAAe,EAAE,oBAAoB,EAAE,kBAAkB,EAAE,MAAM,aAAa,CAAC;AAGxF;;;;;;;;;;;;;;;;;;;;;;GAsBG;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,8EAA8E;IAC9E,6EAA6E;IAC7E,4EAA4E;IAC5E,iEAAiE;IACjE,+EAA+E;IAC/E,mEAAmE;IACnE,EAAE;IACF,8EAA8E;IAC9E,4EAA4E;IAC5E,EAAE;IACF,6EAA6E;IAC7E,8EAA8E;IAC9E,qDAAqD;IACrD,UAAU,EAAE,EAAE,IAAI,EAAE,MAAM,EAAE,UAAU,EAAE,YAAY,EAAE,UAAU,EAAE,YAAY,EAAE;IAChF,yEAAyE;IACzE,4EAA4E;IAC5E,uEAAuE;IACvE,6EAA6E;IAC7E,2EAA2E;IAC3E,uDAAuD;IACvD,yEAAyE;IACzE,UAAU,EAAE,EAAE,IAAI,EAAE,CAAC,IAAI,EAAE,EAAE,CAAC,eAAe,CAAC,IAAI,CAAC,EAAE,KAAK,EAAE,QAAQ,EAAE;IACtE,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

@@ -26,7 +26,7 @@
  * SELECTION can pick a suboptimal redaction profile and can never widen the
  * boundary.
  */
-import { type AgentId, type SelectedAgentId, type TranscriptDialect } from "./types.js";
+import { type AgentId, type HookEventName, type SelectedAgentId, type TranscriptDialect } from "./types.js";
 /**
  * Every dialect, in registration order.
  *
@@ -83,6 +83,44 @@ export declare function resolveAgentId(argv: readonly string[]): string;
  * the id, not the dialect.
  */
 export declare function dialectFor(agentId: string | undefined): TranscriptDialect;
+/**
+ * ⛔ **WHICH OF THE THREE EVENTS IS THIS `hook_event_name`? — `CR-195`, D205.**
+ *
+ * Returns the canonical `HookEventName`, or `null` for a string that names none
+ * of them. `null` is a real answer and not a failure: Claude Code, Codex and
+ * Cursor between them fire far more events than the three this client registers,
+ * and a `SubagentStop` payload arriving here is ordinary rather than wrong.
+ *
+ * ## ⛔ The dialect's own table first, then a case-insensitive fallback
+ *
+ * The exact match is the answer whenever the agent spells events the way its
+ * dialect says it does. The fallback exists for the case that has already bitten
+ * this client once — ⚠ **a spelling nobody anticipated** — and the asymmetry is
+ * what justifies it:
+ *
+ *   - **failing to recognise `SessionEnd` costs the final turn, permanently.**
+ *     That event has no next invocation to pick up what was missed.
+ *   - **recognising one spuriously costs 150 ms of reserve and one settle.**
+ *
+ * Those are not the same size, so this resolves in the direction that captures.
+ * ⛔ It is D164 §D7's ruling applied to events rather than to agent ids — *"an
+ * unknown id falls back; it never stops capture … a misconfigured hook that
+ * captures NOTHING is a worse outcome than one that captures conservatively"* —
+ * and it is the same shape: a BEHAVIOUR fallback that rewrites nothing on the
+ * wire.
+ *
+ * ⚠ **The fallback can only ever ADD recognition, never redirect it.** It runs
+ * only after the exact match has already failed, so a dialect's own spelling
+ * always wins; and `HOOK_EVENTS` is unambiguous case-insensitively, so no
+ * canonical event can be resolved as a different canonical event.
+ * `test/dialect-events.test.ts` pins both directions, including the distinctness
+ * that makes the second claim true rather than merely currently true.
+ *
+ * ⚠ **NOT a widening of the confinement boundary and not adjacent to one.** The
+ * value read here decides how long to wait and whether to settle; it never
+ * reaches a path that decides what may be READ. That stays `transcriptRoots`.
+ */
+export declare function canonicalHookEvent(dialect: TranscriptDialect, wireName: string): HookEventName | null;
 /**
  * Every transcript root, deduped — ⛔ **the confinement boundary, computed from
  * the REGISTRY and never from input.**

package/dist/agents/registry.js

@@ -30,7 +30,7 @@ import { isInside, isInsideAny } from "../paths.js";
 import { CLAUDE_CODE } from "./claude_code.js";
 import { CODEX_CLI } from "./codex_cli.js";
 import { CURSOR } from "./cursor.js";
-import { UNKNOWN_AGENT_ID, } from "./types.js";
+import { HOOK_EVENTS, UNKNOWN_AGENT_ID, } from "./types.js";
 /**
  * Every dialect, in registration order.
  *
@@ -100,6 +100,52 @@ export function resolveAgentId(argv) {
 export function dialectFor(agentId) {
     return DIALECTS.find((dialect) => dialect.id === agentId) ?? CLAUDE_CODE;
 }
+/**
+ * ⛔ **WHICH OF THE THREE EVENTS IS THIS `hook_event_name`? — `CR-195`, D205.**
+ *
+ * Returns the canonical `HookEventName`, or `null` for a string that names none
+ * of them. `null` is a real answer and not a failure: Claude Code, Codex and
+ * Cursor between them fire far more events than the three this client registers,
+ * and a `SubagentStop` payload arriving here is ordinary rather than wrong.
+ *
+ * ## ⛔ The dialect's own table first, then a case-insensitive fallback
+ *
+ * The exact match is the answer whenever the agent spells events the way its
+ * dialect says it does. The fallback exists for the case that has already bitten
+ * this client once — ⚠ **a spelling nobody anticipated** — and the asymmetry is
+ * what justifies it:
+ *
+ *   - **failing to recognise `SessionEnd` costs the final turn, permanently.**
+ *     That event has no next invocation to pick up what was missed.
+ *   - **recognising one spuriously costs 150 ms of reserve and one settle.**
+ *
+ * Those are not the same size, so this resolves in the direction that captures.
+ * ⛔ It is D164 §D7's ruling applied to events rather than to agent ids — *"an
+ * unknown id falls back; it never stops capture … a misconfigured hook that
+ * captures NOTHING is a worse outcome than one that captures conservatively"* —
+ * and it is the same shape: a BEHAVIOUR fallback that rewrites nothing on the
+ * wire.
+ *
+ * ⚠ **The fallback can only ever ADD recognition, never redirect it.** It runs
+ * only after the exact match has already failed, so a dialect's own spelling
+ * always wins; and `HOOK_EVENTS` is unambiguous case-insensitively, so no
+ * canonical event can be resolved as a different canonical event.
+ * `test/dialect-events.test.ts` pins both directions, including the distinctness
+ * that makes the second claim true rather than merely currently true.
+ *
+ * ⚠ **NOT a widening of the confinement boundary and not adjacent to one.** The
+ * value read here decides how long to wait and whether to settle; it never
+ * reaches a path that decides what may be READ. That stays `transcriptRoots`.
+ */
+export function canonicalHookEvent(dialect, wireName) {
+    if (wireName === "")
+        return null;
+    const exact = HOOK_EVENTS.find((event) => dialect.eventNames[event] === wireName);
+    if (exact !== undefined)
+        return exact;
+    const folded = wireName.toLowerCase();
+    return HOOK_EVENTS.find((event) => event.toLowerCase() === folded) ?? null;
+}
 /**
  * Every transcript root, deduped — ⛔ **the confinement boundary, computed from
  * the REGISTRY and never from input.**

package/dist/agents/registry.js.map

@@ -1 +1 @@
-{"version":3,"file":"registry.js","sourceRoot":"","sources":["../../src/agents/registry.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;GA2BG;AAEH,OAAO,EAAE,QAAQ,EAAE,WAAW,EAAE,MAAM,aAAa,CAAC;AACpD,OAAO,EAAE,WAAW,EAAE,MAAM,kBAAkB,CAAC;AAC/C,OAAO,EAAE,SAAS,EAAE,MAAM,gBAAgB,CAAC;AAC3C,OAAO,EAAE,MAAM,EAAE,MAAM,aAAa,CAAC;AACrC,OAAO,EACL,gBAAgB,GAIjB,MAAM,YAAY,CAAC;AAEpB;;;;;;;;GAQG;AACH,MAAM,CAAC,MAAM,QAAQ,GAAiC,CAAC,WAAW,EAAE,SAAS,EAAE,MAAM,CAAC,CAAC;AAEvF;;;;;;GAMG;AACH,MAAM,CAAC,MAAM,gBAAgB,GAAY,aAAa,CAAC;AAEvD,uEAAuE;AACvE,MAAM,UAAU,GAAG,UAAU,CAAC;AAE9B;;;;;;;;;;;;;;;;;;;;;GAqBG;AACH,MAAM,UAAU,cAAc,CAAC,IAAuB;IACpD,KAAK,MAAM,GAAG,IAAI,IAAI,EAAE,CAAC;QACvB,IAAI,CAAC,GAAG,CAAC,UAAU,CAAC,UAAU,CAAC;YAAE,SAAS;QAC1C,MAAM,KAAK,GAAG,GAAG,CAAC,KAAK,CAAC,UAAU,CAAC,MAAM,CAAC,CAAC,IAAI,EAAE,CAAC;QAClD,IAAI,KAAK,KAAK,EAAE;YAAE,OAAO,KAAK,CAAC;IACjC,CAAC;IACD,OAAO,gBAAgB,CAAC;AAC1B,CAAC;AAED;;;;;;;;;;;;;GAaG;AACH,MAAM,UAAU,UAAU,CAAC,OAA2B;IACpD,OAAO,QAAQ,CAAC,IAAI,CAAC,CAAC,OAAO,EAAE,EAAE,CAAC,OAAO,CAAC,EAAE,KAAK,OAAO,CAAC,IAAI,WAAW,CAAC;AAC3E,CAAC;AAED;;;;;;;;;;;;GAYG;AACH,MAAM,UAAU,eAAe,CAAC,IAAY,EAAE,GAAsB;IAClE,OAAO,CAAC,GAAG,IAAI,GAAG,CAAC,QAAQ,CAAC,GAAG,CAAC,CAAC,OAAO,EAAE,EAAE,CAAC,OAAO,CAAC,cAAc,CAAC,IAAI,EAAE,GAAG,CAAC,CAAC,CAAC,CAAC,CAAC;AACpF,CAAC;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA8BG;AACH,MAAM,UAAU,gBAAgB,CAC9B,IAAY,EACZ,GAAsB,EACtB,cAAsB;IAEtB,IAAI,CAAC,WAAW,CAAC,eAAe,CAAC,IAAI,EAAE,GAAG,CAAC,EAAE,cAAc,CAAC;QAAE,OAAO,KAAK,CAAC;IAC3E,MAAM,OAAO,GAAG,UAAU,CAAC,kBAAkB,CAAC,IAAI,EAAE,GAAG,EAAE,cAAc,CAAC,CAAC,CAAC;IAC1E,OAAO,OAAO,CAAC,UAAU,CAAC,OAAO,CAAC,cAAc,CAAC,IAAI,EAAE,GAAG,CAAC,EAAE,cAAc,CAAC,CAAC;AAC/E,CAAC;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAmDG;AACH,MAAM,UAAU,kBAAkB,CAChC,IAAY,EACZ,GAAsB,EACtB,cAAsB;IAEtB,MAAM,OAAO,GAAG,QAAQ,CAAC,MAAM,CAAC,CAAC,OAAO,EAAE,EAAE,CAC1C,QAAQ,CAAC,OAAO,CAAC,cAAc,CAAC,IAAI,EAAE,GAAG,CAAC,EAAE,cAAc,CAAC,CAC5D,CAAC;IACF,OAAO,OAAO,CAAC,MAAM,KAAK,CAAC,CAAC,CAAC,CAAC,OAAO,CAAC,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,gBAAgB,CAAC;AACjE,CAAC"}
+{"version":3,"file":"registry.js","sourceRoot":"","sources":["../../src/agents/registry.ts"],"names":[],"mappings":"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"}

package/dist/agents/types.d.ts

@@ -44,6 +44,7 @@
  * MEASUREMENT un-excluded it — 113 files under Cursor's root, exactly one of
  * them a transcript.
  */
+import type { HookDocShape } from "../agent_hooks.js";
 /**
  * The canonical agent ids — ⛔ **D164 §1 owns this list; this file CITES it.**
  *
@@ -159,6 +160,19 @@ export interface EventBudget {
     /** What this client gives itself. Strictly the smaller of the two. */
     readonly clientBudgetMs: number;
 }
+/**
+ * One agent's hook-config file, and the document shape it validates.
+ *
+ * `path` takes `home` and `env` for the reason every other function member on
+ * this interface does: a module that reads the real HOME cannot be tested
+ * without writing into the developer's own agent configuration — and here that
+ * is not a tidiness argument, it is the difference between a test suite and a
+ * program that edits `~/.claude/settings.json` when you run `npm test`.
+ */
+export interface AgentHookConfig {
+    readonly path: (home: string, env: NodeJS.ProcessEnv) => string;
+    readonly shape: HookDocShape;
+}
 /** Where `connect` found the session running right now. */
 export interface LocatedTranscript {
     readonly path: string;
@@ -228,6 +242,68 @@ export interface TranscriptDialect {
      * That is D177 §7's direction test: fail-closed both ways round.
      */
     readonly admitsFile: (root: string, path: string) => boolean;
+    /**
+     * ⛔ **WHAT THIS AGENT CALLS THE THREE EVENTS — `CR-195`, D205.**
+     *
+     * The canonical name is the KEY and the agent's own spelling is the VALUE, in
+     * that direction on purpose: the key set is `HookEventName`, so the compiler
+     * makes a dialect answer for all three and `EventBudget`'s totality argument
+     * above applies here unchanged.
+     *
+     * ## ⛔ Why this exists at all, and why it is not a `HookEventName` widening
+     *
+     * `D5` predicted the failure and `CR-195` measured it. Cursor's events are
+     * **camelCase** — `stop`, `preCompact`, `sessionEnd` — against this client's
+     * `Stop`, `PreCompact`, `SessionEnd`. `parseHookInput` hands back whatever
+     * string it was given, so `input.eventName === "SessionEnd"` against a Cursor
+     * payload is **not an error, it is `false`**: no settle on the final turn
+     * (lost permanently — that event has no next invocation) and no gap-stamp
+     * reserve. Nothing raises and the hook still exits 0.
+     *
+     * ⚠ **Widening `HookEventName` was the obvious fix and it is the wrong one.**
+     * The three map 1:1, so a rename belongs in a per-dialect table; widening the
+     * union would make `Readonly<Record<HookEventName, EventBudget>>` non-total
+     * over the real event set and force every dialect to declare budgets for
+     * events it can never receive.
+     *
+     * ## ⚠ MEASURED per dialect, and the two measurements differ in kind
+     *
+     *   - **Cursor** — read out of the shipped app bundle's `*.js`, which carry the
+     *     event object as literals. Seventeen events; three are ours.
+     *   - **Codex** — read out of the native binary's embedded JSON schema, where
+     *     each `hook_event_name` is a `const`. PascalCase, so this dialect's table
+     *     is IDENTITY. ⛔ The binary also carries a snake_case enum of the same
+     *     events; a differential run against throwaway `CODEX_HOME`s proved that
+     *     spelling is **not** what `hooks.json` accepts — `SessionEnd` is
+     *     recognised, `session_end` is silently ignored. See
+     *     `test/dialect-events.test.ts`, which records the method.
+     */
+    readonly eventNames: Readonly<Record<HookEventName, string>>;
+    /**
+     * ⛔ **THE FILE `connect` WRITES TO, AND WHICH DOCUMENT SHAPE IT USES —
+     * `CR-195`/U4b, D205.**
+     *
+     * ⚠ **Hook-config knowledge is not new on this interface**, which is the
+     * argument for putting it here rather than in a parallel table keyed by agent
+     * id. `events.registeredTimeoutMs` is already defined as *"what the agent's
+     * hook config registers"* — this member is what makes that value WRITABLE
+     * instead of a mirror of a file maintained by hand in another repository. A
+     * second table would be a second source that can disagree with the first,
+     * which is the `plan §T1` objection.
+     *
+     * ⛔ **TWO SHAPES ACROSS THREE AGENTS, and they are not interchangeable.**
+     * Claude Code and Codex share the nested form; Cursor requires a top-level
+     * numeric `version` and a FLAT entry array, and treats an unrecognised event
+     * key as a validation error. Writing the wrong one does not fail loudly — it
+     * produces a file that parses, registers nothing, and reports success.
+     *
+     * ⚠ **`timeoutSec` is NOT a member here, deliberately.** It is derived from
+     * `events[event].registeredTimeoutMs`, so the number this client writes into
+     * an agent's config and the number it checks its own watchdog against cannot
+     * drift apart. For Codex that derivation lands on 3 s for `SessionEnd`, which
+     * is exactly the cap Codex silently clamps to — measured, not inferred.
+     */
+    readonly hookConfig: AgentHookConfig;
     /** Per-event clocks. See `EventBudget` for the relation that binds them. */
     readonly events: Readonly<Record<HookEventName, EventBudget>>;
     readonly delegatedTranscripts: DelegatedTranscripts;

package/dist/agents/types.js.map

@@ -1 +1 @@
-{"version":3,"file":"types.js","sourceRoot":"","sources":["../../src/agents/types.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA6CG;AA0BH;;;;;;;;;;GAUG;AACH,MAAM,CAAC,MAAM,gBAAgB,GAAG,SAAS,CAAC;AA6D1C;;;;;;GAMG;AACH,MAAM,CAAC,MAAM,WAAW,GAAG,CAAC,MAAM,EAAE,YAAY,EAAE,YAAY,CAAU,CAAC"}
+{"version":3,"file":"types.js","sourceRoot":"","sources":["../../src/agents/types.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA6CG;AA4BH;;;;;;;;;;GAUG;AACH,MAAM,CAAC,MAAM,gBAAgB,GAAG,SAAS,CAAC;AA6D1C;;;;;;GAMG;AACH,MAAM,CAAC,MAAM,WAAW,GAAG,CAAC,MAAM,EAAE,YAAY,EAAE,YAAY,CAAU,CAAC"}

package/dist/commands/auth.d.ts

@@ -0,0 +1,66 @@
+/**
+ * `vibecommit auth` — save this machine's ingest credential. `CR-216/U2`, D206.
+ *
+ * ## The defect this closes
+ *
+ * `~/.vibecommit/credentials.json` was a READ PATH WITH NO PRODUCER. `paths.ts`
+ * named it, `credential.ts` parsed it, `readSecretFile` policed its mode and
+ * `TROUBLESHOOTING.chmodCredentials` told the user to `chmod 600` it — and
+ * nothing in the package ever wrote it. The only credential that reached a hook
+ * came from `VIBECOMMIT_TOKEN`, the escape hatch `credential.ts:28` documents as
+ * being for headless and CI use. So a `git commit` from any ordinary shell ran
+ * the post-commit hook with no credential and bound nothing, and because the
+ * hook exit contract makes a missing credential SILENT by design — correctly, so
+ * capture never derails a developer's turn — the user got transcript capture,
+ * zero commit edges, and no error anywhere to explain it.
+ *
+ * ## Why this is a verb and not a beat inside `connect`
+ *
+ * The obvious fix was "`connect` already holds a credential, so persist it". It
+ * is circular. `connect`'s `credentialBeat` calls the same `loadCredential`
+ * every other surface calls, so the credential it holds came from
+ * `VIBECOMMIT_TOKEN` or from the file — there is no third source. Persisting it
+ * would mean the file could only ever be seeded from the variable it exists to
+ * replace, and on the fresh machine that has the defect there is nothing to
+ * persist at all. The plaintext has to enter the machine somewhere explicit, and
+ * this verb is that place.
+ *
+ * ## ⛔ Why the credential may not be an argument
+ *
+ * `vibecommit auth <token>` is the shape everyone reaches for first, and it is
+ * the wrong one: `argv` lands in the shell's history file and, on most systems,
+ * in `/proc/<pid>/cmdline` for any local process to read while the command runs.
+ * `credential.ts` spends a whole module closing four NARROWER leaks — template
+ * interpolation, `JSON.stringify`, `console.error(obj)`, an unhandled rejection
+ * — so accepting the secret through a wider channel than all of them would make
+ * that discipline theatre. It is refused loudly rather than quietly ignored,
+ * because a user who typed it needs to be told it is now in their history.
+ *
+ * ## What this verb is NOT
+ *
+ * It is not sign-in, and it does not mint. `mintIngestCredential` exists in
+ * `vibecommit-mcp` with no route in front of it, so on this side of the wire the
+ * plaintext still comes from the web app's `POST /api/ingest-credentials`, shown
+ * once, and the human carries it here. Putting a route in front of the minter is
+ * the PKCE work `connect.ts` defers; this verb makes the paste path first-class,
+ * it does not remove the paste.
+ *
+ * @provenance vibecommit-mcp src/oauth/ingest_credential.ts — no route mints one, re-verified
+ * @provenance vibecommit-web app/api/ingest-credentials/route.ts — the only producer, verified
+ */
+import type { CommandContext } from "./context.js";
+export interface AuthDeps {
+    /**
+     * Read the secret from a terminal WITHOUT ECHOING IT. Injected for the same
+     * reason `why` injects its reader: the suite must drive every arm, and a test
+     * cannot type into a TTY.
+     *
+     * ⛔ NOT `ctx.ask`. That is the consent prompt — it echoes, which is right for
+     * `y/N` and wrong for a long-lived secret that would then sit in the user's
+     * scrollback for anyone who scrolls up or screenshots the window.
+     */
+    readonly readSecret?: (prompt: string) => Promise<string>;
+    /** Read the whole of stdin. The pipe path, and the only path on a non-TTY. */
+    readonly readStdin?: () => Promise<string>;
+}
+export declare function auth(ctx: CommandContext, argv: readonly string[], deps?: AuthDeps): Promise<number>;

package/dist/commands/auth.js

@@ -0,0 +1,119 @@
+/**
+ * `vibecommit auth` — save this machine's ingest credential. `CR-216/U2`, D206.
+ *
+ * ## The defect this closes
+ *
+ * `~/.vibecommit/credentials.json` was a READ PATH WITH NO PRODUCER. `paths.ts`
+ * named it, `credential.ts` parsed it, `readSecretFile` policed its mode and
+ * `TROUBLESHOOTING.chmodCredentials` told the user to `chmod 600` it — and
+ * nothing in the package ever wrote it. The only credential that reached a hook
+ * came from `VIBECOMMIT_TOKEN`, the escape hatch `credential.ts:28` documents as
+ * being for headless and CI use. So a `git commit` from any ordinary shell ran
+ * the post-commit hook with no credential and bound nothing, and because the
+ * hook exit contract makes a missing credential SILENT by design — correctly, so
+ * capture never derails a developer's turn — the user got transcript capture,
+ * zero commit edges, and no error anywhere to explain it.
+ *
+ * ## Why this is a verb and not a beat inside `connect`
+ *
+ * The obvious fix was "`connect` already holds a credential, so persist it". It
+ * is circular. `connect`'s `credentialBeat` calls the same `loadCredential`
+ * every other surface calls, so the credential it holds came from
+ * `VIBECOMMIT_TOKEN` or from the file — there is no third source. Persisting it
+ * would mean the file could only ever be seeded from the variable it exists to
+ * replace, and on the fresh machine that has the defect there is nothing to
+ * persist at all. The plaintext has to enter the machine somewhere explicit, and
+ * this verb is that place.
+ *
+ * ## ⛔ Why the credential may not be an argument
+ *
+ * `vibecommit auth <token>` is the shape everyone reaches for first, and it is
+ * the wrong one: `argv` lands in the shell's history file and, on most systems,
+ * in `/proc/<pid>/cmdline` for any local process to read while the command runs.
+ * `credential.ts` spends a whole module closing four NARROWER leaks — template
+ * interpolation, `JSON.stringify`, `console.error(obj)`, an unhandled rejection
+ * — so accepting the secret through a wider channel than all of them would make
+ * that discipline theatre. It is refused loudly rather than quietly ignored,
+ * because a user who typed it needs to be told it is now in their history.
+ *
+ * ## What this verb is NOT
+ *
+ * It is not sign-in, and it does not mint. `mintIngestCredential` exists in
+ * `vibecommit-mcp` with no route in front of it, so on this side of the wire the
+ * plaintext still comes from the web app's `POST /api/ingest-credentials`, shown
+ * once, and the human carries it here. Putting a route in front of the minter is
+ * the PKCE work `connect.ts` defers; this verb makes the paste path first-class,
+ * it does not remove the paste.
+ *
+ * @provenance vibecommit-mcp src/oauth/ingest_credential.ts — no route mints one, re-verified
+ * @provenance vibecommit-web app/api/ingest-credentials/route.ts — the only producer, verified
+ */
+import { AUTH, URLS } from "../copy/index.js";
+import { writeLines } from "./context.js";
+import { EXIT } from "../exit.js";
+import { INGEST_TOKEN_PREFIX, IngestCredential, saveCredential } from "../credential.js";
+import { credentialsPath } from "../paths.js";
+import { renderErrorBlock, tildePath } from "../term.js";
+/**
+ * `--stdin` forces the pipe even on a terminal — the CI shape, where a job may
+ * well have a TTY attached and must not start prompting because of it.
+ */
+const STDIN_FLAG = "--stdin";
+export async function auth(ctx, argv, deps = {}) {
+    // ⛔ THE ARGV REFUSAL COMES FIRST, before stdin is read, resumed or opened.
+    // Anything else would mean the secret in `argv` had already been accepted by
+    // the time we objected to it.
+    const positional = argv.filter((arg) => !arg.startsWith("-"));
+    if (positional.length > 0) {
+        writeLines(ctx.stderr, renderErrorBlock({
+            kind: "bad",
+            what: AUTH.argvWhat,
+            why: [AUTH.argvWhy],
+            fixLabel: AUTH.argvFix,
+            fixes: [AUTH.argvFixPrompt, AUTH.argvFixStdin],
+        }, ctx.colour));
+        return EXIT.usage;
+    }
+    const piped = argv.includes(STDIN_FLAG) || !ctx.stdinIsTty;
+    const raw = piped
+        ? await (deps.readStdin ?? (() => Promise.resolve("")))()
+        : await (deps.readSecret ?? (() => Promise.resolve("")))(AUTH.prompt);
+    // One `trim` for both lanes. A paste carries a trailing newline and a pipe may
+    // carry `\r\n`; neither is part of the credential, and an untrimmed byte would
+    // fail the prefix check further down for a reason the user cannot see.
+    const secret = raw.trim();
+    if (secret === "") {
+        writeLines(ctx.stderr, renderErrorBlock({
+            kind: "bad",
+            what: AUTH.emptyWhat,
+            why: [AUTH.emptyWhy],
+            fixLabel: AUTH.emptyFix,
+            fixes: [URLS.settings],
+        }, ctx.colour));
+        return EXIT.failure;
+    }
+    // The class check happens HERE as well as at the write boundary, and the
+    // duplication is deliberate: this one renders a fix for a human who pasted the
+    // wrong string, and `saveCredential`'s throws for a caller who should not have
+    // asked. Neither is the other's fallback.
+    if (!secret.startsWith(INGEST_TOKEN_PREFIX)) {
+        writeLines(ctx.stderr, renderErrorBlock({
+            kind: "bad",
+            what: AUTH.wrongClassWhat,
+            why: [AUTH.wrongClassWhy],
+            fixLabel: AUTH.wrongClassFix,
+            fixes: [URLS.settings],
+        }, ctx.colour));
+        return EXIT.failure;
+    }
+    saveCredential(ctx.home, new IngestCredential(secret, "file"));
+    writeLines(ctx.stdout, renderErrorBlock({
+        kind: "ok",
+        what: AUTH.savedWhat,
+        why: [AUTH.savedWhy(tildePath(credentialsPath(ctx.home), ctx.home))],
+        fixLabel: AUTH.nextLabel,
+        fixes: [AUTH.nextCommand],
+    }, ctx.colour));
+    return EXIT.ok;
+}
+//# sourceMappingURL=auth.js.map

package/dist/commands/auth.js.map

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

package/dist/commands/connect.js

@@ -22,13 +22,14 @@
  *
  * @provenance vibecommit-mcp src/oauth/ingest_credential.ts — no route mints one, verified
  */
-import { CONNECT, COMMANDS, COMMIT_HOOK, ERRORS, HELP, PATH_CLASH, RUNTIME, SIGNIN, URLS, } from "../copy/index.js";
+import { CONNECT, COMMANDS, AGENT_HOOKS, COMMIT_HOOK, ERRORS, HELP, PATH_CLASH, RUNTIME, SIGNIN, URLS, } from "../copy/index.js";
 import { dialectFor } from "../agents/registry.js";
 import { grantProject, isAffirmative, isProjectAllowed } from "../consent.js";
 import { loadCredential } from "../credential.js";
 import { EXIT } from "../exit.js";
 import { resolveRepoSlug } from "../git.js";
 import { confinementRoots, readSpan, DEFAULT_HOOK_BUDGET_MS } from "../hooks/entry.js";
+import { installAgentHooks } from "../agent_install.js";
 import { classifyInstall, installPostCommitHook } from "../install.js";
 import { mcpUrl } from "../oauth/discovery.js";
 import { loadSession } from "../oauth/session.js";
@@ -359,8 +360,89 @@ async function captureBeat(ctx, keys, credential) {
     // success, which is the only place the PER-CLONE cost can be stated at a
     // moment the user can act on it.
     commitHookBeat(ctx, projectKey);
+    // ⛔ SESSION CAPTURE IS REGISTERED AND REPORTED HERE (`CR-195`/U4b). This is
+    // the beat `/install` has been describing since before it existed — until it,
+    // `connect` wrote GIT hooks only and the npm path gave a user no session
+    // capture at all. It runs AFTER the commit beat because the two are
+    // independent and the commit one is per-clone: reporting the per-clone thing
+    // beside the global one, in that order, is what makes the scope difference
+    // legible rather than a detail in a sentence.
+    agentHookBeat(ctx);
     return pathClash(ctx);
 }
+/**
+ * Register capture with every agent on this machine and SAY WHAT HAPPENED.
+ *
+ * ⚠ **Never changes the exit code**, for `commitHookBeat`'s reason: an agent
+ * whose config we could not parse does not make the connection fail, and
+ * exiting non-zero would tell the user their whole connect failed when one file
+ * of three was unreadable.
+ *
+ * ⛔ **EVERY OUTCOME PRINTS THE PATH.** This is a write OUTSIDE the repository,
+ * into a file shared by every project — the one new responsibility `CR-195`
+ * names — so "we configured your editor" is the shape this must not take.
+ */
+function agentHookBeat(ctx) {
+    const outcomes = installAgentHooks(ctx.home, ctx.env, ctx.selfPath);
+    for (const outcome of outcomes) {
+        // Absent agents say nothing at all. A line per tool the user does not have
+        // is the noise DX3's one-line rule exists to avoid, and it would bury the
+        // agents that WERE wired under a list of ones that were not.
+        if (outcome.install === null)
+            continue;
+        const agent = AGENT_LABELS[outcome.agentId];
+        // ⛔ TRUNCATED, exactly as `commitHookBeat` truncates the repo path. DESIGN.md
+        // §13.4 caps every line at 80 columns and `wrap` cannot break a path — it has
+        // no spaces — so an untruncated `~/.claude/settings.json` under a long temp
+        // or home prefix silently blows the width contract. `test/connect-ending.ts`
+        // caught this at 96 columns; the elision keeps the filename, which is the
+        // half that identifies the file.
+        const path = truncatePath(outcome.path, 56);
+        if (outcome.install.kind === "refused" || outcome.install.kind === "failed") {
+            const refused = outcome.install.kind === "refused";
+            writeLines(ctx.stdout, [
+                "",
+                ...renderErrorBlock({
+                    kind: "warn",
+                    what: refused
+                        ? AGENT_HOOKS.refusedWhat(agent)
+                        : AGENT_HOOKS.failedWhat(agent),
+                    why: [
+                        refused
+                            ? AGENT_HOOKS.refusedWhy(path, outcome.install.why)
+                            : AGENT_HOOKS.failedWhy(path, outcome.install.why),
+                    ],
+                    ...(refused
+                        ? {
+                            fixLabel: AGENT_HOOKS.refusedFixLabel,
+                            fixes: [AGENT_HOOKS.refusedFix(path)],
+                        }
+                        : {}),
+                }, ctx.colour),
+            ]);
+            continue;
+        }
+        const line = outcome.install.kind === "installed"
+            ? AGENT_HOOKS.installed(agent, path)
+            : AGENT_HOOKS.already(agent, path);
+        writeLines(ctx.stdout, [
+            "",
+            ...wrap(line, 2),
+            ...wrap(AGENT_HOOKS.kept(agent), 2),
+            // ⛔ Codex only, and it is not optional politeness: Codex ships the literal
+            // option "Continue without trusting (hooks won't run)", so the file we
+            // just wrote does NOT run until the user trusts it. Printing `installed`
+            // without this would be a true-sounding claim that is not yet true.
+            ...(outcome.agentId === "codex-cli" ? wrap(AGENT_HOOKS.codexTrust, 2) : []),
+        ]);
+    }
+}
+/** What each agent is called in prose. The ids are wire values, not labels. */
+const AGENT_LABELS = {
+    "claude-code": "Claude Code",
+    "codex-cli": "Codex CLI",
+    cursor: "Cursor",
+};
 /**
  * Install the `post-commit` hook for this clone and SAY WHAT HAPPENED.
  *