@revisium/orchestrator 0.2.0-alpha.4 → 0.2.0-alpha.5

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

@@ -1,5 +1,5 @@
 import { step as coreStep, initialState, validateTemplate, InterpretError, selectJoinWinner, reduceJoinVerdict, } from '../pipeline-core/index.js';
-import { resolveLaunchOverrides, runnerNeedsLivePreflight, runnerUsesRealIntegrator } from './route-contract.js';
+import { resolveLaunchOverrides, runnerNeedsLivePreflight } 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';
@@ -10,6 +10,7 @@ export const INTEGRATOR_PROGRESS_EVENT_TYPES = ['integrate_succeeded', 'foreign_
 const MAX_STEPS = 1_000;
 const DEFAULT_RUNNER_TRANSIENT_MAX_ATTEMPTS = 2;
 const DEFAULT_RUNNER_TRANSIENT_RETRY_BACKOFF_MS = 2_000;
+const TRANSIENT_RETRY_GATE_OUTCOMES = ['retry', 'give_up'];
 function readPositiveIntegerEnv(env, key, fallback) {
     const raw = env[key];
     if (raw === undefined)
@@ -45,11 +46,12 @@ function physicalAttemptFor(runId, stepKey, attemptNo) {
         attemptId: `attempt_${fnv1a64Hex(attemptKey)}`,
     };
 }
-function stepInputForAttempt(nodeId, inputs, attempt) {
+function stepInputForAttempt(nodeId, inputs, attempt, retryContext) {
     return {
         nodeId,
         attempt: { attemptNo: attempt.attemptNo, attemptId: attempt.attemptId },
         ...(Object.keys(inputs).length > 0 ? { inputs } : {}),
+        ...(retryContext ? { retryContext } : {}),
     };
 }
 function optionalTiming(timing) {
@@ -98,6 +100,19 @@ function nextOrdinal(byNode, nodeId) {
 function isRecord(value) {
     return value !== null && typeof value === 'object' && !Array.isArray(value);
 }
+function transientRetryGateOutcome(decision) {
+    const answer = isRecord(decision.answer) ? decision.answer : {};
+    let outcome = '';
+    if (typeof decision.outcome === 'string') {
+        outcome = decision.outcome;
+    }
+    else if (typeof answer.outcome === 'string') {
+        outcome = answer.outcome;
+    }
+    if (outcome === 'retry')
+        return 'retry';
+    return 'give_up';
+}
 function producedChangeArtifact(value) {
     if (!isRecord(value))
         return undefined;
@@ -188,9 +203,27 @@ function nodeProducesChange(node) {
         node.produces?.name === 'change' &&
         node.resultSchema === 'schema:change';
 }
+function recoveryContextAfterNode(nodeId, recoveryContext) {
+    if (!recoveryContext)
+        return undefined;
+    return nodeId === 'classifyRecovery' ? recoveryContext : null;
+}
 function runnerProducesWorktreeChanges(runnerId) {
     return runnerId === 'claude-code' || runnerId === 'codex';
 }
+const LIVE_WORKTREE_SCRIPT_REFS = new Set([
+    'script:integrator',
+    'script:confirmMerge',
+    'script:pollPr',
+    'script:overrideMerge',
+    'script:respondThreads',
+]);
+function scriptRequiresLiveWorktree(scriptRef) {
+    return LIVE_WORKTREE_SCRIPT_REFS.has(scriptRef);
+}
+function templateRequiresLiveWorktree(template) {
+    return Object.values(template.nodes).some((node) => node.kind === 'script' && scriptRequiresLiveWorktree(node.scriptRef));
+}
 function artifactRefFromResult(result) {
     const artifacts = result.artifacts;
     const processArtifact = isRecord(artifacts) && isRecord(artifacts.process) ? artifacts.process : artifacts;
@@ -225,6 +258,8 @@ function transientKind(reason) {
         return 'timeout';
     if (/\b429\b|rate.?limit|session limit/i.test(reason))
         return 'rate_limit';
+    if (/\b529\b|overloaded/i.test(reason))
+        return 'overloaded';
     if (isLegacyRetryableCrashReason(reason))
         return 'crash';
     return 'unknown';
@@ -301,7 +336,7 @@ function gateVerdict(decision, outcomes) {
         return outcomes[0];
     return outcomes.length > 1 ? outcomes.at(-1) : undefined;
 }
-function gateResolutionOutput(decision, verdict, fallbackInboxId, trustedGateHeadSha) {
+function gateResolutionMetadata(decision, fallbackInboxId) {
     const decisionRecord = isRecord(decision) ? decision : {};
     const answer = isRecord(decision.answer) ? decision.answer : {};
     const note = decision.note ?? (typeof answer.note === 'string' ? answer.note : undefined);
@@ -311,17 +346,61 @@ function gateResolutionOutput(decision, verdict, fallbackInboxId, trustedGateHea
     const mergeOverrideAudit = answer.mergeOverrideAudit ?? decisionRecord['mergeOverrideAudit'];
     const adoptionAudit = answer.adoptionAudit ?? decisionRecord['adoptionAudit'];
     return {
-        outcome: decision.outcome ?? verdict ?? decision.decision,
         ...(note !== undefined ? { note } : {}),
         resolvedBy,
         resolvedAt,
-        inboxId,
-        ...(trustedGateHeadSha !== undefined ? { trustedGateHeadSha } : {}),
+        ...(inboxId !== undefined ? { inboxId } : {}),
         ...(mergeOverrideAudit !== undefined ? { mergeOverrideAudit } : {}),
         ...(adoptionAudit !== undefined ? { adoptionAudit } : {}),
+    };
+}
+function gateResolutionOutput(decision, verdict, fallbackInboxId, trustedGateHeadSha) {
+    const resolution = gateResolutionMetadata(decision, fallbackInboxId);
+    return {
+        outcome: decision.outcome ?? verdict ?? decision.decision,
+        ...(resolution.note !== undefined ? { note: resolution.note } : {}),
+        resolvedBy: resolution.resolvedBy,
+        resolvedAt: resolution.resolvedAt,
+        inboxId: resolution.inboxId ?? fallbackInboxId,
+        ...(trustedGateHeadSha !== undefined ? { trustedGateHeadSha } : {}),
+        ...(resolution.mergeOverrideAudit !== undefined ? { mergeOverrideAudit: resolution.mergeOverrideAudit } : {}),
+        ...(resolution.adoptionAudit !== undefined ? { adoptionAudit: resolution.adoptionAudit } : {}),
         ...(decision.decision ? { decision: decision.decision } : {}),
     };
 }
+function nonEmptyString(value) {
+    if (typeof value !== 'string')
+        return undefined;
+    const trimmed = value.trim();
+    return trimmed.length > 0 ? trimmed : undefined;
+}
+function isSyntheticGateTimeoutFallback(decision) {
+    const answer = isRecord(decision.answer) ? decision.answer : {};
+    return decision.decision === 'reject' && answer.reason === 'gate-timeout';
+}
+function agentQuestionRetryContext(decision, nodeId, safeLesson) {
+    if (isSyntheticGateTimeoutFallback(decision))
+        return undefined;
+    const resolution = gateResolutionMetadata(decision);
+    const inboxId = nonEmptyString(resolution.inboxId);
+    const resolvedBy = nonEmptyString(resolution.resolvedBy);
+    if (!inboxId || !resolvedBy)
+        return undefined;
+    return {
+        kind: 'agent_question',
+        nodeId,
+        answer: decision.answer,
+        lesson: safeLesson,
+        inboxId,
+        resolvedBy,
+    };
+}
+function unresolvedAgentQuestionLesson(nodeId, safeLesson, decision) {
+    const reason = isSyntheticGateTimeoutFallback(decision)
+        ? 'agent question timed out'
+        : 'agent question resolution is missing inboxId or resolvedBy';
+    return `${reason} for ${nodeId}; original question: ${safeLesson}`;
+}
 function gateTopicFor(reason) {
     if (/merge/i.test(reason))
         return 'merge';
@@ -363,9 +442,19 @@ function freshMergeGateArtifact(decision, lastVerdict, lastProducedOutput) {
         return lastProducedOutput;
     return undefined;
 }
-export function buildGateSummary(decision, outputsByNode, lastVerdict, lastProducedOutput) {
+function latestBlockedScriptArtifact(decision, recoveryContext) {
+    if (decision.nodeId !== 'recoveryGate')
+        return undefined;
+    const payload = recoveryContext?.payload;
+    if (!payload || typeof payload !== 'object' || Array.isArray(payload))
+        return undefined;
+    const record = payload;
+    return typeof record.lesson === 'string' && typeof record.reason === 'string' ? recoveryContext : undefined;
+}
+export function buildGateSummary(decision, outputsByNode, lastVerdict, lastProducedOutput, recoveryContext) {
     const summary = { nodeId: decision.nodeId, outcomes: decision.outcomes };
-    const artRow = freshMergeGateArtifact(decision, lastVerdict, lastProducedOutput)
+    const artRow = latestBlockedScriptArtifact(decision, recoveryContext)
+        ?? freshMergeGateArtifact(decision, lastVerdict, lastProducedOutput)
         ?? resolveGateRow(decision.gatedArtifact, outputsByNode);
     if (artRow)
         summary.gatedArtifact = gateArtifactView(artRow, decision.gatedArtifact?.as);
@@ -444,9 +533,19 @@ function mergeOverrideEventPayload(result) {
         ...(result.override.reason ? { refusalReason: result.override.reason } : {}),
     };
 }
+function scriptGithubAccount(decision, launchBindings) {
+    if (!launchBindings)
+        return undefined;
+    for (let index = launchBindings.length - 1; index >= 0; index -= 1) {
+        const binding = launchBindings[index];
+        if (binding.match.nodeId === decision.nodeId)
+            return binding.accounts?.github;
+    }
+    return undefined;
+}
 export function buildSystemScriptRegistry(deps) {
-    const { appendEvent, releaseWorktreeFn, integrateFn, runStub, confirmMergeFn, runConfirmStub, pollPrFn, runPollStub, overrideMergeFn, runOverrideStub, respondThreadsFn, runRespondStub, } = deps;
-    function buildIntegratorInput(runId, ctx, inputs) {
+    const { appendEvent, releaseWorktreeFn, integrateFn, confirmMergeFn, pollPrFn, overrideMergeFn, respondThreadsFn, } = deps;
+    function buildIntegratorInput(runId, ctx, inputs, githubAccount) {
         const { taskId, title, base, issueRef, issueAction } = ctx;
         const change = producedChangeFromInputs(inputs);
         const mergeReadiness = mergeReadinessFromInputs(inputs);
@@ -456,6 +555,7 @@ export function buildSystemScriptRegistry(deps) {
             taskId,
             title,
             base,
+            ...(githubAccount ? { githubAccount } : {}),
             ...(issueRef ? { issueRef } : {}),
             ...(issueAction ? { issueAction } : {}),
             ...(changeForIntegrator ? { change: changeForIntegrator } : {}),
@@ -465,13 +565,11 @@ export function buildSystemScriptRegistry(deps) {
         };
     }
     function makeIntegratorScript(desc) {
-        return async ({ runId, decision, ctx, bindingByRef, stepKey, inputs }) => {
-            const integratorInput = buildIntegratorInput(runId, ctx, inputs);
-            const binding = bindingByRef.get(decision.scriptRef) ?? bindingByRef.get('script:integrator');
-            const useReal = !!binding && runnerUsesRealIntegrator(binding.resolvedRunnerId);
+        return async ({ runId, decision, ctx, launchBindings, stepKey, inputs }) => {
+            const integratorInput = buildIntegratorInput(runId, ctx, inputs, scriptGithubAccount(decision, launchBindings));
             let result;
             try {
-                result = useReal ? await desc.real(integratorInput) : desc.stub(integratorInput);
+                result = await desc.real(integratorInput);
             }
             catch (err) {
                 const reason = err instanceof Error ? err.message : String(err);
@@ -483,12 +581,17 @@ export function buildSystemScriptRegistry(deps) {
                 return { outcome: 'failed', reason };
             }
             if ('needsHuman' in result) {
+                const pointer = {
+                    reason: desc.blockedReason,
+                    lesson: result.lesson,
+                    nodeId: decision.nodeId,
+                };
                 await appendEvent({
                     runId, taskId: ctx.taskId, stepId: '', stepKey: 'pipeline',
                     type: 'pipeline_blocked',
-                    payload: { reason: desc.blockedReason, lesson: result.lesson, nodeId: decision.nodeId },
+                    payload: pointer,
                 });
-                return { outcome: 'blocked' };
+                return { outcome: 'blocked', pointer };
             }
             const { eventType, payload, pointer, verdict } = desc.mapSuccess(result);
             await appendEvent({ runId, taskId: ctx.taskId, stepId: '', stepKey, type: eventType, payload });
@@ -533,7 +636,6 @@ export function buildSystemScriptRegistry(deps) {
     };
     const integratorScript = makeIntegratorScript({
         real: integrateFn,
-        stub: runStub,
         blockedReason: 'integrate',
         mapSuccess: (result) => ({
             eventType: integratorProgressEventType(result),
@@ -543,7 +645,6 @@ export function buildSystemScriptRegistry(deps) {
     });
     const confirmMergeScript = makeIntegratorScript({
         real: confirmMergeFn,
-        stub: runConfirmStub,
         blockedReason: 'confirm-merge',
         mapSuccess: (result) => ({
             eventType: 'merge_confirmed',
@@ -562,7 +663,6 @@ export function buildSystemScriptRegistry(deps) {
     });
     const pollPrScript = makeIntegratorScript({
         real: pollPrFn,
-        stub: runPollStub,
         blockedReason: 'poll-pr',
         mapSuccess: (result) => ({
             eventType: 'pr_polled',
@@ -579,13 +679,11 @@ export function buildSystemScriptRegistry(deps) {
             verdict: result.verdict,
         }),
     });
-    const overrideMergeScript = async ({ runId, decision, ctx, bindingByRef, stepKey, inputs }) => {
-        const integratorInput = buildIntegratorInput(runId, ctx, inputs);
-        const binding = bindingByRef.get(decision.scriptRef) ?? bindingByRef.get('script:integrator');
-        const useReal = !!binding && runnerUsesRealIntegrator(binding.resolvedRunnerId);
+    const overrideMergeScript = async ({ runId, decision, ctx, launchBindings, stepKey, inputs }) => {
+        const integratorInput = buildIntegratorInput(runId, ctx, inputs, scriptGithubAccount(decision, launchBindings));
         let result;
         try {
-            result = useReal ? await overrideMergeFn(integratorInput) : runOverrideStub(integratorInput);
+            result = await overrideMergeFn(integratorInput);
         }
         catch (err) {
             const reason = err instanceof Error ? err.message : String(err);
@@ -597,12 +695,13 @@ export function buildSystemScriptRegistry(deps) {
             return { outcome: 'failed', reason };
         }
         if ('needsHuman' in result) {
+            const pointer = { reason: 'override-merge', lesson: result.lesson, nodeId: decision.nodeId };
             await appendEvent({
                 runId, taskId: ctx.taskId, stepId: '', stepKey: 'pipeline',
                 type: 'pipeline_blocked',
-                payload: { reason: 'override-merge', lesson: result.lesson, nodeId: decision.nodeId },
+                payload: pointer,
             });
-            return { outcome: 'blocked' };
+            return { outcome: 'blocked', pointer };
         }
         if (result.override.replied > 0 || result.override.resolved > 0) {
             await appendEvent({
@@ -628,7 +727,6 @@ export function buildSystemScriptRegistry(deps) {
     };
     const respondThreadsScript = makeIntegratorScript({
         real: respondThreadsFn,
-        stub: runRespondStub,
         blockedReason: 'respond-threads',
         mapSuccess: (result) => ({
             eventType: 'threads_responded',
@@ -642,7 +740,6 @@ export function buildSystemScriptRegistry(deps) {
         ['script:pollPr', pollPrScript],
         ['script:overrideMerge', overrideMergeScript],
         ['script:respondThreads', respondThreadsScript],
-        // Unknown refs fall through to this entry, matching the original else-branch behavior.
         ['script:integrator', integratorScript],
     ]);
 }
@@ -697,6 +794,22 @@ export function makeDataDrivenTask(runStepFn, deps) {
         await appendRunOutput(row);
         return row;
     }
+    async function recordRecoveryContext(runId, node, ordinal, attemptId, payload, outputsByNode) {
+        const row = {
+            runId,
+            nodeId: node.id,
+            ordinal,
+            name: 'recoveryContext',
+            schemaRef: 'schema:recoveryContext',
+            payload,
+            attemptId,
+        };
+        const list = outputsByNode.get(node.id) ?? [];
+        list.push(row);
+        outputsByNode.set(node.id, list);
+        await appendRunOutput(row);
+        return row;
+    }
     return async function dataDrivenTaskImpl(runId, opts) {
         try {
             return await runBody(runId, opts);
@@ -719,7 +832,8 @@ export function makeDataDrivenTask(runStepFn, deps) {
             throw new Error(`PINNED_TEMPLATE_INVALID: ${template.pipelineId} — ${diagnostics.map((d) => d.code).join(', ')}`);
         }
         const { taskId, title, base, issueRef, issueAction } = await loadRunTaskContext(runId);
-        const live = route.roleBindings.some((b) => runnerNeedsLivePreflight(b.resolvedRunnerId));
+        const live = route.roleBindings.some((b) => runnerNeedsLivePreflight(b.resolvedRunnerId)) ||
+            templateRequiresLiveWorktree(template);
         if (live) {
             const pf = await preflightFn(taskId, base);
             if ('needsHuman' in pf) {
@@ -736,22 +850,20 @@ export function makeDataDrivenTask(runStepFn, deps) {
         const bindingByRef = new Map();
         for (const binding of route.roleBindings) {
             bindingByRef.set(`role:${binding.roleId}`, binding);
-            bindingByRef.set(`script:${binding.roleId}`, binding);
             bindingByRef.set(binding.roleId, binding);
-            if (runnerUsesRealIntegrator(binding.resolvedRunnerId) && !bindingByRef.has('script:integrator')) {
-                bindingByRef.set('script:integrator', binding);
-            }
         }
-        const executionProfile = route.executionProfile;
+        const launchBindings = route.launchBindings ?? [];
         let state = initialState(template);
         let lastResult;
         let lastVerdict = '';
         let lastProducedOutput;
+        let recoveryContext;
         let lastFailureReason = '';
         let approvedMergeGateHeadShaValue;
         let stepCount = 0;
         const effectOrdinalByNode = new Map();
         const outputsByNode = new Map();
+        const agentQuestionRetryContextByNode = new Map();
         for (let i = 0; i < MAX_STEPS; i++) {
             const { state: nextState, decision } = coreStep(template, state, lastResult);
             state = nextState;
@@ -760,11 +872,12 @@ export function makeDataDrivenTask(runStepFn, deps) {
                 return await finish(runId, decision.status, lastVerdict, stepCount, lastFailureReason);
             }
             const eff = await applyDecision(decision, {
-                runId, template, state, bindingByRef, executionProfile, taskId, title, base, issueRef, issueAction,
-                effectOrdinalByNode, outputsByNode, runnerRetryPolicy,
+                runId, template, state, bindingByRef, launchBindings, taskId, title, base, issueRef, issueAction,
+                effectOrdinalByNode, outputsByNode, runnerRetryPolicy, agentQuestionRetryContextByNode,
                 live,
                 lastVerdict,
                 lastProducedOutput,
+                recoveryContext,
                 approvedMergeGateHeadSha: approvedMergeGateHeadShaValue,
             });
             stepCount += eff.stepDelta;
@@ -778,6 +891,8 @@ export function makeDataDrivenTask(runStepFn, deps) {
             lastResult = eff.lastResult;
             lastVerdict = eff.lastVerdict ?? lastVerdict;
             lastProducedOutput = eff.producedOutput ?? lastProducedOutput;
+            if ('recoveryContext' in eff)
+                recoveryContext = eff.recoveryContext ?? undefined;
             lastFailureReason = eff.failureReason ?? '';
             if (eff.approvedMergeGateHeadSha !== undefined) {
                 approvedMergeGateHeadShaValue = eff.approvedMergeGateHeadSha ?? undefined;
@@ -785,6 +900,19 @@ export function makeDataDrivenTask(runStepFn, deps) {
         }
         throw new InterpretError(`data-driven ${template.pipelineId} did not terminate within ${MAX_STEPS} steps (template loop bug)`);
     }
+    function forkBranchArrival(decision, branch, seq, status, lastVerdict) {
+        if (status !== 'succeeded') {
+            throw new InterpretError(`fork ${decision.nodeId} branch ${branch.id} completed ${status} before join ${decision.joinId}`);
+        }
+        return {
+            branchId: branch.id,
+            seq,
+            ...(lastVerdict ? { verdict: lastVerdict } : {}),
+        };
+    }
+    function recoveryContextFromEffect(current, effect) {
+        return 'recoveryContext' in effect ? effect.recoveryContext ?? undefined : current;
+    }
     function branchTemplateForJoin(template, joinId) {
         const join = resolveNode(template, joinId);
         if (join.kind !== 'join')
@@ -837,20 +965,14 @@ export function makeDataDrivenTask(runStepFn, deps) {
         let lastResult;
         let lastVerdict = '';
         let lastProducedOutput;
+        let recoveryContext;
         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 } : {}),
-                    },
+                    arrival: forkBranchArrival(decision, branch, seq, next.decision.status, lastVerdict),
                     stepDelta,
                 };
             }
@@ -860,16 +982,16 @@ export function makeDataDrivenTask(runStepFn, deps) {
                 state,
                 lastVerdict,
                 lastProducedOutput,
+                recoveryContext,
             });
             stepDelta += eff.stepDelta;
             if (eff.terminal)
                 return { terminal: eff.terminal, stepDelta };
-            if (eff.stateOverride)
-                state = eff.stateOverride;
+            state = eff.stateOverride ?? state;
             lastResult = eff.lastResult;
-            if (eff.lastVerdict !== undefined)
-                lastVerdict = eff.lastVerdict;
+            lastVerdict = eff.lastVerdict ?? lastVerdict;
             lastProducedOutput = eff.producedOutput ?? lastProducedOutput;
+            recoveryContext = recoveryContextFromEffect(recoveryContext, eff);
         }
         throw new InterpretError(`fork ${decision.nodeId} branch ${branch.id} did not reach join ${decision.joinId} within ${MAX_STEPS} steps`);
     }
@@ -890,8 +1012,17 @@ export function makeDataDrivenTask(runStepFn, deps) {
                     return { lastResult: { outcome: 'failed', errorCode: REVO_INPUT_MISSING }, lastVerdict: 'failed', failureReason: reason, stepDelta: 1 };
                 }
                 const result = await invokeRole(runId, decision, node, ctx, resolved.inputs, stepKey);
+                if ('question' in result) {
+                    ctx.agentQuestionRetryContextByNode.set(node.id, result.retryContext);
+                    return {
+                        lastResult: undefined,
+                        stateOverride: reopenNodeState(ctx.state, node.id),
+                        stepDelta: result.attemptsMade,
+                    };
+                }
                 if ('blocked' in result) {
                     if (result.recovery) {
+                        ctx.agentQuestionRetryContextByNode.delete(node.id);
                         const recovery = await awaitVerificationRecoveryGate(runId, ctx, result.recovery);
                         return {
                             lastResult: undefined,
@@ -903,6 +1034,22 @@ export function makeDataDrivenTask(runStepFn, deps) {
                             stepDelta: result.attemptsMade,
                         };
                     }
+                    if (result.retry?.attemptsExhausted) {
+                        const retryOutcome = await awaitTransientRetryGate(runId, ctx, {
+                            node,
+                            stepKey,
+                            binding: resolveRoleBinding(ctx, decision),
+                            retry: result.retry,
+                        });
+                        if (retryOutcome === 'retry') {
+                            return {
+                                lastResult: undefined,
+                                stateOverride: reopenNodeState(ctx.state, node.id),
+                                stepDelta: result.attemptsMade,
+                            };
+                        }
+                    }
+                    ctx.agentQuestionRetryContextByNode.delete(node.id);
                     return {
                         lastResult: undefined,
                         terminal: {
@@ -915,6 +1062,7 @@ export function makeDataDrivenTask(runStepFn, deps) {
                     };
                 }
                 if (result.failed) {
+                    ctx.agentQuestionRetryContextByNode.delete(node.id);
                     await appendEvent({
                         runId, taskId, stepId: '', stepKey, type: 'step_failed',
                         idempotencyKey: result.attemptId,
@@ -922,12 +1070,14 @@ export function makeDataDrivenTask(runStepFn, deps) {
                     });
                     return { lastResult: { outcome: 'failed', errorCode: result.errorCode }, lastVerdict: 'failed', failureReason: result.reason, stepDelta: result.attemptsMade };
                 }
+                ctx.agentQuestionRetryContextByNode.delete(node.id);
                 const producedOutput = await recordOutput(runId, node, ordinal, result.attemptId, result.output, ctx.outputsByNode);
                 const verdict = result.verdict;
                 return {
                     lastResult: { outcome: 'succeeded', ...(verdict ? { verdict } : {}) },
                     ...(verdict ? { lastVerdict: verdict } : {}),
                     ...(producedOutput ? { producedOutput } : {}),
+                    ...(ctx.recoveryContext ? { recoveryContext: recoveryContextAfterNode(node.id, ctx.recoveryContext) } : {}),
                     stepDelta: result.attemptsMade,
                 };
             }
@@ -943,13 +1093,21 @@ export function makeDataDrivenTask(runStepFn, deps) {
                     });
                     return { lastResult: { outcome: 'failed', errorCode: REVO_INPUT_MISSING }, lastVerdict: 'failed', failureReason: reason, stepDelta: 1 };
                 }
-                const scriptResult = await invokeScript(runId, decision, { taskId, title, base, issueRef: ctx.issueRef, issueAction: ctx.issueAction }, bindingByRef, stepKeyFor(node.id, ordinal), resolved.inputs);
+                const scriptResult = await invokeScript(runId, decision, { taskId, title, base, issueRef: ctx.issueRef, issueAction: ctx.issueAction }, bindingByRef, ctx.launchBindings, stepKeyFor(node.id, ordinal), resolved.inputs);
                 if (scriptResult.outcome === 'blocked') {
-                    return { lastResult: { outcome: 'failed', errorCode: REVO_SCRIPT_BLOCKED }, lastVerdict: 'blocked', stepDelta: 1 };
+                    const recoveryContext = scriptResult.pointer === undefined
+                        ? undefined
+                        : await recordRecoveryContext(runId, node, ordinal, stepKeyFor(node.id, ordinal), scriptResult.pointer, ctx.outputsByNode);
+                    return {
+                        lastResult: { outcome: 'failed', errorCode: REVO_SCRIPT_BLOCKED },
+                        lastVerdict: 'blocked',
+                        ...(recoveryContext ? { recoveryContext } : {}),
+                        stepDelta: 1,
+                    };
                 }
                 if (scriptResult.outcome === 'failed') {
                     const reason = scriptResult.reason ? `${REVO_SCRIPT_FAILED}: ${scriptResult.reason}` : REVO_SCRIPT_FAILED;
-                    return { lastResult: { outcome: 'failed', errorCode: REVO_SCRIPT_FAILED }, lastVerdict: 'failed', failureReason: reason, stepDelta: 1 };
+                    return { lastResult: { outcome: 'failed', errorCode: REVO_SCRIPT_FAILED }, lastVerdict: 'failed', recoveryContext: null, failureReason: reason, stepDelta: 1 };
                 }
                 let pointer = scriptResult.pointer;
                 let sv = scriptResult.verdict;
@@ -965,6 +1123,7 @@ export function makeDataDrivenTask(runStepFn, deps) {
                     lastResult: stateOverride ? undefined : { outcome: 'succeeded', ...(sv ? { verdict: sv } : {}) },
                     ...(sv ? { lastVerdict: sv } : {}),
                     ...(producedOutput ? { producedOutput } : {}),
+                    ...(ctx.recoveryContext ? { recoveryContext: recoveryContextAfterNode(node.id, ctx.recoveryContext) } : {}),
                     ...(stateOverride ? { stateOverride } : {}),
                     stepDelta: 1,
                 };
@@ -972,7 +1131,7 @@ export function makeDataDrivenTask(runStepFn, deps) {
             case 'awaitGate': {
                 const topic = gateTopicFor(decision.reason);
                 const ordinal = nextOrdinal(ctx.effectOrdinalByNode, decision.nodeId);
-                const summary = buildGateSummary(decision, ctx.outputsByNode, ctx.lastVerdict, ctx.lastProducedOutput);
+                const summary = buildGateSummary(decision, ctx.outputsByNode, ctx.lastVerdict, ctx.lastProducedOutput, ctx.recoveryContext);
                 const human = await awaitHuman(runId, topic, stepKeyFor(decision.nodeId, ordinal), `${decision.reason} approval`, summary, decision.outcomes);
                 const verdict = gateVerdict(human, decision.outcomes);
                 const approvedHeadSha = approvedMergeGateHeadSha(decision, verdict, summary);
@@ -981,6 +1140,7 @@ export function makeDataDrivenTask(runStepFn, deps) {
                     lastResult: verdict ? { verdict } : {},
                     ...(verdict ? { lastVerdict: verdict } : {}),
                     ...(producedOutput ? { producedOutput } : {}),
+                    ...(decision.nodeId === 'recoveryGate' ? { recoveryContext: null } : {}),
                     ...(approvedHeadSha !== undefined ? { approvedMergeGateHeadSha: approvedHeadSha } : {}),
                     stepDelta: 0,
                 };
@@ -1000,9 +1160,43 @@ export function makeDataDrivenTask(runStepFn, deps) {
                 return { lastResult: {}, stepDelta: 0 };
         }
     }
+    async function awaitTransientRetryGate(runId, ctx, input) {
+        const outcomes = [...TRANSIENT_RETRY_GATE_OUTCOMES];
+        const decision = await awaitHuman(runId, 'retry', `transientRetry:${input.stepKey}`, `Retry ${input.node.id} after transient runner failure`, {
+            kind: 'transient_retry',
+            runId,
+            taskId: ctx.taskId,
+            nodeId: input.node.id,
+            step: input.stepKey,
+            role: input.binding.rowId,
+            runner: input.binding.resolvedRunnerId,
+            reason: input.retry.reason,
+            lesson: input.retry.lesson,
+            attemptsExhausted: input.retry.attemptsExhausted,
+            attemptsMade: input.retry.attemptsMade,
+            maxAttempts: input.retry.maxAttempts,
+            attemptIds: input.retry.attemptIds,
+            lastAttemptId: input.retry.lastAttemptId,
+            ...(input.retry.failureKind ? { failureKind: input.retry.failureKind } : {}),
+            ...(input.retry.transientKind ? { transientKind: input.retry.transientKind } : {}),
+            ...(input.retry.timing !== undefined ? { timing: input.retry.timing } : {}),
+            reconcile: { default: 'keep', supported: ['keep'] },
+            outcomes,
+        }, outcomes);
+        return transientRetryGateOutcome(decision);
+    }
     async function invokeRole(runId, decision, node, ctx, inputs, stepKey) {
         const binding = resolveRoleBinding(ctx, decision);
-        return invokeRoleAttempts({ runId, decision, node, ctx, inputs, stepKey, binding });
+        return invokeRoleAttempts({
+            runId,
+            decision,
+            node,
+            ctx,
+            inputs,
+            stepKey,
+            binding,
+            retryContext: ctx.agentQuestionRetryContextByNode.get(node.id),
+        });
     }
     function resolveRoleBinding(ctx, decision) {
         const binding = ctx.bindingByRef.get(decision.roleRef);
@@ -1014,21 +1208,24 @@ export function makeDataDrivenTask(runStepFn, deps) {
     async function invokeRoleAttempts(input) {
         const { runId, decision, node, ctx, inputs, stepKey, binding } = input;
         const attemptIds = [];
+        const retryContext = input.retryContext;
         for (let attemptNo = 1; attemptNo <= ctx.runnerRetryPolicy.maxAttempts; attemptNo++) {
             const physicalAttempt = physicalAttemptFor(runId, stepKey, attemptNo);
             attemptIds.push(physicalAttempt.attemptId);
-            const launchOverrides = resolveLaunchOverrides(binding, decision.nodeId, ctx.executionProfile);
-            const result = await runStepFn(runId, binding.rowId, stepKey, stepInputForAttempt(decision.nodeId, inputs, physicalAttempt), binding.resolvedRunnerId, ctx.executionProfile, physicalAttempt, ctx.template.verdicts.domain, launchOverrides);
+            const launchOverrides = resolveLaunchOverrides(binding, decision.nodeId, ctx.launchBindings);
+            const result = await runStepFn(runId, binding.rowId, stepKey, stepInputForAttempt(decision.nodeId, inputs, physicalAttempt, retryContext), binding.resolvedRunnerId, physicalAttempt, ctx.template.verdicts.domain, launchOverrides);
             const needsHuman = await maybeHandleNeedsHumanRoleResult({
                 ...input,
                 attemptIds,
                 physicalAttempt,
                 result,
             });
-            if (needsHuman === 'retry')
-                continue;
-            if (needsHuman)
+            if (needsHuman) {
+                if ('action' in needsHuman) {
+                    continue;
+                }
                 return needsHuman;
+            }
             const failed = roleValidationFailure(ctx.template, node, result, physicalAttempt);
             if (failed)
                 return failed;
@@ -1089,17 +1286,57 @@ export function makeDataDrivenTask(runStepFn, deps) {
             }
             const transient = transientRunnerFailure(result);
             if (transient === undefined) {
-                return {
-                    blocked: true,
-                    reason: 'agent-needs-human',
-                    lesson: safeLesson,
-                    attemptsMade: physicalAttempt.attemptNo,
-                };
+                const question = await awaitAgentQuestion({ ...input, safeLesson, physicalAttempt });
+                if ('unresolved' in question) {
+                    return {
+                        blocked: true,
+                        reason: question.reason,
+                        lesson: question.lesson,
+                        attemptsMade: physicalAttempt.attemptNo,
+                    };
+                }
+                return { question: true, retryContext: question, attemptsMade: physicalAttempt.attemptNo };
             }
             return handleTransientRoleResult({ ...input, transient });
         }
         return undefined;
     }
+    async function awaitAgentQuestion(input) {
+        const { runId, node, ctx, stepKey, binding, physicalAttempt, safeLesson } = input;
+        const question = await awaitHuman(runId, 'question', `agentQuestion:${stepKey}:attempt${physicalAttempt.attemptNo}`, `${node.id} question`, {
+            kind: 'agent_question',
+            runId,
+            taskId: ctx.taskId,
+            nodeId: node.id,
+            step: stepKey,
+            role: binding.rowId,
+            runner: binding.resolvedRunnerId,
+            lesson: safeLesson,
+            attemptId: physicalAttempt.attemptId,
+        }, undefined, 'question');
+        const retryContext = agentQuestionRetryContext(question, node.id, safeLesson);
+        if (retryContext === undefined) {
+            return {
+                unresolved: true,
+                reason: 'agent-question-unresolved',
+                lesson: unresolvedAgentQuestionLesson(node.id, safeLesson, question),
+            };
+        }
+        await appendEvent({
+            runId,
+            taskId: ctx.taskId,
+            stepId: '',
+            stepKey,
+            type: 'agent_question_resolved',
+            idempotencyKey: `${physicalAttempt.attemptId}:question`,
+            payload: {
+                nodeId: node.id,
+                inboxId: retryContext.inboxId,
+                resolvedBy: retryContext.resolvedBy,
+            },
+        });
+        return retryContext;
+    }
     async function handleTransientRoleResult(input) {
         const { runId, node, ctx, stepKey, attemptIds, physicalAttempt, transient } = input;
         const policy = ctx.runnerRetryPolicy;
@@ -1117,7 +1354,7 @@ export function makeDataDrivenTask(runStepFn, deps) {
             });
             if (policy.backoffMs > 0)
                 await deps.sleep(policy.backoffMs);
-            return 'retry';
+            return { action: 'retry' };
         }
         const retry = runnerRetryBlockPayload({
             transient,
@@ -1240,9 +1477,21 @@ export function makeDataDrivenTask(runStepFn, deps) {
             lesson: `Human selected ${outcome}; recovery is recorded but no Revo worktree patch was adopted by the main session.`,
         };
     }
-    async function invokeScript(runId, decision, ctx, bindingByRef, stepKey, inputs) {
-        const handler = scriptRegistry.get(decision.scriptRef) ?? scriptRegistry.get('script:integrator');
-        return handler({ runId, decision, ctx, bindingByRef, stepKey, inputs });
+    async function invokeScript(runId, decision, ctx, bindingByRef, launchBindings, stepKey, inputs) {
+        const handler = scriptRegistry.get(decision.scriptRef);
+        if (!handler) {
+            const reason = `script handler is not registered: ${decision.scriptRef}`;
+            await appendEvent({
+                runId,
+                taskId: ctx.taskId,
+                stepId: '',
+                stepKey,
+                type: 'step_failed',
+                payload: { scriptRef: decision.scriptRef, error: reason },
+            });
+            return { outcome: 'failed', reason };
+        }
+        return handler({ runId, decision, ctx, bindingByRef, launchBindings, stepKey, inputs });
     }
     async function finish(runId, status, verdict, steps, failureReason = '') {
         if (status === 'succeeded') {