@mmerterden/multi-agent-pipeline 20.2.1 → 20.3.0

package/pipeline/scripts/review-decision-gate.mjs

@@ -0,0 +1,403 @@
+#!/usr/bin/env node
+/**
+ * review-decision-gate.mjs  -  a blocking finding needs more than one model's
+ * opinion before it stops an autopilot run.
+ *
+ * Every reviewer on Claude Code is a Claude model, so a panel shares its blind
+ * spots and a single reviewer's blocker is a judgement nobody independent has
+ * checked. With the quality gates active (lib/unattended.mjs, gatesActive), an
+ * `accepted[]` finding of severity `blocking` keeps that severity only when:
+ *
+ *   corroborated   at least two independent reviewer outputs of the iteration
+ *                  carry a blocking finding that is the same finding (below);
+ *   failing-test   its `verification` (Step 3.7, verify-by-test) is
+ *                  `confirmed` and `evidencePath` is a non-empty log inside the
+ *                  checkout that shows a failing test and no pass;
+ *   test-integrity it is the finding test-integrity-gate.mjs produced for that
+ *                  file, which is a command's output and not a model's.
+ *
+ * Anything else is lowered to `important`, stays in `accepted[]` (triage judged
+ * it real and in scope, so the rework still fixes it) and is listed with its
+ * reason in the report and in the ledger entry. `approved` is recomputed.
+ *
+ * The same finding: the same file (diff prefixes stripped) and either the same
+ * fingerprint (finding-fingerprint.mjs: file plus ruleId, else file plus the
+ * normalized issue text) or cited lines at most LINE_WINDOW apart, where a
+ * whole-file finding (line 0) matches by fingerprint only and two findings
+ * citing different ruleIds or different CWEs never match. Independence is one
+ * entry of `state.reviewIterations[i].reviewers[]` (or one `--source` file):
+ * a separate dispatch that saw the diff and not the other outputs.
+ *
+ * Step 2.5, the rebuttal round, shows each reviewer the others' findings and
+ * replaces its output, which is how reviewers converge on each other. With the
+ * gates active a reviewer entry with `roundCount` above 1 fails the gate (exit
+ * 1, nothing rewritten); `--rebuttal-allowed` is the check Step 2.5 runs before
+ * dispatching the round.
+ *
+ * The verdict is recorded as `review-decision` through gate-ledger.mjs. With
+ * the gates off the decisions are printed marked advisory, the exit is 0 and
+ * neither the triage file nor the state is written.
+ *
+ * Usage:
+ *   review-decision-gate.mjs <triage.json> [--state <agent-state.json>] [--iteration <n>]
+ *                            [--source <reviewer-output.json>]... [--integrity <test-integrity.json>]
+ *                            [--repo <dir>] [--dry-run] [--json]
+ *   review-decision-gate.mjs --rebuttal-allowed [--state <agent-state.json>] [--json]
+ *
+ * Exit (gates active): 0 decided · 1 a rebuttal round ran, or --rebuttal-allowed refused ·
+ * 2 usage · 3 unreadable input, or an accepted blocker with no reviewer record (an empty
+ * `reviewers: []` is no record). A missing or empty --integrity file is no findings,
+ * and a missing or empty --source is an audit that did not run.
+ * Attended: 0, and 2 on a usage error.
+ *
+ * @module pipeline/scripts/review-decision-gate
+ */
+
+import { existsSync, readFileSync, realpathSync, statSync, writeFileSync } from "node:fs";
+import { isAbsolute, join, relative, resolve } from "node:path";
+
+import { invokedDirectly } from "../lib/invoked-directly.mjs";
+import { findingFingerprint, FINGERPRINT_RE, normalizeFile } from "./_fingerprint.mjs";
+import { compileMarkers, getAdapter, resolveStack } from "./_stack-adapter.mjs";
+import { gateContext, recordQuietly } from "./gate-ledger.mjs";
+import { summarize } from "./test-summary.mjs";
+
+export const GATE = "review-decision";
+export const LINE_WINDOW = 3;
+const FAILURE_MARKER = /\bFAILED\b|✗|\b[1-9][0-9]*\s+(?:failures?|failing|failed)\b/;
+
+function fingerprintOf(f) {
+  return typeof f?.fingerprint === "string" && FINGERPRINT_RE.test(f.fingerprint)
+    ? f.fingerprint
+    : findingFingerprint(f);
+}
+
+function category(f) {
+  if (typeof f?.ruleId === "string" && f.ruleId.trim()) return `rule:${f.ruleId.trim()}`;
+  if (typeof f?.security?.cwe === "string") return `cwe:${f.security.cwe}`;
+  return null;
+}
+
+/**
+ * @param {object} a
+ * @param {object} b
+ * @returns {boolean}
+ */
+export function sameFinding(a, b) {
+  if (normalizeFile(a?.file) !== normalizeFile(b?.file)) return false;
+  if (fingerprintOf(a) === fingerprintOf(b)) return true;
+  const ca = category(a);
+  const cb = category(b);
+  if (ca && cb && ca !== cb) return false;
+  const la = Number.isInteger(a?.line) ? a.line : 0;
+  const lb = Number.isInteger(b?.line) ? b.line : 0;
+  return la > 0 && lb > 0 && Math.abs(la - lb) <= LINE_WINDOW;
+}
+
+function real(p) {
+  try {
+    return realpathSync(p);
+  } catch {
+    return resolve(p);
+  }
+}
+
+function failureMarkers(root) {
+  const list = [FAILURE_MARKER];
+  try {
+    for (const { id } of resolveStack(root).adapters) {
+      const m = compileMarkers(getAdapter(id), "test");
+      if (m) list.push(...m.failure);
+    }
+  } catch {
+    // An unreadable adapter file leaves the generic marker.
+  }
+  return list;
+}
+
+/**
+ * Does the log at `path` show a failing test?
+ *
+ * @param {string} path  relative to `root`, or absolute inside it
+ * @param {string} root  the checkout
+ * @returns {{ok: boolean, reason: string}}
+ */
+export function evidenceFromLog(path, root) {
+  if (typeof path !== "string" || !path.trim()) {
+    return { ok: false, reason: "no evidencePath recorded" };
+  }
+  const abs = isAbsolute(path) ? path : join(root, path);
+  if (!existsSync(abs)) return { ok: false, reason: `evidence log ${path} does not exist` };
+  const rel = relative(real(root), real(abs));
+  if (rel.startsWith("..") || isAbsolute(rel)) {
+    return { ok: false, reason: `evidence log ${path} is outside the checkout` };
+  }
+  let body;
+  try {
+    if (statSync(abs).size === 0) return { ok: false, reason: `evidence log ${path} is empty` };
+    body = readFileSync(abs, "utf8");
+  } catch (err) {
+    return { ok: false, reason: `evidence log ${path} is unreadable: ${err.message}` };
+  }
+  if (!body.trim()) return { ok: false, reason: `evidence log ${path} is empty` };
+  const summary = summarize(body, { source: path });
+  if (summary.status === "failed") {
+    return { ok: true, reason: `${path}: ${summary.failed} failed of ${summary.executed}` };
+  }
+  if (summary.status === "passed") {
+    return { ok: false, reason: `evidence log ${path} shows a pass (${summary.executed} passed)` };
+  }
+  if (summary.status === "no-tests") {
+    return { ok: false, reason: `evidence log ${path} shows no test executed` };
+  }
+  if (failureMarkers(root).some((re) => re.test(body))) {
+    return { ok: true, reason: `${path}: failure marker, counts unparsed` };
+  }
+  return { ok: false, reason: `evidence log ${path} shows no failing test` };
+}
+
+function blockingOf(output) {
+  const list = Array.isArray(output?.findings) ? output.findings : [];
+  return list.filter((f) => f && typeof f === "object" && f.severity === "blocking");
+}
+
+/**
+ * Did a rebuttal round replace any reviewer output?
+ * @param {object[]} reviewers
+ */
+export function rebuttalRecorded(reviewers) {
+  return (Array.isArray(reviewers) ? reviewers : []).some(
+    (r) => Number.isInteger(r?.roundCount) && r.roundCount > 1,
+  );
+}
+
+/**
+ * Apply the decision rule. Pure: the input is not mutated.
+ *
+ * @param {{triage: object, reviewers: object[], integrity?: object[], root: string}} input
+ * @returns {{triage: object, kept: object[], downgraded: object[]}}
+ */
+export function decide({ triage, reviewers, integrity = [], root }) {
+  const next = structuredClone(triage);
+  const sources = (Array.isArray(reviewers) ? reviewers : []).map(blockingOf);
+  const gateFindings = (Array.isArray(integrity) ? integrity : []).filter(
+    (f) => f && f.tag === "test_integrity",
+  );
+  const kept = [];
+  const downgraded = [];
+  for (const f of Array.isArray(next.accepted) ? next.accepted : []) {
+    if (!f || f.severity !== "blocking") continue;
+    const id = {
+      fingerprint: fingerprintOf(f),
+      file: f.file,
+      line: f.line,
+      issue: f.issue,
+    };
+    const count = sources.filter((list) => list.some((raw) => sameFinding(f, raw))).length;
+    if (count >= 2) {
+      kept.push({ ...id, basis: "corroborated", sources: count });
+      continue;
+    }
+    if (gateFindings.some((g) => normalizeFile(g.file) === normalizeFile(f.file))) {
+      kept.push({ ...id, basis: "test-integrity", sources: count });
+      continue;
+    }
+    const v = f.verification;
+    let evidence = null;
+    if (v && v.result === "confirmed") {
+      evidence = evidenceFromLog(v.evidencePath, root);
+      if (evidence.ok) {
+        kept.push({ ...id, basis: "failing-test", sources: count, evidence: evidence.reason });
+        continue;
+      }
+    }
+    const why = [
+      `raised by ${count} reviewer${count === 1 ? "" : "s"}, two needed`,
+      evidence
+        ? `verify-by-test evidence rejected: ${evidence.reason}`
+        : "no failing test recorded (verify-by-test)",
+    ].join("; ");
+    f.severity = "important";
+    downgraded.push({ ...id, sources: count, reason: `lowered to important: ${why}` });
+  }
+  next.approved = !(next.accepted || []).some((f) => f?.severity === "blocking");
+  return { triage: next, kept, downgraded };
+}
+
+// ---------------------------------------------------------------------------
+// CLI
+
+function readJson(p, what) {
+  try {
+    return JSON.parse(readFileSync(p, "utf8"));
+  } catch (err) {
+    throw new Error(`cannot read ${what} ${p}: ${err.message}`, { cause: err });
+  }
+}
+
+/**
+ * Step 1.76's findings. No flag, no file or an empty file is the gate's own
+ * "no findings" output; a file with content that is not JSON is unreadable.
+ */
+function readIntegrity(p) {
+  if (!p || !existsSync(p)) return [];
+  let body;
+  try {
+    body = readFileSync(p, "utf8");
+  } catch (err) {
+    throw new Error(`cannot read test-integrity output ${p}: ${err.message}`, { cause: err });
+  }
+  if (!body.trim()) return [];
+  try {
+    const doc = JSON.parse(body);
+    return Array.isArray(doc?.findings) ? doc.findings : [];
+  } catch (err) {
+    throw new Error(`cannot read test-integrity output ${p}: ${err.message}`, { cause: err });
+  }
+}
+
+function parse(argv) {
+  const opts = { source: [], json: false, dryRun: false, rebuttalAllowed: false, triage: null };
+  const single = new Set(["--state", "--iteration", "--integrity", "--repo"]);
+  for (let i = 0; i < argv.length; i++) {
+    const a = argv[i];
+    if (a === "--json") opts.json = true;
+    else if (a === "--dry-run") opts.dryRun = true;
+    else if (a === "--rebuttal-allowed") opts.rebuttalAllowed = true;
+    else if (a === "--source" || single.has(a)) {
+      const v = argv[++i];
+      if (v === undefined) throw new Error(`${a} needs a value`);
+      if (a === "--source") opts.source.push(v);
+      else opts[a.slice(2)] = v;
+    } else if (a.startsWith("--")) throw new Error(`unexpected argument ${a}`);
+    else if (opts.triage) throw new Error(`one triage file only, got ${a} too`);
+    else opts.triage = a;
+  }
+  if (!opts.rebuttalAllowed && !opts.triage) throw new Error("a triage file is required");
+  if (opts.iteration !== undefined && !/^[1-9][0-9]*$/.test(opts.iteration)) {
+    throw new Error("--iteration must be a positive integer");
+  }
+  return opts;
+}
+
+function reviewerRecord(opts, state) {
+  const iterations = Array.isArray(state?.reviewIterations) ? state.reviewIterations : [];
+  const at = opts.iteration ? Number(opts.iteration) - 1 : iterations.length - 1;
+  const fromState = Array.isArray(iterations[at]?.reviewers) ? iterations[at].reviewers : [];
+  const extra = opts.source
+    .filter((p) => existsSync(p) && readFileSync(p, "utf8").trim())
+    .map((p) => readJson(p, "reviewer output"));
+  const all = [...fromState, ...extra];
+  return all.length ? all : null;
+}
+
+function emit(json, result, stream) {
+  if (json) {
+    writeFileSync(1, `${JSON.stringify(result, null, 2)}\n`);
+    return;
+  }
+  const lines = [
+    `${GATE}${result.advisory ? " (advisory, the quality gates are off)" : ""}: ${result.summary}`,
+  ];
+  for (const d of result.downgraded || []) lines.push(`  ${d.file}:${d.line} ${d.reason}`);
+  writeFileSync(stream, `${lines.join("\n")}\n`);
+}
+
+async function main(argv) {
+  let opts;
+  try {
+    opts = parse(argv);
+  } catch (err) {
+    process.stderr.write(`review-decision-gate: ${err.message}\n`);
+    return 2;
+  }
+  const ctx = gateContext({ statePath: opts.state || null, repo: opts.repo || process.cwd() });
+  const advisory = !ctx.active;
+
+  if (opts.rebuttalAllowed) {
+    if (advisory) {
+      if (opts.json) writeFileSync(1, `${JSON.stringify({ rebuttalAllowed: true })}\n`);
+      return 0;
+    }
+    const why =
+      "the quality gates are active: reviewers stay blind to each other, Step 2.5 does not run";
+    if (opts.json) writeFileSync(1, `${JSON.stringify({ rebuttalAllowed: false, reason: why })}\n`);
+    else writeFileSync(1, `rebuttal round: off (${why})\n`);
+    return 1;
+  }
+
+  const state = ctx.state;
+  const worktree =
+    typeof state?.worktreePath === "string" && existsSync(state.worktreePath)
+      ? state.worktreePath
+      : null;
+  const root = opts.repo || worktree || process.cwd();
+
+  let result;
+  let decided = null;
+  try {
+    const triage = readJson(opts.triage, "the triage output");
+    if (!triage || typeof triage !== "object" || !Array.isArray(triage.accepted)) {
+      throw new Error(`${opts.triage} is not a triage output (no accepted[])`);
+    }
+    const reviewers = reviewerRecord(opts, state);
+    const integrity = readIntegrity(opts.integrity);
+    if (rebuttalRecorded(reviewers)) {
+      result = {
+        gate: GATE,
+        verdict: "rebuttal-round",
+        summary:
+          "a Step 2.5 rebuttal round replaced reviewer output; with the quality gates active reviewers stay blind to each other",
+      };
+    } else {
+      const blockers = triage.accepted.filter((f) => f?.severity === "blocking");
+      if (blockers.length && !reviewers) {
+        throw new Error(
+          "no reviewer record for this iteration (state.reviewIterations[].reviewers or --source), so no blocker can be checked for corroboration",
+        );
+      }
+      decided = decide({ triage, reviewers: reviewers || [], integrity, root });
+      result = {
+        gate: GATE,
+        verdict: "pass",
+        summary: `${blockers.length} blocking finding(s): ${decided.kept.length} kept, ${decided.downgraded.length} lowered to important`,
+        approved: decided.triage.approved,
+        kept: decided.kept,
+        downgraded: decided.downgraded,
+      };
+    }
+  } catch (err) {
+    result = { gate: GATE, verdict: "unreadable", summary: err.message };
+  }
+
+  if (advisory) {
+    emit(opts.json, { ...result, advisory: true }, 1);
+    return 0;
+  }
+
+  if (decided && !opts.dryRun)
+    writeFileSync(opts.triage, `${JSON.stringify(decided.triage, null, 2)}\n`);
+  const detail =
+    result.verdict === "pass"
+      ? {
+          kept: result.kept.length,
+          downgraded: result.downgraded.map(({ fingerprint, file, line, reason }) => ({
+            fingerprint,
+            file,
+            line,
+            reason,
+          })),
+        }
+      : { verdict: result.verdict, reason: result.summary };
+  await recordQuietly(GATE, result.verdict === "pass" ? "pass" : "fail", detail, {
+    repo: existsSync(root) ? root : null,
+    statePath: ctx.statePath,
+  });
+  emit(opts.json, result, result.verdict === "pass" ? 1 : 2);
+  if (result.verdict === "pass") return 0;
+  return result.verdict === "rebuttal-round" ? 1 : 3;
+}
+
+if (invokedDirectly(import.meta.url)) {
+  main(process.argv.slice(2)).then((code) => process.exit(code));
+}

package/pipeline/scripts/routine-registry.mjs

@@ -28,6 +28,7 @@
 import { existsSync, readFileSync, writeFileSync, mkdirSync, rmSync, renameSync } from "node:fs";
 import { join, dirname } from "node:path";
 import { runMain } from "../lib/fatal.mjs";
+import { hostCommand } from "../lib/user-facing.mjs";
 
 const NAME_RE = /^[a-z0-9][a-z0-9-]*$/;
 const MAX_NAME = 40;
@@ -59,7 +60,7 @@ function fail(msg) {
 }
 
 function homeDir(args) {
-  return args.home || process.env.HOME || process.env.USERPROFILE || "";
+  return args.home || process.env.HOME || "";
 }
 function prefsPath(home) {
   return join(home, ".claude", "multi-agent-preferences.json");
@@ -174,7 +175,9 @@ function cmdAdd(home, args) {
   prefs.global.routines = routines;
   writePrefs(home, prefs);
   console.log(`routine-registry: saved "${name}" -> ${join(dir, "SKILL.md")}`);
-  console.log("routine-registry: available as /multi-agent:" + name + " after a session reload");
+  console.log(
+    `routine-registry: available as ${hostCommand(name, import.meta.dirname)} after a session reload`,
+  );
 }
 
 function cmdRemove(home, name) {

package/pipeline/scripts/runs-index.mjs

@@ -22,9 +22,16 @@
  *
  * Read-only. Never writes, never migrates, never deletes.
  *
+ * The JSON is a contract (pipeline/schemas/runs-index.schema.json). Fields are
+ * only ever added: `subs` stays the count a reader already decodes, and the
+ * sub-steps themselves are `subList`. `--redact` drops every field the schema
+ * marks `x-sensitivity: local` - paths and the PR URL - and scrubs the free
+ * text a phase wrote into `now`, sub-step names and a pending question.
+ *
  * Usage:
  *   node runs-index.mjs                 # human table, grouped
  *   node runs-index.mjs --json          # the same records as JSON
+ *   node runs-index.mjs --json --redact # without the fields specific to this machine
  *   node runs-index.mjs --group waiting # one group only
  *   node runs-index.mjs --task-id <id>  # one run
  *
@@ -36,8 +43,10 @@
  */
 
 import { existsSync, readFileSync } from "node:fs";
+import { readRegularFile } from "../lib/regular-file.mjs";
 import { join } from "node:path";
 import { costUsd } from "./_cost.mjs";
+import { omit, scrub } from "./_redact.mjs";
 import { listRuns, logsRoot, resolveRunDir, taskIdVariants } from "./_run-paths.mjs";
 import { runMain } from "../lib/fatal.mjs";
 import { invokedDirectly } from "../lib/invoked-directly.mjs";
@@ -48,9 +57,24 @@ import { invokedDirectly } from "../lib/invoked-directly.mjs";
  * under an eight-phase contract, 4 under six), so a literal would survive a
  * renumbering unchanged and silently regroup every run.
  */
-const PHASE_WAITING_FROM = JSON.parse(
+const PHASE_CONTRACT = JSON.parse(
   readFileSync(new URL("../schemas/phases.json", import.meta.url), "utf8"),
-).thresholds.waitingFromPhase;
+);
+const PHASE_WAITING_FROM = PHASE_CONTRACT.thresholds.waitingFromPhase;
+
+/**
+ * The last phase id, so the Phase column reads "current/last" in the same
+ * numbering the run records use. Phases are numbered from 0, so this is one
+ * less than the phase count.
+ */
+const LAST_PHASE = PHASE_CONTRACT.phases[PHASE_CONTRACT.phases.length - 1].id;
+
+export const CONTRACT_VERSION = "1.1.0";
+
+const STATE_MAX_BYTES = 16 * 1024 * 1024;
+
+/** The run fields runs-index.schema.json marks x-sensitivity local. */
+export const LOCAL_RUN_FIELDS = ["dir", "worktreePath", "prUrl", "duplicateOf"];
 
 const GROUPS = {
   waiting: "Waiting on you",
@@ -60,10 +84,11 @@ const GROUPS = {
 };
 
 function parseArgs(argv) {
-  const flags = { json: false, group: null, taskId: null };
+  const flags = { json: false, redact: false, group: null, taskId: null };
   for (let i = 0; i < argv.length; i++) {
     const a = argv[i];
     if (a === "--json") flags.json = true;
+    else if (a === "--redact") flags.redact = true;
     else if (a === "--group") flags.group = argv[++i];
     else if (a.startsWith("--group=")) flags.group = a.slice(8);
     else if (a === "--task-id") flags.taskId = argv[++i];
@@ -84,9 +109,9 @@ function parseArgs(argv) {
 }
 
 function readJson(path) {
-  if (!path || !existsSync(path)) return null;
+  if (!path) return null;
   try {
-    return JSON.parse(readFileSync(path, "utf-8"));
+    return JSON.parse(readRegularFile(path, { maxBytes: STATE_MAX_BYTES }));
   } catch {
     // A truncated state file is a fact about the run, not a reason to refuse
     // the whole index. It surfaces as `stateReadable: false`.
@@ -134,10 +159,12 @@ function summarisePhases(tracker) {
   let usd = 0;
   const rows = phases.map((p) => {
     // phase-tracker.sh writes flat `tokens_in` / `tokens_out` / `tokens_cached`
-    // on each phase, not a nested `tokens` object.
-    const tin = Number(p.tokens_in ?? 0) || 0;
-    const tout = Number(p.tokens_out ?? 0) || 0;
-    const tcached = Number(p.tokens_cached ?? 0) || 0;
+    // on each phase, not a nested `tokens` object. Token counts are whole
+    // numbers in the contract, so a fractional value a writer produced is
+    // rounded here rather than handed to a decoder that reads an integer.
+    const tin = Math.round(Number(p.tokens_in ?? 0) || 0);
+    const tout = Math.round(Number(p.tokens_out ?? 0) || 0);
+    const tcached = Math.round(Number(p.tokens_cached ?? 0) || 0);
     tokensIn += tin;
     tokensOut += tout;
     tokensCached += tcached;
@@ -152,6 +179,13 @@ function summarisePhases(tracker) {
       completedAt: p.completed_at ?? null,
       now: p.now ?? null,
       subs: Array.isArray(p.subs) ? p.subs.length : 0,
+      subList: Array.isArray(p.subs)
+        ? p.subs.map((sub) => ({
+            id: String(sub?.id ?? ""),
+            name: sub?.name ?? "",
+            status: sub?.status ?? "pending",
+          }))
+        : [],
     };
   });
   return {
@@ -175,12 +209,37 @@ function groupOf(state) {
   const prUrl = state?.pr?.url ?? state?.prUrl ?? null;
   if (status === "awaiting_input" || status === "awaiting-user-test-main-checkout")
     return "waiting";
+  // A paused run names the step it re-enters. It is waiting on a person at any
+  // phase, and at phase 0 it must not read as a run left at intake, which the
+  // question group offers to garbage-collect.
+  if (state?.waitingFor) return "waiting";
   if (prUrl) return "waiting";
   if (Number.isFinite(phase) && phase >= PHASE_WAITING_FROM) return "waiting";
   if (Number.isFinite(phase) && phase === 0) return "question";
   return "stopped";
 }
 
+/**
+ * The question a run stopped on, in the shape answer-question.mjs accepts an
+ * answer to, or null. Only a run with `waitingFor: "question"` has one: a stale
+ * record left beside another pause is not a question anyone can answer.
+ *
+ * @param {object|null} state
+ */
+function questionOf(state) {
+  const q = state?.pendingQuestion;
+  if (state?.waitingFor !== "question" || !q || typeof q !== "object") return null;
+  return {
+    id: String(q.id ?? ""),
+    stepId: String(q.stepId ?? ""),
+    text: String(q.text ?? ""),
+    kind: q.kind === "multi-select" ? "multi-select" : "single-select",
+    options: Array.isArray(q.options)
+      ? q.options.map((o) => ({ id: String(o?.id ?? ""), label: String(o?.label ?? "") }))
+      : [],
+  };
+}
+
 /**
  * Every run, enriched, in one stable order.
  *
@@ -229,8 +288,13 @@ export function buildIndex() {
       worktreePath: state?.worktreePath ?? null,
       prUrl,
       autopilot: Boolean(state?.autopilot),
-      schemaVersion: state?.schemaVersion ?? null,
+      // agent-state.schema.json declares a string; a number a hand-edited
+      // state carries is printed as its string so the field keeps one type.
+      schemaVersion: state?.schemaVersion == null ? null : String(state.schemaVersion),
       rev: Number.isInteger(state?.rev) ? state.rev : null,
+      sessionId: typeof state?.sessionId === "string" ? state.sessionId : null,
+      waitingFor: typeof state?.waitingFor === "string" ? state.waitingFor : null,
+      pendingQuestion: questionOf(state),
       group: groupOf(state),
       phases: phases.phases,
       tokens: phases.tokens,
@@ -278,7 +342,7 @@ function renderHuman(records) {
       "  ID                              Phase  Status            Branch                    Age    ~USD",
     );
     for (const r of rows) {
-      const phase = r.currentPhase === null ? " -" : `${r.currentPhase}/7`;
+      const phase = r.currentPhase === null ? " -" : `${r.currentPhase}/${LAST_PHASE}`;
       out.push(
         "  " +
           [
@@ -306,34 +370,78 @@ function renderHuman(records) {
   return out.join("\n");
 }
 
+/**
+ * The --json envelope. Redaction is applied here, after grouping and
+ * filtering, so a redacted index and a full one list the same runs.
+ */
+export function envelope(records, { redact = false } = {}) {
+  const runs = redact
+    ? records.map((r) => ({
+        ...omit(r, LOCAL_RUN_FIELDS),
+        pendingQuestion: r.pendingQuestion && {
+          ...r.pendingQuestion,
+          text: scrub(r.pendingQuestion.text),
+          options: r.pendingQuestion.options.map((o) => ({ ...o, label: scrub(o.label) })),
+        },
+        phases: r.phases.map((p) => ({
+          ...p,
+          name: scrub(p.name),
+          now: p.now === null ? null : scrub(p.now),
+          subList: p.subList.map((sub) => ({ ...sub, name: scrub(sub.name) })),
+        })),
+      }))
+    : records;
+  const out = { contractVersion: CONTRACT_VERSION };
+  if (!redact) out.logsRoot = logsRoot();
+  out.count = runs.length;
+  out.runs = runs;
+  return out;
+}
+
+/** The group names --group accepts. */
+export const GROUP_NAMES = Object.keys(GROUPS);
+
+/**
+ * The records one invocation selects: every run, one task id, or one group.
+ * `found` is false only when a task id was asked for and no run carries it.
+ * The CLI and contract-server.mjs both call this, so a filter means the same
+ * thing on either carrier.
+ *
+ * @param {{taskId?: string|null, group?: string|null}} [opts]
+ * @returns {{found: boolean, records: object[]}}
+ */
+export function selectRuns({ taskId = null, group = null } = {}) {
+  let records = buildIndex();
+  if (taskId) {
+    const wanted = new Set(taskIdVariants(taskId));
+    records = records.filter((r) => wanted.has(r.taskId));
+    if (!records.length) return { found: false, records };
+  }
+  if (group) records = records.filter((r) => r.group === group);
+  return { found: true, records };
+}
+
 function main() {
   const flags = parseArgs(process.argv.slice(2));
   if (flags.help) {
     process.stdout.write(
-      "Usage: runs-index.mjs [--json] [--group waiting|stopped|question|unknown] [--task-id <id>]\n",
+      "Usage: runs-index.mjs [--json [--redact]] [--group waiting|stopped|question|unknown] [--task-id <id>]\n",
     );
     return 0;
   }
 
-  let records = buildIndex();
-
-  if (flags.taskId) {
-    const wanted = new Set(taskIdVariants(flags.taskId));
-    records = records.filter((r) => wanted.has(r.taskId));
-    if (!records.length) {
-      const dir = resolveRunDir(flags.taskId);
-      process.stderr.write(
-        `runs-index: no run for ${flags.taskId}${dir ? ` (directory ${dir} has no markers)` : ""}\n`,
-      );
-      return 0;
-    }
+  const { found, records } = selectRuns(flags);
+  if (!found) {
+    const dir = resolveRunDir(flags.taskId);
+    process.stderr.write(
+      `runs-index: no run for ${flags.taskId}${dir ? ` (directory ${dir} has no markers)` : ""}\n`,
+    );
+    return 0;
   }
-  if (flags.group) records = records.filter((r) => r.group === flags.group);
 
   if (flags.json) {
     process.stdout.write(
-      JSON.stringify({ logsRoot: logsRoot(), count: records.length, runs: records }, null, 2) +
-        "\n",
+      JSON.stringify(envelope(records, { redact: flags.redact }), null, 2) + "\n",
     );
   } else {
     process.stdout.write(renderHuman(records) + "\n");