phronesis 1.0.0

package/src/codex-hooks-schema.js

@@ -0,0 +1,92 @@
+import { readFileSync } from 'node:fs';
+
+const ROOT_FIELDS = new Set(['hooks']);
+const EVENT_ENTRY_FIELDS = new Set(['matcher', 'hooks']);
+const HANDLER_FIELDS = new Set(['type', 'command', 'commandWindows', 'timeout', 'statusMessage', 'async']);
+
+function isRecord(value) {
+  return Boolean(value) && typeof value === 'object' && !Array.isArray(value);
+}
+
+function unknownFields(value, allowed) {
+  return Object.keys(value).filter((key) => !allowed.has(key));
+}
+
+function pushUnknown(errors, path, keys, expected) {
+  if (keys.length) {
+    errors.push(`${path} has unknown field(s): ${keys.join(', ')}; expected only ${expected}`);
+  }
+}
+
+export function validateCodexHooksSchema(config, { source = 'hooks.json' } = {}) {
+  const errors = [];
+
+  if (!isRecord(config)) {
+    return {
+      ok: false,
+      errors: [`${source} root must be a JSON object with a single "hooks" field`],
+    };
+  }
+
+  pushUnknown(errors, `${source} root`, unknownFields(config, ROOT_FIELDS), '"hooks"');
+  if (!Object.hasOwn(config, 'hooks')) {
+    errors.push(`${source} root is missing required field "hooks"`);
+    return { ok: false, errors };
+  }
+  if (!isRecord(config.hooks)) {
+    errors.push(`${source}.hooks must be an object mapping event names to hook entries`);
+    return { ok: false, errors };
+  }
+
+  for (const [eventName, entries] of Object.entries(config.hooks)) {
+    const eventPath = `${source}.hooks.${eventName}`;
+    if (!Array.isArray(entries)) {
+      errors.push(`${eventPath} must be an array of event entries`);
+      continue;
+    }
+
+    entries.forEach((entry, entryIndex) => {
+      const entryPath = `${eventPath}[${entryIndex}]`;
+      if (!isRecord(entry)) {
+        errors.push(`${entryPath} must be an object`);
+        return;
+      }
+
+      pushUnknown(errors, entryPath, unknownFields(entry, EVENT_ENTRY_FIELDS), '"matcher", "hooks"');
+      if (!Object.hasOwn(entry, 'hooks')) {
+        errors.push(`${entryPath} is missing required field "hooks"`);
+        return;
+      }
+      if (!Array.isArray(entry.hooks)) {
+        errors.push(`${entryPath}.hooks must be an array of command handlers`);
+        return;
+      }
+
+      entry.hooks.forEach((handler, handlerIndex) => {
+        const handlerPath = `${entryPath}.hooks[${handlerIndex}]`;
+        if (!isRecord(handler)) {
+          errors.push(`${handlerPath} must be an object`);
+          return;
+        }
+        pushUnknown(
+          errors,
+          handlerPath,
+          unknownFields(handler, HANDLER_FIELDS),
+          '"type", "command", "commandWindows", "timeout", "statusMessage", "async"',
+        );
+      });
+    });
+  }
+
+  return { ok: errors.length === 0, errors };
+}
+
+export function validateCodexHooksFile(filePath, { source = filePath } = {}) {
+  let parsed;
+  try {
+    parsed = JSON.parse(readFileSync(filePath, 'utf8'));
+  } catch (err) {
+    return { ok: false, errors: [`${source} is not valid JSON: ${err.message}`] };
+  }
+  return validateCodexHooksSchema(parsed, { source });
+}

package/src/compile.js

@@ -0,0 +1,513 @@
+// `phronesis compile accept|reject <draft>` (core-0017 H9) — the operator review
+// primitives over a compile candidate (.phronesis/drafts/…). Plumbing, not porcelain: the
+// batch-approval UX (`phronesis compile review`, security.md) is T7.5; T5.1 ships the
+// per-draft primitives + their compile.accepted/rejected events. Every check, move, event,
+// and the "WAS moved, but the audit failed" failure shape live behind compileAccept /
+// compileReject in @phronesis/core, so the CLI and any direct caller are the same action.
+//
+// accept's approval signal is the env PHRONESIS_APPROVAL_SOURCE (the same channel as
+// `phronesis act`), recorded verbatim as approval_source on action_type.committed —
+// acceptance IS the operator approval. Core messages are self-describing, so the CLI
+// prints them as-is rather than double-prefixing.
+
+import { join } from 'node:path';
+import { existsSync } from 'node:fs';
+import { readFile, readdir, rename, rm, writeFile } from 'node:fs/promises';
+import fse from 'fs-extra';
+import {
+  DEFAULT_DOMAIN,
+  compileAccept,
+  compileReject,
+  digestFile,
+  readEvents,
+  resolveInstall,
+  resumeCompileAccept,
+} from '@phronesis/core';
+
+export async function runCompileAccept({ draftPath, session, surface, dir } = {}) {
+  if (!draftPath) {
+    console.error('compile accept: name the <draft_path> to promote (a .phronesis/drafts/… candidate).');
+    process.exitCode = 1;
+    return null;
+  }
+  try {
+    // actor is NOT threaded — accept events are operator-driven by contract (the core
+    // hard-sets it). The approval signal still travels on PHRONESIS_APPROVAL_SOURCE.
+    const result = await compileAccept({
+      dir,
+      cwd: process.cwd(),
+      draftPath,
+      session,
+      surface,
+      approvalSource: process.env.PHRONESIS_APPROVAL_SOURCE || undefined,
+    });
+    console.log(JSON.stringify(result));
+    process.exitCode = 0;
+    return result;
+  } catch (err) {
+    console.error(err.message);
+    process.exitCode = 1;
+    return null;
+  }
+}
+
+// --- `phronesis compile review` (core-0029 PR2 / T7.5) -------------------------------
+// The batch-approval UX over the EXISTING per-draft accept/reject moves (L3): no new event
+// type, no second canonical-mutation path. Approve-all stamps one shared batch_id + rationale
+// (change 0025) so the batch is one logical approval queryable by batch_id (L5).
+// Suspicious-payload-flagged drafts are FAIL-CLOSED excluded from approve-all (L4): a draft is
+// batch-eligible only if its compile.candidate event is provably-clean AND unique. A durable
+// batch journal (written before iterating, updated as each post-move boundary completes)
+// makes a mid-batch crash recoverable: --resume re-drives the resumable compileAccept,
+// reconciling every missing post-move boundary in order (L7/L8).
+
+const REVIEW_JOURNAL = 'compile-review-journal.json';
+
+function journalPath(installRoot) {
+  return join(installRoot, '.phronesis', REVIEW_JOURNAL);
+}
+
+async function readJournal(installRoot) {
+  const p = journalPath(installRoot);
+  if (!existsSync(p)) return null;
+  let parsed;
+  try {
+    parsed = JSON.parse(await readFile(p, 'utf8'));
+  } catch {
+    return { __corrupt: true };
+  }
+  // A structurally-invalid-but-parseable journal ({}, [], 42, {planned:null}, a truncated
+  // then-flushed write) must be caught here, not crash the resume loop with a TypeError.
+  if (!parsed || typeof parsed !== 'object' || !Array.isArray(parsed.planned) || typeof parsed.cursors !== 'object' || parsed.cursors === null) {
+    return { __corrupt: true };
+  }
+  return parsed;
+}
+
+async function writeJournal(installRoot, journal) {
+  await fse.ensureDir(join(installRoot, '.phronesis'));
+  // Atomic write: a torn/half-flushed journal (a crash mid-write) is unrecoverable bookkeeping
+  // and would be quarantined as __corrupt on the next resume. Serialize to a temp sibling, then
+  // rename into place — rename is atomic on the same filesystem, so a crash leaves EITHER the
+  // prior journal or the complete new one, never a partial file.
+  const target = journalPath(installRoot);
+  const tmp = `${target}.tmp`;
+  await writeFile(tmp, `${JSON.stringify(journal, null, 2)}\n`);
+  await rename(tmp, target);
+}
+
+async function clearJournal(installRoot) {
+  await rm(journalPath(installRoot), { force: true });
+}
+
+// Walk .phronesis/drafts/{domain}/*/*.md — every pending compile candidate for the domain.
+export async function listPendingDrafts(installRoot, domain) {
+  const base = join(installRoot, '.phronesis', 'drafts', domain);
+  if (!existsSync(base)) return [];
+  const out = [];
+  for (const typeDir of (await readdir(base, { withFileTypes: true })).sort((a, b) => a.name.localeCompare(b.name))) {
+    if (!typeDir.isDirectory()) continue;
+    const typePath = join(base, typeDir.name);
+    for (const f of (await readdir(typePath)).sort()) {
+      if (f.endsWith('.md')) out.push(`.phronesis/drafts/${domain}/${typeDir.name}/${f}`);
+    }
+  }
+  return out;
+}
+
+// L4 — fail-closed classification from the compile.candidate EVENT (the flag is reliably in
+// the event on both create + update). A draft is batch-eligible ONLY if its compile.candidate
+// is provably clean. Re-drafting an unaccepted object, or updating an already-canonical one,
+// LEGITIMATELY appends a new compile.candidate while overwriting the draft file (the documented
+// idempotent re-draft, actions.js) — so multiple candidates for a path are the NORMAL steady
+// state, not an anomaly. The draft file on disk was produced by the MOST RECENT candidate, so
+// classify on THAT one: its suspicious_payload flag is the authoritative provenance of the
+// current draft. A draft with NO candidate at all (missing / archived / purged) is not provably
+// clean → individual review. Absence of a flag is never assumed clean for a missing event.
+// (This corrects the packet's literal "exactly one candidate" mechanism — which would quarantine
+// every re-draft/update — while preserving the spec's only requirement: flagged drafts are
+// excluded from approve-all, security.md:55.)
+export async function classifyDrafts(installRoot, draftRels, candidates) {
+  const all = candidates || (await readEvents({ installRoot, type: 'compile.candidate' }));
+  const eligible = [];
+  const excluded = [];
+  for (const draftRel of draftRels) {
+    const matches = all.filter((e) => e?.payload?.draft_path === draftRel);
+    if (matches.length === 0) {
+      excluded.push({ draftRel, reason: 'no compile.candidate event (missing / archived / purged) — not provably clean' });
+      continue;
+    }
+    const latest = matches[matches.length - 1]; // readEvents is chronological
+    if (latest.payload.suspicious_payload !== undefined) {
+      excluded.push({ draftRel, reason: `suspicious_payload flagged: ${String(latest.payload.suspicious_payload).slice(0, 160)}` });
+      continue;
+    }
+    // change 0027 (D3): bind batch eligibility to the REVIEWED bytes. The latest candidate must
+    // carry a content_digest AND the on-disk draft's sha-256 must equal it. Fail-closed (the L4
+    // posture): a missing digest (a legacy/unstamped latest candidate) or a mismatch (the draft
+    // was edited after its clean candidate — the review-session-scale TOCTOU) is NOT provably
+    // clean → individual review, never approve-all. Re-hashed via the SAME digestFile the handler
+    // stamped with, so handler and verifier read the bytes identically.
+    const expected = latest.payload.content_digest;
+    if (typeof expected !== 'string' || expected === '') {
+      excluded.push({ draftRel, reason: 'latest compile.candidate has no content_digest — not provably clean (change 0027)' });
+      continue;
+    }
+    let actual;
+    try {
+      actual = await digestFile(join(installRoot, draftRel));
+    } catch (err) {
+      excluded.push({ draftRel, reason: `draft bytes could not be read to verify content_digest (${err.code || err.message}) — not provably clean` });
+      continue;
+    }
+    if (actual !== expected) {
+      excluded.push({ draftRel, reason: 'draft bytes changed since its clean candidate (content_digest mismatch) — not provably clean' });
+      continue;
+    }
+    eligible.push(draftRel);
+  }
+  return { eligible, excluded };
+}
+
+function makeBatchId({ session, now }) {
+  const stamp = (now || new Date()).toISOString().replace(/[:.]/g, '-');
+  return `compile-batch-${session}-${stamp}`;
+}
+
+// A best-effort durability hook handed to compileAccept / resumeCompileAccept: it records the
+// per-draft intent (at the 'moved' boundary, when the draft is gone) + the per-boundary status
+// cursor (incl. the committed event_id) into the journal, persisting after each boundary so a
+// crash leaves a recoverable receipt.
+function makeRecordBoundary(installRoot, draftRel, journal) {
+  return async (boundary, info) => {
+    const c = journal.cursors[draftRel] || {};
+    if (boundary === 'moved') {
+      c.moved = true;
+      c.intent = info;
+    } else if (boundary === 'committed') {
+      c.committed = { done: true, event_id: info.event_id };
+    } else if (boundary === 'projection') {
+      c.projection = { done: true };
+    } else if (boundary === 'accepted') {
+      c.accepted = { done: true };
+    }
+    journal.cursors[draftRel] = c;
+    // The in-memory cursor (above) is authoritative for THIS run's clear/remaining logic; the
+    // disk write is best-effort crash-durability for --resume. A journal write failure must
+    // NEVER abort the canonical mutation it is only bookkeeping for — swallow + warn.
+    try {
+      await writeJournal(installRoot, journal);
+    } catch (err) {
+      console.error(`compile review: warning — could not persist the batch journal (${err.message}); resume after a crash may be degraded.`);
+    }
+  };
+}
+
+function remainingDrafts(journal) {
+  return journal.planned.filter((d) => !journal.cursors[d]?.accepted?.done);
+}
+
+export async function runCompileReview({
+  domain = DEFAULT_DOMAIN,
+  dir,
+  session,
+  surface = 'cli',
+  rationale,
+  approveAll = false,
+  resume = false,
+  json = false,
+  now,
+} = {}) {
+  const installed = resolveInstall({ dir, cwd: process.cwd() });
+  if (installed.error) {
+    console.error(installed.error);
+    process.exitCode = 1;
+    return null;
+  }
+  const installRoot = installed.root;
+  if (typeof session !== 'string' || session === '') {
+    console.error('compile review: --session <id> is required (the review session).');
+    process.exitCode = 1;
+    return null;
+  }
+
+  if (resume) return resumeReview({ installRoot, session, surface, json, now });
+
+  const draftRels = await listPendingDrafts(installRoot, domain);
+  const { eligible, excluded } = await classifyDrafts(installRoot, draftRels);
+
+  if (!approveAll) {
+    const plan = { domain, batch_eligible: eligible, individual_review: excluded };
+    if (json) console.log(JSON.stringify(plan, null, 2));
+    else printPlan(plan);
+    return plan;
+  }
+
+  // Never overwrite an existing batch journal with a fresh approve-all. A COMPLETED batch clears
+  // its journal (below), so a journal present here means a prior batch crashed/failed mid-way and
+  // still holds the ONLY recovery receipt for its half-moved drafts (their intent + status
+  // cursor). Blindly writing a new journal would destroy it, orphaning canonical artifacts with
+  // no path back to a clean spine. Refuse and point the operator at --resume (or a hand
+  // resolution of a corrupt journal). A true two-process race between this check and the write
+  // below is still possible (a cross-process lock is out of V1 scope); this closes the common
+  // "retry/second batch before --resume" footgun.
+  const existing = await readJournal(installRoot);
+  if (existing) {
+    if (existing.__corrupt) {
+      console.error(
+        `compile review: a batch journal exists but is corrupt (${journalPath(installRoot)}) — resolve it by hand before starting a new batch.`,
+      );
+      process.exitCode = 1;
+      return null;
+    }
+    const pending = remainingDrafts(existing);
+    if (pending.length) {
+      console.error(
+        `compile review: a prior batch (${existing.batch_id}) left ${pending.length} unreconciled draft(s) in the journal — ` +
+          'run `phronesis compile review --resume` to finish it (or resolve it by hand) before starting a new batch; ' +
+          'starting fresh would destroy the only recovery receipt.',
+      );
+      process.exitCode = 1;
+      return null;
+    }
+    // A stale but fully-reconciled journal (a clearJournal that never landed) — safe to clear.
+    await clearJournal(installRoot);
+  }
+
+  if (typeof rationale !== 'string' || rationale.trim() === '') {
+    console.error('compile review --approve-all requires --rationale "<why>" (recorded on every batch compile.accepted).');
+    process.exitCode = 1;
+    return null;
+  }
+  if (!eligible.length) {
+    const out = { batch_id: null, accepted: [], excluded };
+    if (json) console.log(JSON.stringify(out, null, 2));
+    else console.log(`compile review: no batch-eligible drafts under ${domain} (${excluded.length} routed to individual review).`);
+    return out;
+  }
+
+  const batchId = makeBatchId({ session, now });
+  // Write the journal BEFORE iterating (L7.1) — the plan is durable before the first move.
+  // Record the batch's start time (created_ts) so resume's out-of-band check can tell THIS batch's
+  // terminal events from a STALE prior review of the same — REUSED — draft path (Codex round-3 F2;
+  // the resumable-mutation rule: reconcile by recorded identity, never a non-unique key like a path).
+  const journal = { batch_id: batchId, rationale, domain, session, surface, created_ts: (now || new Date()).toISOString(), planned: [...eligible], cursors: {} };
+  await writeJournal(installRoot, journal);
+
+  const accepted = [];
+  const failed = [];
+  for (const draftRel of eligible) {
+    // change 0027 (F2/round-2): re-verify the draft IMMEDIATELY BEFORE promoting it. Eligibility was
+    // computed once for the whole batch; a draft changed after classification but before its turn —
+    // a concurrent agent, or a misbehaving mutation hook firing on an earlier accept — must not ride
+    // the batch on a stale check. classifyDrafts RE-READS the candidate event stream AND the draft
+    // file FRESH here (NO reused stream): the fresh read catches both a mutated draft file (digest
+    // mismatch) AND a newly-appended FLAGGED re-draft candidate with identical bytes (a stale stream
+    // missed the flag — reservation blocks freehand CLI emission, not the real compile action/a hook).
+    const recheck = await classifyDrafts(installRoot, [draftRel]);
+    if (!recheck.eligible.includes(draftRel)) {
+      const reason = recheck.excluded.find((e) => e.draftRel === draftRel)?.reason || 'no longer provably clean at promotion';
+      failed.push({ draftRel, error: `draft changed since classification — not promoted (${reason})` });
+      continue;
+    }
+    const recordBoundary = makeRecordBoundary(installRoot, draftRel, journal);
+    try {
+      const r = await compileAccept({
+        dir,
+        cwd: process.cwd(),
+        draftPath: draftRel,
+        session,
+        surface,
+        approvalSource: process.env.PHRONESIS_APPROVAL_SOURCE || undefined,
+        now,
+        batchId,
+        rationale,
+        recordBoundary,
+      });
+      accepted.push({ draftRel, accepted_path: r.accepted_path });
+    } catch (err) {
+      // A caught error leaves this draft in the journal (its cursor reflects how far it got);
+      // continue the batch best-effort, and --resume reconciles the rest.
+      failed.push({ draftRel, error: err.message });
+    }
+  }
+
+  const remaining = remainingDrafts(journal);
+  if (!remaining.length) await clearJournal(installRoot);
+  const out = { batch_id: batchId, rationale, accepted, failed, excluded, remaining };
+  if (json) console.log(JSON.stringify(out, null, 2));
+  else printReviewResult(out);
+  if (failed.length) process.exitCode = 1;
+  return out;
+}
+
+async function resumeReview({ installRoot, session, surface, json, now }) {
+  const journal = await readJournal(installRoot);
+  if (!journal || journal.__corrupt) {
+    console.error(
+      journal?.__corrupt
+        ? `compile review --resume: the batch journal (${journalPath(installRoot)}) is corrupt — resolve it by hand.`
+        : 'compile review --resume: no batch journal to resume.',
+    );
+    // Both the corrupt AND the missing case are non-zero: --resume is an explicit request to
+    // finish a batch, so "there was nothing to resume" is a failed request, not a success —
+    // automation must not read it as "nothing left to do, all good".
+    process.exitCode = 1;
+    return null;
+  }
+  // Faithful attribution: resumed events carry the ORIGINAL batch's session + surface, not the
+  // resume invocation's. The batch is one logical unit (batch_id + session); a --resume from a
+  // different --session must not split its events across audit sessions. The terminal events are
+  // pre-read ONCE for the draft-gone out-of-band check; the L4 re-check below RE-READS the candidate
+  // stream FRESH per draft, so a FLAGGED re-draft candidate appended mid-resume is not missed
+  // (Codex round-2 — a once-loaded stream would let a stale clean candidate promote a flagged draft).
+  const batchSurface = journal.surface || surface;
+  const batchSession = journal.session || session;
+  const acceptedEvents = await readEvents({ installRoot, type: 'compile.accepted' });
+  const rejectedEvents = await readEvents({ installRoot, type: 'compile.rejected' });
+  // Draft paths are REUSED across re-drafts/updates of one object, so a terminal event for this path
+  // may be STALE (a prior review), NOT proof of THIS batch's out-of-band resolution. Count a terminal
+  // event only if it is at/after the batch's recorded start (created_ts) — the operation identity the
+  // resumable-mutation rule requires (Codex round-3 F2): keying on the non-unique path alone would let
+  // a stale prior accept clear a live orphan's journal, silently dropping its missing audit spine. A
+  // journal MUST carry created_ts to do this safely; missing it (a hand-corrupted or pre-fix journal)
+  // is UNVERIFIABLE → no out-of-band resolution (fail closed to manual repair), NEVER the old
+  // path-only false-skip (Codex round-4: don't fall back to a non-identity check). NOTE: a wall-clock
+  // ts is a coarse identity; the robust form (a recorded terminal-event-id baseline + batch_id match)
+  // is the flagged operation-identity provenance follow-up — this interim catches the common
+  // stale-prior (normal past ts) case and fails closed on the rest.
+  const watermark = typeof journal.created_ts === 'string' ? journal.created_ts : null;
+  const afterStart = (e) => watermark !== null && typeof e?.ts === 'string' && e.ts >= watermark;
+  const resolvedOutOfBand = (rel) =>
+    acceptedEvents.some((e) => e?.payload?.draft_path === rel && afterStart(e)) ||
+    rejectedEvents.some((e) => e?.payload?.draft_path === rel && afterStart(e));
+  const accepted = [];
+  const failed = [];
+  for (const draftRel of journal.planned) {
+    const cursor = journal.cursors[draftRel] || {};
+    if (cursor.accepted?.done) {
+      accepted.push({ draftRel, skipped: 'already complete (no-op)' });
+      continue;
+    }
+    const recordBoundary = makeRecordBoundary(installRoot, draftRel, journal);
+    try {
+      if (cursor.moved && cursor.intent) {
+        const r = await resumeCompileAccept({
+          dir: installRoot,
+          intent: cursor.intent,
+          statusCursor: cursor,
+          session: batchSession,
+          surface: batchSurface,
+          now,
+          recordBoundary,
+        });
+        accepted.push({ draftRel, resumed: true, accepted_path: r.accepted_path });
+      } else if (!existsSync(join(installRoot, draftRel))) {
+        // The draft file is gone but the cursor never recorded a `moved` boundary. TWO very
+        // different states hide here, and the filesystem alone cannot tell them apart:
+        //  (1) genuinely resolved OUT-OF-BAND — a manual accept/reject between the crash and this
+        //      resume — PROVEN by a terminal compile.accepted/compile.rejected event for the path;
+        //  (2) the move SUCCEEDED but the best-effort 'moved' journal write failed before the
+        //      crash — the canonical artifact is ORPHANED with no committed spine. Marking THIS
+        //      "done" would clear the journal and silently leave canonical state without its audit
+        //      boundaries. So only (1) is "done"; (2) FAILS CLOSED to manual repair. Never infer
+        //      "done" from the missing draft alone — require a terminal event to prove it.
+        if (resolvedOutOfBand(draftRel)) {
+          accepted.push({ draftRel, skipped: 'resolved out-of-band (terminal event present)' });
+          if (!cursor.accepted) journal.cursors[draftRel] = { ...cursor, accepted: { done: true } };
+          continue;
+        }
+        failed.push({
+          draftRel,
+          error:
+            'draft gone but NO terminal compile.accepted/compile.rejected event and no recorded "moved" cursor — ' +
+            'an orphaned post-move state (the canonical artifact may exist without its committed spine). FAILING ' +
+            'CLOSED: resolve it by hand before resuming (do not start a fresh batch — that would lose this receipt).',
+        });
+        continue;
+      } else {
+        // The draft is still present → a fresh accept. RE-RUN L4 first: a suspicious
+        // compile.candidate could have been appended for its path between plan-write and the
+        // crash. Never fresh-accept a now-unclean draft on resume (the fail-closed gate must hold
+        // across the crash boundary, not just at plan time).
+        const { eligible } = await classifyDrafts(installRoot, [draftRel]);
+        if (!eligible.includes(draftRel)) {
+          failed.push({ draftRel, error: 'no longer provably clean on resume (L4) — routed to individual review' });
+          continue;
+        }
+        const r = await compileAccept({
+          dir: installRoot,
+          cwd: process.cwd(),
+          draftPath: draftRel,
+          session: batchSession,
+          surface: batchSurface,
+          approvalSource: process.env.PHRONESIS_APPROVAL_SOURCE || undefined,
+          now,
+          batchId: journal.batch_id,
+          rationale: journal.rationale,
+          recordBoundary,
+        });
+        accepted.push({ draftRel, accepted_path: r.accepted_path });
+      }
+    } catch (err) {
+      failed.push({ draftRel, error: err.message });
+    }
+  }
+  const remaining = remainingDrafts(journal);
+  if (!remaining.length) await clearJournal(installRoot);
+  const out = { batch_id: journal.batch_id, resumed: true, accepted, failed, remaining };
+  if (json) console.log(JSON.stringify(out, null, 2));
+  else printReviewResult(out);
+  if (failed.length) process.exitCode = 1;
+  return out;
+}
+
+function printPlan({ domain, batch_eligible, individual_review }) {
+  console.log(`compile review — ${domain}`);
+  console.log(`batch-eligible (provably-clean): ${batch_eligible.length}`);
+  for (const d of batch_eligible) console.log(`  + ${d}`);
+  console.log(`individual review (fail-closed — flagged / not provably clean): ${individual_review.length}`);
+  for (const e of individual_review) console.log(`  ! ${e.draftRel} — ${e.reason}`);
+  console.log('\nrun with --approve-all --rationale "<why>" to approve the clean set as one batch.');
+}
+
+function printReviewResult(out) {
+  if (out.batch_id) console.log(`batch ${out.batch_id}${out.resumed ? ' (resumed)' : ''}`);
+  console.log(`accepted: ${out.accepted.length}`);
+  for (const a of out.accepted) console.log(`  + ${a.draftRel}${a.resumed ? ' (resumed)' : ''}${a.skipped ? ` (${a.skipped})` : ''}`);
+  if (out.excluded?.length) {
+    console.log(`individual review (excluded from batch): ${out.excluded.length}`);
+    for (const e of out.excluded) console.log(`  ! ${e.draftRel} — ${e.reason}`);
+  }
+  if (out.failed?.length) {
+    console.log(`failed (left in the journal — re-run with --resume): ${out.failed.length}`);
+    for (const f of out.failed) console.log(`  x ${f.draftRel} — ${f.error}`);
+  }
+  if (out.remaining?.length) console.log(`remaining (resumable): ${out.remaining.length}`);
+}
+
+export async function runCompileReject({ draftPath, reason, session, surface, dir } = {}) {
+  if (!draftPath) {
+    console.error('compile reject: name the <draft_path> to discard (a .phronesis/drafts/… candidate).');
+    process.exitCode = 1;
+    return null;
+  }
+  try {
+    // actor is NOT threaded — reject events are operator-driven by contract (core hard-set).
+    const result = await compileReject({
+      dir,
+      cwd: process.cwd(),
+      draftPath,
+      reason,
+      session,
+      surface,
+    });
+    console.log(JSON.stringify(result));
+    process.exitCode = 0;
+    return result;
+  } catch (err) {
+    console.error(err.message);
+    process.exitCode = 1;
+    return null;
+  }
+}