pincer-workflow 0.4.0 → 0.5.0

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

@@ -0,0 +1,63 @@
+'use strict';
+// PINCER runtime — output sanitizer (docs/runtime-contracts.md, "Capture and
+// sanitization"). A safety net applied to every captured line and to command
+// display text before anything is persisted: documented secret patterns are
+// replaced by [redacted] and counted. It is not a guarantee; checks must avoid
+// printing secrets, and no raw log is ever exported.
+const PATTERNS = [
+  // Bearer tokens first, so an `Authorization: Bearer <token>` header keeps the
+  // token, not the word Bearer, as the redacted value.
+  { re: /((?:bearer|basic|token|digest)\s+)[A-Za-z0-9\-._~+/=]+/gi, replace: '$1[redacted]' },
+  // key/secret/password/token/authorization assignments and JSON fields; a
+  // quoted value is redacted up to its closing quote, an unquoted one to the
+  // next whitespace or separator. Bounded quantifiers: an unbounded prefix would
+  // backtrack quadratically on long lines.
+  { re: /((?:^|[^A-Za-z0-9_.-])[A-Za-z0-9_.-]{0,64}?(?:key|secret|password|passwd|token|authorization)[A-Za-z0-9_.-]{0,64}["']?[ \t]{0,8}[:=][ \t]{0,8})(?:"([^"\n]{0,512})"|'([^'\n]{0,512})'|([^\s"',;]+))/gi, replace: (m, head, dq, sq, bare) => `${head}${dq !== undefined ? '"[redacted]"' : sq !== undefined ? "'[redacted]'" : '[redacted]'}` },
+  { re: /AKIA[0-9A-Z]{16}/g, replace: '[redacted]' },
+  { re: /gh[pousr]_[A-Za-z0-9]{20,}/g, replace: '[redacted]' },
+];
+const PEM_BEGIN = /-----BEGIN [A-Z ]*PRIVATE KEY-----/;
+const PEM_END = /-----END [A-Z ]*PRIVATE KEY-----/;
+
+// Stateful: PEM private key blocks span lines. `state` is a plain object the
+// caller keeps per stream.
+function sanitizeLine(line, state = {}) {
+  let redactions = 0;
+  if (state.inPem) {
+    if (PEM_END.test(line)) state.inPem = false;
+    return { text: '[redacted]', redactions: 1 };
+  }
+  if (PEM_BEGIN.test(line)) {
+    state.inPem = !PEM_END.test(line);
+    return { text: '[redacted]', redactions: 1 };
+  }
+  let text = line;
+  for (const { re, replace } of PATTERNS) {
+    text = text.replace(re, (...args) => {
+      redactions++;
+      return typeof replace === 'function' ? replace(...args) : replace.replace(/\$(\d)/g, (_, n) => args[Number(n)]);
+    });
+  }
+  return { text, redactions };
+}
+
+function sanitizeText(text) {
+  const state = {};
+  let redactions = 0;
+  const lines = String(text).split('\n').map(line => { const r = sanitizeLine(line, state); redactions += r.redactions; return r.text; });
+  return { text: lines.join('\n'), redactions };
+}
+
+// A Verification block must not carry an inline secret literal: the block is
+// recorded as display text and would persist the value. `$references` and
+// empty values are fine.
+// An assignment anywhere in the line (after a word boundary, so `env TOKEN=x cmd`
+// and `true; TOKEN=x cmd` count); `$VAR`, `"$VAR"`, `$(…)` and backtick
+// references are allowed, literals are not.
+const INLINE_SECRET = /(?:^|[\s;&|(])(?:export\s+)?[A-Za-z0-9_]*(?:KEY|SECRET|PASSWORD|PASSWD|TOKEN)[A-Za-z0-9_]*=(?!["']?\$|["']?`|\s|$)\S/i;
+function inlineSecretLine(commands) {
+  const index = commands.findIndex(line => INLINE_SECRET.test(line));
+  return index === -1 ? null : index + 1;
+}
+
+module.exports = { sanitizeLine, sanitizeText, inlineSecretLine, PATTERNS };

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

@@ -0,0 +1,129 @@
+'use strict';
+// PINCER runtime — the source manifest (docs/runtime-contracts.md, "Source
+// manifest"): a versioned SHA-256 identity of the inputs a verification ran
+// against. Tracked plus untracked non-ignored files, modes, deletions; tickets
+// and PRDs normalized; fixed and configured exclusions; secret paths, symlinks
+// and submodules refused rather than silently omitted.
+const fs = require('node:fs');
+const path = require('node:path');
+const parse = require('./parse.cjs');
+const { atomicWrite, tryGit } = require('./fsutil.cjs');
+
+const SCHEMA = 1;
+const FIXED_EXCLUDES = ['.git/', '.pincer/', 'NOTES.md', '.prd/evidence/', '.prd/changes/'];
+const EXCLUDE_FILE = '.prd/source-exclude';
+const PROTECTED_PREFIXES = ['tickets/'];
+const NUL = String.fromCharCode(0);
+
+const isTicket = p => /^tickets\/T-[0-9]+.*\.md$/.test(p);
+const isPrd = p => parse.PRD_REF.test(p);
+const isSecret = p => { const b = path.posix.basename(p); return b === '.env' || (b.startsWith('.env.') && b !== '.env.example'); };
+const fixedExcluded = p => FIXED_EXCLUDES.some(rule => (rule.endsWith('/') ? p.startsWith(rule) : p === rule));
+
+// Glob -> RegExp: `**` spans directories, `*` stays within a segment, `?` is one
+// character; a pattern without `/` matches a basename anywhere; a trailing `/`
+// matches a directory prefix.
+function compilePattern(pattern) {
+  const escape = s => s.replace(/[.+^${}()|[\]\\]/g, '\\$&');
+  const glob = s => escape(s).replace(/\*\*/g, 'DOUBLESTAR').replace(/\*/g, '[^/]*').replace(/\?/g, '[^/]').replace(/DOUBLESTAR/g, '.*');
+  if (pattern.endsWith('/')) return new RegExp(`^${glob(pattern.slice(0, -1))}/`);
+  if (!pattern.includes('/')) return new RegExp(`(^|/)${glob(pattern)}$`);
+  return new RegExp(`^${glob(pattern.replace(/^\//, ''))}$`);
+}
+function readExcludeFile(root) {
+  const file = path.join(root, EXCLUDE_FILE);
+  if (!fs.existsSync(file)) return [];
+  return fs.readFileSync(file, 'utf8').split('\n').map(l => l.trim()).filter(l => l && !l.startsWith('#'));
+}
+
+const splitZ = buffer => (buffer ? buffer.toString('utf8').split(NUL).filter(Boolean) : []);
+
+// Compute the manifest. Returns { schema, digest, files, excluded, limitations, problems }.
+function snapshot(root) {
+  const problems = [];
+  const limitations = [];
+  const excluded = [];
+  const toplevel = tryGit(root, ['rev-parse', '--show-toplevel']);
+  if (toplevel.error) {
+    return { schema: SCHEMA, digest: null, files: [], excluded, limitations, problems: [{ code: 'UNSUPPORTED_INPUT', detail: 'not inside a git repository; the source identity needs git' }] };
+  }
+  const tracked = new Map(); // path -> mode from the index
+  const staged = tryGit(root, ['ls-files', '-z', '-s'], { buffer: true });
+  if (staged.error) problems.push({ code: 'UNSUPPORTED_INPUT', detail: `git ls-files failed: ${staged.error}` });
+  else {
+    for (const entry of splitZ(staged.out)) {
+      const match = entry.match(/^(\d{6}) [0-9a-f]{40} \d\t([\s\S]*)$/);
+      if (match) tracked.set(match[2], match[1]);
+    }
+  }
+  const listed = tryGit(root, ['ls-files', '-z', '--cached', '--others', '--exclude-standard'], { buffer: true });
+  const paths = listed.error ? [] : [...new Set(splitZ(listed.out))];
+  const deleted = new Set(splitZ(tryGit(root, ['ls-files', '-z', '--deleted'], { buffer: true }).out));
+  const ignoredDirs = splitZ(tryGit(root, ['ls-files', '-z', '--others', '--ignored', '--exclude-standard', '--directory'], { buffer: true }).out)
+    .filter(p => !p.startsWith('.pincer/') && p !== '.pincer/');
+  if (ignoredDirs.length) {
+    const shown = ignoredDirs.slice(0, 10).join(', ') + (ignoredDirs.length > 10 ? `, ... (${ignoredDirs.length} ignored paths)` : '');
+    limitations.push(`ignored paths are not part of the source identity: ${shown}`);
+  }
+  limitations.push('external services and installed toolchains are not part of the source identity');
+
+  const patterns = readExcludeFile(root).map(pattern => ({ pattern, regex: compilePattern(pattern) }));
+  const entries = [];
+  for (const p of paths) {
+    if (fixedExcluded(p)) { excluded.push(p); continue; }
+    if (isSecret(p)) { problems.push({ code: 'SECRET_PATH', detail: `${p}: secret file in the source view; remove it or ignore it (its contents were not read)` }); continue; }
+    const mode = tracked.get(p);
+    if (mode === '160000') { problems.push({ code: 'UNSUPPORTED_INPUT', detail: `${p}: submodules are not supported` }); continue; }
+    const abs = path.join(root, p);
+    let stat = null;
+    try { stat = fs.lstatSync(abs); } catch { stat = null; }
+    if (mode === '120000' || (stat && stat.isSymbolicLink())) { problems.push({ code: 'UNSUPPORTED_INPUT', detail: `${p}: symbolic links are not supported` }); continue; }
+    const rule = patterns.find(({ regex }) => regex.test(p));
+    if (rule) {
+      if (PROTECTED_PREFIXES.some(prefix => p.startsWith(prefix)) || isPrd(p) || p === EXCLUDE_FILE) problems.push({ code: 'UNSUPPORTED_INPUT', detail: `${EXCLUDE_FILE}: pattern "${rule.pattern}" matches protected path ${p}` });
+      else if (tracked.has(p)) problems.push({ code: 'UNSUPPORTED_INPUT', detail: `${EXCLUDE_FILE}: pattern "${rule.pattern}" matches tracked file ${p}; exclusions may cover untracked paths only` });
+      else excluded.push(p);
+      continue;
+    }
+    if (deleted.has(p) || !stat) { entries.push({ path: p, deleted: true }); continue; }
+    if (stat.isDirectory()) continue;
+    let content;
+    try { content = fs.readFileSync(abs); } catch (error) { problems.push({ code: 'UNSUPPORTED_INPUT', detail: `${p}: cannot read (${error.code || error.message})` }); continue; }
+    let sha;
+    if (isTicket(p)) sha = parse.sha256(parse.normalizeTicket(content.toString('utf8')));
+    else if (isPrd(p)) sha = parse.sha256(parse.normalizePrd(content.toString('utf8')));
+    else sha = parse.sha256(content);
+    entries.push({ path: p, sha256: sha, mode: (stat.mode & 0o111) ? '100755' : '100644' });
+  }
+  entries.sort((a, b) => Buffer.compare(Buffer.from(a.path), Buffer.from(b.path)));
+  const digestInput = entries.map(e => `${e.deleted ? 'deleted' : e.mode} ${e.deleted ? '-' : e.sha256} ${e.path}\n`).join('');
+  const digest = problems.length ? null : parse.sha256(digestInput);
+  return { schema: SCHEMA, digest, files: entries, excluded, limitations, problems };
+}
+
+function storeManifest(root, manifest) {
+  if (!manifest.digest) throw new Error('cannot store a manifest with problems');
+  const file = path.join(root, '.pincer', 'runtime', 'manifests', `${manifest.digest}.json`);
+  if (!fs.existsSync(file)) atomicWrite(file, `${JSON.stringify(manifest, null, 2)}\n`, { journalDir: path.join(root, '.pincer', 'runtime', 'journal') });
+  return `.pincer/runtime/manifests/${manifest.digest}.json`;
+}
+function readManifest(root, digest) {
+  const file = path.join(root, '.pincer', 'runtime', 'manifests', `${digest}.json`);
+  try { return JSON.parse(fs.readFileSync(file, 'utf8')); } catch { return null; }
+}
+
+// Paths that differ between two manifests, for diagnostics.
+function diffManifests(before, after) {
+  const a = new Map(before.files.map(e => [e.path, e]));
+  const b = new Map(after.files.map(e => [e.path, e]));
+  const changed = [];
+  for (const [p, e] of b) {
+    const prior = a.get(p);
+    if (!prior) changed.push(`${p} (added)`);
+    else if (JSON.stringify(prior) !== JSON.stringify(e)) changed.push(`${p}${e.deleted ? ' (deleted)' : prior.mode !== e.mode ? ' (mode)' : ''}`);
+  }
+  for (const p of a.keys()) if (!b.has(p)) changed.push(`${p} (removed)`);
+  return changed;
+}
+
+module.exports = { SCHEMA, FIXED_EXCLUDES, EXCLUDE_FILE, snapshot, storeManifest, readManifest, diffManifests, compilePattern, isSecret };

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

@@ -0,0 +1,292 @@
+'use strict';
+// PINCER runtime — local state store (docs/runtime-contracts.md, "Attempts").
+// Everything under <root>/.pincer/runtime/ belongs to this worktree: an index
+// with the authoritative sequence and current pointers, one record per attempt,
+// content-addressed source manifests, an exclusive lock directory and a journal
+// for atomic replacement. Nothing here is a second editable truth.
+const fs = require('node:fs');
+const os = require('node:os');
+const path = require('node:path');
+const crypto = require('node:crypto');
+const { nowIso, atomicWrite, readJson } = require('./fsutil.cjs');
+
+const RUNTIME_DIR = '.pincer/runtime';
+const INDEX_SCHEMA = 1;
+const LOCK_WAIT_MS = 10000;
+const LOCK_POLL_MS = 100;
+const GRACE_MS = 5000;
+
+function paths(root) {
+  const dir = path.join(root, RUNTIME_DIR);
+  return {
+    dir,
+    index: path.join(dir, 'index.json'),
+    attempts: path.join(dir, 'attempts'),
+    manifests: path.join(dir, 'manifests'),
+    lock: path.join(dir, 'lock'),
+    owner: path.join(dir, 'lock', 'owner.json'),
+    journal: path.join(dir, 'journal'),
+  };
+}
+function ensureLayout(root) {
+  const p = paths(root);
+  for (const dir of [p.dir, p.attempts, p.manifests, p.journal]) fs.mkdirSync(dir, { recursive: true });
+  return p;
+}
+const exists = root => fs.existsSync(paths(root).dir);
+
+const emptyIndex = () => ({ schema: INDEX_SCHEMA, sequence: 0, current: {}, running: [] });
+function validateIndex(doc) {
+  if (!doc || typeof doc !== 'object' || Array.isArray(doc)) return 'index must be a JSON object';
+  if (doc.schema !== INDEX_SCHEMA) return `unsupported index schema ${JSON.stringify(doc.schema)}`;
+  if (!Number.isInteger(doc.sequence) || doc.sequence < 0) return 'sequence must be a non-negative integer';
+  if (!doc.current || typeof doc.current !== 'object' || Array.isArray(doc.current)) return 'current must be an object';
+  if (!Array.isArray(doc.running) || !doc.running.every(id => typeof id === 'string')) return 'running must be an array of attempt IDs';
+  return null;
+}
+// Read the index; a missing file is an empty index, a malformed one is an error
+// (code INVALID) and is never overwritten by inspection.
+function readIndex(root) {
+  const p = paths(root);
+  if (!fs.existsSync(p.index)) return { index: emptyIndex(), missing: true };
+  const read = readJson(p.index);
+  if (read.error) return { error: `${RUNTIME_DIR}/index.json: ${read.error}`, code: 'INVALID' };
+  const invalid = validateIndex(read.data);
+  if (invalid) return { error: `${RUNTIME_DIR}/index.json: ${invalid}`, code: 'INVALID' };
+  return { index: read.data };
+}
+function writeIndex(root, index) {
+  const p = ensureLayout(root);
+  atomicWrite(p.index, `${JSON.stringify(index, null, 2)}\n`, { journalDir: p.journal });
+}
+
+function isAlive(pid) {
+  if (!Number.isInteger(pid) || pid <= 0) return false;
+  try { process.kill(pid, 0); return true; } catch (error) { return error.code === 'EPERM'; }
+}
+function sleep(ms) { Atomics.wait(new Int32Array(new SharedArrayBuffer(4)), 0, 0, ms); }
+
+class StateBusy extends Error {
+  constructor(message, owner) { super(message); this.code = 'STATE_BUSY'; this.owner = owner; }
+}
+
+// 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`) } = {}) {
+  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;
+  const ownerJson = () => `${JSON.stringify({ pid: process.pid, ppid: process.ppid, host: os.hostname(), started: nowIso(), command }, null, 2)}\n`;
+  for (;;) {
+    // Build the lock directory with its owner file in a private location and
+    // rename it into place: a directory rename onto an existing lock fails, so
+    // acquisition is atomic and a waiter never sees an owner-less lock.
+    const staging = `${p.lock}.new.${process.pid}.${crypto.randomBytes(3).toString('hex')}`;
+    try {
+      fs.mkdirSync(staging);
+      fs.writeFileSync(path.join(staging, 'owner.json'), ownerJson());
+      fs.renameSync(staging, p.lock);
+      let released = false;
+      return () => { if (released) return; released = true; try { fs.rmSync(p.lock, { recursive: true, force: true }); } catch { /* already gone */ } };
+    } catch (error) {
+      try { fs.rmSync(staging, { recursive: true, force: true }); } catch { /* nothing staged */ }
+      if (!['EEXIST', 'ENOTEMPTY', 'EISDIR', 'EPERM'].includes(error.code)) throw error;
+    }
+    const owner = readJson(p.owner).data || null;
+    if (owner && owner.host === os.hostname() && !isAlive(owner.pid)) {
+      // Claim the stale directory by renaming it first; only the process that
+      // won the rename removes it, after confirming the owner is still the
+      // dead one it read (another waiter may have replaced the lock meanwhile).
+      const claim = `${p.lock}.stale.${process.pid}.${crypto.randomBytes(3).toString('hex')}`;
+      try { fs.renameSync(p.lock, claim); } catch { sleep(LOCK_POLL_MS); continue; }
+      const claimed = readJson(path.join(claim, 'owner.json')).data || null;
+      if (claimed && claimed.host === os.hostname() && !isAlive(claimed.pid)) {
+        log(`pincer: reclaiming stale lock left by pid ${claimed.pid} (${claimed.command || 'unknown command'}, started ${claimed.started || '?'}); the process is no longer running`);
+        try { fs.rmSync(claim, { recursive: true, force: true }); } catch { /* best effort */ }
+      } else {
+        // A live holder's lock was renamed by mistake: give it back.
+        try { fs.renameSync(claim, p.lock); } catch { try { fs.rmSync(claim, { recursive: true, force: true }); } catch { /* gone */ } }
+      }
+      continue;
+    }
+    if (Date.now() >= deadline) {
+      const who = owner ? `pid ${owner.pid} on ${owner.host} (${owner.command || 'unknown command'}, started ${owner.started || '?'})` : 'an unknown owner (no owner.json)';
+      throw new StateBusy(`${RUNTIME_DIR}/lock is held by ${who}; retry, or run recover if that process died`, owner);
+    }
+    sleep(LOCK_POLL_MS);
+  }
+}
+function withLock(root, fn, options) {
+  const release = acquireLock(root, options);
+  try { return fn(); } finally { release(); }
+}
+
+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}`);
+
+const OUTCOMES = ['running', 'passed', 'failed', 'interrupted', 'timed_out', 'error'];
+const SHA256 = /^[0-9a-f]{64}$/;
+// Validate an attempt record read from disk against record schema 1 and, when
+// given, the context `key` it is read for and the `pointedId` the index names.
+// A record that is incomplete, malformed, written for another context or
+// carrying another id than the pointer is never evidence: readiness reports
+// ATTEMPT_ERROR and export refuses. An `interrupted` record may lack log
+// digests (a `recover` that predates their recording). Returns null or a problem.
+function validateAttempt(a, key, pointedId) {
+  const obj = v => v && typeof v === 'object' && !Array.isArray(v);
+  const str = v => typeof v === 'string' && v.length > 0;
+  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');
+  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');
+  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');
+  const finished = OUTCOMES.includes(a.outcome) && a.outcome !== 'running';
+  if (!(a.exit_code === null || Number.isInteger(a.exit_code))) bad.push('exit_code');
+  if (!(a.signal === null || str(a.signal))) bad.push('signal');
+  if (!obj(a.runner) || !str(a.runner.shell) || !Array.isArray(a.runner.args)) bad.push('runner');
+  if (!str(a.cwd)) bad.push('cwd');
+  if (!obj(a.environment)) bad.push('environment');
+  if (!str(a.started)) bad.push('started');
+  if (finished ? !str(a.finished) : a.finished !== null) bad.push('finished');
+  if (!obj(a.source) || !digestOrNull(a.source.before) || !digestOrNull(a.source.after)) bad.push('source');
+  if (!obj(a.artifacts)) bad.push('artifacts');
+  else {
+    for (const k of ['stdout', 'stderr']) {
+      const info = a.artifacts[k];
+      const expectedPath = str(a.id) ? `${RUNTIME_DIR}/attempts/${a.id}/${k}.log` : null;
+      const digestRequired = finished && a.outcome !== 'interrupted';
+      if (!obj(info) || info.path !== expectedPath || !(digestRequired ? typeof info.sha256 === 'string' && SHA256.test(info.sha256) : digestOrNull(info.sha256))) bad.push(`artifacts.${k}`);
+    }
+  }
+  if (bad.length) return `record is incomplete or malformed: ${bad.join(', ')}`;
+  if (key && contextKey(c) !== key) return `record belongs to ${contextKey(c)}, not ${key}`;
+  if (pointedId && a.id !== pointedId) return `record ${a.id} is not the attempt the index points at (${pointedId})`;
+  return null;
+}
+// Compare an attempt's captured logs with local state: `missing` when a log is
+// gone, `altered` when its content no longer matches the digest the record
+// carries. Annotates and returns the record; never writes.
+function inspectArtifacts(root, attempt) {
+  if (!attempt || !attempt.artifacts || typeof attempt.artifacts !== 'object') return attempt;
+  for (const k of ['stdout', 'stderr']) {
+    const info = attempt.artifacts[k];
+    if (!info || typeof info !== 'object' || typeof info.path !== 'string') continue;
+    let data;
+    try { data = fs.readFileSync(path.join(root, info.path)); } catch { attempt.artifacts[k] = { ...info, missing: true }; continue; }
+    if (attempt.outcome !== 'running' && typeof info.sha256 === 'string' && crypto.createHash('sha256').update(data).digest('hex') !== info.sha256) attempt.artifacts[k] = { ...info, altered: true };
+  }
+  return attempt;
+}
+
+function attemptFile(root, id) { return path.join(paths(root).attempts, `${id}.json`); }
+function writeAttempt(root, attempt) {
+  const p = ensureLayout(root);
+  atomicWrite(attemptFile(root, attempt.id), `${JSON.stringify(attempt, null, 2)}\n`, { journalDir: p.journal });
+}
+function readAttempt(root, id) {
+  const read = readJson(attemptFile(root, id));
+  if (read.error) return { error: `${RUNTIME_DIR}/attempts/${id}.json: ${read.error}` };
+  return { attempt: read.data };
+}
+function listAttempts(root, key) {
+  const p = paths(root);
+  if (!fs.existsSync(p.attempts)) return [];
+  const out = [];
+  for (const name of fs.readdirSync(p.attempts)) {
+    if (!name.endsWith('.json') || name.startsWith('.')) continue;
+    const read = readJson(path.join(p.attempts, name));
+    if (read.error || !read.data || typeof read.data !== 'object') continue;
+    if (!key || contextKey(read.data.context || {}) === key) out.push(read.data);
+  }
+  return out.sort((a, b) => (a.sequence || 0) - (b.sequence || 0));
+}
+// The attempt the index points at for a context. The pointer is the authority:
+// a pointed-at record that is missing or unreadable yields null (readiness then
+// reports EVIDENCE_MISSING) rather than an older record that may have passed.
+// Only when the index carries no pointer at all is the highest sequence used.
+function latestAttempt(root, key, index) {
+  const idx = index || readIndex(root).index;
+  const pointed = idx && idx.current && idx.current[key];
+  if (pointed) {
+    const read = readAttempt(root, pointed);
+    return read.attempt || null;
+  }
+  const all = listAttempts(root, key);
+  return all.length ? all[all.length - 1] : null;
+}
+
+// Diagnose and repair after a crash: finalize running attempts whose owner is
+// dead on this host as interrupted, report the rest, remove stray journal files.
+// Never promotes an unfinished record to passed.
+function recover(root, options = {}) {
+  return withLock(root, () => {
+    const p = paths(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 stillRunning = [];
+    for (const id of index.running) {
+      const attempt = readAttempt(root, id).attempt;
+      if (!attempt) { report.missing.push(id); continue; }
+      if (attempt.outcome !== 'running') continue;
+      const owner = attempt.owner || {};
+      if (owner.host !== os.hostname()) { report.foreign.push({ id, owner }); stillRunning.push(id); continue; }
+      if (isAlive(owner.pid)) { report.live.push({ id, owner }); stillRunning.push(id); continue; }
+      attempt.outcome = 'interrupted';
+      attempt.finished = nowIso();
+      attempt.limitations = [...(attempt.limitations || []), `finalized as interrupted by recover: owner pid ${owner.pid} was no longer running`];
+      // Record what the dead runner captured so the logs are bound to the
+      // record like every finalized attempt's (a missing log stays unrecorded).
+      for (const k of ['stdout', 'stderr']) {
+        const info = attempt.artifacts && attempt.artifacts[k];
+        if (!info || typeof info.path !== 'string') continue;
+        try { const data = fs.readFileSync(path.join(root, info.path)); attempt.artifacts[k] = { ...info, sha256: crypto.createHash('sha256').update(data).digest('hex'), bytes: data.length }; } catch { /* leave as recorded */ }
+      }
+      const childPid = attempt.child && attempt.child.pid;
+      if (childPid && isAlive(childPid)) {
+        // Terminate the orphaned group and wait for it here: an unref'd timer
+        // would never fire before the command exits.
+        const signalGroup = signal => { try { process.kill(-childPid, signal); } catch { try { process.kill(childPid, signal); } catch { /* gone */ } } };
+        signalGroup('SIGTERM');
+        const deadline = Date.now() + GRACE_MS;
+        while (isAlive(childPid) && Date.now() < deadline) sleep(LOCK_POLL_MS);
+        if (isAlive(childPid)) {
+          signalGroup('SIGKILL');
+          const hardDeadline = Date.now() + 2000;
+          while (isAlive(childPid) && Date.now() < hardDeadline) sleep(LOCK_POLL_MS);
+          attempt.limitations.push(`orphaned child process group ${childPid} ignored SIGTERM for ${GRACE_MS / 1000} s and was sent SIGKILL${isAlive(childPid) ? ' (still alive when recover returned)' : ''}`);
+        } else attempt.limitations.push(`orphaned child process group ${childPid} was sent SIGTERM and exited`);
+      }
+      writeAttempt(root, attempt);
+      report.finalized.push(id);
+    }
+    if (fs.existsSync(p.journal)) {
+      for (const name of fs.readdirSync(p.journal)) {
+        const file = path.join(p.journal, name);
+        try { fs.rmSync(file, { force: true }); report.journal.push(`${RUNTIME_DIR}/journal/${name}`); } catch { /* ignore */ }
+      }
+    }
+    if (stillRunning.length !== index.running.length || report.missing.length) {
+      index.running = stillRunning;
+      writeIndex(root, index);
+    }
+    return report;
+  }, { command: 'recover', ...options });
+}
+
+module.exports = {
+  RUNTIME_DIR, INDEX_SCHEMA, LOCK_WAIT_MS, StateBusy,
+  paths, ensureLayout, exists, emptyIndex, readIndex, writeIndex, isAlive,
+  acquireLock, withLock, attemptId, contextKey, validateAttempt, inspectArtifacts, writeAttempt, readAttempt, listAttempts, latestAttempt, recover,
+};