@popovych.co/witness 0.4.0

package/dist/schemas.js

@@ -0,0 +1,119 @@
+import { ID_RE, validateCriteria, validateNeeds } from './dsl.js';
+import { v } from './refusal.js';
+export const SPEC_STATUS = ['draft', 'approved', 'live'];
+export const PLAN_STATUS = ['draft', 'approved', 'in-progress', 'done', 'abandoned'];
+export const PRINCIPLES_STATUS = ['draft', 'approved'];
+export function validateDoc(meta, body) {
+    const out = [];
+    const id = meta.id;
+    if (typeof id !== 'string' || !ID_RE.test(id)) {
+        out.push(v('id', 'id-charset', String(id ?? 'absent'), '[a-z0-9-]+'));
+    }
+    const type = meta.type;
+    if (type !== 'spec' && type !== 'plan' && type !== 'principles') {
+        out.push(v('type', 'enum', String(type ?? 'absent'), 'spec | plan | principles'));
+        return out;
+    }
+    if (typeof id === 'string' && (type === 'principles' ? id !== 'principles' : id === 'principles')) {
+        out.push(v('id', 'reserved', id, "'principles' is reserved for type: principles"));
+    }
+    if (meta.ui !== undefined && type !== 'spec') {
+        out.push(v('ui', 'forbidden', String(meta.ui), 'ui is a spec-only flag'));
+    }
+    if (meta.design !== undefined && type !== 'spec') {
+        out.push(v('design', 'forbidden', 'present', 'design is a spec-only, gate-written stamp'));
+    }
+    const depends = meta.depends ?? [];
+    if (!Array.isArray(depends) || depends.some((d) => typeof d !== 'string' || !ID_RE.test(d))) {
+        out.push(v('depends', 'shape', JSON.stringify(meta.depends), 'list of ids matching [a-z0-9-]+'));
+    }
+    out.push(...validateNeeds(meta.needs));
+    const statuses = type === 'spec' ? SPEC_STATUS : type === 'plan' ? PLAN_STATUS : PRINCIPLES_STATUS;
+    if (!statuses.includes(String(meta.status))) {
+        out.push(v('status', 'enum', String(meta.status ?? 'absent'), statuses.join(' | ')));
+    }
+    if (type === 'spec') {
+        const s = meta.summary;
+        if (typeof s !== 'string' || s.length === 0) {
+            out.push(v('summary', 'required', String(s ?? 'absent'), 'one-liner: what the slice is'));
+        }
+        else if (s.length > 120) {
+            out.push(v('summary', 'max-length', `${s.length} chars`, '<=120 chars'));
+        }
+        if (meta.ui !== undefined && meta.ui !== true) {
+            out.push(v('ui', 'shape', String(meta.ui), 'true or omitted (a ui spec earns a design stage)'));
+        }
+        if (meta.design !== undefined) {
+            const d = meta.design;
+            const hex = (x) => typeof x === 'string' && /^[0-9a-f]{64}$/.test(x);
+            if (typeof meta.design !== 'object' || meta.design === null || !hex(d.sha) || !hex(d.spec)) {
+                out.push(v('design', 'shape', JSON.stringify(meta.design), '{sha: <64hex>, spec: <64hex>} — the gate-written design stamp'));
+            }
+        }
+        if (typeof id === 'string')
+            out.push(...validateCriteria(meta.criteria, id));
+        if (meta.supersedes !== undefined && (typeof meta.supersedes !== 'string' || !ID_RE.test(meta.supersedes))) {
+            out.push(v('supersedes', 'shape', String(meta.supersedes), 'a spec id'));
+        }
+        for (const h of ['## Motivation', '## Behavior']) {
+            if (!new RegExp(`^${h}$`, 'm').test(body)) {
+                out.push(v('body', 'template', `missing ${h}`, 'spec body carries ## Motivation and ## Behavior'));
+            }
+        }
+    }
+    if (type === 'plan') {
+        if (typeof meta.parent !== 'string' || !ID_RE.test(meta.parent)) {
+            out.push(v('parent', 'required', String(meta.parent ?? 'absent'), 'parent spec id (or principles for chores)'));
+        }
+        const df = meta['derives-from'];
+        if (typeof df !== 'string' || !/^[0-9a-f]{64}$/.test(df)) {
+            out.push(v('derives-from', 'shape', String(df ?? 'absent'), '64-hex canonical content sha'));
+        }
+        if (meta['design-from'] !== undefined && (typeof meta['design-from'] !== 'string' || !/^[0-9a-f]{64}$/.test(String(meta['design-from'])))) {
+            out.push(v('design-from', 'shape', String(meta['design-from']), '64-hex design artifact sha'));
+        }
+        out.push(...validateSteps(meta.steps, body));
+    }
+    if (type === 'principles' && meta.criteria !== undefined) {
+        out.push(v('criteria', 'forbidden', 'present', 'principles carry no criteria'));
+    }
+    return out;
+}
+function validateSteps(raw, body) {
+    if (!Array.isArray(raw) || raw.length === 0) {
+        return [v('steps', 'required', raw === undefined ? 'absent' : 'empty', '>=1 step {id, title, criteria|scaffolding}')];
+    }
+    const out = [];
+    const ids = new Set();
+    raw.forEach((s, i) => {
+        const at = `steps[${i}]`;
+        const e = (typeof s === 'object' && s !== null ? s : {});
+        if (typeof e.id !== 'string' || !ID_RE.test(e.id)) {
+            out.push(v(`${at}.id`, 'id-charset', String(e.id ?? 'absent'), '[a-z0-9-]+'));
+        }
+        else if (ids.has(e.id)) {
+            out.push(v(`${at}.id`, 'id-unique', e.id, 'unique per plan'));
+        }
+        else {
+            ids.add(e.id);
+        }
+        if (typeof e.title !== 'string' || e.title === '') {
+            out.push(v(`${at}.title`, 'required', String(e.title ?? 'absent'), 'non-empty title'));
+        }
+        const hasCriteria = Array.isArray(e.criteria) && e.criteria.length > 0;
+        const isScaffolding = e.scaffolding === true;
+        if (hasCriteria === isScaffolding) {
+            out.push(v(at, 'mapping', hasCriteria ? 'criteria and scaffolding' : 'neither criteria nor scaffolding', 'criteria: [ids] XOR scaffolding: true'));
+        }
+    });
+    const found = new Set([...body.matchAll(/^## Step: (\S+)$/gm)].map((m) => m[1]));
+    for (const sid of ids) {
+        if (!found.has(sid))
+            out.push(v('body', 'step-section-missing', `no '## Step: ${sid}' section`, 'one section per manifest step'));
+    }
+    for (const f of found) {
+        if (!ids.has(f))
+            out.push(v('body', 'step-section-orphan', `'## Step: ${f}'`, 'every section names a manifest step'));
+    }
+    return out;
+}

package/dist/sha.js

@@ -0,0 +1,27 @@
+import { createHash } from 'node:crypto';
+export const VOLATILE_FIELDS = ['status', 'drift', 'pr', 'design'];
+export function canonicalJson(value) {
+    if (Array.isArray(value))
+        return '[' + value.map(canonicalJson).join(',') + ']';
+    if (value && typeof value === 'object') {
+        return ('{' +
+            Object.entries(value)
+                .filter(([, val]) => val !== undefined)
+                .sort(([a], [b]) => (a < b ? -1 : a > b ? 1 : 0))
+                .map(([k, val]) => JSON.stringify(k) + ':' + canonicalJson(val))
+                .join(',') +
+            '}');
+    }
+    return JSON.stringify(value);
+}
+export function canonicalSha(meta, body) {
+    const kept = Object.fromEntries(Object.entries(meta).filter(([k]) => !VOLATILE_FIELDS.includes(k)));
+    return createHash('sha256')
+        .update(canonicalJson(kept))
+        .update('\0')
+        .update(body.replace(/\s+$/, '') + '\n')
+        .digest('hex');
+}
+export function short(sha) {
+    return sha.slice(0, 7);
+}

package/dist/ship.js

@@ -0,0 +1,257 @@
+import { execFileSync } from 'node:child_process';
+import { EXIT } from './cli.js';
+import { loadConfig } from './config.js';
+import { acquireLock } from './lock.js';
+import { crashPoint, guardTxn, withTxn } from './txn.js';
+import { journalRel, readStream } from './journal.js';
+import { primaryRoot, stateCommit, tryGit } from './gitio.js';
+import { findById, loadCanon } from './scan.js';
+import { ok, refuse, renderRefusal, v } from './refusal.js';
+import { kv } from './toon.js';
+import { runGate } from './gate.js';
+import { lastGateRun } from './rounds.js';
+import { prepareStamp, writeStamp } from './stamp.js';
+import { branchName, worktreePath } from './worktree.js';
+import { gateSettled } from './verbs/next.js';
+import { worktreeTreeSha } from './reviewed.js';
+export function shipPhase(plan, entries, treeSha, baseMoved = false) {
+    // A PR exists, but the watch is only legitimate while the verdict still describes both
+    // this tree AND this base. Either one moving re-arms the gate — otherwise a rebase (or
+    // any post-approval edit) merges a tree no battery ever read, and re-running
+    // `witness ship` is a one-command bypass of every check below.
+    // `baseMoved` is a SEPARATE input from `treeSha` on purpose: a moved base has not yet
+    // touched the worktree, so the tree sha still matches. Routing on the tree alone would
+    // detect the moved base forever and never rebase — only the gate phase rebases, and it
+    // is the rebase that finally moves the tree.
+    if (plan.meta.pr !== undefined) {
+        return gateSettled(entries, 'ship', treeSha) && !baseMoved ? 'watch' : 'gate';
+    }
+    const last = lastGateRun(entries, 'ship');
+    if (!last)
+        return 'gate';
+    const after = entries.slice(entries.indexOf(last) + 1);
+    const decision = after.find((e) => e.t === 'human-decision' && e.gate === 'ship');
+    // awaiting-decision is deliberately blind to baseMoved: a human reading
+    // `decide ship --show` is reading findings pinned to a sha, and rebasing under them
+    // would lapse the very gate they are deciding on.
+    if (!decision)
+        return 'awaiting-decision';
+    if (decision.decision !== 'approve')
+        return 'gate';
+    // An approval is against a base as well as a tree — opening the PR on a base that has
+    // since moved is the same stale-review bug one step earlier.
+    return baseMoved ? 'gate' : 'pr';
+}
+function gh(ctx, cwd, args, timeout = 120_000) {
+    try {
+        const out = execFileSync('gh', args, {
+            cwd, env: ctx.env, encoding: 'utf8', timeout, maxBuffer: 16 * 1024 * 1024,
+        });
+        return { ok: true, out };
+    }
+    catch (e) {
+        const err = e;
+        return { ok: false, out: `${err.stdout ?? ''}${err.stderr ?? ''}` || String(err.message) };
+    }
+}
+export function existingPr(ctx, root, branch) {
+    const r = gh(ctx, root, ['pr', 'list', '--head', branch, '--json', 'number']);
+    if (!r.ok)
+        return undefined;
+    try {
+        const arr = JSON.parse(r.out);
+        return arr[0]?.number;
+    }
+    catch {
+        return undefined;
+    }
+}
+export function createPr(ctx, wt, root, plan, parentSummary) {
+    const branch = branchName(String(plan.meta.id));
+    if (!tryGit(root, 'remote', 'get-url', 'origin').ok) {
+        return refuse([v('origin', 'no-remote', '(none)', 'an origin remote — gh pr create needs one')]);
+    }
+    // --force-with-lease once an upstream exists: the rebase now runs in the GATE phase, so
+    // a re-entered pr phase pushes a rebased branch and a plain push is no longer a
+    // fast-forward. The lease still refuses to clobber anything pushed by someone else.
+    const hasUpstream = tryGit(wt, 'rev-parse', '--verify', `refs/remotes/origin/${branch}`).ok;
+    const push = hasUpstream
+        ? tryGit(wt, 'push', '--force-with-lease', '-u', 'origin', branch)
+        : tryGit(wt, 'push', '-u', 'origin', branch);
+    if (!push.ok)
+        return refuse([v('push', 'push-failed', push.out.slice(0, 200), 'git push -u origin to succeed')]);
+    const found = existingPr(ctx, root, branch);
+    if (found !== undefined)
+        return ok(found);
+    const created = gh(ctx, wt, ['pr', 'create', '--head', branch,
+        '--title', `${String(plan.meta.id)}: ${parentSummary}`,
+        '--body', `Realizes spec ${String(plan.meta.parent)} at ${String(plan.meta['derives-from']).slice(0, 7)} (witness).`]);
+    if (!created.ok) {
+        return refuse([v('gh', 'pr-create-failed', created.out.slice(0, 200), 'gh authenticated with push access — witness check probes gh auth status')]);
+    }
+    const m = /\/pull\/(\d+)\s*$/.exec(created.out.trim());
+    if (!m)
+        return refuse([v('gh', 'pr-url-unparseable', created.out.slice(-120), 'a …/pull/<n> URL')]);
+    return ok(Number(m[1]));
+}
+export function stampPr(ctx, root, planId, pr) {
+    const canon = loadCanon(root);
+    const plan = findById(canon, planId);
+    const stamp = prepareStamp(plan, String(plan.meta.status), 'ship', { pr });
+    // pr: is volatile — status stays in-progress; the stamp writes meta.pr and journals the entry
+    const lockR = acquireLock(root);
+    if (!lockR.ok)
+        return lockR;
+    try {
+        return withTxn(root, {
+            op: 'pr-stamp', files: [plan.rel, journalRel(planId)],
+            journalMulti: [{ stream: planId, line: stamp.line }],
+        }, () => {
+            writeStamp(root, { ...stamp, doc: { ...plan, meta: { ...plan.meta, pr } } });
+            crashPoint(ctx.env, 'pr-stamp');
+            return stateCommit(root, [plan.rel, journalRel(planId)], `ship(${planId}): pr #${pr}`);
+        });
+    }
+    finally {
+        lockR.value();
+    }
+}
+export function rebaseIfMoved(wt, shipBranch, remote = 'origin') {
+    // Resolve the base from the REMOTE tip, not the local ref: with several flows merging
+    // concurrently, local <shipBranch> lags every merge since the human's last pull, so a
+    // local ancestry check reports "clean" against a base that is provably behind and the
+    // conflict resurfaces on GitHub after CI already went green.
+    if (!tryGit(wt, 'remote', 'get-url', remote).ok) {
+        return refuse([v('origin', 'no-remote', '(none)', `a ${remote} remote — ship rebases on its tip`)]);
+    }
+    // A configured remote that will not fetch is NOT the offline case. Degrading to the
+    // local ref here would silently rebase on a stale base immediately before a merge,
+    // which is the exact failure this function exists to prevent.
+    const fetched = tryGit(wt, 'fetch', remote, shipBranch);
+    if (!fetched.ok) {
+        return refuse([v('fetch', 'fetch-failed', fetched.out.slice(0, 200), `git fetch ${remote} ${shipBranch} to succeed`)]);
+    }
+    const base = `${remote}/${shipBranch}`;
+    if (tryGit(wt, 'merge-base', '--is-ancestor', base, 'HEAD').ok)
+        return ok('clean');
+    // --autostash: this runs in the GATE phase, and implement deliberately leaves the
+    // worktree uncommitted (ship owns the sole code commit, in the pr phase below), so the
+    // tree is normally dirty and a bare rebase refuses with "you have unstaged changes".
+    // Autostash makes the rebase see a clean tree without moving witness's commit ahead of
+    // the human's decision. A pop that conflicts fails the rebase and refuses like any other.
+    const rebase = tryGit(wt, 'rebase', '--autostash', base);
+    if (!rebase.ok) {
+        tryGit(wt, 'rebase', '--abort');
+        return refuse([v('rebase', 'textual-conflict', `${base} moved`, 'resolve in the worktree (rebase manually), then re-run witness ship — the CLI never freehands a merge')]);
+    }
+    // Only push a branch that HAS an upstream. This now runs in the gate phase, before
+    // createPr has ever pushed, so on a first ship there is nothing on the remote to
+    // update and an unconditional push fails with "no upstream branch" — createPr does
+    // the initial push. Where an upstream does exist the push result is the whole point:
+    // reporting 'rebased' after a failed push leaves the PR head on the pre-rebase commit,
+    // and CI goes green on a tree nobody will merge.
+    if (tryGit(wt, 'rev-parse', '--verify', '--quiet', '@{upstream}').ok) {
+        const push = tryGit(wt, 'push', '--force-with-lease');
+        if (!push.ok) {
+            return refuse([v('push', 'push-failed', push.out.slice(0, 200), 'git push --force-with-lease to succeed')]);
+        }
+    }
+    return ok('rebased');
+}
+export async function runShip(ctx, planId) {
+    const rootR = primaryRoot(ctx.cwd);
+    if (!rootR.ok) {
+        renderRefusal(rootR.violations).forEach((l) => ctx.err(l));
+        return EXIT.REFUSED;
+    }
+    const root = rootR.value;
+    const blocked = guardTxn(ctx, root);
+    if (blocked !== undefined)
+        return blocked;
+    const cfgR = loadConfig(root);
+    if (!cfgR.ok) {
+        renderRefusal(cfgR.violations).forEach((l) => ctx.err(l));
+        return EXIT.REFUSED;
+    }
+    const canon = loadCanon(root);
+    const plan = findById(canon, planId);
+    if (!plan || plan.meta.type !== 'plan') {
+        renderRefusal([v('plan', 'unknown-plan', planId, 'a plans/ doc id')]).forEach((l) => ctx.err(l));
+        return EXIT.REFUSED;
+    }
+    const wt = worktreePath(root, planId);
+    const entries = readStream(root, planId);
+    const ship = (cfgR.value.raw.ship ?? {});
+    const shipBranch = ship.branch ?? 'main';
+    // One read-only fetch decides the whole routing. A failed fetch (no remote, offline)
+    // leaves baseMoved false and the phases behave as they did — the gate phase's own
+    // rebaseIfMoved is where that condition turns into a structured refusal.
+    const baseMoved = tryGit(wt, 'fetch', 'origin', shipBranch).ok
+        && !tryGit(wt, 'merge-base', '--is-ancestor', `origin/${shipBranch}`, 'HEAD').ok;
+    let phase = shipPhase(plan, entries, worktreeTreeSha(wt), baseMoved);
+    if (baseMoved)
+        ctx.out(kv('ship', `${shipBranch} moved — rebasing and re-reviewing before the watch`));
+    if (phase === 'gate') {
+        // Rebase BEFORE the battery, never after: the reviewers must judge the tree that will
+        // actually merge. Reviewing first spends a battery — and a human decision — on a tree
+        // without any sibling's merged work, which then lapses (gateSettled's reviewed_sha)
+        // the moment the rebase lands.
+        const rebase = rebaseIfMoved(wt, shipBranch);
+        if (!rebase.ok) {
+            renderRefusal(rebase.violations).forEach((l) => ctx.err(l));
+            // A textual conflict is a hand-back, not a refusal: the human resolves it in the
+            // worktree and re-runs. Every other rule (no-remote, fetch-failed, push-failed) is
+            // a genuine refusal and exits REFUSED like the rest of the CLI.
+            return rebase.violations.some((x) => x.rule === 'textual-conflict') ? EXIT.FINDINGS : EXIT.REFUSED;
+        }
+        if (rebase.value === 'rebased')
+            ctx.out(kv('rebase', `${shipBranch} moved — rebased before the battery`));
+        const code = await runGate(ctx, 'ship', planId, { fresh: false, manual: false });
+        if (code !== EXIT.FINDINGS && code !== EXIT.OK)
+            return code;
+        ctx.out(`help: witness decide ship ${planId} --approve to send the PR — ship always stops`);
+        return EXIT.FINDINGS;
+    }
+    if (phase === 'awaiting-decision') {
+        ctx.out(kv('ship', `${planId} awaits the ship decision`));
+        ctx.out(`help: witness decide ship ${planId} --show | --approve | --revise --note "<why>" | --stop`);
+        return EXIT.FINDINGS;
+    }
+    if (phase === 'pr') {
+        const parent = findById(canon, String(plan.meta.parent));
+        const parentSummary = String(parent?.meta.summary ?? 'witness change');
+        // implement leaves the worktree uncommitted — ship owns the sole code commit
+        if (tryGit(wt, 'status', '--porcelain').out !== '') {
+            tryGit(wt, 'add', '-A');
+            const committed = tryGit(wt, 'commit', '-m', `${planId}: ${parentSummary}`);
+            if (!committed.ok) {
+                renderRefusal([v('commit', 'ship-commit-failed', committed.out.slice(0, 200), 'a committable worktree — resolve and re-run witness ship')]).forEach((l) => ctx.err(l));
+                return EXIT.REFUSED;
+            }
+            ctx.out(kv('commit', `${planId}: ${parentSummary}`));
+        }
+        const created = createPr(ctx, wt, root, plan, parentSummary);
+        if (!created.ok) {
+            renderRefusal(created.violations).forEach((l) => ctx.err(l));
+            return EXIT.REFUSED;
+        }
+        const stamped = stampPr(ctx, root, planId, created.value);
+        if (!stamped.ok) {
+            renderRefusal(stamped.violations).forEach((l) => ctx.err(l));
+            return EXIT.REFUSED;
+        }
+        ctx.out(kv('pr', `#${created.value} created and stamped`));
+        phase = 'watch';
+    }
+    const pr = Number(findById(loadCanon(root), planId).meta.pr);
+    // watch never mutates and never rebases: reaching here means shipPhase already
+    // established that both the reviewed tree and the base are the ones the battery judged.
+    const green = gh(ctx, root, ['pr', 'checks', String(pr), '--watch'], 1_800_000);
+    if (!green.ok) {
+        ctx.out(kv('ci', `red — ${green.out.trim().slice(-200)}`));
+        return EXIT.FINDINGS;
+    }
+    ctx.out(kv('ci', 'green'));
+    ctx.out(kv('ship', `merge PR #${pr} on GitHub when ready — the lazy stamp flips plan → done, spec → live`));
+    return EXIT.OK;
+}

package/dist/stamp.js

@@ -0,0 +1,104 @@
+import { execFileSync } from 'node:child_process';
+import { existsSync } from 'node:fs';
+import { join } from 'node:path';
+import { writeDoc } from './fm.js';
+import { stateCommit } from './gitio.js';
+import { appendEntry, entryLine, journalRel } from './journal.js';
+import { acquireLock } from './lock.js';
+import { canonicalSha } from './sha.js';
+import { findById } from './scan.js';
+import { crashPoint, withTxn } from './txn.js';
+import { removeWorktree, worktreePath } from './worktree.js';
+export function prepareStamp(doc, to, cause, extra = {}) {
+    const entry = {
+        v: 1, t: 'status', artifact: String(doc.meta.id),
+        from: String(doc.meta.status), to, cause, ...extra,
+    };
+    return { doc, to, entry, line: entryLine(entry), rel: doc.rel, stream: String(doc.meta.id) };
+}
+export function writeStamp(root, s) {
+    writeDoc(join(root, s.rel), { meta: { ...s.doc.meta, status: s.to }, body: s.doc.body });
+    appendEntry(root, s.stream, s.entry);
+}
+function prState(ctx, root, pr) {
+    try {
+        const out = execFileSync('gh', ['pr', 'view', String(pr), '--json', 'state'], {
+            cwd: root, env: ctx.env, encoding: 'utf8', timeout: 3_000,
+        });
+        return JSON.parse(out).state;
+    }
+    catch {
+        return undefined;
+    }
+}
+export function lazyStamp(root, ctx, canon) {
+    const result = { stamped: [], stale: [] };
+    if (ctx.env.CI)
+        return result; // CI never writes state
+    const candidates = canon.docs.filter((d) => d.meta.type === 'plan' && String(d.meta.status) === 'in-progress' && d.meta.pr !== undefined);
+    for (const plan of candidates) {
+        const planId = String(plan.meta.id);
+        const pr = Number(plan.meta.pr);
+        const state = prState(ctx, root, pr);
+        if (state === undefined) {
+            result.stale.push({ plan: planId, why: "stale, couldn't check" });
+            continue;
+        }
+        if (state === 'CLOSED') {
+            result.stale.push({ plan: planId, why: `pr #${pr} closed unmerged — witness abandon ${planId}?` });
+            continue;
+        }
+        if (state !== 'MERGED') {
+            result.stale.push({ plan: planId, why: `pr #${pr} still ${state}` });
+            continue;
+        }
+        const parent = findById(canon, String(plan.meta.parent));
+        const pinFresh = parent !== undefined &&
+            canonicalSha(parent.meta, parent.body) === String(plan.meta['derives-from']);
+        const planStamp = prepareStamp(plan, 'done', 'merge', { pr, ...(pinFresh ? {} : { note: 'stale-merge' }) });
+        const specStamp = parent && pinFresh && parent.meta.type === 'spec'
+            ? prepareStamp(parent, 'live', 'merge', { pr }) : undefined;
+        const files = [planStamp.rel, journalRel(planStamp.stream),
+            ...(specStamp ? [specStamp.rel, journalRel(specStamp.stream)] : [])];
+        const lockR = acquireLock(root);
+        if (!lockR.ok) {
+            result.stale.push({ plan: planId, why: 'lock held' });
+            continue;
+        }
+        try {
+            const txn = withTxn(root, {
+                op: 'merge-stamp', files,
+                journalMulti: [
+                    { stream: planStamp.stream, line: planStamp.line },
+                    ...(specStamp ? [{ stream: specStamp.stream, line: specStamp.line }] : []),
+                ],
+            }, () => {
+                writeStamp(root, planStamp);
+                if (specStamp)
+                    writeStamp(root, specStamp);
+                crashPoint(ctx.env, 'merge-stamp');
+                return stateCommit(root, files, `merge(${planId}): pr #${pr}`);
+            });
+            if (txn.ok) {
+                removeWorktree(root, planId);
+                result.stamped.push({ plan: planId, ...(specStamp ? { spec: specStamp.stream } : {}), pr });
+            }
+            else {
+                result.stale.push({ plan: planId, why: txn.violations.map((x) => x.rule).join(' ') });
+            }
+        }
+        finally {
+            lockR.value();
+        }
+    }
+    // a crash between writeStamp and this point recovers generically (journal replay +
+    // commit only) — completeTxn has no notion of "also remove the worktree", and a plan
+    // already 'done' never re-enters `candidates` above, so the removal must be re-checked
+    // independently of whichever call actually performed the stamp.
+    for (const plan of canon.docs.filter((d) => d.meta.type === 'plan' && String(d.meta.status) === 'done')) {
+        const planId = String(plan.meta.id);
+        if (existsSync(worktreePath(root, planId)))
+            removeWorktree(root, planId);
+    }
+    return result;
+}

package/dist/toon.js

@@ -0,0 +1,16 @@
+function esc(value) {
+    const s = String(value ?? '');
+    return /[,"\n]|^\s|\s$/.test(s) ? `"${s.replaceAll('"', '""')}"` : s;
+}
+export function kv(key, value) {
+    return `${key}: ${esc(value)}`;
+}
+export function list(key, values) {
+    return `${key}[${values.length}]: ${values.map(esc).join(',')}`;
+}
+export function rows(key, fields, items) {
+    return [
+        `${key}[${items.length}]{${fields.join(',')}}:`,
+        ...items.map((it) => '  ' + fields.map((f) => esc(it[f])).join(',')),
+    ];
+}

package/dist/txn.js

@@ -0,0 +1,70 @@
+import { appendFileSync, existsSync, mkdirSync, readFileSync, rmSync, writeFileSync } from 'node:fs';
+import { join } from 'node:path';
+import { EXIT } from './cli.js';
+import { git, stateCommit, tryGit } from './gitio.js';
+import { journalRel } from './journal.js';
+const markerPath = (root) => join(root, '.witness', 'txn.json');
+export function pendingTxn(root) {
+    if (!existsSync(markerPath(root)))
+        return undefined;
+    return JSON.parse(readFileSync(markerPath(root), 'utf8'));
+}
+export function crashPoint(env, name) {
+    if (env.WITNESS_CRASH_AFTER === name)
+        process.exit(9);
+}
+export function withTxn(root, marker, fn) {
+    mkdirSync(join(root, '.witness'), { recursive: true });
+    writeFileSync(markerPath(root), JSON.stringify(marker));
+    let res;
+    try {
+        res = fn();
+    }
+    catch (e) {
+        rollbackTxn(root, marker);
+        throw e;
+    }
+    if (res.ok)
+        rmSync(markerPath(root), { force: true });
+    else
+        rollbackTxn(root, marker);
+    return res;
+}
+export function rollbackTxn(root, marker) {
+    for (const f of marker.files) {
+        const tracked = tryGit(root, 'ls-files', '--error-unmatch', '--', f).ok;
+        if (tracked)
+            git(root, 'checkout', '--', f);
+        else
+            rmSync(join(root, f), { force: true });
+    }
+    rmSync(markerPath(root), { force: true });
+}
+export function completeTxn(root, marker) {
+    const items = [...(marker.journal ? [marker.journal] : []), ...(marker.journalMulti ?? [])];
+    if (items.length)
+        mkdirSync(join(root, '.witness', 'journal'), { recursive: true });
+    for (const { stream, line } of items) {
+        const p = join(root, journalRel(stream));
+        const current = existsSync(p) ? readFileSync(p, 'utf8') : '';
+        const lastLine = current.split('\n').filter(Boolean).at(-1);
+        if (lastLine !== line)
+            appendFileSync(p, line + '\n');
+    }
+    const res = stateCommit(root, marker.files, `${marker.op} (recovered)`);
+    if (res.ok)
+        rmSync(markerPath(root), { force: true });
+    return res;
+}
+export function guardTxn(ctx, root) {
+    const m = pendingTxn(root);
+    if (!m)
+        return undefined;
+    ctx.err(`pending transaction from a crashed invocation: ${m.op}`);
+    // `files` is required on every marker and populated at all withTxn sites, so this
+    // localizes the damage everywhere — unlike an optional owner field, which would be
+    // absent at the longest-running write window (gate.ts) and teach a false distinction.
+    ctx.err(`  files: ${m.files.join(', ')}`);
+    ctx.err('help: witness recover --complete | --rollback');
+    return EXIT.BLOCKED;
+}