pincer-workflow 0.4.1 → 0.6.0

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

@@ -0,0 +1,205 @@
+'use strict';
+// PINCER runtime — the resume report (docs/runtime-contracts.md, "Resume
+// report"). Read-only inspection of the selected (or named) change for a fresh
+// session: identity, lifecycle, repository view, agreement and authorization,
+// decisions, references to the authored artifacts, tickets and attempts, the
+// candidate, the authored handoff (labeled, never an input), the blockers in
+// gate order and one next action chosen by the documented precedence. Distinct
+// from `change resume`, the lifecycle operation. Launches nothing, writes nothing.
+const fs = require('node:fs');
+const path = require('node:path');
+const parse = require('./parse.cjs');
+const changes = require('./changes.cjs');
+const agreement = require('./agreement.cjs');
+const status = require('./status.cjs');
+const state = require('./state.cjs');
+const transaction = require('./transaction.cjs');
+const gates = require('./gates.cjs');
+
+// Resume JSON schema 2 (PRD v6): schema 1 plus the strict coverage summary; the
+// coverage codes join rule 4 of the next-action precedence.
+const SCHEMA = 2;
+const STATE_CODES = ['INPUT_INVALID', 'MALFORMED', 'UNSUPPORTED_SCHEMA', 'HISTORY_INVALID', 'STATE_INCOMPLETE'];
+const COVERAGE_CODES = ['INVENTORY_INVALID', 'COVERAGE_INVALID', 'COVERAGE_INCOMPLETE', 'OBLIGATION_MISSING', 'SCOPE_UNAUTHORIZED'];
+const CANDIDATE_COVERAGE_CODES = ['REVIEW_MISSING', 'ADEQUACY_REQUIRED'];
+const phases = require('./phases.cjs');
+const routing = require('./routing.cjs');
+const SELECTION_CODES = ['SELECTION_REQUIRED', 'SELECTION_INVALID'];
+const AGREEMENT_CODES = ['DECISION_REQUIRED', 'AUTHORIZATION_REQUIRED', 'AGREEMENT_CHANGED'];
+const RUNTIME = 'node scripts/pincer-runtime.cjs';
+
+const 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;
+};
+const title = text => { const m = parse.lines(text).find(l => /^# /.test(l)); return m ? m.replace(/^# /, '').trim() : null; };
+
+// build(root, { change }) → { json, blockers, next, gathered } — the whole report.
+function build(root, { change = null } = {}) {
+  const st = status.render(root, { change });
+  const j = st.json;
+  const generated = j.generated;
+  const report = { schema: SCHEMA, runtime: changes.RUNTIME_STRICT, generated, root, mode: j.mode, selection: null, change: null, agreement: null, references: null, tickets: [], attempts: [], candidate: null, coverage: j.coverage || { strict: false, label: 'unverified', reason: null, structure: null, implementation: null, candidate: null, next: null }, handoff: null, blockers: [], next: null };
+  const blockers = [];
+  const push = (code, detail) => { if (!blockers.some(b => b.code === code && b.detail === detail)) blockers.push({ code, detail }); };
+  if (j.mode !== 'changes') {
+    report.selection = { change: null, problem: { code: j.mode === 'invalid' ? 'INPUT_INVALID' : 'CHANGE_REQUIRED', detail: j.mode === 'legacy' ? 'this project keeps no change records; register with: node scripts/pincer-runtime.cjs register --prd .prd/prd-vN.md' : j.mode === 'migrated' ? 'this project keeps a v0.5.0 binding; migrate it with: node scripts/pincer-runtime.cjs migrate --preview --prd <prd>' : (j.reasons[0] ? j.reasons[0].detail : 'unreadable change records') } };
+    push(report.selection.problem.code, report.selection.problem.detail);
+    report.blockers = blockers;
+    report.next = { action: 'repair or migrate', command: report.selection.problem.detail.replace(/^.*?: /, ''), ticket: null, check: null, rule: 1 };
+    return { json: report, text: render(report), exit: st.exit };
+  }
+  report.selection = j.selection;
+  // Rule 1: invalid or missing state, or no usable selection.
+  for (const r of j.reasons) if (STATE_CODES.includes(r.code)) push(r.code, r.detail);
+  if (!j.change) {
+    const problem = j.selection.problem || (j.reasons[0] ? j.reasons[0] : { code: 'SELECTION_REQUIRED', detail: 'no change selected' });
+    push(problem.code, problem.detail);
+    report.blockers = blockers;
+    const first = blockers[0];
+    report.next = STATE_CODES.includes(first.code)
+      ? { action: first.code === 'STATE_INCOMPLETE' ? 'complete the interrupted transaction' : 'repair the change records by hand', command: first.code === 'STATE_INCOMPLETE' ? `${RUNTIME} recover` : `${RUNTIME} change list`, ticket: null, check: null, rule: 1 }
+      : { action: 'select the change to work on', command: `${RUNTIME} change select <id>`, ticket: null, check: null, rule: 1 };
+    return { json: report, text: render(report), exit: st.exit };
+  }
+  const id = j.change.id;
+  const resolved = changes.resolveSelected(root, { change: id });
+  const record = resolved.record;
+  report.change = { id, prd: j.change.prd, prd_revision: j.change.prd_revision, base: j.change.base, registered: record ? record.registered : null, sequence: j.change.sequence, lifecycle: j.change.lifecycle, view: j.change.view };
+  const ag = j.change.agreement;
+  report.agreement = {
+    current: ag.current,
+    authorized: ag.authorized ? { ...ag.authorized, reference: (record.authorizations.find(a => a.id === ag.authorized.id) || {}).reference || null, excerpt: (record.authorizations.find(a => a.id === ag.authorized.id) || {}).excerpt || null, constraints: (record.authorizations.find(a => a.id === ag.authorized.id) || {}).constraints || null } : null,
+    verdict: ag.verdict, difference: ag.difference,
+    decisions: { open: record.decisions.filter(d => d.status === 'open').map(d => ({ id: d.id, summary: d.summary, raised: d.raised })), resolved: record.decisions.filter(d => d.status === 'resolved').map(d => ({ id: d.id, summary: d.summary, reference: d.reference, resolved: d.resolved })) },
+  };
+  // References: the authored artifacts the agreement is read from (titles and first lines only).
+  let prdText = null;
+  try { prdText = fs.readFileSync(path.join(root, record.prd), 'utf8'); } catch { prdText = null; }
+  const authorizedEntry = ag.authorized ? record.agreements.find(g => g.id === ag.authorized.agreement) : null;
+  report.references = {
+    prd: { path: record.prd, title: prdText ? title(prdText) : null },
+    snapshot: authorizedEntry ? authorizedEntry.snapshot : null,
+    tickets: (st.gathered && st.gathered.tickets ? st.gathered.tickets : []).map(t => ({ id: t.fields.ticket, file: t.file, objective: firstLine(t.text, '## Objective') })),
+  };
+  report.tickets = j.tickets;
+  const idx = state.exists(root) ? state.readIndex(root) : { index: null };
+  if (idx.index) {
+    for (const t of j.tickets) {
+      const key = state.contextKey({ kind: 'ticket', change: id, ticket: t.id });
+      for (const a of state.listAttempts(root, key)) report.attempts.push({ ticket: t.id, check: null, id: a.id, outcome: a.outcome, started: a.started, finished: a.finished, current: idx.index.current[key] === a.id });
+    }
+    if (j.candidate && j.candidate.evaluation) {
+      for (const a of state.listAttempts(root)) {
+        if (a.context && a.context.kind === 'candidate' && a.context.change === id && a.context.candidate === j.candidate.evaluation.candidate) {
+          const key = state.contextKey({ ...a.context, mode: 'changes' });
+          report.attempts.push({ ticket: null, check: a.context.check, id: a.id, outcome: a.outcome, started: a.started, finished: a.finished, current: idx.index.current[key] === a.id });
+        }
+      }
+    }
+  }
+  report.candidate = j.candidate;
+  const lc = record.lifecycle;
+  report.handoff = lc.reason || lc.note ? { kind: record.events.filter(e => ['pause', 'reopen'].includes(e.kind)).at(-1)?.kind || null, reason: lc.reason, note: lc.note, since: lc.since, authored: true } : null;
+  // Blockers in gate order, then the readiness and candidate reasons.
+  const running = transaction.runningAttempts(root, id);
+  const viewProblems = j.reasons.filter(r => r.code === 'BASE_MISMATCH');
+  for (const r of viewProblems) push(r.code, r.detail);
+  if (running.length) push('ATTEMPT_RUNNING', `attempt ${running[0].id} of change ${id} is running${running[0].alive === false ? ' (its owner is no longer running)' : ''}`);
+  if (changes.TERMINAL.includes(lc.state)) push('LIFECYCLE_BLOCKED', `change ${id} is ${lc.state}${lc.superseded_by ? ` by ${lc.superseded_by}` : ''}; it cannot execute`);
+  if (ag.verdict && ag.verdict !== 'current') push(ag.verdict, ag.verdict_detail || ag.verdict);
+  // Rule 4 also covers the structural coverage gaps of a strict change.
+  const selected = !resolved.selection || resolved.selection.change === id;
+  const cov = changes.isStrict(record) ? phases.report(root, record, { gathered: st.gathered, generated, selected }) : null;
+  if (cov) for (const p of cov.structure.problems) push(p.code, p.detail);
+  for (const t of j.tickets) for (const r of t.readiness.reasons) if (t.status === 'done' || t.status === 'in_progress') push(r.code, `${t.id}: ${r.detail}`);
+  // A missing or stale evaluation blocks only a completed change: before completion no candidate is expected.
+  if (j.candidate && lc.state === 'completed') for (const r of j.candidate.reasons) push(r.code, r.detail);
+  if (cov && lc.state === 'completed') for (const p of cov.candidate.problems) if (p.code !== 'EVIDENCE_MISSING' || !cov.candidate.evaluated) push(p.code, p.detail);
+  report.blockers = blockers;
+  report.next = routing.qualify(decide({ id, lc, ag, j, running, viewProblems, gathered: st.gathered, record, cov, selected }), { id, selected });
+  return { json: report, text: render(report), exit: st.exit };
+}
+
+// The documented next-action precedence (rules 1..8); rule 1 is handled by the caller.
+function decide({ id, lc, ag, j, running, viewProblems, gathered, record, cov = null, selected = true }) {
+  const cmd = (action, command, extra = {}) => ({ action, command, ticket: null, check: null, ...extra });
+  const change = sub => `${RUNTIME} change ${sub} ${id}`;
+  // Rules 2 and 3 are shared with the coverage report (routing.cjs) so the two
+  // cannot drift apart again.
+  const ahead = routing.preface({ id, lifecycle: lc, base: record.base, running, viewProblems });
+  if (ahead) return ahead;
+  const gap = ag.verdict && ag.verdict !== 'current';
+  if (gap) {
+    if (ag.verdict === 'DECISION_REQUIRED') return cmd('record the user\'s decision', `${change('decide')} --resolve ${ag.open_decisions[0]} --reference <text> --excerpt <text>`, { rule: 4 });
+    if (ag.verdict === 'AUTHORIZATION_REQUIRED') return cmd('record the user\'s authorization', `${change('authorize')} --agreement ${ag.current} --reference <text> --excerpt <text>`, { rule: 4 });
+    if (ag.verdict === 'AGREEMENT_CHANGED') return cmd('record the disposition of the changed agreement', `${change('authorize')} --agreement ${ag.current} --reference <text> --excerpt <text> (user) or --delegated --basis ${ag.authorized ? ag.authorized.id : (record.authorizations.at(-1) || {}).id || 'A-NN'} --explanation <text>`, { rule: 4 });
+    return cmd('repair the agreement inputs', `${ag.verdict}: ${ag.verdict_detail}`, { rule: 4 });
+  }
+  // Rule 4 (strict coverage): a structural coverage gap precedes any verification work.
+  if (cov && cov.structure.problems.length) return { ...cov.next, rule: 4 };
+  const staged = routing.lifecycleAction({ id, lifecycle: lc });
+  if (staged) return staged;
+  const tickets = j.tickets;
+  const inProgress = tickets.find(t => t.status === 'in_progress');
+  // A fresh clone without local attempt history relies on the saved candidate record (as `ready` does): a done
+  // ticket whose only reason is EVIDENCE_MISSING is that stated limit, not stale work.
+  const localUnavailable = Boolean(j.candidate && j.candidate.local_attempts === 'unavailable');
+  const stale = tickets.find(t => t.status === 'done' && !t.readiness.ready && !(localUnavailable && t.readiness.reasons.every(r => r.code === 'EVIDENCE_MISSING')));
+  const open = tickets.filter(t => t.status === 'open');
+  const blocked = t => t.readiness.reasons.some(x => x.code === 'DEPENDENCY_BLOCKED');
+  const nextOpen = open.find(t => !blocked(t)) || null;
+  if (lc.state === 'active') {
+    if (inProgress) return cmd(`finish ${inProgress.id}`, `scripts/pincer-ticket.sh verify ${inProgress.id} → done ${inProgress.id}`, { ticket: inProgress.id, rule: 5 });
+    if (stale) return cmd(`re-verify ${stale.id} (${stale.readiness.reasons[0].code})`, `scripts/pincer-ticket.sh verify ${stale.id}`, { ticket: stale.id, rule: 5 });
+    if (nextOpen) return cmd(`start ${nextOpen.id}`, `scripts/pincer-ticket.sh start ${nextOpen.id}`, { ticket: nextOpen.id, rule: 5 });
+    if (open.length) return cmd('unblock the remaining tickets', `${open.map(t => `${t.id}: ${t.readiness.reasons[0] ? t.readiness.reasons[0].detail : 'blocked'}`).join('; ')}`, { ticket: open[0].id, rule: 5 });
+    if (!tickets.length) return cmd('write the breakdown', '/pincer-narrow — the change has no tickets', { rule: 5 });
+    return cmd('complete the change', change('complete'), { rule: 6 });
+  }
+  // completed
+  if (stale) return cmd(`re-verify ${stale.id} (${stale.readiness.reasons[0].code})`, `${change('reopen')} --reason <text>, then scripts/pincer-ticket.sh verify ${stale.id}`, { ticket: stale.id, rule: 5 });
+  const cand = j.candidate || {};
+  const newer = (cand.reasons || []).find(r => ['CHECK_FAILED', 'ATTEMPT_RUNNING', 'ATTEMPT_TIMED_OUT', 'ATTEMPT_INTERRUPTED', 'ATTEMPT_ERROR'].includes(r.code));
+  if (newer) return cmd(`re-run ${newer.detail.split(':')[0]} and re-evaluate`, `${RUNTIME} check ${newer.detail.split(':')[0]} --candidate ${cand.candidate}${cov ? '' : ' -- <command>'}, then /pincer-evaluate`, { check: newer.detail.split(':')[0], rule: 5 });
+  // Rules 7 and 8 (strict coverage): the candidate coverage decides what the evaluation still lacks.
+  if (cov && cov.candidate.problems.some(p => CANDIDATE_COVERAGE_CODES.includes(p.code) || (cov.candidate.evaluated && ['CHECK_FAILED', 'ATTEMPT_ERROR'].includes(p.code)))) return { ...cov.next, rule: 7 };
+  if (cand.notes !== 'current' || (j.prd && j.prd.status !== 'built')) return cmd('evaluate the candidate', `/pincer-evaluate${j.prd && j.prd.status !== 'built' ? ` (PRD status is '${j.prd.status}', expected 'built')` : cand.reason ? ` (${cand.reason})` : ''}`, { rule: 7 });
+  return cmd('read-only release audit', '/pincer-release', { rule: 8 });
+}
+
+function render(r) {
+  const lines = [];
+  const short = s => (typeof s === 'string' ? s.slice(0, 12) : '—');
+  lines.push(`PINCER resume · ${r.generated} · ${r.root}`);
+  if (!r.change) {
+    lines.push(`Selection  ${r.selection && r.selection.change ? r.selection.change : 'none'}${r.selection && r.selection.problem ? ` · ${r.selection.problem.code}: ${r.selection.problem.detail}` : ''}`);
+  } else {
+    const c = r.change, v = c.view;
+    lines.push(`Change     ${c.id} · ${c.prd} · revision ${short(c.prd_revision)} · base ${c.base.slice(0, 7)} · registered ${c.registered} · sequence ${c.sequence}`);
+    lines.push(`Lifecycle  ${c.lifecycle.state} since ${c.lifecycle.since}${c.lifecycle.superseded_by ? ` · superseded by ${c.lifecycle.superseded_by}` : ''}`);
+    lines.push(`View       HEAD ${v.head ? v.head.slice(0, 7) : 'none'} · branch ${v.branch || 'detached'} · base ${v.base_is_ancestor ? 'is an ancestor' : 'is NOT an ancestor'} · dirty ${v.dirty.length} path(s)${v.dirty.length ? `: ${v.dirty.slice(0, 5).join(', ')}${v.dirty.length > 5 ? ` (+${v.dirty.length - 5})` : ''}` : ''}`);
+    const a = r.agreement;
+    lines.push(`Agreement  ${a.current ? short(a.current) : 'unavailable'}${a.authorized ? ` · authorized as ${a.authorized.agreement} by ${a.authorized.id} (${a.authorized.disposition}, ${a.authorized.recorded})` : ' · not authorized'}${a.difference && !a.difference.same ? ` · differs from the authorized agreement: ${agreement.renderDifference(a.difference)}` : ''}`);
+    lines.push(`Authorization ${a.verdict}${a.authorized && a.authorized.excerpt ? ` — "${a.authorized.excerpt}" (${a.authorized.reference})${a.authorized.constraints ? ` · constraints: ${a.authorized.constraints}` : ''}` : ''}`);
+    lines.push(`Decisions  ${a.decisions.open.length || a.decisions.resolved.length ? [...a.decisions.open.map(d => `${d.id} open: ${d.summary}`), ...a.decisions.resolved.map(d => `${d.id} resolved: ${d.summary}`)].join('; ') : 'none'}`);
+    lines.push(`References PRD ${r.references.prd.path}${r.references.prd.title ? ` ("${r.references.prd.title}")` : ''}${r.references.snapshot ? ` · authorized snapshot ${r.references.snapshot}` : ''}${r.references.tickets.length ? ` · tickets ${r.references.tickets.map(t => `${t.id} (${t.file})`).join(', ')}` : ' · no tickets'}`);
+    for (const t of r.references.tickets) if (t.objective) lines.push(`  ${t.id}  ${t.objective}`);
+    const ticketWord = t => (t.status === 'open' ? (t.readiness.reasons.some(x => x.code === 'DEPENDENCY_BLOCKED') ? ` ${t.readiness.reasons[0].detail}` : '') : t.readiness.ready ? ' ready' : t.readiness.reasons[0] ? ` ${t.readiness.reasons[0].code}` : '');
+    lines.push(`Tickets    ${r.tickets.length ? r.tickets.map(t => `${t.id} ${t.status}${ticketWord(t)}`).join(' · ') : 'none'}`);
+    lines.push(`Attempts   ${r.attempts.length ? r.attempts.map(x => `${x.ticket || x.check} ${x.id} ${x.outcome}${x.current ? ' (current)' : ''}`).join('; ') : 'none'}`);
+    const cand = r.candidate;
+    lines.push(`Candidate  ${cand ? `${cand.locator || 'NOTES.md'}: ${cand.notes === 'current' ? `current (${cand.candidate})` : cand.reason}${cand.evidence ? ` · evidence ${cand.evidence.verdict}` : ''}` : 'none'}`);
+    const cv = r.coverage;
+    lines.push(`Coverage   ${cv.label}${cv.strict ? ` · structure ${cv.structure.complete ? 'complete' : `incomplete (${cv.structure.problems[0].code})`} · implementation ${cv.implementation.scenarios.complete}/${cv.implementation.scenarios.total - cv.implementation.scenarios.dispositioned} scenarios · candidate ${cv.candidate.evaluated ? `delivery original ${cv.candidate.delivery.original}, agreed ${cv.candidate.delivery.agreed}, adequacy ${cv.candidate.adequacy}` : 'not evaluated'}` : cv.reason ? ` · ${cv.reason}` : ''}`);
+    lines.push(`Handoff (authored) ${r.handoff ? `${r.handoff.kind || 'note'} since ${r.handoff.since}${r.handoff.reason ? ` · reason: ${r.handoff.reason}` : ''}${r.handoff.note ? ` · note: ${r.handoff.note}` : ''}` : 'none'}`);
+  }
+  lines.push(`Blockers   ${r.blockers.length ? r.blockers.map(b => `${b.code} ${b.detail}`).join('\n           ') : 'none'}`);
+  lines.push(`Next       ${r.next.action}: ${r.next.command}`);
+  return `${lines.join('\n')}\n`;
+}
+
+module.exports = { SCHEMA, build, decide, render };

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

@@ -0,0 +1,54 @@
+'use strict';
+// The head of the next-action precedence (docs/runtime-contracts.md, rules 1-8),
+// in one place. `resume` and `coverage` both render a next action; when each
+// carried its own copy they drifted, and `coverage` ended up recommending
+// commands the gates refuse — `start T-01` on a paused change, execution on a
+// cancelled one. Rules 2 and 3 live here so the two reports cannot disagree
+// again, and so neither can disagree with the gate that will run next.
+const changes = require('./changes.cjs');
+
+const RUNTIME = 'node scripts/pincer-runtime.cjs';
+const action = (what, command, extra = {}) => ({ action: what, command, ticket: null, check: null, ...extra });
+
+// Rules 2 and 3: what outranks the agreement gap. Returns null when none applies
+// and the caller should go on to rule 4.
+//   running       — transaction.runningAttempts(root, id)
+//   viewProblems  — the BASE_MISMATCH reasons for this change
+function preface({ id, lifecycle, base = null, running = [], viewProblems = [] }) {
+  if (running.length) {
+    const first = running[0];
+    return first.alive === false
+      ? action('recover the interrupted attempt', `${RUNTIME} recover`, { rule: 2 })
+      : action('wait for the running attempt', `wait for attempt ${first.id}, or ${RUNTIME} recover if its owner died`, { rule: 2 });
+  }
+  if (changes.TERMINAL.includes(lifecycle.state)) {
+    return action('inspect the historical change; execution needs a new change',
+      `${RUNTIME} change show ${id} — then register a replacement: ${RUNTIME} register --prd <prd> --change <id>`, { rule: 3 });
+  }
+  if (viewProblems.length) {
+    return action('check out the branch that carries the change',
+      `git checkout <branch with base ${String(base || '').slice(0, 7)}> — ${viewProblems[0].detail}`, { rule: 3 });
+  }
+  return null;
+}
+
+// Rule 3 again, after rule 4 is satisfied: a planned or paused change has to be
+// brought to active before any ticket command will run.
+function lifecycleAction({ id, lifecycle }) {
+  if (lifecycle.state === 'planned') return action('activate the change', `${RUNTIME} change activate ${id}`, { rule: 3 });
+  if (lifecycle.state === 'paused') return action('resume the change', `${RUNTIME} change resume ${id}`, { rule: 3 });
+  return null;
+}
+
+// A ticket command resolves its ticket against the *selected* change, so when a
+// report describes a change this worktree has not selected, the command it prints
+// is refused with WRONG_CHANGE unless the selection is changed first. Commands that
+// name their change explicitly (`change authorize <id>`, `change show <id>`) run
+// as written and are left alone.
+const TICKET_COMMAND = /(^|[^\w])(scripts\/pincer-ticket\.sh|pincer-runtime\.cjs)\s+(start|verify|done)\s+T-/;
+function qualify(next, { id, selected = true }) {
+  if (selected || !next || typeof next.command !== 'string' || !TICKET_COMMAND.test(next.command)) return next;
+  return { ...next, command: `${RUNTIME} change select ${id}, then ${next.command}` };
+}
+
+module.exports = { preface, lifecycleAction, qualify, RUNTIME };

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

@@ -0,0 +1,242 @@
+'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. `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 };
+
+  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;
+      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, runtime: schema, id, sequence, context: persisted,
+        check: { digest: checkDigest, display, timeout_seconds: timeoutSeconds },
+        outcome: 'running', exit_code: null, signal: null,
+        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 },
+        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 && 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);
+  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: 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) {
+      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 };

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 };