@videlic/connect 0.1.2 → 0.1.7

package/hook.mjs

@@ -2,27 +2,55 @@
 // Managed by @videlic/connect — do not edit by hand.
 //
 // Runs as a Claude Code Stop hook (`node videlic-hook.mjs`). Reads the stop
-// event JSON on stdin, resolves the transcript, attaches git metadata, and
-// POSTs to Videlic's /v1/ingest. Cross-platform: pure Node, no bash/jq/curl.
+// event JSON on stdin, resolves the transcript, attaches git metadata, asks
+// `gh` which pull request the branch is on, and POSTs to Videlic's
+// /v1/ingest. Cross-platform: pure Node, no bash/jq/curl.
 //
 // Resilient, like the original shell hook:
 //   • skips sessions that predate install (consent guard),
 //   • tail-truncates transcripts over 8 MB so edge gateways don't 413,
 //   • retries 5xx up to 3× with backoff; gives up on 4xx,
-//   • logs HTTP code + body to ~/.claude/videlic-hook.log on failure.
+//   • logs HTTP code + body to ~/.claude/videlic-hook.log on failure,
+//   • never lets a `gh` that is missing, signed out or offline cost the
+//     session: the body still goes, carrying `pr: null`.
+//
+// One line goes back to the terminal on every stop (`systemMessage`): the
+// link to what was captured, or the one honest sentence about why we could
+// not name the pull request.
 
 import { homedir } from "node:os";
 import { join } from "node:path";
+import { createHash } from "node:crypto";
 import {
+  accessSync,
+  constants,
   existsSync,
   readFileSync,
+  readdirSync,
+  mkdirSync,
   statSync,
   openSync,
   readSync,
   closeSync,
   appendFileSync,
+  writeFileSync,
+  unlinkSync,
 } from "node:fs";
-import { execFileSync } from "node:child_process";
+import { execFileSync, spawn } from "node:child_process";
+
+/**
+ * The version of the hook that COMPOSED this body — not what was installed.
+ * It lives here, in the file that does the composing, because that is the
+ * only claim it can honestly make: `install.mjs` copies this file verbatim
+ * (`copyFileSync`), so a machine can be running a hook months older than the
+ * package that put it there, and a version read from `package.json` at
+ * install time would describe the installer instead of the sender.
+ *
+ * `hook.test.mjs` holds it equal to `package.json`, so publishing a changed
+ * hook under an unchanged version fails the test rather than the fleet
+ * measurement.
+ */
+const CLIENT_VERSION = "0.1.7";
 
 const claudeDir = join(homedir(), ".claude");
 const logPath = join(claudeDir, "videlic-hook.log");
@@ -36,6 +64,138 @@ const log = (m) => {
 
 const MAX_BYTES = 8_000_000;
 
+/**
+ * The server's own shape for a client-reported pull request
+ * (`ingest.ts` `clientPrSchema`), mirrored here on purpose.
+ *
+ * Zod rejects the WHOLE body when one of these is off — a GitHub Enterprise
+ * URL, a SHA-256 head, a `state` word we did not expect — and a 400 loses the
+ * session, not just the pull request. So everything `gh` answers is measured
+ * against the server's limits before it is allowed near the wire, and
+ * anything that does not fit becomes `pr: null`: the capture always survives.
+ */
+const PR_URL = /^https:\/\/github\.com\/([^/\s]+\/[^/\s]+)\/pull\/(\d+)\/?$/;
+const PR_SHA = /^[a-f0-9]{7,64}$/;
+const PR_STATES = new Set(["OPEN", "CLOSED", "MERGED"]);
+const PR_URL_MAX = 500;
+const PR_REPO_MAX = 200;
+const PR_BASE_BRANCH_MAX = 256;
+
+/**
+ * `gh` has no `baseRepository` field (measured on gh 2.89), so the repository
+ * a pull request LIVES in is read off its URL — which is the base repository
+ * on a fork pull request too. `headRefName` is here only to check that a pull
+ * request found through the session's own `gh pr create` receipt really is
+ * this branch's.
+ */
+const GH_FIELDS = "number,url,isDraft,state,headRefOid,baseRefName,headRefName,headRepository,headRepositoryOwner";
+/**
+ * `gh pr view` measured at 0.53-0.65 s on a warm cache. The ceiling matters
+ * because a stop hook HOLDS THE DEVELOPER'S TERMINAL while it runs, and that —
+ * not the agent's own patience — is the budget worth defending: a `gh` whose
+ * HTTPS call blackholes (captive portal, VPN drop, proxy) would otherwise eat
+ * the time the upload needs.
+ *
+ * The agent's patience was written here as 60 s and that was wrong. Measured
+ * on Claude Code 2.1.220, two ways that agree: a hook that sleeps 65 s runs to
+ * completion, one that sleeps 620 s is killed at 601 s, and the binary's own
+ * constant is 600 000 ms for `Stop`/`SubagentStop` alike. A per-hook `timeout`
+ * in `settings.json` overrides it and is in SECONDS — a hook declared
+ * `timeout: 5` was killed at 5 s. (`SessionEnd` is the exception and is not
+ * ours: 1 500 ms by default, capped at 60 000 ms.)
+ *
+ * Ten minutes of rope is not permission to take it. The number that bounds
+ * this file is the terminal's, and it stays where it is.
+ */
+const GH_TIMEOUT_MS = 12_000;
+
+/**
+ * The environment `gh` is asked in. Three of these repair an answer the hook
+ * could not read, and one takes back a question it never meant to ask.
+ *
+ * `CLICOLOR_FORCE` is the one that bites: on gh 2.89 it beats BOTH `NO_COLOR`
+ * and `GH_NO_COLOR`, and `--json` output then arrives as pretty-printed ANSI
+ * that `JSON.parse` throws on — measured. A developer with `CLICOLOR_FORCE=1`
+ * in their shell profile (a common line for forcing colour through pipes)
+ * would silently never have a pull request found, on any stop, forever.
+ *
+ * `GH_REPO` is deleted, not overridden: it makes gh answer about a repository
+ * the session was never in (measured), and the whole point of this call is
+ * "the pull request of THIS branch, in THIS clone".
+ */
+function ghEnv() {
+  const env = {
+    ...process.env,
+    GH_PAGER: "",
+    GH_PROMPT_DISABLED: "1",
+    GH_NO_UPDATE_NOTIFIER: "1",
+    NO_COLOR: "1",
+    GH_NO_COLOR: "1",
+    CLICOLOR_FORCE: "0",
+    FORCE_COLOR: "0",
+  };
+  delete env.GH_REPO;
+  return env;
+}
+
+/**
+ * The two provenances this client can stamp (`PR_SOURCES` on the server).
+ * Named once so the wire test can hold them against the server's enum
+ * instead of against a string typed twice.
+ */
+const PR_SOURCE = { view: "gh-pr-view", receipt: "gh-pr-create-output" };
+
+/**
+ * The two provenances the CATCH-UP can stamp (`CATCH_UP_PR_SOURCES` on the
+ * server). A separate map from `PR_SOURCE` on purpose: these describe a
+ * question asked on a LATER stop, about a session that already uploaded, and
+ * `/v1/ingest` must refuse them exactly as `/v1/catch-up` refuses the other
+ * three. The wire test holds both enums apart in both directions.
+ */
+const CATCH_UP_SOURCE = { sha: "gh-pr-list-sha", again: "gh-pr-view-again" };
+
+/**
+ * The absolute path of a tool, resolved from PATH here rather than handed to
+ * the OS as a bare name.
+ *
+ * On Windows libuv looks for the executable in the CHILD's working directory
+ * before it scans PATH. This hook runs `gh` with the repository root as that
+ * directory, and `git` with whatever directory the agent started it in — so a
+ * file named `gh.exe` or `git.exe` committed to a repository would be what
+ * runs, at the end of every session, on the machine of everyone who cloned
+ * it. Resolving the name ourselves takes that decision away from the
+ * directory. Only real executables count: `.cmd` and `.bat` shims cannot be
+ * spawned without a shell, and this hook never runs one.
+ */
+function resolveTool(name) {
+  const isWindows = process.platform === "win32";
+  const dirs = (process.env.PATH || "").split(isWindows ? ";" : ":");
+  const exts = isWindows ? [".exe", ".com"] : [""];
+  for (const raw of dirs) {
+    const dir = raw.replace(/^"|"$/g, "").trim();
+    if (!dir) continue;
+    for (const ext of exts) {
+      const candidate = join(dir, `${name}${ext}`);
+      try {
+        // Executable, not merely present: `execvp` — which is what a bare
+        // name used to be resolved by — remembers a file it may not run and
+        // keeps scanning. A mode-644 `git` left in an early PATH entry (a zip
+        // extraction, a COPY without the bit) must not become a hard stop
+        // where the developer's own shell walks straight past it.
+        if (statSync(candidate).isFile()) {
+          accessSync(candidate, constants.X_OK);
+          return candidate;
+        }
+      } catch {
+        /* gone, unreadable, a directory, or not ours to run — keep looking */
+      }
+    }
+  }
+  return null;
+}
+/** `terminal` surface profile (spec §4.7): one line, no paths, no quotes, lead capped. */
+const TERMINAL_LEAD_CAP = 100;
+
 function readConfig() {
   const p = join(claudeDir, "videlic.json");
   if (!existsSync(p)) return null;
@@ -86,11 +246,17 @@ function readTail(path, maxBytes) {
 }
 
 function gitMeta(cwd) {
-  const out = { branch: "", commitSha: "", repoUrl: "" };
+  const out = { branch: "", commitSha: "", repoUrl: "", root: "" };
   if (!cwd) return out;
+  // No fallback to the bare name: handing "git" to the OS is the Windows
+  // cwd-search hazard this resolver exists to close, and a `git` that PATH
+  // cannot name is one `execvp` could not have found either. Without it the
+  // session still uploads — it simply carries no branch.
+  const gitBin = resolveTool("git");
+  if (!gitBin) return out;
   const git = (args) => {
     try {
-      return execFileSync("git", ["-C", cwd, ...args], {
+      return execFileSync(gitBin, ["-C", cwd, ...args], {
         stdio: ["ignore", "pipe", "ignore"],
       })
         .toString()
@@ -103,10 +269,1188 @@ function gitMeta(cwd) {
     out.branch = git(["rev-parse", "--abbrev-ref", "HEAD"]);
     out.commitSha = git(["rev-parse", "HEAD"]);
     out.repoUrl = git(["config", "--get", "remote.origin.url"]);
+    // The working tree's root, not the agent's cwd: a session that ran in a
+    // subdirectory is still the same repository, and every later command
+    // should be asked from one place.
+    out.root = git(["rev-parse", "--show-toplevel"]) || cwd;
   }
   return out;
 }
 
+/**
+ * What went wrong when `gh` did not answer with a pull request. Exit codes
+ * alone cannot tell these apart — everything but "not authenticated" (4)
+ * exits 1 — so the text `gh` printed decides, and anything unrecognised stays
+ * `gh-failed` rather than being read as "there is no pull request".
+ */
+function ghFailureKind(err) {
+  if (err?.code === "ENOENT") return "gh-missing";
+  if (err?.signal || err?.killed) return "timeout";
+  const text = `${err?.stderr ?? ""}${err?.stdout ?? ""}${err?.message ?? ""}`;
+  if (/no pull requests found/i.test(text)) return "no-pr";
+  // Measured on gh 2.89: "none of the git remotes configured for this
+  // repository point to a known GitHub host. To tell gh about a new GitHub
+  // host, please use `gh auth login`" — the words of the auth test are inside
+  // the message for a repository that is simply not on GitHub, and reading it
+  // as "signed out" told an authenticated developer to log in on every stop.
+  if (/point to a known GitHub host|no git remotes found/i.test(text)) return "not-github";
+  if (/not on any branch|could not determine current branch/i.test(text)) return "no-branch";
+  if (/not a git repository/i.test(text)) return "no-repo";
+  if (err?.status === 4 || /gh auth login|HTTP 401/i.test(text)) return "gh-signed-out";
+  if (
+    /dial tcp|no such host|connection refused|network is unreachable|i\/o timeout|TLS handshake|context deadline exceeded|EOF$/im.test(
+      text,
+    )
+  ) {
+    return "offline";
+  }
+  return "gh-failed";
+}
+
+/**
+ * Runs one `gh` subcommand in `dir`, asking for `GH_FIELDS`, and parses its
+ * JSON. Never throws.
+ *
+ * One body for both questions this hook asks. `gh pr view` and `gh pr list`
+ * differ only in the words before `--json`, and everything around them —
+ * resolving the executable off PATH ourselves, the environment repairs in
+ * `ghEnv()`, the timeout, reading stderr so `ghFailureKind` has text to read —
+ * is the part that must never drift between the two. A second copy is how
+ * `CLICOLOR_FORCE=0` ends up on one spawn and not the other.
+ */
+function ghJson(dir, args, timeoutMs = GH_TIMEOUT_MS) {
+  const gh = resolveTool("gh");
+  if (!gh) return { ok: false, kind: "gh-missing" };
+  let raw;
+  try {
+    raw = execFileSync(gh, [...args, "--json", GH_FIELDS], {
+      cwd: dir,
+      stdio: ["ignore", "pipe", "pipe"],
+      timeout: timeoutMs,
+      encoding: "utf8",
+      env: ghEnv(),
+    });
+  } catch (err) {
+    return { ok: false, kind: ghFailureKind(err) };
+  }
+  try {
+    return { ok: true, json: JSON.parse(raw) };
+  } catch {
+    return { ok: false, kind: "gh-failed" };
+  }
+}
+
+/** `gh pr view` — one pull request, by branch or by number. */
+function ghPrView(dir, args, timeoutMs = GH_TIMEOUT_MS) {
+  return ghJson(dir, ["pr", "view", ...args], timeoutMs);
+}
+
+/**
+ * `gh pr list --search` — every pull request GitHub matches, as an array.
+ *
+ * Two things measured on gh 2.89 shape this call, and both are written out
+ * rather than left to a default:
+ *
+ *   `--state all`, because the default is `open`: without it a pull request
+ *   merged between two stops reads as "no match", and the ledger entry would
+ *   wait out its fourteen days instead of closing honestly.
+ *
+ *   `--limit`, so the ceiling is a fact in this file rather than whatever gh
+ *   ships.
+ *
+ * And `--repo` is never passed: gh pins the search to the base repository it
+ * resolved from the remotes, and overriding that is how a question about THIS
+ * clone becomes a question about someone else's.
+ *
+ * `{ ok: true, list: [] }` — "gh answered, nothing matched" — is a real answer
+ * and not a failure; it is what most catch-up asks see.
+ */
+function ghPrList(dir, search, limit, timeoutMs = GH_TIMEOUT_MS) {
+  const got = ghJson(dir, ["pr", "list", "--state", "all", "--search", search, "--limit", String(limit)], timeoutMs);
+  if (!got.ok) return got;
+  return { ok: true, list: Array.isArray(got.json) ? got.json : [] };
+}
+
+/**
+ * `gh pr view --json …` → the body's `pr`, or null when any part of it would
+ * not survive the server's schema. Total: every rejection is a `pr: null`,
+ * never a thrown hook and never a half-filled object.
+ */
+function toWirePr(json) {
+  if (!json || typeof json !== "object") return null;
+  const url = typeof json.url === "string" ? json.url.trim() : "";
+  if (url.length > PR_URL_MAX) return null;
+  const m = PR_URL.exec(url);
+  if (!m) return null; // not github.com — GitHub Enterprise has no address here yet
+  const repo = m[1];
+  if (repo.length < 3 || repo.length > PR_REPO_MAX) return null;
+  const number = typeof json.number === "number" ? json.number : Number.NaN;
+  if (!Number.isInteger(number) || number <= 0 || Number(m[2]) !== number) return null;
+  const headSha = typeof json.headRefOid === "string" ? json.headRefOid.trim().toLowerCase() : "";
+  if (!PR_SHA.test(headSha)) return null;
+  const state = typeof json.state === "string" ? json.state.trim() : "";
+  if (!PR_STATES.has(state)) return null;
+  if (typeof json.isDraft !== "boolean") return null;
+  const pr = {
+    number,
+    url: url.replace(/\/$/, ""),
+    draft: json.isDraft,
+    state,
+    headSha,
+    repo,
+  };
+  const baseBranch = typeof json.baseRefName === "string" ? json.baseRefName.trim() : "";
+  // Optional on the wire: send it only when it is a branch name we actually read.
+  if (baseBranch && baseBranch.length <= PR_BASE_BRANCH_MAX) pr.baseBranch = baseBranch;
+  return pr;
+}
+
+/**
+ * The one pull request this session's own transcript proves exists: the
+ * receipt Claude Code files for a `gh pr create` that succeeded
+ * (`toolUseResult.gitOperation.pr`), or, for clients that file no receipt,
+ * the URL such a command printed on stdout.
+ *
+ * Owner decision D25: a number may come from `gh pr view` or from this
+ * session's `gh pr create` — never from a URL someone merely wrote. Measured
+ * on 110 local transcripts: 71 name a pull request, 70 of them through a
+ * receipt; the single prose-only URL was a pull request in a DIFFERENT
+ * repository quoted in a user's message, which is exactly the wrong link this
+ * rule refuses to make.
+ *
+ * `action` must be `created`: the same receipt shape is filed for
+ * `gh pr close` and `gh pr edit` (1 and 2 of the 23 in that corpus), and
+ * those say nothing about the branch this stop is on.
+ */
+function prFromSessionReceipt(sessionData) {
+  if (typeof sessionData !== "string" || !sessionData) return null;
+  const commands = new Map();
+  let fromReceipt = null;
+  let fromStdout = null;
+  for (const line of sessionData.split("\n")) {
+    // Cheap prefilter: JSON.parse over an 8 MB transcript is the expensive
+    // part, and only these three kinds of line can carry a receipt.
+    if (
+      !line ||
+      (!line.includes('"gitOperation"') && !line.includes("/pull/") && !line.includes("pr create"))
+    ) {
+      continue;
+    }
+    let entry;
+    try {
+      entry = JSON.parse(line);
+    } catch {
+      continue; // a tail-truncated transcript starts mid-object
+    }
+    const receipt = entry?.toolUseResult?.gitOperation?.pr;
+    if (receipt && receipt.action === "created") {
+      const parsed = parsePrUrl(receipt.url);
+      if (parsed && (typeof receipt.number !== "number" || receipt.number === parsed.number)) {
+        fromReceipt = parsed;
+      }
+    }
+    const content = entry?.message?.content;
+    if (!Array.isArray(content)) continue;
+    for (const block of content) {
+      if (block?.type === "tool_use" && typeof block.id === "string") {
+        const command = typeof block.input?.command === "string" ? block.input.command : "";
+        if (command) commands.set(block.id, command);
+      }
+      if (block?.type === "tool_result" && block.is_error !== true) {
+        if (!invokesPrCreate(commands.get(block.tool_use_id) || "")) continue;
+        const text =
+          typeof block.content === "string"
+            ? block.content
+            : Array.isArray(block.content)
+              ? block.content.map((c) => (typeof c?.text === "string" ? c.text : "")).join("\n")
+              : "";
+        // A successful `gh pr create` prints ONE address and nothing else.
+        // Anything longer is a command that did more than create — a list, a
+        // loop that opened several, a script that printed a link it read
+        // somewhere — and a number taken from the first URL in such output is
+        // exactly the borrowed link this rule exists to refuse.
+        const printed = parsePrUrl(text.trim());
+        if (printed) fromStdout = printed;
+      }
+    }
+  }
+  // The structured receipt is Claude Code's own record of what the command
+  // did; the printed line is a reading of what it said. When both exist they
+  // are on the SAME transcript entry, so the reading must never be allowed to
+  // overwrite the record.
+  return fromReceipt ?? fromStdout;
+}
+
+/**
+ * Whether a Bash command actually RUNS `gh pr create`, rather than merely
+ * containing those words.
+ *
+ * A substring test matched `grep -rn "gh pr create" …`, a `node -e` scan over
+ * transcripts, and a heredoc writing this very file — all of which print pull
+ * request URLs that belong to someone else's work. So each segment of the
+ * command line is checked for `gh` in the position a command name occupies,
+ * with `pr create` among its arguments.
+ */
+function invokesPrCreate(command, depth = 0) {
+  if (!command || depth > 2) return false;
+  // `$(…)` and backticks open a new command; a quote does not, or
+  // `grep "gh pr create"` would read as an invocation of gh.
+  for (const segment of command.split(/\n|&&|\|\||;|\||\$\(|`/)) {
+    const tokens = segment.trim().split(/\s+/).filter(Boolean);
+    let i = 0;
+    // Leading environment assignments and the wrappers that keep a command a
+    // command: `GH_TOKEN=… sudo command gh pr create …`.
+    while (i < tokens.length && (/^[A-Za-z_][A-Za-z0-9_]*=/.test(tokens[i]) || /^(sudo|command|env)$/.test(tokens[i]))) i++;
+    const name = (tokens[i] ?? "").replace(/^["']|["']$/g, "");
+    if (!name) continue;
+    // A shell told to run a command line: look inside the line, not at the
+    // shell. `grep`, `rg` and `node -e` are not shells, so what they were
+    // handed stays a string.
+    if (/(^|[\\/])(ba|z|k|da)?sh$/.test(name)) {
+      const flag = tokens.indexOf("-c", i) >= 0 ? tokens.indexOf("-c", i) : tokens.findIndex((t, j) => j > i && /^-[a-z]*c$/.test(t));
+      if (flag > 0 && invokesPrCreate(tokens.slice(flag + 1).join(" ").replace(/^["']|["']$/g, ""), depth + 1)) return true;
+      continue;
+    }
+    if (!/(^|[\\/])gh(\.exe)?$/.test(name)) continue;
+    // `pr` next to `create`, so gh's own global flags (`gh --repo x pr
+    // create`) do not hide the subcommand.
+    const args = tokens.slice(i + 1).filter((t) => !t.startsWith("-"));
+    if (args.some((t, j) => t === "pr" && args[j + 1] === "create")) return true;
+  }
+  return false;
+}
+
+function parsePrUrl(url) {
+  if (typeof url !== "string") return null;
+  const m = PR_URL.exec(url.trim());
+  if (!m) return null;
+  return { number: Number(m[2]), repo: m[1] };
+}
+
+/**
+ * Whether GitHub says this pull request's head IS the branch the stop is on.
+ *
+ * The local branch NAME, and nothing else. An earlier version also accepted
+ * `branch.<name>.merge`, thinking of a branch pushed under another name — but
+ * that config holds the branch's UPSTREAM, which for `git checkout -b next
+ * origin/parent` is the parent. It would have let a session on a fresh branch
+ * be filed under the pull request of the branch it forked from.
+ */
+function headIsThisBranch(json, branch) {
+  const head = typeof json?.headRefName === "string" ? json.headRefName : "";
+  return !!head && head === branch;
+}
+
+/** `owner/name` of a git remote, however it is spelled. */
+function repoFromRemote(url) {
+  if (typeof url !== "string") return "";
+  const m = /[:/]([^/\s:]+)\/([^/\s]+?)(?:\.git)?\/?$/.exec(url.trim());
+  return m ? `${m[1]}/${m[2]}` : "";
+}
+
+/**
+ * Where GitHub says this pull request's head lives, compared with the clone
+ * this stop happened in: `"yes"`, `"no"`, or `"cannot-tell"`.
+ *
+ * The branch NAME alone is not enough: a session that opened a pull request
+ * in one repository and stopped in another, on a branch of a name both share
+ * (`main`, `dev`, `patch-1`), would file its work under the other's number.
+ * On a fork pull request the base repository is the parent and the head is
+ * the fork — the clone — so this compares the head, not the base.
+ *
+ * `"cannot-tell"` is a real third answer and is kept apart from `"yes"` on
+ * purpose. This clone's own name is read from `remote.origin.url` alone, and a
+ * checkout made as `git clone -o upstream …` has no `origin` at all — so the
+ * comparison has nothing on OUR side, not merely nothing on GitHub's. A caller
+ * that treats that as "yes" is claiming ownership it never established; the
+ * catch-up's search path therefore demands the commit proof outright when the
+ * answer is `"cannot-tell"`, instead of accepting an abstention from it too.
+ */
+function headClone(json, repoUrl) {
+  const mine = repoFromRemote(repoUrl);
+  const head =
+    typeof json?.headRepository?.nameWithOwner === "string"
+      ? json.headRepository.nameWithOwner
+      : typeof json?.headRepositoryOwner?.login === "string" && typeof json?.headRepository?.name === "string"
+        ? `${json.headRepositoryOwner.login}/${json.headRepository.name}`
+        : "";
+  if (!mine || !head) return "cannot-tell";
+  return mine.toLowerCase() === head.toLowerCase() ? "yes" : "no";
+}
+
+/**
+ * The receipt path's question: is this pull request's head NOT this clone's?
+ * Abstains towards accepting, because there the pull request was named by the
+ * session's own `gh pr create` and the clone check is corroboration.
+ */
+function headIsInThisClone(json, repoUrl) {
+  return headClone(json, repoUrl) !== "no";
+}
+
+/**
+ * Which pull request this session is on, and how we learned it.
+ *
+ * `gh pr view` first, because it answers about the branch as it is NOW —
+ * draft flipped, closed, merged, head moved. Measured on a fork clone with
+ * two remotes (`origin` = fork, `upstream` = parent) and no
+ * `gh repo set-default`: gh picks the base repository by REMOTE NAME
+ * (`upstream` > `github` > `origin`), without prompting and without an error,
+ * so a pull request that lives in the fork becomes invisible to the branch
+ * query. That measured hole is the one the session's own `gh pr create`
+ * receipt closes — and it closes it by asking `gh` again, by number, so
+ * `draft`, `state` and `headSha` are still GitHub's answer and never a guess
+ * carried over from when the command ran.
+ *
+ * ONE failure earns that second question: "no pull request for this branch in
+ * the repository I picked". Every other answer — gh missing, signed out,
+ * unreachable, timed out, unreadable — would fail again the same way, and the
+ * stop hook would pay the same wait twice for nothing: two blocking calls of
+ * ${GH_TIMEOUT_MS} ms each, in front of an upload the agent gives 60 s to.
+ */
+function findPullRequest(dir, branch, repoUrl, readSessionData) {
+  if (!dir || !branch || branch === "HEAD") return { pr: null, source: null, gap: "no-branch" };
+
+  const started = Date.now();
+  const viewed = ghPrView(dir, []);
+  if (viewed.ok) {
+    const pr = toWirePr(viewed.json);
+    if (pr) return { pr, source: PR_SOURCE.view, gap: null };
+    return { pr: null, source: null, gap: "unusable" };
+  }
+  if (viewed.kind !== "no-pr") return { pr: null, source: null, gap: viewed.kind };
+
+  const receipt = prFromSessionReceipt(readSessionData());
+  if (!receipt) return { pr: null, source: null, gap: viewed.kind };
+
+  // The host is pinned to the one the receipt's address has: `--repo
+  // owner/name` alone would be resolved against GH_HOST, and a repository of
+  // the same name on another host is not this one.
+  const left = Math.max(2_000, GH_TIMEOUT_MS - (Date.now() - started));
+  const byNumber = ghPrView(dir, [String(receipt.number), "--repo", `github.com/${receipt.repo}`], left);
+  if (!byNumber.ok) return { pr: null, source: null, gap: viewed.kind };
+  const pr = toWirePr(byNumber.json);
+  if (!pr || pr.number !== receipt.number || pr.repo !== receipt.repo) {
+    return { pr: null, source: null, gap: viewed.kind };
+  }
+  // The receipt names a pull request, not a branch: attach it only when
+  // GitHub says its head is the branch this stop is on. A session that opened
+  // one and moved on would otherwise file its work under the other's number.
+  if (!headIsThisBranch(byNumber.json, branch) || !headIsInThisClone(byNumber.json, repoUrl)) {
+    return { pr: null, source: null, gap: "receipt-other-branch" };
+  }
+  return { pr, source: PR_SOURCE.receipt, gap: null };
+}
+
+/**
+ * Does this pull request ask for a review? The client's mirror of the server's
+ * `shouldAnalyzeFromIngest` — OPEN and not a draft, and nothing else.
+ *
+ * Named, rather than written out at each of the three places that need it,
+ * because it is a mirror: an unnamed copy of somebody else's rule is the thing
+ * that drifts. The server still asks its own question on every path; this one
+ * only decides whether the hook is going to bother asking.
+ */
+function asksForReview(pr) {
+  return !!pr && pr.draft === false && pr.state === "OPEN";
+}
+
+/**
+ * Does the pull request whose head is `headSha` actually CONTAIN `sha`?
+ *
+ * `gh pr list --search` is free text, not a `sha:` qualifier — measured: a
+ * search for `ENG-82` returns the pull request whose TITLE says so, and a
+ * forty-hex sha quoted in a title or a body matches exactly the same way. So
+ * the search is a candidate generator and never a proof, and this is the
+ * proof, taken from the clone we are standing in.
+ *
+ * `git merge-base --is-ancestor A B` — measured in this repository: 0 when A
+ * is an ancestor of B (a commit is its own ancestor, so 0 for A === B), 1 when
+ * it is not, 128 when either object is missing locally. Only 1 is a refusal.
+ * 128 is an ABSTENTION — a fork's head, or a branch this clone never fetched,
+ * is not a wrong answer, it is no answer — and the caller keeps whatever the
+ * other guards decided rather than treating "I cannot see it" as "it is not
+ * there".
+ */
+function containsCommit(dir, sha, headSha) {
+  const gitBin = resolveTool("git");
+  if (!gitBin || !dir || !sha || !headSha) return null;
+  try {
+    execFileSync(gitBin, ["-C", dir, "merge-base", "--is-ancestor", sha, headSha], {
+      stdio: ["ignore", "ignore", "ignore"],
+      timeout: 5_000,
+    });
+    return true;
+  } catch (err) {
+    return err?.status === 1 ? false : null;
+  }
+}
+
+/**
+ * ─────────────────────────── THE CATCH-UP LEDGER ───────────────────────────
+ *
+ * A session whose stop found no pull request asking for a review leaves one
+ * small file here. On any LATER stop in the same repository, the hook asks gh
+ * about one of them, and if gh names a pull request that is provably this
+ * session's, tells the server (`POST /v1/catch-up`).
+ *
+ * That covers the three shapes a stop-time answer cannot: a pull request
+ * opened by hand afterwards, a draft marked ready later, and a branch re-used
+ * for different work — which must never be mixed in, and is not, because the
+ * question asked is "which pull request contains MY commit" rather than "what
+ * is on this branch now".
+ *
+ * NO TIMER AND NO DAEMON. The trigger is a later run of this same hook, which
+ * is the honest cost of the design: a session in a repository the developer
+ * never opens again is never caught up.
+ *
+ * ONE FILE PER ENTRY, never a shared list. An enrolment is an exclusive
+ * create, an update is a whole small overwrite, a close is an unlink — so
+ * there is no read-modify-write for two agents stopping at the same second to
+ * lose an update in, and no half-written shared file to parse.
+ */
+const LEDGER_DIR = join(claudeDir, "videlic-catchup");
+/**
+ * An entry may not outlive the row it names: the server hard-deletes a
+ * pending, pull-request-less capture after fourteen days
+ * (`ORPHAN_CAPTURE_TTL_DAYS`), and past that the claim has no subject.
+ */
+const LEDGER_TTL_MS = 14 * 24 * 60 * 60 * 1000;
+/** Across all repositories. Oldest go first when a new one arrives. */
+const LEDGER_MAX_ENTRIES = 64;
+/** Names read in one pass, however many are on disk — a bound on the work, not on the ledger. */
+const LEDGER_SCAN_CAP = 256;
+/** How long one entry waits between asks. */
+const CATCH_UP_COOLDOWN_MS = 10 * 60 * 1000;
+/** One ceiling for the gh call and the POST together — the tail this pass adds to a stop. */
+const CATCH_UP_BUDGET_MS = 12_000;
+/** Written out so the ceiling is a fact in this file rather than whatever gh's default happens to be. */
+const CATCH_UP_SEARCH_LIMIT = 30;
+/**
+ * A session on the trunk has no "this branch's pull request" to wait for. An
+ * enrolment filter for cost, not a correctness guard — correctness is the head
+ * branch check — and the same two names `findPrOwnerOnBranch` already refuses.
+ */
+const TRUNK_BRANCHES = new Set(["main", "master"]);
+/**
+ * Server answers that can change by asking again, matched by PREFIX.
+ *
+ * The prefix is not decoration: `reanalyzeSession` templates two of its reasons
+ * with the provider's own message (`download-failed: 502 Bad Gateway`), so an
+ * exact-match set could never hold them — and a single Supabase Storage blip,
+ * which this codebase has measured at 1 upload in 611, would otherwise close
+ * the entry for good. That is the worst shape in the whole pass: the route has
+ * already settled the row as failed with the Re-analyze control withheld, so
+ * the one mechanism that could still have retried would have just deleted
+ * itself.
+ *
+ * `session-not-found` is here for the same reason. This route fetched that row
+ * two calls earlier, so a later "not found" is a swallowed database error, not
+ * a deleted session — and if the session really was pruned, the entry simply
+ * ages out on the fourteen days it shares with the server's own orphan sweep.
+ *
+ * Everything else the server says about a claim is final, and the entry closes:
+ * it is an answer, not a failure to answer.
+ */
+const CATCH_UP_TRANSIENT_REASONS = ["storage-disabled", "pull-request-not-ready", "session-not-found", "download-failed"];
+
+function isTransientReason(reason) {
+  return CATCH_UP_TRANSIENT_REASONS.some((r) => reason === r || reason.startsWith(`${r}:`));
+}
+
+/**
+ * This stop's own answer from `gh`, when it means gh cannot answer a SECOND
+ * question either.
+ *
+ * `findPullRequest` already refuses to ask gh twice for exactly this reason —
+ * "two blocking calls of ${GH_TIMEOUT_MS} ms each, in front of an upload the
+ * agent gives 60 s to" — and the catch-up would have re-introduced that second
+ * call through a different function. On a machine where github.com blackholes,
+ * every stop would have held the terminal for twice the timeout, every ten
+ * minutes, for fourteen days.
+ *
+ * `no-pr`, `no-branch`, `unusable` and `receipt-other-branch` are NOT here:
+ * each is an answer ABOUT THIS BRANCH and says nothing about whether gh can
+ * answer a question about a commit.
+ */
+const GH_CANNOT_ANSWER = new Set(["gh-missing", "gh-signed-out", "offline", "timeout", "gh-failed", "not-github", "no-repo"]);
+
+/**
+ * One spelling per repository. The root always comes from
+ * `git rev-parse --show-toplevel`, never the stop payload's `cwd`, so both
+ * sides of the comparison are answered by the same command — on macOS those
+ * two differ (`/var/folders/…` against `/private/var/folders/…`) and a
+ * repository would alias itself.
+ */
+function normalizeRoot(root) {
+  let s = String(root).replace(/\\/g, "/").replace(/\/+$/, "");
+  // The two platforms whose filesystems are case-insensitive by default.
+  if (process.platform === "win32" || process.platform === "darwin") s = s.toLowerCase();
+  return s;
+}
+
+/** The repository, as a name: the hash, so the ledger's file names leak no directory layout. */
+function rootHash(root) {
+  return createHash("sha256").update(normalizeRoot(root)).digest("hex").slice(0, 12);
+}
+
+/**
+ * One entry per SESSION, so a second pull-request-less stop of the same
+ * session refreshes its own entry instead of enrolling a rival carrying a
+ * different commit. Identity is always read from the file's CONTENT, never
+ * from its name.
+ */
+function ledgerPath(root, sessionPublicId) {
+  return join(LEDGER_DIR, `${rootHash(root)}-${sessionPublicId}.json`);
+}
+
+/** Best-effort, like `log()`: the ledger is a convenience and never a reason to fail a stop. */
+function ledgerWrite(path, entry) {
+  try {
+    mkdirSync(LEDGER_DIR, { recursive: true, mode: 0o700 });
+    writeFileSync(path, JSON.stringify(entry), { mode: 0o600 });
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+function ledgerClose(path) {
+  try {
+    unlinkSync(path);
+  } catch {
+    /* already gone, or a directory we may not write — either way there is nothing to do */
+  }
+}
+
+function ledgerRead(path) {
+  try {
+    const entry = JSON.parse(readFileSync(path, "utf8"));
+    // A file we cannot recognise is not an entry. Anything that reached this
+    // directory by another route must never become a claim.
+    if (entry?.v !== 1 || typeof entry.session !== "string" || typeof entry.branch !== "string") return null;
+    if (typeof entry.at !== "number") return null;
+    return entry;
+  } catch {
+    return null;
+  }
+}
+
+/** Every entry on disk, newest-enrolled last. Never throws. */
+function ledgerList() {
+  let names;
+  try {
+    names = readdirSync(LEDGER_DIR);
+  } catch {
+    return [];
+  }
+  const out = [];
+  for (const name of names.slice(0, LEDGER_SCAN_CAP)) {
+    if (!name.endsWith(".json")) continue;
+    const path = join(LEDGER_DIR, name);
+    const entry = ledgerRead(path);
+    if (entry) {
+      out.push({ path, entry, name });
+      continue;
+    }
+    // A file we cannot read is NOT deleted on sight, and that is the whole
+    // reason it is not: `writeFileSync` truncates before it writes, so a hook
+    // stopping in another repository at that instant reads an empty file — and
+    // deleting it there would destroy an enrolment that was about to land, in
+    // silence, for the session whose pull request nobody is waiting on any
+    // more. It is retired by AGE instead, from the filesystem's own timestamp,
+    // which needs no parse and cannot race a write that just happened.
+    try {
+      if (Date.now() - statSync(path).mtimeMs > LEDGER_TTL_MS) ledgerClose(path);
+    } catch {
+      /* gone already, or a directory — nothing to retire */
+    }
+  }
+  return out.sort((a, b) => a.entry.at - b.entry.at);
+}
+
+/**
+ * Should this stop leave an entry behind, and of which kind?
+ *
+ * THE SIGNAL IS THE SERVER'S OWN SENTENCE, not the hook's guess. Ingest
+ * answers `analysis: "none"` with NO reason on exactly one branch — the one
+ * where no pull request asked for a review. Every other "none" carries a
+ * reason (`auto-review-cap`, `another-session-holds-it`, `already-analyzed`,
+ * …), which means a pull request WAS tried and asking again cannot change it.
+ *
+ * Which kind depends on what this stop's own `gh` found:
+ *   nothing, or a CLOSED pull request → a COMMIT entry. The branch's work may
+ *     still get a pull request, and the question to ask about it later is
+ *     "which one contains this commit".
+ *   an OPEN one (so, a draft — a ready one would have triggered) → a NUMBER
+ *     entry. The question is "is that one ready yet", and a number needs no
+ *     search.
+ *   a MERGED one → nothing. The work landed; nobody is waiting for a review.
+ */
+function catchUpEnrolment({ sent, found, branch, commitSha, now }) {
+  if (!sent?.ok || !sent.sessionPublicId) return null;
+  if (sent.analysis !== "none" || sent.analysisReason) return null;
+  if (!branch || branch === "HEAD" || TRUNK_BRANCHES.has(branch)) return null;
+  const pr = found?.pr ?? null;
+  if (pr && pr.state === "MERGED") return null;
+  // Full shas only: `--search` matches a sha by prefix, and a prefix is a
+  // weaker key than the claim it would be used to make.
+  const sha = /^[a-f0-9]{40,64}$/.test(commitSha || "") ? commitSha : null;
+  const byNumber = pr && pr.state === "OPEN";
+  if (!byNumber && !sha) return null;
+  return {
+    v: 1,
+    session: sent.sessionPublicId,
+    branch,
+    sha,
+    pr: byNumber ? pr.number : null,
+    prRepo: byNumber ? pr.repo : null,
+    at: now,
+    // Null, so the very next stop may ask straight away: the cooldown throttles
+    // ASKS, not enrolment.
+    lastAskAt: null,
+    asks: 0,
+  };
+}
+
+/**
+ * Ask gh about one entry. Returns what gh said, in this pass's vocabulary —
+ * never a claim, only a candidate and the reasons it survived or did not.
+ */
+function catchUpAsk(root, repoUrl, entry, timeoutMs) {
+  // A number is an exact question and needs no search.
+  if (entry.pr) {
+    // The host is pinned to the entry's own, exactly as the receipt path pins
+    // it: `--repo owner/name` alone resolves against GH_HOST, and a repository
+    // of the same name on another host is not this one.
+    const got = ghPrView(root, [String(entry.pr), "--repo", `github.com/${entry.prRepo}`], timeoutMs);
+    if (!got.ok) return { kind: "gh", gap: got.kind };
+    const pr = toWirePr(got.json);
+    if (!pr || pr.number !== entry.pr || pr.repo !== entry.prRepo) return { kind: "unusable" };
+    if (!headIsThisBranch(got.json, entry.branch) || !headIsInThisClone(got.json, repoUrl)) {
+      return { kind: "other-branch" };
+    }
+    return { kind: "pr", pr };
+  }
+
+  const got = ghPrList(root, entry.sha, CATCH_UP_SEARCH_LIMIT, timeoutMs);
+  if (!got.ok) return { kind: "gh", gap: got.kind };
+  if (got.list.length === 0) return { kind: "no-match" };
+  // The search finds; the guards prove. Every candidate has to be a pull
+  // request we can record, whose head GitHub says is this session's branch, in
+  // this clone, and which really contains the commit — the last one because
+  // the search is free text and a pull request that merely QUOTES the sha
+  // matches it.
+  const mine = [];
+  for (const json of got.list) {
+    const pr = toWirePr(json);
+    if (!pr) continue;
+    if (!headIsThisBranch(json, entry.branch)) continue;
+    const placed = headClone(json, repoUrl);
+    if (placed === "no") continue;
+    const contained = containsCommit(root, entry.sha, pr.headSha);
+    if (contained === false) continue;
+    // When the head could not be placed — this clone has no `origin`, or gh
+    // answered without a head repository — the commit proof stops being
+    // corroboration and becomes the only evidence there is, so an abstention
+    // from it is not enough. Otherwise a contributor's fork, on a branch of the
+    // same obvious name, reverting a commit of ours, passes every guard at
+    // once: the name matches, the clone cannot be compared, and their head
+    // object was never fetched here.
+    if (placed === "cannot-tell" && contained !== true) continue;
+    mine.push(pr);
+  }
+  if (mine.length === 0) return { kind: "other-branch" };
+  // A MERGED candidate that contains the commit means the work already landed,
+  // and the same rule `catchUpEnrolment` applies at the stop applies here:
+  // nobody is waiting for a review of it. It matters because containment
+  // proves ANCESTRY, not authorship — once the commit is in the branch's
+  // history every later head on that branch contains it, including the head of
+  // a pull request that REVERTS it (git's own revert message quotes the sha in
+  // full, so the free-text search returns it too). Without this the session
+  // that wrote the code would be reviewed against the diff that undoes it.
+  if (mine.some((pr) => pr.state === "MERGED")) return { kind: "settled" };
+  const ready = mine.filter(asksForReview);
+  // Two open pull requests from one head in one clone (two base branches)
+  // leave the claim unprovable. Refuse rather than pick.
+  if (ready.length > 1) return { kind: "ambiguous" };
+  if (ready.length === 1) return { kind: "pr", pr: ready[0] };
+  if (mine.some((pr) => pr.state === "OPEN")) return { kind: "draft" };
+  // Every candidate is CLOSED, and none of them landed: the branch's pull
+  // requests were abandoned, so a replacement may still come.
+  return { kind: "abandoned" };
+}
+
+/**
+ * Make the claim, ask again later, or stop asking. One place, because the two
+ * questions have different shapes and the same three outcomes.
+ */
+function catchUpDecide(entry, answer) {
+  if (answer.kind === "gh") {
+    // This clone will never have a GitHub pull request to name.
+    if (answer.gap === "no-repo" || answer.gap === "not-github") return { action: "close", why: answer.gap };
+    // gh missing, signed out, offline, timed out: a login and a network can
+    // both happen between two stops.
+    return { action: "keep", why: answer.gap };
+  }
+  if (answer.kind === "pr") {
+    const pr = answer.pr;
+    if (asksForReview(pr)) return { action: "send", pr, why: "ready" };
+    if (pr.state === "OPEN") return { action: "keep", why: "draft" };
+    if (pr.state === "MERGED") return { action: "close", why: "settled" };
+    // CLOSED: this pull request was abandoned and the branch's work may
+    // continue into another one, so fall back to asking by commit.
+    return entry.sha ? { action: "demote", why: "closed" } : { action: "close", why: "closed" };
+  }
+  if (answer.kind === "ambiguous" || answer.kind === "unusable" || answer.kind === "settled") {
+    return { action: "close", why: answer.kind };
+  }
+  // `no-match`, `other-branch`, `draft`, `abandoned` — nothing to claim yet,
+  // and tomorrow may be different.
+  return { action: "keep", why: answer.kind };
+}
+
+/**
+ * ONE attempt, and deliberately not `send()`.
+ *
+ * `send()` retries a 5xx three times with a growing backoff, because the
+ * session it is carrying exists nowhere else. A catch-up carries no bytes at
+ * all — the claim is about work the server already holds — so the retry loop
+ * for old work must never compete with the developer's own capture. The next
+ * stop IS the retry.
+ */
+async function sendCatchUp(cfg, body, timeoutMs) {
+  const url = `${cfg.apiUrl.replace(/\/+$/, "")}/v1/catch-up`;
+  try {
+    const res = await fetch(url, {
+      method: "POST",
+      headers: { Authorization: `Bearer ${cfg.key}`, "Content-Type": "application/json" },
+      body: JSON.stringify(body),
+      signal: AbortSignal.timeout(timeoutMs),
+    });
+    const text = await res.text().catch(() => "");
+    let parsed = null;
+    try {
+      parsed = JSON.parse(text);
+    } catch {
+      /* the status carries the decision; the body is the explanation */
+    }
+    return { status: res.status, body: parsed, detail: text.slice(0, 300) };
+  } catch (e) {
+    return { status: 0, body: null, detail: String(e?.message ?? e) };
+  }
+}
+
+/**
+ * What the server's answer means for the entry.
+ *
+ * Anchored to the one rule `send()` already follows — a 4xx is an answer and a
+ * 5xx is a failure to answer — with the single exception the catch-up adds:
+ * a 202 is an answer too, and the reason inside it says whether asking again
+ * could ever change it.
+ */
+function catchUpAfterSend(res) {
+  if (res.status === 202) {
+    const reason = res.body?.analysisReason ?? null;
+    if (!reason) return { action: "close", why: "queued" };
+    return isTransientReason(reason) ? { action: "keep", why: reason } : { action: "close", why: reason };
+  }
+  // 400 (we composed a body it will not take), 404 (the row is gone), 409 (the
+  // claim contradicts the server's own record), 413 — none of them changes by
+  // repeating it.
+  if (res.status >= 400 && res.status < 500 && res.status !== 429) {
+    return { action: "close", why: `http-${res.status}` };
+  }
+  // 429, 5xx, and a request that never arrived: not an answer about the claim.
+  return { action: "keep", why: res.status ? `http-${res.status}` : "unreachable" };
+}
+
+/**
+ * The whole pass: record this stop, retire what has expired, and spend at most
+ * ONE gh call and ONE request on one older session.
+ *
+ * Deliberately voiceless. The developer's single line (D20) is about the stop
+ * that just happened and carries THIS session's link; a clause about a
+ * different session beside that link is the same contradiction F1 refused when
+ * it declined to print a pull request number the session page could not show.
+ * Every ask writes a line to the hook's log instead, where nothing contradicts
+ * it.
+ */
+async function catchUp({ cfg, root, repoUrl, sent, branch, commitSha }, found) {
+  // A stop whose OWN capture did not land has a bad token, a bad address or no
+  // network — and a catch-up would spend a gh call and a request to learn the
+  // same thing a second time. The whole pass waits for a stop that worked; the
+  // entries are on disk and lose nothing by it.
+  if (!root || !sent?.ok) return;
+  const started = Date.now();
+  const now = started;
+
+  // This stop first, so a session the server has just linked cannot then be
+  // picked up and asked about as if it were still waiting.
+  if (sent.sessionPublicId) {
+    const mine = ledgerPath(root, sent.sessionPublicId);
+    const entry = catchUpEnrolment({ sent, found, branch, commitSha, now });
+    if (entry) {
+      if (ledgerWrite(mine, entry)) log(`catch-up enrolled ${entry.session} (${entry.pr ? `#${entry.pr}` : "by commit"})`);
+    } else {
+      ledgerClose(mine);
+    }
+  }
+
+  const entries = ledgerList();
+  // Retire from age before anything is asked: an entry past the cap names a
+  // row the server has already deleted.
+  const live = [];
+  for (const it of entries) {
+    if (now - it.entry.at > LEDGER_TTL_MS) {
+      ledgerClose(it.path);
+      log(`catch-up expired ${it.entry.session}`);
+    } else {
+      live.push(it);
+    }
+  }
+  // Oldest first, so one runaway repository cannot starve the rest.
+  while (live.length > LEDGER_MAX_ENTRIES) ledgerClose(live.shift().path);
+
+  const prefix = `${rootHash(root)}-`;
+  const eligible = live.filter(
+    (it) =>
+      it.name.startsWith(prefix) &&
+      it.entry.session !== sent.sessionPublicId &&
+      (it.entry.lastAskAt == null || now - it.entry.lastAskAt >= CATCH_UP_COOLDOWN_MS),
+  );
+  // LEAST RECENTLY ASKED, not oldest enrolled — and the difference is the
+  // whole feature. Enrolment order looks right and starves the ledger: a
+  // branch that never gets a pull request answers `no-match` forever and stays
+  // at the front, so with one ask per stop and a ten-minute cooldown only the
+  // first few entries are ever reached, and the session this change exists for
+  // — the one whose pull request was just opened by hand — waits behind them
+  // until it expires. A never-asked entry sorts first (`?? 0`), so a new
+  // enrolment is always reached on the next stop. Enrolment order keeps the
+  // job it is right for: which entry the cap evicts.
+  eligible.sort((a, b) => (a.entry.lastAskAt ?? 0) - (b.entry.lastAskAt ?? 0) || a.entry.at - b.entry.at);
+  const candidate = eligible[0];
+  if (!candidate) return;
+
+  const { path, entry } = candidate;
+  // This stop already paid to learn that gh cannot answer here. Asking it a
+  // second question would cost the same wait again — and `lastAskAt` is left
+  // alone, so the entry is first in line on a stop where gh works.
+  if (found?.gap && GH_CANNOT_ANSWER.has(found.gap)) {
+    log(`catch-up ${entry.session} not asked (gh ${found.gap} this stop)`);
+    return;
+  }
+  const answer = catchUpAsk(root, repoUrl, entry, Math.max(2_000, CATCH_UP_BUDGET_MS - (Date.now() - started)));
+  // The cost was paid whatever the answer, so the cooldown is spent first.
+  ledgerWrite(path, { ...entry, lastAskAt: Date.now(), asks: (entry.asks ?? 0) + 1 });
+
+  const decision = catchUpDecide(entry, answer);
+  if (decision.action === "close") {
+    log(`catch-up ${entry.session} closed (${decision.why})`);
+    ledgerClose(path);
+    return;
+  }
+  if (decision.action === "demote") {
+    log(`catch-up ${entry.session} demoted to a commit question (${decision.why})`);
+    ledgerWrite(path, { ...entry, pr: null, prRepo: null, lastAskAt: Date.now(), asks: (entry.asks ?? 0) + 1 });
+    return;
+  }
+  if (decision.action === "keep") {
+    log(`catch-up ${entry.session} still waiting (${decision.why})`);
+    return;
+  }
+
+  const body = {
+    sessionPublicId: entry.session,
+    branch: entry.branch,
+    pr: decision.pr,
+    // The provenance names the question that was asked, and the key travels
+    // with it: a commit for the search, nothing for a number asked again.
+    prSource: entry.pr ? CATCH_UP_SOURCE.again : CATCH_UP_SOURCE.sha,
+    ...(entry.pr ? {} : { commitSha: entry.sha }),
+    clientVersion: CLIENT_VERSION,
+  };
+  const res = await sendCatchUp(cfg, body, Math.max(2_000, CATCH_UP_BUDGET_MS - (Date.now() - started)));
+  const after = catchUpAfterSend(res);
+  // The server's own words, not only our reading of them. A 409 says WHICH of
+  // the three ways the claim contradicted the row, a 400 carries the field a
+  // body we composed got wrong, and an unreachable server carries the transport
+  // error — and on the close branch the entry is about to disappear, so this
+  // line is the only place any of it survives.
+  log(
+    `catch-up ${entry.session} -> #${decision.pr.number} ${res.status || "unreachable"} (${after.why})` +
+      (res.detail ? ` ${res.detail}` : ""),
+  );
+  if (after.action === "close") ledgerClose(path);
+}
+
+/**
+ * The single line the developer sees in their terminal (owner decision D20).
+ * Either the link to what was captured, or one honest sentence — never
+ * silence, and never a promise about a review that has not been asked for.
+ *
+ * It does NOT name the pull request, even when this hook just found one. The
+ * link goes to the session page, and that page reads the App's `pr_number`
+ * (`sessions/[publicId]/page.tsx`), which F0 deliberately does not write from
+ * a client report — so on the no-App flow this change is built for, a line
+ * saying "on pull request #19" would be followed one click later by a page
+ * saying "Waiting for a pull request". The number goes to the hook's log,
+ * where nothing contradicts it, until F2 makes the page able to show it.
+ */
+function terminalLine(sent, found) {
+  if (!sent?.ok) {
+    return sent?.status
+      ? `Videlic could not save this session (HTTP ${sent.status})`
+      : "Videlic could not be reached — this session was not sent";
+  }
+  let lead = "Videlic captured this session";
+  if (!found?.pr) {
+    switch (found?.gap) {
+      case "no-pr":
+        // What gh answered, not what the world is: with two remotes gh picks
+        // the base repository by remote NAME (measured), so a pull request
+        // living in the fork is a "no" here while it is plainly open on
+        // GitHub. The sentence says whose answer this is.
+        lead = "Videlic captured this session; gh found no pull request for this branch";
+        break;
+      case "gh-missing":
+        lead = "Videlic captured this session; install gh so it can name your pull request";
+        break;
+      case "gh-signed-out":
+        lead = "Videlic captured this session; run gh auth login so it can name your pull request";
+        break;
+      case "unusable":
+        // gh answered — we could not use the answer (an address that is not
+        // github.com, a field outside what the server accepts). Saying "could
+        // not ask gh" here would blame the tool for our own limit.
+        lead = "Videlic captured this session; the pull request gh named is not one it can record";
+        break;
+      case "receipt-other-branch":
+        lead = "Videlic captured this session; the pull request it opened is not this branch's";
+        break;
+      case "offline":
+      case "timeout":
+      case "gh-failed":
+        lead = "Videlic captured this session; it could not ask gh which pull request this is";
+        break;
+      case "not-github":
+        // Nothing to advise: this product reviews GitHub pull requests, and
+        // the session was captured all the same. The reason is in the log.
+        break;
+      default:
+        break;
+    }
+  }
+  if (lead.length > TERMINAL_LEAD_CAP) lead = `${lead.slice(0, TERMINAL_LEAD_CAP - 1).trimEnd()}…`;
+  return sent.sessionUrl ? `${lead} — ${sent.sessionUrl}` : lead;
+}
+
+/** One line of JSON on stdout is how a stop hook speaks to the terminal. */
+function say(line) {
+  try {
+    // A pipe whose reader is gone reports itself asynchronously, as an
+    // `error` event on the stream — outside this try/catch, outside
+    // `main().catch`, and so as an uncaught exception that ends the hook with
+    // a stack trace and exit code 1 after a session that uploaded perfectly.
+    process.stdout.on("error", () => {});
+    // `suppressOutput` keeps the raw JSON out of the transcript — the message
+    // is shown to the developer, not fed back into the next session we read.
+    process.stdout.write(`${JSON.stringify({ systemMessage: line, suppressOutput: true })}\n`);
+  } catch {
+    /* the line is a courtesy; never fail the stop over it */
+  }
+}
+
+async function send(url, key, body) {
+  // The last status the server actually answered with, kept across retries:
+  // "we gave up after three 500s" and "we never reached it" are different
+  // sentences, and only a status tells them apart.
+  let lastStatus = 0;
+  for (let attempt = 1; attempt <= 3; attempt++) {
+    let status = 0;
+    let detail = "";
+    try {
+      const res = await fetch(url, {
+        method: "POST",
+        headers: {
+          Authorization: `Bearer ${key}`,
+          "Content-Type": "application/json",
+        },
+        body: JSON.stringify(body),
+        signal: AbortSignal.timeout(60_000),
+      });
+      status = res.status;
+      lastStatus = status;
+      const text = await res.text().catch(() => "");
+      if (status >= 200 && status < 300) {
+        log(`ingest OK (${status})`);
+        let sessionUrl = "";
+        // What the server did with this upload, in its own words. The id is
+        // the strongest key this hook will ever hold for the session — the
+        // ledger is keyed on it rather than on anything the hook composed —
+        // and `analysis`/`analysisReason` are what decide whether this stop is
+        // worth coming back to at all.
+        let sessionPublicId = "";
+        let analysis = "";
+        let analysisReason = "";
+        // The two the evidence endpoint refuses to work without, and the
+        // reason they are read from the ANSWER rather than from what we sent:
+        // an upload with no `sessionFileId` of its own is given one by the
+        // server (`auto_<hash>`), so the id this session is filed under is the
+        // server's to state. `ingestId` is minted per upload and is how the
+        // server tells a bundle collected for THIS stop from one that arrives
+        // after the next stop already moved the conversation on.
+        let ingestId = "";
+        let sessionFileId = "";
+        try {
+          const parsed = JSON.parse(text);
+          if (typeof parsed?.sessionUrl === "string") sessionUrl = parsed.sessionUrl;
+          if (typeof parsed?.sessionPublicId === "string") sessionPublicId = parsed.sessionPublicId;
+          if (typeof parsed?.analysis === "string") analysis = parsed.analysis;
+          if (typeof parsed?.analysisReason === "string") analysisReason = parsed.analysisReason;
+          if (typeof parsed?.ingestId === "string") ingestId = parsed.ingestId;
+          if (typeof parsed?.sessionFileId === "string") sessionFileId = parsed.sessionFileId;
+        } catch {
+          /* the link is a courtesy; the capture already landed */
+        }
+        return { ok: true, status, sessionUrl, sessionPublicId, analysis, analysisReason, ingestId, sessionFileId };
+      }
+      detail = text.slice(0, 300);
+    } catch (e) {
+      detail = String(e?.message ?? e);
+    }
+    if (status >= 400 && status < 500) {
+      log(`ingest failed ${status}: ${detail}`); // client error — don't retry
+      return { ok: false, status };
+    }
+    log(`ingest attempt ${attempt} -> ${status || "error"} (${detail})`);
+    if (attempt < 3) await new Promise((r) => setTimeout(r, attempt * 2000));
+  }
+  return { ok: false, status: lastStatus };
+}
+
+/** The flag that makes this file the collector instead of the hook. */
+const COLLECT_FLAG = "--collect-evidence";
+
+/**
+ * Hand the evidence collection to a copy of THIS file, detached.
+ *
+ * Why a second run of the same file and not a second file with its own entry
+ * point: `install.mjs` copies what it is given into `~/.claude`, and a hook
+ * that had to find a sibling script by path would break the moment anybody
+ * moved or renamed one of them. `process.argv[1]` is the file that is running,
+ * which is the only path that is true wherever it was installed.
+ *
+ * Nothing secret goes on the command line — `ps` is world-readable on every
+ * machine this runs on. The child reads `~/.claude/videlic.json` itself, the
+ * same way this process did.
+ *
+ * The transcript's PATH travels, the transcript does not. E2 needs the
+ * session's own test commands — a runner listing a repository's whole test
+ * suite from the root is not the selection of a run that started inside one
+ * package, and the difference was measured at 460 files against 5. A command
+ * LINE may carry a token somebody would not want in `ps`; a path to a file in
+ * the developer's own home directory names nothing that `root` and
+ * `sessionFileId`, already both here, do not.
+ */
+function spawnCollector(cfg, sent, root, transcript) {
+  if (!root || !sent?.ok) return;
+  // Both are the server's own words about this upload. An older server that
+  // does not echo them yet simply gets no bundle, which is correct: the
+  // endpoint would refuse one it cannot key, and a bundle filed under a guess
+  // is worse than no bundle.
+  if (!sent.ingestId || !sent.sessionFileId) {
+    log("evidence: server did not name this ingest — nothing to collect against");
+    return;
+  }
+  try {
+    const self = process.argv[1];
+    if (!self) return;
+    const argv = [self, COLLECT_FLAG, root, sent.sessionFileId, sent.ingestId];
+    // Optional and last, so a collector started by an older hook — or by a
+    // hook whose stop payload named no transcript — still parses its own
+    // arguments and still sends the tree.
+    if (transcript) argv.push(transcript);
+    const child = spawn(process.execPath, argv, {
+      detached: true,
+      stdio: "ignore",
+      windowsHide: true,
+    });
+    // A spawn failure arrives as an ASYNCHRONOUS `error` event, which the
+    // try/catch around this call cannot see — and an `error` with no listener
+    // is rethrown by Node as an uncaught exception. That would take down the
+    // Stop hook AFTER the capture has landed and the developer's line has been
+    // printed: a stack trace on their terminal, caused entirely by a
+    // nice-to-have. The listener must be attached before `unref`.
+    child.on("error", (e) => log(`evidence: collector failed to start: ${e?.message ?? e}`));
+    child.unref();
+    log(`evidence: collector ${child.pid} detached for ingest ${sent.ingestId}`);
+  } catch (e) {
+    // A collector that could not start costs the review its evidence and the
+    // session nothing at all. That is the right way round, and it is why this
+    // is the last thing main() does.
+    log(`evidence: could not start collector: ${e?.message ?? e}`);
+  }
+}
+
+/**
+ * The detached half: collect the bundle and post it.
+ *
+ * It runs after the hook has already returned, so it has no terminal, no
+ * stdin and no deadline it shares with the session. Everything it can do
+ * wrong, it does quietly into the log.
+ */
+async function collect(root, sessionFileId, ingestId, transcript) {
+  const cfg = readConfig();
+  if (!cfg) return;
+  const started = Date.now();
+  const { collectEvidence, commandsFromTranscript } = await import("./evidence.mjs");
+  // The session's own command lines, read here rather than passed on the
+  // command line. `undefined` when there is no transcript to read, which is
+  // the honest answer: the collector did not ATTEMPT a selection, which is a
+  // different fact from a repository that runs no tests.
+  //
+  // Reading it cannot cost the bundle. A transcript that has been rotated,
+  // truncated or deleted between the hook's read and this one leaves the
+  // sections that do not depend on it exactly as they were.
+  let testCommands;
+  if (transcript) {
+    try {
+      testCommands = commandsFromTranscript(readFileSync(transcript, "utf8"));
+    } catch (e) {
+      log(`evidence: transcript unreadable for the selection (${e?.message ?? e})`);
+    }
+  }
+  const r = collectEvidence({ root, clientVersion: CLIENT_VERSION, testCommands });
+  if (!r.bundle) {
+    log(`evidence: nothing collected (${r.reason})`);
+    return;
+  }
+  const sections = Object.entries(r.bundle.sent)
+    .map(([k, v]) => `${k}=${v === true ? "yes" : v}`)
+    .join(" ");
+  log(`evidence: collected in ${r.spentMs}ms, ${r.bytes} B · ${sections}`);
+  const url = `${cfg.apiUrl.replace(/\/+$/, "")}/v1/evidence`;
+  try {
+    const res = await fetch(url, {
+      method: "POST",
+      headers: { Authorization: `Bearer ${cfg.key}`, "Content-Type": "application/json" },
+      body: JSON.stringify({ sessionFileId, ingestId, bundle: r.bundle }),
+      signal: AbortSignal.timeout(EVIDENCE_POST_TIMEOUT_MS),
+    });
+    const text = await res.text().catch(() => "");
+    // One attempt, no retry. The bundle describes a tree that is already
+    // moving under the developer's hands, and the next stop collects a fresher
+    // one anyway — a retry would spend minutes to deliver something staler
+    // than what is coming.
+    log(`evidence: ${res.status} ${text.slice(0, 200)} (total ${Date.now() - started}ms)`);
+  } catch (e) {
+    log(`evidence: post failed: ${e?.message ?? e}`);
+  }
+}
+
+/** The bundle is one request and gzips to well under a megabyte; it does not need the upload's minute. */
+const EVIDENCE_POST_TIMEOUT_MS = 30_000;
+
 async function main() {
   const cfg = readConfig();
   if (!cfg) process.exit(0); // not configured — nothing to do
@@ -157,48 +1501,130 @@ async function main() {
     sessionData = readFileSync(transcript, "utf8");
   }
 
-  const { branch, commitSha, repoUrl } = gitMeta(cwd);
+  const { branch, commitSha, repoUrl, root } = gitMeta(cwd);
+  const found = findPullRequest(root, branch, repoUrl, () => sessionData);
+  if (found.pr) {
+    log(`pr ${found.pr.repo}#${found.pr.number} (${found.pr.state}${found.pr.draft ? ", draft" : ""}) via ${found.source}`);
+  } else {
+    log(`pr none (${found.gap})`);
+  }
 
+  // Each of these is bounded on the server, and Zod answers a body that
+  // exceeds one with a 400 that loses the WHOLE session — the same trap the
+  // pull request is held to above. A field we cannot send within its bound is
+  // dropped; the capture is worth more than the label.
+  const fits = (value, max) => (typeof value === "string" && value.length > 0 && value.length <= max ? value : null);
   const body = { agent: "claude-code", sessionData };
-  if (sessionId) body.sessionFileId = sessionId;
-  if (branch) body.branch = branch;
-  if (commitSha) body.commitSha = commitSha;
-  if (repoUrl) body.repoUrl = repoUrl;
+  if (fits(sessionId, 100)) body.sessionFileId = sessionId;
+  if (fits(branch, 256)) body.branch = branch;
+  if (/^[a-f0-9]{7,64}$/.test(commitSha)) body.commitSha = commitSha;
+  if (fits(repoUrl, 1000)) body.repoUrl = repoUrl;
   if (truncated) body.truncated = true;
+  // Which hook composed this body — never omitted, so a server can measure
+  // the fleet by it and read "absent" as the pre-version client it is.
+  body.clientVersion = CLIENT_VERSION;
+  // Explicitly null, not absent: "we asked and there is none" and "we never
+  // asked" are different facts, and only the first one is a null on the wire.
+  body.pr = found.pr;
+  // `prSource` describes `pr` — the server refuses one without the other.
+  if (found.pr && found.source) body.prSource = found.source;
+
+  // Is a bundle coming? The server reads this to hold the analysis for one
+  // (`startAfter`) rather than judging a session it is about to have evidence
+  // for. It must be answered before the upload, so it is answered by what this
+  // hook is ABLE to do — a git repository we found a root for — and never by
+  // optimism: a `follows` that never arrives costs the review its own budget.
+  body.evidence = root ? "follows" : "none";
 
   const url = `${cfg.apiUrl.replace(/\/+$/, "")}/v1/ingest`;
-  for (let attempt = 1; attempt <= 3; attempt++) {
-    let status = 0;
-    let detail = "";
-    try {
-      const res = await fetch(url, {
-        method: "POST",
-        headers: {
-          Authorization: `Bearer ${cfg.key}`,
-          "Content-Type": "application/json",
-        },
-        body: JSON.stringify(body),
-        signal: AbortSignal.timeout(60_000),
-      });
-      status = res.status;
-      if (status >= 200 && status < 300) {
-        log(`ingest OK (${status})`);
-        return;
-      }
-      detail = (await res.text().catch(() => "")).slice(0, 300);
-    } catch (e) {
-      detail = String(e?.message ?? e);
-    }
-    if (status >= 400 && status < 500) {
-      log(`ingest failed ${status}: ${detail}`); // client error — don't retry
-      return;
+  const sent = await send(url, cfg.key, body);
+  // The developer's line goes out BEFORE the catch-up, not after. The pass is
+  // voiceless by design, so nothing on the line depends on it — and putting it
+  // second meant the terminal stayed blank for the whole of the catch-up's
+  // budget on top of the upload's. It also means a hook killed mid-pass has
+  // already said what happened to THIS session.
+  say(terminalLine(sent, found));
+  // The evidence goes to a DETACHED process, and the whole design rests on
+  // that: collection reads every source file in the repository (measured at
+  // ~0.9 s and 4.2 MB on a 24 000-file monorepo, but it is somebody else's
+  // laptop and somebody else's disk), while a stop hook holds the developer's
+  // terminal for as long as it runs. Measured: a child spawned `detached` with
+  // `stdio: "ignore"` and unref'd survives both this process exiting normally
+  // and a SIGKILL of its whole process group — which is what Claude Code does
+  // to a hook that overruns. So the collection cannot cost the session, and
+  // being killed cannot cost the collection.
+  spawnCollector(cfg, sent, root, transcript);
+  // After the upload, because enrolment needs two things only the server's
+  // answer carries — the session's public id and the server's own sentence
+  // about whether anything was even tried — and because a stop whose own
+  // capture failed has a bad token or a bad network, and would spend a gh call
+  // and a request to learn it twice.
+  await catchUp({ cfg, root, repoUrl, sent, branch, commitSha }, found).catch((e) =>
+    log(`catch-up failed: ${e?.message ?? e}`),
+  );
+}
+
+// `main()` runs whenever this file is executed, which is the only way the
+// hook is ever used. Tests import the helpers above with
+// VIDELIC_HOOK_NO_MAIN=1 set; the default stays "run" on purpose, because a
+// hook that silently did nothing would be indistinguishable from a working
+// one until a developer noticed their sessions had stopped arriving.
+if (process.env.VIDELIC_HOOK_NO_MAIN !== "1") {
+  // The collector branch comes FIRST, and it has to: `main()` awaits stdin
+  // unconditionally, and a detached child is spawned with `stdio: "ignore"` —
+  // it would read "", fail to parse it, and log "unparseable stop payload"
+  // forever while collecting nothing.
+  const flagAt = process.argv.indexOf(COLLECT_FLAG);
+  if (flagAt > 0) {
+    const [root, sessionFileId, ingestId, transcript] = process.argv.slice(flagAt + 1);
+    if (root && sessionFileId && ingestId) {
+      collect(root, sessionFileId, ingestId, transcript).catch((e) => log(`evidence: fatal: ${e?.message ?? e}`));
+    } else {
+      log("evidence: collector started without a root, a session or an ingest");
     }
-    log(`ingest attempt ${attempt} -> ${status || "error"} (${detail})`);
-    if (attempt < 3) await new Promise((r) => setTimeout(r, attempt * 2000));
+  } else {
+    main().catch((e) => {
+      log(`fatal: ${e?.message ?? e}`);
+      process.exit(0); // never break the user's session on our account
+    });
   }
 }
 
-main().catch((e) => {
-  log(`fatal: ${e?.message ?? e}`);
-  process.exit(0); // never break the user's session on our account
-});
+export {
+  CLIENT_VERSION,
+  COLLECT_FLAG,
+  collect,
+  spawnCollector,
+  findPullRequest,
+  headIsInThisClone,
+  repoFromRemote,
+  PR_SOURCE,
+  CATCH_UP_SOURCE,
+  GH_FIELDS,
+  GH_TIMEOUT_MS,
+  ghEnv,
+  ghFailureKind,
+  headIsThisBranch,
+  invokesPrCreate,
+  parsePrUrl,
+  prFromSessionReceipt,
+  resolveTool,
+  terminalLine,
+  toWirePr,
+  asksForReview,
+  catchUpAfterSend,
+  catchUpDecide,
+  catchUpEnrolment,
+  containsCommit,
+  headClone,
+  isTransientReason,
+  GH_CANNOT_ANSWER,
+  normalizeRoot,
+  rootHash,
+  LEDGER_DIR,
+  LEDGER_TTL_MS,
+  LEDGER_MAX_ENTRIES,
+  CATCH_UP_COOLDOWN_MS,
+  CATCH_UP_SEARCH_LIMIT,
+  TRUNK_BRANCHES,
+};