@revisium/orchestrator 0.1.0-alpha.9 → 0.1.0

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

@@ -31,8 +31,61 @@ import { step as coreStep, initialState, validateTemplate, InterpretError, } fro
 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.
+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 };
+}
 /**
  * Reserved engine error codes (matched only by a node's `catch`, §3/§6).
  *
@@ -48,6 +101,31 @@ const REVO_SCRIPT_FAILED = 'revo.ScriptFailed';
 const REVO_SCRIPT_BLOCKED = 'revo.ScriptBlocked';
 const REVO_RESULT_INVALID = 'revo.ResultInvalid';
 const REVO_INPUT_MISSING = 'revo.InputMissing';
+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 };
+}
 /** 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). */
@@ -64,6 +142,125 @@ function nextOrdinal(byNode, nodeId) {
 function isRecord(value) {
     return value !== null && typeof value === 'object' && !Array.isArray(value);
 }
+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),
+    };
+}
+/**
+ * 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';
+    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);
+}
 /** 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) {
@@ -205,7 +402,7 @@ export function buildGateSummary(decision, outputsByNode, lastVerdict) {
  * 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;
+    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) {
@@ -240,7 +437,7 @@ export function makeDataDrivenTask(runStepFn, deps) {
     }
     /** 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 +447,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);
@@ -283,7 +480,7 @@ export function makeDataDrivenTask(runStepFn, deps) {
         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);
+        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
@@ -292,7 +489,7 @@ export function makeDataDrivenTask(runStepFn, deps) {
         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.
+            // 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);
@@ -310,9 +507,9 @@ export function makeDataDrivenTask(runStepFn, deps) {
         let result;
         try {
             if (live) {
-                await createWorktreeFn(runId, taskId, title, base);
+                await createWorktreeFn(runId, taskId, title, base, issueRef);
             }
-            result = await runGraph(runId, opts, taskId, title, base);
+            result = await runGraph(runId, opts, taskId, title, base, issueRef, live);
             return result;
         }
         finally {
@@ -327,8 +524,8 @@ export function makeDataDrivenTask(runStepFn, deps) {
         }
     }
     /** 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;
+    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
@@ -363,17 +560,25 @@ 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,
+                runId, template, 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);
+            }
             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)`);
     }
@@ -401,19 +606,35 @@ 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) {
+                    // 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: {
+                            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': {
@@ -429,7 +650,7 @@ 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);
+                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).
@@ -439,7 +660,7 @@ export function makeDataDrivenTask(runStepFn, deps) {
                 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);
+                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;
@@ -480,29 +701,200 @@ export function makeDataDrivenTask(runStepFn, deps) {
     // ── 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) {
+        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`);
         }
-        // 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);
+            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` };
+            // 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`));
+                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 {
+            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 { failed: false, verdict: domainVerdictOf(result), output: result.output };
+        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
@@ -524,7 +916,20 @@ export function makeDataDrivenTask(runStepFn, deps) {
         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 } : {}) };
+        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 } : {}),
+        };
         // 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);
@@ -576,9 +981,21 @@ 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
@@ -590,7 +1007,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,9 +1038,26 @@ 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 = '') {
@@ -644,14 +1086,14 @@ export function makeDataDrivenTask(runStepFn, deps) {
      * 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 };