@vibe-commit/capture 0.1.0

package/dist/agents/registry.js

@@ -0,0 +1,212 @@
+/**
+ * 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 { 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";
+/**
+ * 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 const DIALECTS = [CLAUDE_CODE, CODEX_CLI, CURSOR];
+/**
+ * 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 const DEFAULT_AGENT_ID = "claude-code";
+/** The flag. ⛔ `--agent=<value>`; there is no space-separated form. */
+const AGENT_FLAG = "--agent=";
+/**
+ * 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 function resolveAgentId(argv) {
+    for (const arg of argv) {
+        if (!arg.startsWith(AGENT_FLAG))
+            continue;
+        const value = arg.slice(AGENT_FLAG.length).trim();
+        if (value !== "")
+            return value;
+    }
+    return DEFAULT_AGENT_ID;
+}
+/**
+ * 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 function dialectFor(agentId) {
+    return DIALECTS.find((dialect) => dialect.id === agentId) ?? CLAUDE_CODE;
+}
+/**
+ * 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 function transcriptRoots(home, env) {
+    return [...new Set(DIALECTS.map((dialect) => dialect.transcriptRoot(home, env)))];
+}
+/**
+ * ⛔ **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 function admitsTranscript(home, env, transcriptPath) {
+    if (!isInsideAny(transcriptRoots(home, env), transcriptPath))
+        return false;
+    const dialect = dialectFor(agentForTranscript(home, env, transcriptPath));
+    return dialect.admitsFile(dialect.transcriptRoot(home, env), transcriptPath);
+}
+/**
+ * ⛔ **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 function agentForTranscript(home, env, transcriptPath) {
+    const matches = DIALECTS.filter((dialect) => isInside(dialect.transcriptRoot(home, env), transcriptPath));
+    return matches.length === 1 ? matches[0].id : UNKNOWN_AGENT_ID;
+}
+//# sourceMappingURL=registry.js.map

package/dist/agents/registry.js.map

@@ -0,0 +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"}

package/dist/agents/types.d.ts

@@ -0,0 +1,279 @@
+/**
+ * The transcript lane, as a type.
+ *
+ * `CR-183`, D164 §1. The registry key is the transcript FORMAT, not the agent:
+ * Codex CLI is the second member of ONE lane, not a special case.
+ *
+ * ## The scope statement, verbatim — it is the whole membership rule
+ *
+ * > Agents that append NDJSON to a file and hand a hook its path.
+ *
+ * Read it as an exclusion, because that is the work it does. An agent whose
+ * transcript is Markdown, or a database, or is never handed to a hook at all, is
+ * NOT a member — and adding one is a different capture STRATEGY, not another
+ * entry in this file. `docs/architecture_refactor.md` lists eleven agents; this
+ * lane covers five of them after `CR-193` (D177 §1). "Config not code" is true
+ * WITHIN the lane and false across lanes (D164), and the type below is what
+ * makes that difference mechanical rather than a promise in a comment.
+ *
+ * ## Why the lock-out is `transport` and not a runtime check
+ *
+ * `transport: "ndjson"` is a LITERAL type, so a dialect for a Markdown-transcript
+ * agent cannot be registered without EDITING THIS INTERFACE. That is a compile
+ * error in a diff a human reads, rather than a config line nobody reviews.
+ *
+ * It is not decoration. D164's first ruling names the defect it prevents:
+ * `redact.ts` parses each line as JSON and returns any NON-JSON line UNCHANGED,
+ * which is correct for a partial line at a span boundary and catastrophic for a
+ * transcript that is not JSON at all — every line would ship unredacted.
+ * Redaction correctness is a property of the FORMAT, so the format is what the
+ * type system has to pin.
+ *
+ * ## The members are limited to what two confirmed differences justify
+ *
+ * `transcriptRoot`, `admitsFile`, `events`, `delegatedTranscripts`, `redaction`
+ * and the optional `locateCurrentTranscript` differ between the three members
+ * that exist. `id` names them and `transport` locks the lane. Nothing else is
+ * here, and the omissions are deliberate rather than pending: a field whose only
+ * member set is a guess about an agent nobody has measured is a decision made
+ * early with no evidence, and it will be wrong in the direction that is
+ * expensive to undo.
+ *
+ * ⚠ **`admitsFile` is `CR-193`'s, and it clears that bar rather than bending
+ * it** (D177 §2): it was one of `CR-183`'s seven speculative exclusions until a
+ * MEASUREMENT un-excluded it — 113 files under Cursor's root, exactly one of
+ * them a transcript.
+ */
+/**
+ * The canonical agent ids — ⛔ **D164 §1 owns this list; this file CITES it.**
+ *
+ * ⛔ **D177 §1 widened it to FOUR:** `claude-code` | `codex-cli` | `cursor` |
+ * `unknown`, and four artifacts in three repos must spell them identically.
+ * ⚠ **Only three of the four are dialects.** `unknown` is the SERVER's honest
+ * label for a capture whose producer it did not recognise — the client never
+ * asserts it, because the client sends the literal it was given (see
+ * `resolveAgentId`). So a client-side `unknown` dialect would be a fourth
+ * spelling of a value this side never produces.
+ *
+ * ⛔ **`cursor`, NEVER `cursor-ide` and never `cursor-mcp`** (D177 §1). Not a
+ * style preference: `CLIENT_NAME_ALIASES` already maps both `cursor-mcp` and
+ * `cursor` onto `cursor`, and `agent_ids.test.ts` asserts that every producible
+ * id is one of that map's TARGETS — so `cursor-ide` reds a cell in another
+ * repository on day one.
+ *
+ * The four-way spelling is unguarded in the direction that actually fails: emit
+ * `codex_cli` instead of `codex-cli` and the server does not recognise it, the
+ * default extractor runs, and the row lands `unknown` permanently with no error
+ * anywhere. `test/agent-registry.test.ts` pins the literals.
+ */
+export type AgentId = "claude-code" | "codex-cli" | "cursor";
+/**
+ * D164 §1's third value — a producer nobody can name, never a dialect.
+ *
+ * ⛔ **AND IT NEVER TRAVELS.** The docblock above stays literally true after
+ * `CR-204`: this is the SELECTOR's answer for a transcript no single registry
+ * root contains, and `buildIngestHeaders` turns that answer into an **omitted**
+ * header rather than a sent one. The server distinguishes the two — an absent
+ * header is *"nothing to say"* and cannot disagree with the value a stream is
+ * already pinned to, while a present `unknown` resolves and **does** disagree,
+ * which drops the buffered tail and sheds the in-flight turn. See `post.ts`.
+ */
+export declare const UNKNOWN_AGENT_ID = "unknown";
+/**
+ * What the ROOT SELECTOR can answer — ⛔ **D164 §1's list, and nothing else.**
+ *
+ * ⚠ **Not "what travels":** two of the three do, and `unknown` is the answer
+ * that means *send nothing*. Named for the selection rather than the wire so
+ * that distinction cannot quietly rot into "the wire carries `unknown`".
+ *
+ * A separate type from `AgentId` for the same reason `RedactionProfile` is one:
+ * the fail-closed case has no agent id to be named after. And separate from
+ * `string` — which is what `resolveAgentId` returns — because that is the
+ * structural half of D177 §7. The `--agent=` flag's value is a `string` and is
+ * therefore **not assignable here**: a later edit cannot put the flag on the
+ * wire by mistake, only by widening this type in a diff a human reads.
+ */
+export type SelectedAgentId = AgentId | typeof UNKNOWN_AGENT_ID;
+/**
+ * Which scrubber a span goes through — a LABEL, not an implementation.
+ *
+ * ⛔ `CR-185` owns `src/redact.ts` and what each profile DOES. What lives here is
+ * only the name, because the selection has to be expressible before the
+ * behaviour exists.
+ *
+ * ⚠ **A separate vocabulary from `AgentId`, deliberately, even though the two
+ * coincide today.** D164 §5 makes the profile a property of WHICH REGISTRY ROOT
+ * CONTAINS the resolved transcript path — never of the `--agent=` flag — and the
+ * fail-closed case (a path inside no known root at all) has no agent id to be
+ * named after. Typing it as its own union is what stops a later edit passing an
+ * agent id here and quietly making the two things one.
+ */
+export type RedactionProfile = "claude-code" | "codex-cli" | "cursor";
+/**
+ * How this agent's DELEGATED transcripts are found — announce vs discover.
+ *
+ * The second of the two confirmed differences, and the one that is a genuine
+ * mechanism split rather than a different string:
+ *
+ *   `discover`  the paths are not handed over. Claude Code writes them to
+ *               `<session>/subagents/` and the hook globs `agent-*.jsonl` there
+ *               (`hooks/entry.ts`, `CR-124`).
+ *   `announce`  the path ARRIVES, on hook stdin, as `agent_transcript_path`.
+ *
+ * ⛔ **`announce` HAS A READER AS OF `CR-196`** (D177 §9), and this sentence is
+ * the one that used to say it did not. From `CR-183` until that unit, nothing in
+ * this client parsed `agent_transcript_path`, so a dialect declaring `announce`
+ * delegated nothing at all and the discriminator's only effect was to SUPPRESS
+ * Claude's glob. `announcedSubagentFiles` in `hooks/entry.ts` is the reader.
+ *
+ * ⚠ **What it does NOT change:** the announced path is INPUT and is confined
+ * exactly as a globbed one is (`admitsTranscript` — the registry-computed
+ * boundary plus the file gate), and the stream's `file_key` is still derived
+ * from a FILENAME rather than from anything inside the file. Cursor's children
+ * carry no `agent-` prefix, so the key is SYNTHESIZED client-side
+ * (`announcedSubagentFileKey`); widening the server's stream-key column was
+ * considered and DECLINED, because five independent layers refuse a bare id.
+ */
+export type DelegatedTranscripts = "discover" | "announce";
+/**
+ * The three hook events DESIGN.md §13.7 names.
+ *
+ * Both members of this lane fire the same three; that is exactly why
+ * `hook_event_name` was REJECTED as an adapter selector (`CR-183`) — the events
+ * are shared, so they discriminate nothing.
+ */
+export declare const HOOK_EVENTS: readonly ["Stop", "PreCompact", "SessionEnd"];
+export type HookEventName = (typeof HOOK_EVENTS)[number];
+/**
+ * One event's two clocks, and the relation between them is the point.
+ *
+ * ⛔ `clientBudgetMs` MUST be strictly less than `registeredTimeoutMs`, or the
+ * client's own watchdog never fires and the agent kills the process instead —
+ * which loses the exit-0/silent-stdout contract the watchdog exists to hold.
+ * That relation sat in a comment on `DEFAULT_HOOK_BUDGET_MS` and was checked by
+ * nothing; `test/agent-registry.test.ts` asserts it for every adapter event.
+ */
+export interface EventBudget {
+    /** What the agent's hook config registers, in MILLISECONDS. */
+    readonly registeredTimeoutMs: number;
+    /** What this client gives itself. Strictly the smaller of the two. */
+    readonly clientBudgetMs: number;
+}
+/** Where `connect` found the session running right now. */
+export interface LocatedTranscript {
+    readonly path: string;
+    readonly sessionId: string;
+    readonly size: number;
+}
+/**
+ * One member of the lane.
+ *
+ * Every function member takes `home` and `env` explicitly, for the reason
+ * `paths.ts` does: a module that reads the real HOME cannot be tested without
+ * touching the developer's own transcripts.
+ */
+export interface TranscriptDialect {
+    readonly id: AgentId;
+    /**
+     * ⛔ THE LANE LOCK. A literal type, not a string — see the module docblock.
+     */
+    readonly transport: "ndjson";
+    /**
+     * The directory this agent writes transcripts under.
+     *
+     * ⛔ The CONFINEMENT BOUNDARY is computed from these and NEVER from input.
+     * `transcript_path` arrives on hook stdin and is attacker-influenced in the
+     * one way that matters — it reaches a read whose result is uploaded — so a
+     * path that CLAIMS to be somewhere may never widen where we will read from.
+     */
+    readonly transcriptRoot: (home: string, env: NodeJS.ProcessEnv) => string;
+    /**
+     * ⛔ **IS THIS FILE, INSIDE THAT ROOT, A TRANSCRIPT? — `CR-193`, D177 §2.**
+     *
+     * D177 §2 supersedes `CR-183`'s exclusion of `transcriptExtension`: *"the root
+     * must be `.jsonl`-gated."* This is that field, ⚠ **a predicate rather than an
+     * extension string, because a bare extension cannot express what Cursor needs
+     * it to.** Cursor's transcripts sit two levels below the deepest root
+     * `(home, env)` can express — `<root>/<workspace>/agent-transcripts/…` — and
+     * the three sibling directories at that depth hold scraped web content, a
+     * scratch React project and MCP tool schemas (`isCursorTranscript`).
+     *
+     * ⛔ **REQUIRED, not optional, and that is the same device `transport` uses.**
+     * A dialect added later must ANSWER this rather than inherit a default, and
+     * the compiler is what asks. An optional member would need a registry totality
+     * pin naming the key to be worth anything at all
+     * (`project_optional_member_needs_registry_pin`); a required one gets that
+     * from the type system for free.
+     *
+     * ## ⚠ WHY THIS IS NOT THE DECLARED FIELD `plan §T1` REJECTED
+     *
+     * `plan §D9` proposed a declared *capability* member and `plan §T1` reversed
+     * it, for a reason that reads at a glance like an objection to this field:
+     * `shellInvocationsOf?` is **already optional on the interface, so the members
+     * themselves carry the truth**, and a declared field beside them is a SECOND
+     * source that can disagree with the first.
+     *
+     * ⛔ **Here no member carries it.** Nothing about `transcriptRoot`,
+     * `transport` or `delegatedTranscripts` says which files under a root are
+     * transcripts, and — measured — the answer differs between dialects: under
+     * Claude's and Codex's roots every file is one, under Cursor's 112 of 113 are
+     * not. So this is the **only** source rather than a second one, which is
+     * exactly the condition `T1` turns on. ⚠ Said here because the next reader
+     * sees a declared field on this interface and reasonably wonders whether `T1`
+     * was violated.
+     *
+     * ⚠ **A NARROWING, and only ever a narrowing.** It runs AFTER
+     * `isInsideAny(transcriptRoots(...))` — see `admitsTranscript` — so it can
+     * refuse a path the boundary admitted and can never admit one it refused.
+     * That is D177 §7's direction test: fail-closed both ways round.
+     */
+    readonly admitsFile: (root: string, path: string) => boolean;
+    /** Per-event clocks. See `EventBudget` for the relation that binds them. */
+    readonly events: Readonly<Record<HookEventName, EventBudget>>;
+    readonly delegatedTranscripts: DelegatedTranscripts;
+    readonly redaction: RedactionProfile;
+    /**
+     * ⛔ **WHICH SESSION IS COMMITTING — read from the environment, not inferred
+     * from HEAD (`D3`, `D183`).**
+     *
+     * `spool.ts`'s `activeSessionFor()` picks the most recently mtime'd session
+     * state file within 30 minutes. Two agents in one clone: session A commits, B's
+     * file is newer, **A's commit enters B's spool**, and `cr071:157` makes the
+     * resulting edge PERMANENT — UPDATE and DELETE both raise, `service_role`
+     * included. An environment variable the committing process already carries is
+     * an OBSERVATION; the mtime race is an inference, and it is wrong silently.
+     *
+     * ⚠ **`env` is passed, never read from `process.env` here** — the same reason
+     * every other function member takes `home` and `env`: a module that reads the
+     * real environment cannot be tested without the developer's own session id.
+     *
+     * ⛔ **REQUIRED, not optional, and that is `admitsFile`'s device.** A dialect
+     * added later must ANSWER this rather than inherit a default, and the compiler
+     * is what asks. An optional member would be behaviourally identical to a
+     * hoisted `undefined` branch and would be worth only what a registry totality
+     * pin naming the key made it worth
+     * (`project_optional_member_needs_registry_pin`). ⚠ The pin in
+     * `test/agent-registry.test.ts` is kept ANYWAY, because the compiler cannot see
+     * the other mutation: a dialect DELETED FROM THE REGISTRY has no missing member
+     * to complain about.
+     *
+     * ⛔ **`null` FROM AN UNMEASURED DIALECT IS NOT "THIS AGENT HAS NO SESSION
+     * ID".** Two of the three return `null` because nobody has measured them, and
+     * the docblock at each one says **UNMEASURED** by that word so a later reader
+     * can tell the two apart. `null` also remains the honest answer for the
+     * MEASURED dialect when the variable is absent — a human's `git commit` strips
+     * it — and that arm is measured (`M1`).
+     */
+    readonly sessionIdFromEnv: (env: NodeJS.ProcessEnv) => string | null;
+    /**
+     * Find the session running right now — for `connect`, which is typed by a
+     * human and is handed no `transcript_path`.
+     *
+     * ⛔ **OPTIONAL, and its absence is a real answer.** An agent with no locator
+     * makes `connect` SKIP the test-capture beat entirely rather than fall back to
+     * something. The available fallback would be to read a `cwd` out of the
+     * transcript's own records to find the repository, and that is ANALYSIS, which
+     * D60 §D6 forbids this client outright.
+     */
+    readonly locateCurrentTranscript?: (home: string, env: NodeJS.ProcessEnv, projectKey: string) => LocatedTranscript | null;
+}

package/dist/agents/types.js

@@ -0,0 +1,67 @@
+/**
+ * The transcript lane, as a type.
+ *
+ * `CR-183`, D164 §1. The registry key is the transcript FORMAT, not the agent:
+ * Codex CLI is the second member of ONE lane, not a special case.
+ *
+ * ## The scope statement, verbatim — it is the whole membership rule
+ *
+ * > Agents that append NDJSON to a file and hand a hook its path.
+ *
+ * Read it as an exclusion, because that is the work it does. An agent whose
+ * transcript is Markdown, or a database, or is never handed to a hook at all, is
+ * NOT a member — and adding one is a different capture STRATEGY, not another
+ * entry in this file. `docs/architecture_refactor.md` lists eleven agents; this
+ * lane covers five of them after `CR-193` (D177 §1). "Config not code" is true
+ * WITHIN the lane and false across lanes (D164), and the type below is what
+ * makes that difference mechanical rather than a promise in a comment.
+ *
+ * ## Why the lock-out is `transport` and not a runtime check
+ *
+ * `transport: "ndjson"` is a LITERAL type, so a dialect for a Markdown-transcript
+ * agent cannot be registered without EDITING THIS INTERFACE. That is a compile
+ * error in a diff a human reads, rather than a config line nobody reviews.
+ *
+ * It is not decoration. D164's first ruling names the defect it prevents:
+ * `redact.ts` parses each line as JSON and returns any NON-JSON line UNCHANGED,
+ * which is correct for a partial line at a span boundary and catastrophic for a
+ * transcript that is not JSON at all — every line would ship unredacted.
+ * Redaction correctness is a property of the FORMAT, so the format is what the
+ * type system has to pin.
+ *
+ * ## The members are limited to what two confirmed differences justify
+ *
+ * `transcriptRoot`, `admitsFile`, `events`, `delegatedTranscripts`, `redaction`
+ * and the optional `locateCurrentTranscript` differ between the three members
+ * that exist. `id` names them and `transport` locks the lane. Nothing else is
+ * here, and the omissions are deliberate rather than pending: a field whose only
+ * member set is a guess about an agent nobody has measured is a decision made
+ * early with no evidence, and it will be wrong in the direction that is
+ * expensive to undo.
+ *
+ * ⚠ **`admitsFile` is `CR-193`'s, and it clears that bar rather than bending
+ * it** (D177 §2): it was one of `CR-183`'s seven speculative exclusions until a
+ * MEASUREMENT un-excluded it — 113 files under Cursor's root, exactly one of
+ * them a transcript.
+ */
+/**
+ * D164 §1's third value — a producer nobody can name, never a dialect.
+ *
+ * ⛔ **AND IT NEVER TRAVELS.** The docblock above stays literally true after
+ * `CR-204`: this is the SELECTOR's answer for a transcript no single registry
+ * root contains, and `buildIngestHeaders` turns that answer into an **omitted**
+ * header rather than a sent one. The server distinguishes the two — an absent
+ * header is *"nothing to say"* and cannot disagree with the value a stream is
+ * already pinned to, while a present `unknown` resolves and **does** disagree,
+ * which drops the buffered tail and sheds the in-flight turn. See `post.ts`.
+ */
+export const UNKNOWN_AGENT_ID = "unknown";
+/**
+ * The three hook events DESIGN.md §13.7 names.
+ *
+ * Both members of this lane fire the same three; that is exactly why
+ * `hook_event_name` was REJECTED as an adapter selector (`CR-183`) — the events
+ * are shared, so they discriminate nothing.
+ */
+export const HOOK_EVENTS = ["Stop", "PreCompact", "SessionEnd"];
+//# sourceMappingURL=types.js.map

package/dist/agents/types.js.map

@@ -0,0 +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"}

package/dist/commands/connect.d.ts

@@ -0,0 +1,36 @@
+/**
+ * `vibecommit connect` — the install moment.
+ *
+ * This task owns the CONSENT GATE and the runtime floor. Two later tasks own the
+ * rest of the screen and must not be front-run:
+ *   - `CR-111d` landed the disclosure copy, transcribed from style guide §10.2.
+ *     D64 falsified the trust argument the earlier draft used (this repo is
+ *     private, so "read the source" is false and BLOCKED). The approved
+ *     replacement links `Vibe-Commit/claude-plugin`, which vendors the exact
+ *     binary — and "inspect the build" is WEAKER than "read the source" and may
+ *     not be dressed up as it.
+ *   - `CR-025` owns the ending: capture the current session and print the live
+ *     `/app/commits/<sha>` URL. The seam is marked below.
+ *
+ * `CR-084d` lands the browser sign-in beat (PKCE loopback → a user-principal
+ * token for the READ lane) behind `--sign-in`. It is opt-in and not part of the
+ * default install for one reason: **sign-in does not produce an ingest
+ * credential**, so it cannot replace the beat below. No route in
+ * `vibecommit-mcp` mints a `vcik_` — `mintIngestCredential` exists and has no
+ * call site outside that repo's own tests — so `VIBECOMMIT_TOKEN` remains the
+ * supported path for capture, exactly as before.
+ *
+ * @provenance vibecommit-mcp src/oauth/ingest_credential.ts — no route mints one, verified
+ */
+import { type CommandContext } from "./context.js";
+/**
+ * What `connect` was asked to do beyond the default.
+ *
+ * A parameter rather than a field on `CommandContext`: the context is ambient
+ * state (env, home, the clock), and which flags were typed is an argument.
+ */
+export interface ConnectOptions {
+    /** `--sign-in`. Off by default — see the module note for why. */
+    readonly signIn?: boolean;
+}
+export declare function connect(ctx: CommandContext, options?: ConnectOptions): Promise<number>;