rig-create 0.0.0-stage → 1.0.0

package/src/reopen.ts

@@ -0,0 +1,144 @@
+import { writeFileSync } from 'node:fs';
+import { resolve } from 'node:path';
+
+import { asArray, asString, isObject, type Finding } from './check.ts';
+import { collectAmendments } from './amend.ts';
+import { readProject } from './feedback.ts';
+import { readVerbatim } from './record-input.ts';
+import { refuse, USAGE_EXIT } from './refusal.ts';
+import { newRefusals } from './refusal-baseline.ts';
+import { stageIndex, stageOfStep, STAGE_VALUES } from './stages.ts';
+import type { JsonObject } from './templates.ts';
+
+export interface Reopen {
+  readonly stage: string;
+  readonly at: number;
+}
+
+/** Validate history before using it as authority. Invalid entries supersede nothing. */
+export function collectReopens(project: JsonObject, refusals: Finding[]): Reopen[] {
+  const out: Reopen[] = [];
+  const push = (code: string, path: string, why: string): void => {
+    refusals.push({ code, path, message: `${path}: ${why}; record a human reopen to a previously reached stage` });
+  };
+  if (project.reopens !== undefined && !Array.isArray(project.reopens)) {
+    push('REOPEN_MALFORMED', 'reopens', 'must be a list');
+    return out;
+  }
+  for (const [index, raw] of asArray(project.reopens).entries()) {
+    const path = `reopens[${index}]`;
+    if (!isObject(raw) || ['stage', 'from_stage', 'by', 'at', 'verbatim'].some(k => asString(raw[k]) === null)
+      || !Number.isFinite(Date.parse(raw.at as string)) || (raw.source !== undefined && typeof raw.source !== 'string')) {
+      push('REOPEN_MALFORMED', path, 'needs stage, from_stage, by, a valid at, verbatim and optional text source');
+      continue;
+    }
+    if ((raw.by as string).toLowerCase() === 'agent') {
+      push('SIGNOFF_NOT_HUMAN', path, 'signed by agent');
+      continue;
+    }
+    if (!Array.isArray(raw.steps_before) || raw.steps_before.some(s => !isObject(s) || typeof s.id !== 'string'
+      || (s.status !== undefined && (typeof s.status !== 'string' || !['pending', 'in-progress', 'at-checkpoint', 'done'].includes(s.status))))) {
+      push('REOPEN_MALFORMED', path, 'steps_before must snapshot step ids and original statuses');
+      continue;
+    }
+    const stage = raw.stage as string;
+    if (stageIndex(stage) < 0 || stage === 'accepted') {
+      push('REOPEN_STAGE_UNKNOWN', path, `target ${stage} is not a reopenable stage`);
+      continue;
+    }
+    const fromStage = raw.from_stage as string;
+    if (!STAGE_VALUES.includes(fromStage)) {
+      push('REOPEN_MALFORMED', `${path}.from_stage`, 'must be a known project stage');
+      continue;
+    }
+    const at = Date.parse(raw.at as string);
+    if (stageIndex(stage) > reachedIndex(project, at, fromStage)) {
+      push('REOPEN_NOT_PASSED', path, `target ${stage} was not reached at ${String(raw.at)}`);
+      continue;
+    }
+    out.push({ stage, at });
+  }
+  return [...out, ...collectAmendments(project, refusals)];
+}
+
+/** Historical stages and dated builds witness reach even after stage has moved back. */
+function reachedIndex(project: JsonObject, at: number, fromStage: string): number {
+  let reached = stageIndex(fromStage);
+  for (const raw of asArray(project.signoffs)) {
+    if (!isObject(raw) || typeof raw.by !== 'string' || raw.by.toLowerCase() === 'agent'
+      || typeof raw.verbatim !== 'string' || typeof raw.at !== 'string' || !(Date.parse(raw.at) <= at)) continue;
+    reached = Math.max(reached, stageIndex(asString(raw.stage) ?? ''));
+  }
+  for (const raw of asArray(project.versions)) {
+    if (!isObject(raw) || typeof raw.at !== 'string' || !(Date.parse(raw.at) <= at)) continue;
+    if (raw.kind === 'rig') reached = Math.max(reached, stageIndex('rigging'));
+    if (raw.kind === 'post') reached = Math.max(reached, stageIndex('post'));
+  }
+  return reached;
+}
+
+/** Each reopen invalidates its suffix; a later, narrower reopen cannot resurrect an earlier suffix. */
+export function reopenTime(reopens: readonly Reopen[], stage: string): number {
+  return Math.max(-Infinity, ...reopens.filter(r => stageIndex(r.stage) <= stageIndex(stage)).map(r => r.at));
+}
+
+/** The `reopens[]` index of a validated reopen, matched by its stage and time. */
+export function reopenIndex(project: JsonObject, reopen: Reopen): number {
+  return asArray(project.reopens).findIndex(r => isObject(r) && r.stage === reopen.stage && Date.parse(asString(r.at) ?? '') === reopen.at);
+}
+
+export function liveSignoff(reopens: readonly Reopen[], stage: string, at: number): boolean {
+  const since = reopenTime(reopens, stage);
+  return since === -Infinity || at > since;
+}
+
+export const REOPEN_HELP = `reopen:
+  <stage> [<project dir>]  record a human backward move and set project.stage
+  --by <who>              human signer (agent is refused)
+  --verbatim-file <file>  unchanged UTF-8 words, or - for stdin (default)
+  --source <text>         optional origin of the words, separate from verbatim
+  --json                  print the reopen record
+  The clock supplies at; sign-offs and versions remain history.`;
+
+export function reopenCommand(args: string[], now: number): { stdout: string; exit: number } {
+  const opts: Record<string, string> = {};
+  const positional: string[] = [];
+  let json = false;
+  for (let i = 0; i < args.length; i++) {
+    const arg = args[i] as string;
+    if (arg === '--json') json = true;
+    else if (['--by', '--verbatim-file', '--source'].includes(arg)) {
+      const value = args[++i];
+      if (arg in opts || value === undefined || value === '') refuse('REOPEN_OPTION_INVALID', `reopens: ${arg} needs one non-empty value; supply it once`, USAGE_EXIT);
+      opts[arg] = value;
+    } else if (arg.startsWith('-')) refuse('UNKNOWN_OPTION', `reopens: unsupported ${arg}; see reopen help`, USAGE_EXIT);
+    else positional.push(arg);
+  }
+  if (positional.length < 1 || positional.length > 2 || opts['--by'] === undefined) refuse('REOPEN_OPTION_INVALID', 'reopens: supply a stage, --by and one optional project directory', USAGE_EXIT);
+  const dir = resolve(positional[1] ?? process.cwd());
+  const { file, project } = readProject(dir);
+  const before = structuredClone(project);
+  const steps = asArray(isObject(project.plan) ? project.plan.steps : undefined);
+  if (steps.some(s => !isObject(s) || typeof s.id !== 'string' || (s.phase !== 'rig' && s.phase !== 'post'))) {
+    refuse('REOPEN_MALFORMED', 'plan.steps: each step needs id and phase; restore the plan before reopening');
+  }
+  const affected = steps.filter((s): s is JsonObject => isObject(s)
+    && stageIndex(stageOfStep(s.phase as 'rig' | 'post', s.id as string)) >= stageIndex(positional[0] as string));
+  const entry: JsonObject = { from_stage: project.stage ?? null, steps_before: affected.map(s => ({ id: s.id as string, ...(s.status === undefined ? {} : { status: s.status }) })), stage: positional[0] as string, by: opts['--by'], at: new Date(now).toISOString(), verbatim: '' };
+  if (opts['--source'] !== undefined) entry.source = opts['--source'];
+  const refusals: Finding[] = [];
+  // Validate against the original reached stage before moving it backwards.
+  const candidate = { ...project, reopens: [...asArray(project.reopens), entry] };
+  if (project.reopens !== undefined && !Array.isArray(project.reopens)) collectReopens(project, refusals);
+  collectReopens(candidate, refusals);
+  const first = refusals[0];
+  if (first !== undefined) refuse(first.code, first.message);
+  entry.verbatim = readVerbatim(opts['--verbatim-file'] ?? '-');
+  for (const step of affected) step.status = 'pending';
+  project.reopens = candidate.reopens;
+  project.stage = entry.stage;
+  const rejected = newRefusals(dir, before, project, { now })[0];
+  if (rejected !== undefined) refuse(rejected.code, rejected.message);
+  writeFileSync(file, `${JSON.stringify(project, null, 2)}\n`);
+  return { stdout: json ? JSON.stringify(entry, null, 2) : `reopen: ${String(entry.stage)} by ${String(entry.by)} at ${String(entry.at)}`, exit: 0 };
+}

package/src/republish.ts

@@ -0,0 +1,93 @@
+/** Add a publication generation without rebuilding any rig artifact. */
+import { closeSync, fchmodSync, openSync, realpathSync, renameSync, rmSync, statSync, writeFileSync } from 'node:fs';
+import { join } from 'node:path';
+import { isDeepStrictEqual } from 'node:util';
+import { asArray, checkProject, isObject } from './check.ts';
+import { publicationFile, liveManifestPath, originalPaintingReference, prepareLiveManifest, checkPublicationGenerations, sealedScene } from './job-publication.ts';
+import { assertRequestedRig } from './job-host.ts';
+import { acquireBoundJobWrite, prepareVersionIntent, publishCommittedVersion } from './job-writer.ts';
+import { cancelUncommittedIntent, jobHash, type PendingPublication } from './job-outbox.ts';
+import { baselineOf, newFindings } from './refusal-baseline.ts';
+import { refuse } from './refusal.ts';
+import type { Finding } from './check.ts';
+import type { JsonObject } from './templates.ts';
+
+export function republishCommand(args: string[], now: number): { stdout: string; exit: number } {
+  const positional: string[] = []; let reason: string | undefined;
+  for (let i = 0; i < args.length; i++) {
+    if (args[i] === '--reason' && reason === undefined) reason = args[++i];
+    else if (args[i]!.startsWith('-')) refuse('PUBLICATION_GENERATION_INVALID', 'project.json: use republish <rig> [<dir>] --reason <words>');
+    else positional.push(args[i]!);
+  }
+  const n = Number(positional[0]?.replace(/^v/, ''));
+  if (!Number.isSafeInteger(n) || n < 1 || positional.length > 2 || !reason?.trim()) refuse('PUBLICATION_GENERATION_INVALID', 'project.json: use republish <rig> [<dir>] --reason <words>');
+  const root = realpathSync(positional[1] ?? process.cwd());
+  const lock = join(root, '.republish.lock');
+  let fd: number;
+  try { fd = openSync(lock, 'wx'); } catch { refuse('PUBLICATION_GENERATION_INVALID', 'project.json: another republish writer holds the lock; wait and retry'); }
+  let release = () => {}; let staged = false; let committed = false; let intent: PendingPublication | null = null;
+  const path = `review-live-v${n}-g2.json`;
+  try {
+    release = acquireBoundJobWrite(root);
+    const original = publicationFile(root, 'project.json');
+    const project = JSON.parse(original.toString('utf8')) as JsonObject;
+    assertRequestedRig(root, String(n));
+    const version = asArray(project.versions).filter(isObject).find(v => v.n === n)!;
+    liveManifestPath(root, project, n);
+    if (version.publication_generations !== undefined) refuse('PUBLICATION_GENERATION_DUPLICATE', `versions[v${n}].publication_generations: a publication generation already exists; reopen it with job open --rig ${n}`);
+    if (version.kind !== 'post' && (!Array.isArray(project.inputs) || project.inputs.length === 0)) refuse('PUBLICATION_PAINTING_MISSING', `versions[v${n}]: no inputs[0] original painting is declared; register it with input add before republishing`);
+    const reference = version.kind === 'post' ? null : originalPaintingReference(root, project, n);
+    const legacyPath = `review-live-v${n}.json`;
+    const old = publicationFile(root, legacyPath);
+    const manifest = JSON.parse(old.toString('utf8')) as JsonObject;
+    if (version.kind !== 'post' && Array.isArray(manifest.references) && manifest.references.length) refuse('PUBLICATION_GENERATION_DUPLICATE', `versions[v${n}]: the publication already carries a reference; reopen it with job open --rig ${n}`);
+    // Check the exact immutable legacy shape through the original publisher.
+    prepareLiveManifest(root, project, n);
+    let scene: string | undefined;
+    const sources = new Map<string, string>();
+    if (version.kind === 'post') {
+      const directionPath = `evidence/direction/v${n}.json`;
+      const directionBytes = publicationFile(root, directionPath);
+      const direction = JSON.parse(directionBytes.toString('utf8')) as JsonObject;
+      if (direction.schema !== 'rig-create/direction@2' || !isObject(direction.scene)) refuse('PUBLICATION_GENERATION_INVALID', `${directionPath}: post generation requires direction@2 and its committed scene; retain the existing publication for a scene-less post`);
+      if (manifest.scene !== undefined) refuse('PUBLICATION_GENERATION_DUPLICATE', `${legacyPath}: the publication already carries a scene; reopen it with job open --rig ${n}`);
+      const sealed = sealedScene(root, project, directionPath, direction)!;
+      scene = sealed.path;
+      const binding = (version.provenance as JsonObject).direction as JsonObject;
+      if (binding.path !== directionPath || binding.sha256 !== jobHash(directionBytes) || direction.scene.sha256 !== sealed.sha256) refuse('PUBLICATION_GENERATION_INVALID', `${directionPath}: publication sources changed during republish; restore the frozen direction and scene bytes`);
+      sources.set(directionPath, String(binding.sha256));
+      sources.set(scene, sealed.sha256);
+      for (const plate of sealed.plates) sources.set(plate.path, plate.sha256);
+    }
+    const before = baselineOf(checkProject(root, project, { now, readOnly: true }));
+    const bytes = Buffer.from(`${JSON.stringify({ ...manifest, revision: `v${n}-g2`, ...(scene ? { scene } : { references: [reference] }) }, null, 2)}\n`);
+    const next = structuredClone(project);
+    const target = asArray(next.versions).filter(isObject).find(v => v.n === n)!;
+    target.publication_generations = [{ generation: 2, supersedes: { generation: 1, path: legacyPath, sha256: jobHash(old) },
+      manifest: { path, sha256: jobHash(bytes) }, at: new Date(now).toISOString(), reason }];
+    try { writeFileSync(join(root, path), bytes, { flag: 'wx' }); staged = true; }
+    catch { refuse('PUBLICATION_GENERATION_INVALID', `versions[v${n}]: ${path} already exists or is unwritable; preserve existing generations and restore writable storage`); }
+    const findings: Finding[] = [];
+    checkPublicationGenerations(root, next, findings);
+    findings.push(...newFindings(before, checkProject(root, next, { now, readOnly: true }).refusals));
+    if (findings[0]) refuse(findings[0].code, findings[0].message);
+    if (!publicationFile(root, 'project.json').equals(original) || !publicationFile(root, legacyPath).equals(old) ||
+        (reference !== null && !isDeepStrictEqual(originalPaintingReference(root, project, n), reference)) ||
+        [...sources].some(([path, sha256]) => jobHash(publicationFile(root, path)) !== sha256)) refuse('PUBLICATION_GENERATION_INVALID', 'project.json: source changed during republish; freeze the record and publication sources and retry');
+    const record = Buffer.from(`${JSON.stringify(next, null, 2)}\n`);
+    intent = prepareVersionIntent(root, record, n);
+    fchmodSync(fd, statSync(join(root, 'project.json')).mode);
+    writeFileSync(fd, record);
+    renameSync(lock, join(root, 'project.json')); committed = true;
+    publishCommittedVersion(root, n);
+    return { stdout: `republish: ${version.kind === 'post' ? 'post' : 'rig'} v${n} generation 2 recorded (${path})`, exit: 0 };
+  } finally {
+    closeSync(fd);
+    if (!committed) {
+      cancelUncommittedIntent(root, intent);
+      if (staged) rmSync(join(root, path));
+      rmSync(lock, { force: true });
+    }
+    release();
+  }
+}

package/src/restart.ts

@@ -0,0 +1,141 @@
+/**
+ * `restart`: start a project's record again at v1 through a writer (create#285). The fresh record is
+ * the one init writes. It keeps the inputs, re-validated by the input writer's checks, and the fix
+ * ledger, because owner feedback belongs to the project, not to a version. create does not keep the
+ * earlier project.json; git history holds it, and restarts[] names its sha256. That holds only when
+ * project.json is committed, so restart refuses before it writes unless project.json is tracked and
+ * byte-identical to its HEAD version (create#304).
+ */
+import { createHash } from 'node:crypto';
+import { existsSync, readFileSync } from 'node:fs';
+import { join, resolve } from 'node:path';
+import { asArray, checkProject, isObject, PROJECT_SCHEMA, type Finding } from './check.ts';
+import { ledgerRows, writeRecord } from './fix-ledger.ts';
+import { freshProjectRecord, run } from './init.ts';
+import { checkInputs } from './inputs.ts';
+import { acquireBoundJobWrite } from './job-writer.ts';
+import { readVerbatim } from './record-input.ts';
+import { refuse, USAGE_EXIT } from './refusal.ts';
+import { baselineOf, newFindings } from './refusal-baseline.ts';
+import type { Json, JsonObject } from './templates.ts';
+
+export const RESTART_HELP = `restart:
+  [<dir>] --by <human> --reason-file <file> [--json]
+  Replace project.json with the record init writes: the template's stage, no versions, drafts,
+  signoffs, plan, answers or review acts. Keeps name, title, painting, same_artwork, inputs[] (each file must
+  still match its sha256) and fix_ledger with every row, and appends restarts[] { at, by, reason,
+  previous_record_sha256 }. git history holds the earlier record, so restart refuses unless
+  project.json is committed: tracked and byte-identical to HEAD. A kept part set (inputs under
+  <set>/parts/*.png or <set>/parts.json) keeps <set>/parts.json and its rig: rig.json and
+  mesh_report.json, at <set>/rig/ or <set>/.`;
+
+/**
+ * The bytes of `<dir>/project.json` at HEAD, refusing unless the folder is in a git work tree and the
+ * file is committed there byte for byte: restart drops the earlier record, so git history must hold it.
+ */
+export function committedRecord(dir: string, file: string): Buffer {
+  const remedy = 'commit project.json, then restart';
+  const inside = run(['git', 'rev-parse', '--is-inside-work-tree'], dir);
+  if (!inside.ok || inside.out !== 'true') {
+    refuse('RESTART_NOT_IN_GIT', `${file}: the folder is not inside a git work tree, so git history cannot hold the record restart replaces; put the project under git, ${remedy}`);
+  }
+  const prefix = run(['git', 'rev-parse', '--show-prefix'], dir);
+  if (!prefix.ok) refuse('RESTART_NOT_IN_GIT', `${file}: git cannot resolve the folder's path in its work tree (${prefix.out}); ${remedy}`);
+  const path = `${prefix.out}project.json`;
+  const head = Bun.spawnSync(['git', 'show', `HEAD:${path}`], { cwd: dir, stdout: 'pipe', stderr: 'pipe' });
+  if (head.exitCode !== 0) {
+    const tracked = run(['git', 'ls-files', '--error-unmatch', '--', 'project.json'], dir).ok;
+    refuse('RESTART_RECORD_UNCOMMITTED', `${file}: ${tracked ? 'is staged but was never committed' : 'is untracked'}, so git history does not hold the record restart replaces; ${remedy}`);
+  }
+  const bytes = Buffer.from(head.stdout);
+  if (!readFileSync(file).equals(bytes)) {
+    refuse('RESTART_RECORD_UNCOMMITTED', `${file}: differs from HEAD:${path} (uncommitted changes), so git history does not hold the record restart replaces; ${remedy}`);
+  }
+  return bytes;
+}
+
+/** Kept part sets missing their manifest, their rig or their PNGs, by set root. */
+export function partSetGaps(inputs: Json | undefined): string[] {
+  const paths = new Set(asArray(inputs).filter(isObject).map(input => input.path).filter((path): path is string => typeof path === 'string'));
+  const roots = new Set<string>();
+  for (const path of paths) {
+    const set = /^(?:(.*)\/)?parts\/[^/]+\.png$/i.exec(path) ?? /^(?:(.*)\/)?parts\.json$/.exec(path);
+    if (set) roots.add(set[1] ?? '');
+  }
+  const gaps: string[] = [];
+  for (const root of [...roots].sort()) {
+    const at = (name: string): string => (root === '' ? name : `${root}/${name}`);
+    const missing: string[] = [];
+    if (!paths.has(at('parts.json'))) missing.push(at('parts.json'));
+    if (![...paths].some(path => path.startsWith(at('parts/')) && /\.png$/i.test(path))) missing.push(at('parts/*.png'));
+    const rig = ['rig/', ''].find(prefix => paths.has(at(`${prefix}rig.json`)) && paths.has(at(`${prefix}mesh_report.json`)));
+    if (rig === undefined) missing.push(`${at('rig/rig.json')} and ${at('rig/mesh_report.json')} (or ${at('rig.json')} and ${at('mesh_report.json')})`);
+    if (missing.length) gaps.push(`${root === '' ? '(project root)' : root}: ${missing.join(', ')}`);
+  }
+  return gaps;
+}
+
+export function restartCommand(args: string[], now: number): { stdout: string; exit: number } {
+  const opts: Record<string, string> = {};
+  const positional: string[] = [];
+  let json = false;
+  for (let i = 0; i < args.length; i++) {
+    const arg = args[i]!;
+    if (arg === '--json') json = true;
+    else if (arg === '--by' || arg === '--reason-file') {
+      const value = args[++i];
+      if (value === undefined || value.startsWith('--') || value.trim() === '' || opts[arg] !== undefined) refuse('RESTART_USAGE', `restart: ${arg} needs one value; see restart help`, USAGE_EXIT);
+      opts[arg] = value;
+    } else if (arg.startsWith('-')) refuse('RESTART_USAGE', `restart: unsupported ${arg}; see restart help`, USAGE_EXIT);
+    else positional.push(arg);
+  }
+  if (positional.length > 1 || opts['--by'] === undefined || opts['--reason-file'] === undefined) refuse('RESTART_USAGE', RESTART_HELP, USAGE_EXIT);
+  if (opts['--by'].toLowerCase() === 'agent') refuse('SIGNOFF_NOT_HUMAN', 'restarts[].by: restart by agent; a person orders a restart');
+  const reason = readVerbatim(opts['--reason-file']).trim();
+  if (!reason) refuse('RESTART_USAGE', 'restarts[].reason: the reason file is empty; say why the record restarts', USAGE_EXIT);
+  const dir = resolve(positional[0] ?? process.cwd());
+  const file = join(dir, 'project.json');
+  const notProject = (why: string): never => refuse('RESTART_NOT_A_PROJECT', `${file}: ${why}; restart runs on a create project folder`);
+  if (!existsSync(file)) notProject('does not exist');
+  const committed = committedRecord(dir, file);
+  const release = acquireBoundJobWrite(dir);
+  try {
+    const original = readFileSync(file);
+    if (!original.equals(committed)) refuse('RESTART_SOURCE_CHANGED', 'project.json: changed while restart was validating; retry against the current record');
+    let project: JsonObject;
+    try {
+      const parsed: unknown = JSON.parse(original.toString('utf8'));
+      if (!isObject(parsed as Json) || (parsed as JsonObject).schema !== PROJECT_SCHEMA) throw new Error('schema');
+      project = parsed as JsonObject;
+    } catch { return notProject(`is not a ${PROJECT_SCHEMA} record`); }
+    const inputs = { dir, project, refusals: [] as Finding[], warnings: [] as Finding[] };
+    checkInputs(inputs);
+    const input = inputs.refusals[0] ?? inputs.warnings[0];
+    if (input !== undefined) refuse('RESTART_INPUT_INVALID', `${input.path}: ${input.code}: ${input.message}; a restart keeps only inputs the input writer would record, so restore the file or register it again with input add`);
+    const gaps = partSetGaps(project.inputs);
+    if (gaps.length) refuse('RESTART_PART_SET_INCOMPLETE', `inputs: a kept part set needs its parts.json and its rig with its PNGs, missing ${gaps.join('; ')}; register the missing files with input add, or stop keeping the set`);
+    const candidate = freshProjectRecord(typeof project.name === 'string' ? project.name : '', now);
+    if (project.name !== undefined) candidate.name = project.name;
+    if (project.title !== undefined) candidate.title = project.title;
+    if (project.painting !== undefined) candidate.painting = project.painting;
+    if (project.same_artwork !== undefined) candidate.same_artwork = project.same_artwork;
+    candidate.inputs = project.inputs ?? [];
+    candidate.fix_ledger = project.fix_ledger ?? [];
+    const entry: JsonObject = { at: new Date(now).toISOString(), by: opts['--by'], reason, previous_record_sha256: createHash('sha256').update(original).digest('hex') };
+    candidate.restarts = [...asArray(project.restarts), entry];
+    const ledger: Finding[] = [];
+    ledgerRows(candidate, ledger, now);
+    if (ledger[0] !== undefined) refuse(ledger[0].code, `${ledger[0].message}; a restart keeps every ledger row as written`);
+    // The restarted record carries exactly what a fresh init record carries (its open interview) and nothing from the retired one.
+    const fresh = checkProject(dir, freshProjectRecord(String(candidate.name ?? ''), now), { now });
+    const rejected = newFindings(baselineOf(fresh), checkProject(dir, structuredClone(candidate), { now }).refusals)[0];
+    if (rejected !== undefined) refuse(rejected.code, rejected.message);
+    writeRecord(file, original, candidate, 'restart');
+    const rows = asArray(candidate.fix_ledger).length;
+    return {
+      stdout: json ? JSON.stringify(entry, null, 2)
+        : `restart: project record restarted at stage ${String(candidate.stage)}; kept ${asArray(candidate.inputs).length} input(s) and ${rows} ledger row(s); the earlier record (sha256 ${String(entry.previous_record_sha256)}) is in git history`,
+      exit: 0,
+    };
+  } finally { release(); }
+}

package/src/review-act-runtime.ts

@@ -0,0 +1,16 @@
+/** Private stdin/stdout adapter for the synchronous review writer. */
+import { readFileSync } from 'node:fs';
+import { fetchReviewAct, type ReviewActTransport } from './review-act.ts';
+import { Refusal } from './refusal.ts';
+
+if (import.meta.main) {
+  try {
+    const input = JSON.parse(readFileSync(0, 'utf8')) as ReviewActTransport;
+    const fetched = await fetchReviewAct(input);
+    process.stdout.write(JSON.stringify({ ok: true, bytes: fetched.bytes, stillBytes: fetched.stillBytes }));
+  } catch (error) {
+    process.stdout.write(JSON.stringify({ ok: false, code: error instanceof Refusal ? error.code : 'REVIEW_ACT_FETCH_REFUSED',
+      message: error instanceof Refusal ? error.message : 'project.json.review_acts: fetch failed; restore the live Review job' }));
+    process.exitCode = 1;
+  }
+}