@vibe-commit/capture 0.1.0

package/dist/hooks/session_end.js

@@ -0,0 +1,120 @@
+/**
+ * `SessionEnd` settles before it reads — `CR-020d`, D57 §DX7.
+ *
+ * The finding, verbatim: *"`SessionEnd` settles and re-reads inside its timeout.
+ * `transcript_path` is documented as written asynchronously and may lag;
+ * `SessionEnd` has no next event, so D56's advance-regardless loses the final
+ * turn **permanently**."*
+ *
+ * ## Why only this event
+ *
+ * The client's whole design tolerates a lagging write: read what is there, leave
+ * the offset where it lands, and let the NEXT invocation pick up whatever the
+ * write had not flushed yet. `Stop` and `PreCompact` both have a next
+ * invocation. `SessionEnd` does not — it is the last hook of the session, so
+ * bytes missed here are missed forever, and they are the bytes of the final
+ * turn, which is the one a user is most likely to go looking for.
+ *
+ * So the fix is narrow on purpose: one event pays the cost, and `Stop` behaves
+ * exactly as it did before this task. `test/contract.test.ts` asserts that
+ * negative half directly, because a change that quietly made every event settle
+ * would pass the positive test just as well.
+ *
+ * ## One wait, not a poll loop
+ *
+ * The task is "settle-and-reread", singular. D56 §D8 is a founder override that
+ * a hook must never block or slow a developer's turn, and "wait until the file
+ * stops growing" has no natural upper bound — under load it is unbounded exactly
+ * when blocking is least affordable. A single named wait is the simplest thing
+ * that closes the finding, and its cost is knowable by reading one constant.
+ *
+ * ## This module holds no I/O and no clock
+ *
+ * `settledSize` takes both, for the same reason `policy.ts` is pure: the whole
+ * settle rule is then testable without a real 250 ms of wall clock and without a
+ * filesystem, and the one place that does touch either is the caller.
+ */
+/**
+ * The event name Claude Code sends on stdin as `hook_event_name` for the last
+ * hook of a session. DESIGN.md §13.7 governs it alongside `Stop` and
+ * `PreCompact`; this task changes WHEN bytes are read, never the exit contract.
+ */
+export const SESSION_END_EVENT = "SessionEnd";
+/**
+ * How long to let the transcript settle. **250 ms, and the number is reasoned.**
+ *
+ * The lag being covered is a local filesystem write-flush artifact — Claude
+ * Code's own process appending JSONL lines to a file this process is about to
+ * stat — not a network round trip. That puts the expected lag in the
+ * tens-of-milliseconds range, so 250 ms is roughly an order of magnitude of
+ * margin over the effect it is covering, while staying a twentieth of the
+ * default 5 s budget.
+ *
+ * It is deliberately NOT larger. Every millisecond here is taken from the send
+ * that follows (see `settleDelayMs`), and a settle generous enough to cover a
+ * pathologically slow write would starve the upload it exists to make complete.
+ * If evidence ever shows real lag above this, change the constant and say why —
+ * it is one number in one place precisely so that stays cheap.
+ */
+export const SESSION_END_SETTLE_DELAY_MS = 250;
+/**
+ * The most of the hook's budget the settle may ever claim.
+ *
+ * The settle is carved OUT of the existing budget, never added on top of it, so
+ * it competes with the send. This cap is what keeps the constant above safe at
+ * any budget: on the 5 s default it never binds (0.3 × 5000 = 1500 ≫ 250), and
+ * on a budget small enough that a flat 250 ms would swallow the invocation it
+ * scales the settle down instead of eating the send.
+ */
+export const SETTLE_BUDGET_FRACTION = 0.3;
+/**
+ * How long to actually settle, given this invocation's whole budget.
+ *
+ * The override exists for the same two reasons `resolveCaps` has one
+ * (`policy.ts`): an operator on a filesystem slower than this constant assumes
+ * can raise it without a release, and the end-to-end test has to widen the
+ * window to land an append inside it deterministically rather than racing a
+ * child's boot — which varies by an order of magnitude under load (`CR-126`).
+ *
+ * Unset or unparseable takes the default rather than disabling the settle: a
+ * window an empty string can switch off is not a window. The budget cap still
+ * applies to the override, so it can widen the settle but never let it swallow
+ * the send.
+ */
+export function settleDelayMs(env, budgetMs) {
+    const raw = env.VIBECOMMIT_SESSION_END_SETTLE_MS;
+    const parsed = raw === undefined ? NaN : Number(raw);
+    const configured = Number.isFinite(parsed) && parsed > 0 ? parsed : SESSION_END_SETTLE_DELAY_MS;
+    return Math.min(configured, Math.floor(budgetMs * SETTLE_BUDGET_FRACTION));
+}
+/**
+ * The transcript's size after letting a lagging write land.
+ *
+ * Read, wait, read again, and take the LARGER. Growth is the case this exists
+ * for: the first read raced a write in progress, and the second sees the final
+ * turn the first one missed.
+ *
+ * **A SHORTER second read keeps the first.** That is truncation or rotation — a
+ * different and much rarer failure mode, which this task deliberately does not
+ * try to solve; `nextSpan` already resyncs from 0 when the offset sits past EOF,
+ * and `readSpan` already sends only the bytes actually present. Named as a known
+ * gap rather than handled speculatively.
+ *
+ * A `null` second read (the file went away mid-settle) also keeps the first, for
+ * the same reason: what we saw is better evidence than what we can no longer see.
+ */
+export async function settledSize(sizeOf, wait, delayMs) {
+    const first = sizeOf();
+    // Nothing to settle toward — the caller treats null as "do not send", and a
+    // wait would spend budget to learn the same thing again.
+    if (first === null)
+        return null;
+    if (delayMs <= 0)
+        return first;
+    await wait(delayMs);
+    const second = sizeOf();
+    if (second === null)
+        return first;
+    return second > first ? second : first;
+}
+//# sourceMappingURL=session_end.js.map

package/dist/hooks/session_end.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"session_end.js","sourceRoot":"","sources":["../../src/hooks/session_end.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAmCG;AAEH;;;;GAIG;AACH,MAAM,CAAC,MAAM,iBAAiB,GAAG,YAAY,CAAC;AAE9C;;;;;;;;;;;;;;;GAeG;AACH,MAAM,CAAC,MAAM,2BAA2B,GAAG,GAAG,CAAC;AAE/C;;;;;;;;GAQG;AACH,MAAM,CAAC,MAAM,sBAAsB,GAAG,GAAG,CAAC;AAE1C;;;;;;;;;;;;;GAaG;AACH,MAAM,UAAU,aAAa,CAAC,GAAsB,EAAE,QAAgB;IACpE,MAAM,GAAG,GAAG,GAAG,CAAC,gCAAgC,CAAC;IACjD,MAAM,MAAM,GAAG,GAAG,KAAK,SAAS,CAAC,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC,MAAM,CAAC,GAAG,CAAC,CAAC;IACrD,MAAM,UAAU,GACd,MAAM,CAAC,QAAQ,CAAC,MAAM,CAAC,IAAI,MAAM,GAAG,CAAC,CAAC,CAAC,CAAC,MAAM,CAAC,CAAC,CAAC,2BAA2B,CAAC;IAC/E,OAAO,IAAI,CAAC,GAAG,CAAC,UAAU,EAAE,IAAI,CAAC,KAAK,CAAC,QAAQ,GAAG,sBAAsB,CAAC,CAAC,CAAC;AAC7E,CAAC;AAED;;;;;;;;;;;;;;;GAeG;AACH,MAAM,CAAC,KAAK,UAAU,WAAW,CAC/B,MAA2B,EAC3B,IAAmC,EACnC,OAAe;IAEf,MAAM,KAAK,GAAG,MAAM,EAAE,CAAC;IACvB,4EAA4E;IAC5E,yDAAyD;IACzD,IAAI,KAAK,KAAK,IAAI;QAAE,OAAO,IAAI,CAAC;IAChC,IAAI,OAAO,IAAI,CAAC;QAAE,OAAO,KAAK,CAAC;IAE/B,MAAM,IAAI,CAAC,OAAO,CAAC,CAAC;IAEpB,MAAM,MAAM,GAAG,MAAM,EAAE,CAAC;IACxB,IAAI,MAAM,KAAK,IAAI;QAAE,OAAO,KAAK,CAAC;IAClC,OAAO,MAAM,GAAG,KAAK,CAAC,CAAC,CAAC,MAAM,CAAC,CAAC,CAAC,KAAK,CAAC;AACzC,CAAC"}

package/dist/index.d.ts

@@ -0,0 +1,34 @@
+#!/usr/bin/env node
+import { type InvocationMode } from "./exit.js";
+declare const VERBS: readonly ["connect", "status", "off", "why", "report"];
+export type Verb = (typeof VERBS)[number];
+export declare function isVerb(value: string): value is Verb;
+/**
+ * Hook invocations are distinguished by ARGV FIRST, then by env.
+ *
+ * ⚠ `CLAUDE_HOOK_EVENT` is **not** a variable Claude Code sets. The documented
+ * contract puts `hook_event_name` on **stdin JSON**, and the environment carries
+ * `CLAUDE_PROJECT_DIR` / `CLAUDE_PLUGIN_ROOT` — neither of which identifies a
+ * hook event. Keying the mode off that variable alone would make every hook
+ * invocation run in INTERACTIVE mode, which is the shape of a contract test that
+ * passes while testing nothing.
+ *
+ * So the primary signal is the one we control: `CR-028`'s `hooks.json` invokes
+ * `vibecommit hook`. The env var is kept as a secondary because the scaffold
+ * established it and a wrapper may already set it.
+ */
+export declare function invocationMode(env: NodeJS.ProcessEnv, argv: readonly string[]): InvocationMode;
+/**
+ * `--help`, wrapped hard at 80 columns per DESIGN.md §13.4.
+ *
+ * Never reflows to `process.stdout.columns`: identical commands must emit
+ * identical bytes, or issue-paste, screenshots and every golden-file test of the
+ * copy break. `test/help-golden.test.ts` is that golden file.
+ *
+ * No SGR here at all. Colour would have to be resolved before help could be
+ * rendered, and help is the one surface where structure alone is enough —
+ * indentation and the label gutter carry it, which is §13.1's point about
+ * `NO_COLOR` being a lossless degradation rather than a downgrade.
+ */
+export declare function renderHelp(): string;
+export {};

package/dist/index.js

@@ -0,0 +1,360 @@
+#!/usr/bin/env node
+/**
+ * `vibecommit` — CLI entry point.
+ *
+ * Verb bodies that are NOT here, each an owned task in
+ * `coordination/CAPTURE_REFACTOR_TASKS.md`:
+ *
+ *   why  CR-086   report  CR-108   connect's live-capture ending  CR-025
+ *   status/off output spec  CR-021   failure policy  CR-018
+ *   repo binding key + X-Repo-Slug  CR-017 / CR-019
+ *
+ * What IS established here, and must not be undone by those tasks:
+ *   - no user-facing string literal in a command body (CR-090 → `src/copy/`)
+ *   - the exit-code contract is split hook vs interactive (CR-022 → `src/exit.ts`)
+ *   - one commit-header renderer taking the grade (CR-090 → `src/copy/grades.ts`)
+ *   - every escape sequence comes from `src/term.ts` (DESIGN.md §13.2)
+ *   - the hook contract is enforced by the entry, not by each verb
+ */
+import { writeSync } from "node:fs";
+import { homedir } from "node:os";
+import { createInterface } from "node:readline/promises";
+import { resolveAgentId } from "./agents/registry.js";
+import { connect } from "./commands/connect.js";
+import { off, status } from "./commands/status.js";
+import { report } from "./commands/report.js";
+import { why } from "./commands/why.js";
+import { HELP, INTERNAL, USAGE } from "./copy/index.js";
+import { EXIT } from "./exit.js";
+import { runHook } from "./hooks/entry.js";
+import { runPostCommit } from "./hooks/post_commit.js";
+import { runPostRewrite } from "./hooks/post_rewrite.js";
+import { LABEL_GUTTER, renderErrorBlock, resolveColour, wrap } from "./term.js";
+import { CLIENT_VERSION } from "./version.js";
+const VERBS = ["connect", "status", "off", "why", "report"];
+export function isVerb(value) {
+    return VERBS.includes(value);
+}
+/**
+ * Hook invocations are distinguished by ARGV FIRST, then by env.
+ *
+ * ⚠ `CLAUDE_HOOK_EVENT` is **not** a variable Claude Code sets. The documented
+ * contract puts `hook_event_name` on **stdin JSON**, and the environment carries
+ * `CLAUDE_PROJECT_DIR` / `CLAUDE_PLUGIN_ROOT` — neither of which identifies a
+ * hook event. Keying the mode off that variable alone would make every hook
+ * invocation run in INTERACTIVE mode, which is the shape of a contract test that
+ * passes while testing nothing.
+ *
+ * So the primary signal is the one we control: `CR-028`'s `hooks.json` invokes
+ * `vibecommit hook`. The env var is kept as a secondary because the scaffold
+ * established it and a wrapper may already set it.
+ */
+export function invocationMode(env, argv) {
+    if (argv[0] === "hook")
+        return "hook";
+    return env.CLAUDE_HOOK_EVENT ? "hook" : "interactive";
+}
+/**
+ * `--help`, wrapped hard at 80 columns per DESIGN.md §13.4.
+ *
+ * Never reflows to `process.stdout.columns`: identical commands must emit
+ * identical bytes, or issue-paste, screenshots and every golden-file test of the
+ * copy break. `test/help-golden.test.ts` is that golden file.
+ *
+ * No SGR here at all. Colour would have to be resolved before help could be
+ * rendered, and help is the one surface where structure alone is enough —
+ * indentation and the label gutter carry it, which is §13.1's point about
+ * `NO_COLOR` being a lossless degradation rather than a downgrade.
+ */
+export function renderHelp() {
+    const lines = [
+        ...wrap(HELP.tagline, 2),
+        "",
+        ...wrap(`${USAGE.usageLabel} ${HELP.usage}`, 2),
+        "",
+        ...wrap(USAGE.commandsLabel, 2),
+    ];
+    for (const verb of VERBS) {
+        // The description is wrapped on its own and the verb column is written over
+        // the first line's indent. Wrapping `verb + padding + description` as one
+        // string would not work: `wrap` normalises whitespace, so the fixed gutter
+        // would collapse to a single space.
+        const head = `    ${verb.padEnd(LABEL_GUTTER)}`;
+        const body = wrap(HELP.commands[verb], head.length);
+        lines.push(head + body[0].slice(head.length), ...body.slice(1));
+    }
+    lines.push("", ...wrap(`${USAGE.docsLabel} ${HELP.docsUrl}`, 2));
+    return lines.join("\n");
+}
+function interactiveContext(argv) {
+    return {
+        env: process.env,
+        home: homedir(),
+        cwd: process.cwd(),
+        nodeVersion: process.versions.node,
+        // `CR-183`. Resolved from argv HERE, the same pure read the hook branch at
+        // the bottom of this file makes — `connect` needs it to know whether the
+        // agent it was told about has a way to find the running session at all.
+        agentId: resolveAgentId(argv),
+        colour: resolveColour({
+            env: process.env,
+            isTty: process.stdout.isTTY === true,
+            noColorFlag: argv.includes("--no-color"),
+            json: argv.includes("--json"),
+        }),
+        stdinIsTty: process.stdin.isTTY === true,
+        stdout: process.stdout,
+        stderr: process.stderr,
+        /**
+         * The readline interface is created HERE, on the first question, and not
+         * once per invocation — CR-117.
+         *
+         * `createInterface` RESUMES stdin, and a resumed stdin keeps the event loop
+         * alive until it ends. Built eagerly, a verb that returns without ever
+         * prompting sat there until the pipe closed: `connect` refusing a non-TTY,
+         * and `status` / `off`, which never ask anything. On a terminal that looked
+         * fine, because stdin ends at EOF; under `cmd | vibecommit connect` in CI it
+         * is the hang the source finding names first, burning the job's whole
+         * timeout with the refusal already on screen and no way to explain it.
+         *
+         * It also makes style guide §10.2 rule 2 literally true rather than nearly
+         * true: on the refusal path stdin is not read, resumed, or opened at all.
+         */
+        ask: async (question) => {
+            const rl = createInterface({ input: process.stdin, output: process.stdout });
+            try {
+                return await rl.question(question);
+            }
+            finally {
+                rl.close();
+            }
+        },
+        now: () => new Date(),
+        selfPath: process.argv[1] ?? "",
+    };
+}
+async function main(argv) {
+    const [verb] = argv;
+    if (verb === undefined || verb === "--help" || verb === "-h") {
+        process.stdout.write(`${renderHelp()}\n`);
+        return EXIT.ok;
+    }
+    if (verb === "--version" || verb === "-v") {
+        process.stdout.write(`${CLIENT_VERSION}\n`);
+        return EXIT.ok;
+    }
+    if (!isVerb(verb)) {
+        process.stderr.write(`${USAGE.unknownCommand(verb)}\n\n${renderHelp()}\n`);
+        return EXIT.usage;
+    }
+    const ctx = interactiveContext(argv);
+    switch (verb) {
+        case "connect":
+            // `--sign-in` (CR-084d) is a FLAG, not a verb: `VERBS` is what `renderHelp`
+            // iterates, so a sixth verb would move `test/help.golden.txt`, and the
+            // brief for this task is explicit that the golden file must not move.
+            return await connect(ctx, { signIn: argv.includes("--sign-in") });
+        case "status":
+            // `argv.slice(1)` for the same reason `why` and `report` take it: `status`
+            // reads its own `--json` flag rather than this package acquiring an
+            // argument parser it has deliberately never had (DESIGN.md §13.3).
+            return status(ctx, argv.slice(1));
+        case "off":
+            return off(ctx);
+        case "why":
+            // CR-086. `argv.slice(1)` is everything after the verb — there is no
+            // argument parser in this package and `why` does not add one; it reads
+            // `<file>:<line>` and refuses `--json`, which is the smallest shape that
+            // satisfies the verbatim-approved `--help` sentence.
+            return await why(ctx, argv.slice(1));
+        case "report":
+            // CR-108, W10. Same shape as `why`: `argv.slice(1)` is everything after
+            // the verb, and the verb reads its own two flags rather than adding an
+            // argument parser this package deliberately does not have.
+            return await report(ctx, argv.slice(1));
+    }
+}
+function readStdin() {
+    return new Promise((resolve) => {
+        let buf = "";
+        process.stdin.setEncoding("utf8");
+        process.stdin.on("data", (chunk) => {
+            buf += chunk;
+        });
+        process.stdin.on("end", () => resolve(buf));
+        process.stdin.on("error", () => resolve(""));
+    });
+}
+/**
+ * The INTERACTIVE half of the split exit contract — CR-022, D61 round 3 §D8.
+ *
+ * The hook half is enforced in `hooks/entry.ts`: swallow everything, exit 0, stay
+ * silent, because a non-zero hook feeds stderr back into the user's agent and
+ * derails the task they were actually doing. **An interactive verb must not
+ * inherit that blanket.** As originally written the exit-0/stdout-empty rule read
+ * as governing the whole binary, which would make `why` on a read-lane 5xx exit 0
+ * and print nothing — a read verb failing silently, which is the defect this
+ * split exists to prevent.
+ *
+ * So: same fault, same binary, two modes, two behaviours. Interactive gets exit 1
+ * and §13.6's shape.
+ *
+ * Two things this deliberately does NOT do:
+ *   - **No signal handling.** `Ctrl-C` cancelling a `connect` prompt is normal
+ *     CLI behaviour, and suppressing `SIGINT` globally would be a UX regression
+ *     dressed up as a fix. The hook's signal override stays scoped to hook mode.
+ *   - **No stack trace** unless `VIBECOMMIT_DEBUG` is set (§13.6, first
+ *     prohibition). The detail then goes out RAW, after the block, rather than
+ *     through `wrap()`, which would reflow a stack into nonsense.
+ */
+function reportUnexpected(error, argv) {
+    const colour = resolveColour({
+        env: process.env,
+        isTty: process.stderr.isTTY === true,
+        noColorFlag: argv.includes("--no-color"),
+        json: argv.includes("--json"),
+    });
+    const lines = renderErrorBlock({
+        kind: "bad",
+        what: INTERNAL.unexpectedWhat,
+        why: [INTERNAL.unexpectedWhy],
+        fixLabel: INTERNAL.unexpectedFix,
+        fixes: [INTERNAL.unexpectedDebugCommand],
+    }, colour);
+    if (process.env.VIBECOMMIT_DEBUG !== undefined)
+        lines.push("", detailOf(error));
+    // `writeSync(2, …)` rather than `process.stderr.write`: stderr to a pipe is
+    // asynchronous and `process.exit` does not flush it, so the caller below would
+    // race its own diagnostic away. Same reason `finish()` uses it on fd 1.
+    try {
+        writeSync(2, `${lines.join("\n")}\n`);
+    }
+    catch {
+        // An unwritable stderr is not worth a second exception on this path.
+    }
+}
+/**
+ * The raw detail, for `VIBECOMMIT_DEBUG` only.
+ *
+ * Interpolating an error is safe by construction here: an `IngestCredential`
+ * renders `vcik_…redacted` through `toString`, `toJSON` and the inspect hook, so
+ * a stack that embedded one cannot print the plaintext.
+ */
+function detailOf(error) {
+    if (error instanceof Error && typeof error.stack === "string")
+        return error.stack;
+    return String(error);
+}
+/**
+ * Catch what escapes `main()` entirely — a stray timer's throw, a rejection from
+ * a promise nobody awaited. Without these, Node prints its own stack trace to
+ * stderr, which §13.6 forbids outright.
+ *
+ * These force an exit rather than setting `process.exitCode`, because by
+ * definition something unexpected is still in flight and may be holding the event
+ * loop open. The `main()` rejection path below does not: nothing is in flight
+ * there, and letting the loop drain preserves whatever the verb already wrote.
+ */
+function installInteractiveGuards(argv) {
+    const fail = (error) => {
+        reportUnexpected(error, argv);
+        process.exit(EXIT.failure);
+    };
+    process.on("uncaughtException", fail);
+    process.on("unhandledRejection", fail);
+}
+/**
+ * Swallow EPIPE.
+ *
+ * `vibecommit --help | head` closes stdout mid-write, and Node's default for an
+ * unhandled stream error is to print a stack trace and exit non-zero. §13.6
+ * forbids the stack trace outright, and a non-zero exit for an ordinary
+ * `| head` would teach a wrapper script that the command failed.
+ */
+function installPipeGuards() {
+    for (const stream of [process.stdout, process.stderr]) {
+        stream.on("error", (err) => {
+            if (err.code === "EPIPE")
+                process.exit(EXIT.ok);
+        });
+    }
+}
+// Only run when executed as the binary, so tests can import the module freely.
+if (process.argv[1] && import.meta.url === `file://${process.argv[1]}`) {
+    installPipeGuards();
+    const argv = process.argv.slice(2);
+    if (argv[0] === "post-commit") {
+        // ⛔ A HIDDEN VERB, dispatched here rather than through `main`, and NOT in
+        // `VERBS` — `renderHelp` iterates that list, so adding it would move
+        // `test/help.golden.txt` for a verb no human ever types. `hook` is dispatched
+        // the same way, for the same reason.
+        //
+        // It runs inside the user's `git commit`, so it exits 0 unconditionally and
+        // writes nothing to either stream (`hooks/post_commit.ts`).
+        //
+        // ⛔ `env` IS THE LADDER'S FIRST RUNG. Claude Code exports
+        // `CLAUDE_CODE_SESSION_ID` into the Bash tool's environment and git passes it
+        // through to us (`M1`), so the committing session identifies ITSELF instead of
+        // being guessed at by mtime. This is the one place the real environment is
+        // read on this path; everything below takes it as a parameter.
+        process.exit(runPostCommit({ home: homedir(), cwd: process.cwd(), env: process.env }));
+    }
+    if (argv[0] === "post-rewrite") {
+        // The other hidden verb, for the same reason — and it is `post-commit`'s
+        // other half: `--amend` and `rebase` fire `post-commit` for a sha they then
+        // DESTROY (`M5`), and this is the only hook git tells about the pairing.
+        //
+        // ⛔ THE PAIRS ARRIVE ON STDIN, and it is read HERE so `hooks/post_rewrite.ts`
+        // opens nothing — the same seam that keeps every other module in this package
+        // free of a real file descriptor. ⚠ `readStdin` REUSED rather than a second
+        // synchronous reader beside it: it already resolves an `error` to `""`, and
+        // two stdin readers in one file is how the two come to disagree about what an
+        // unreadable stream means. An empty read parses to zero pairs, which is an
+        // ordinary answer rather than a failure.
+        void readStdin().then((stdin) => process.exit(runPostRewrite({
+            home: homedir(),
+            cwd: process.cwd(),
+            env: process.env,
+            // git's own `argv[1]` — `amend` or `rebase`.
+            kind: argv[1] ?? "",
+            stdin,
+        })));
+        // ⛔ `else if` FROM HERE, AND THE BRANCH ABOVE IS WHY. Reading stdin is
+        // asynchronous, so unlike `post-commit` this block RETURNS rather than
+        // exiting — and a plain `if` below would then run `main(["post-rewrite"])`
+        // synchronously, print an unknown-verb error, and put it in the terminal of
+        // someone in the middle of a `git rebase`. The contract this hook is held to
+        // is silence.
+    }
+    else if (invocationMode(process.env, argv) === "hook") {
+        // `runHook` installs the contract guards before it does any work and always
+        // calls `process.exit(0)`. It never returns, so nothing follows it.
+        void runHook({
+            env: process.env,
+            home: homedir(),
+            nodeVersion: process.versions.node,
+            // ⛔ `CR-183` — THE ONE PLACE THE FLAG IS READ ON THIS PATH, and it is read
+            // HERE rather than inside the hook for a structural reason: `runHook` never
+            // receives argv at all, and `parseHookInput` must not select the adapter
+            // because stdin is the input the confinement boundary exists to constrain.
+            // This is the seam that already injects `home` and `nodeVersion`.
+            //
+            // ⚠ Note what the line ABOVE this block does and does not do: resolving an
+            // id is not entering hook mode. `invocationMode` keys on `argv[0]`, so the
+            // registered command MUST lead with the `hook` verb — put the flag first
+            // and this branch is never taken.
+            agentId: resolveAgentId(argv),
+            readStdin,
+        });
+    }
+    else {
+        installInteractiveGuards(argv);
+        void main(argv).then((code) => {
+            process.exitCode = code;
+        }, (error) => {
+            reportUnexpected(error, argv);
+            process.exitCode = EXIT.failure;
+        });
+    }
+}
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

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