gstack/bin/gstack-review-dispatch

#!/usr/bin/env -S bun --no-env-file --config=/dev/null
/**
 * gstack-review-dispatch — /ship's reviewers get their briefs byte for byte and the parent changes
 * nothing they return (GSTA-167 no-loss gate; docs/review-policy.md#verbatim-dispatch).
 *
 *   gstack-review-dispatch render --role <role> [--name <n>] --out <dir> [slots]   write the brief, print its sha256
 *   gstack-review-dispatch sent --ledger <f> --role <role> [--name <n>] --sent <file>  the prompt actually passed; mismatch fails
 *   gstack-review-dispatch collect --ledger <f> --role <role> [--name <n>] --output <file> --merged <file>
 *   gstack-review-dispatch judge --ledger <f> --merged <file> --judged <file>        no drop, no downgrade
 *   gstack-review-dispatch verify --ledger <f> [--targeted-out <file>]               replay every hash and the judgment
 *   gstack-review-dispatch pass --base <b> --out <dir> --pass <id> [-- plan flags]  the pass's staged manifest
 *   gstack-review-dispatch show|stage|chunk|mark --manifest <f> ...                  one manifest step
 *   gstack-review-dispatch program [--ledger <f>]                                    the checked-in Capy pass program
 *
 * Logic: lib/review-brief.ts (rendering from the sections), lib/review-ledger.ts (ledger, collect, judge, verify),
 * lib/review-pass.ts (the staged manifest) and lib/capy-review-pass.js (the Capy program that runs it).
 */
import { spawnSync } from 'node:child_process';
import * as fs from 'node:fs';
import * as path from 'node:path';
import { EXIT, exitTableHelp } from '../lib/headless-artifacts';
import { BRIEF_ROLES, BriefError, briefFile, checkReviewedTree, checkoutRoot, checkoutTree, promptHash, renderBrief, sectionTexts, withWorkspace, type BriefRole, type Slots, type TreeCheck } from '../lib/review-brief';
import { cleanMarkers, collect, fixableRaises, mayBeUnavailable, parseFindings, readJsonl, readLedger, readerKey, recordJudgment, recordSent, appendEvent, verify, type JudgedLine, type MergedLine, type VerifyRow } from '../lib/review-ledger';
import { buildManifest, chunkCount, chunkOf, manifestPath, markReader, readManifest, renderStage, writeManifest, STAGES, type Extra, type Manifest, type PassReader, type ReaderState, type Stage } from '../lib/review-pass';
import type { Dispatch } from '../lib/review-depth';
import { runScriptSync } from '../lib/script-invocation';
import { TARGETED_RULES, parseClassList, targetedBriefSha, targetedRead } from '../lib/review-targeted';
import { resolveBaseBranch } from '../lib/ship-policy';
import { REVIEW_DIFF_MAX_BYTES, ceilingContext, disclosureDigest, disclosureLine, parseTail, readSelection, tooLargeLine, unreadableLine, type PlanExclude, type ReaderDiff } from '../lib/review-exclude';

const HELP = `gstack-review-dispatch — verbatim reviewer briefs and loss-free collection for /ship

  render --role <role> [--name <n>] --out <dir> [--ledger <f>] [slots]
      roles: ${BRIEF_ROLES.join(', ')}
      slots: --diff-base <sha> (every role but fix-check)  --exclude '<DIFF_CMD tail>'  --stack <s>  --test-fw <s>
             --keep '<DIFF_KEEP tail after <diff-base>>'  --disclosure '<the line every brief carries>' (both only under review_exclude_paths)
             --learnings-file <f>  --checklist <path> (default <root>/review/specialists/<name>.md; red-team.md for red-team)
             --checklists <a,b> (specialist-batched: the plan's checklists= names, or paths)  --findings-file <f> --specialists <n> (red-team)
             --fix-list <f> --hunks <f> --tests <f> [--callers <f>] (fix-check)
             --classes <money,gate,auth,secret> (targeted: the plan's TARGETED classes; the brief is review/specialists/targeted.md;
             --diff-base must be the merge base with --base, default origin/HEAD's branch, on every pass)
      writes <out>/<role>[-<name>].prompt.md, the brief followed by the workspace paragraph naming the toplevel of the
      checkout it runs in (the one its diff and merge base come from), records it in the ledger (default <out>/review-ledger.jsonl) and prints
      BRIEF: reader=<role/name> sha256=<h> bytes=<n> file=<path>. Pass that file's content as the reader's prompt, unchanged.
  sent --ledger <f> --role <role> [--name <n>] --sent <file>
      the exact prompt a dispatch passed: BRIEF_SENT: … match, or BRIEF_MISMATCH: … (exit 1; the pass is not reviewed)
  collect --ledger <f> --role <role> [--name <n>] --output <file> --merged <merged.jsonl> [--manifest <f>]
      the reader's raw output: hashes it and appends each finding to merged.jsonl with its label as written. A reply with
      no finding must carry its brief's clean marker (NO FINDINGS; the Recommendation: line for the voices); without one it is
      COLLECT_NOT_REVIEWED (exit 1): a refusal, an empty reply or a reader that never saw the diff, and verify reports NOT_COLLECTED
      until the brief is re-sent and answered with a review, which voids it. A reply whose REVIEWED_TREE line is missing or names
      another checkout or tree than its brief was rendered on is COLLECT_WRONG_TREE (COLLECT_TREE_MOVED when only the tree
      moved; exit 1, nothing merged, verify reports NOT_COLLECTED, and with --manifest <f> the reader becomes failed); the
      outside voice's, when it holds no finding, is recorded as unavailable coverage instead --unavailable '<reason>' (the outside voice only; refused when the
      output holds findings) records its failure text as missing coverage: COLLECT_UNAVAILABLE, and verify prints UNAVAILABLE and unavailable=N, never a review
  judge --ledger <f> --merged <merged.jsonl> --judged <judged.jsonl>
      judged lines {"id","severity","reason"?,"duplicate_of"?}: every merged id kept at its severity or above (a
      duplicate folds into one at least as severe); added and promoted findings need a reason. JUDGMENT: ok …, or
      JUDGMENT_REJECTED: dropped=… downgraded=… (exit 1)
  verify --ledger <f> [--targeted-out <file>]
      BRIEF, OUTPUT and JUDGE rows from the ledger alone, then VERIFY: clean (exit 0), VERIFY: dirty (exit 1) or
      VERIFY: no brief records (exit 3: this run's ledger kept no prompts). A ledger with a targeted brief also prints
      TARGETED_RECORD: and --targeted-out writes it as the JSON gstack-ship-receipt write --review-targeted reads; under
      review_exclude_paths prints REVIEW_EXCLUDE_RECORD: digest=<d> (the selection every reader's newest brief names: the
      value gstack-ship-receipt write --review-exclude takes), and a mixed set of digests makes it dirty
  pass --base <ref> --out <dir> --pass <id> [--ledger <f>] [--diff-base <sha>] [--learnings-file <f>] [--extras <json>] [--audit-only]
       [--checklist-root <dir>] [--fix-list <f> --hunks <f> --tests <f> [--callers <f>]] [-- <gstack-review-plan flags>]
      runs gstack-review-plan and writes <out>/pass-manifest.json: stage first (audit readers marked first in --extras),
      specialists (with the other --extras readers), red-team, voices (Step 11). Renders first and specialists now; prints
      the plan, MANIFEST: and one READER: line per reader. A plan whose NEXT is not full, scoped or fix-check prints PASS: none.
      A fix-check reader (stage specialists) renders from decision 3.5's --fix-list, --hunks, --tests and --callers files.
      --diff-base sets every reader's base, a scoped pass's Red Team included (the targeted reader keeps the merge base).
      An existing manifest for the same --pass is reused (resumed). --extras: [{"name","prompt_file","first"?,"model"?}]
      --audit-only skips the plan: the --extras readers are the whole pass (Step 14.5's docs audit)
      Before anything is written (and again before stage renders), each reviewer's diff is read once with a
      ${REVIEW_DIFF_MAX_BYTES}-byte ceiling: over it prints REVIEW_DIFF_TOO_LARGE with the largest folders and the fix for where the
      base policy's review_exclude_paths stands (exit 3); a git failure or timeout prints REVIEW_DIFF_UNREADABLE with the
      stderr written under --out (exit 1). render applies the same ceiling to the selection --exclude and --keep name
      whenever --diff-base is a commit here (always for the outside voice, whose brief embeds that selection).
  show --manifest <f>                         MANIFEST_JSON: <the manifest on one line>
  stage --manifest <f> --stage <first|specialists|red-team|voices>
      renders a stage; the Red Team only after every earlier reader is collected, its findings file being the
      specialists' merged.jsonl lines byte for byte
  chunk --manifest <f> --reader <r> --index <i>
      BRIEF_CHUNK: reader=… index=i of=n sha256=…, then one JSON string line of at most 65,536 brief characters
  mark --manifest <f> --reader <r> --state <intent|created|queued|collected|failed> [--path <p>] [--output <f>] [--error <e>]
      an audit reader is collected with --output, whose REVIEWED_TREE line must match its render (else failed, COLLECT_WRONG_TREE)
  mark --manifest <f> --before <tokens>,<credits> [--voices]   the pass's reading at its first dispatch; --voices keeps Step 11's own
  mark --manifest <f> --log-start <key> --token <t>   records a review-log start token once, so a rerun starts only what is missing
      reader states move forward only; intent is recorded before the subagent is created, its path right after
  program [--ledger <f>]
      PROGRAM: v<n> sha256=… bytes=…, then lib/capy-review-pass.js as one JSON string line (see the gstack Capy skill)
${exitTableHelp()}`;

const args = process.argv.slice(2);
const flag = (n: string) => { const i = args.indexOf(n); return i >= 0 ? args[i + 1] : undefined; };
const readFile = (f: string | undefined, what: string) => {
  if (!f) return undefined;
  try { return fs.readFileSync(f, 'utf8'); } catch { throw new BriefError(`cannot read ${what} file ${f}`); }
};
const ROOT = path.resolve(import.meta.dir, '..');

function render(): number {
  const role = flag('--role') as BriefRole | undefined;
  const out = flag('--out');
  if (!role || !BRIEF_ROLES.includes(role) || !out) { process.stderr.write(`gstack-review-dispatch render: needs --role <${BRIEF_ROLES.join('|')}> and --out <dir>\n`); return EXIT.usage; }
  const name = flag('--name');
  const diffBase = flag('--diff-base');
  const checklist = flag('--checklist') ?? (role === 'red-team' ? path.join(ROOT, 'review/specialists/red-team.md') : role === 'targeted' ? path.join(ROOT, 'review/specialists/targeted.md') : role === 'specialist' && name ? path.join(ROOT, 'review/specialists', `${name}.md`) : undefined);
  if (checklist && (role === 'specialist' || role === 'red-team' || role === 'targeted') && !fs.existsSync(checklist)) throw new BriefError(`checklist not found: ${checklist}`);
  const brief = role === 'targeted' ? readFile(checklist, 'targeted brief') : undefined;
  if (role === 'targeted') {
    const base = resolveBaseBranch(process.cwd(), flag('--base'));
    const mb = mergeBaseWith(base);
    const full = diffBase ? spawnSync('git', ['rev-parse', '--verify', '--quiet', `${diffBase}^{commit}`], { encoding: 'utf8', timeout: 30_000 }).stdout?.trim() : undefined;
    if (!full || full !== mb) throw new BriefError(`the targeted reader reads the whole diff on every pass: --diff-base must be the merge base with ${base} (${mb ?? 'unresolved'}), got ${diffBase ?? 'none'}`);
    if (!flag('--disclosure') && ceilingContext(process.cwd(), base).state === 'active') throw new BriefError(`${base}'s review_exclude_paths is active, so the targeted reader renders in the pass manifest's voices stage (gstack-review-dispatch stage --manifest <f> --stage voices), which carries the exclusion and its disclosure line`);
  }
  const checklists = flag('--checklists')?.split(',').map(s => s.trim()).filter(Boolean).map(c => (c.includes('/') ? c : path.join(ROOT, 'review/specialists', `${c}.md`)));
  for (const c of checklists ?? []) if (!fs.existsSync(c)) throw new BriefError(`checklist not found: ${c}`);
  let diff: string | undefined;
  const keepItems = parseTail(flag('--keep')).filter(s => s !== '--');
  const policyItems = parseTail(flag('--exclude')).filter(s => s.startsWith(':(top,exclude,glob)'));
  const resolvable = !!diffBase && git(['rev-parse', '--verify', '--quiet', `${diffBase}^{commit}`]) !== null;
  if (role !== 'fix-check' && diffBase && (resolvable || role === 'outside-voice')) {
    const over = ceiling('gstack-review-dispatch render', resolveBaseBranch(process.cwd(), flag('--base')), out, [{ reader: readerKey(role, name), exclude: flag('--exclude'), keep: keepItems }], diffBase, undefined);
    if (over) { process.stderr.write(over.line + '\n'); return over.exit; }
    if (role === 'outside-voice') diff = branchDiff(diffBase, { exclude: flag('--exclude'), keep: keepItems });
  }
  const slots: Slots = {
    name, diff_base: diffBase, exclude: flag('--exclude'), stack: flag('--stack'), test_fw: flag('--test-fw'),
    learnings: readFile(flag('--learnings-file'), 'learnings'), checklist, checklists: checklists?.join(','),
    findings: readFile(flag('--findings-file'), 'findings'), specialists: flag('--specialists'), diff,
    classes: flag('--classes'), brief,
    ...(flag('--disclosure') ? { disclosure: flag('--disclosure'), policy_exclude: policyItems.map(quote).join(' ') || undefined, keep: keepItems.map(quote).join(' ') || undefined } : {}),
    fix_list: readFile(flag('--fix-list'), 'fix list'), hunks: readFile(flag('--hunks'), 'hunks'), tests: readFile(flag('--tests'), 'tests'), callers: readFile(flag('--callers'), 'callers'),
  };
  const workdir = checkoutRoot();
  const tree = checkoutTree(workdir);
  if (!tree) throw new BriefError(`cannot read HEAD^{tree} and the toplevel of ${workdir}; a brief names the checkout its reply must prove`);
  const text = withWorkspace(renderBrief(role, slots, sectionTexts(ROOT)), workdir);
  fs.mkdirSync(out, { recursive: true, mode: 0o700 });
  const file = path.join(path.resolve(out), briefFile(role, name));
  fs.writeFileSync(file, text, { mode: 0o600 });
  const ledger = flag('--ledger') ?? path.join(out, 'review-ledger.jsonl');
  const sha = promptHash(text);
  const targeted = brief === undefined ? {} : { classes: parseClassList(flag('--classes')!), rules: TARGETED_RULES, brief_sha: targetedBriefSha(checklist), diff_base: diffBase ?? null, ...(diffBase ? targetedRead(process.cwd(), diffBase) : { patch_id: 'none', head: null }) };
  appendEvent(ledger, { event: 'rendered', reader: readerKey(role, name), role, name: name ?? null, file, sha256: sha, bytes: Buffer.byteLength(text), workdir, tree, ...targeted, ...(disclosureDigest(flag('--disclosure')) ? { exclude: disclosureDigest(flag('--disclosure')) } : {}) });
  process.stdout.write(`BRIEF: reader=${readerKey(role, name)} sha256=${sha} bytes=${Buffer.byteLength(text)} file=${file}\n`);
  return EXIT.ok;
}

const quote = (s: string) => `'${s.replace(/'/g, "'\\''")}'`;
const wrongTree = (reader: string, t: TreeCheck) => `${t.moved ? 'COLLECT_TREE_MOVED' : 'COLLECT_WRONG_TREE'}: reader=${reader} reported=${JSON.stringify(t.reported)} expected=${JSON.stringify(t.expected)} (${t.moved ? 'the checkout moved after this brief was rendered' : 'the reply did not review the checkout its brief named'}; nothing merged; restore it with a fresh pass under a new --pass and --out)\n`;

const PROGRAM_FILE = path.join(ROOT, 'lib', 'capy-review-pass.js');
const PROGRAM_VERSION = 1;
const git = (a: string[]) => { const r = spawnSync('git', a, { encoding: 'utf8', timeout: 60_000, maxBuffer: 256 * 1024 * 1024 }); return r.status === 0 ? r.stdout : null; };
const mergeBaseWith = (base: string) => [`origin/${base}`, base].map(ref => git(['merge-base', ref, 'HEAD'])?.trim()).find(Boolean);
const readerLine = (m: Manifest, r: PassReader) => `READER: ${r.reader} stage=${r.stage} state=${r.state} title="${r.title}"${r.sha256 ? ` sha256=${r.sha256} bytes=${r.bytes} chunks=${r.chunks}` : ''}${r.path ? ` path=${r.path}` : ''}`;
/** Each selection is read once per process: the ceiling check and the outside voice's embedded diff share it. */
const selections = new Map<string, ReaderDiff>();
const selectionOf = (base: string, exclude: string | undefined, keep: readonly string[] = []) => {
  const key = JSON.stringify([base, exclude ?? '', keep]);
  if (!selections.has(key)) selections.set(key, readSelection(process.cwd(), base, parseTail(exclude), keep));
  return selections.get(key)!;
};
const branchDiff = (base: string, r?: Pick<PassReader, 'exclude' | 'keep'>) => {
  const d = selectionOf(base, r?.exclude, r?.keep);
  if (!d.ok) throw new BriefError(`git diff ${base} failed`);
  return d.text;
};

/** The ceiling over every reader about to render: the first one over or unreadable stops the step before it writes anything else. */
function ceiling(context: string, base: string, outDir: string, readers: ReadonlyArray<Pick<PassReader, 'reader' | 'exclude' | 'keep' | 'diff_base' | 'prompt_file'> & { diff_base?: string }>, diffBase: string, known: PlanExclude | undefined): { exit: number; line: string } | null {
  for (const r of readers) {
    if (r.prompt_file) continue;
    const at = r.diff_base ?? diffBase;
    const d = selectionOf(at, r.exclude, r.keep);
    if (!d.ok) return { exit: EXIT.fail, line: unreadableLine(context, r.reader, d, at, base, outDir) };
    if (d.bytes > REVIEW_DIFF_MAX_BYTES) return { exit: EXIT.refused, line: tooLargeLine(context, r.reader, d, ceilingContext(process.cwd(), base, known)).line };
  }
  return null;
}

function pass(): number {
  const base = flag('--base'), out = flag('--out'), id = flag('--pass');
  if (!base || !out || !id || !/^[a-z0-9-]+$/.test(id)) { process.stderr.write('gstack-review-dispatch pass: needs --base <ref>, --out <dir> and --pass <id> (lowercase letters, digits, dashes)\n'); return EXIT.usage; }
  const file = manifestPath(out);
  if (fs.existsSync(file)) {
    const m = readManifest(file);
    if (m.pass !== id) throw new BriefError(`${file} belongs to pass ${m.pass}, not ${id}`);
    process.stdout.write([...m.plan_lines, `MANIFEST: file=${file} pass=${m.pass} readers=${m.readers.length} resumed`, ...m.readers.map(r => readerLine(m, r))].join('\n') + '\n');
    return EXIT.ok;
  }
  const planArgs = args.includes('--') ? args.slice(args.indexOf('--') + 1) : [];
  if (args.includes('--audit-only')) {
    const extrasFile = flag('--extras');
    if (!extrasFile) { process.stderr.write('gstack-review-dispatch pass --audit-only: needs --extras (the audit readers, e.g. Step 14.5\'s docs reader)\n'); return EXIT.usage; }
    const extras = JSON.parse(readFile(extrasFile, 'extras')!) as Extra[];
    const m = buildManifest({ pass: id, out, ledger: flag('--ledger') ?? path.join(out, 'review-ledger.jsonl'), base, diffBase: mergeBaseWith(base) ?? 'HEAD', root: git(['rev-parse', '--show-toplevel'])?.trim() ?? process.cwd(),
      checklistRoot: flag('--checklist-root') ?? ROOT, dispatches: [], next: 'audit', planLines: ['PASS: audit-only (no reviewer plan; its extras run as one batch)'], extras });
    fs.mkdirSync(m.out, { recursive: true, mode: 0o700 });
    const t = sectionTexts(ROOT);
    renderStage(m, 'first', t, branchDiff);
    renderStage(m, 'specialists', t, branchDiff);
    writeManifest(file, m);
    process.stdout.write([...m.plan_lines, `MANIFEST: file=${file} pass=${id} readers=${m.readers.length} audit-only`, ...m.readers.map(r => readerLine(m, r))].join('\n') + '\n');
    return EXIT.ok;
  }
  const plan = (json: boolean) => runScriptSync(path.join(ROOT, 'bin', 'gstack-review-plan'), ['--base', base, ...planArgs, ...(json ? ['--json'] : [])], { encoding: 'utf8', timeout: 180_000, maxBuffer: 64 * 1024 * 1024 });
  const text = plan(false);
  if (text.status !== 0) { process.stdout.write(text.stdout ?? ''); process.stderr.write(text.stderr ?? ''); return EXIT.fail; }
  const j = plan(true);
  if (j.status !== 0) { process.stderr.write(j.stderr ?? ''); return EXIT.fail; }
  const p = JSON.parse(j.stdout) as { next: { step: string }; dispatches: Dispatch[]; targeted?: { classes: string[] }; fix_range?: { base: string } | null; review_exclude?: Record<string, unknown> & { state: string; excluded?: number; kept_files?: unknown; references?: unknown } };
  const step = p.next.step;
  const fixChecks = step === 'fix-check' ? [] : p.dispatches.filter(d => d.role === 'fix-check');
  const planLines = [...text.stdout.trimEnd().split('\n'), ...fixChecks.map(d => `FIX_CHECK: planned effort=${d.effort} (Step 3.5 runs it on its own; not in this manifest)`)];
  if (step !== 'full' && step !== 'scoped' && step !== 'fix-check') { process.stdout.write([...planLines, `PASS: none next=${step} (no reviewer pass; follow NEXT)`].join('\n') + '\n'); return EXIT.ok; }
  const rangeBase = step === 'scoped' ? git(['rev-parse', '--verify', '--quiet', `${p.fix_range?.base ?? ''}^{commit}`])?.trim() : undefined;
  if (step === 'scoped' && !rangeBase) throw new BriefError('a scoped plan names no readable fix range base');
  const mergeBase = mergeBaseWith(base);
  const diffBase = flag('--diff-base') ?? (planArgs.includes('--adversarial-ran') ? rangeBase : undefined) ?? mergeBase;
  if (!diffBase) throw new BriefError(`no merge base between ${base} and HEAD`);
  const root = git(['rev-parse', '--show-toplevel'])?.trim() ?? process.cwd();
  const extrasFile = flag('--extras');
  const extras = extrasFile ? JSON.parse(readFile(extrasFile, 'extras')!) as Extra[] : [];
  const m = buildManifest({ pass: id, out, ledger: flag('--ledger') ?? path.join(out, 'review-ledger.jsonl'), base, diffBase, root, checklistRoot: flag('--checklist-root') ?? ROOT,
    dispatches: step === 'fix-check' ? p.dispatches : p.dispatches.filter(d => d.role !== 'fix-check'), next: step, planLines, learnings: readFile(flag('--learnings-file'), 'learnings') ?? null, extras,
    targetedClasses: p.targeted?.classes, mergeBase, rangeBase: flag('--diff-base') ? undefined : rangeBase,
    fixCheck: step === 'fix-check' && (flag('--fix-list') || flag('--hunks') || flag('--tests')) ? { fix_list: flag('--fix-list')!, hunks: flag('--hunks')!, tests: flag('--tests')!, callers: flag('--callers') } : undefined,
    ...planExclude(p.review_exclude) });
  const over = ceiling('gstack-review-dispatch pass', base, m.out, m.readers, m.diff_base, (m.review_exclude as PlanExclude) ?? null);
  if (over) { process.stdout.write(planLines.join('\n') + '\n'); process.stderr.write(over.line + '\n'); return over.exit; }
  fs.mkdirSync(m.out, { recursive: true, mode: 0o700 });
  const t = sectionTexts(ROOT);
  renderStage(m, 'first', t, branchDiff);
  renderStage(m, 'specialists', t, branchDiff);
  writeManifest(file, m);
  const count = (s: string) => m.readers.filter(r => r.stage === s).length;
  process.stdout.write([...planLines, `MANIFEST: file=${file} pass=${id} readers=${m.readers.length} first=${count('first')} specialists=${count('specialists')} red-team=${count('red-team')} voices=${count('voices')}`, ...m.readers.map(r => readerLine(m, r))].join('\n') + '\n');
  return EXIT.ok;
}

/** The manifest's copy of the plan's review_exclude (no file lists) and the brief's disclosure line, when the plan had one. */
function planExclude(x: (Record<string, unknown> & { state: string; excluded?: number }) | undefined): { reviewExclude?: Record<string, unknown>; disclosure?: string } {
  if (!x) return {};
  const { kept_files: _k, references: _r, ...rest } = x;
  return { reviewExclude: rest, ...(x.state === 'active' ? { disclosure: disclosureLine(x as unknown as Parameters<typeof disclosureLine>[0]) } : {}) };
}

function passStep(cmd: string): number {
  const file = flag('--manifest');
  if (!file) { process.stderr.write(`gstack-review-dispatch ${cmd}: --manifest <file> is required\n`); return EXIT.usage; }
  const m = readManifest(file);
  if (cmd === 'show') { process.stdout.write(`MANIFEST_JSON: ${JSON.stringify(m)}\n`); return EXIT.ok; }
  if (cmd === 'stage') {
    const stage = flag('--stage') as Stage | undefined;
    if (!stage || !STAGES.includes(stage)) { process.stderr.write(`gstack-review-dispatch stage: --stage ${STAGES.join('|')}\n`); return EXIT.usage; }
    const pending = m.readers.filter(r => r.stage === stage && r.state === 'planned');
    const over = ceiling('gstack-review-dispatch stage', m.base, m.out, pending, m.diff_base, (m.review_exclude as PlanExclude) ?? null);
    if (over) { process.stderr.write(over.line + '\n'); return over.exit; }
    const done = renderStage(m, stage, sectionTexts(ROOT), branchDiff);
    writeManifest(file, m);
    process.stdout.write([`STAGE: ${stage} rendered=${done.length}`, ...done.map(r => readerLine(m, r))].join('\n') + '\n');
    return EXIT.ok;
  }
  if (cmd === 'chunk') {
    const r = m.readers.find(x => x.reader === flag('--reader'));
    if (!r?.file || !r.sha256) { process.stderr.write(`gstack-review-dispatch chunk: no rendered reader ${flag('--reader')}\n`); return EXIT.usage; }
    const text = readFile(r.file, 'brief')!;
    if (promptHash(text) !== r.sha256) throw new BriefError(`${r.reader}'s brief ${r.file} changed since it was rendered`);
    const index = Number(flag('--index') ?? '0');
    process.stdout.write(`BRIEF_CHUNK: reader=${r.reader} index=${index} of=${chunkCount(text)} sha256=${r.sha256}\n${JSON.stringify(chunkOf(text, index))}\n`);
    return EXIT.ok;
  }
  if (cmd === 'mark') {
    const logStart = flag('--log-start');
    if (logStart) {
      const token = flag('--token');
      if (!token) { process.stderr.write('gstack-review-dispatch mark: --log-start <key> --token <t>\n'); return EXIT.usage; }
      m.log_starts ??= {};
      m.log_starts[logStart] ??= token;
      writeManifest(file, m);
      process.stdout.write(`LOG_START: ${logStart} token=${m.log_starts[logStart]}\n`);
      return EXIT.ok;
    }
    const before = flag('--before');
    if (before) {
      const [tokens, credits] = before.split(',').map(Number);
      if (!Number.isFinite(tokens) || !Number.isFinite(credits)) { process.stderr.write('gstack-review-dispatch mark: --before <tokens>,<credits> [--voices]\n'); return EXIT.usage; }
      const key = args.includes('--voices') ? 'before_voices' : 'before';
      m[key] ??= { tokens: tokens!, credits: credits! };
      writeManifest(file, m);
      process.stdout.write(`BEFORE: ${key === 'before_voices' ? 'stage=voices ' : ''}tokens=${m[key]!.tokens} credits=${m[key]!.credits}\n`);
      return EXIT.ok;
    }
    const audit = m.readers.find(x => x.reader === flag('--reader'));
    if (flag('--state') === 'collected' && audit?.prompt_file && audit.tree !== undefined) {
      if (!flag('--output')) { process.stderr.write(`gstack-review-dispatch mark: ${audit.reader} is collected with --output <its reply>, which must prove the checkout it reviewed\n`); return EXIT.usage; }
      const tree = checkReviewedTree(readFile(flag('--output'), 'reader output')!, audit.tree);
      if (!tree.ok) {
        markReader(m, audit.reader, 'failed', { output: flag('--output'), error: `reviewed another tree: ${tree.reported}` });
        writeManifest(file, m);
        process.stdout.write(wrongTree(audit.reader, tree));
        return EXIT.fail;
      }
    }
    const r = markReader(m, flag('--reader') ?? '', flag('--state') as ReaderState, { path: flag('--path'), output: flag('--output'), error: flag('--error') });
    writeManifest(file, m);
    process.stdout.write(readerLine(m, r) + '\n');
    return EXIT.ok;
  }
  return EXIT.usage;
}

function program(): number {
  const text = readFile(PROGRAM_FILE, 'pass program')!;
  const sha = promptHash(text);
  const ledger = flag('--ledger');
  if (ledger) appendEvent(ledger, { event: 'program', version: PROGRAM_VERSION, sha256: sha });
  process.stdout.write(`PROGRAM: v${PROGRAM_VERSION} sha256=${sha} bytes=${Buffer.byteLength(text)}\n${JSON.stringify(text)}\n`);
  return EXIT.ok;
}

/**
 * The receipt's review_targeted record from the newest targeted dispatch: done only when its brief was sent verbatim, its output
 * collected, and it was rendered on a committed diff (uncommitted never proves what was read). `head` names the commit it read:
 * a later commit does not undo the read, and gstack-ship-receipt write binds the record only while that commit's product patch is
 * the receipt's (GST-986: Step 11 fixes after the read printed status=failed findings=0 for a completed reader).
 */
function targetedRecord(ledger: string, rows: VerifyRow[]): { classes: string[]; rules: string; brief_sha: string; status: 'done' | 'failed'; findings: number; raised_by: string; head: string | null } | null {
  const events = readLedger(ledger);
  const render = events.filter(e => e.event === 'rendered' && e.reader === 'targeted').at(-1);
  if (!render) return null;
  const label = rows.filter(r => r.kind === 'BRIEF' && r.reader.split('@')[0] === 'targeted').at(-1)?.reader;
  const brief = rows.filter(r => r.kind === 'BRIEF' && r.reader === label).at(-1);
  const output = rows.filter(r => r.kind === 'OUTPUT' && r.reader === label).at(-1);
  const head = typeof render.head === 'string' && /^[0-9a-f]{40,64}$/.test(render.head) ? render.head : null;
  const committed = typeof render.patch_id === 'string' && !['uncommitted', 'none'].includes(render.patch_id) && head !== null;
  const done = brief?.status === 'MATCH' && output?.status === 'MATCH' && committed;
  const ids = events.filter(e => e.event === 'output' && e.reader === 'targeted').at(-1)?.ids;
  return { classes: (render.classes as string[]) ?? [], rules: String(render.rules), brief_sha: String(render.brief_sha), status: done ? 'done' : 'failed', findings: Array.isArray(ids) ? ids.length : 0, raised_by: 'targeted', head };
}

/**
 * The selection the verified briefs read under review_exclude_paths: the digest every reader's newest brief names (fix-check reads
 * named hunks, not the selection); null when no brief names one, so a repository without the key verifies as before.
 */
function excludeRecord(ledger: string): { digest: string } | { mixed: string[] } | null {
  const newest = new Map<string, Record<string, unknown>>();
  for (const e of readLedger(ledger)) if (e.event === 'rendered' && e.role && e.role !== 'fix-check') newest.set(String(e.reader), e);
  const named = [...newest.values()].map(e => (typeof e.exclude === 'string' ? e.exclude : 'none'));
  if (!named.some(d => d !== 'none')) return null;
  const digests = [...new Set(named)];
  return digests.length === 1 ? { digest: digests[0]! } : { mixed: digests };
}

function main(): number {
  const cmd = args[0];
  if (!cmd || cmd === '--help' || cmd === '-h') { process.stdout.write(HELP + '\n'); return cmd ? EXIT.ok : EXIT.usage; }
  if (cmd === 'render') return render();
  if (cmd === 'pass') return pass();
  if (cmd === 'program') return program();
  if (['show', 'stage', 'chunk', 'mark'].includes(cmd)) return passStep(cmd);
  const ledger = flag('--ledger');
  if (!ledger) { process.stderr.write(`gstack-review-dispatch ${cmd}: --ledger <file> is required\n`); return EXIT.usage; }
  const reader = flag('--role') ? readerKey(flag('--role')!, flag('--name')) : '';
  if (cmd === 'sent') {
    const sent = readFile(flag('--sent'), 'sent prompt');
    if (!reader || sent === undefined) { process.stderr.write('gstack-review-dispatch sent: needs --role and --sent <file>\n'); return EXIT.usage; }
    const r = recordSent(ledger, reader, sent);
    process.stdout.write(r.ok ? `BRIEF_SENT: reader=${reader} sha256=${r.sent} match\n`
      : `BRIEF_MISMATCH: reader=${reader} rendered=${r.rendered ?? 'none'} sent=${r.sent} (dispatch the rendered file unchanged; this reader's review does not count)\n`);
    return r.ok ? EXIT.ok : EXIT.fail;
  }
  if (cmd === 'collect') {
    const outFile = flag('--output');
    const output = readFile(outFile, 'reader output');
    const merged = flag('--merged');
    if (!reader || output === undefined || !merged) { process.stderr.write('gstack-review-dispatch collect: needs --role, --output <file> and --merged <file>\n'); return EXIT.usage; }
    const unavailable = flag('--unavailable');
    if (unavailable !== undefined && !mayBeUnavailable(reader)) { process.stderr.write(`gstack-review-dispatch collect: --unavailable is for the outside voice only; ${reader}'s missing coverage leaves the review incomplete, never clean\n`); return EXIT.usage; }
    if (unavailable !== undefined && !unavailable.trim()) { process.stderr.write('gstack-review-dispatch collect: --unavailable needs a reason\n'); return EXIT.usage; }
    if (unavailable !== undefined && parseFindings(reader, output).length) { process.stderr.write(`gstack-review-dispatch collect: ${reader}'s output holds findings; collect it without --unavailable so none is lost\n`); return EXIT.usage; }
    const rendered = readLedger(ledger).filter(e => e.event === 'rendered' && e.reader === reader).at(-1);
    const tree = unavailable === undefined && rendered && 'tree' in rendered ? checkReviewedTree(output, typeof rendered.tree === 'string' ? rendered.tree : null) : undefined;
    if (tree && !tree.ok && mayBeUnavailable(reader) && !parseFindings(reader, output).length) {
      const why = `reviewed another tree: reported ${tree.reported}, expected ${tree.expected}`;
      const r = collect(ledger, reader, output, merged, path.resolve(outFile!), why);
      process.stdout.write(`COLLECT_UNAVAILABLE: reader=${reader} sha256=${r.sha} reason=${JSON.stringify(why)} (missing outside coverage: unavailable, never clean)\n`);
      return EXIT.ok;
    }
    const mf = flag('--manifest');
    let plan: ReturnType<typeof readManifest> | undefined;
    try { plan = mf ? readManifest(mf) : undefined; } catch (e) { process.stderr.write(`gstack-review-dispatch collect: ${(e as Error).message}; native FIXABLE collects as CRITICAL\n`); }
    const r = collect(ledger, reader, output, merged, path.resolve(outFile!), unavailable, tree, fixableRaises(plan && path.resolve(plan.ledger) === path.resolve(ledger) ? plan.plan_lines : undefined));
    if (tree && !tree.ok) {
      if (mf && plan) { markReader(plan, reader, 'failed', { output: outFile, error: `reviewed another tree: ${tree.reported}` }); writeManifest(mf, plan); }
      process.stdout.write(wrongTree(reader, tree));
      return EXIT.fail;
    }
    if (unavailable !== undefined) { process.stdout.write(`COLLECT_UNAVAILABLE: reader=${reader} sha256=${r.sha} reason=${JSON.stringify(unavailable)} (missing outside coverage: unavailable, never clean)\n`); return EXIT.ok; }
    if (!r.review) {
      process.stdout.write(`COLLECT_NOT_REVIEWED: reader=${reader} findings=0 sha256=${r.sha} (no finding and no ${cleanMarkers(reader).map(([m]) => m).join(' or ')} line: a refusal, an empty reply or a reader that never saw the diff is not a review; verify reports this brief NOT_COLLECTED)\n`);
      return EXIT.fail;
    }
    process.stdout.write(`COLLECT: reader=${reader} findings=${r.lines.length} sha256=${r.sha} merged=${merged}\n`);
    return EXIT.ok;
  }
  if (cmd === 'judge') {
    const merged = flag('--merged');
    const judged = flag('--judged');
    if (!merged || !judged) { process.stderr.write('gstack-review-dispatch judge: needs --merged <file> and --judged <file>\n'); return EXIT.usage; }
    const r = recordJudgment(ledger, readJsonl<MergedLine>(merged), readJsonl<JudgedLine>(judged), judged, merged);
    process.stdout.write(r.ok ? `JUDGMENT: ok added=${r.added.length} promoted=${r.promoted.length} folded=${r.folded.length}\n`
      : `JUDGMENT_REJECTED: dropped=${JSON.stringify(r.dropped)} downgraded=${JSON.stringify(r.downgraded)} unexplained=${JSON.stringify(r.unexplained)} invalid=${JSON.stringify(r.invalid)} (lead judgment may add or promote a finding, never drop or downgrade one)\n`);
    return r.ok ? EXIT.ok : EXIT.fail;
  }
  if (cmd === 'verify') {
    if (flag('--targeted-out')) fs.rmSync(flag('--targeted-out')!, { force: true });
    const v = verify(ledger);
    for (const r of v.rows) process.stdout.write(`${r.kind} ${r.reader} ${r.status} ${r.detail}\n`);
    if (!v.briefs) { process.stdout.write('VERIFY: no brief records (this run\'s ledger kept no prompts; dispatched-vs-rendered cannot be checked)\n'); return EXIT.refused; }
    const record = targetedRecord(ledger, v.rows);
    if (record) {
      process.stdout.write(`TARGETED_RECORD: classes=${record.classes.join(',')} status=${record.status} findings=${record.findings} brief=${record.brief_sha.slice(0, 12)} rules=${record.rules} read=${record.head?.slice(0, 12) ?? 'none'}\n`);
      if (flag('--targeted-out')) fs.writeFileSync(flag('--targeted-out')!, JSON.stringify(record) + '\n');
    }
    const sel = excludeRecord(ledger);
    if (sel && 'digest' in sel) process.stdout.write(`REVIEW_EXCLUDE_RECORD: digest=${sel.digest} (gstack-ship-receipt write --review-exclude ${sel.digest})\n`);
    if (sel && 'mixed' in sel) process.stdout.write(`REVIEW_EXCLUDE_RECORD: mixed digests=${sel.mixed.join(',')} (readers read different review_exclude_paths selections; rerun the review so every reader reads HEAD's)\n`);
    const clean = v.clean && !(sel && 'mixed' in sel);
    process.stdout.write(`VERIFY: ${clean ? 'clean' : 'dirty'} briefs=${v.briefs} outputs=${v.rows.filter(r => r.kind === 'OUTPUT').length} voided=${v.voided}${v.unavailable ? ` unavailable=${v.unavailable}` : ''}\n`);
    return clean ? EXIT.ok : EXIT.fail;
  }
  process.stderr.write(`gstack-review-dispatch: unknown command ${cmd}\n${HELP}\n`);
  return EXIT.usage;
}

try { process.exitCode = main(); } catch (e) {
  if (e instanceof BriefError) { process.stderr.write(`BRIEF_RENDER_FAILED: ${e.message}\n`); process.exitCode = EXIT.fail; } else throw e;
}