@revisium/orchestrator 0.1.0-alpha.9 → 0.2.0-alpha.0

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

@@ -1,61 +1,94 @@
-/**
- * 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';
+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.
-/**
- * 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 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) {
+    const raw = env[key];
+    if (raw === undefined)
+        return fallback;
+    if (!/^\d+$/.test(raw))
+        throw new Error(`${key} must be a positive integer`);
+    const parsed = Number(raw);
+    if (!Number.isSafeInteger(parsed) || parsed <= 0)
+        throw new Error(`${key} must be a positive integer`);
+    return parsed;
+}
+function readNonNegativeIntegerEnv(env, key, fallback) {
+    const raw = env[key];
+    if (raw === undefined)
+        return fallback;
+    if (!/^\d+$/.test(raw))
+        throw new Error(`${key} must be a non-negative integer`);
+    const parsed = Number(raw);
+    if (!Number.isSafeInteger(parsed) || parsed < 0)
+        throw new Error(`${key} must be a non-negative integer`);
+    return parsed;
+}
+export function resolveRunnerTransientRetryPolicy(env = process.env) {
+    return {
+        maxAttempts: readPositiveIntegerEnv(env, 'REVO_RUNNER_TRANSIENT_MAX_ATTEMPTS', DEFAULT_RUNNER_TRANSIENT_MAX_ATTEMPTS),
+        backoffMs: readNonNegativeIntegerEnv(env, 'REVO_RUNNER_TRANSIENT_RETRY_BACKOFF_MS', DEFAULT_RUNNER_TRANSIENT_RETRY_BACKOFF_MS),
+    };
+}
+function physicalAttemptFor(runId, stepKey, attemptNo) {
+    const attemptKey = `${runId}|${stepKey}|${attemptNo}`;
+    return {
+        attemptNo,
+        attemptId: `attempt_${fnv1a64Hex(attemptKey)}`,
+    };
+}
+function stepInputForAttempt(nodeId, inputs, attempt) {
+    return {
+        nodeId,
+        attempt: { attemptNo: attempt.attemptNo, attemptId: attempt.attemptId },
+        ...(Object.keys(inputs).length > 0 ? { inputs } : {}),
+    };
+}
+function optionalTiming(timing) {
+    return timing === undefined ? {} : { timing };
+}
+function optionalFailureKind(failureKind) {
+    return failureKind === undefined ? {} : { failureKind };
+}
 const REVO_SCRIPT_FAILED = 'revo.ScriptFailed';
 const REVO_SCRIPT_BLOCKED = 'revo.ScriptBlocked';
 const REVO_RESULT_INVALID = 'revo.ResultInvalid';
 const REVO_INPUT_MISSING = 'revo.InputMissing';
-/** 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 invalidRoleResult(reason, physicalAttempt) {
+    return {
+        failed: true,
+        errorCode: REVO_RESULT_INVALID,
+        reason,
+        attemptId: physicalAttempt.attemptId,
+        attemptsMade: physicalAttempt.attemptNo,
+    };
+}
+function runnerBlockReason(transient) {
+    if (transient.failureKind)
+        return transient.failureKind;
+    return `runner-transient-failure:${transient.transientKind}`;
+}
+function runnerBlockLesson(transient) {
+    const safe = String(redactEventPayload(transient.reason));
+    if (transient.failureKind)
+        return `${transient.failureKind}: ${safe || 'runner failed'}`;
+    return `runner-transient-failure (${transient.transientKind}): ${safe || 'runner failed'}`;
+}
+function pipelineBlockedPayload(reason, lesson, retry) {
+    if (retry === undefined)
+        return { reason, lesson };
+    return { ...retry };
+}
 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);
@@ -64,7 +97,120 @@ function nextOrdinal(byNode, nodeId) {
 function isRecord(value) {
     return value !== null && typeof value === 'object' && !Array.isArray(value);
 }
-/** Extract the DOMAIN verdict from the only supported source: top-level AttemptResult.verdict. */
+function producedChangeArtifact(value) {
+    if (!isRecord(value))
+        return undefined;
+    const candidate = isRecord(value.change) ? value.change : value;
+    const branch = candidate.branch;
+    const headSha = candidate.headSha;
+    if (typeof branch !== 'string' || branch.trim().length === 0)
+        return undefined;
+    if (typeof headSha !== 'string' || headSha.trim().length === 0)
+        return undefined;
+    const issueRef = normalizeArtifactIssueRef(candidate.issueRef);
+    return {
+        branch,
+        headSha,
+        ...(issueRef ? { issueRef } : {}),
+        ...(typeof candidate.worktreePath === 'string' && candidate.worktreePath.trim() ? { worktreePath: candidate.worktreePath } : {}),
+        ...(typeof candidate.artifactRef === 'string' && candidate.artifactRef.trim() ? { artifactRef: candidate.artifactRef } : {}),
+        ...(typeof candidate.prNumber === 'number' && Number.isSafeInteger(candidate.prNumber) ? { prNumber: candidate.prNumber } : {}),
+    };
+}
+function normalizeArtifactIssueRef(value) {
+    try {
+        return normalizeIssueRef(value, 'change.issueRef');
+    }
+    catch {
+        return undefined;
+    }
+}
+function changeWithRunIssueRef(change, issueRef) {
+    const normalized = { ...change };
+    if (issueRef) {
+        normalized.issueRef = issueRef;
+    }
+    else {
+        delete normalized.issueRef;
+    }
+    return normalized;
+}
+function producedChangeFromInputs(inputs) {
+    for (const key of ['reviewChange', 'ciChange', 'reworkChange', 'developerChange', 'change']) {
+        const artifact = producedChangeArtifact(inputs[key]);
+        if (artifact)
+            return artifact;
+    }
+    return undefined;
+}
+function mergeReadinessFromInputs(inputs) {
+    const value = inputs.mergeReadiness;
+    if (!isRecord(value))
+        return undefined;
+    const headSha = value.headSha;
+    if (typeof headSha !== 'string' || headSha.trim().length === 0)
+        return undefined;
+    return { headSha };
+}
+function attachProducedChange(output, change) {
+    if (isRecord(output))
+        return { ...output, change };
+    return { summary: output, change };
+}
+function nodeProducesChange(node) {
+    return (node.kind === 'agent' || node.kind === 'script') &&
+        node.produces?.name === 'change' &&
+        node.resultSchema === 'schema:change';
+}
+function runnerProducesWorktreeChanges(runnerId) {
+    return runnerId === 'claude-code' || runnerId === 'codex';
+}
+function artifactRefFromResult(result) {
+    const artifacts = result.artifacts;
+    const processArtifact = isRecord(artifacts) && isRecord(artifacts.process) ? artifacts.process : artifacts;
+    if (!isRecord(processArtifact))
+        return undefined;
+    return typeof processArtifact.ref === 'string' ? processArtifact.ref : undefined;
+}
+function publicTimeoutFailureKind(value) {
+    return value === RUNNER_IDLE_TIMEOUT_KIND || value === RUNNER_WALL_CLOCK_LIMIT_KIND
+        ? value
+        : undefined;
+}
+function transientRunnerFailure(result) {
+    const output = result.output;
+    if (!isRecord(output) || output.error !== 'runner_failed')
+        return undefined;
+    const reason = typeof output.reason === 'string' ? output.reason : '';
+    const failureKind = publicTimeoutFailureKind(output.failureKind);
+    const legacyKind = transientKind(reason);
+    const retryableCandidate = output.retryableCandidate !== false;
+    return {
+        reason,
+        transientKind: failureKind ? 'timeout' : legacyKind,
+        retryableCandidate,
+        retryable: retryableCandidate && (failureKind !== undefined || legacyKind !== 'unknown'),
+        ...optionalFailureKind(failureKind),
+        ...optionalTiming(output.timing),
+    };
+}
+function transientKind(reason) {
+    if (/exceeded\s*\d+\s*ms|timed?\s*out|\btimeout\b/i.test(reason))
+        return 'timeout';
+    if (/\b429\b|rate.?limit|session limit/i.test(reason))
+        return 'rate_limit';
+    if (isLegacyRetryableCrashReason(reason))
+        return 'crash';
+    return 'unknown';
+}
+function isLegacyRetryableCrashReason(reason) {
+    if (/\b(auth|credential|permission|forbidden|denied|unauthori[sz]ed|config|schema|malformed|parseable|invalid|RUNNER_NOT_IMPLEMENTED|not wired|unknown runner|requires an OpenAI|ENOENT|not found)\b/i
+        .test(reason)) {
+        return false;
+    }
+    return /\b(signal|crash(?:ed)?|killed|ECONNRESET|ETIMEDOUT|EAI_AGAIN|socket hang up|ENOMEM|EAGAIN)\b/i
+        .test(reason);
+}
 function domainVerdictOf(result) {
     if (typeof result.verdict === 'string' && result.verdict.trim().length > 0) {
         return result.verdict.trim().toLowerCase();
@@ -83,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;
@@ -109,28 +249,11 @@ 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.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 gateTopicFor(reason) {
     if (/merge/i.test(reason))
         return 'merge';
@@ -138,15 +261,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;
@@ -155,20 +271,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)
-}
-/**
- * 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).
- */
+    return produced[produced.length - 1];
+}
 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 {
@@ -178,12 +286,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);
@@ -192,22 +294,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, 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). */
+    const { appendEvent, appendRunOutput, awaitHuman, completeRun, failRun, blockRun, loadRunTaskContext, integrateFn, runStub, confirmMergeFn, runConfirmStub, pollPrFn, runPollStub, respondThreadsFn, runRespondStub, captureChangeFn, preflightFn, createWorktreeFn, releaseWorktreeFn } = deps;
     function resolveConsumes(node, outputsByNode) {
         const refs = 'consumes' in node ? (node.consumes ?? []) : [];
         const inputs = {};
@@ -238,9 +330,7 @@ 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, output, outputsByNode) {
+    async function recordOutput(runId, node, ordinal, attemptId, output, outputsByNode) {
         if (!('produces' in node) || !node.produces)
             return;
         const row = {
@@ -250,7 +340,7 @@ export function makeDataDrivenTask(runStepFn, deps) {
             name: node.produces.name,
             schemaRef: ('resultSchema' in node && node.resultSchema) || '',
             payload: output,
-            attemptId: stepKeyFor(node.id, ordinal),
+            attemptId,
         };
         const list = outputsByNode.get(node.id) ?? [];
         list.push(row);
@@ -262,9 +352,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);
@@ -277,64 +364,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 } = 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 { taskId, title, base, issueRef } = await loadRunTaskContext(runId);
         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/freshness 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);
-            }
-            result = await runGraph(runId, opts, taskId, title, base);
-            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) {
-        const { route, template } = 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.
+    async function runGraph(runId, opts, taskId, title, base, issueRef, live) {
+        const { route, template, runnerRetryPolicy } = opts;
         const bindingByRef = new Map();
         for (const binding of route.roleBindings) {
             bindingByRef.set(`role:${binding.roleId}`, binding);
@@ -350,9 +398,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++) {
@@ -363,25 +408,111 @@ 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,
-                effectOrdinalByNode, outputsByNode,
-                // 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.
+                runId, template, state, bindingByRef, executionProfile, taskId, title, base, issueRef,
+                effectOrdinalByNode, outputsByNode, runnerRetryPolicy,
+                live,
                 lastVerdict,
             });
+            stepCount += eff.stepDelta;
+            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;
             lastFailureReason = eff.failureReason ?? '';
-            stepCount += eff.stepDelta;
         }
         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) {
@@ -391,9 +522,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` },
@@ -401,26 +529,37 @@ export function makeDataDrivenTask(runStepFn, deps) {
                     return { lastResult: { outcome: 'failed', errorCode: REVO_INPUT_MISSING }, lastVerdict: 'failed', stepDelta: 1 };
                 }
                 const result = await invokeRole(runId, decision, node, ctx, resolved.inputs, stepKey);
+                if ('blocked' in result) {
+                    return {
+                        lastResult: undefined,
+                        terminal: {
+                            status: 'blocked',
+                            reason: result.reason,
+                            lesson: result.lesson,
+                            ...(result.retry ? { retry: result.retry } : {}),
+                        },
+                        stepDelta: result.attemptsMade,
+                    };
+                }
                 if (result.failed) {
                     await appendEvent({
                         runId, taskId, stepId: '', stepKey, type: 'step_failed',
+                        idempotencyKey: result.attemptId,
                         payload: { nodeId: node.id, error: result.errorCode },
                     });
-                    return { lastResult: { outcome: 'failed', errorCode: result.errorCode }, lastVerdict: 'failed', failureReason: result.reason, stepDelta: 1 };
+                    return { lastResult: { outcome: 'failed', errorCode: result.errorCode }, lastVerdict: 'failed', failureReason: result.reason, stepDelta: result.attemptsMade };
                 }
-                await recordOutput(runId, node, ordinal, result.output, ctx.outputsByNode);
+                await recordOutput(runId, node, ordinal, result.attemptId, result.output, ctx.outputsByNode);
                 const verdict = result.verdict;
                 return {
                     lastResult: { outcome: 'succeeded', ...(verdict ? { verdict } : {}) },
                     ...(verdict ? { lastVerdict: verdict } : {}),
-                    stepDelta: 1,
+                    stepDelta: result.attemptsMade,
                 };
             }
             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({
@@ -429,35 +568,25 @@ 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 }, 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).
+                const scriptResult = await invokeScript(runId, decision, { taskId, title, base, issueRef: ctx.issueRef }, bindingByRef, stepKeyFor(node.id, ordinal), resolved.inputs);
                 if (scriptResult.outcome === 'blocked') {
                     return { lastResult: { outcome: 'failed', errorCode: REVO_SCRIPT_BLOCKED }, lastVerdict: 'blocked', stepDelta: 1 };
                 }
                 if (scriptResult.outcome === 'failed') {
                     return { lastResult: { outcome: 'failed', errorCode: REVO_SCRIPT_FAILED }, lastVerdict: 'failed', stepDelta: 1 };
                 }
-                await recordOutput(runId, node, 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.
+                await recordOutput(runId, node, ordinal, stepKeyFor(node.id, ordinal), scriptResult.pointer, ctx.outputsByNode);
                 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 verdict = gateVerdict(human, decision.outcomes);
                 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,
@@ -466,67 +595,225 @@ 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);
+        return invokeRoleAttempts({ runId, decision, node, ctx, inputs, stepKey, binding });
+    }
+    function resolveRoleBinding(ctx, decision) {
         const binding = ctx.bindingByRef.get(decision.roleRef);
-        if (!binding) {
-            // A VALID template's caps resolve at run start; an unresolved roleRef is a fatal config gap.
+        if (binding === undefined) {
             throw new Error(`CAPABILITY_UNRESOLVED: roleRef ${decision.roleRef} has no route binding`);
         }
-        // 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).
-        const stepInput = Object.keys(inputs).length > 0 ? { nodeId: decision.nodeId, inputs } : { nodeId: decision.nodeId };
-        const result = await runStepFn(runId, binding.rowId, stepKey, stepInput, binding.resolvedRunnerId, ctx.executionProfile);
-        // runStep converts a runner-process crash into a blocking attempt (needsHuman + verdict BLOCKER);
-        // that is a domain failure of the node → route via §6 precedence as a result-invalid/failed effect.
+        return binding;
+    }
+    async function invokeRoleAttempts(input) {
+        const { runId, decision, node, ctx, inputs, stepKey, binding } = input;
+        const attemptIds = [];
+        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, ctx.template.verdicts.domain);
+            const needsHuman = await maybeHandleNeedsHumanRoleResult({
+                ...input,
+                attemptIds,
+                physicalAttempt,
+                result,
+            });
+            if (needsHuman === 'retry')
+                continue;
+            if (needsHuman)
+                return needsHuman;
+            const failed = roleValidationFailure(ctx.template, node, result, physicalAttempt);
+            if (failed)
+                return failed;
+            let output = result.output;
+            const hasProducedChange = producedChangeArtifact(output) !== undefined;
+            const shouldCaptureChange = nodeProducesChange(node) &&
+                !hasProducedChange &&
+                ctx.live &&
+                runnerProducesWorktreeChanges(binding.resolvedRunnerId);
+            if (shouldCaptureChange) {
+                const artifactRef = artifactRefFromResult(result);
+                const change = await captureChangeFn({
+                    runId,
+                    taskId: ctx.taskId,
+                    title: ctx.title,
+                    base: ctx.base,
+                    nodeId: node.id,
+                    attemptId: physicalAttempt.attemptId,
+                    ...(ctx.issueRef ? { issueRef: ctx.issueRef } : {}),
+                    ...(artifactRef ? { artifactRef } : {}),
+                });
+                output = attachProducedChange(output, change);
+            }
+            return {
+                failed: false,
+                verdict: domainVerdictOf(result),
+                output,
+                attemptId: physicalAttempt.attemptId,
+                attemptsMade: attemptNo,
+            };
+        }
+        throw new InterpretError(`runner retry loop for ${stepKey} exceeded maxAttempts`);
+    }
+    async function maybeHandleNeedsHumanRoleResult(input) {
+        const { result, node, physicalAttempt } = input;
         if (result.needsHuman) {
-            return { failed: true, errorCode: REVO_RESULT_INVALID, reason: `${REVO_RESULT_INVALID}: node ${node.id} returned needsHuman instead of a valid result` };
+            const transient = transientRunnerFailure(result);
+            if (transient === undefined) {
+                const safeLesson = String(redactEventPayload(result.lesson ?? `agent ${node.id} reported needsHuman`));
+                return { blocked: true, reason: 'agent-needs-human', lesson: safeLesson, attemptsMade: physicalAttempt.attemptNo };
+            }
+            return handleTransientRoleResult({ ...input, transient });
         }
-        if (!resultSatisfiesSchema(node, result)) {
-            return { failed: true, errorCode: REVO_RESULT_INVALID, reason: `${REVO_RESULT_INVALID}: node ${node.id} result did not satisfy resultSchema ${String('resultSchema' in node ? node.resultSchema : '')}` };
+        return undefined;
+    }
+    async function handleTransientRoleResult(input) {
+        const { runId, node, ctx, stepKey, attemptIds, physicalAttempt, transient } = input;
+        const policy = ctx.runnerRetryPolicy;
+        if (shouldRetryTransient(transient, physicalAttempt, policy)) {
+            const nextAttempt = physicalAttemptFor(runId, stepKey, physicalAttempt.attemptNo + 1);
+            await appendRunnerRetryScheduled({
+                runId,
+                taskId: ctx.taskId,
+                stepKey,
+                nodeId: node.id,
+                failedAttempt: physicalAttempt,
+                nextAttempt,
+                policy,
+                transient,
+            });
+            if (policy.backoffMs > 0)
+                await deps.sleep(policy.backoffMs);
+            return 'retry';
         }
-        const verdictProblem = resultVerdictProblem(ctx.template, node, result);
-        if (verdictProblem) {
-            return { failed: true, errorCode: REVO_RESULT_INVALID, reason: verdictProblem };
+        const retry = runnerRetryBlockPayload({
+            transient,
+            attemptIds,
+            lastAttempt: physicalAttempt,
+            policy,
+            attemptsExhausted: transient.retryable && physicalAttempt.attemptNo >= policy.maxAttempts,
+        });
+        if (retry.attemptsExhausted) {
+            await appendRunnerRetryExhausted({
+                runId,
+                taskId: ctx.taskId,
+                stepKey,
+                nodeId: node.id,
+                retry,
+                idempotencyKey: physicalAttempt.attemptId,
+            });
         }
-        return { failed: false, verdict: domainVerdictOf(result), output: result.output };
+        return {
+            blocked: true,
+            reason: retry.reason,
+            lesson: retry.lesson,
+            retry,
+            attemptsMade: physicalAttempt.attemptNo,
+        };
+    }
+    function shouldRetryTransient(transient, attempt, policy) {
+        return transient.retryable && attempt.attemptNo < policy.maxAttempts;
+    }
+    function roleValidationFailure(template, node, result, physicalAttempt) {
+        if (resultSatisfiesSchema(node, result)) {
+            const verdictProblem = resultVerdictProblem(template, node, result);
+            if (verdictProblem)
+                return invalidRoleResult(verdictProblem, physicalAttempt);
+            return undefined;
+        }
+        return invalidRoleResult(`${REVO_RESULT_INVALID}: node ${node.id} result did not satisfy resultSchema ${String('resultSchema' in node ? node.resultSchema : '')}`, physicalAttempt);
+    }
+    function runnerRetryBlockPayload(input) {
+        const { transient, attemptIds, lastAttempt, policy, attemptsExhausted } = input;
+        const reason = runnerBlockReason(transient);
+        const lesson = runnerBlockLesson(transient);
+        return {
+            attemptsExhausted,
+            attemptsMade: lastAttempt.attemptNo,
+            maxAttempts: policy.maxAttempts,
+            attemptIds: [...attemptIds],
+            lastAttemptId: lastAttempt.attemptId,
+            reason,
+            lesson,
+            ...optionalFailureKind(transient.failureKind),
+            transientKind: transient.transientKind,
+            ...optionalTiming(transient.timing),
+        };
+    }
+    async function appendRunnerRetryScheduled(input) {
+        const { runId, taskId, stepKey, nodeId, failedAttempt, nextAttempt, policy, transient } = input;
+        await appendEvent({
+            runId,
+            taskId,
+            stepId: '',
+            stepKey,
+            type: 'runner_retry_scheduled',
+            idempotencyKey: failedAttempt.attemptId,
+            payload: {
+                nodeId,
+                failedAttemptNo: failedAttempt.attemptNo,
+                failedAttemptId: failedAttempt.attemptId,
+                nextAttemptNo: nextAttempt.attemptNo,
+                nextAttemptId: nextAttempt.attemptId,
+                maxAttempts: policy.maxAttempts,
+                backoffMs: policy.backoffMs,
+                reason: runnerBlockReason(transient),
+                lesson: runnerBlockLesson(transient),
+                ...optionalFailureKind(transient.failureKind),
+                transientKind: transient.transientKind,
+                ...optionalTiming(transient.timing),
+            },
+        });
+    }
+    async function appendRunnerRetryExhausted(input) {
+        const { runId, taskId, stepKey, nodeId, retry, idempotencyKey } = input;
+        await appendEvent({
+            runId,
+            taskId,
+            stepId: '',
+            stepKey,
+            type: 'runner_retry_exhausted',
+            idempotencyKey,
+            payload: {
+                nodeId,
+                ...retry,
+            },
+        });
     }
-    /**
-     * 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 integratorInput = { runId, taskId: ctx.taskId, title: ctx.title, base: ctx.base, ...(inputs.triage !== undefined ? { triage: inputs.triage } : {}) };
-        // 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 change = producedChangeFromInputs(inputs);
+        const mergeReadiness = mergeReadinessFromInputs(inputs);
+        const issueRef = ctx.issueRef;
+        const changeForIntegrator = change ? changeWithRunIssueRef(change, issueRef) : undefined;
+        const integratorInput = {
+            runId,
+            taskId: ctx.taskId,
+            title: ctx.title,
+            base: ctx.base,
+            ...(issueRef ? { issueRef } : {}),
+            ...(changeForIntegrator ? { change: changeForIntegrator } : {}),
+            ...(inputs.triage === undefined ? {} : { triage: inputs.triage }),
+            ...(mergeReadiness ? { mergeReadiness } : {}),
+        };
         const useReal = !!binding && runnerUsesRealIntegrator(binding.resolvedRunnerId);
         let result;
         try {
@@ -555,8 +842,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,
@@ -576,13 +861,23 @@ export function makeDataDrivenTask(runStepFn, deps) {
                 stepId: '',
                 stepKey,
                 type: 'merge_confirmed',
-                payload: { prNumber: merged.prNumber, prUrl: merged.prUrl },
+                payload: {
+                    prNumber: merged.prNumber,
+                    prUrl: merged.prUrl,
+                    ...(merged.issueRef ? { issueRef: merged.issueRef } : {}),
+                },
             });
-            return { outcome: 'ok', pointer: { merged: true, prNumber: merged.prNumber, prUrl: merged.prUrl } };
+            return {
+                outcome: 'ok',
+                pointer: {
+                    merged: true,
+                    prNumber: merged.prNumber,
+                    prUrl: merged.prUrl,
+                    ...(merged.issueRef ? { issueRef: merged.issueRef } : {}),
+                },
+            };
         }
         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,
@@ -590,7 +885,15 @@ export function makeDataDrivenTask(runStepFn, deps) {
                 stepId: '',
                 stepKey,
                 type: 'pr_polled',
-                payload: { prNumber: feedback.prNumber, verdict: feedback.verdict, ciFailures: feedback.ciFailures.length, reviewThreads: feedback.reviewThreads.length },
+                payload: {
+                    prNumber: feedback.prNumber,
+                    headSha: feedback.headSha,
+                    verdict: feedback.verdict,
+                    evidence: feedback.evidence,
+                    ciFailures: feedback.ciFailures.length,
+                    reviewThreads: feedback.reviewThreads.length,
+                    ...(feedback.issueRef ? { issueRef: feedback.issueRef } : {}),
+                },
             });
             return { outcome: 'ok', pointer: feedback, verdict: feedback.verdict };
         }
@@ -613,11 +916,27 @@ export function makeDataDrivenTask(runStepFn, deps) {
             stepId: '',
             stepKey,
             type: 'integrate_succeeded',
-            payload: { prUrl: integrated.prUrl, branch: integrated.branch, prNumber: integrated.prNumber },
+            payload: {
+                prUrl: integrated.prUrl,
+                branch: integrated.branch,
+                prNumber: integrated.prNumber,
+                headSha: integrated.headSha,
+                status: integrated.status,
+                ...(integrated.issueRef ? { issueRef: integrated.issueRef } : {}),
+            },
         });
-        return { outcome: 'ok', pointer: { prUrl: integrated.prUrl, branch: integrated.branch, prNumber: integrated.prNumber } };
+        return {
+            outcome: 'ok',
+            pointer: {
+                prUrl: integrated.prUrl,
+                branch: integrated.branch,
+                prNumber: integrated.prNumber,
+                headSha: integrated.headSha,
+                status: integrated.status,
+                ...(integrated.issueRef ? { issueRef: integrated.issueRef } : {}),
+            },
+        };
     }
-    /** 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 });
@@ -638,26 +957,19 @@ 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) {
+    async function blockWithLesson(runId, taskId, reason, lesson, steps, retry) {
         await appendEvent({
             runId,
             taskId,
             stepId: '',
             stepKey: 'pipeline',
             type: 'pipeline_blocked',
-            payload: { reason, lesson },
+            payload: pipelineBlockedPayload(reason, lesson, retry),
         });
         await blockRun(runId, { actor: 'pipeline', source: `data-driven-${reason}`, reason });
         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)