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, 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, targetedPatchId } from '../lib/review-targeted';
import { resolveBaseBranch } from '../lib/ship-policy';

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>
             --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
  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.
      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)
  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'}`);
  }
  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;
  if (role === 'outside-voice' && diffBase) {
    const r = spawnSync('git', ['-c', 'core.quotePath=false', 'diff', '--no-color', '--no-ext-diff', diffBase], { encoding: 'utf8', timeout: 60_000, maxBuffer: 256 * 1024 * 1024 });
    if (r.status !== 0) throw new BriefError(`git diff ${diffBase} failed: ${(r.stderr ?? '').trim().split('\n')[0]}`);
    diff = r.stdout;
  }
  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,
    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, patch_id: diffBase ? targetedPatchId(process.cwd(), diffBase) : 'none' };
  appendEvent(ledger, { event: 'rendered', reader: readerKey(role, name), role, name: name ?? null, file, sha256: sha, bytes: Buffer.byteLength(text), workdir, tree, ...targeted });
  process.stdout.write(`BRIEF: reader=${readerKey(role, name)} sha256=${sha} bytes=${Buffer.byteLength(text)} file=${file}\n`);
  return EXIT.ok;
}

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}` : ''}`;
const branchDiff = (base: string) => {
  const d = git(['-c', 'core.quotePath=false', 'diff', '--no-color', '--no-ext-diff', base]);
  if (d === null) throw new BriefError(`git diff ${base} failed`);
  return d;
};

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 };
  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,
    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 });
  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;
}

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 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 the committed diff it was rendered on is still the one at verify (targetedPatchId; uncommitted never proves it).
 */
function targetedRecord(ledger: string, rows: VerifyRow[]): { classes: string[]; rules: string; brief_sha: string; status: 'done' | 'failed'; findings: number; raised_by: string } | 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 read = typeof render.patch_id === 'string' && !['uncommitted', 'none'].includes(render.patch_id) && typeof render.diff_base === 'string' && targetedPatchId(process.cwd(), render.diff_base) === render.patch_id;
  const done = brief?.status === 'MATCH' && output?.status === 'MATCH' && read;
  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: done && Array.isArray(ids) ? ids.length : 0, raised_by: 'targeted' };
}

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 r = collect(ledger, reader, output, merged, path.resolve(outFile!), unavailable, tree);
    if (tree && !tree.ok) {
      const mf = flag('--manifest');
      if (mf) { const m = readManifest(mf); markReader(m, reader, 'failed', { output: outFile, error: `reviewed another tree: ${tree.reported}` }); writeManifest(mf, m); }
      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') {
    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}\n`);
      if (flag('--targeted-out')) fs.writeFileSync(flag('--targeted-out')!, JSON.stringify(record) + '\n');
    }
    process.stdout.write(`VERIFY: ${v.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 v.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;
}