pincer-workflow 0.4.0 → 0.5.0

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

@@ -0,0 +1,297 @@
+'use strict';
+// PINCER runtime — parser and validator for the supported Markdown grammar
+// (docs/runtime-contracts.md, "Supported grammar" and "Content revisions").
+// Dependency-free. The rules and diagnostics match the v0.4.1 Bash validators
+// so the two never disagree; the Node module is now the only implementation.
+const fs = require('node:fs');
+const path = require('node:path');
+const crypto = require('node:crypto');
+const { spawnSync } = require('node:child_process');
+
+const TIMESTAMP = /^\d{4}-\d{2}-\d{2}T\d{2}:\d{2}:\d{2}Z$/;
+const PRD_REF = /^\.prd\/prd-v([1-9][0-9]{0,8})\.md$/;
+const HEX40 = /^[0-9a-f]{40}$/;
+const DEFAULT_TIMEOUT = 600;
+const MAX_TIMEOUT = 2147483; // setTimeout's 32-bit millisecond limit, in seconds
+const LIFECYCLE_FIELDS = ['status', 'started', 'finished', 'verified', 'last_check'];
+const CHECKBOX_LINE = /^([ \t]*(?:[-+*]|[0-9]+[.)])[ \t]+)\[([ xX])\]/;
+
+const sha256 = text => crypto.createHash('sha256').update(text).digest('hex');
+const lines = text => {
+  const all = String(text).split('\n');
+  if (all.length && all[all.length - 1] === '') all.pop();
+  return all;
+};
+
+// CLI shorthand -> canonical ID ("3" -> "T-03"); null when not a ticket id.
+function normalizeId(input) {
+  let n = String(input);
+  if (n.startsWith('T-') || n.startsWith('t-')) n = n.slice(2);
+  if (!/^[0-9]{1,6}$/.test(n) || Number(n) === 0) return null;
+  return `T-${String(Number(n)).padStart(2, '0')}`;
+}
+function canonicalId(s) {
+  if (typeof s !== 'string' || !/^T-[0-9][0-9]+$/.test(s)) return false;
+  const n = s.slice(2);
+  return n.length <= 6 && Number(n) > 0 && `T-${String(Number(n)).padStart(2, '0')}` === s;
+}
+
+// Frontmatter: `---`, unindented unique `key: value` lines (inline `#` comments,
+// blank and comment lines allowed), `---`. Returns the fields and the index of
+// the closing line, or the single structural problem.
+function parseFrontmatter(text, kind = 'ticket') {
+  const rows = lines(text);
+  const fields = {};
+  const order = [];
+  if (rows[0] !== '---') return { problem: 'frontmatter must begin with ---', rows };
+  for (let i = 1; i < rows.length; i++) {
+    const line = rows[i];
+    if (line === '---') return { fields, order, end: i, rows };
+    if (/^[ \t]*(#.*)?$/.test(line)) continue;
+    if (!/^[a-z_][a-z0-9_]*:[ \t]*/.test(line)) {
+      return { problem: kind === 'ticket' ? 'frontmatter requires unindented key: value fields' : 'expected unindented key: value metadata', rows };
+    }
+    const key = line.slice(0, line.indexOf(':'));
+    if (key in fields) return { problem: `duplicate ${kind === 'ticket' ? 'frontmatter' : 'metadata'} key: ${key}`, rows };
+    let value = line.slice(key.length + 1);
+    value = value.replace(/#.*/, '').trim();
+    fields[key] = value;
+    order.push(key);
+  }
+  return { problem: 'frontmatter must close with ---', rows };
+}
+
+// Read one frontmatter field the way the Bash helper did (first match, comment
+// stripped), tolerating files without valid frontmatter.
+function frontmatterField(text, key) {
+  const fm = parseFrontmatter(text);
+  if (fm.problem && fm.problem !== 'frontmatter must close with ---') {
+    if (fm.problem === 'frontmatter must begin with ---') return '';
+  }
+  for (const line of lines(text).slice(1)) {
+    if (line === '---') break;
+    if (line.startsWith(`${key}:`)) return line.slice(key.length + 1).replace(/#.*/, '').trim();
+  }
+  return '';
+}
+
+function verificationCommands(text) {
+  const out = [];
+  let inBlock = false, otherFence = false, inVerify = false;
+  for (const line of lines(text)) {
+    if (inBlock) { if (/^[ \t]*```[ \t]*$/.test(line)) break; out.push(line); continue; }
+    if (otherFence) { if (/^[ \t]*```/.test(line)) otherFence = false; continue; }
+    if (/^## Verification[ \t]*$/.test(line)) { inVerify = true; continue; }
+    if (inVerify && /^[ \t]*```bash[ \t]*$/.test(line)) { inBlock = true; continue; }
+    if (inVerify && /^## /.test(line)) break;
+    if (/^[ \t]*```/.test(line)) otherFence = true;
+  }
+  return out;
+}
+// The block as the legacy helper hashed and executed it: joined lines, one trailing newline.
+const blockText = text => { const c = verificationCommands(text); return c.length ? `${c.join('\n')}\n` : ''; };
+const legacyBlockHash = text => sha256(blockText(text)).slice(0, 12);
+
+function unticked(text) {
+  const out = [];
+  let otherFence = false, inAccept = false;
+  for (const line of lines(text)) {
+    if (otherFence) { if (/^[ \t]*```/.test(line)) otherFence = false; continue; }
+    if (/^[ \t]*```/.test(line)) { otherFence = true; continue; }
+    if (/^## Acceptance Criteria[ \t]*$/.test(line)) { inAccept = true; continue; }
+    if (inAccept && /^## /.test(line)) break;
+    if (inAccept && /^[ \t]*([-+*]|[0-9]+[.)])[ \t]+\[ \]/.test(line)) out.push(line);
+  }
+  return out;
+}
+
+function effectiveTimeout(fields) {
+  return fields.timeout ? Number(fields.timeout) : DEFAULT_TIMEOUT;
+}
+
+// Full ticket validation. Returns { ok, problems, fields, timeout }.
+function validateTicket(file, text) {
+  const problems = [];
+  const fm = parseFrontmatter(text, 'ticket');
+  if (fm.problem) return { ok: false, problems: [fm.problem], fields: {} };
+  const { fields, rows } = fm;
+  let inVerify = false, otherFence = false, section = '';
+  let accept = 0, verify = 0, boxes = 0, fences = 0, runnable = 0;
+  for (let i = fm.end + 1; i < rows.length; i++) {
+    const line = rows[i];
+    if (inVerify) {
+      if (/^[ \t]*```[ \t]*$/.test(line)) { inVerify = false; continue; }
+      if (/^[ \t]*```/.test(line)) { problems.push('Verification requires one closed bash fence'); continue; }
+      if (!/^[ \t]*(#.*)?$/.test(line)) runnable++;
+      continue;
+    }
+    if (otherFence) { if (/^[ \t]*```/.test(line)) otherFence = false; continue; }
+    if (/^## Acceptance Criteria[ \t]*$/.test(line)) { if (accept++) problems.push('duplicate Acceptance Criteria section'); section = 'accept'; continue; }
+    if (/^## Verification[ \t]*$/.test(line)) { if (verify++) problems.push('duplicate Verification section'); section = 'verify'; continue; }
+    if (/^## /.test(line)) { section = ''; continue; }
+    if (section === 'accept') {
+      if (/^[ \t]*(```|~~~)/.test(line)) { problems.push('Acceptance Criteria must contain visible checkboxes, not fences'); continue; }
+      if (/^[ \t]*([-+*]|[0-9]+[.)])[ \t]+/.test(line) || /^[ \t]*([-+*]|[0-9]+[.)])?[ \t]*\[/.test(line)) {
+        if (!/^[ \t]*([-+*]|[0-9]+[.)])[ \t]+\[[ xX]\][ \t]+[^ \t]/.test(line)) {
+          problems.push('malformed acceptance checkbox; use - [ ] text or - [x] text (indented/list marker variants supported)');
+        }
+        boxes++;
+      }
+    }
+    if (/^[ \t]*~~~/.test(line)) { problems.push('use backtick fences; tilde fences are unsupported'); continue; }
+    if (/^[ \t]*```/.test(line)) {
+      if (section === 'verify') {
+        if (!/^[ \t]*```bash[ \t]*$/.test(line) || fences++) problems.push('Verification requires exactly one bash fence');
+        inVerify = true;
+      } else otherFence = true;
+    }
+  }
+  if (!('ticket' in fields) || !canonicalId(fields.ticket)) problems.push('ticket must be a canonical ID between T-01 and T-999999');
+  else {
+    const base = path.basename(file);
+    const prefix = `${fields.ticket}-`;
+    if (!base.startsWith(prefix) || !/.+\.md$/.test(base) || base.length <= prefix.length + 3) problems.push('ticket ID must match filename T-NN-slug.md');
+  }
+  if (!['open', 'in_progress', 'done'].includes(fields.status)) problems.push('status must be open, in_progress, or done');
+  if (!['S', 'M', 'L'].includes(fields.size)) problems.push('size must be S, M, or L');
+  for (const key of ['started', 'finished']) if (key in fields && !TIMESTAMP.test(fields[key])) problems.push(`${key} must be an ISO UTC timestamp`);
+  for (const key of ['verified', 'last_check']) {
+    if (!(key in fields)) continue;
+    const parts = fields[key].split(/[ \t]+/);
+    const expected = key === 'verified' ? 2 : 3;
+    if (parts.length !== expected || !TIMESTAMP.test(parts[0]) || !/^[0-9a-f]{12}$/.test(parts[parts.length - 1])) problems.push(`malformed ${key} timestamp/hash`);
+    else if (key === 'last_check' && !['running', 'passed', 'failed', 'interrupted'].includes(parts[1])) problems.push('invalid last_check outcome');
+  }
+  if ('timeout' in fields && (!/^[1-9][0-9]{0,8}$/.test(fields.timeout) || Number(fields.timeout) > MAX_TIMEOUT)) problems.push(`timeout must be a positive integer number of seconds (at most ${MAX_TIMEOUT})`);
+  const deps = fields.depends_on;
+  if (!('depends_on' in fields) || !/^\[[ \t]*(T-[0-9]+([ \t]*,[ \t]*T-[0-9]+)*)?[ \t]*\]$/.test(deps)) problems.push('depends_on must be an inline list such as [T-01, T-02]');
+  else {
+    const seen = new Set();
+    for (const entry of deps.replace(/^\[[ \t]*/, '').replace(/[ \t]*\]$/, '').split(',')) {
+      const dep = entry.trim();
+      if (dep === '') continue;
+      if (!canonicalId(dep)) problems.push(`depends_on contains noncanonical ticket ID: ${dep}`);
+      if (dep === fields.ticket) problems.push('ticket cannot depend on itself');
+      if (seen.has(dep)) problems.push(`duplicate depends_on ID: ${dep}`);
+      seen.add(dep);
+    }
+  }
+  if (!accept || !boxes) problems.push('Acceptance Criteria requires at least one nonempty checkbox');
+  if (!verify || fences !== 1 || inVerify || !runnable) problems.push('Verification requires exactly one closed runnable bash fence');
+  if (problems.length === 0) {
+    const syntax = spawnSync('bash', ['-n', '-c', blockText(text)], { encoding: 'utf8' });
+    if (syntax.error) problems.push(`cannot run bash to check the Verification block (${syntax.error.message})`);
+    else if (syntax.status !== 0) problems.push('invalid bash syntax in Verification block');
+  }
+  return { ok: problems.length === 0, problems, fields, timeout: effectiveTimeout(fields) };
+}
+
+function dependencies(fields) {
+  return ((fields.depends_on || '').match(/T-[0-9]+/g) || []);
+}
+
+// PRDs and evaluation notes use the same deliberately small metadata format.
+function validateMetadata(text) {
+  const fm = parseFrontmatter(text, 'metadata');
+  return fm.problem ? { ok: false, problems: [fm.problem], fields: {} } : { ok: true, problems: [], fields: fm.fields };
+}
+
+function validatePrd(root, ref) {
+  const match = typeof ref === 'string' ? ref.match(PRD_REF) : null;
+  if (!match) return { ok: false, problems: [`invalid PRD reference ${ref}; use .prd/prd-vN.md`], prefix: 'pincer' };
+  const file = path.join(root, ref);
+  if (!fs.existsSync(file)) return { ok: false, problems: [`PRD does not exist: ${ref}`], prefix: 'pincer' };
+  const text = fs.readFileSync(file, 'utf8');
+  const meta = validateMetadata(text);
+  if (!meta.ok) return { ok: false, problems: meta.problems, file: ref };
+  const problems = [];
+  const { fields } = meta;
+  if (fields.version !== match[1]) problems.push(`version must match filename (${match[1]})`);
+  if (!['draft', 'ticketed', 'built'].includes(fields.status)) problems.push('PRD status must be draft, ticketed, or built');
+  if (!['', 'small', 'standard', undefined].includes(fields.profile)) problems.push('profile must be small or standard (omit for standard)');
+  return { ok: problems.length === 0, problems, file: ref, fields, text, profile: fields.profile || 'standard' };
+}
+
+// Normalizations (contract "Content revisions"): lifecycle fields and checkbox
+// marks are the only exceptions; everything else contributes to identity.
+function normalizeTicket(text) {
+  const rows = lines(text);
+  const out = [];
+  let closed = rows[0] !== '---';
+  let otherFence = false, inAccept = false;
+  for (let i = 0; i < rows.length; i++) {
+    const line = rows[i];
+    if (!closed) {
+      if (i > 0 && line === '---') closed = true;
+      else if (i > 0) {
+        const key = (line.match(/^([a-z_][a-z0-9_]*):/) || [])[1];
+        if (key && LIFECYCLE_FIELDS.includes(key)) continue;
+      }
+      out.push(line);
+      continue;
+    }
+    if (otherFence) { if (/^[ \t]*```/.test(line)) otherFence = false; out.push(line); continue; }
+    if (/^[ \t]*```/.test(line)) { otherFence = true; out.push(line); continue; }
+    if (/^## Acceptance Criteria[ \t]*$/.test(line)) inAccept = true;
+    else if (/^## /.test(line)) inAccept = false;
+    out.push(inAccept ? line.replace(CHECKBOX_LINE, '$1[ ]') : line);
+  }
+  return `${out.join('\n')}\n`;
+}
+function normalizePrd(text) {
+  const rows = lines(text);
+  const out = [];
+  let closed = rows[0] !== '---';
+  for (let i = 0; i < rows.length; i++) {
+    const line = rows[i];
+    if (!closed) {
+      if (i > 0 && line === '---') closed = true;
+      else if (i > 0 && /^status:/.test(line)) continue;
+    }
+    out.push(line);
+  }
+  return `${out.join('\n')}\n`;
+}
+const ticketDigest = text => sha256(normalizeTicket(text));
+const prdDigest = text => sha256(normalizePrd(text));
+const checkDigest = (text, timeoutSeconds = DEFAULT_TIMEOUT) => sha256(`${blockText(text)}timeout=${timeoutSeconds}\n`);
+
+// tickets/T-NN-*.md resolution and set validation.
+function ticketFiles(root) {
+  const dir = path.join(root, 'tickets');
+  if (!fs.existsSync(dir)) return [];
+  return fs.readdirSync(dir).filter(name => /^T-[0-9]+.*\.md$/.test(name)).sort().map(name => `tickets/${name}`);
+}
+function ticketFile(root, input) {
+  const id = normalizeId(input);
+  if (!id) return { problem: `not a ticket id (expected 1..999999): ${input}` };
+  const matches = ticketFiles(root).filter(f => path.basename(f).startsWith(`${id}-`));
+  if (matches.length > 1) return { problem: `several files match tickets/${id}-*.md` };
+  if (matches.length === 0) return { problem: `no ticket file tickets/${id}-*.md` };
+  return { id, file: matches[0] };
+}
+function validateTicketSet(root) {
+  const files = ticketFiles(root);
+  const ids = new Set();
+  for (const file of files) {
+    const id = frontmatterField(fs.readFileSync(path.join(root, file), 'utf8'), 'ticket');
+    if (id) {
+      if (ids.has(id)) return { ok: false, problems: [`duplicate ticket ID: ${id}`] };
+      ids.add(id);
+    }
+  }
+  for (const file of files) {
+    const result = validateTicket(file, fs.readFileSync(path.join(root, file), 'utf8'));
+    if (!result.ok) return { ok: false, file, problems: result.problems };
+  }
+  return { ok: true, files };
+}
+
+module.exports = {
+  TIMESTAMP, PRD_REF, HEX40, DEFAULT_TIMEOUT, MAX_TIMEOUT, LIFECYCLE_FIELDS,
+  sha256, lines, normalizeId, canonicalId, parseFrontmatter, frontmatterField,
+  verificationCommands, blockText, legacyBlockHash, unticked, effectiveTimeout,
+  validateTicket, dependencies, validateMetadata, validatePrd,
+  normalizeTicket, normalizePrd, ticketDigest, prdDigest, checkDigest,
+  ticketFiles, ticketFile, validateTicketSet,
+};

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

@@ -0,0 +1,89 @@
+'use strict';
+// PINCER runtime — the one readiness computation (docs/runtime-contracts.md,
+// "Readiness and reason codes"). Pure functions over parsed inputs: the human
+// status, the JSON status, `ready`, `done`, `start` and release all consume
+// these so they cannot disagree. Nothing here reads the clock, executes a
+// command or writes a file.
+const parse = require('./parse.cjs');
+const { validateAttempt } = require('./state.cjs');
+
+const reason = (code, detail, next) => ({ code, detail, next });
+
+// Legacy mode: the v0.4.1 rules over the ticket's own receipts. Returns
+// { ready, reasons, legacyMessage } where legacyMessage is the exact wording
+// the Bash helper printed for a done ticket that needs attention.
+function legacyTicketReadiness(text, fields) {
+  const receipt = fields.verified || '';
+  const attempt = fields.last_check || '';
+  const hash = parse.legacyBlockHash(text);
+  const fail = (message, code, detail = message) => ({ ready: false, legacyMessage: message, reasons: [reason(code, detail, 're-run verify')] });
+  if (!attempt) return fail('missing latest verification outcome — re-run verify', 'EVIDENCE_MISSING', 'no recorded verification attempt');
+  const parts = attempt.split(/[ \t]+/);
+  if (!(parts.length === 3 && parse.TIMESTAMP.test(parts[0]) && parts[1] === 'passed' && /^[a-f0-9]{12}$/.test(parts[2])) || parts[2] !== hash) {
+    const outcomeCode = parts[1] === 'running' ? 'ATTEMPT_RUNNING' : parts[1] === 'interrupted' ? 'ATTEMPT_INTERRUPTED' : parts[1] === 'failed' ? 'CHECK_FAILED' : 'CHECK_CHANGED';
+    const code = parts[1] === 'passed' && parts[2] !== hash ? 'CHECK_CHANGED' : outcomeCode;
+    return fail(`latest verification: ${attempt} — re-run verify`, code, code === 'CHECK_CHANGED' ? 'the Verification block changed after the latest pass' : `latest verification: ${attempt}`);
+  }
+  if (!receipt) return fail('done without a verification receipt — re-run verify', 'EVIDENCE_MISSING', 'done without a verification receipt');
+  const rparts = receipt.split(/[ \t]+/);
+  if (!(rparts.length === 2 && parse.TIMESTAMP.test(rparts[0]) && /^[a-f0-9]{12}$/.test(rparts[1])) || rparts[1] !== hash) {
+    return fail('stale or malformed verification receipt — re-run verify', 'CHECK_CHANGED', 'stale or malformed verification receipt');
+  }
+  if (parse.unticked(text).length) return fail('unticked acceptance criteria — complete and re-run verify', 'CRITERIA_UNTICKED', 'unticked acceptance criteria');
+  return { ready: true, reasons: [] };
+}
+
+// Migrated mode: readiness derives from the latest attempt for the ticket's
+// context and the current inputs. `current` carries the digests computed now;
+// `sourceProblems` are snapshot problems (secret path, unsupported input);
+// `contextKey` is the key the attempt was read for and `pointedId` the id the
+// index names for it (the record must match both); the attempt's artifacts
+// carry `missing`/`altered` from state.inspectArtifacts.
+function migratedTicketReadiness({ text, fields, timeout, attempt, legacyReceipt, current, sourceProblems = [], changedPaths = [], contextKey = null, pointedId = null }) {
+  const reasons = [];
+  for (const p of sourceProblems) reasons.push(reason(p.code, p.detail, p.code === 'SECRET_PATH' ? 'remove or ignore the secret file' : 'remove the input or change the configuration'));
+  if (reasons.length) return { ready: false, reasons };
+  if (!attempt) {
+    if (legacyReceipt) return { ready: false, reasons: [reason('LEGACY_RECEIPT', `migrated legacy receipt (${legacyReceipt.verified || legacyReceipt.last_check || 'present'}) is history, not runtime evidence`, 'verify')] };
+    return { ready: false, reasons: [reason('EVIDENCE_MISSING', 'no runtime attempt recorded', 'verify')] };
+  }
+  const id = typeof attempt.id === 'string' && attempt.id ? attempt.id : '?';
+  // The record must be complete and written for this context before any
+  // outcome is honored: a stripped or foreign record is never a pass.
+  const invalid = validateAttempt(attempt, contextKey, pointedId);
+  if (invalid) return { ready: false, reasons: [reason('ATTEMPT_ERROR', `attempt ${id} ${invalid}`, 'verify')] };
+  switch (attempt.outcome) {
+    case 'running': return { ready: false, reasons: [reason('ATTEMPT_RUNNING', `attempt ${id} is running`, 'wait, or run recover if its owner died')] };
+    case 'interrupted': return { ready: false, reasons: [reason('ATTEMPT_INTERRUPTED', `attempt ${id} was interrupted`, 'verify')] };
+    case 'timed_out': return { ready: false, reasons: [reason('ATTEMPT_TIMED_OUT', `attempt ${id} timed out after ${attempt.check && attempt.check.timeout_seconds} s`, 'fix or raise timeout, then verify')] };
+    case 'error': return { ready: false, reasons: [reason('ATTEMPT_ERROR', `attempt ${id}: ${attempt.error || 'could not be recorded'}`, 'inspect the record, then verify')] };
+    case 'failed': return { ready: false, reasons: [reason('CHECK_FAILED', `attempt ${id} failed (exit ${attempt.exit_code ?? attempt.signal ?? '?'})`, 'fix, then verify')] };
+    case 'passed': break;
+    default: return { ready: false, reasons: [reason('ATTEMPT_ERROR', `attempt ${id} has unknown outcome ${JSON.stringify(attempt.outcome)}`, 'verify')] };
+  }
+  if (current.prdRevision && attempt.context && attempt.context.prd_revision !== current.prdRevision) {
+    reasons.push(reason('REVISION_CHANGED', 'the PRD revision changed since the passing attempt', 'register --rebind, then verify'));
+  }
+  if (attempt.check && attempt.check.digest !== parse.checkDigest(text, timeout)) {
+    reasons.push(reason('CHECK_CHANGED', 'the Verification block or timeout changed since the passing attempt', 'verify'));
+  }
+  if (attempt.context && attempt.context.ticket_digest !== parse.ticketDigest(text)) {
+    reasons.push(reason('SOURCE_CHANGED', 'the ticket\'s authored content changed since the passing attempt', 'verify'));
+  }
+  if (current.sourceDigest && attempt.source && attempt.source.after !== current.sourceDigest) {
+    const shown = changedPaths.slice(0, 5).join(', ') + (changedPaths.length > 5 ? `, … (${changedPaths.length} paths)` : '');
+    reasons.push(reason('SOURCE_CHANGED', `source changed since the passing attempt${shown ? `: ${shown}` : ''}`, 'verify'));
+  }
+  const streams = ['stdout', 'stderr'];
+  if (streams.some(k => attempt.artifacts[k].missing)) {
+    reasons.push(reason('EVIDENCE_MISSING', 'the attempt\'s captured log is missing from local state', 'verify'));
+  }
+  const altered = streams.filter(k => attempt.artifacts[k].altered);
+  if (altered.length) {
+    reasons.push(reason('EVIDENCE_MISSING', `the attempt's captured ${altered.join(' and ')} log was altered after the run and no longer matches the recorded digest`, 'verify'));
+  }
+  if (parse.unticked(text).length) reasons.push(reason('CRITERIA_UNTICKED', 'unticked acceptance criteria', 'tick verified criteria'));
+  return { ready: reasons.length === 0, reasons };
+}
+
+module.exports = { reason, legacyTicketReadiness, migratedTicketReadiness };

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

@@ -0,0 +1,224 @@
+'use strict';
+// PINCER runtime — the attempt runner (docs/runtime-contracts.md, "Attempts",
+// "Capture and sanitization"). Persists a `running` record before launch (which
+// supersedes prior readiness for the context immediately), snapshots inputs
+// before and after, executes the check through `bash -eo pipefail` in its own
+// process group with bounded sanitized capture, enforces the timeout with
+// escalation, handles signals, and finalizes the record from what actually
+// happened. Nothing here decides readiness; readiness.cjs reads the records.
+const fs = require('node:fs');
+const os = require('node:os');
+const path = require('node:path');
+const { spawn, execFileSync } = require('node:child_process');
+const parse = require('./parse.cjs');
+const source = require('./source.cjs');
+const state = require('./state.cjs');
+const { sanitizeLine, sanitizeText } = require('./sanitize.cjs');
+const { nowIso } = require('./fsutil.cjs');
+
+const CAPTURE_LIMIT = 1024 * 1024;
+const PARTIAL_LINE_LIMIT = 64 * 1024;
+const GRACE_MS = 5000;
+const DRAIN_MS = 2000;
+const RUNNER_ARGS = ['-eo', 'pipefail', '-c'];
+
+let bashInfo = null;
+function runnerInfo() {
+  if (bashInfo) return bashInfo;
+  let shell = 'bash', version = 'unknown';
+  try { shell = execFileSync('bash', ['-c', 'command -v bash'], { encoding: 'utf8' }).trim() || 'bash'; } catch { /* keep default */ }
+  try { version = execFileSync('bash', ['--version'], { encoding: 'utf8' }).split('\n')[0]; } catch { /* keep default */ }
+  bashInfo = { shell, args: RUNNER_ARGS, version };
+  return bashInfo;
+}
+
+// A bounded, sanitized capture of one stream into a file, echoed to `echo` when given.
+class Capture {
+  constructor(file, echo) {
+    this.file = file; this.echo = echo;
+    this.fd = fs.openSync(file, 'w');
+    this.bytes = 0; this.dropped = 0; this.redactions = 0; this.truncated = false;
+    this.partial = ''; this.state = {}; this.failed = null;
+  }
+  write(chunk) {
+    this.partial += chunk.toString('utf8');
+    let index;
+    while ((index = this.partial.indexOf('\n')) !== -1) {
+      this.emit(this.partial.slice(0, index), true);
+      this.partial = this.partial.slice(index + 1);
+    }
+    if (this.partial.length > PARTIAL_LINE_LIMIT) { this.emit(this.partial, false); this.partial = ''; }
+  }
+  emit(line, newline) {
+    const { text, redactions } = sanitizeLine(line, this.state);
+    this.redactions += redactions;
+    const out = newline ? `${text}\n` : text;
+    if (this.echo) this.echo.write(out);
+    const buffer = Buffer.from(out, 'utf8');
+    if (this.bytes + buffer.length <= CAPTURE_LIMIT) {
+      try { fs.writeSync(this.fd, buffer); this.bytes += buffer.length; } catch (error) { this.failed = this.failed || error.message; }
+    } else {
+      if (!this.truncated) {
+        const room = CAPTURE_LIMIT - this.bytes;
+        if (room > 0) { try { fs.writeSync(this.fd, buffer.subarray(0, room)); this.bytes += room; } catch (error) { this.failed = this.failed || error.message; } }
+        this.truncated = true;
+        this.dropped += buffer.length - Math.max(room, 0);
+      } else this.dropped += buffer.length;
+    }
+  }
+  close() {
+    if (this.partial) { this.emit(this.partial, false); this.partial = ''; }
+    if (this.truncated) {
+      try { fs.writeSync(this.fd, `\n[pincer: truncated, ${this.dropped} more bytes not stored]\n`); } catch (error) { this.failed = this.failed || error.message; }
+    }
+    fs.closeSync(this.fd);
+    return { bytes: this.bytes, truncated: this.truncated, redactions: this.redactions, failed: this.failed };
+  }
+}
+
+// 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 = {} }) {
+  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, () => {
+      const read = state.readIndex(root);
+      if (read.error) { const e = new Error(read.error); e.code = 'INVALID'; throw e; }
+      const index = read.index;
+      const sequence = index.sequence + 1;
+      const id = state.attemptId(sequence);
+      source.storeManifest(root, before);
+      relLogDir = `${state.RUNTIME_DIR}/attempts/${id}`;
+      logDir = path.join(root, relLogDir);
+      fs.mkdirSync(logDir, { recursive: true });
+      attempt = {
+        schema: 1, runtime: 1, id, sequence, context,
+        check: { digest: checkDigest, display, timeout_seconds: timeoutSeconds },
+        outcome: 'running', exit_code: null, signal: null,
+        runner: runnerInfo(), 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 },
+        artifacts: { stdout: { path: `${relLogDir}/stdout.log`, sha256: null, bytes: 0, truncated: false, redactions: 0 }, stderr: { path: `${relLogDir}/stderr.log`, sha256: null, bytes: 0, truncated: false, redactions: 0 } },
+        owner: { pid: process.pid, ppid: process.ppid, host: os.hostname() }, child: null,
+        limitations: [],
+      };
+      state.writeAttempt(root, attempt);
+      index.sequence = sequence;
+      index.current[key] = id;
+      index.running.push(id);
+      state.writeIndex(root, index);
+    }, { command });
+  } catch (error) {
+    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}` };
+  }
+
+  // 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);
+  const stderr = new Capture(path.join(logDir, 'stderr.log'), echo ? process.stderr : null);
+  let timedOut = false, interruptedBy = null, abandoned = false, killTimer = null, graceTimer = null, drainTimer = null, settle = null;
+  const sent = [];
+  // Signal the whole group, whether or not the shell itself has exited: a
+  // background child that inherited the output pipes keeps the run alive and
+  // must be terminated the same way. The bare pid is a fallback only while the
+  // shell is known to be alive (after it is reaped the pid may be reused). The
+  // group id itself can be reused only once every member is gone; the window
+  // between the two attempts is a documented limit, not something detected here.
+  // `sent` records only signals a kill call delivered.
+  const signalGroup = signal => {
+    try { process.kill(-child.pid, signal); sent.push(signal); return; } catch { /* no group left */ }
+    if (child.exitCode === null && child.signalCode === null) { try { process.kill(child.pid, signal); sent.push(signal); } catch { /* gone */ } }
+  };
+  let terminating = false;
+  const terminate = () => {
+    if (!child || !child.pid || terminating) return;
+    terminating = true;
+    signalGroup('SIGTERM');
+    graceTimer = setTimeout(() => {
+      signalGroup('SIGKILL');
+      // Bound the wait for the pipes to close: a descendant that survives
+      // SIGKILL (or was never reachable) must not hold the run open forever.
+      drainTimer = setTimeout(() => {
+        abandoned = true;
+        try { child.stdout.destroy(); child.stderr.destroy(); child.unref(); } catch { /* best effort */ }
+        settle({ code: child.exitCode, signal: child.signalCode });
+      }, DRAIN_MS);
+    }, GRACE_MS);
+  };
+  const onSignal = signal => { interruptedBy = signal; terminate(); };
+  const exit = await new Promise(resolve => {
+    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 });
+    } catch (error) { launchError = error.message; return settle({ code: null, signal: null }); }
+    child.on('error', error => { launchError = error.message; });
+    if (child.pid) {
+      attempt.child = { pid: child.pid };
+      try { state.withLock(root, () => state.writeAttempt(root, attempt), { command }); } catch { /* the final write records it */ }
+    }
+    child.stdout.on('data', chunk => stdout.write(chunk));
+    child.stderr.on('data', chunk => stderr.write(chunk));
+    process.on('SIGINT', onSignal); process.on('SIGTERM', onSignal);
+    killTimer = setTimeout(() => { timedOut = true; terminate(); }, timeoutSeconds * 1000);
+    child.on('close', (code, signal) => settle({ code, signal }));
+  });
+  clearTimeout(killTimer); clearTimeout(graceTimer); clearTimeout(drainTimer);
+  process.off('SIGINT', onSignal); process.off('SIGTERM', onSignal);
+  const outInfo = stdout.close(), errInfo = stderr.close();
+  const termination = `${sent.length ? `the child process group was sent ${sent.join(' then ')}` : 'no reachable process remained in the child\'s group (the shell had exited and its descendants left the group)'}${abandoned ? `; output capture was abandoned ${DRAIN_MS / 1000} s after the SIGKILL point and a descendant may still be running` : ''}`;
+
+  const after = source.snapshot(root);
+  const changed = after.digest && before.digest !== after.digest ? source.diffManifests(before, after) : [];
+  attempt.finished = nowIso();
+  attempt.exit_code = exit.code;
+  attempt.signal = exit.signal;
+  attempt.source.after = after.digest;
+  for (const [name, info] of [['stdout', outInfo], ['stderr', errInfo]]) {
+    const file = path.join(logDir, `${name}.log`);
+    let sha = null;
+    try { sha = parse.sha256(fs.readFileSync(file)); } catch { sha = null; }
+    attempt.artifacts[name] = { ...attempt.artifacts[name], sha256: sha, bytes: info.bytes, truncated: info.truncated, redactions: info.redactions };
+  }
+  const captureFailure = outInfo.failed || errInfo.failed;
+  if (launchError) { attempt.outcome = 'error'; attempt.error = `cannot launch the check: ${launchError}`; }
+  else if (interruptedBy) { attempt.outcome = 'interrupted'; attempt.limitations.push(`interrupted by ${interruptedBy}; ${termination}`); }
+  else if (timedOut) { attempt.outcome = 'timed_out'; attempt.limitations.push(`terminated after ${timeoutSeconds} s; ${termination}`); }
+  else if (captureFailure) { attempt.outcome = 'error'; attempt.error = `capture failed: ${captureFailure}`; }
+  else if (after.problems.length) { attempt.outcome = 'error'; attempt.error = `source view invalid after the run: ${after.problems[0].code} ${after.problems[0].detail}`; }
+  else if (exit.code === 0 && changed.length) { attempt.outcome = 'error'; attempt.error = `SOURCE_CHANGED: the check mutated source: ${changed.slice(0, 5).join(', ')}${changed.length > 5 ? ` (+${changed.length - 5})` : ''}`; }
+  else if (exit.code === 0) attempt.outcome = 'passed';
+  else attempt.outcome = 'failed';
+  if (changed.length && attempt.outcome !== 'error') attempt.limitations.push(`source changed during the run: ${changed.slice(0, 5).join(', ')}`);
+  if (after.digest) { try { source.storeManifest(root, after); } catch { /* best effort; the digest is recorded */ } }
+
+  try {
+    state.withLock(root, () => {
+      const read = state.readIndex(root);
+      if (read.error) { const e = new Error(read.error); e.code = 'INVALID'; throw e; }
+      const index = read.index;
+      state.writeAttempt(root, attempt);
+      index.running = index.running.filter(id => id !== attempt.id);
+      state.writeIndex(root, index);
+    }, { command });
+  } catch (error) {
+    return { code: 'ATTEMPT_ERROR', problem: `attempt ${attempt.id} finished ${attempt.outcome} but the record could not be finalized: ${error.message}`, attempt };
+  }
+  return { attempt, changed };
+}
+
+const exitFor = attempt => ({ passed: 0, failed: 1, timed_out: 124, interrupted: 130, error: 4 })[attempt.outcome] ?? 4;
+
+module.exports = { runAttempt, exitFor, CAPTURE_LIMIT, GRACE_MS, DRAIN_MS, runnerInfo };