@smartmemory/stratum 0.4.6 → 0.5.0

package/dist/engine/engine.js

@@ -6,6 +6,8 @@ import { join, resolve } from "node:path";
 import { promisify } from "node:util";
 import { z } from "zod";
 import { runAgent } from "../connectors/runner.js";
+import { processIdentity } from "../connectors/proc_identity.js";
+import { procStartTime } from "../connectors/proc_identity.js";
 import { extractReferences } from "../ir/refs.js";
 import { validateSpec } from "../ir/validate.js";
 import { LearnEgress } from "../learn/smartmemory_egress.js";
@@ -14,8 +16,9 @@ import { buildFlowTerminalEvent, buildGateResolutionEvent } from "../policy/even
 import { emitPolicyEvent as postPolicyEvent } from "../policy/smartmemory_client.js";
 import { BUDGET_KEYS, BudgetLedger, validConnectorTelemetry, validUsage } from "./ledger.js";
 import { commitCheckpoint, revertCheckpoint } from "./checkpoint.js";
+import { acquireRunLock, cancelLockWaitMs, readDriverLeaseSync, releaseDriverLeaseSync, writeDriverLeaseSync } from "./run_lock.js";
 import { buildReceipt, findReceipt, ReceiptValidationError, spineSpent } from "./receipts.js";
-import { StateStore } from "./state.js";
+import { assertRunId, burnIssuances, StateStore } from "./state.js";
 const execFileAsync = promisify(execFile);
 /**
  * The fixed shape every S1 `evaluate:` step must return. Engine-owned and
@@ -89,8 +92,28 @@ export class StratumEngine {
     // V1 loop ownership is in-process like runLocks; startup rehydrates ownership
     // for detached runs marked in their durable state.
     bgFlows = new Map();
+    // Run ids whose cross-process file lock this engine currently holds. `persist` asserts
+    // membership: every write to a run record happens inside a locked section, and this
+    // assertion is what makes that claim checkable rather than a comment.
+    heldLocks = new Set();
+    // Driver-lease tokens for the runs this engine has pinned (R4-4). A lease naming another
+    // LIVE process means that process owns the in-memory copy of the run, and a cancel from
+    // here is refused rather than raced.
+    driverLeases = new Map();
+    lockOptions;
+    hooks;
+    identity;
+    selfStartTime;
+    selfIdentityReady;
     constructor(options) {
         this.store = new StateStore(options.stateRoot);
+        this.lockOptions = options.lockOptions ?? {};
+        this.hooks = options.hooks ?? {};
+        this.identity = this.lockOptions.identity ?? processIdentity;
+        this.selfIdentityReady = (this.lockOptions.selfStartTime ?? (() => procStartTime(process.pid)))()
+            .then((value) => { if (value !== undefined)
+            this.selfStartTime = value; })
+            .catch(() => undefined);
         this.evaluator = options.evaluator;
         if (options.judge)
             this.judge = options.judge;
@@ -101,6 +124,10 @@ export class StratumEngine {
             ...options.learnEgressOptions,
             store: this.store,
             withReceiptUpdate: (runId, update) => this.withReceiptUpdate(runId, update),
+            // F3: a drain snapshot is a READ. Routed through the update path it re-persisted the
+            // record, and on a cancelled run that meant the guard above rejected a call that was
+            // never going to write anything.
+            withReceiptRead: (runId, read) => this.withRunLock(runId, async () => read(await this.loadRun(runId))),
         });
         this.learnEgressStartup = this.learnEgress.enabled()
             ? this.learnEgress.drainAll().catch((error) => {
@@ -114,24 +141,106 @@ export class StratumEngine {
             return active.run;
         return this.store.load(runId);
     }
+    /** Pinning is SYNCHRONOUS by design (see scheduleFanout), so the lease it declares is
+     *  written synchronously too — a deferred async write would leave a window in which a
+     *  pinned run looks unowned to a second process. */
     retainRun(runId, run) {
         const active = this.activeRuns.get(runId);
-        if (active)
+        if (active) {
             active.refs += 1;
-        else
-            this.activeRuns.set(runId, { run, refs: 1 });
+            return;
+        }
+        // An UNLEASED pin is the exact state the lease exists to make impossible: this process
+        // holds the run's in-memory object, and nothing on disk says so, so a second process reads
+        // "unowned", cancels against its own copy, and the two diverge. Refusing to pin is the
+        // only safe answer to "we cannot declare ownership" — the previous `return` pinned anyway.
+        if (this.selfStartTime === undefined) {
+            throw Object.assign(new Error(`cannot establish process identity; run ${runId} cannot be pinned`), { code: "RUN_LOCK_IDENTITY_UNAVAILABLE" });
+        }
+        // Lease FIRST, then register the pin: a throwing claim must leave no pin behind. The error
+        // propagates — a swallowed one produced precisely the unleased pin above, and reported
+        // success while doing it.
+        //
+        // The token we already hold for this run is passed so `writeDriverLeaseSync` can tell OUR
+        // leftover from a live sibling's lease. Identity alone cannot: two engines in one process
+        // share a pid and a start time, so the old same-identity reclaim let the second one delete
+        // the first's live lease and drive the same run (F1).
+        const token = writeDriverLeaseSync(this.store.root, runId, this.selfStartTime, this.driverLeases.get(runId));
+        this.activeRuns.set(runId, { run, refs: 1 });
+        this.driverLeases.set(runId, token);
+    }
+    /** Resolve any INCUMBENT driver lease, immediately before a pin claims one (R4-4).
+     *
+     *  `writeDriverLeaseSync` now claims with `link()` and refuses to overwrite, so the identity
+     *  question has to be ANSWERED rather than papered over by a `rename()`. It is answered here
+     *  because it is async — a probe of another process — while `retainRun` is synchronous by
+     *  design. Every async pin site runs this inside its own locked section, so the answer cannot
+     *  go stale between the probe and the claim. */
+    async prepareLease(runId) {
+        const lease = readDriverLeaseSync(this.store.root, runId);
+        if (lease === undefined)
+            return;
+        if (this.driverLeases.get(runId) === lease.token)
+            return; // ours, by TOKEN
+        // There is deliberately no "same pid and start time, therefore ours" arm here (F1). Two
+        // engine instances in one process answer that test identically, so it let the second one
+        // reclaim a lease the first was actively driving. A same-identity lease whose token we do
+        // not hold is a LIVE lease, and the probe below says so.
+        const state = await this.identity(lease.pid, lease.startTime);
+        if (state === "dead") {
+            releaseDriverLeaseSync(this.store.root, runId, lease.token);
+            return;
+        }
+        throw Object.assign(new Error(`run ${runId} is driven by pid ${lease.pid}; it cannot be pinned from this process`), { code: "DRIVER_LEASE_HELD", holderPid: lease.pid });
     }
     releaseRun(runId) {
         const active = this.activeRuns.get(runId);
         if (!active)
             return;
         active.refs -= 1;
-        if (active.refs <= 0)
-            this.activeRuns.delete(runId);
+        if (active.refs > 0)
+            return;
+        this.activeRuns.delete(runId);
+        const token = this.driverLeases.get(runId);
+        if (token === undefined)
+            return;
+        // Reached from `finally` blocks, so it must not throw — but it must not go quiet either:
+        // a lease left behind wedges every other process off this run.
+        //
+        // The token is forgotten only once the release has actually SUCCEEDED (F5). Deleting it
+        // first meant a transient unlink failure left a lease on disk that this engine no longer
+        // recognised: `prepareLease` and `claimDriverLease` compare by token, so their own leftover
+        // read back as a live foreign lease naming this very pid, and the run became unpinnable and
+        // uncancellable from the one process that owned it. Retaining it keeps the reclaim path open.
+        try {
+            releaseDriverLeaseSync(this.store.root, runId, token);
+            this.driverLeases.delete(runId);
+        }
+        catch (error) {
+            process.stderr.write(`stratum: unable to release driver lease for ${runId}: ${message(error)}\n`);
+        }
     }
-    withRunLock(runId, action) {
+    /** The in-process promise chain still serialises same-process callers cheaply; the file
+     *  lock is what makes the exclusion cross-process. */
+    withRunLock(runId, action, options) {
+        assertRunId(runId);
         const previous = this.runLocks.get(runId) ?? Promise.resolve();
-        const result = previous.then(action);
+        const result = previous.then(async () => {
+            await this.selfIdentityReady;
+            // The cached identity, not a fresh probe: `procStartTime` shells out to python/ps on
+            // darwin, and every locked section on the hot path would otherwise pay for it again.
+            const release = await acquireRunLock(this.store.root, runId, {
+                ...this.lockOptions, ...options, selfStartTime: () => Promise.resolve(this.selfStartTime),
+            });
+            this.heldLocks.add(runId);
+            try {
+                return await action();
+            }
+            finally {
+                this.heldLocks.delete(runId);
+                await release();
+            }
+        });
         const tail = result.catch(() => undefined);
         this.runLocks.set(runId, tail);
         void tail.then(() => {
@@ -143,6 +252,12 @@ export class StratumEngine {
     async withReceiptUpdate(runId, update) {
         return this.withRunLock(runId, async () => {
             const run = await this.loadRun(runId);
+            // Same reason as `usageReport`: refuse BEFORE `update` touches the shared object, not
+            // after, at the persist. The run object is pinned and shared, so a mutation applied and
+            // then rejected is a mutation the rest of the engine can still see.
+            if (run.status === "cancelled" || run.cancelRequested === true) {
+                throw Object.assign(new Error(`run ${runId} is cancelled; no further receipt updates are accepted`), { code: "PERSIST_ON_CANCELLED_RUN" });
+            }
             const result = await update(run);
             await this.persist(run);
             return result;
@@ -202,8 +317,14 @@ export class StratumEngine {
             // different process cwd after restart.
             ...(options.workspaceRoot !== undefined ? { workspaceRoot: resolve(options.workspaceRoot) } : {}),
         };
-        await this.persist(run);
-        return this.withRevisionDigest(await this.advance(run, effectiveValidation.value, effectiveValidation.contracts), run);
+        // R3-3a: the initial persist AND the first advance are inside the lock. The run id is
+        // minted above, and acquireRunLock mkdir -p's the state root, so the lock may legitimately
+        // precede the run file's existence. The advance must be inside too: it is what issues the
+        // first dispatch tokens.
+        return this.withRunLock(run.id, async () => {
+            await this.persist(run);
+            return this.withRevisionDigest(await this.advance(run, effectiveValidation.value, effectiveValidation.contracts), run);
+        });
     }
     async flowRunBg(specInput, input, options = {}) {
         const validation = validateSpec(specInput);
@@ -223,26 +344,48 @@ export class StratumEngine {
             }
         }
         const first = await this.plan(validation.value, input, options);
-        const run = await this.withRunLock(first.runId, async () => {
+        await this.hooks.beforePin?.(first.runId);
+        // ONE locked transaction: load, mark, claim the lease, pin, launch. Splitting it — as this
+        // did, pinning after the lock was released — leaves a window in which the run is loaded,
+        // unpinned and unleased, so a cancel from anywhere settles it durably and the driver then
+        // pins the stale object it loaded before that and writes `running` back over the settle.
+        // The launch is INSIDE too: `driveBg` is not awaited, and its own first `withRunLock`
+        // queues behind this section, so it observes whatever the durable record says afterwards.
+        await this.withRunLock(first.runId, async () => {
             const current = await this.loadRun(first.runId);
-            current.bgDriven = true;
-            await this.persist(current);
-            return current;
-        });
-        const bg = { status: "running", cancelRequested: false, pendingGates: [] };
-        this.bgFlows.set(first.runId, bg);
-        // Pin before launch so the loop and any fanout always share one run object.
-        this.retainRun(first.runId, run);
-        const loop = this.driveBg(first.runId, first);
-        bg.loop = loop;
-        void loop.finally(() => {
-            this.releaseRun(first.runId);
-            if (bg.loop === loop)
-                delete bg.loop;
+            // OWNERSHIP BEFORE BOOKKEEPING (F2). The durable `bgDriven` mark used to be written
+            // first, so a lease this process could not claim left the run marked as driven by a
+            // driver that never started — a run rehydrated on the next boot as a live bg flow with
+            // nothing behind it. Nothing is mutated until the lease and the pin are both held, and
+            // anything that fails after them is rolled back here.
+            await this.prepareLease(first.runId);
+            this.retainRun(first.runId, current);
+            const bg = { status: "running", cancelRequested: false, pendingGates: [] };
+            this.bgFlows.set(first.runId, bg);
+            try {
+                current.bgDriven = true;
+                await this.persist(current);
+            }
+            catch (error) {
+                delete current.bgDriven;
+                this.bgFlows.delete(first.runId);
+                this.releaseRun(first.runId);
+                throw error;
+            }
+            const loop = this.driveBg(first.runId, first);
+            bg.loop = loop;
+            void loop.finally(() => {
+                this.releaseRun(first.runId);
+                if (bg.loop === loop)
+                    delete bg.loop;
+            });
         });
         return { runId: first.runId, status: "running" };
     }
     async rehydrateBgFlows() {
+        // The pins below are synchronous and write a driver lease, which needs this process's
+        // identity resolved first.
+        await this.selfIdentityReady;
         for (const runId of await this.store.list()) {
             let run;
             try {
@@ -267,26 +410,62 @@ export class StratumEngine {
             // its own (background) driver, not abort the whole scan. driveBg self-discovers
             // the live state via reAdvance (which also re-schedules any in-flight fanout),
             // so no explicit resume is needed; the synthesized initial's ledger is never
-            // read (driveBg re-derives it). retainRun and the launch are adjacent with no
-            // throwing await between them, so the retain can never leak.
+            // read (driveBg re-derives it).
+            //
+            // The load above is only a FILTER. Everything that decides ownership — the
+            // authoritative re-load, the lease claim, the pin and the launch — happens inside one
+            // locked section below, because the scan is long and a cancel that lands during it must
+            // be observed rather than overwritten by a driver pinning a pre-cancel snapshot.
             //
             // AT-LEAST-ONCE across restart: an in-flight connector was durable as `ready`,
             // so the driver re-dispatches it — a step may run twice, and that second
             // physical dispatch is NOT re-ledgered (a dispatch budget may under-count by the
             // in-flight-at-crash count). Callers doing writes must be idempotent. A worktree
-            // fanout merge retains its pre-existing crash window (accepted residual). This
-            // assumes SINGLE-PROCESS ownership — the prior engine is gone; two live engines
-            // on one state root are unsupported in v1 (same single-owner model as runLocks).
-            const bg = { status: "running", cancelRequested: false, pendingGates: [] };
-            this.bgFlows.set(run.id, bg);
-            this.retainRun(run.id, run);
-            const loop = this.driveBg(run.id, { status: "running", runId: run.id, ledger: { spent: {} } });
-            bg.loop = loop;
-            void loop.finally(() => {
-                this.releaseRun(run.id);
-                if (bg.loop === loop)
-                    delete bg.loop;
-            });
+            // fanout merge retains its pre-existing crash window (accepted residual).
+            await this.hooks.beforePin?.(run.id);
+            try {
+                await this.withRunLock(run.id, async () => {
+                    const current = await this.store.load(run.id);
+                    // Re-read under the lock: `current`, not the snapshot the scan filtered on.
+                    if (!current.bgDriven || this.bgFlows.has(current.id))
+                        return;
+                    if (current.status !== "running") {
+                        this.bgFlows.set(current.id, { status: current.status, cancelRequested: false, pendingGates: [] });
+                        return;
+                    }
+                    if (current.cancelRequested === true) {
+                        this.bgFlows.set(current.id, { status: "cancelled", cancelRequested: true, pendingGates: [] });
+                        return;
+                    }
+                    // Lease and pin BEFORE the `bgFlows` insert (F2): a failing lease write used to leave
+                    // a `running` entry naming a driver that never launched, and every later poll and
+                    // cancel read that entry as a live loop in this process.
+                    await this.prepareLease(current.id);
+                    this.retainRun(current.id, current);
+                    const bg = { status: "running", cancelRequested: false, pendingGates: [] };
+                    this.bgFlows.set(current.id, bg);
+                    let loop;
+                    try {
+                        loop = this.driveBg(current.id, { status: "running", runId: current.id, ledger: { spent: {} } });
+                    }
+                    catch (error) {
+                        this.bgFlows.delete(current.id);
+                        this.releaseRun(current.id);
+                        throw error;
+                    }
+                    bg.loop = loop;
+                    void loop.finally(() => {
+                        this.releaseRun(current.id);
+                        if (bg.loop === loop)
+                            delete bg.loop;
+                    });
+                });
+            }
+            catch (error) {
+                // A live lease elsewhere means another process owns this run: leave it alone rather
+                // than aborting the whole scan. Everything else is equally per-run.
+                process.stderr.write(`stratum: not rehydrating flow '${run.id}': ${message(error)}\n`);
+            }
         }
     }
     async stepDone(runId, stepId, result, dispatchToken) {
@@ -435,6 +614,15 @@ export class StratumEngine {
                 throw new ReceiptValidationError('usdSource "legacy" is reserved for engine-synthesized receipts');
             }
             const run = await this.loadRun(runId);
+            // R4-1 BEFORE duplicate detection and before any mutation. `persist` refuses a cancelled
+            // record, but by the time it does, this method has already advanced `receiptCounter`,
+            // debited the ledger and appended the receipt and its events to the in-memory object the
+            // rest of the engine shares — so the throw leaves the pinned run mutated, and an
+            // automatic retry finds its own receipt, takes the duplicate branch, and reports SUCCESS
+            // for a receipt that was never durably recorded.
+            if (run.status === "cancelled" || run.cancelRequested === true) {
+                throw Object.assign(new Error(`run ${runId} is cancelled; no further receipts are accepted`), { code: "PERSIST_ON_CANCELLED_RUN" });
+            }
             const candidate = input;
             if (typeof input !== "object" || input === null || Array.isArray(input)
                 || typeof candidate?.dispatchId !== "string" || candidate.dispatchId.length === 0) {
@@ -497,6 +685,7 @@ export class StratumEngine {
         this.assertExternalMutationAllowed(runId, "commit");
         return await this.withRunLock(runId, async () => {
             const run = await this.loadCheckpointRun(runId);
+            this.assertCancelledCheckpointRefusal(run, "commit");
             this.assertNoForegroundFanout(run, "commit");
             const normalized = label.trim();
             if (!normalized)
@@ -519,6 +708,7 @@ export class StratumEngine {
         this.assertExternalMutationAllowed(runId, "revert");
         return await this.withRunLock(runId, async () => {
             const run = await this.loadCheckpointRun(runId);
+            this.assertCancelledCheckpointRefusal(run, "revert");
             this.assertNoForegroundFanout(run, "revert");
             const normalized = label.trim();
             // Money spent is spent: a revert restores state, never spend. Capture the live
@@ -573,6 +763,19 @@ export class StratumEngine {
     }
     async resumeLocked(runId) {
         const run = await this.loadRun(runId);
+        // D5. Without this a cancelled run re-emits `resumed`, re-arms every in-flight fanout
+        // below, and lands in advance's {status:"running"} limbo. assertExternalMutationAllowed
+        // cannot cover it: a foreground run has no bgFlows entry.
+        if (run.cancelRequested === true || run.status === "cancelled") {
+            throw new Error(`run ${runId} is cancelled; resume is not permitted`);
+        }
+        // Resume is the TAKEOVER entry point: it re-arms in-flight fanouts, and arming one pins the
+        // run. The pin used to meet the incumbent lease with no way to resolve it — `scheduleFanout`
+        // is synchronous, so it cannot probe an owner — and the only thing that got past a leftover
+        // lease was the same-pid reclaim F1 removes. A crashed driver's lease would therefore have
+        // wedged every later resume. Resolve it HERE, where the probe can be awaited: a dead owner
+        // is reclaimed, a live one still refuses.
+        await this.prepareLease(runId);
         const computedDigest = digest(run.spec);
         if (run.revisionDigest !== undefined && run.revisionDigest !== computedDigest) {
             throw new Error("persisted revision digest does not match the effective specification");
@@ -596,7 +799,7 @@ export class StratumEngine {
         // holds: audit is the consumer's discovery surface (D5) and a token minted
         // on the live object must stay invisible until its save lands.
         const run = await this.store.load(runId);
-        return { runId, status: run.status, events: structuredClone(run.events), steps: structuredClone(run.steps), flowSpent: structuredClone(run.flowSpent), ...(run.output !== undefined ? { output: structuredClone(run.output) } : {}) };
+        return { runId, status: run.status, events: structuredClone(run.events), steps: structuredClone(run.steps), flowSpent: structuredClone(run.flowSpent), ...(run.output !== undefined ? { output: structuredClone(run.output) } : {}), ...(run.carry !== undefined ? { carry: structuredClone(run.carry) } : {}) };
     }
     /** Restart-safe read-only wait surface: events are sliced from the persisted spine. */
     async flowPoll(runId, cursor = 0) {
@@ -654,41 +857,202 @@ export class StratumEngine {
         }
         return { status: bg.status };
     }
-    async gateResolve(runId, stepId, decision, gateToken, userId) {
-        const response = await this.withRunLock(runId, () => this.gateResolveLocked(runId, stepId, decision, gateToken));
-        const resolvedRun = await this.loadRun(runId);
-        if (resolvedRun.bundle_id !== undefined) {
-            const round = resolvedRun.events.filter((event) => event.type === "gate_resolved" && event.stepId === stepId).length;
-            this.firePolicyEvent(buildGateResolutionEvent({
-                runId,
-                bundleId: resolvedRun.bundle_id,
-                stepId,
-                round,
-                outcome: decision,
-                ...(userId !== undefined ? { resolvedByUserId: userId } : {}),
-            }));
+    /** R4-4. A live lease held by ANOTHER process means that process owns the in-memory copy of
+     *  this run: refuse rather than race it. A provably dead owner's lease is removed and we
+     *  proceed, because the crashed driver's memory is gone and disk is truth again. An
+     *  `unknown` identity is never reclaimed — we do not break a lease we cannot disprove. */
+    async claimDriverLease(runId) {
+        const lease = readDriverLeaseSync(this.store.root, runId);
+        if (lease === undefined)
+            return;
+        if (this.driverLeases.get(runId) === lease.token)
+            return; // ours
+        const state = await this.identity(lease.pid, lease.startTime);
+        if (state === "dead") {
+            releaseDriverLeaseSync(this.store.root, runId, lease.token);
+            return;
         }
-        const bg = this.bgFlows.get(runId);
-        if (bg?.status === "paused_gate" && response.status !== "ready" && response.status !== "running") {
-            bg.status = response.status;
-            bg.pendingGates = [];
+        throw Object.assign(new Error(`run ${runId} is driven by pid ${lease.pid}; cancel must be issued from that process`), { code: "CANCELLATION_UNCONFIRMED", reason: "engine_dispatch_active", holderPid: lease.pid });
+    }
+    /** R3-7. Admission for a foreground agent about to be spawned against this flow.
+     *
+     *  Deliberately NOT a boolean: `false` would conflate "healthy", "does not exist" and
+     *  "could not read the record", and only the first is a reason to start an agent. An
+     *  unreadable record fails CLOSED, because admitting an uncancellable agent is the failure
+     *  this check exists to prevent. */
+    async admitFlowAgent(runId) {
+        let run;
+        try {
+            run = await this.withRunLock(runId, () => this.loadRun(runId));
         }
-        else if (bg?.status === "paused_gate") {
+        catch (error) {
+            if (typeof error === "object" && error !== null && "code" in error && error.code === "ENOENT") {
+                throw Object.assign(new Error(`flow ${runId} is not running`), { code: "FLOW_NOT_RUNNING" });
+            }
+            throw Object.assign(new Error(`flow ${runId} admission check failed: ${message(error)}`), { code: "FLOW_ADMISSION_FAILED" });
+        }
+        if (run.status !== "running" || run.cancelRequested === true) {
+            throw Object.assign(new Error(`flow ${runId} is ${run.status === "running" ? "cancelled" : run.status}`), { code: "FLOW_NOT_RUNNING" });
+        }
+    }
+    /** Foreground cancel, addressable by flow id from any process (STRAT-FLOW-CANCEL-FG).
+     *  Unlike flowCancelBg this SETTLES the run rather than abandoning it, and it works with no
+     *  bgFlows entry — which is the whole point: a compose team build is a foreground
+     *  consumer-fanout run, and `compose build --abort` runs in a different process.
+     *
+     *  One locked section, one persist. No mark-then-settle two-phase: under the lock there is
+     *  nothing to race, so the durable mark and the settle ARE the same write. */
+    async flowCancel(runId, reason) {
+        return this.withRunLock(runId, async () => {
+            // DURABLE STATUS FIRST, and BEFORE the lease decision. Two reasons, both load-bearing:
+            //
+            // A terminal run must not be MUTATED at all, and a lease refusal is a mutation refusal
+            // for a mutation nobody asked for. Worse, an already-cancelled run whose driver's lease
+            // is still live would raise `engine_dispatch_active` — so the orchestrator's re-sweep,
+            // which is the documented recovery from a CANCELLATION_TEARDOWN_TIMEOUT, would fail on
+            // the very run it just cancelled. `already_cancelled` is what lets that sweep run.
+            //
+            // The decision is read from DISK, not from a pinned object: another process may have
+            // completed this run.
+            const persisted = await this.store.load(runId);
+            if (persisted.status !== "running") {
+                return {
+                    runId,
+                    status: persisted.status,
+                    flowSettled: persisted.status === "cancelled",
+                    settledByThisCall: false,
+                    reason: `already_${persisted.status}`,
+                    ledger: this.ledgerInfo(persisted),
+                };
+            }
+            // Only NOW, with the run known to be durably running, does the lease decide whether this
+            // process may apply the cancel at all.
+            await this.claimDriverLease(runId);
+            // Mutate the object the rest of the engine is using. When a fanout of OURS holds a pin,
+            // loadRun returns that instance, so its cooperative brake and its item settle see the
+            // burn on the very same object — which is the whole reason the lease restricts this
+            // path to the driving process (R4-4).
+            const run = await this.loadRun(runId);
+            await this.terminalCancel(run, reason);
+            return { runId, status: run.status, flowSettled: true, settledByThisCall: true, ledger: this.ledgerInfo(run) };
+        }, { timeoutMs: cancelLockWaitMs() });
+    }
+    async gateResolve(runId, stepId, decision, gateToken, userId) {
+        // A PAUSED background flow resolves its gate and re-kicks its driver in ONE locked
+        // transaction, and the driver lease is claimed FIRST (F1). Resolving the gate first —
+        // even in its own earlier locked section — consumed and PERSISTED the gate token before
+        // this process knew it could drive the run at all: a refused claim then left a run whose
+        // successor step was ready, whose durable gate token was already spent, and whose loop had
+        // never started. Nothing could resolve the gate again to produce a driver. Claiming first
+        // means a refusal leaves the durable gate exactly as it was, so the SAME token retries.
+        const bg = this.bgFlows.get(runId);
+        const rekick = bg !== undefined && bg.status === "paused_gate";
+        if (rekick)
+            await this.hooks.beforePin?.(runId);
+        let policy;
+        const response = await this.withRunLock(runId, async () => {
+            if (!rekick || bg === undefined) {
+                const plain = await this.gateResolveLocked(runId, stepId, decision, gateToken);
+                policy = await this.gatePolicySnapshot(runId, stepId);
+                return plain;
+            }
+            // Claim and pin BEFORE the gate is touched. A throw here has mutated nothing.
+            await this.prepareLease(runId);
+            this.retainRun(runId, await this.loadRun(runId));
+            let resolved;
+            try {
+                resolved = await this.gateResolveLocked(runId, stepId, decision, gateToken);
+            }
+            catch (error) {
+                this.releaseRun(runId);
+                throw error;
+            }
+            policy = await this.gatePolicySnapshot(runId, stepId);
+            const durable = await this.store.load(runId);
+            if (resolved.status !== "ready" && resolved.status !== "running") {
+                bg.status = resolved.status;
+                bg.pendingGates = [];
+                this.releaseRun(runId);
+                return resolved;
+            }
+            if (durable.status !== "running" || durable.cancelRequested === true) {
+                bg.status = durable.status === "running" ? "cancelled" : durable.status;
+                bg.pendingGates = [];
+                this.releaseRun(runId);
+                return resolved;
+            }
+            const priorStatus = bg.status;
+            const priorGates = bg.pendingGates;
             bg.status = "running";
             bg.pendingGates = [];
-            const run = await this.loadRun(runId);
-            // Re-kick only after gateResolve releases the run lock; stepDone must interleave.
-            this.retainRun(runId, run);
-            const loop = this.driveBg(runId, response);
+            let loop;
+            try {
+                loop = this.driveBg(runId, resolved);
+            }
+            catch (error) {
+                bg.status = priorStatus;
+                bg.pendingGates = priorGates;
+                this.releaseRun(runId);
+                throw error;
+            }
             bg.loop = loop;
             void loop.finally(() => {
                 this.releaseRun(runId);
                 if (bg.loop === loop)
                     delete bg.loop;
             });
+            return resolved;
+        });
+        if (policy !== undefined) {
+            this.firePolicyEvent(buildGateResolutionEvent({
+                runId,
+                bundleId: policy.bundleId,
+                stepId,
+                round: policy.round,
+                outcome: decision,
+                ...(userId !== undefined ? { resolvedByUserId: userId } : {}),
+            }));
         }
         return response;
     }
+    /** The bundle/round pair the policy event needs, read INSIDE the gate's locked transaction.
+     *  Read afterwards it could count a later round appended by the loop this call just launched. */
+    async gatePolicySnapshot(runId, stepId) {
+        const run = await this.loadRun(runId);
+        if (run.bundle_id === undefined)
+            return undefined;
+        return {
+            bundleId: run.bundle_id,
+            round: run.events.filter((event) => event.type === "gate_resolved" && event.stepId === stepId).length,
+        };
+    }
+    /** Every on_revise write this gate declares, resolved against the UN-RESET scope.
+     *  All expressions are resolved before any of them is applied, so a missing source
+     *  output fails the decision with no partial mutation. */
+    resolveCarryOnRevise(scope, gateId, gateToken) {
+        const declarations = scope.flow.carry;
+        if (declarations === undefined)
+            return [];
+        const writes = [];
+        for (const [name, declaration] of Object.entries(declarations)) {
+            // Object.hasOwn on the on_revise map too: a gate step legitimately named
+            // `constructor` must not pick up an inherited member as a declaration (R2-3).
+            const onRevise = declaration.on_revise;
+            if (onRevise === undefined || !Object.hasOwn(onRevise, gateId))
+                continue; // gates that declare nothing leave the entry untouched
+            const expression = onRevise[gateId];
+            const value = this.resolve(this.carryReference(expression), scope);
+            if (value === undefined) {
+                throw new Error(`carry_revise_unresolved: carry ${JSON.stringify(name)} at gate ${JSON.stringify(gateId)} resolved to no value`);
+            }
+            // sourceStep/sourceEpoch name the INITIAL declaration's source (D6), so the write
+            // survives every later advance until that source is itself reset (D7).
+            const initial = this.carryReference(declaration.initial);
+            const source = initial.kind === "step" ? { sourceStep: initial.stepId, sourceEpoch: scope.steps[initial.stepId]?.epoch ?? 0 } : {};
+            writes.push({ name, value, provenance: { kind: "revise", ...source, gate: gateId, gateToken, at: now() } });
+        }
+        return writes;
+    }
     async gateResolveLocked(runId, stepId, decision, gateToken) {
         // Runtime guard for JS callers: an unknown decision must be rejected, not
         // fall through the ternary chain onto the kill route.
@@ -713,8 +1077,35 @@ export class StratumEngine {
         if (state.gateToken !== gateToken) {
             throw new Error("gate decision is stale: issued for a superseded gate round");
         }
-        delete state.gateToken;
         const target = decision === "approve" ? step.gate.on_approve : decision === "revise" ? step.gate.on_revise : step.gate.on_kill;
+        // ---- STRAT-LOOP-CARRY R1-6: MUTATION-FREE PREFLIGHT ---------------------
+        // Everything that can throw runs here, while the gate token is still valid and no
+        // event has been appended. loadRun returns the LIVE run object while a fanout is
+        // active, so a throw after this point would strand the gate: the token would be
+        // consumed and the decision unrepeatable.
+        let carryWrites = [];
+        let reviseTotal = 0;
+        let reviseGateRounds = 0;
+        if (decision === "revise") {
+            reviseGateRounds = state.iterations ?? 0;
+            reviseTotal = (scope.parent ? scope.parent.state.sub?.rounds ?? 0 : run.rounds ?? 0) + 1;
+            const flowLimit = scope.flow.max_rounds;
+            const gateLimit = step.gate.max_rounds;
+            if (target === null || flowLimit === undefined || reviseTotal > flowLimit || (gateLimit !== undefined && reviseGateRounds + 1 > gateLimit)) {
+                // Rounds exhaustion terminalises the run deliberately; it is the one preflight
+                // outcome that mutates, and nothing runs after it.
+                delete state.gateToken;
+                this.event(run, "gate_resolved", stepId, { decision, target });
+                return scope.parent
+                    ? this.failScope(run, validated.value, validated.contracts, scope, "gate revision rounds exhausted")
+                    : this.terminalFailure(run, { attempt: 0, reason: "gate revision rounds exhausted" });
+            }
+            // Resolves every declared expression against the UN-RESET scope. Throws
+            // `carry_revise_unresolved` before any mutation if one has no value.
+            carryWrites = this.resolveCarryOnRevise(scope, step.id, gateToken);
+        }
+        // ---- END PREFLIGHT; EVERYTHING BELOW MUTATES ----------------------------
+        delete state.gateToken;
         this.event(run, "gate_resolved", stepId, { decision, target });
         if (decision === "kill") {
             state.status = "succeeded";
@@ -726,22 +1117,21 @@ export class StratumEngine {
             }
         }
         else if (decision === "revise") {
-            const total = (scope.parent ? scope.parent.state.sub?.rounds ?? 0 : run.rounds ?? 0) + 1;
-            const gateRounds = state.iterations ?? 0;
-            const flowLimit = scope.flow.max_rounds;
-            const gateLimit = step.gate.max_rounds;
-            if (target === null || flowLimit === undefined || total > flowLimit || (gateLimit !== undefined && gateRounds + 1 > gateLimit)) {
-                return scope.parent
-                    ? this.failScope(run, validated.value, validated.contracts, scope, "gate revision rounds exhausted")
-                    : this.terminalFailure(run, { attempt: 0, reason: "gate revision rounds exhausted" });
-            }
             if (scope.parent)
-                scope.parent.state.sub.rounds = total;
+                scope.parent.state.sub.rounds = reviseTotal;
             else
-                run.rounds = total;
+                run.rounds = reviseTotal;
+            if (carryWrites.length > 0) {
+                const carryStore = this.carryScope(run, validated.value, scope).carry;
+                for (const write of carryWrites) {
+                    const provenance = { ...write.provenance, round: reviseTotal };
+                    carryStore[write.name] = { value: write.value, provenance };
+                    this.event(run, "carry_updated", step.id, { name: write.name, reason: "revise", provenance });
+                }
+            }
             this.resetFrom(run, scope, target);
             // The target's descendants include this gate; retain its local revision counter.
-            scope.steps[step.id].iterations = gateRounds + 1;
+            scope.steps[step.id].iterations = reviseGateRounds + 1;
             await this.persist(run);
             return this.advance(run, validated.value, validated.contracts, scope);
         }
@@ -858,6 +1248,19 @@ export class StratumEngine {
                     bg.status = response.status;
                     return;
                 }
+                // R2-11: bg.cancelRequested above is IN-MEMORY, and a second process cannot set it.
+                // Without this a bg run cancelled cross-process settles durably while flowBgPoll
+                // reports `running` forever — the two halves disagreeing is exactly the hazard
+                // rehydrateBgFlows exists to prevent across restarts.
+                // Deliberately store.load, NOT loadRun: a bg-driven run is PINNED by flowRunBg, so
+                // loadRun would hand back this driver's own in-memory object and could never observe
+                // a settle performed anywhere else. The durable record is the only source that can.
+                if (response.status === "cancelled" || (await this.store.load(runId).catch(() => undefined))?.status === "cancelled") {
+                    bg.cancelRequested = true;
+                    bg.status = "cancelled";
+                    bg.pendingGates = [];
+                    return;
+                }
                 // Pause on gates only when the run is QUIESCENT: no in-flight fanout can
                 // still settle behind the exited driver. Decided under the run lock so it
                 // cannot interleave inside settleFanout's locked flip+advance — otherwise a
@@ -897,7 +1300,68 @@ export class StratumEngine {
             bg.status = "failed";
         }
     }
+    /** Idempotent `initial` materialisation. Re-writes only when the source step's epoch
+     *  differs from the recorded one, so:
+     *   - a source that re-runs (which can only happen after a reset bumped its epoch)
+     *     replaces its now-stale derived value;
+     *   - a revise write, stamped with the initial source's CURRENT epoch, survives every
+     *     later advance until that source is itself reset.
+     *  `scope` MUST come from `carryScope` so `scope.carry === run.carry` (R2-1). */
+    materialiseCarry(run, scope) {
+        const declarations = scope.flow.carry;
+        if (declarations === undefined)
+            return { kind: "unchanged" };
+        const store = scope.carry;
+        if (store === undefined)
+            return { kind: "unchanged" };
+        const staged = [];
+        for (const [name, declaration] of Object.entries(declarations)) {
+            const reference = this.carryReference(declaration.initial);
+            // Object.hasOwn: a declared variable named `toString` must not read as materialised
+            // just because Object.prototype has one (R2-3).
+            const existing = Object.hasOwn(store, name) ? store[name] : undefined;
+            let provenance;
+            if (reference.kind === "step") {
+                const source = scope.steps[reference.stepId];
+                if (source?.status !== "succeeded")
+                    continue;
+                const sourceEpoch = source.epoch ?? 0;
+                if (existing !== undefined && existing.provenance.sourceEpoch === sourceEpoch)
+                    continue;
+                provenance = { kind: "initial", sourceStep: reference.stepId, sourceEpoch, at: now() };
+            }
+            else {
+                if (existing !== undefined)
+                    continue; // input-sourced: write once
+                provenance = { kind: "initial", at: now() };
+            }
+            const value = this.resolve(reference, scope);
+            // NEVER create an entry from an absent value (R1-3): a materialised-but-undefined
+            // carry would fail later at a confusing site, or hand `undefined` to a fanout.
+            if (value === undefined) {
+                return { kind: "failed", reason: `carry_initial_unresolved: carry ${JSON.stringify(name)} resolved to no value from ${declaration.initial}` };
+            }
+            staged.push({ name, value, provenance });
+        }
+        if (staged.length === 0)
+            return { kind: "unchanged" };
+        for (const write of staged) {
+            store[write.name] = { value: write.value, provenance: write.provenance };
+            this.event(run, "carry_updated", write.provenance.sourceStep, { name: write.name, reason: "initial", provenance: write.provenance });
+        }
+        return { kind: "written" };
+    }
     async advance(run, spec, contracts, scope = this.rootScope(run, spec)) {
+        // STRAT-LOOP-CARRY D7: the re-entry after every dispatching settle, and BEFORE the
+        // scope loop, so a ${carry} fanout sees the value in the same pass it activates.
+        // carryScope patches THIS scope object when it is the root one (R2-1) — building a
+        // detached root scope here would leave the live scope's carry undefined.
+        // `advance` does not persist on every path, so a write persists itself.
+        const materialised = this.materialiseCarry(run, this.carryScope(run, spec, scope));
+        if (materialised.kind === "failed")
+            return this.failScope(run, spec, contracts, scope, materialised.reason);
+        if (materialised.kind === "written")
+            await this.persist(run);
         await this.advanceScopeLoop(run, spec, contracts, scope);
         if (run.status !== "running")
             return this.response(run);
@@ -1028,6 +1492,12 @@ export class StratumEngine {
                     state.output = output;
                     state.attempts.push({ attempt: 1, at: now(), result: output });
                     this.event(run, "result", this.scopedId(scope, step.id), { attempt: 1, result: output });
+                    // R1-2: a later step in THIS pass may read the value. R2-5: never a partial write.
+                    const setCarry = this.materialiseCarry(run, this.carryScope(run, spec, scope));
+                    if (setCarry.kind === "failed") {
+                        await this.failScope(run, spec, contracts, scope, setCarry.reason);
+                        break;
+                    }
                     changed = true;
                     await this.persist(run);
                     continue;
@@ -1168,6 +1638,11 @@ export class StratumEngine {
                     state.output = parsed.data;
                     state.attempts.push({ attempt, at: now(), result: parsed.data });
                     this.event(run, "result", this.scopedId(scope, step.id), { attempt, result: parsed.data });
+                    const evalCarry = this.materialiseCarry(run, this.carryScope(run, spec, scope));
+                    if (evalCarry.kind === "failed") {
+                        await this.failScope(run, spec, contracts, scope, evalCarry.reason);
+                        break;
+                    }
                     await this.persist(run);
                     changed = true;
                     continue;
@@ -1223,12 +1698,16 @@ export class StratumEngine {
         const key = `${run.id}:${stepId}:${run.steps[stepId]?.fanoutEpoch ?? 0}`;
         if (this.scheduledFanouts.has(key))
             return;
-        this.scheduledFanouts.add(key);
         // Pin SYNCHRONOUSLY with the scheduler's own run object: from here until
         // release, loadRun hands this exact instance to every entry point, so an
         // independent stepDone proceeds during a slow fanout and mutates the same
         // instance — never a divergent disk copy, never blocked behind the batch.
+        //
+        // The pin comes BEFORE the key is marked scheduled (F2). Marked first, a failing lease
+        // write left the key set with no execution behind it, and the epoch-keyed guard above then
+        // refused to schedule the fanout ever again — the step simply never ran.
         this.retainRun(run.id, run);
+        this.scheduledFanouts.add(key);
         const scheduledFanout = run.steps[stepId]?.fanout;
         queueMicrotask(() => {
             void this.executeFanout(run, stepId).catch(async (error) => {
@@ -1467,148 +1946,212 @@ export class StratumEngine {
     async executeFanoutItem(run, spec, contracts, flow, step, state, item, value, fanoutRef) {
         if (!step.fanout)
             throw new Error("fanout missing after validation");
+        const fanout = step.fanout;
         // A revise can invalidate this fanout at any await point; once stale, the
         // item belongs to a dead epoch — stop recording into it (already-reserved
-        // dispatch costs stay in the flow ledger: they were really spent).
-        const stale = () => run.cancelRequested === true || state.fanout !== fanoutRef;
+        // dispatch costs stay in the flow ledger: they were really spent). A cancel
+        // is the other way in: the settle sets both `cancelRequested` and `status`.
+        const stale = () => run.cancelRequested === true || run.status === "cancelled" || state.fanout !== fanoutRef;
+        // R2-2/R4-5: the connector await is the ONE thing outside the lock. Everything that
+        // ADMITS, ACCEPTS or RECORDS an attempt runs inside a locked transaction, so a cancel
+        // landing during the await is seen at the one point where its answer becomes durable.
+        const lock = (action) => this.withRunLock(run.id, action);
         item.status = "running";
         let cwd = run.workspaceRoot;
         try {
-            if (step.fanout.isolation === "worktree") {
-                if (!cwd)
-                    throw new Error("worktree fanout requires workspaceRoot");
-                const previousWorktree = item.worktree;
-                const directory = await mkdtemp(join(tmpdir(), `stratum-${run.id.slice(0, 8)}-${item.index}-`));
-                await rm(directory, { recursive: true, force: true });
-                await execFileAsync("git", ["-C", cwd, "worktree", "add", "--detach", directory, "HEAD"]);
-                if (previousWorktree && previousWorktree !== directory) {
-                    await this.teardownWorktree(cwd, previousWorktree);
-                }
-                item.worktree = directory;
-                cwd = directory;
+            if (fanout.isolation === "worktree") {
+                const prepared = await lock(async () => {
+                    if (stale())
+                        return undefined;
+                    if (!cwd)
+                        throw new Error("worktree fanout requires workspaceRoot");
+                    const previousWorktree = item.worktree;
+                    const directory = await mkdtemp(join(tmpdir(), `stratum-${run.id.slice(0, 8)}-${item.index}-`));
+                    await rm(directory, { recursive: true, force: true });
+                    await execFileAsync("git", ["-C", cwd, "worktree", "add", "--detach", directory, "HEAD"]);
+                    if (previousWorktree && previousWorktree !== directory) {
+                        await this.teardownWorktree(cwd, previousWorktree);
+                    }
+                    item.worktree = directory;
+                    return directory;
+                });
+                if (prepared === undefined)
+                    return;
+                cwd = prepared;
             }
             let previous = undefined;
             let finalStageSkipped = false;
-            for (const [stageIndex, stage] of step.fanout.steps.entries()) {
+            for (const [stageIndex, stage] of fanout.steps.entries()) {
                 if (stale())
                     return;
-                item.stage = stageIndex;
-                item.epoch = state.epoch ?? 0;
-                delete item.dispatchToken;
-                delete item.acceptedDispatchToken;
-                if (stage.when !== undefined) {
-                    const enabled = this.evaluateFanout(stage.when, run, value, previous, cwd);
-                    if (enabled !== true) {
-                        this.event(run, "fanout_item_skipped", step.id, { itemIndex: item.index, stage: stageIndex });
-                        if (stageIndex === step.fanout.steps.length - 1)
-                            finalStageSkipped = true;
-                        continue;
+                const gate = await lock(async () => {
+                    if (stale())
+                        return "abandon";
+                    item.stage = stageIndex;
+                    item.epoch = state.epoch ?? 0;
+                    delete item.dispatchToken;
+                    delete item.acceptedDispatchToken;
+                    if (stage.when !== undefined) {
+                        const enabled = this.evaluateFanout(stage.when, run, value, previous, cwd);
+                        if (enabled !== true) {
+                            this.event(run, "fanout_item_skipped", step.id, { itemIndex: item.index, stage: stageIndex });
+                            return "skip";
+                        }
                     }
+                    return "run";
+                });
+                if (gate === "abandon")
+                    return;
+                if (gate === "skip") {
+                    if (stageIndex === fanout.steps.length - 1)
+                        finalStageSkipped = true;
+                    continue;
                 }
                 let success = false;
                 let lastFailure;
                 const maximum = stage.attempts ?? step.attempts ?? 2;
                 for (let stageAttempt = 1; stageAttempt <= maximum; stageAttempt += 1) {
-                    const attempt = item.attempts.length + 1;
-                    let prompt;
-                    try {
-                        prompt = this.renderFanout(stage.do, run, value, previous);
-                    }
-                    catch (error) {
-                        lastFailure = { attempt, reason: message(error) };
-                        this.recordFanoutAttempt(run, step, item, stageIndex, attempt, false, "connector", lastFailure);
+                    const admission = await lock(async () => {
+                        if (stale())
+                            return { kind: "abandon" };
+                        const attempt = item.attempts.length + 1;
+                        const carried = lastFailure;
+                        let prompt;
+                        try {
+                            prompt = this.renderFanout(stage.do, run, value, previous);
+                        }
+                        catch (error) {
+                            lastFailure = { attempt, reason: message(error) };
+                            this.recordFanoutAttempt(run, step, item, stageIndex, attempt, false, "connector", lastFailure);
+                            return { kind: "continue" };
+                        }
+                        const reserve = this.debit(run, step, state, { dispatches: 1 }, "reserve");
+                        if (reserve) {
+                            lastFailure = { attempt, reason: `${reserve} budget exhausted` };
+                            this.recordFanoutAttempt(run, step, item, stageIndex, attempt, false, "budget", lastFailure);
+                            // Flow-ledger exhaustion is TERMINAL for the run — it must never be
+                            // absorbed as one failed item that a tolerant `require` outweighs.
+                            if (reserve === "flow")
+                                await this.terminalBudget(run, lastFailure);
+                            return { kind: "break" };
+                        }
+                        item.dispatchToken = randomUUID();
+                        this.event(run, "fanout_ledger_debit", step.id, { itemIndex: item.index, amount: { dispatches: 1 } });
+                        this.event(run, "fanout_item_dispatched", step.id, { itemIndex: item.index, stage: stageIndex, attempt });
+                        // Durable BEFORE the (possibly long) connector await: a restart or a
+                        // fresh poller must see the dispatched lifecycle event, not a
+                        // pending item — the event spine is restart-proof.
+                        await this.persist(run);
+                        return { kind: "dispatch", prompt, attempt, ...(carried ? { previousFailure: carried } : {}) };
+                    });
+                    if (admission.kind === "abandon")
+                        return;
+                    if (admission.kind === "continue")
                         continue;
-                    }
-                    const reserve = this.debit(run, step, state, { dispatches: 1 }, "reserve");
-                    if (reserve) {
-                        lastFailure = { attempt, reason: `${reserve} budget exhausted` };
-                        this.recordFanoutAttempt(run, step, item, stageIndex, attempt, false, "budget", lastFailure);
-                        // Flow-ledger exhaustion is TERMINAL for the run — it must never be
-                        // absorbed as one failed item that a tolerant `require` outweighs.
-                        if (reserve === "flow")
-                            await this.terminalBudget(run, lastFailure);
+                    if (admission.kind === "break")
                         break;
-                    }
-                    item.dispatchToken = randomUUID();
-                    this.event(run, "fanout_ledger_debit", step.id, { itemIndex: item.index, amount: { dispatches: 1 } });
-                    this.event(run, "fanout_item_dispatched", step.id, { itemIndex: item.index, stage: stageIndex, attempt });
-                    // Durable BEFORE the (possibly long) connector await: a restart or a
-                    // fresh poller must see the dispatched lifecycle event, not a
-                    // pending item — the event spine is restart-proof.
-                    await this.persist(run);
-                    let result;
+                    const { prompt, attempt } = admission;
                     const rawContract = stage.out !== undefined ? spec.contracts[stage.out] : undefined;
+                    // R4-5: capture, do not act. Neither arm touches the run — the failure path used to
+                    // call recordFanoutAttempt in a bare catch, recording an attempt against a run that
+                    // may already have been cancelled.
+                    let outcome;
                     try {
-                        result = await this.connector({
-                            agent: stage.agent ?? "claude", prompt, ...(cwd !== undefined ? { cwd } : {}), attempt,
-                            ...(lastFailure ? { previousFailure: lastFailure } : {}),
-                            ...(rawContract !== undefined ? { outSchema: rawContract } : {}),
-                            sandbox: step.fanout.isolation === "worktree" ? "workspace-write" : "read-only",
-                        });
+                        outcome = { ok: true, result: await this.connector({
+                                agent: stage.agent ?? "claude", prompt, ...(cwd !== undefined ? { cwd } : {}), attempt,
+                                ...(admission.previousFailure ? { previousFailure: admission.previousFailure } : {}),
+                                ...(rawContract !== undefined ? { outSchema: rawContract } : {}),
+                                sandbox: fanout.isolation === "worktree" ? "workspace-write" : "read-only",
+                            }) };
                     }
                     catch (error) {
-                        if (stale())
-                            return;
-                        lastFailure = { attempt, reason: message(error) };
-                        this.recordFanoutAttempt(run, step, item, stageIndex, attempt, false, "connector", lastFailure);
-                        continue;
+                        outcome = { ok: false, error };
                     }
-                    if (stale())
-                        return;
-                    const outcome = await this.settleFanoutAttempt(run, spec, contracts, step, state, item, value, previous, stageIndex, attempt, result, cwd);
-                    if (stale())
+                    const disposition = await lock(async () => {
+                        if (stale())
+                            return "abandon";
+                        if (!outcome.ok) {
+                            lastFailure = { attempt, reason: message(outcome.error) };
+                            this.recordFanoutAttempt(run, step, item, stageIndex, attempt, false, "connector", lastFailure);
+                            return "retry";
+                        }
+                        const settled = await this.settleFanoutAttempt(run, spec, contracts, step, state, item, value, previous, stageIndex, attempt, outcome.result, cwd);
+                        if (stale())
+                            return "abandon";
+                        if (!settled.success) {
+                            lastFailure = settled.failure;
+                            return "retry";
+                        }
+                        return "accepted";
+                    });
+                    if (disposition === "abandon")
                         return;
-                    if (!outcome.success) {
-                        lastFailure = outcome.failure;
+                    if (disposition === "retry")
                         continue;
-                    }
-                    previous = result.output;
+                    previous = outcome.ok ? outcome.result.output : undefined;
                     success = true;
                     break;
                 }
                 if (!success) {
-                    item.status = "failed";
-                    item.failure = lastFailure ?? { attempt: item.attempts.length + 1, reason: "fanout stage failed" };
-                    delete item.dispatchToken;
+                    const abandoned = await lock(async () => {
+                        if (stale())
+                            return true;
+                        item.status = "failed";
+                        item.failure = lastFailure ?? { attempt: item.attempts.length + 1, reason: "fanout stage failed" };
+                        delete item.dispatchToken;
+                        return false;
+                    });
+                    void abandoned;
                     return undefined;
                 }
             }
-            if (finalStageSkipped) {
-                // The fanout output element type is the LAST stage's contract; an item
-                // whose final stage was `when`-skipped has no such value — it is a
-                // skipped item (null in the output array), never a success `require`
-                // can count, and its partial worktree work is never merged.
-                item.status = "skipped";
+            await lock(async () => {
+                if (stale())
+                    return;
+                if (finalStageSkipped) {
+                    // The fanout output element type is the LAST stage's contract; an item
+                    // whose final stage was `when`-skipped has no such value — it is a
+                    // skipped item (null in the output array), never a success `require`
+                    // can count, and its partial worktree work is never merged.
+                    item.status = "skipped";
+                    delete item.dispatchToken;
+                    return;
+                }
+                if (item.worktree) {
+                    // Include newly-created files in the patch without staging their contents.
+                    // Persisted on the item BEFORE it turns succeeded, so a restart between
+                    // item completion and merge still has every patch.
+                    await execFileAsync("git", ["-C", item.worktree, "add", "-N", "."]);
+                    // Diff against HEAD so STAGED changes are captured too — an agent that
+                    // ran `git add` in its worktree must not have its work silently lost.
+                    // Node's default 1 MiB maxBuffer would fail any item touching a large
+                    // or binary file; 64 MiB bounds the patch without breaking real work.
+                    const patch = (await execFileAsync("git", ["-C", item.worktree, "diff", "--binary", "HEAD"], { maxBuffer: 64 * 1024 * 1024 })).stdout;
+                    if (patch)
+                        item.patch = patch;
+                }
+                item.output = previous;
+                item.status = "succeeded";
+                if (item.dispatchToken !== undefined)
+                    item.acceptedDispatchToken = item.dispatchToken;
                 delete item.dispatchToken;
-                return;
-            }
-            if (item.worktree) {
-                // Include newly-created files in the patch without staging their contents.
-                // Persisted on the item BEFORE it turns succeeded, so a restart between
-                // item completion and merge still has every patch.
-                await execFileAsync("git", ["-C", item.worktree, "add", "-N", "."]);
-                // Diff against HEAD so STAGED changes are captured too — an agent that
-                // ran `git add` in its worktree must not have its work silently lost.
-                // Node's default 1 MiB maxBuffer would fail any item touching a large
-                // or binary file; 64 MiB bounds the patch without breaking real work.
-                const patch = (await execFileAsync("git", ["-C", item.worktree, "diff", "--binary", "HEAD"], { maxBuffer: 64 * 1024 * 1024 })).stdout;
-                if (patch)
-                    item.patch = patch;
-            }
-            item.output = previous;
-            item.status = "succeeded";
-            if (item.dispatchToken !== undefined)
-                item.acceptedDispatchToken = item.dispatchToken;
-            delete item.dispatchToken;
+            });
         }
         finally {
-            if (run.cancelRequested === true)
-                delete item.dispatchToken;
-            if (item.worktree && run.workspaceRoot) {
-                await this.teardownWorktree(run.workspaceRoot, item.worktree);
-                delete item.worktree;
-            }
-            await this.persist(run);
+            await lock(async () => {
+                if (run.cancelRequested === true)
+                    delete item.dispatchToken;
+                // Worktree teardown still runs on the abandon path: a cancelled run must not leak
+                // worktrees just because it may not write.
+                if (item.worktree && run.workspaceRoot) {
+                    await this.teardownWorktree(run.workspaceRoot, item.worktree);
+                    delete item.worktree;
+                }
+                // R4-1/R4-4: the settle already wrote the final record — and on the same object,
+                // since the lease guarantees this process performed it. Nothing to add.
+                if (run.status !== "cancelled")
+                    await this.persist(run);
+            });
         }
     }
     async teardownWorktree(workspaceRoot, directory) {
@@ -2089,7 +2632,7 @@ export class StratumEngine {
     }
     dependencies(step) {
         const output = new Set(step.after ?? []);
-        for (const value of stringLeaves(step)) {
+        for (const { value } of stringLeaves(step)) {
             for (const extracted of extractReferences(value) ?? [])
                 if (extracted.reference.kind === "step")
                     output.add(extracted.reference.stepId);
@@ -2136,6 +2679,7 @@ export class StratumEngine {
             stage: item.stage,
             isFinalStage: item.stage === step.fanout.steps.length - 1,
             itemIndex: item.index,
+            item: values[item.index],
             generation: item.generation,
             contract: closure,
             contractDigest: closure === null ? null : digest(closure),
@@ -2253,7 +2797,19 @@ export class StratumEngine {
         return parse && !parse.success ? parse.error.message : parse ? undefined : "output contract missing";
     }
     rootScope(run, spec) {
-        return { input: run.input, steps: run.steps, flow: this.flowFor(run, spec), flowName: run.flowName };
+        return { input: run.input, steps: run.steps, carry: run.carry, flow: this.flowFor(run, spec), flowName: run.flowName };
+    }
+    /** The root scope carry is written through, sharing ONE object with the run so a write
+     *  made during this pass is visible to every later read through the LIVE scope (R2-1).
+     *  Null-prototype so an inherited name like `toString` can never masquerade as a
+     *  declared variable (R2-3); a reloaded run's plain object is guarded by Object.hasOwn. */
+    carryScope(run, spec, scope) {
+        const root = scope.parent === undefined ? scope : this.rootScope(run, spec);
+        if (root.flow.carry === undefined)
+            return root; // never persist an empty carry map
+        run.carry ??= Object.create(null);
+        root.carry = run.carry;
+        return root;
     }
     childScope(spec, parentStep, parentState) {
         if (parentStep.run === undefined || parentState.sub === undefined)
@@ -2436,11 +2992,32 @@ export class StratumEngine {
         await this.persist(run);
         return this.advance(run, spec, contracts, root);
     }
+    /** The single reference in a carry `initial` / `on_revise` value. Validation has
+     *  already proved the shape (CARRY_REF_INVALID), so a failure here is a bug. */
+    carryReference(value) {
+        const extracted = extractReferences(value);
+        const reference = extracted?.length === 1 && extracted[0].fullValue ? extracted[0].reference : undefined;
+        if (!reference)
+            throw new Error("invalid carry reference after validation");
+        return reference;
+    }
     resolve(reference, scope) {
         if (reference.kind === "input")
             return access(scope.input, reference.path);
         if (reference.kind === "step")
             return access(scope.steps[reference.stepId]?.output, reference.path);
+        if (reference.kind === "carry") {
+            // Object.hasOwn, never `?.[name]`: a persisted run reloads as a PLAIN object
+            // (state.ts JSON.parse), so a variable legitimately named `toString` or
+            // `constructor` would otherwise resolve to an inherited function (R2-3).
+            const store = scope.carry;
+            if (store === undefined || !Object.hasOwn(store, reference.name)) {
+                // A named, actionable failure replaces the generic "must resolve to an array"
+                // that `over` would otherwise produce two frames up (D1).
+                throw new Error(`carry variable ${JSON.stringify(reference.name)} is not materialised`);
+            }
+            return access(store[reference.name].value, reference.path);
+        }
         throw new Error("fanout references are outside P1 engine scope");
     }
     context(_run, scope) {
@@ -2454,6 +3031,15 @@ export class StratumEngine {
     }
     assertExternalMutationAllowed(runId, operation) {
         const bg = this.bgFlows.get(runId);
+        // R4-6: commit and revert take this pre-check BEFORE the lock, and "cancelled" is not in
+        // the terminal allowlist below — so a cancelled BG run would report `is background-driven`
+        // while a cancelled FOREGROUND run reported `flow_cancelled`. Two errors for one
+        // condition, neither of them true. Let a cancelled run through to
+        // assertCancelledCheckpointRefusal, which runs inside the lock and is the truth.
+        // stepDone and resume keep refusing here: both have their own cancelled refusal further in,
+        // and a bg-driven run must not be externally pumped whatever its status.
+        if (bg?.status === "cancelled" && (operation === "commit" || operation === "revert"))
+            return;
         if (bg !== undefined && bg.status !== "completed" && bg.status !== "failed" && bg.status !== "budget_exhausted") {
             throw new Error(`run ${runId} is background-driven; external ${operation} is not permitted (poll via flow_bg_poll)`);
         }
@@ -2530,6 +3116,23 @@ export class StratumEngine {
     // it settles onto the restored state. Refuse both while a fanout is in flight (a fanout
     // step stays `running` from dispatch through settlement), the same quiescence the
     // detached driver already requires. bg-driven runs are covered by the ownership guard.
+    /** D5/R2-10. A cancelled run is terminal. `cancelRequested` is a CHECKPOINT_FIELD, so a
+     *  revert could otherwise restore `cancelRequested: false` and resurrect a run whose agents
+     *  have already been killed; and a commit would snapshot a half-torn-down run as if it were
+     *  a recovery point. Round 0's carve-out for commit ("snapshotting a terminal run is the
+     *  documented recovery case") does not survive: that case is a run that failed on its own,
+     *  whose state is coherent — a cancelled run's is mid-teardown by construction.
+     *
+     *  R4-6: this runs INSIDE the lock, and it is the first thing that can report on a
+     *  cancelled run. assertExternalMutationAllowed's terminal allowlist does not contain
+     *  "cancelled", so a cancelled BG run would otherwise report `is background-driven` while a
+     *  cancelled foreground run reported `flow_cancelled` — two errors for one condition,
+     *  neither of them true. */
+    assertCancelledCheckpointRefusal(run, operation) {
+        if (run.status !== "cancelled" && run.cancelRequested !== true)
+            return;
+        throw new CheckpointOperationError("flow_cancelled", `Flow '${run.id}' is cancelled; ${operation} is not permitted`);
+    }
     assertNoForegroundFanout(run, operation) {
         if (run.status !== "running")
             return;
@@ -2581,6 +3184,32 @@ export class StratumEngine {
         this.emitFlowTerminal(run);
         return this.response(run);
     }
+    /** D3. `failure` stays UNSET: the status is honest, so inventing a FailureContext would put
+     *  a lie in the audit trail (and requiredFailure would invent a worse one).
+     *
+     *  Cancel is exempt from both mutation guards, DELIBERATELY: not assertNoForegroundFanout —
+     *  cancel exists precisely to break the stuck consumer-fanout lifecycle that guard protects
+     *  — and not assertExternalMutationAllowed, because a bg-driven run is cancellable from
+     *  outside. Do not "fix" the omission; it reintroduces the wedge this feature exists to
+     *  break. Assumes the run lock is held: every caller is inside a locked section. */
+    async terminalCancel(run, reason) {
+        run.cancelRequested = true;
+        const burned = burnIssuances(run);
+        run.status = "cancelled";
+        this.event(run, "flow_cancelled", undefined, { by: "fg", ...(reason !== undefined ? { reason } : {}), burned });
+        // R4-1: the ONE sanctioned write of a cancelled record.
+        await this.persistTerminalCancel(run);
+        this.emitFlowTerminal(run);
+        // A bg run cancelled through the fg surface must report consistently to flowBgPoll — but
+        // only in THIS process; another engine's bgFlows map is reached by driveBg's own check.
+        const bg = this.bgFlows.get(run.id);
+        if (bg) {
+            bg.cancelRequested = true;
+            bg.status = "cancelled";
+            bg.pendingGates = [];
+        }
+        return this.response(run);
+    }
     async terminalFailure(run, failure) {
         run.status = "failed";
         run.failure = failure;
@@ -2628,6 +3257,11 @@ export class StratumEngine {
             return { status: "completed", runId: run.id, output: run.output, ledger };
         if (run.status === "budget_exhausted")
             return { status: "budget_exhausted", runId: run.id, failure: requiredFailure(run), ledger };
+        // Above the failed fallthrough: requiredFailure would otherwise INVENT
+        // {attempt: 0, reason: "run failed without context"} and report a cancelled run as a
+        // failure with a fabricated reason (C15).
+        if (run.status === "cancelled")
+            return { status: "cancelled", runId: run.id, ledger };
         return { status: "failed", runId: run.id, failure: requiredFailure(run), ledger };
     }
     withRevisionDigest(response, run) {
@@ -2642,7 +3276,30 @@ export class StratumEngine {
     event(run, type, stepId, detail) {
         run.events.push({ at: now(), type, ...(stepId ? { stepId } : {}), ...(detail !== undefined ? { detail } : {}) });
     }
-    persist(run) {
+    /** Every persist happens inside a locked section. A persist outside one is a lost update
+     *  waiting to happen, and the three write paths this assertion caught (plan's initial
+     *  persist, the engine-fanout admission writes, and `stratum learn egress`) are why it is a
+     *  check rather than a comment. */
+    assertLockHeld(runId) {
+        if (this.heldLocks.has(runId))
+            return;
+        const detail = `run ${runId}: persist outside a locked section`;
+        if (process.env.NODE_ENV === "production") {
+            process.stderr.write(`stratum: ${detail}\n`);
+            return;
+        }
+        throw new Error(detail);
+    }
+    /** The single sanctioned save of a cancelled run: terminalCancel's own. */
+    persistTerminalCancel(run) { return this.persist(run, true); }
+    persist(run, sanctioned = false) {
+        this.assertLockHeld(run.id);
+        // R4-1: after a settle the durable record is final. Refusing is right; refusing SILENTLY
+        // is not — a swallowed usageReport or receipt update is indistinguishable from one that
+        // succeeded, so every unsanctioned caller reaching here surfaces instead of vanishing.
+        if (run.status === "cancelled" && !sanctioned) {
+            throw Object.assign(new Error(`run ${run.id} is cancelled; no further writes are accepted`), { code: "PERSIST_ON_CANCELLED_RUN" });
+        }
         const previous = this.persistLocks.get(run.id) ?? Promise.resolve();
         const result = previous
             .then(() => this.store.save(run))
@@ -2674,22 +3331,27 @@ function access(value, path) {
     }
     return current;
 }
-function stringLeaves(step) {
+export function stringLeaves(step) {
     const values = [];
-    const collect = (value) => {
+    const collect = (value, expression = false) => {
         if (typeof value === "string")
-            values.push(value);
+            values.push({ value, expression });
         else if (Array.isArray(value))
-            value.forEach(collect);
+            value.forEach((entry) => collect(entry, expression));
         else if (typeof value === "object" && value !== null)
-            Object.values(value).forEach(collect);
+            Object.values(value).forEach((entry) => collect(entry, expression));
     };
     if (step.do !== undefined)
         collect(step.do);
     if (step.when !== undefined)
-        collect(step.when);
+        collect(step.when, true);
     if (step.set !== undefined)
-        collect(step.set);
+        collect(step.set, true);
+    if (step.iterate?.until !== undefined)
+        collect(step.iterate.until, true);
+    for (const predicate of step.ensure ?? [])
+        if ("expr" in predicate)
+            collect(predicate.expr, true);
     // The engine's dependency edges must mirror the validator's: subflow `with`
     // templates and fanout over/stage templates reference steps too — a fanout
     // over "${prep.output.items}" must wait for prep, not fail at resolve time.
@@ -2702,7 +3364,10 @@ function stringLeaves(step) {
         for (const stage of step.fanout.steps) {
             collect(stage.do);
             if (stage.when !== undefined)
-                collect(stage.when);
+                collect(stage.when, true);
+            for (const predicate of stage.ensure ?? [])
+                if ("expr" in predicate)
+                    collect(predicate.expr, true);
         }
     }
     return values;