@revisium/orchestrator 0.1.0 → 0.2.0-alpha.1

package/dist/pipeline/data-driven-task.workflow.js

@@ -1,33 +1,4 @@
-/**
- * data-driven-task.workflow.ts — the DBOS effect-adapter for a DATA-DRIVEN pipeline (plan 0015 §10).
- *
- * Runs the pure `pipeline-core` graph on REAL DBOS. As of slice 3 this is the SOLE pipeline engine:
- * selection routes EVERY pipeline here (TaskControlPlaneApiService), executing the state-machine
- * template pinned for the run; a pipeline without a valid template FAILS LOUD at selection. The old
- * hardcoded `developTask` workflow + its role→phase classifiers were removed.
- *
- * INVARIANT: `src/pipeline/*` imports NO `@dbos-inc/dbos-sdk` (M1 — DBOS sealed). All DBOS interaction
- * goes through the generic DbosService verbs (registerStep/registerWorkflow/awaitDecision) injected as
- * deps. This file is registered via the engine seam in PipelineService.
- *
- * GENERIC ENGINE: zero role-ids / pipeline shapes here. `roleRef`/`scriptRef` are opaque capability
- * handles resolved against the run's route bindings + the existing runner machinery (§1/§10).
- *
- * The loop (§10):
- *   { state, decision } = core.step(template, state, lastResult)
- *     → execute `decision` as a durable DBOS step (runner / human gate / integrator / fork)
- *     → validate result vs the node's `resultSchema` + redact at this boundary (reuse runStep/append)
- *     → record the result as the next `lastResult`
- *   → repeat until `decision.type === 'complete'` → finish the run.
- *
- * RECOVERY: DBOS replays the workflow body; `core.step` is deterministic and every effect is a durable
- * memoized DBOS step, so a replay re-derives the identical Decision sequence and consumes the recorded
- * step results — no live race, no duplicate effects (deterministic ids + ROW_CONFLICT no-op).
- *
- * C1 architecture: the body is an extracted DBOS-free builder (`makeDataDrivenTask`) registered via the
- * engine seam, so tests exercise the SAME production logic directly with a plain step fn.
- */
-import { step as coreStep, initialState, validateTemplate, InterpretError, } from '../pipeline-core/index.js';
+import { step as coreStep, initialState, validateTemplate, InterpretError, selectJoinWinner, reduceJoinVerdict, } from '../pipeline-core/index.js';
 import { runnerNeedsLivePreflight, runnerUsesRealIntegrator } from './route-contract.js';
 import { redactEventPayload } from '../run/append-event.js';
 import { redactSecrets } from '../control-plane/inbox.js';
@@ -35,7 +6,7 @@ import { fnv1a64Hex } from '../control-plane/steps.js';
 import { normalizeIssueRef } from '../run/issue-ref.js';
 import { RUNNER_IDLE_TIMEOUT_KIND, RUNNER_WALL_CLOCK_LIMIT_KIND, } from '../worker/process-executor.js';
 export const RUN_PROGRESS_EVENT_KEY = 'run-progress';
-const MAX_STEPS = 1_000; // a VALID template terminates; guards a data/loop authoring mistake at runtime.
+const MAX_STEPS = 1_000;
 const DEFAULT_RUNNER_TRANSIENT_MAX_ATTEMPTS = 2;
 const DEFAULT_RUNNER_TRANSIENT_RETRY_BACKOFF_MS = 2_000;
 function readPositiveIntegerEnv(env, key, fallback) {
@@ -86,17 +57,6 @@ function optionalTiming(timing) {
 function optionalFailureKind(failureKind) {
     return failureKind === undefined ? {} : { failureKind };
 }
-/**
- * Reserved engine error codes (matched only by a node's `catch`, §3/§6).
- *
- * A built-in script (the integrator) has TWO distinct failure modes the routing data discriminates:
- *  - `revo.ScriptBlocked` — the script needs a human (nothing-to-integrate, ambiguous PRs, a refused
- *    pinned identity, a non-JSON `pr view`). NOT a crash; a `catch` routes it to a `blocked` terminal,
- *    and the adapter surfaces the human-readable lesson on a `pipeline_blocked` event (parity with the
- *    old engine's `blockPipeline({ reason:'integrate' })`).
- *  - `revo.ScriptFailed` — the script THREW (a gh/push error). A `catch` routes it to a `failed`
- *    terminal (parity with the old engine's top-level catch → failRun).
- */
 const REVO_SCRIPT_FAILED = 'revo.ScriptFailed';
 const REVO_SCRIPT_BLOCKED = 'revo.ScriptBlocked';
 const REVO_RESULT_INVALID = 'revo.ResultInvalid';
@@ -126,14 +86,9 @@ function pipelineBlockedPayload(reason, lesson, retry) {
         return { reason, lesson };
     return { ...retry };
 }
-/** Per-node execution stepKey: the bare nodeId on the first entry (stable ids for existing tests), an
- *  ordinal-suffixed key on loop re-entries so attempts/events/outputs are distinct per iteration (0016
- *  §4.1 — fixes the latent 0015 stepKey-reuse collision). */
 function stepKeyFor(nodeId, ordinal) {
     return ordinal <= 1 ? nodeId : `${nodeId}#${ordinal}`;
 }
-/** Next per-(run,node) execution ordinal (1-based). Deterministic on DBOS replay: the runBody loop
- *  re-runs identically (coreStep is pure, effects are memoized), so the accumulator is rebuilt 1:1. */
 function nextOrdinal(byNode, nodeId) {
     const n = (byNode.get(nodeId) ?? 0) + 1;
     byNode.set(nodeId, n);
@@ -181,7 +136,7 @@ function changeWithRunIssueRef(change, issueRef) {
     return normalized;
 }
 function producedChangeFromInputs(inputs) {
-    for (const key of ['reviewChange', 'ciChange', 'reworkChange', 'developerChange', 'change']) {
+    for (const key of ['reviewChange', 'ciChange', 'stuckReworkChange', 'reworkChange', 'developerChange', 'change']) {
         const artifact = producedChangeArtifact(inputs[key]);
         if (artifact)
             return artifact;
@@ -239,11 +194,6 @@ function transientRunnerFailure(result) {
         ...optionalTiming(output.timing),
     };
 }
-/**
- * Classify a transient runner failure into a SHORT, machine-readable kind so a consumer can tell
- * timeout / rate-limit / crash apart from `pipeline_blocked.payload.reason` alone (the full detail
- * stays in the lesson). Checked timeout-first so a "exited 1 (timeout)" message reads as a timeout.
- */
 function transientKind(reason) {
     if (/exceeded\s*\d+\s*ms|timed?\s*out|\btimeout\b/i.test(reason))
         return 'timeout';
@@ -261,7 +211,6 @@ function isLegacyRetryableCrashReason(reason) {
     return /\b(signal|crash(?:ed)?|killed|ECONNRESET|ETIMEDOUT|EAI_AGAIN|socket hang up|ENOMEM|EAGAIN)\b/i
         .test(reason);
 }
-/** Extract the DOMAIN verdict from the only supported source: top-level AttemptResult.verdict. */
 function domainVerdictOf(result) {
     if (typeof result.verdict === 'string' && result.verdict.trim().length > 0) {
         return result.verdict.trim().toLowerCase();
@@ -280,12 +229,6 @@ function resultVerdictProblem(template, node, result) {
     }
     return undefined;
 }
-/**
- * Validate a recorded result against a node's `resultSchema` at the ADAPTER boundary (§10). MVP
- * contract (resolves §14 Q3 — resultSchema is a DATA handle, validated structurally here): a declared
- * `resultSchema` requires a non-empty object/string output. Token redaction already happens inside
- * `runStep`/`appendEvent`; this guards a malformed effect result → `revo.ResultInvalid` (§6 precedence).
- */
 function resultSatisfiesSchema(node, result) {
     if (!('resultSchema' in node) || !node.resultSchema)
         return true;
@@ -306,28 +249,23 @@ function progressCursor(state, lastResult) {
         ...(lastResult ? { lastResult } : {}),
     };
 }
-/**
- * Map an approve/reject human decision onto a DOMAIN verdict the template's gate `outcomes` can route.
- * The core never sees approve/reject — it routes on a domain label (§8). Approve → the first declared
- * outcome (the "proceed" label by template convention, e.g. `approved`); reject → fail-closed to a
- * NON-first outcome if one exists (e.g. `changes_requested`), else undefined so the gate's `default`
- * (typically a `blocked` terminal) fires. This keeps gate semantics 100% in the routing data (§6/§8).
- */
 function gateVerdict(decision, outcomes) {
+    if (decision.outcome)
+        return outcomes.includes(decision.outcome) ? decision.outcome : undefined;
     if (decision.decision === 'approve')
         return outcomes[0];
-    // reject: prefer a declared "rework/changes" outcome; else let the default branch route (blocked).
     return outcomes.length > 1 ? outcomes.at(-1) : undefined;
 }
-/**
- * Stable gate topic from a node's reason. The topic is the DBOS recv channel AND part of the gate
- * inbox id (`runId|topic`), so DISTINCT gates in one pipeline MUST map to DISTINCT topics — otherwise
- * a second gate's `recv` collides with the first's already-consumed message and the run hangs (plan
- * 0018: the `review-question` gate would otherwise reuse the `plan` topic of the plan gate).
- *   merge-review   → 'merge'
- *   review-question→ 'question'
- *   (anything else)→ 'plan'  (the plan-review gate)
- */
+function gateResolutionOutput(decision, verdict, fallbackInboxId) {
+    return {
+        outcome: decision.outcome ?? verdict ?? decision.decision,
+        ...(decision.note !== undefined ? { note: decision.note } : {}),
+        resolvedBy: decision.resolvedBy ?? '',
+        resolvedAt: decision.resolvedAt ?? '',
+        inboxId: decision.inboxId ?? fallbackInboxId,
+        ...(decision.decision ? { decision: decision.decision } : {}),
+    };
+}
 function gateTopicFor(reason) {
     if (/merge/i.test(reason))
         return 'merge';
@@ -335,15 +273,8 @@ function gateTopicFor(reason) {
         return 'question';
     return 'plan';
 }
-// D3 — enrich the gate inbox row with the artifact under review + the reviewer verdict, inline, so an
-// approver decides without digging the agent log. `pushInbox` has no size cap (unlike run-outputs'
-// PAYLOAD_MAX), so the artifact is budgeted HERE: over-budget → a head preview + a payload_ref locator,
-// never the full payload. The inbox id is keyed by runId|gateKey only, so a larger context does not
-// change it → pushInbox stays idempotent on replay. The payload is also secret/token redacted at this
-// build site (pushInbox only masks secret-NAMED keys, not token SHAPES in free-text) — see gateArtifactView.
 export const GATE_ARTIFACT_MAX = 16_000;
 export const GATE_PREVIEW_CHARS = 4_000;
-/** Latest (or pinned-ordinal) output row for a gate ref, or undefined if the producer has not run. */
 function resolveGateRow(ref, outputsByNode) {
     if (!ref)
         return undefined;
@@ -352,20 +283,12 @@ function resolveGateRow(ref, outputsByNode) {
         return undefined;
     if (typeof ref.iteration === 'number')
         return produced.find((o) => o.ordinal === ref.iteration);
-    return produced[produced.length - 1]; // 'latest' (and 'all' → the most recent for an inline view)
+    return produced[produced.length - 1];
 }
-/**
- * Inline artifact view with the 16KB budget. Secrets + token shapes are scrubbed BEFORE inlining or
- * previewing — mirroring run-outputs.ts (the sibling persist boundary): pushInbox only masks
- * secret-NAMED keys, so a token shape (`ghp_…`) in a free-text field (e.g. pollPr's prFeedback) would
- * otherwise persist verbatim. Over-budget → a head preview (of the redacted serialization) + an
- * `attempt:` locator (the full artifact is recoverable from that attempt's agent log).
- */
 function gateArtifactView(row, as) {
     const base = { nodeId: row.nodeId, name: as ?? row.name, schemaRef: row.schemaRef };
     const safe = redactEventPayload(redactSecrets(row.payload) ?? null);
     const serialized = JSON.stringify(safe ?? null);
-    // Budget on BYTES (not UTF-16 length) so a multi-byte payload can't slip past the cap.
     if (Buffer.byteLength(serialized, 'utf8') <= GATE_ARTIFACT_MAX)
         return { ...base, payload: safe };
     return {
@@ -375,12 +298,6 @@ function gateArtifactView(row, as) {
         payloadRef: `attempt:${row.attemptId ?? ''}`,
     };
 }
-/**
- * Build the enriched gate inbox summary from the workflow-local outputs (replay-safe — rebuilt
- * identically, 0016 §6). `verdictFrom` resolves a node's verdict output; when it is NOT specified, the
- * verdict defaults to the routing verdict that opened the gate (`lastVerdict`). Routing is unaffected —
- * purely informational.
- */
 export function buildGateSummary(decision, outputsByNode, lastVerdict) {
     const summary = { nodeId: decision.nodeId, outcomes: decision.outcomes };
     const artRow = resolveGateRow(decision.gatedArtifact, outputsByNode);
@@ -389,22 +306,12 @@ export function buildGateSummary(decision, outputsByNode, lastVerdict) {
     const verdictRow = resolveGateRow(decision.verdictFrom, outputsByNode);
     if (verdictRow)
         summary.reviewerVerdict = gateArtifactView(verdictRow);
-    // Only fall back to the routing verdict when no verdictFrom was REQUESTED — a specified-but-unresolved
-    // verdictFrom must not silently present the routing verdict as if it came from that source.
     else if (!decision.verdictFrom && lastVerdict)
         summary.reviewerVerdict = { verdict: lastVerdict };
     return summary;
 }
-/**
- * makeDataDrivenTask — DBOS-free factory for the dataDrivenTask async function (C1).
- *
- * Receives the (DBOS-wrapped in prod, plain in tests) `runStepFn` so the body is IDENTICAL across
- * production and tests. Returns a plain async function with the workflow signature.
- */
 export function makeDataDrivenTask(runStepFn, deps) {
     const { appendEvent, appendRunOutput, awaitHuman, completeRun, failRun, blockRun, loadRunTaskContext, integrateFn, runStub, confirmMergeFn, runConfirmStub, pollPrFn, runPollStub, respondThreadsFn, runRespondStub, captureChangeFn, preflightFn, createWorktreeFn, releaseWorktreeFn } = deps;
-    /** Resolve a node's `consumes` from the workflow-local output accumulator — NOT live Revisium reads
-     *  (0016 §6 / consensus M4: a live read on replay can see rows written past the replay point). */
     function resolveConsumes(node, outputsByNode) {
         const refs = 'consumes' in node ? (node.consumes ?? []) : [];
         const inputs = {};
@@ -435,8 +342,6 @@ export function makeDataDrivenTask(runStepFn, deps) {
         }
         return { inputs };
     }
-    /** Record a node's produced output to the workflow-local accumulator + Revisium (when `produces`). */
-    // (gate-summary helpers live at module scope below — they are pure over outputsByNode.)
     async function recordOutput(runId, node, ordinal, attemptId, output, outputsByNode) {
         if (!('produces' in node) || !node.produces)
             return;
@@ -459,9 +364,6 @@ export function makeDataDrivenTask(runStepFn, deps) {
             return await runBody(runId, opts);
         }
         catch (err) {
-            // TERMINAL failure: mark the Revisium run-row `failed` (idempotent, event-first) before
-            // re-throwing so DBOS still records the workflow ERROR (progress truth) and the run-row stops
-            // lying. The run's terminal-failure surfacing contract (0008 #2).
             const reason = err instanceof Error ? err.message : String(err);
             try {
                 await failRun(runId, reason);
@@ -474,64 +376,25 @@ export function makeDataDrivenTask(runStepFn, deps) {
     };
     async function runBody(runId, opts) {
         const { route, template } = opts;
-        // Defense-in-depth: the pinned template is validated at the boundary (§9 — pipeline-core is the
-        // authoritative validator even though selection already validated it). A broken pin fails the run.
         const diagnostics = validateTemplate(template).filter((d) => d.severity === 'error');
         if (diagnostics.length > 0) {
             throw new Error(`PINNED_TEMPLATE_INVALID: ${template.pipelineId} — ${diagnostics.map((d) => d.code).join(', ')}`);
         }
         const { taskId, title, base, issueRef } = await loadRunTaskContext(runId);
-        // B5/B7 — live preflight: one memoized DBOS step, evaluated exactly once BEFORE the graph runs.
-        // Skipped entirely when every selected binding resolves to a stub/script runner (mirrors the old
-        // engine's gate). A `needsHuman` preflight blocks the run (clean/base invariant unmet) and surfaces
-        // the lesson — the run never enters the graph. This is an engine-level guard (infrastructure), not a
-        // template node: it is cross-cutting and identical for every pinned pipeline (zero role-ids/shapes).
         const live = route.roleBindings.some((b) => runnerNeedsLivePreflight(b.resolvedRunnerId));
         if (live) {
-            // Preflight runs against the BASE checkout (resolveTaskCwd), BEFORE the worktree exists — its
-            // fetch + clean/base-availability checks protect the user's base repo. Ordering is load-bearing.
             const pf = await preflightFn(taskId, base);
             if ('needsHuman' in pf) {
                 return await blockWithLesson(runId, taskId, 'preflight', pf.lesson, 0);
             }
         }
-        // Per-run worktree (plan 0017): create AFTER a passing preflight and BEFORE any live effect, so all
-        // repo-touching steps (developer/rework + integrator) resolve to the isolated worktree (keyed by
-        // runId) — never the shared base checkout. Skipped for non-live runs. The `finally` releases it at a
-        // SUCCEEDED terminal (the PR is merged via confirmMerge → branch is in base → worktree disposable) and
-        // on a throw (failure); it KEEPS the worktree on a `blocked` terminal (confirmMerge blocks when the PR
-        // isn't merged yet — the tree must survive for rework / a manual merge; reclaimed by cleanup_worktree
-        // + the host-start sweep). It does NOT run while parked at a gate (awaitHuman suspends the live
-        // workflow via `recv`, so runBody never returns there). Create is INSIDE the try so the release also
-        // cleans up a create that partially built the worktree before throwing (codex/CodeRabbit).
-        let result;
-        try {
-            if (live) {
-                await createWorktreeFn(runId, taskId, title, base, issueRef);
-            }
-            result = await runGraph(runId, opts, taskId, title, base, issueRef, live);
-            return result;
-        }
-        finally {
-            if (live && result?.status !== 'blocked') {
-                try {
-                    await releaseWorktreeFn(runId, taskId);
-                }
-                catch (releaseErr) {
-                    console.warn(`[data-driven] worktree release for ${runId} failed (orphan; pruned later): ${String(releaseErr)}`);
-                }
-            }
+        if (live) {
+            await createWorktreeFn(runId, taskId, title, base, issueRef);
         }
+        return runGraph(runId, opts, taskId, title, base, issueRef, live);
     }
-    /** The pipeline-core interpretation loop, extracted so the worktree `finally` in runBody wraps it. */
     async function runGraph(runId, opts, taskId, title, base, issueRef, live) {
         const { route, template, runnerRetryPolicy } = opts;
-        // Capability resolution map (GENERIC — no role-ids in the engine): roleRef/scriptRef → route binding.
-        // The route's bindings are authoritative for runner dispatch (and durable on recovery via the DBOS
-        // workflow input). A `role:<id>` handle resolves to the binding whose roleId matches `<id>`. A
-        // `script:<id>` handle likewise resolves by roleId; additionally the canonical `script:integrator`
-        // handle resolves to whichever binding's RESOLVED runner mechanically performs the merge (runner-
-        // wins, D7) so the integrator script dispatches real-vs-stub exactly like the hardcoded path.
         const bindingByRef = new Map();
         for (const binding of route.roleBindings) {
             bindingByRef.set(`role:${binding.roleId}`, binding);
@@ -547,9 +410,6 @@ export function makeDataDrivenTask(runStepFn, deps) {
         let lastVerdict = '';
         let lastFailureReason = '';
         let stepCount = 0;
-        // Workflow-local dataflow state (0016 §4.1/§6): per-node execution ordinals + produced outputs.
-        // Both are rebuilt deterministically on DBOS replay (the loop re-runs identically); the adapter
-        // hydrates consumers from `outputsByNode`, never from a live Revisium read.
         const effectOrdinalByNode = new Map();
         const outputsByNode = new Map();
         for (let i = 0; i < MAX_STEPS; i++) {
@@ -560,21 +420,19 @@ export function makeDataDrivenTask(runStepFn, deps) {
                 return await finish(runId, decision.status, lastVerdict, stepCount, lastFailureReason);
             }
             const eff = await applyDecision(decision, {
-                runId, template, bindingByRef, executionProfile, taskId, title, base, issueRef,
+                runId, template, state, bindingByRef, executionProfile, taskId, title, base, issueRef,
                 effectOrdinalByNode, outputsByNode, runnerRetryPolicy,
                 live,
-                // The verdict from the PRIOR effect (the reviewer/poller that routed into this node). At an
-                // awaitGate this is the routing verdict that opened the gate → D3's default reviewerVerdict.
                 lastVerdict,
             });
             stepCount += eff.stepDelta;
-            // Engine-level short-circuit (agent needsHuman, classified by invokeRole): block the run at a
-            // visible, lesson-bearing terminal WITHOUT routing through the core's onFailure:'abort' machinery
-            // (which would fail the run). blockWithLesson emits the single `pipeline_blocked` (token-redacted
-            // at the persist boundary) + marks the run-row blocked — the same guard the preflight block uses.
             if (eff.terminal) {
                 return await blockWithLesson(runId, taskId, eff.terminal.reason, eff.terminal.lesson, stepCount, eff.terminal.retry);
             }
+            if (eff.stateOverride) {
+                state = eff.stateOverride;
+                await deps.setProgress?.(runId, progressCursor(state, eff.lastResult));
+            }
             lastResult = eff.lastResult;
             if (eff.lastVerdict !== undefined)
                 lastVerdict = eff.lastVerdict;
@@ -582,11 +440,91 @@ export function makeDataDrivenTask(runStepFn, deps) {
         }
         throw new InterpretError(`data-driven ${template.pipelineId} did not terminate within ${MAX_STEPS} steps (template loop bug)`);
     }
-    /**
-     * Execute ONE non-terminal Decision as a durable effect and return the next `lastResult`/`lastVerdict`
-     * + the step-count delta. Extracted from the `runBody` loop so each is small + independently testable
-     * (the loop just threads the result; this is the per-kind dispatch).
-     */
+    function branchTemplateForJoin(template, joinId) {
+        const join = resolveNode(template, joinId);
+        if (join.kind !== 'join')
+            throw new InterpretError(`fork target ${joinId} is not a join (${join.kind})`);
+        return {
+            ...template,
+            nodes: {
+                ...template.nodes,
+                [joinId]: { id: joinId, kind: 'terminal', status: 'succeeded' },
+            },
+        };
+    }
+    async function executeForkBranches(decision, ctx) {
+        const branchTemplate = branchTemplateForJoin(ctx.template, decision.joinId);
+        const results = await Promise.all(decision.branches.map((branch, idx) => executeForkBranch(branchTemplate, decision, branch, idx + 1, ctx)));
+        const stepDelta = results.reduce((sum, result) => sum + result.stepDelta, 0);
+        const terminal = results.find((result) => result.terminal)?.terminal;
+        if (terminal)
+            return { lastResult: undefined, terminal, stepDelta };
+        const arrivals = results.flatMap((result) => result.arrival ? [result.arrival] : []);
+        if (arrivals.length !== decision.branches.length) {
+            throw new InterpretError(`fork ${decision.nodeId} expected ${decision.branches.length} branch arrivals, got ${arrivals.length}`);
+        }
+        const lastResult = { joinArrivals: arrivals };
+        const winner = selectJoinWinner(decision.mode, arrivals, decision.joinId);
+        const join = resolveNode(ctx.template, decision.joinId);
+        if (join.kind !== 'join')
+            throw new InterpretError(`fork target ${decision.joinId} is not a join (${join.kind})`);
+        const verdict = reduceJoinVerdict(join, arrivals, winner);
+        return {
+            lastResult,
+            ...(verdict !== undefined ? { lastVerdict: verdict } : {}),
+            stateOverride: {
+                ...ctx.state,
+                activeNodeIds: new Set([decision.joinId]),
+                status: 'running',
+                lastResult,
+            },
+            stepDelta,
+        };
+    }
+    async function executeForkBranch(branchTemplate, decision, branch, seq, ctx) {
+        let state = {
+            ...ctx.state,
+            activeNodeIds: new Set([branch.entry]),
+            scopedCounters: { ...ctx.state.scopedCounters },
+            status: 'running',
+            lastResult: undefined,
+        };
+        let lastResult;
+        let lastVerdict = '';
+        let stepDelta = 0;
+        for (let i = 0; i < MAX_STEPS; i++) {
+            const next = coreStep(branchTemplate, state, lastResult);
+            state = next.state;
+            if (next.decision.type === 'complete') {
+                if (next.decision.status !== 'succeeded') {
+                    throw new InterpretError(`fork ${decision.nodeId} branch ${branch.id} completed ${next.decision.status} before join ${decision.joinId}`);
+                }
+                return {
+                    arrival: {
+                        branchId: branch.id,
+                        seq,
+                        ...(lastVerdict ? { verdict: lastVerdict } : {}),
+                    },
+                    stepDelta,
+                };
+            }
+            const eff = await applyDecision(next.decision, {
+                ...ctx,
+                template: branchTemplate,
+                state,
+                lastVerdict,
+            });
+            stepDelta += eff.stepDelta;
+            if (eff.terminal)
+                return { terminal: eff.terminal, stepDelta };
+            if (eff.stateOverride)
+                state = eff.stateOverride;
+            lastResult = eff.lastResult;
+            if (eff.lastVerdict !== undefined)
+                lastVerdict = eff.lastVerdict;
+        }
+        throw new InterpretError(`fork ${decision.nodeId} branch ${branch.id} did not reach join ${decision.joinId} within ${MAX_STEPS} steps`);
+    }
     async function applyDecision(decision, ctx) {
         const { runId, template, bindingByRef, taskId, title, base } = ctx;
         switch (decision.type) {
@@ -596,9 +534,6 @@ export function makeDataDrivenTask(runStepFn, deps) {
                 const stepKey = stepKeyFor(node.id, ordinal);
                 const resolved = resolveConsumes(node, ctx.outputsByNode);
                 if ('missing' in resolved) {
-                    // A required upstream output is absent → fail-loud as a WIRING fault (0016 §6 / consensus M3):
-                    // a dedicated step_failed names the missing (node, as), distinct from a domain `blocker`. The
-                    // node's default onFailure='abort' then routes to a failed terminal (the run fails loud).
                     await appendEvent({
                         runId, taskId, stepId: '', stepKey, type: 'step_failed',
                         payload: { nodeId: node.id, error: `${REVO_INPUT_MISSING}: required input ${resolved.missing} was not produced` },
@@ -607,9 +542,6 @@ export function makeDataDrivenTask(runStepFn, deps) {
                 }
                 const result = await invokeRole(runId, decision, node, ctx, resolved.inputs, stepKey);
                 if ('blocked' in result) {
-                    // needsHuman (deliberate agent block OR transient runner failure): short-circuit to a visible
-                    // `blocked` terminal carrying the per-kind lesson (runGraph emits the pipeline_blocked + blocks
-                    // the run-row via blockWithLesson). NOT a failed/aborted run — the block is recoverable.
                     return {
                         lastResult: undefined,
                         terminal: {
@@ -640,8 +572,6 @@ export function makeDataDrivenTask(runStepFn, deps) {
             case 'invokeScript': {
                 const node = resolveNode(template, decision.nodeId);
                 const ordinal = nextOrdinal(ctx.effectOrdinalByNode, node.id);
-                // A script node may `consumes` upstream data (plan 0018: respondThreads ← triage). Hydrate it
-                // from the workflow-local accumulator (same seam as agents), fail-loud on a missing required input.
                 const resolved = resolveConsumes(node, ctx.outputsByNode);
                 if ('missing' in resolved) {
                     await appendEvent({
@@ -651,9 +581,6 @@ export function makeDataDrivenTask(runStepFn, deps) {
                     return { lastResult: { outcome: 'failed', errorCode: REVO_INPUT_MISSING }, lastVerdict: 'failed', stepDelta: 1 };
                 }
                 const scriptResult = await invokeScript(runId, decision, { taskId, title, base, issueRef: ctx.issueRef }, bindingByRef, stepKeyFor(node.id, ordinal), resolved.inputs);
-                // A blocked script (needsHuman) routes via revo.ScriptBlocked → a `blocked` terminal; a thrown
-                // script routes via revo.ScriptFailed → a `failed` terminal (§6 catch). The lesson-bearing
-                // pipeline_blocked is emitted inside invokeScript for the block path (parity with the old engine).
                 if (scriptResult.outcome === 'blocked') {
                     return { lastResult: { outcome: 'failed', errorCode: REVO_SCRIPT_BLOCKED }, lastVerdict: 'blocked', stepDelta: 1 };
                 }
@@ -661,24 +588,18 @@ export function makeDataDrivenTask(runStepFn, deps) {
                     return { lastResult: { outcome: 'failed', errorCode: REVO_SCRIPT_FAILED }, lastVerdict: 'failed', stepDelta: 1 };
                 }
                 await recordOutput(runId, node, ordinal, stepKeyFor(node.id, ordinal), scriptResult.pointer, ctx.outputsByNode);
-                // A classifying script (pollPr, plan 0018) surfaces a DOMAIN verdict so the next `choice` can
-                // route on it (§8). Scripts with a single fixed `next` (integrator/confirmMerge) carry none.
                 const sv = scriptResult.verdict;
                 return { lastResult: { outcome: 'succeeded', ...(sv ? { verdict: sv } : {}) }, ...(sv ? { lastVerdict: sv } : {}), stepDelta: 1 };
             }
             case 'awaitGate': {
                 const topic = gateTopicFor(decision.reason);
-                // Per-entry gate key (nodeId#ordinal) so a re-entered gate (e.g. a question gate looped in the
-                // review phase) gets a DISTINCT inbox row instead of colliding on `runId|topic` (§3.2 audit).
                 const ordinal = nextOrdinal(ctx.effectOrdinalByNode, decision.nodeId);
-                const human = await awaitHuman(runId, topic, stepKeyFor(decision.nodeId, ordinal), `${decision.reason} approval`, buildGateSummary(decision, ctx.outputsByNode, ctx.lastVerdict));
+                const human = await awaitHuman(runId, topic, stepKeyFor(decision.nodeId, ordinal), `${decision.reason} approval`, buildGateSummary(decision, ctx.outputsByNode, ctx.lastVerdict), decision.outcomes);
                 const verdict = gateVerdict(human, decision.outcomes);
+                await recordOutput(runId, resolveNode(template, decision.nodeId), ordinal, stepKeyFor(decision.nodeId, ordinal), gateResolutionOutput(human, verdict, stepKeyFor(decision.nodeId, ordinal)), ctx.outputsByNode);
                 return { lastResult: verdict ? { verdict } : {}, ...(verdict ? { lastVerdict: verdict } : {}), stepDelta: 0 };
             }
             case 'fork': {
-                // Fork/join is supported by the core; the MVP feature-development pipeline has none. Record a
-                // deterministic barrier arrival per branch (verdict undefined) so an `all` join proceeds. A richer
-                // concurrent-branch executor (DBOS child workflows) is a later slice (§14 Q1).
                 await appendEvent({
                     runId,
                     taskId,
@@ -687,30 +608,19 @@ export function makeDataDrivenTask(runStepFn, deps) {
                     type: 'pipeline_fork',
                     payload: { nodeId: decision.nodeId, branches: decision.branches.map((b) => b.id), joinId: decision.joinId },
                 });
-                return {
-                    lastResult: { joinArrivals: decision.branches.map((b, idx) => ({ branchId: b.id, seq: idx + 1 })) },
-                    stepDelta: 0,
-                };
+                return executeForkBranches(decision, ctx);
             }
             case 'startTimer':
-                // `wait` nodes are rare (§1) and unused by the MVP templates; a durable timer executor is a later
-                // slice. Treat as an immediate (recorded) resume so a template using it still advances.
                 return { lastResult: {}, stepDelta: 0 };
         }
     }
-    // ── Effect executors ─────────────────────────────────────────────────────────
-    /** invokeRole → dispatch via the existing runStep DBOS step; validate result vs resultSchema. */
     async function invokeRole(runId, decision, node, ctx, inputs, stepKey) {
         const binding = resolveRoleBinding(ctx, decision);
-        // stepKey is ordinal-aware (0016 §4.1): distinct per loop iteration, stable across replay. The
-        // hydrated `inputs` (consumed upstream outputs) ride in stepInput → the runner renders them as a
-        // `## Inputs (from previous steps)` prompt section (build-context).
         return invokeRoleAttempts({ runId, decision, node, ctx, inputs, stepKey, binding });
     }
     function resolveRoleBinding(ctx, decision) {
         const binding = ctx.bindingByRef.get(decision.roleRef);
         if (binding === undefined) {
-            // A VALID template's caps resolve at run start; an unresolved roleRef is a fatal config gap.
             throw new Error(`CAPABILITY_UNRESOLVED: roleRef ${decision.roleRef} has no route binding`);
         }
         return binding;
@@ -721,7 +631,7 @@ export function makeDataDrivenTask(runStepFn, deps) {
         for (let attemptNo = 1; attemptNo <= ctx.runnerRetryPolicy.maxAttempts; attemptNo++) {
             const physicalAttempt = physicalAttemptFor(runId, stepKey, attemptNo);
             attemptIds.push(physicalAttempt.attemptId);
-            const result = await runStepFn(runId, binding.rowId, stepKey, stepInputForAttempt(decision.nodeId, inputs, physicalAttempt), binding.resolvedRunnerId, ctx.executionProfile, physicalAttempt);
+            const result = await runStepFn(runId, binding.rowId, stepKey, stepInputForAttempt(decision.nodeId, inputs, physicalAttempt), binding.resolvedRunnerId, ctx.executionProfile, physicalAttempt, ctx.template.verdicts.domain);
             const needsHuman = await maybeHandleNeedsHumanRoleResult({
                 ...input,
                 attemptIds,
@@ -768,12 +678,6 @@ export function makeDataDrivenTask(runStepFn, deps) {
     async function maybeHandleNeedsHumanRoleResult(input) {
         const { result, node, physicalAttempt } = input;
         if (result.needsHuman) {
-            // A `needsHuman` result is NOT a wiring fault — it is a recoverable human-block. Route it to a
-            // visible `blocked` terminal (like a blocked SCRIPT), never a ResultInvalid abort (which permanently
-            // kills the run). TWO distinct things produce needsHuman; both block, but the human must see WHICH:
-            //  - DELIBERATE: the agent self-reported `needsHuman:true` (the result-envelope contract). It carries
-            //    the agent's own `output` + `lesson` — a genuine "I need a human decision".
-            //  - TRANSIENT: runStep wraps a runner-process failure as `output.error === 'runner_failed'`.
             const transient = transientRunnerFailure(result);
             if (transient === undefined) {
                 const safeLesson = String(redactEventPayload(result.lesson ?? `agent ${node.id} reported needsHuman`));
@@ -896,26 +800,19 @@ export function makeDataDrivenTask(runStepFn, deps) {
             },
         });
     }
-    /**
-     * invokeScript → the built-in system SCRIPT library. The only built-in v1 script is the integrator
-     * (`script:integrator`); it dispatches to the real integrator (live) or the stub (script) exactly as
-     * the hardcoded path does — runner-wins via the resolved binding (D7).
-     *
-     * Two distinct outcomes the routing data discriminates (parity with the old engine):
-     *  - `blocked`: the integrator needs a human (nothing to integrate, ambiguous PRs, refused identity,
-     *    non-JSON pr view). We emit a `pipeline_blocked` event carrying the human-readable lesson (so the
-     *    human sees WHY — the persist boundary redacts any token), then the node's `catch[revo.ScriptBlocked]`
-     *    routes to a `blocked` terminal.
-     *  - `failed`: the integrator THREW (a gh/push error). `catch[revo.ScriptFailed]` routes to a `failed`
-     *    terminal; the run's top-level catch failRuns (the thrown reason is recorded, redacted).
-     */
     async function invokeScript(runId, decision, ctx, bindingByRef, stepKey, inputs) {
+        if (decision.scriptRef === 'script:cleanupWorktree') {
+            try {
+                await releaseWorktreeFn(runId, ctx.taskId);
+            }
+            catch { /* best-effort */ }
+            await appendEvent({ runId, taskId: ctx.taskId, stepId: '', stepKey, type: 'worktree_released', payload: { nodeId: decision.nodeId } });
+            return { outcome: 'ok', pointer: { released: true } };
+        }
         const isConfirmMerge = decision.scriptRef === 'script:confirmMerge';
         const isPollPr = decision.scriptRef === 'script:pollPr';
         const isRespondThreads = decision.scriptRef === 'script:respondThreads';
         const binding = bindingByRef.get(decision.scriptRef) ?? bindingByRef.get('script:integrator');
-        // respondThreads consumes `triage` (plan 0018) — ride the hydrated input on the integrator input so
-        // the live script can reply/resolve the triaged threads without a live Revisium read.
         const change = producedChangeFromInputs(inputs);
         const mergeReadiness = mergeReadinessFromInputs(inputs);
         const issueRef = ctx.issueRef;
@@ -930,8 +827,6 @@ export function makeDataDrivenTask(runStepFn, deps) {
             ...(inputs.triage === undefined ? {} : { triage: inputs.triage }),
             ...(mergeReadiness ? { mergeReadiness } : {}),
         };
-        // A script node whose resolved runner mechanically performs the merge uses the REAL script;
-        // otherwise the pure stub (zero git/gh). Absent a binding (template-only script), default to stub.
         const useReal = !!binding && runnerUsesRealIntegrator(binding.resolvedRunnerId);
         let result;
         try {
@@ -960,8 +855,6 @@ export function makeDataDrivenTask(runStepFn, deps) {
             return { outcome: 'failed' };
         }
         if ('needsHuman' in result) {
-            // Surface the blocking reason as pipeline_blocked (the persist boundary redacts any token, D15) so
-            // the human sees WHY the script could not proceed — exactly as the old engine's blockPipeline.
             const reason = isConfirmMerge ? 'confirm-merge' : isPollPr ? 'poll-pr' : isRespondThreads ? 'respond-threads' : 'integrate';
             await appendEvent({
                 runId,
@@ -998,8 +891,6 @@ export function makeDataDrivenTask(runStepFn, deps) {
             };
         }
         if (isPollPr) {
-            // pollPr CLASSIFIES the feedback: its verdict (review_changes/ci_changes/clean) routes the prRouter
-            // choice (§8 — a script may emit a domain verdict the routing data acts on, same as an agent).
             const feedback = result;
             await appendEvent({
                 runId,
@@ -1059,7 +950,6 @@ export function makeDataDrivenTask(runStepFn, deps) {
             },
         };
     }
-    /** Terminal: finish the run in Revisium per the core's terminal status. */
     async function finish(runId, status, verdict, steps, failureReason = '') {
         if (status === 'succeeded') {
             await completeRun(runId, { actor: 'pipeline', source: 'data-driven-complete', verdict, iterations: steps });
@@ -1080,12 +970,6 @@ export function makeDataDrivenTask(runStepFn, deps) {
         }
         return { runId, status, verdict, steps };
     }
-    /**
-     * Block the run early with a human-readable lesson (the engine-level preflight guard — there is no
-     * graph node for it). Emits a lesson-bearing `pipeline_blocked` (token-redacted at the persist
-     * boundary) + marks the Revisium run-row blocked, then returns a `blocked` result WITHOUT entering the
-     * graph. Mirrors the old engine's `blockPipeline({ reason })`.
-     */
     async function blockWithLesson(runId, taskId, reason, lesson, steps, retry) {
         await appendEvent({
             runId,
@@ -1099,7 +983,6 @@ export function makeDataDrivenTask(runStepFn, deps) {
         return { runId, status: 'blocked', verdict: 'blocked', steps };
     }
 }
-/** Resolve a node id against the template (a VALID template never dangles — guarded defensively). */
 function resolveNode(template, nodeId) {
     const node = template.nodes[nodeId];
     if (!node)