pincer-workflow 0.5.0 → 0.7.0

package/template/scripts/pincer-runtime/runner.cjs

@@ -79,18 +79,34 @@ class Capture {
 // Run one attempt. `context` is the attempt context (kind, change, prd, prd_revision,
 // base, ticket/ticket_digest or candidate/check); `commands` the block lines;
 // `timeoutSeconds` the effective timeout; `echo` when the output should also reach
-// the terminal. Returns { attempt } or { code, problem } for refusals before launch.
-async function runAttempt({ root, context, commands, timeoutSeconds, command = 'verify', echo = true, declared = {} }) {
+// the terminal. `revalidate`, when given, is called under the worktree lock
+// immediately before the `running` record is written and returns the context to
+// record (docs/runtime-contracts.md, "Command gates"): the gates the caller passed
+// before the lock are evaluated again there, so a transition, revision or
+// authorization committed in between is seen and the attempt is refused (a thrown
+// transaction Refusal becomes { code, problem, refused: true }) or recorded against
+// the current agreement. `announce` is called once the record is registered and
+// before the launch, so a refusal prints nothing. Returns { attempt } or { code,
+// problem } for refusals before launch; nothing is written for a refusal.
+async function runAttempt({ root, context, commands, timeoutSeconds, command = 'verify', echo = true, declared = {}, revalidate = null, announce = null, cwd = null }) {
   const block = commands.length ? `${commands.join('\n')}\n` : '';
   const checkDigest = parse.sha256(`${block}timeout=${timeoutSeconds}\n`);
   const display = sanitizeText(block).text.slice(0, 2000);
   const before = source.snapshot(root);
   if (before.problems.length) return { code: before.problems[0].code, problem: before.problems.map(p => `${p.code}: ${p.detail}`).join('\n'), problems: before.problems };
 
-  const key = state.contextKey(context);
   let attempt, logDir, relLogDir;
   try {
     state.withLock(root, () => {
+      // Finish any committed transaction before writing: its staged files would
+      // otherwise be renamed over this attempt and its index pointer later.
+      require('./transaction.cjs').recoverPending(root);
+      if (revalidate) context = revalidate();
+      const key = state.contextKey(context);
+      // Changes mode records (schema 2) carry the agreement digest; `mode` only
+      // selects the key format and is not part of the record.
+      const { mode, ...persisted } = context;
+      const schema = persisted.coverage ? 3 : persisted.agreement ? 2 : 1;
       const read = state.readIndex(root);
       if (read.error) { const e = new Error(read.error); e.code = 'INVALID'; throw e; }
       const index = read.index;
@@ -101,10 +117,10 @@ async function runAttempt({ root, context, commands, timeoutSeconds, command = '
       logDir = path.join(root, relLogDir);
       fs.mkdirSync(logDir, { recursive: true });
       attempt = {
-        schema: 1, runtime: 1, id, sequence, context,
+        schema, runtime: schema, id, sequence, context: persisted,
         check: { digest: checkDigest, display, timeout_seconds: timeoutSeconds },
         outcome: 'running', exit_code: null, signal: null,
-        runner: runnerInfo(), cwd: '.',
+        runner: runnerInfo(), cwd: cwd || '.',
         environment: { os: `${os.platform()} ${os.release()}`, node: process.version, declared },
         started: nowIso(), finished: null,
         source: { before: before.digest, after: null, files: before.files.length, limitations: before.limitations },
@@ -119,11 +135,13 @@ async function runAttempt({ root, context, commands, timeoutSeconds, command = '
       state.writeIndex(root, index);
     }, { command });
   } catch (error) {
+    if (error && error.refusal) return { code: error.code, problem: error.message, refused: true };
     if (error.code === 'STATE_BUSY') return { code: 'STATE_BUSY', problem: error.message };
     if (error.code === 'INVALID') return { code: 'INPUT_INVALID', problem: error.message };
     return { code: 'ATTEMPT_ERROR', problem: `cannot persist the attempt record: ${error.message}` };
   }
 
+  if (announce) announce(attempt);
   // Execute in a fresh process group so timeouts and signals reach every descendant.
   let child, launchError = null;
   const stdout = new Capture(path.join(logDir, 'stdout.log'), echo ? process.stdout : null);
@@ -162,7 +180,7 @@ async function runAttempt({ root, context, commands, timeoutSeconds, command = '
     let settled = false;
     settle = result => { if (!settled) { settled = true; resolve(result); } };
     try {
-      child = spawn(runnerInfo().shell, [...RUNNER_ARGS, block], { cwd: root, detached: true, stdio: ['ignore', 'pipe', 'pipe'], env: process.env });
+      child = spawn(runnerInfo().shell, [...RUNNER_ARGS, block], { cwd: cwd ? path.join(root, cwd) : root, detached: true, stdio: ['ignore', 'pipe', 'pipe'], env: process.env });
     } catch (error) { launchError = error.message; return settle({ code: null, signal: null }); }
     child.on('error', error => { launchError = error.message; });
     if (child.pid) {

package/template/scripts/pincer-runtime/scaffold.cjs

@@ -0,0 +1,254 @@
+'use strict';
+// PINCER runtime — the coverage draft (docs/runtime-contracts.md, "Coverage draft").
+// `coverage scaffold --change <id>` projects the validated PRD inventory, the change's
+// tickets and any authored map into one reviewable draft. It exists because authoring
+// `.prd/coverage/<id>.json` means transcribing every live scenario, every ticket role
+// and every check declaration out of documents the runtime has already parsed; that
+// transcription is the measured cost this removes (docs/prd-v7-pilots.md).
+//
+// What it must never do is decide. The draft carries no semantic judgment: an
+// unresolved scenario stays unresolved, a check command is never invented, a ticket
+// role is never guessed, and a scope disposition is never chosen. Candidate tickets
+// and their existing verification text are listed as *material to read*, with their
+// file provenance, never promoted into a link or a declaration.
+//
+// The envelope is `draft: 1` with no `schema` key, so `coverage.validateMap` refuses
+// it: a draft written to disk is not a coverage map and cannot become one by being
+// saved. The real map is authored by hand, validated by `coverage`, adopted by
+// `coverage adopt` and authorized by `change authorize`, exactly as before.
+//
+// Pure and read-only: nothing here writes a file, launches a check, changes a
+// selection or records an approval. The draft body carries no timestamp, so two calls
+// on identical authored inputs produce byte-identical output.
+const fs = require('node:fs');
+const path = require('node:path');
+const parse = require('./parse.cjs');
+const requirements = require('./requirements.cjs');
+const coverage = require('./coverage.cjs');
+
+const DRAFT = 1;
+const KIND = 'coverage-draft';
+const RUNTIME = 'node scripts/pincer-runtime.cjs';
+// Unresolved codes, in report order. These describe the draft, not the runtime state:
+// they say what a human still has to author, never what a gate will refuse.
+const UNRESOLVED_ORDER = ['SCENARIO_UNLINKED', 'CHECK_UNDECLARED', 'TICKET_UNCLASSIFIED', 'SCENARIO_STALE', 'TICKET_FOREIGN'];
+
+const AUTHORED = 'authored';
+const UNRESOLVED = 'unresolved';
+
+// The first line under a ticket heading, used as the objective a reviewer reads.
+function firstLine(text, heading) {
+  const rows = parse.lines(text);
+  const i = rows.findIndex(l => l.trim() === heading);
+  if (i === -1) return null;
+  const next = rows.slice(i + 1).find(l => l.trim() !== '');
+  return next ? next.trim() : null;
+}
+// The IDs a ticket's own Context section claims ("- Implements: R-04." and
+// "- Scenarios: S-10, S-11."). Classified against the live inventory rather than by
+// prefix, because tickets name other tickets on the same lines — T-03 of the strict
+// fixture says "Implements: none (enables T-01, T-02)", and reading that as two
+// scenario claims would be the draft inventing a link out of prose. An ID the
+// inventory does not define is not reported at all.
+const CLAIM_LINE = /^[ \t]*[-+*][ \t]+(?:Implements|Scenarios|Requirements):/;
+function claimsOf(text, inventory) {
+  const ids = new Set();
+  for (const row of parse.lines(text)) {
+    if (!CLAIM_LINE.test(row)) continue;
+    for (const id of row.match(new RegExp(requirements.ID, 'g')) || []) ids.add(id);
+  }
+  const claimed = [...ids];
+  return {
+    requirements: requirements.sortIds(claimed.filter(id => inventory.requirements[id])),
+    scenarios: requirements.sortIds(claimed.filter(id => inventory.scenarios[id])),
+  };
+}
+// The ticket's own Verification fence, verbatim, as provenance for a reviewer. It is
+// quoted, never turned into a check declaration: whether it proves the scenario is a
+// judgment the draft does not make.
+function verificationOf(text) {
+  const commands = parse.verificationCommands(text);
+  return commands && commands.length ? commands.join('\n') : null;
+}
+
+// build(root, record) → { ok, code, problems, draft }
+// `code` is set only when the inputs cannot be read; a missing map is the normal case
+// this command exists for, not an error.
+function build(root, record) {
+  const fail = (code, problems) => ({ ok: false, code, problems, draft: null });
+  const inv = requirements.readInventory(root, record.prd);
+  if (!inv.ok) return fail(inv.code, inv.problems);
+  const inventory = inv.inventory;
+
+  // An absent map is expected; an unreadable one is not — silently dropping authored
+  // content would be the one way this command could destroy work.
+  const rel = coverage.file(record.change);
+  const real = coverage.realFile(root, rel);
+  let authored = null;
+  if (!real) {
+    const m = coverage.readMap(root, record);
+    if (!m.ok) return fail(m.code, m.problems);
+    authored = m;
+  } else if (!real.endsWith(': missing')) {
+    return fail('COVERAGE_INVALID', [`${rel}: ${real.slice(rel.length + 2)}`]);
+  }
+
+  const t = coverage.ticketsOf(root, record);
+  if (!t.ok) return fail(t.code, t.problems);
+
+  const map = authored ? authored.map : null;
+  const unresolved = [];
+  const note = (code, id, detail) => unresolved.push({ code, id, detail });
+
+  // --- scenarios: every live scenario exactly once, authored rows preserved ----------
+  const scenarios = {};
+  const scope = {};
+  for (const id of requirements.sortIds(Object.keys(inventory.scenarios))) {
+    const live = inventory.scenarios[id];
+    const authoredScope = map && map.scope ? map.scope[id] : null;
+    if (authoredScope) {
+      scope[id] = { ...authoredScope, state: AUTHORED };
+      continue;
+    }
+    const row = map && map.scenarios ? map.scenarios[id] : null;
+    const tickets = row ? [...row.tickets] : [];
+    const checks = row ? [...row.checks] : [];
+    const resolved = Boolean(row) && tickets.length > 0 && checks.length > 0;
+    scenarios[id] = { requirement: live.requirement, state: resolved ? AUTHORED : UNRESOLVED, tickets, checks };
+    if (!row) note('SCENARIO_UNLINKED', id, `${id} (${live.requirement}) has no row in scenarios or scope`);
+    else if (!tickets.length) note('SCENARIO_UNLINKED', id, `${id} is linked to no ticket`);
+    else if (!checks.length) note('CHECK_UNDECLARED', id, `${id} is linked to no check`);
+  }
+  // A map row naming a scenario the inventory no longer defines is authored content:
+  // it is preserved and flagged, never deleted, because removing an obligation is a
+  // decision with its own disposition and authorization.
+  if (map) {
+    for (const id of requirements.sortIds(Object.keys(map.scenarios))) {
+      if (scenarios[id] || scope[id]) continue;
+      scenarios[id] = { requirement: null, state: UNRESOLVED, tickets: [...map.scenarios[id].tickets], checks: [...map.scenarios[id].checks] };
+      note('SCENARIO_STALE', id, `${id} has a row but is not a scenario of ${record.prd}`);
+    }
+    for (const id of requirements.sortIds(Object.keys(map.scope))) {
+      if (scope[id] || inventory.scenarios[id]) continue;
+      scope[id] = { ...map.scope[id], state: UNRESOLVED };
+      note('SCENARIO_STALE', id, `${id} has a scope row but is not a scenario of ${record.prd}`);
+    }
+  }
+
+  // --- tickets: authored roles preserved; unclassified tickets named, not classified --
+  const tickets = {};
+  for (const id of requirements.sortIds(Object.keys(t.tickets))) {
+    const row = map && map.tickets ? map.tickets[id] : null;
+    if (row) tickets[id] = { role: row.role, rationale: row.rationale, state: AUTHORED };
+    else {
+      tickets[id] = { role: null, rationale: null, state: UNRESOLVED };
+      note('TICKET_UNCLASSIFIED', id, `${id} has no role; classify it as implements or enables (an enabling ticket needs a rationale)`);
+    }
+  }
+  if (map) {
+    for (const id of requirements.sortIds(Object.keys(map.tickets))) {
+      if (tickets[id]) continue;
+      tickets[id] = { role: map.tickets[id].role, rationale: map.tickets[id].rationale, state: UNRESOLVED };
+      note(t.others[id] ? 'TICKET_FOREIGN' : 'SCENARIO_STALE', id,
+        t.others[id] ? `${id} is a ticket of ${t.others[id]}, not of ${record.prd}` : `${id} has a row but no ticket file is associated with ${record.prd}`);
+    }
+  }
+
+  // --- checks: authored declarations preserved verbatim; none invented ---------------
+  const checks = {};
+  if (map) for (const id of Object.keys(map.checks).sort()) checks[id] = { ...map.checks[id], state: AUTHORED };
+  // Every check a scenario links to must be declared; an undeclared one is named.
+  for (const [sid, row] of Object.entries(scenarios)) {
+    for (const c of row.checks) {
+      if (checks[c]) continue;
+      note('CHECK_UNDECLARED', c, `${c} is linked from ${sid} but has no declaration`);
+    }
+  }
+
+  // --- candidates: material to read, with provenance. Never a link. -----------------
+  const candidates = { tickets: {} };
+  for (const id of requirements.sortIds(Object.keys(t.tickets))) {
+    const entry = t.tickets[id];
+    const claims = claimsOf(entry.text, inventory);
+    candidates.tickets[id] = {
+      file: entry.file,
+      objective: firstLine(entry.text, '## Objective'),
+      implements: claims.requirements,
+      scenarios: claims.scenarios,
+      verification: verificationOf(entry.text),
+    };
+  }
+
+  unresolved.sort((a, b) => (UNRESOLVED_ORDER.indexOf(a.code) - UNRESOLVED_ORDER.indexOf(b.code)) || requirements.compareIds(a.id, b.id));
+  const draft = {
+    draft: DRAFT,
+    kind: KIND,
+    change: record.change,
+    prd: record.prd,
+    inventory: { digest: inventory.digest, requirements: Object.keys(inventory.requirements).length, scenarios: Object.keys(inventory.scenarios).length },
+    authored: { map: authored ? authored.file : null, digest: authored ? authored.digest : null },
+    scenarios, scope, tickets, checks, candidates, unresolved,
+    next: nextAction(record, unresolved, authored),
+  };
+  return { ok: true, code: null, problems: [], draft };
+}
+
+// What the reader does next. A complete draft does not adopt anything: it says the map
+// is ready to be reviewed and validated, which is a different claim from "correct".
+function nextAction(record, unresolved, authored) {
+  if (unresolved.length) {
+    const first = unresolved[0];
+    return { action: `author the unresolved entries (${unresolved.length}), starting with ${first.id}`, command: `edit ${coverage.file(record.change)} — ${first.detail}` };
+  }
+  if (!authored) return { action: 'author the map from this draft, then validate it', command: `edit ${coverage.file(record.change)}, then ${RUNTIME} coverage --change ${record.change}` };
+  return { action: 'review the authored map, then preview adoption', command: `${RUNTIME} coverage adopt --preview --change ${record.change}` };
+}
+
+function render(d) {
+  const lines = [];
+  const count = o => Object.keys(o).length;
+  lines.push(`PINCER coverage draft · change ${d.change} · ${d.prd}`);
+  lines.push(`Inventory  ${d.inventory.requirements} requirement(s), ${d.inventory.scenarios} scenario(s) · digest ${d.inventory.digest.slice(0, 12)}`);
+  lines.push(`Authored   ${d.authored.map ? `${d.authored.map} · digest ${d.authored.digest.slice(0, 12)}` : 'no map yet'}`);
+  lines.push('');
+  lines.push(`Scenarios  ${count(d.scenarios)} linked row(s), ${count(d.scope)} scope row(s)`);
+  for (const [id, s] of Object.entries(d.scenarios)) {
+    const marker = s.state === AUTHORED ? ' ' : '?';
+    lines.push(`  ${marker} ${id}  ${s.requirement || '(not in the inventory)'}  tickets ${s.tickets.length ? s.tickets.join(', ') : '—'}  checks ${s.checks.length ? s.checks.join(', ') : '—'}`);
+  }
+  for (const [id, s] of Object.entries(d.scope)) {
+    lines.push(`  ${s.state === AUTHORED ? ' ' : '?'} ${id}  scope: ${s.disposition}${s.decision ? ` (${s.decision})` : ''}${s.note ? ` — ${s.note}` : ''}`);
+  }
+  lines.push('');
+  lines.push(`Tickets    ${count(d.tickets)}`);
+  for (const [id, t] of Object.entries(d.tickets)) {
+    const c = d.candidates.tickets[id];
+    lines.push(`  ${t.state === AUTHORED ? ' ' : '?'} ${id}  role ${t.role || '—'}${t.rationale ? ` (${t.rationale})` : ''}${c && c.objective ? `  · ${c.objective}` : ''}`);
+    if (t.state !== AUTHORED && c) {
+      const claimed = [...c.implements, ...c.scenarios];
+      if (claimed.length) lines.push(`      the ticket says it implements ${claimed.join(', ')} (${c.file}) — a statement to check, not a link`);
+      if (c.verification) lines.push(`      its Verification block runs: ${c.verification.split('\n')[0]}${c.verification.includes('\n') ? ' …' : ''}`);
+    }
+  }
+  lines.push('');
+  lines.push(`Checks     ${count(d.checks)}`);
+  for (const [id, c] of Object.entries(d.checks)) {
+    lines.push(`  ${c.state === AUTHORED ? ' ' : '?'} ${id}  ${c.kind}${c.required ? ', required' : ''}  ${c.kind === 'command' ? c.command : c.obligation}`);
+  }
+  if (!count(d.checks)) lines.push('    none declared — a check is authored, never derived from a ticket');
+  lines.push('');
+  if (d.unresolved.length) {
+    lines.push(`Unresolved ${d.unresolved.length}`);
+    for (const u of d.unresolved) lines.push(`  ${u.code}  ${u.detail}`);
+  } else {
+    lines.push('Unresolved none — every scenario has a row, every ticket a role, every linked check a declaration');
+  }
+  lines.push('');
+  lines.push('This is a draft, not a coverage map: it carries no schema, and `coverage`,');
+  lines.push('`coverage adopt` and the agreement digest do not accept it. Author');
+  lines.push(`${coverage.file(d.change)} yourself, review the links, then validate and adopt it.`);
+  lines.push(`Next       ${d.next.action}: ${d.next.command}`);
+  return `${lines.join('\n')}\n`;
+}
+
+module.exports = { DRAFT, KIND, UNRESOLVED_ORDER, AUTHORED, UNRESOLVED, build, render, nextAction };

package/template/scripts/pincer-runtime/state.cjs

@@ -9,6 +9,7 @@ const os = require('node:os');
 const path = require('node:path');
 const crypto = require('node:crypto');
 const { nowIso, atomicWrite, readJson } = require('./fsutil.cjs');
+const io = require('./io.cjs');
 
 const RUNTIME_DIR = '.pincer/runtime';
 const INDEX_SCHEMA = 1;
@@ -34,6 +35,9 @@ function ensureLayout(root) {
   return p;
 }
 const exists = root => fs.existsSync(paths(root).dir);
+// Local attempt history exists once an index was written; a selection alone (a fresh
+// clone that ran `change select`) is not attempt history.
+const hasIndex = root => fs.existsSync(paths(root).index);
 
 const emptyIndex = () => ({ schema: INDEX_SCHEMA, sequence: 0, current: {}, running: [] });
 function validateIndex(doc) {
@@ -73,7 +77,7 @@ class StateBusy extends Error {
 // Acquire the exclusive lock: mkdir is atomic; a lock whose owner pid is dead on
 // this host is reclaimed with a diagnostic; a live or foreign-host owner is never
 // stolen. Returns a release function.
-function acquireLock(root, { waitMs, command = 'runtime', log = message => process.stderr.write(`${message}\n`) } = {}) {
+function acquireLock(root, { waitMs, command = 'runtime', log = message => io.err(`${message}\n`) } = {}) {
   const p = ensureLayout(root);
   const bound = waitMs ?? (Number(process.env.PINCER_LOCK_WAIT_MS) > 0 ? Number(process.env.PINCER_LOCK_WAIT_MS) : LOCK_WAIT_MS);
   const deadline = Date.now() + bound;
@@ -124,7 +128,12 @@ function withLock(root, fn, options) {
 
 const compactTimestamp = () => nowIso().replace(/[-:]/g, '');
 const attemptId = sequence => `${String(sequence).padStart(6, '0')}-${compactTimestamp()}-${crypto.randomBytes(3).toString('hex')}`;
-const contextKey = context => (context.kind === 'candidate' ? `candidate:${context.candidate}:${context.check}` : `ticket:${context.change}:${context.ticket}`);
+// Context keys (docs/runtime-contracts.md, "Attempts"): ticket keys are change-scoped
+// in every runtime mode; candidate keys gain the change in changes mode (schema 2
+// records) so two changes sharing a check ID and a candidate never share a pointer.
+const contextKey = context => (context.kind === 'candidate'
+  ? (context.mode === 'changes' || context.agreement ? `candidate:${context.change}:${context.candidate}:${context.check}` : `candidate:${context.candidate}:${context.check}`)
+  : `ticket:${context.change}:${context.ticket}`);
 
 const OUTCOMES = ['running', 'passed', 'failed', 'interrupted', 'timed_out', 'error'];
 const SHA256 = /^[0-9a-f]{64}$/;
@@ -140,13 +149,19 @@ function validateAttempt(a, key, pointedId) {
   const digestOrNull = v => v === null || (typeof v === 'string' && SHA256.test(v));
   if (!obj(a)) return 'record is not a JSON object';
   const bad = [];
-  if (a.schema !== 1) bad.push('schema');
-  if (a.runtime !== 1) bad.push('runtime');
+  // Schema 1 (migrated mode), schema 2 (changes mode: the agreement digest is part
+  // of the context) and schema 3 (strict coverage: inventory and coverage digests
+  // too) share every other field.
+  if (![1, 2, 3].includes(a.schema)) bad.push('schema');
+  if (a.runtime !== a.schema) bad.push('runtime');
   if (!str(a.id)) bad.push('id');
   if (!Number.isInteger(a.sequence) || a.sequence < 1) bad.push('sequence');
   const c = a.context;
   if (!obj(c) || !['ticket', 'candidate'].includes(c.kind) || !str(c.change) || !str(c.prd) || !str(c.prd_revision) || !str(c.base)
-    || (c.kind === 'ticket' ? !str(c.ticket) || !str(c.ticket_digest) : !str(c.candidate) || !str(c.check))) bad.push('context');
+    || (c.kind === 'ticket' ? !str(c.ticket) || !str(c.ticket_digest) : !str(c.candidate) || !str(c.check))
+    || (a.schema === 1 ? 'agreement' in c || 'inventory' in c || 'coverage' in c
+      : !(typeof c.agreement === 'string' && SHA256.test(c.agreement))
+        || (a.schema === 2 ? 'inventory' in c || 'coverage' in c : !(typeof c.inventory === 'string' && SHA256.test(c.inventory) && typeof c.coverage === 'string' && SHA256.test(c.coverage))))) bad.push('context');
   if (!obj(a.check) || typeof a.check.digest !== 'string' || !SHA256.test(a.check.digest) || typeof a.check.display !== 'string'
     || !Number.isInteger(a.check.timeout_seconds) || a.check.timeout_seconds <= 0) bad.push('check');
   if (!OUTCOMES.includes(a.outcome)) bad.push('outcome');
@@ -231,10 +246,14 @@ function latestAttempt(root, key, index) {
 function recover(root, options = {}) {
   return withLock(root, () => {
     const p = paths(root);
+    // Committed-but-unapplied transactions are completed and uncommitted staging
+    // is discarded before anything else is read (docs/runtime-contracts.md,
+    // "Transactions and recovery"); required lazily to avoid a module cycle.
+    const transactions = require('./transaction.cjs').recoverPending(root);
     const read = readIndex(root);
     if (read.error) { const e = new Error(read.error); e.code = 'INVALID'; throw e; }
     const index = read.index;
-    const report = { finalized: [], live: [], foreign: [], missing: [], journal: [] };
+    const report = { finalized: [], live: [], foreign: [], missing: [], journal: [], transactions };
     const stillRunning = [];
     for (const id of index.running) {
       const attempt = readAttempt(root, id).attempt;
@@ -274,6 +293,9 @@ function recover(root, options = {}) {
     if (fs.existsSync(p.journal)) {
       for (const name of fs.readdirSync(p.journal)) {
         const file = path.join(p.journal, name);
+        let stat = null;
+        try { stat = fs.lstatSync(file); } catch { continue; }
+        if (stat.isDirectory()) continue; // transaction staging is handled above; an unreadable manifest stays for inspection
         try { fs.rmSync(file, { force: true }); report.journal.push(`${RUNTIME_DIR}/journal/${name}`); } catch { /* ignore */ }
       }
     }
@@ -287,6 +309,6 @@ function recover(root, options = {}) {
 
 module.exports = {
   RUNTIME_DIR, INDEX_SCHEMA, LOCK_WAIT_MS, StateBusy,
-  paths, ensureLayout, exists, emptyIndex, readIndex, writeIndex, isAlive,
+  paths, ensureLayout, exists, hasIndex, emptyIndex, readIndex, writeIndex, isAlive,
   acquireLock, withLock, attemptId, contextKey, validateAttempt, inspectArtifacts, writeAttempt, readAttempt, listAttempts, latestAttempt, recover,
 };