gstack/bin/gstack-evidence

#!/usr/bin/env -S bun --no-env-file --config=/dev/null
/**
 * gstack-evidence — verification-evidence ledger: the mechanical arm of /ship's
 * IRON LAW ("no completion claims without fresh verification evidence").
 *
 *   gstack-evidence run [--reuse [--max-age <hours>]] --label <L> -- <cmd...>
 *   gstack-evidence record-ci --label <L> --base <base> -- <cmd>
 *   gstack-evidence carried [--json]
 *   gstack-evidence check [--label <L> [--expect-cmd <exact string>]]... | --all
 *                         [--max-age <hours>] [--allow-paths <csv>]
 *   gstack-evidence bundle --out <file> [--label <L>]... [--require <csv>] [--selection L=<text>]...
 *                          [--run-url L=<url>]... [--import <json>] [--base <branch>]   (plan C3; lib/evidence-bundle.ts)
 *   gstack-evidence ancestor <sha>... | --from-policy [--base <branch>]                 (plan C7)
 *   gstack-evidence verify <bundle> [--rerun] [--out <file>] [--json]                   (plan E2)
 *
 * `run` is a TRANSPARENT wrapper: it streams the child's output through
 * unchanged, tees it to a 0600 log (2MB cap with a truncation marker), and
 * appends {ts, label, command, cmd_sha256, exit, duration_s, commit, tree,
 * dirty, wtree or wtree_changed, log_path, tests_ran} to ~/.gstack/projects/<slug>/<branch>-evidence.jsonl.
 *
 * `tests_ran` (zero-run green, W3 of docs/designs/HONEST_WORK_GATE_INTEGRITY.md)
 * is parsed from a bounded tail of the streamed output for the supported
 * runners only: bun (shard-engine's summary parser where importable; executed =
 * pass + fail, so an all-skip run is 0), jest, vitest, pytest, rspec, Go's
 * zero-only case (every package `[no test files]`), gstack's own shard runner
 * (`bun run test:free` / `test:ubicloud`: the sum of its per-shard
 * `[test:free] PASS — N tests` epilogues, or a files-from run's
 * `FILES-FROM RESULT: … tests=N`), and a `gstack-pregate --remote` lane (the
 * remote gate's `PREGATE_REMOTE: … tests=N` row, or the cleared obligation's
 * `cleared by remote-gate … tests=N` receipt). The shard runner and the remote
 * gate print only bun's terminal totals, which count skipped tests, so for
 * those two the number is "ran, skips included" rather than executed (the shard
 * runner refuses a shard whose bun summary counts fewer files than planned, but
 * a shard whose files all loaded and executed nothing still passes with that
 * total). When the shard runner spoke, its verdict stands for the whole tail:
 * the tail is the stdout tail then the stderr tail, so a line's position says
 * nothing about when it was printed across streams, and bun's own counts (on
 * stderr) would otherwise outrank a 10k-test run whichever of the two ran
 * first. Any summary when it did not speak follows the last-summary-wins rule;
 * anything else is "unknown".
 * Three states, never merged:
 * a count, 0 (ZERO-RUN, graded like STALE by `check`) and unknown (non-blocking).
 *
 * TRANSPARENCY INVARIANT (load-bearing): the child's exit code is ALWAYS the
 * wrapper's exit code. Every bookkeeping failure — ledger append, log dir,
 * non-git context, redact scan — is a stderr warning, never a failure. The
 * wrapper must never turn green tests red.
 *
 * Freshness binds to `wtree`, the working-tree content fingerprint from
 * bin/gstack-wtree: evidence recorded on uncommitted code stays FRESH after
 * the exact tested content is committed, and an untracked new source file
 * invalidates it. `cmd_sha256` = sha256 of the exact command string, no
 * normalization — the same convention as bin/gstack-verify-gate (which hashes
 * for TRUST; this ledger hashes for FRESHNESS).
 *
 * `run --reuse` (GSTA-258, what gstack-ship-preflight and finish pass): before
 * running, the newest row for this label, command hash and working-tree
 * fingerprint decides. It is reused only when it passed with a counted run
 * (tests_ran > 0) under the same execution identity (bun and node versions,
 * OS, architecture and runner image; lockfiles and pins are tree content) within --max-age
 * hours (default 24); a newer failure on that tree vetoes an older pass. The
 * reuse appends a copy that keeps the original timestamp, so check's max age
 * still measures the real run.
 *
 * `record-ci` writes the explicit CI-sourced row for a lane CI carried: it
 * finds and verifies the run itself (lib/ci-carry.ts) for a command the base's
 * ship_lanes_from maps, then records source "ci", the runs and profiles, the
 * run's finish time as ts, bound to HEAD's clean tree; `carried` lists those
 * rows at the current tree for the ship receipt.
 *
 * MACHINE-LOCAL by design: neither the ledger nor the logs are brain-synced.
 * A synced record citing an unsynced log would grade FRESH on a machine where
 * the log doesn't exist.
 *
 * `check` is read-only and never throws into the calling skill flow: any git
 * failure (gc'd stored tree, not a repo) degrades to STALE/MISSING. Call sites
 * must name expected labels explicitly — `--all` checks only labels that exist
 * in the ledger; it cannot prove that an expected lane ever ran.
 */

import { openSync, writeSync, closeSync, readdirSync, statSync, unlinkSync, chmodSync, readFileSync } from "fs";
import { mkdirpSync } from "../lib/fs-utils";
import { join, dirname } from "path";
import { spawnSync } from "child_process";
import { appendJsonl, readJsonl } from "../lib/jsonl-store";
import { resolveStateRoot } from "../lib/state-root";
import { scan, applyRedactions } from "../lib/redact-engine";
import { buildBundle, checkAncestors, readBundle, renderVerification, verifyBundle } from "../lib/evidence-bundle";
import { resultLine } from "../lib/result-codes";
import { isUnavailable, loadPolicyFromBase, resolveBaseBranch } from "../lib/ship-policy";
import { versionAtRef } from "../lib/restamp";
import { bashCommandInvocation, runScriptSync, wtreeFingerprint } from "../lib/script-invocation";
import { findCarry } from "../lib/ci-carry";
import { isConfigUnavailable, loadConfigFromBase } from "../lib/pregate/config";
import { buildRunCheck } from "../lib/pregate/run-check";
import { runInventory } from "../lib/run-evidence";

const BIN_DIR = dirname(Bun.fileURLToPath(import.meta.url));
const LOG_MAX_BYTES = 2 * 1024 * 1024;
const LOG_PRUNE_DAYS = 30;

interface EvidenceRecord {
  ts: string;
  label: string;
  command: string;
  cmd_sha256: string;
  exit: number;
  duration_s: number;
  commit?: string;
  tree?: string;
  dirty?: boolean;
  wtree?: string;
  /** Up to five paths whose content changed between the before-run and after-run fingerprints (set instead of wtree). */
  wtree_changed?: string[];
  log_path?: string;
  redacted?: boolean;
  /** sha256 of the runtime the run had (identityDigest). */
  identity?: string;
  /** The original ts of the row a `run --reuse` copied. */
  reused_from?: string;
  /** "ci" for a lane CI carried (record-ci); absent for a local run. */
  source?: "ci";
  runs?: string[];
  profiles?: string[];
  /** The base policy that mapped a carried lane (record-ci), as `origin/<base>@<sha>:.gstack/pregate.json`. */
  policy?: string;
  /** The runner's own test count (executed for bun/jest/vitest/pytest/rspec; ran with skips included for gstack's shard runner and the remote gate), 0 for ZERO-RUN, or "unknown" when no supported summary was seen. */
  tests_ran?: number | "unknown";
}

/** Bytes of streamed output kept for the tests_ran parse (the 2MB log would truncate the summary). */
const TAIL_MAX_BYTES = 64 * 1024;

/**
 * Ring of the last TAIL_MAX_BYTES of each child stream, kept per stream: the
 * pumps interleave by arrival, so a stderr summary read while stdout still has
 * pipe-buffered bytes behind it would otherwise be pushed out of a shared ring.
 */
class OutputTail {
  private readonly decoders = { stdout: new TextDecoder("utf-8"), stderr: new TextDecoder("utf-8") };
  private readonly text = { stdout: "", stderr: "" };
  push(chunk: Uint8Array, origin: "stdout" | "stderr"): void {
    this.text[origin] += this.decoders[origin].decode(chunk, { stream: true });
    if (this.text[origin].length > TAIL_MAX_BYTES * 2) this.text[origin] = this.text[origin].slice(-TAIL_MAX_BYTES);
  }
  end(): string {
    const tails = (["stdout", "stderr"] as const).map((origin) => {
      const text = this.text[origin] + this.decoders[origin].decode();
      return text.length > TAIL_MAX_BYTES ? text.slice(-TAIL_MAX_BYTES) : text;
    });
    return tails.join("\n");
  }
}

const ANSI = /\u001B\[[0-?]*[ -/]*[@-~]/g;
const strip = (l: string) => l.replace(ANSI, "").replace(/\r$/, "");
const count = (text: string, word: string): number => Number(new RegExp(`(\\d+) ${word}\\b`).exec(text)?.[1] ?? 0);

/**
 * Bun: the last "Ran N tests across M files" block; executed = its " N pass" +
 * " N fail" lines. Bun always prints that counts block (" 0 pass" / " 0 fail"
 * even for an all-skip or empty run), so a terminal line with no " N pass"
 * above it is a line gstack's quiet shard runner forwarded (it forwards the
 * terminal line without the " N pass" line), not a bun summary:
 * it is skipped and the shard runner's own epilogue counts. A terminal line
 * that itself says "Ran 0 tests" is ZERO-RUN even without counts, unless the
 * shard runner spoke: a forwarded "Ran 0 tests across 1 file" is one shard's
 * empty file, not the run.
 */
async function bunTestsRan(lines: string[]): Promise<{ at: number; ran: number } | null> {
  let isTerminal = (l: string) => /^Ran \d+ tests? across \d+ files?\. \[/.test(l);
  try {
    const engine = await import("../scripts/lib/shard-engine");
    isTerminal = (l: string) => engine.parseBunTerminalSummary(l) !== null;
  } catch {
    warn("shard-engine classifier not importable; using the built-in bun summary parser");
  }
  for (let i = lines.length - 1; i >= 0; i--) {
    if (!isTerminal(lines[i])) continue;
    let pass: number | null = null;
    let fail = 0;
    for (let j = i - 1; j >= 0 && j >= i - 12; j--) {
      if (isTerminal(lines[j])) break;
      const p = /^\s*(\d+) pass$/.exec(lines[j]);
      const f = /^\s*(\d+) fail$/.exec(lines[j]);
      if (p) pass = Number(p[1]);
      if (f) fail = Number(f[1]);
    }
    if (pass === null) {
      if (/^Ran 0 tests? across/.test(lines[i])) return { at: i, ran: 0 };
      continue;
    }
    return { at: i, ran: pass + fail };
  }
  return null;
}

/**
 * gstack's shard runner (scripts/test-free-shards.ts; `bun run test:free` /
 * `test:ubicloud`). Its quiet shards forward bun's terminal line without the
 * counts the bun branch reads, so each shard's epilogue "[test:free] PASS — N
 * tests, M files, Ts." carries the shard's "Ran N" total (skips included) and
 * the run's total is their sum; a files-from run ends with "[test:free]
 * FILES-FROM RESULT: files=F tests=N failed=K exit=E", the same sum. Only the
 * last run in the tail counts (its "[test:free] full suite:" / "files-from" /
 * "QUICK SUBSET" start line); the other parsers decide only when no runner
 * line at all is in the tail. A run with a "FAIL —" or "FLAKY-PASS —" epilogue and no FILES-FROM
 * total has lost a shard's count (a FAIL epilogue carries none; the flaky retry
 * re-runs only the failing files), so it is unknown rather than a partial sum.
 * The runner's verdict covers the whole tail once it spoke: the tail is
 * stdout-then-stderr, bun's counts block is on stderr and the runner's
 * epilogues are on stdout, so "after" cannot be told from "before" across the
 * two streams and a bun block printed before the suite (a focused file run
 * first) would otherwise record its count, or ZERO-RUN, for a 10k-test run.
 * The quiet shards forward only count-less terminal lines (a shard's "Ran 0
 * tests across 1 file" is one empty file, not the run); under `--verbose` they
 * forward whole blocks, which the runner's sum outranks. The epilogue is
 * matched as the runner's whole line (the log path may contain spaces); like
 * every runner summary here it is the child's own stdout, so a test that
 * forges one is trusted the same way a forged bun summary is (see W3's trust
 * model), and the exit is never derived from it. Returns undefined when no
 * runner line is in the tail. A verdict line (PASS/FAIL/FLAKY-PASS epilogue or
 * FILES-FROM RESULT) without its start line means the start line was evicted
 * from the tail (a chatty default-mode or --verbose run): the runner spoke,
 * the sum is incomplete, so the result is unknown rather than a forwarded
 * shard block's count. A full-suite start line names its shard count
 * ("across N shard processes", plus one exclusive host-state shard when it
 * says so); fewer PASS epilogues than that (killed mid-shards, `--ci-verify`)
 * is unknown, never a partial sum. An empty shard prints "shard i/N: 0 files,
 * 0s, pass" instead of a PASS epilogue and counts as zero.
 */
function shardRunnerTestsRan(lines: string[]): number | "unknown" | undefined {
  const verdictLine = /^\s*\[test:free\] (?:PASS — |FAIL — |FLAKY-PASS — |FILES-FROM RESULT: )/;
  const start = lines.findLastIndex((l) => /^\s*\[test:free\] (?:full suite:|files-from |QUICK SUBSET:)/.test(l));
  if (start < 0) return lines.some((l) => verdictLine.test(l)) ? "unknown" : undefined;
  const run = lines.slice(start);
  const result = /^\s*\[test:free\] FILES-FROM RESULT: files=\d+ tests=(\d+) failed=\d+ exit=\d+\s*$/;
  const total = run.findLast((l) => result.test(l));
  if (total) return Number(result.exec(total)![1]);
  if (run.some((l) => /^\s*\[test:free\] (?:FAIL|FLAKY-PASS) — /.test(l) || /^\s*\[test:free\] PASS — \? tests/.test(l))) return "unknown";
  const counts = run.map((l) => /^\s*\[test:free\] PASS — (\d+) tests?, \d+ files?, \d+s\. Full log: \S.*$/.exec(l)?.[1] ?? (/^\s*\[test:free\] shard \d+\/\d+: 0 files, \d+s, pass\s*$/.test(l) ? "0" : undefined)).filter((n): n is string => n !== undefined);
  const planned = /across (\d+) shard processes/.exec(run[0]!);
  const expected = planned ? Number(planned[1]) + (/exclusive host-state file/.test(run[0]!) ? 1 : 0) : 1;
  return counts.length >= expected ? counts.reduce((sum, n) => sum + Number(n), 0) : "unknown";
}

function otherRunnersTestsRan(lines: string[]): { at: number; ran: number } | null {
  const hits: { at: number; ran: number }[] = [];
  const last = (re: RegExp) => {
    for (let i = lines.length - 1; i >= 0; i--) if (re.test(lines[i])) return i;
    return -1;
  };
  // jest: "Tests:       1 failed, 2 passed, 3 total" / "No tests found"
  let i = last(/^Tests:\s+.*\d+ total/);
  if (i >= 0) hits.push({ at: i, ran: count(lines[i], "passed") + count(lines[i], "failed") });
  i = last(/^No tests found/);
  if (i >= 0) hits.push({ at: i, ran: 0 });
  // vitest: "      Tests  3 passed | 1 skipped (4)" / "No test files found"
  i = last(/^\s*Tests\s+\d+ .*\(\d+\)\s*$/);
  if (i >= 0) hits.push({ at: i, ran: count(lines[i], "passed") + count(lines[i], "failed") });
  i = last(/^No test files found/);
  if (i >= 0) hits.push({ at: i, ran: 0 });
  // pytest: "===== 3 passed, 1 skipped in 0.12s =====" / "no tests ran in 0.01s"
  i = last(/^=+ .* in [\d.]+s(?: \([^)]*\))? =+$/);
  if (i >= 0) {
    const t = lines[i];
    hits.push({ at: i, ran: /\bno tests ran\b/.test(t) ? 0 : count(t, "passed") + count(t, "failed") + count(t, "errors?") + count(t, "xfailed") + count(t, "xpassed") });
  }
  // rspec: "12 examples, 0 failures, 2 pending"
  i = last(/^\d+ examples?, \d+ failures?/);
  if (i >= 0) hits.push({ at: i, ran: count(lines[i], "examples?") - count(lines[i], "pending") });
  // go test: zero-only — every package "[no test files]" and no ok/FAIL package line
  const goNoTests = lines.filter((l) => /^\?\s+\S+\s+\[no test files\]$/.test(l));
  const goRan = lines.some((l) => /^(?:ok|FAIL|---)\s/.test(l));
  if (goNoTests.length > 0 && !goRan) hits.push({ at: last(/\[no test files\]$/), ran: 0 });
  // gstack-pregate --remote: the remote gate's own "PREGATE_REMOTE: tree=… tests=N failed=M"
  // line (tests = the shard runner's FILES-FROM RESULT sum, relayed by scripts/ubicloud/pregate-remote.sh;
  // lib/pregate/checks/lanes.ts parseRemoteReport is the canonical parser), rendered as a lane
  // row under "lanes:" in the pregate table, and the obligation's "requires-remote: … cleared by
  // remote-gate tree=… tests=N" receipt line (lib/pregate/index.ts). Whole lines, like every
  // other runner pattern here, so a prefixed or quoted echo does not count (the row is indented
  // under "lanes:" by design, so indentation is accepted). When both appear they carry the same
  // count; the later one wins.
  for (const re of [/^\s*(?:lanes:\s+)?PREGATE_REMOTE: tree=\S+ tests=(\d+) failed=\d+(?: spent=\S+)?\s*$/, /^\s*requires-remote: .* cleared by remote-gate tree=\S+ tests=(\d+)\b/]) {
    i = last(re);
    if (i >= 0) hits.push({ at: i, ran: Number(re.exec(lines[i])![1]) });
  }
  if (hits.length === 0) return null;
  return hits.reduce((a, b) => (b.at > a.at ? b : a));
}

/** The runner-reported test count from the output tail (see the header for which runners report executed vs ran), 0, or "unknown". Never throws into the caller's exit path. */
async function parseTestsRan(tail: string): Promise<number | "unknown"> {
  if (process.env.GSTACK_EVIDENCE_FAULT === "tests_ran") throw new Error("injected tests_ran parser fault");
  const lines = tail.split("\n").map(strip);
  const shard = shardRunnerTestsRan(lines);
  if (shard !== undefined) return shard;
  const candidates = [await bunTestsRan(lines), otherRunnersTestsRan(lines)].filter((c): c is { at: number; ran: number } => c !== null);
  if (candidates.length === 0) return "unknown";
  return candidates.reduce((a, b) => (b.at > a.at ? b : a)).ran;
}

function warn(msg: string): void {
  console.error(`gstack-evidence: warning: ${msg}`);
}

function sha256(text: string): string {
  const h = new Bun.CryptoHasher("sha256");
  h.update(text);
  return h.digest("hex");
}

function git(args: string[]): string | undefined {
  try {
    const r = spawnSync("git", args, { encoding: "utf-8", timeout: 15000 });
    if (r.status !== 0) return undefined;
    const out = (r.stdout || "").trim();
    return out || undefined;
  } catch {
    return undefined;
  }
}

let wtreeWarned = false;
/** Content fingerprint (SHA-1 or SHA-256 tree id); undefined grades STALE, with the reason printed once. */
function currentWtree(): string | undefined {
  const fp = wtreeFingerprint({ cwd: process.cwd(), timeoutMs: 30000 });
  if ("tree" in fp) return fp.tree;
  if (!wtreeWarned) warn(`working-tree fingerprint unavailable (${fp.error}) — evidence recorded without it (will grade STALE)`);
  wtreeWarned = true;
  return undefined;
}

function ledgerPath(): { dir: string; file: string; logsDir: string } {
  const home = resolveStateRoot();
  // No resolvable home: skip bookkeeping (the relative ".gstack" fallback would
  // land inside the repo and perturb the fingerprint it exists to compute).
  if (home === ".gstack") throw new Error("no GSTACK_HOME/HOME — bookkeeping skipped");
  // ONE gstack-slug spawn: its output carries both SLUG= and BRANCH= lines
  // (same branch→filename sanitization as reviews.jsonl).
  const slugOut = runScriptSync(join(BIN_DIR, "gstack-slug"), [], { encoding: "utf-8", timeout: 30000 });
  const sm = (slugOut.stdout || "").match(/^SLUG=(.+)$/m);
  const bm = (slugOut.stdout || "").match(/^BRANCH=(.+)$/m);
  const slug = sm ? sm[1].trim() : "unknown";
  const branch = bm ? bm[1].trim() : "no-branch";
  const dir = join(home, "projects", slug);
  return { dir, file: join(dir, `${branch}-evidence.jsonl`), logsDir: join(dir, "logs") };
}

/** Redact-engine pass over the command string. HIGH finding → store redacted. */
function safeCommandForRecord(command: string): { command: string; redacted: boolean } {
  try {
    const { findings } = scan(command);
    const high = findings.filter((f) => f.tier === "HIGH");
    if (high.length === 0) return { command, redacted: false };
    const redactedBody = applyRedactions(command, findings.map((f) => f.id)).body;
    const still = scan(redactedBody).findings.some((f) => f.tier === "HIGH");
    return { command: still ? "<redacted: HIGH credential in command>" : redactedBody, redacted: true };
  } catch {
    return { command, redacted: false };
  }
}

/** Opportunistic prune of logs older than LOG_PRUNE_DAYS. Best-effort. */
function pruneOldLogs(logsDir: string): void {
  try {
    const cutoff = Date.now() - LOG_PRUNE_DAYS * 24 * 3600 * 1000;
    for (const name of readdirSync(logsDir)) {
      const p = join(logsDir, name);
      try {
        if (statSync(p).mtimeMs < cutoff) unlinkSync(p);
      } catch {}
    }
  } catch {}
}

/** Exclusive-open a collision-safe log file. Returns undefined on failure. */
function openLog(logsDir: string, label: string, cmdSha: string): { fd: number; path: string } | undefined {
  try {
    mkdirpSync(logsDir);
    pruneOldLogs(logsDir);
    const ts = new Date().toISOString().replace(/[:.]/g, "-");
    const base = `${ts}-${label}-${process.pid}-${cmdSha.slice(0, 8)}`;
    for (let i = 0; i < 3; i++) {
      const p = join(logsDir, i === 0 ? `${base}.log` : `${base}-${i}.log`);
      try {
        const fd = openSync(p, "ax", 0o600);
        return { fd, path: p };
      } catch {}
    }
  } catch (e: any) {
    warn(`log setup failed (${e?.message ?? e}) — running unlogged`);
  }
  return undefined;
}

async function cmdRun(argv: string[]): Promise<number> {
  let label = "default";
  const li = argv.indexOf("--label");
  const sep = argv.indexOf("--");
  if (li >= 0 && li + 1 < argv.length && (sep < 0 || li < sep)) label = argv[li + 1];
  if (sep < 0 || sep + 1 >= argv.length) {
    console.error("usage: gstack-evidence run [--reuse [--max-age <hours>]] --label <L> -- <cmd...>");
    return 2;
  }
  const opts = argv.slice(0, sep);
  const reuse = opts.includes("--reuse") && !opts.includes("--no-reuse");
  const maxAgeAt = opts.indexOf("--max-age");
  const reuseMaxAge = maxAgeAt >= 0 ? Number(opts[maxAgeAt + 1]) : 24;
  if (!Number.isFinite(reuseMaxAge) || reuseMaxAge <= 0) {
    console.error(`gstack-evidence: --max-age must be a positive number of hours, got: ${JSON.stringify(opts[maxAgeAt + 1])}`);
    return 2;
  }
  const cmdArgv = argv.slice(sep + 1);
  // Compound/piped commands pass as ONE string via bash -c; a multi-token argv
  // runs directly. The hashed command string is exact, no normalization.
  const commandString = cmdArgv.length === 1 ? cmdArgv[0] : cmdArgv.join(" ");
  const shell = cmdArgv.length === 1 ? bashCommandInvocation(cmdArgv[0]) : null;
  const cmdSha = sha256(commandString);
  label = label.replace(/[^a-zA-Z0-9._-]/g, "_");

  // Bookkeeping context — every piece is optional; failures only warn.
  let paths: ReturnType<typeof ledgerPath> | undefined;
  try {
    paths = ledgerPath();
    mkdirpSync(paths.dir);
  } catch (e: any) {
    warn(`ledger setup failed (${e?.message ?? e}) — result will not be recorded`);
  }
  if (reuse && paths && reused(paths.file, label, cmdSha, reuseMaxAge)) return 0;
  const log = paths ? openLog(paths.logsDir, label, cmdSha) : undefined;

  // Fingerprint the content BEFORE the child runs: a working-tree edit made
  // DURING a long suite must not be certified as "the tested content".
  const wtreeBefore = currentWtree();

  const started = Date.now();
  let exitCode: number;
  let proc: ReturnType<typeof Bun.spawn> | undefined;
  try {
    if (shell && !shell.ok) throw new Error(shell.error);
    const spawnArgv = shell?.ok ? [shell.cmd, ...shell.argv] : cmdArgv;
    proc = Bun.spawn(spawnArgv, { stdin: "inherit", stdout: "pipe", stderr: "pipe", env: log ? { ...process.env, GSTACK_EVIDENCE_LOG: log.path } : process.env });
  } catch (e: any) {
    // Spawn failure (ENOENT on argv-direct form): record exit 127, propagate 127.
    exitCode = 127;
    warn(`spawn failed: ${e?.message ?? e}`);
    record(paths, log?.path, label, commandString, cmdSha, exitCode, started, wtreeBefore);
    return exitCode;
  }

  // Stream-tee: forward chunks as they arrive (never buffer — E2E logs are MBs).
  const tail = new OutputTail();
  let logBytes = 0;
  let truncated = false;
  const teeToLog = (chunk: Uint8Array) => {
    if (!log || truncated) return;
    try {
      if (logBytes + chunk.byteLength > LOG_MAX_BYTES) {
        const room = LOG_MAX_BYTES - logBytes;
        if (room > 0) writeSync(log.fd, chunk.subarray(0, room));
        writeSync(log.fd, Buffer.from("\n\n[gstack-evidence: log truncated at 2MB — output continued on console]\n"));
        truncated = true;
      } else {
        writeSync(log.fd, chunk);
        logBytes += chunk.byteLength;
      }
    } catch {
      truncated = true; // stop teeing on any write failure; console stream continues
      try {
        writeSync(log.fd, Buffer.from("\n\n[gstack-evidence: log ended early (write failure) — output continued on console]\n"));
      } catch {}
    }
  };
  const pump = async (stream: ReadableStream<Uint8Array> | undefined, out: NodeJS.WriteStream, origin: "stdout" | "stderr") => {
    if (!stream) return;
    for await (const chunk of stream) {
      // Honor backpressure: when the console consumer is slower than the child
      // (piped into a pager/log collector), wait for drain instead of queueing
      // unbounded chunks in the WriteStream buffer.
      if (!out.write(chunk)) {
        // Race drain against error: a dying consumer (EPIPE from `| head`)
        // never drains — resolve either way and stop forwarding on error.
        await new Promise<void>((r) => {
          const done = () => {
            out.off("drain", done);
            out.off("error", done);
            r();
          };
          out.once("drain", done);
          out.once("error", done);
        });
      }
      teeToLog(chunk);
      try {
        tail.push(chunk, origin);
      } catch (e: any) {
        warn(`output tail failed (${e?.message ?? e}) — tests_ran will be unknown`);
      }
    }
  };
  try {
    await Promise.all([pump(proc.stdout as any, process.stdout, "stdout"), pump(proc.stderr as any, process.stderr, "stderr")]);
    exitCode = await proc.exited;
    if (exitCode === null || exitCode === undefined) exitCode = 1;
  } catch (e: any) {
    warn(`stream error: ${e?.message ?? e}`);
    try {
      exitCode = await proc.exited;
    } catch {
      exitCode = 1;
    }
  } finally {
    if (log) {
      try {
        closeSync(log.fd);
      } catch {}
    }
  }

  // TRANSPARENCY INVARIANT: the parse runs AFTER the exit code is fixed and
  // can only change the receipt, never the code this wrapper returns.
  let testsRan: number | "unknown" = "unknown";
  try {
    testsRan = await parseTestsRan(tail.end());
  } catch (e: any) {
    warn(`tests_ran parse failed (${e?.message ?? e}) — recorded as unknown; the command result stands`);
  }
  record(paths, log?.path, label, commandString, cmdSha, exitCode, started, wtreeBefore, testsRan);
  return exitCode;
}

function record(
  paths: { dir: string; file: string } | undefined,
  logPath: string | undefined,
  label: string,
  commandString: string,
  cmdSha: string,
  exitCode: number,
  startedMs: number,
  wtreeBefore: string | undefined,
  testsRan: number | "unknown" = "unknown",
): void {
  if (!paths) return;
  try {
    const { command, redacted } = safeCommandForRecord(commandString);
    const rec: EvidenceRecord = {
      ts: new Date().toISOString(),
      label,
      command,
      cmd_sha256: cmdSha,
      exit: exitCode,
      duration_s: Math.round((Date.now() - startedMs) / 100) / 10,
      tests_ran: testsRan,
    };
    if (redacted) rec.redacted = true;
    const commit = git(["rev-parse", "HEAD"]);
    if (commit) {
      rec.commit = commit;
      rec.tree = git(["rev-parse", "HEAD^{tree}"]);
      rec.dirty = (git(["status", "--porcelain", "-uno"]) ?? "") !== "";
      // TOCTOU guard: the fingerprint is only trustworthy when the content was
      // IDENTICAL before and after the run. A mid-run edit omits wtree, so
      // check grades STALE instead of certifying content the suite never ran.
      const wtreeAfter = currentWtree();
      if (wtreeBefore && wtreeAfter && wtreeBefore === wtreeAfter) {
        rec.wtree = wtreeAfter;
        rec.identity = identityDigest();
      } else if (wtreeBefore || wtreeAfter) {
        const changed = wtreeBefore && wtreeAfter ? (git(["diff", "--name-only", wtreeBefore, wtreeAfter]) ?? "").split("\n").map((s) => s.trim()).filter(Boolean) : [];
        if (changed.length) rec.wtree_changed = changed.slice(0, 5);
        const named = changed.length ? `: ${changed.slice(0, 5).join(", ")}${changed.length > 5 ? ", ..." : ""}` : "";
        warn(`working-tree content changed during the run${named} — evidence recorded without a content fingerprint (will grade STALE)`);
      }
    }
    if (logPath) rec.log_path = logPath;
    appendJsonl(paths.file, rec, { mode: 0o600 });
    try {
      chmodSync(paths.file, 0o600);
    } catch {}
    // Summary line on stderr so calling agents get the exit + log path even
    // when the lane ran backgrounded. Never on stdout (stays transparent).
    console.error(`gstack-evidence: recorded label=${label} exit=${exitCode} tests_ran=${testsRan} log=${logPath ?? "-"}`);
  } catch (e: any) {
    warn(`ledger append failed (${e?.message ?? e}) — the command result stands`);
  }
}

/**
 * sha256 of the runtime a lane ran under: the bun and node on PATH, OS, architecture and runner image. The lockfiles and
 * pins the execution identity also names (lib/evidence-bundle.ts) are working-tree content, so the fingerprint binds them.
 */
function identityDigest(): string {
  const version = (b: string) => {
    const r = spawnSync(b, ["--version"], { encoding: "utf-8", timeout: 15000 });
    return r.status === 0 ? (r.stdout || "").trim().replace(/^v/, "") || null : null;
  };
  return sha256(JSON.stringify({ bun: version("bun"), node: version("node"), os: process.platform, arch: process.arch, image: process.env.GSTACK_RUNNER_IMAGE || null }));
}

/**
 * `run --reuse`: the newest local row for this label, command and working tree decides. A counted pass under the same
 * identity within the max age is copied (original ts kept) and printed as a run would be; anything else runs the command.
 */
function reused(file: string, label: string, cmdSha: string, maxAgeHours: number): boolean {
  const wtree = currentWtree();
  if (!wtree) return false;
  let records: EvidenceRecord[] = [];
  try {
    records = readJsonl<EvidenceRecord>(file);
  } catch {
    return false;
  }
  const newest = records.findLast((r) => r.label === label && r.cmd_sha256 === cmdSha && r.wtree === wtree && r.source === undefined);
  if (!newest || newest.exit !== 0 || typeof newest.tests_ran !== "number" || newest.tests_ran <= 0) return false;
  const age = Date.now() - Date.parse(newest.ts);
  if (!(age >= 0 && age <= maxAgeHours * 3600_000)) return false;
  if (newest.identity !== identityDigest()) return false;
  try {
    appendJsonl(file, { ...newest, reused_from: newest.reused_from ?? newest.ts }, { mode: 0o600 });
  } catch (e: any) {
    warn(`ledger append failed (${e?.message ?? e}) — running the command instead`);
    return false;
  }
  console.error(`gstack-evidence: reused label=${label} tree=${wtree.slice(0, 12)} from=${newest.ts}`);
  console.error(`gstack-evidence: recorded label=${label} exit=0 tests_ran=${newest.tests_ran} log=${newest.log_path ?? "-"}`);
  return true;
}

/**
 * `record-ci`: carry a lane from CI. Its command must be a key of the base branch's ship_lanes_from; the run is found and
 * verified here (lib/ci-carry.ts) at HEAD's clean tree, so no caller supplies run ids, a test count or a tree. Never runs the lane.
 */
function cmdRecordCi(argv: string[]): number {
  const sep = argv.indexOf("--");
  const opts = sep < 0 ? argv : argv.slice(0, sep);
  const get = (name: string) => { const i = opts.indexOf(name); return i >= 0 ? opts[i + 1] : undefined; };
  const label = get("--label")?.replace(/[^a-zA-Z0-9._-]/g, "_");
  const base = get("--base");
  const command = sep < 0 ? "" : argv.slice(sep + 1).join(" ");
  if (!label || !base || !command || opts.length !== 4) {
    console.error("usage: gstack-evidence record-ci --label <L> --base <base> -- <command>");
    return 2;
  }
  const none = (reason: string, detail: string) => {
    console.error(`CARRY_NONE: ${reason}: ${detail}`);
    console.error(`gstack-evidence record-ci: label=${label} not carried; nothing recorded`);
    return 1;
  };
  const cwd = process.cwd();
  const loaded = loadConfigFromBase(cwd, base);
  if (isConfigUnavailable(loaded)) return none("config_unavailable", loaded.detail);
  if (loaded.errors.length) return none("config_invalid", loaded.errors.map((x) => `${x.path}: ${x.message}`).join("; "));
  const from = loaded.config.ship_lanes_from;
  if (!Object.prototype.hasOwnProperty.call(from, command)) return none("not_mapped", `the command is not a key of origin/${base}'s ship_lanes_from`);
  const m = from[command]!;
  const check = buildRunCheck(cwd, null, true, base);
  if ("error" in check) return none("profiles_unavailable", check.error);
  const head = git(["rev-parse", "HEAD"]);
  const tree = git(["rev-parse", "HEAD^{tree}"]);
  if (!head || !tree) return none("no_head", "HEAD is unreadable");
  const wtree = () => { const fp = wtreeFingerprint({ cwd, timeoutMs: 30000 }); return "tree" in fp ? fp.tree : null; };
  const v = findCarry(check, { profiles: m.profiles, head, tree, wtree, inventory: () => runInventory(m.inventory, cwd) });
  if (!v.ok) return none(v.reason, v.detail);
  let paths: ReturnType<typeof ledgerPath>;
  try {
    paths = ledgerPath();
    mkdirpSync(paths.dir);
  } catch (e: any) {
    console.error(`gstack-evidence record-ci: ledger setup failed (${e?.message ?? e}); nothing recorded`);
    return 1;
  }
  const runs = v.runs.map((r) => `${r.run_id}/${r.run_attempt}`);
  const rec: EvidenceRecord = {
    ts: new Date(v.runs.map((r) => r.finished_at).sort()[0]!).toISOString(), label, command, cmd_sha256: sha256(command), exit: 0, duration_s: 0,
    commit: head, tree, dirty: false, wtree: tree, tests_ran: v.tests, source: "ci", runs, profiles: m.profiles, policy: loaded.label,
  };
  appendJsonl(paths.file, rec, { mode: 0o600 });
  console.error(`gstack-evidence: recorded label=${label} exit=0 tests_ran=${v.tests} log=- source=ci runs=${runs.join(",")} policy=${loaded.label}`);
  return 0;
}

/** `carried`: each label's newest row when it is a CI-sourced row at the current working tree, as the receipt's ci_carried entries. */
function cmdCarried(argv: string[]): number {
  let records: EvidenceRecord[] = [];
  try {
    records = readJsonl<EvidenceRecord>(ledgerPath().file);
  } catch {
    records = [];
  }
  const wtree = currentWtree();
  const latest = new Map<string, EvidenceRecord>();
  for (const r of records) latest.set(r.label, r);
  const carried = [...latest.values()].filter((r) => r.source === "ci" && !!wtree && r.wtree === wtree && Array.isArray(r.runs))
    .flatMap((r) => r.runs!.map((ref) => { const [run, attempt] = ref.split("/").map(Number); return { lane: r.label, run, attempt, tree: r.wtree! }; }));
  if (argv.includes("--json")) console.log(JSON.stringify(carried));
  else for (const c of carried) console.log(`CI_CARRIED: ${c.lane} run=${c.run}/${c.attempt} tree=${c.tree.slice(0, 12)}`);
  return 0;
}

function cmdCheck(argv: string[]): number {
  // Parse: repeated --label, each optionally followed (anywhere later) by its
  // own --expect-cmd; pairing is positional — an --expect-cmd binds to the most
  // recent --label before it.
  const wanted: { label: string; expectCmd?: string }[] = [];
  let all = false;
  let maxAgeHours: number | undefined;
  let allowPaths: string[] = [];
  for (let i = 0; i < argv.length; i++) {
    const a = argv[i];
    if (a === "--label") wanted.push({ label: argv[++i] ?? "" });
    else if (a === "--expect-cmd") {
      if (wanted.length === 0) {
        console.error("gstack-evidence: --expect-cmd requires a preceding --label");
        return 2;
      }
      wanted[wanted.length - 1].expectCmd = argv[++i] ?? "";
    } else if (a === "--all") all = true;
    else if (a === "--max-age") {
      maxAgeHours = Number(argv[++i]);
      if (!Number.isFinite(maxAgeHours) || maxAgeHours <= 0) {
        // A typo must never silently drop the age gate (fail open) on a
        // freshness checker: it is a usage error.
        console.error(`gstack-evidence: --max-age must be a positive number of hours, got: ${JSON.stringify(argv[i])}`);
        return 2;
      }
    }
    else if (a === "--allow-paths") allowPaths = (argv[++i] ?? "").split(",").map((s) => s.trim()).filter(Boolean);
  }
  if (!all && wanted.length === 0) {
    console.error("usage: gstack-evidence check [--label <L> [--expect-cmd <s>]]... | --all  [--max-age <hrs>] [--allow-paths <csv>]");
    return 2;
  }

  let records: EvidenceRecord[] = [];
  try {
    records = readJsonl<EvidenceRecord>(ledgerPath().file);
  } catch {
    records = [];
  }

  const labels = all
    ? [...new Set(records.map((r) => r.label))].map((label) => ({ label, expectCmd: undefined as string | undefined }))
    : wanted;
  if (all && labels.length === 0) {
    console.log("EVIDENCE: MISSING (ledger empty — no labels recorded)");
    return 1;
  }

  const wtreeNow = currentWtree();
  let allFresh = true;
  for (const { label, expectCmd } of labels) {
    const latest = records.findLast((r) => r.label === label);
    if (!latest) {
      console.log(`EVIDENCE: MISSING label=${label}`);
      allFresh = false;
      continue;
    }
    const testsRan = typeof latest.tests_ran === "number" ? latest.tests_ran : "unknown";
    const changedDuringRun = Array.isArray(latest.wtree_changed) ? latest.wtree_changed.filter((p): p is string => typeof p === "string" && p !== "" && !/[\u0000-\u001f\u007f]/.test(p)).slice(0, 5) : [];
    const ci = latest.source === "ci" && Array.isArray(latest.runs) ? ` source=ci runs=${latest.runs.filter((s) => /^\d+\/\d+$/.test(s)).join(",")}` : "";
    const detail = `label=${label} exit=${latest.exit} tests_ran=${testsRan} ts=${latest.ts}${latest.log_path ? ` log=${latest.log_path}` : ""}${ci}`;
    let verdict: "FRESH" | "STALE" | "ZERO-RUN" = "FRESH";
    let reason = "";
    if (latest.exit !== 0) {
      verdict = "STALE";
      reason = "recorded run failed";
    } else if (testsRan === 0) {
      // Zero-run green: exit 0 with nothing executed (all skipped, empty
      // selection, "No tests found"). Graded like STALE under its own label;
      // "unknown" (no recognised runner summary) stays non-blocking.
      verdict = "ZERO-RUN";
      reason = "runner reported 0 executed tests";
    } else if (maxAgeHours !== undefined) {
      const ageMs = Date.now() - Date.parse(latest.ts);
      if (!(ageMs >= 0 && ageMs <= maxAgeHours * 3600 * 1000)) {
        verdict = "STALE";
        reason = `older than ${maxAgeHours}h`;
      }
    }
    if (verdict === "FRESH" && expectCmd !== undefined && sha256(expectCmd) !== latest.cmd_sha256) {
      verdict = "STALE";
      reason = "command changed (cmd_sha256 mismatch)";
    }
    if (verdict === "FRESH") {
      // Content binding: identical working-tree fingerprint, or a diff confined
      // to the allow-list. Any git failure (gc'd tree, not a repo) → STALE —
      // never an error into the calling flow.
      if (!latest.wtree || !/^[0-9a-f]{40}$/.test(latest.wtree) || !wtreeNow) {
        // Stored fingerprints are re-validated before reaching git argv — a
        // forged/corrupt ledger line must degrade, never inject options.
        verdict = "STALE";
        reason = !latest.wtree
          ? changedDuringRun.length
            ? `content changed during the run: ${changedDuringRun.join(", ")}`
            : "record has no content fingerprint"
          : !/^[0-9a-f]{40}$/.test(latest.wtree)
            ? "record has malformed fingerprint"
            : "current fingerprint unavailable";
      } else if (latest.wtree !== wtreeNow) {
        const diff = git(["diff", "--name-only", latest.wtree, wtreeNow]);
        if (diff === undefined) {
          verdict = "STALE";
          reason = "content changed (fingerprint diff unavailable)";
        } else {
          const changed = diff.split("\n").map((s) => s.trim()).filter(Boolean);
          const outside = changed.filter((f) => !allowPaths.some((a) => f === a || f.startsWith(a.replace(/\/$/, "") + "/")));
          if (changed.length === 0 || outside.length === 0) {
            reason = changed.length ? `diff confined to allow-paths (${changed.length} file(s))` : "";
          } else {
            verdict = "STALE";
            reason = `content changed: ${outside.slice(0, 5).join(", ")}${outside.length > 5 ? ", ..." : ""}`;
          }
        }
      }
    }
    console.log(`EVIDENCE: ${verdict} ${detail}${reason ? ` reason=${reason}` : ""}`);
    if (verdict !== "FRESH") allFresh = false;
  }
  return allFresh ? 0 : 1;
}

/** C3: export the ledger's latest record per label plus the execution identity as a portable bundle. */
function cmdBundle(argv: string[]): number {
  const labels: string[] = [];
  const selections: Record<string, string> = {};
  const runUrls: Record<string, string> = {};
  let out: string | undefined;
  let required: string[] | undefined;
  let imported: Record<string, unknown>[] = [];
  let base: string | undefined;
  const kv = (into: Record<string, string>, raw: string) => { const i = raw.indexOf("="); if (i > 0) into[raw.slice(0, i)] = raw.slice(i + 1); };
  for (let i = 0; i < argv.length; i++) {
    const a = argv[i];
    if (a === "--label") labels.push(argv[++i] ?? "");
    else if (a === "--out") out = argv[++i];
    else if (a === "--require") required = (argv[++i] ?? "").split(",").map((s) => s.trim()).filter(Boolean);
    else if (a === "--selection") kv(selections, argv[++i] ?? "");
    else if (a === "--run-url") kv(runUrls, argv[++i] ?? "");
    else if (a === "--base") base = argv[++i];
    else if (a === "--import") {
      try { const parsed = JSON.parse(readFileSync(argv[++i] ?? "", "utf-8")); imported = Array.isArray(parsed) ? parsed : [parsed]; }
      catch (e: any) { console.error(`gstack-evidence bundle: --import unreadable (${e?.message ?? e})`); return 2; }
    }
  }
  if (!out) { console.error("usage: gstack-evidence bundle --out <file> [--label <L>]... [--require <csv>] [--selection L=<text>]... [--run-url L=<url>]... [--import <json>]"); return 2; }
  const repoRoot = git(["rev-parse", "--show-toplevel"]) ?? process.cwd();
  let records: Record<string, unknown>[] = [];
  try { records = readJsonl<Record<string, unknown>>(ledgerPath().file); } catch { records = []; }
  const policy = loadPolicyFromBase(repoRoot, resolveBaseBranch(repoRoot, base));
  const p = isUnavailable(policy) ? null : policy.policy;
  const head = versionAtRef(repoRoot, "HEAD");
  const comparison = {
    version_rel: "rel" in head ? head.rel : "VERSION", version: "version" in head ? head.version : null,
    changelog: p?.changelog ?? "CHANGELOG.md", stamp_paths: p?.stamp_paths ?? [], release_outputs: p?.release_outputs ?? [],
  };
  let gstackVersion: string | null = null;
  try { gstackVersion = readFileSync(join(BIN_DIR, "..", "VERSION"), "utf-8").trim(); } catch {}
  const built = buildBundle({ repoRoot, ledgerRecords: records, labels, required, selections, runUrls, imported, comparison, gstackVersion });
  for (const e of built.errors) console.error(resultLine("gstack-evidence bundle", e.code, e.message));
  if (!built.bundle) return 1;
  mkdirpSync(dirname(out));
  const { writeFileSync } = require("fs") as typeof import("fs");
  writeFileSync(out, JSON.stringify(built.bundle, null, 2) + "\n");
  const verified = built.bundle.lanes.filter((l) => l.verified).length;
  console.log(`EVIDENCE_BUNDLE: ${out} tree=${built.bundle.repo.tree} lanes=${built.bundle.lanes.length} verified=${verified} imported=${built.bundle.imported.length}${built.bundle.repo.dirty ? " dirty=yes (committed heads only; lanes on a dirty tree are not verified)" : ""}`);
  return built.errors.length ? 1 : 0;
}

/** C7: every preregistration sha must be an ancestor of HEAD. */
function cmdAncestor(argv: string[]): number {
  const repoRoot = git(["rev-parse", "--show-toplevel"]) ?? process.cwd();
  let shas = argv.filter((a) => !a.startsWith("--") && argv[argv.indexOf(a) - 1] !== "--base");
  if (argv.includes("--from-policy")) {
    const loaded = loadPolicyFromBase(repoRoot, resolveBaseBranch(repoRoot, argv[argv.indexOf("--base") + 1]));
    if (isUnavailable(loaded)) { console.error(resultLine("gstack-evidence ancestor", "POLICY_SOURCE_UNAVAILABLE", loaded.detail)); return 3; }
    shas = [...shas, ...loaded.policy.preregistration_shas];
  }
  if (shas.length === 0) { console.log("ANCESTOR: none (no preregistration_shas)"); return 0; }
  const results = checkAncestors(repoRoot, shas);
  for (const r of results) {
    if (r.ok) console.log(`ANCESTOR: ok ${r.sha} (${r.detail})`);
    else console.log(`ANCESTOR: missing ${r.sha} (${r.detail}) — fix: merge or rebase so it is in the branch history, or drop it from the policy (PREREGISTRATION_NOT_ANCESTOR)`);
  }
  return results.every((r) => r.ok) ? 0 : 1;
}

/** E2: rerun each lane's probe on the bundle's tree, or mark each claim from this machine's ledger. */
function cmdVerify(argv: string[]): number {
  const file = argv.find((a, i) => !a.startsWith("--") && argv[i - 1] !== "--out");
  if (!file) { console.error("usage: gstack-evidence verify <bundle.json> [--rerun] [--out <file>] [--json]"); return 2; }
  const read = readBundle(file);
  if (!read.bundle) { console.error(resultLine("gstack-evidence verify", read.error!.code, read.error!.message)); return 1; }
  const repoRoot = git(["rev-parse", "--show-toplevel"]) ?? process.cwd();
  let records: Record<string, unknown>[] = [];
  try { records = readJsonl<Record<string, unknown>>(ledgerPath().file); } catch { records = []; }
  const v = verifyBundle({ repoRoot, bundle: read.bundle, bundlePath: file, rerun: argv.includes("--rerun"), ledgerRecords: records });
  const outIdx = argv.indexOf("--out");
  if (outIdx >= 0 && argv[outIdx + 1]) {
    const { writeFileSync } = require("fs") as typeof import("fs");
    mkdirpSync(dirname(argv[outIdx + 1]!));
    writeFileSync(argv[outIdx + 1]!, JSON.stringify({ ...read.bundle, verification: v }, null, 2) + "\n");
  }
  if (argv.includes("--json")) console.log(JSON.stringify(v)); else process.stdout.write(renderVerification(v));
  for (const c of v.claims) if (c.verdict === "unverified" && c.required) console.error(resultLine("gstack-evidence verify", "EVIDENCE_UNVERIFIED", `${c.label}: ${c.reason}`));
  return v.required_unverified.length ? 1 : 0;
}

const [, , sub, ...rest] = process.argv;
try {
  if (sub === "run") {
    process.exit(await cmdRun(rest));
  } else if (sub === "record-ci") {
    process.exit(cmdRecordCi(rest));
  } else if (sub === "carried") {
    process.exit(cmdCarried(rest));
  } else if (sub === "check") {
    process.exit(cmdCheck(rest));
  } else if (sub === "bundle") {
    process.exit(cmdBundle(rest));
  } else if (sub === "ancestor") {
    process.exit(cmdAncestor(rest));
  } else if (sub === "verify") {
    process.exit(cmdVerify(rest));
  } else {
    console.error("usage: gstack-evidence run|record-ci|carried|check|bundle|ancestor|verify ...");
    process.exit(2);
  }
} catch (e: any) {
  // Never let the wrapper's own failure look like a command failure in a way
  // that breaks a skill flow: `run` propagates the child's code from inside
  // cmdRun; reaching here means bookkeeping blew up outside it.
  warn(`unexpected error: ${e?.message ?? e}`);
  process.exit(1);
}