@exaudeus/workrail 3.74.1 → 3.74.2

package/dist/daemon/workflow-runner.d.ts

@@ -120,8 +120,6 @@ export interface WorkflowDeliveryFailed {
 }
 export type WorkflowRunResult = WorkflowRunSuccess | WorkflowRunError | WorkflowRunTimeout | WorkflowRunStuck | WorkflowDeliveryFailed;
 export type ChildWorkflowRunResult = WorkflowRunSuccess | WorkflowRunError | WorkflowRunTimeout | WorkflowRunStuck;
-export type SteerRegistry = Map<string, (text: string) => void>;
-export type AbortRegistry = Map<string, () => void>;
 export interface OrphanedSession {
     readonly sessionId: string;
     readonly continueToken: string;
@@ -159,6 +157,14 @@ export declare function buildAgentClient(trigger: WorkflowTrigger, apiKey: strin
     agentClient: Anthropic | AnthropicBedrock;
     modelId: string;
 };
+export type TerminalSignal = {
+    readonly kind: 'stuck';
+    readonly reason: 'repeated_tool_call' | 'no_progress' | 'stall';
+} | {
+    readonly kind: 'timeout';
+    readonly reason: 'wall_clock' | 'max_turns';
+};
+export declare function setTerminalSignal(state: SessionState, signal: TerminalSignal): boolean;
 export interface SessionState {
     isComplete: boolean;
     lastStepNotes: string | undefined;
@@ -172,8 +178,7 @@ export interface SessionState {
     }>;
     issueSummaries: string[];
     pendingSteerParts: string[];
-    stuckReason: 'repeated_tool_call' | 'no_progress' | 'stall' | null;
-    timeoutReason: 'wall_clock' | 'max_turns' | null;
+    terminalSignal: TerminalSignal | null;
     turnCount: number;
 }
 export declare function createSessionState(initialToken: string): SessionState;
@@ -221,6 +226,8 @@ export type PreAgentSessionResult = {
 } | {
     readonly kind: 'complete';
     readonly result: WorkflowRunResult;
+    readonly workrailSessionId: string | null;
+    readonly handle: SessionHandle | undefined;
 };
 export interface AgentReadySession {
     readonly preAgentSession: PreAgentSession;

package/dist/daemon/workflow-runner.js

@@ -50,6 +50,7 @@ exports.buildSystemPrompt = buildSystemPrompt;
 exports.tagToStatsOutcome = tagToStatsOutcome;
 exports.sidecardLifecycleFor = sidecardLifecycleFor;
 exports.buildAgentClient = buildAgentClient;
+exports.setTerminalSignal = setTerminalSignal;
 exports.createSessionState = createSessionState;
 exports.evaluateStuckSignals = evaluateStuckSignals;
 exports.finalizeSession = finalizeSession;
@@ -880,6 +881,13 @@ function buildAgentClient(trigger, apiKey, env) {
         modelId: 'claude-sonnet-4-6',
     };
 }
+function setTerminalSignal(state, signal) {
+    if (state.terminalSignal === null) {
+        state.terminalSignal = signal;
+        return true;
+    }
+    return false;
+}
 function createSessionState(initialToken) {
     return {
         isComplete: false,
@@ -891,13 +899,12 @@ function createSessionState(initialToken) {
         lastNToolCalls: [],
         issueSummaries: [],
         pendingSteerParts: [],
-        stuckReason: null,
-        timeoutReason: null,
+        terminalSignal: null,
         turnCount: 0,
     };
 }
 function evaluateStuckSignals(state, config) {
-    if (config.maxTurns > 0 && state.turnCount >= config.maxTurns && state.timeoutReason === null) {
+    if (config.maxTurns > 0 && state.turnCount >= config.maxTurns && state.terminalSignal === null) {
         return { kind: 'max_turns_exceeded' };
     }
     if (state.lastNToolCalls.length === config.stuckRepeatThreshold &&
@@ -913,8 +920,8 @@ function evaluateStuckSignals(state, config) {
         state.stepAdvanceCount === 0) {
         return { kind: 'no_progress', turnCount: state.turnCount, maxTurns: config.maxTurns };
     }
-    if (state.timeoutReason !== null) {
-        return { kind: 'timeout_imminent', timeoutReason: state.timeoutReason };
+    if (state.terminalSignal?.kind === 'timeout') {
+        return { kind: 'timeout_imminent', timeoutReason: state.terminalSignal.reason };
     }
     return null;
 }
@@ -1004,8 +1011,7 @@ async function buildPreAgentSession(trigger, ctx, apiKey, sessionId, startMs, st
     }
     catch (e) {
         const message = e instanceof Error ? e.message : String(e);
-        writeExecutionStats(statsDir, sessionId, trigger.workflowId, startMs, 'error', 0);
-        return { kind: 'complete', result: { _tag: 'error', workflowId: trigger.workflowId, message, stopReason: 'error' } };
+        return { kind: 'complete', result: { _tag: 'error', workflowId: trigger.workflowId, message, stopReason: 'error' }, workrailSessionId: null, handle: undefined };
     }
     const state = createSessionState('');
     let continueToken;
@@ -1023,7 +1029,6 @@ async function buildPreAgentSession(trigger, ctx, apiKey, sessionId, startMs, st
     else {
         const startResult = await (0, start_js_1.executeStartWorkflow)({ workflowId: trigger.workflowId, workspacePath: trigger.workspacePath, goal: trigger.goal }, ctx, { is_autonomous: 'true', workspacePath: trigger.workspacePath, triggerSource: 'daemon' });
         if (startResult.isErr()) {
-            writeExecutionStats(statsDir, sessionId, trigger.workflowId, startMs, 'error', 0);
             return {
                 kind: 'complete',
                 result: {
@@ -1032,6 +1037,8 @@ async function buildPreAgentSession(trigger, ctx, apiKey, sessionId, startMs, st
                     message: `start_workflow failed: ${startResult.error.kind} -- ${JSON.stringify(startResult.error)}`,
                     stopReason: 'error',
                 },
+                workrailSessionId: null,
+                handle: undefined,
             };
         }
         const r = startResult.value.response;
@@ -1057,7 +1064,6 @@ async function buildPreAgentSession(trigger, ctx, apiKey, sessionId, startMs, st
             workspacePath: trigger.workspacePath,
         });
         if (persistResult.kind === 'err') {
-            writeExecutionStats(statsDir, sessionId, trigger.workflowId, startMs, 'error', 0);
             return {
                 kind: 'complete',
                 result: {
@@ -1066,6 +1072,8 @@ async function buildPreAgentSession(trigger, ctx, apiKey, sessionId, startMs, st
                     message: `Initial token persist failed: ${persistResult.error.code} -- ${persistResult.error.message}`,
                     stopReason: 'error',
                 },
+                workrailSessionId: state.workrailSessionId,
+                handle: undefined,
             };
         }
     }
@@ -1097,7 +1105,6 @@ async function buildPreAgentSession(trigger, ctx, apiKey, sessionId, startMs, st
                     await execFileAsync('git', ['-C', trigger.workspacePath, 'worktree', 'remove', '--force', sessionWorkspacePath]);
                 }
                 catch { }
-                writeExecutionStats(statsDir, sessionId, trigger.workflowId, startMs, 'error', 0);
                 return {
                     kind: 'complete',
                     result: {
@@ -1106,6 +1113,8 @@ async function buildPreAgentSession(trigger, ctx, apiKey, sessionId, startMs, st
                         message: `Worktree sidecar persist failed: ${worktreePersistResult.error.code} -- ${worktreePersistResult.error.message}`,
                         stopReason: 'error',
                     },
+                    workrailSessionId: state.workrailSessionId,
+                    handle: undefined,
                 };
             }
             console.log(`[WorkflowRunner] Worktree created: sessionId=${sessionId} branch=${branchPrefix}${sessionId} path=${sessionWorkspacePath}`);
@@ -1113,10 +1122,11 @@ async function buildPreAgentSession(trigger, ctx, apiKey, sessionId, startMs, st
         catch (e) {
             const errMsg = e instanceof Error ? e.message : String(e);
             console.error(`[WorkflowRunner] Worktree creation failed: sessionId=${sessionId} error=${errMsg}`);
-            writeExecutionStats(statsDir, sessionId, trigger.workflowId, startMs, 'error', 0);
             return {
                 kind: 'complete',
                 result: { _tag: 'error', workflowId: trigger.workflowId, message: `Worktree creation failed: ${errMsg}`, stopReason: 'error' },
+                workrailSessionId: state.workrailSessionId,
+                handle: undefined,
             };
         }
     }
@@ -1126,16 +1136,6 @@ async function buildPreAgentSession(trigger, ctx, apiKey, sessionId, startMs, st
         handle = activeSessionSet?.register(state.workrailSessionId, (text) => { state.pendingSteerParts.push(text); });
     }
     if (isComplete) {
-        const lifecycle = sidecardLifecycleFor('success', trigger.branchStrategy);
-        if (lifecycle.kind === 'delete_now') {
-            await fs.unlink(path.join(sessionsDir, `${sessionId}.json`)).catch(() => { });
-        }
-        emitter?.emit({ kind: 'session_completed', sessionId, workflowId: trigger.workflowId, outcome: 'success', detail: 'stop', ...(0, _shared_js_1.withWorkrailSession)(state.workrailSessionId) });
-        if (state.workrailSessionId !== null) {
-            daemonRegistry?.unregister(state.workrailSessionId, 'completed');
-            handle?.dispose();
-        }
-        writeExecutionStats(statsDir, sessionId, trigger.workflowId, startMs, 'success', 0);
         return {
             kind: 'complete',
             result: {
@@ -1146,6 +1146,8 @@ async function buildPreAgentSession(trigger, ctx, apiKey, sessionId, startMs, st
                 ...(sessionWorktreePath !== undefined ? { sessionId } : {}),
                 ...(trigger.botIdentity !== undefined ? { botIdentity: trigger.botIdentity } : {}),
             },
+            workrailSessionId: state.workrailSessionId,
+            handle,
         };
     }
     return {
@@ -1169,14 +1171,13 @@ async function buildPreAgentSession(trigger, ctx, apiKey, sessionId, startMs, st
         },
     };
 }
-function constructTools(session, ctx, apiKey, schemas, scope) {
-    const { state, sessionWorkspacePath, spawnCurrentDepth, spawnMaxDepth } = session;
-    const { fileTracker, onAdvance, onComplete, emitter, activeSessionSet, maxIssueSummaries } = scope;
+function constructTools(ctx, apiKey, schemas, scope) {
+    const { fileTracker, onAdvance, onComplete, onTokenUpdate, onIssueReported, getCurrentToken, sessionWorkspacePath, spawnCurrentDepth, spawnMaxDepth, emitter, activeSessionSet, } = scope;
     const sid = scope.sessionId;
     const workrailSid = scope.workrailSessionId;
     const readFileStateMap = fileTracker.toMap();
     return [
-        (0, continue_workflow_js_1.makeCompleteStepTool)(sid, ctx, () => state.currentContinueToken, onAdvance, onComplete, (t) => { state.currentContinueToken = t; }, schemas, index_js_1.executeContinueWorkflow, emitter, workrailSid),
+        (0, continue_workflow_js_1.makeCompleteStepTool)(sid, ctx, getCurrentToken, onAdvance, onComplete, onTokenUpdate, schemas, index_js_1.executeContinueWorkflow, emitter, workrailSid),
         (0, continue_workflow_js_1.makeContinueWorkflowTool)(sid, ctx, onAdvance, onComplete, schemas, index_js_1.executeContinueWorkflow, emitter, workrailSid),
         (0, bash_js_1.makeBashTool)(sessionWorkspacePath, schemas, sid, emitter, workrailSid),
         (0, file_tools_js_1.makeReadTool)(sessionWorkspacePath, readFileStateMap, schemas, sid, emitter, workrailSid),
@@ -1184,11 +1185,7 @@ function constructTools(session, ctx, apiKey, schemas, scope) {
         (0, glob_grep_js_1.makeGlobTool)(sessionWorkspacePath, schemas, sid, emitter, workrailSid),
         (0, glob_grep_js_1.makeGrepTool)(sessionWorkspacePath, schemas, sid, emitter, workrailSid),
         (0, file_tools_js_1.makeEditTool)(sessionWorkspacePath, readFileStateMap, schemas, sid, emitter, workrailSid),
-        (0, report_issue_js_1.makeReportIssueTool)(sid, emitter, workrailSid, undefined, (summary) => {
-            if (state.issueSummaries.length < maxIssueSummaries) {
-                state.issueSummaries.push(summary);
-            }
-        }),
+        (0, report_issue_js_1.makeReportIssueTool)(sid, emitter, workrailSid, undefined, onIssueReported),
         (0, spawn_agent_js_1.makeSpawnAgentTool)(sid, ctx, apiKey, workrailSid ?? '', spawnCurrentDepth, spawnMaxDepth, runWorkflow, schemas, emitter, activeSessionSet),
         (0, signal_coordinator_js_1.makeSignalCoordinatorTool)(sid, emitter, workrailSid),
     ];
@@ -1207,7 +1204,7 @@ function buildTurnEndSubscriber(ctx) {
         const signal = evaluateStuckSignals(ctx.state, ctx.stuckConfig);
         if (signal !== null) {
             if (signal.kind === 'max_turns_exceeded') {
-                ctx.state.timeoutReason = 'max_turns';
+                setTerminalSignal(ctx.state, { kind: 'timeout', reason: 'max_turns' });
                 ctx.emitter?.emit({ kind: 'agent_stuck', sessionId: ctx.sessionId, reason: 'timeout_imminent', detail: 'Max-turn limit reached', ...(0, _shared_js_1.withWorkrailSession)(ctx.state.workrailSessionId) });
                 ctx.agent.abort();
                 return;
@@ -1215,20 +1212,22 @@ function buildTurnEndSubscriber(ctx) {
             else if (signal.kind === 'repeated_tool_call') {
                 ctx.emitter?.emit({ kind: 'agent_stuck', sessionId: ctx.sessionId, reason: 'repeated_tool_call', detail: `Same tool+args called ${ctx.stuckRepeatThreshold} times: ${signal.toolName}`, toolName: signal.toolName, argsSummary: signal.argsSummary, ...(0, _shared_js_1.withWorkrailSession)(ctx.state.workrailSessionId) });
                 void writeStuckOutboxEntry({ workflowId: ctx.workflowId, reason: 'repeated_tool_call', ...(ctx.state.issueSummaries.length > 0 ? { issueSummaries: [...ctx.state.issueSummaries] } : {}) });
-                if (ctx.stuckConfig.stuckAbortPolicy !== 'notify_only' && ctx.state.stuckReason === null && ctx.state.timeoutReason === null) {
-                    ctx.state.stuckReason = 'repeated_tool_call';
-                    ctx.agent.abort();
-                    return;
+                if (ctx.stuckConfig.stuckAbortPolicy !== 'notify_only') {
+                    if (setTerminalSignal(ctx.state, { kind: 'stuck', reason: 'repeated_tool_call' })) {
+                        ctx.agent.abort();
+                        return;
+                    }
                 }
             }
             else if (signal.kind === 'no_progress') {
                 ctx.emitter?.emit({ kind: 'agent_stuck', sessionId: ctx.sessionId, reason: 'no_progress', detail: `${signal.turnCount} turns used, 0 step advances (${signal.maxTurns} turn limit)`, ...(0, _shared_js_1.withWorkrailSession)(ctx.state.workrailSessionId) });
                 if (ctx.stuckConfig.noProgressAbortEnabled) {
                     void writeStuckOutboxEntry({ workflowId: ctx.workflowId, reason: 'no_progress', ...(ctx.state.issueSummaries.length > 0 ? { issueSummaries: [...ctx.state.issueSummaries] } : {}) });
-                    if (ctx.stuckConfig.stuckAbortPolicy !== 'notify_only' && ctx.state.stuckReason === null && ctx.state.timeoutReason === null) {
-                        ctx.state.stuckReason = 'no_progress';
-                        ctx.agent.abort();
-                        return;
+                    if (ctx.stuckConfig.stuckAbortPolicy !== 'notify_only') {
+                        if (setTerminalSignal(ctx.state, { kind: 'stuck', reason: 'no_progress' })) {
+                            ctx.agent.abort();
+                            return;
+                        }
                     }
                 }
             }
@@ -1264,7 +1263,7 @@ function buildAgentCallbacks(sessionId, state, modelId, emitter, stuckRepeatThre
             emitter?.emit({ kind: 'tool_call_failed', sessionId, toolName, durationMs, errorMessage, ...(0, _shared_js_1.withWorkrailSession)(state.workrailSessionId) });
         },
         onStallDetected: () => {
-            state.stuckReason = 'stall';
+            setTerminalSignal(state, { kind: 'stuck', reason: 'stall' });
             emitter?.emit({
                 kind: 'agent_stuck',
                 sessionId,
@@ -1281,27 +1280,31 @@ function buildAgentCallbacks(sessionId, state, modelId, emitter, stuckRepeatThre
     };
 }
 function buildSessionResult(state, stopReason, errorMessage, trigger, sessionId, sessionWorktreePath) {
-    if (state.stuckReason !== null) {
-        return {
-            _tag: 'stuck',
-            workflowId: trigger.workflowId,
-            reason: state.stuckReason,
-            message: `Session aborted: stuck heuristic fired (${state.stuckReason})`,
-            stopReason: 'aborted',
-            ...(state.issueSummaries.length > 0 ? { issueSummaries: [...state.issueSummaries] } : {}),
-        };
-    }
-    if (state.timeoutReason !== null) {
-        const limitDescription = state.timeoutReason === 'wall_clock'
-            ? `${trigger.agentConfig?.maxSessionMinutes ?? exports.DEFAULT_SESSION_TIMEOUT_MINUTES} minutes`
-            : `${trigger.agentConfig?.maxTurns ?? exports.DEFAULT_MAX_TURNS} turns`;
-        return {
-            _tag: 'timeout',
-            workflowId: trigger.workflowId,
-            reason: state.timeoutReason,
-            message: `Workflow ${state.timeoutReason === 'wall_clock' ? 'timed out' : 'exceeded turn limit'} after ${limitDescription}`,
-            stopReason: 'aborted',
-        };
+    if (state.terminalSignal !== null) {
+        const signal = state.terminalSignal;
+        if (signal.kind === 'stuck') {
+            return {
+                _tag: 'stuck',
+                workflowId: trigger.workflowId,
+                reason: signal.reason,
+                message: `Session aborted: stuck heuristic fired (${signal.reason})`,
+                stopReason: 'aborted',
+                ...(state.issueSummaries.length > 0 ? { issueSummaries: [...state.issueSummaries] } : {}),
+            };
+        }
+        if (signal.kind === 'timeout') {
+            const limitDescription = signal.reason === 'wall_clock'
+                ? `${trigger.agentConfig?.maxSessionMinutes ?? exports.DEFAULT_SESSION_TIMEOUT_MINUTES} minutes`
+                : `${trigger.agentConfig?.maxTurns ?? exports.DEFAULT_MAX_TURNS} turns`;
+            return {
+                _tag: 'timeout',
+                workflowId: trigger.workflowId,
+                reason: signal.reason,
+                message: `Workflow ${signal.reason === 'wall_clock' ? 'timed out' : 'exceeded turn limit'} after ${limitDescription}`,
+                stopReason: 'aborted',
+            };
+        }
+        return (0, assert_never_js_1.assertNever)(signal);
     }
     if (stopReason === 'error' || errorMessage) {
         const errMsg = errorMessage ?? 'Agent stopped with error reason';
@@ -1359,14 +1362,24 @@ async function buildAgentReadySession(preAgentSession, trigger, ctx, apiKey, ses
         fileTracker: new session_scope_js_1.DefaultFileStateTracker(preAgentSession.readFileState),
         onAdvance,
         onComplete,
+        onTokenUpdate: (t) => { state.currentContinueToken = t; },
+        onIssueReported: (summary) => {
+            if (state.issueSummaries.length < MAX_ISSUE_SUMMARIES) {
+                state.issueSummaries.push(summary);
+            }
+        },
+        onSteer: (text) => { state.pendingSteerParts.push(text); },
+        getCurrentToken: () => state.currentContinueToken,
+        sessionWorkspacePath,
+        spawnCurrentDepth: preAgentSession.spawnCurrentDepth,
+        spawnMaxDepth: preAgentSession.spawnMaxDepth,
         workrailSessionId: state.workrailSessionId,
         emitter,
         sessionId,
         workflowId: trigger.workflowId,
         activeSessionSet,
-        maxIssueSummaries: MAX_ISSUE_SUMMARIES,
     };
-    const tools = constructTools(preAgentSession, ctx, apiKey, schemas, scope);
+    const tools = constructTools(ctx, apiKey, schemas, scope);
     const contextLoader = new context_loader_js_1.DefaultContextLoader(loadDaemonSoul, loadWorkspaceContext, loadSessionNotes, ctx);
     const baseCtx = await contextLoader.loadBase(trigger);
     const contextBundle = await contextLoader.loadSession(startContinueToken, baseCtx);
@@ -1430,9 +1443,7 @@ async function runAgentLoop(session, trigger, conversationPath) {
     try {
         const timeoutPromise = new Promise((_, reject) => {
             timeoutHandle = setTimeout(() => {
-                if (state.timeoutReason === null) {
-                    state.timeoutReason = 'wall_clock';
-                }
+                setTerminalSignal(state, { kind: 'timeout', reason: 'wall_clock' });
                 reject(new Error('Workflow timed out'));
             }, sessionTimeoutMs);
         });
@@ -1486,6 +1497,21 @@ async function runWorkflow(trigger, ctx, apiKey, daemonRegistry, emitter, active
     });
     const preResult = await buildPreAgentSession(trigger, ctx, apiKey, sessionId, startMs, statsDir, sessionsDir, emitter, daemonRegistry, activeSessionSet, source);
     if (preResult.kind === 'complete') {
+        const earlyCtx = {
+            sessionId,
+            workrailSessionId: preResult.workrailSessionId,
+            startMs,
+            stepAdvanceCount: 0,
+            branchStrategy: trigger.branchStrategy,
+            statsDir,
+            sessionsDir,
+            conversationPath: path.join(sessionsDir, `${sessionId}-conversation.jsonl`),
+            emitter,
+            daemonRegistry,
+            workflowId: trigger.workflowId,
+        };
+        preResult.handle?.dispose();
+        await finalizeSession(preResult.result, earlyCtx);
         return preResult.result;
     }
     const readySession = await buildAgentReadySession(preResult.session, trigger, ctx, apiKey, sessionId, emitter, daemonRegistry, activeSessionSet);

package/dist/manifest.json

@@ -142,8 +142,8 @@
       "bytes": 1507
     },
     "application/services/workflow-interpreter.js": {
-      "sha256": "860a147051cb6cf36720c18a30c5c6f62c7868c4dd9a0f98e413fda0b0d205a5",
-      "bytes": 22145
+      "sha256": "b340f4e4c2b54b2c9ac97c99b5e67b11d472a3d16944bf77b16badb7d887b088",
+      "bytes": 23716
     },
     "application/services/workflow-service.d.ts": {
       "sha256": "c9c9e2ab4396c46da0f12af93133ca1e7da94bdc88f67a074d8f6c43ef0a5b3b",
@@ -473,8 +473,8 @@
       "sha256": "5fe866e54f796975dec5d8ba9983aefd86074db212d3fccd64eed04bc9f0b3da",
       "bytes": 8011
     },
-    "console-ui/assets/index-BmDxs-a5.js": {
-      "sha256": "8090617babfe49eb6f4b313ee45d13d862eba3ba8c9714ef805cda33918e4f08",
+    "console-ui/assets/index-CK8Zux9a.js": {
+      "sha256": "6e1d3f6c4ec56f5b9b75a780d9cf3e1a3c62b173850093fae221add3d58d0b10",
       "bytes": 768234
     },
     "console-ui/assets/index-DHrKiMCf.css": {
@@ -482,7 +482,7 @@
       "bytes": 60673
     },
     "console-ui/index.html": {
-      "sha256": "d7ca1e4d2950572216e245c8a6a5130f8393ed3c961f067d2320202295b18183",
+      "sha256": "06cf7fbd1120973d829d69db8114e98fd38e28e88d9cac7c3daa8c1834d4ebd8",
       "bytes": 417
     },
     "console/standalone-console.d.ts": {
@@ -662,8 +662,8 @@
       "bytes": 247
     },
     "daemon/session-scope.d.ts": {
-      "sha256": "1d4c5c8ad79bde16bf49d8f364f1e95a8294896caad8d9e4e16209301505496b",
-      "bytes": 1394
+      "sha256": "35e102ecaeb59fbb57b715a43c030e8aba7a2e0aa757d0f828dc677910020ada",
+      "bytes": 1681
     },
     "daemon/session-scope.js": {
       "sha256": "2f5295aa36b8d46b162a2b1f4d6f13af00517796aa468956563a8de46e2ecd56",
@@ -774,12 +774,12 @@
       "bytes": 429
     },
     "daemon/workflow-runner.d.ts": {
-      "sha256": "757ac2f51eb800f1b7d714fdf86695fac10322829f334166f0a083abdabe0cb1",
-      "bytes": 13256
+      "sha256": "27fd8ac603948712aaf266ef57d2c165c1b4f92f877358debc40ad4f43d5b24c",
+      "bytes": 13463
     },
     "daemon/workflow-runner.js": {
-      "sha256": "9d25e56934be6a7cfdfc54086faacee6e3119e7b7d01240cb958749ea33f8bcd",
-      "bytes": 79776
+      "sha256": "458be357c7dd86b215aaa8eabb3fe7ddb05172a0a4a771523232dc9b012ea156",
+      "bytes": 80362
     },
     "di/container.d.ts": {
       "sha256": "003bb7fb7478d627524b9b1e76bd0a963a243794a687ff233b96dc0e33a06d9f",
@@ -2138,8 +2138,8 @@
       "bytes": 161
     },
     "v2/durable-core/domain/context-template-resolver.js": {
-      "sha256": "81bb0b3e94cb301ab3c24a9aa1737accdd2ad76b1a6d7a61de5ce7d4d6c34801",
-      "bytes": 962
+      "sha256": "05a0f2f61cf666b160677e6b22faa624f290e4a9f26fae98283c8cfc5b71a546",
+      "bytes": 2129
     },
     "v2/durable-core/domain/decision-trace-builder.d.ts": {
       "sha256": "f897dd17019bb094c72b1b19d7e731d535f66256ae38a0b08646d2604be0663d",

package/dist/v2/durable-core/domain/context-template-resolver.js

@@ -4,23 +4,48 @@ exports.CONTEXT_TOKEN_PATTERN = void 0;
 exports.resolveContextTemplates = resolveContextTemplates;
 exports.CONTEXT_TOKEN_PATTERN = /\{\{(?!wr\.)([a-zA-Z_]\w*(?:\.[a-zA-Z_]\w*)*)\}\}/;
 function resolveDotPath(base, path) {
-    let current = base;
-    for (const segment of path) {
-        if (current === null || typeof current !== 'object')
-            return undefined;
+    if (path.length === 0)
+        return { kind: 'ok', value: base };
+    const rootKey = path[0];
+    if (base === null || typeof base !== 'object') {
+        return { kind: 'missing_root', rootKey };
+    }
+    const rootValue = base[rootKey];
+    if (rootValue === undefined || rootValue === null) {
+        return { kind: 'missing_root', rootKey };
+    }
+    let current = rootValue;
+    for (let i = 1; i < path.length; i++) {
+        const segment = path[i];
+        if (current === null || typeof current !== 'object') {
+            const actualType = current === null ? 'null' : typeof current;
+            const raw = String(current);
+            const preview = raw.length > 60 ? raw.slice(0, 60) + '…' : raw;
+            return { kind: 'wrong_type', failedAtKey: path.slice(0, i).join('.'), actualType, preview };
+        }
         current = current[segment];
     }
-    return current;
+    if (current === undefined || current === null) {
+        return { kind: 'leaf_missing', fullPath: path.join('.') };
+    }
+    return { kind: 'ok', value: current };
 }
 function resolveContextTemplates(template, context) {
     if (!template.includes('{{'))
         return template;
     const re = new RegExp(exports.CONTEXT_TOKEN_PATTERN.source, 'g');
     return template.replace(re, (_match, dotPath) => {
-        const value = resolveDotPath(context, dotPath.split('.'));
-        if (value === undefined || value === null) {
-            return `[unset: ${dotPath}]`;
+        const segments = dotPath.split('.');
+        const result = resolveDotPath(context, segments);
+        switch (result.kind) {
+            case 'ok':
+                return String(result.value);
+            case 'missing_root':
+                return `[unset: ${dotPath}]`;
+            case 'wrong_type':
+                return `[unset: ${dotPath} -- '${result.failedAtKey}' is ${result.actualType} ("${result.preview}"), not object]`;
+            case 'leaf_missing':
+                return `[unset: ${dotPath}]`;
         }
-        return String(value);
     });
 }

package/docs/ideas/backlog.md

@@ -65,26 +65,50 @@ No proposed solutions here -- just the problem.]
 
 ### wr.coding-task forEach loop exposes broken agent-facing state (Apr 30, 2026)
 
-**Status: bug** | Priority: high
+**Status: done** | Shipped May 1, 2026 (PR #926)
 
 **Score: 13** | Cor:3 Cap:1 Eff:2 Lev:2 Con:3 | Blocked: no
 
-The `phase-6-implement-slices` loop (forEach over `slices`) ran correctly mechanically -- it iterated all 8 slices and stopped. But the agent-facing representation was broken in ways that violate WorkRail's promise of consistency and determinism:
+**Root cause (diagnosed Apr 30, 2026):** The agent wrote `slices` as an array of plain strings (`["1: slice name", ...]`) instead of objects (`[{name: "...", ...}]`). The engine accepted the array (it was an array), entered the loop, and `{{currentSlice.name}}` silently resolved to `[unset]` on every iteration because strings don't have a `.name` property.
 
-1. **`currentSlice.name` showed `[unset]`** -- the agent was inside a forEach loop over `slices` with `itemVar: "currentSlice"`, but the template variable wasn't being projected into sessionContext before rendering. The agent couldn't see which slice it was on. This is an engine rendering issue in `buildLoopRenderContext` / `prompt-renderer.ts`.
+**Shipped (PR #926):**
+1. **forEach shape guard** (`workflow-interpreter.ts`): at iteration 0, if the body uses `{{itemVar.field}}` dot-path access but the items array contains primitives, returns `LOOP_MISSING_CONTEXT` with a message naming the actual type and a preview of the bad value. The loop never enters with broken state.
+2. **Diagnostic `[unset]` messages** (`context-template-resolver.ts`): when dot-path navigation fails mid-path due to a type mismatch (e.g. `currentSlice` is a string), the rendered prompt now shows `[unset: currentSlice.name -- 'currentSlice' is string ("1: Auth..."), not object]` instead of just `[unset: currentSlice.name]`.
 
-2. **Agent emitted `wr.loop_control` artifacts that had no effect** -- the forEach loop silently ignores these. The agent did useless work the engine discarded without signaling that this was happening. A correct system should either prevent the agent from emitting artifacts that can't affect the loop, or tell the agent explicitly that artifact-based exit isn't available in this loop type.
+**Remaining open (separate items):** context contract enforcement (systemic fix), `todoList` abstraction, `wr.loop_control` shown in forEach prompts.
 
-3. **Loop presented as "Pass N of 20" not "Slice 3 of 8"** -- the framing confused the agent about what was happening. The agent should be told it's iterating over concrete slices, not burning through a budget.
+**GitHub issue:** https://github.com/EtienneBBeaulac/workrail/issues/920
+
+---
 
-The forEach loop *worked* but the agent experience was wrong. This matters because WorkRail's value is that agents should not be confused about their own loop state. An agent that emits useless artifacts, can't see its own iteration variable, and misunderstands whether the loop is progress-based or budget-based is not operating under the deterministic, correct framework WorkRail promises.
+### Context contract: steps must declare required and produced context keys (Apr 30, 2026)
 
-**GitHub issue:** https://github.com/EtienneBBeaulac/workrail/issues/920
+**Status: tentative** | Priority: medium
+
+**Score: 12** | Cor:3 Cap:2 Eff:1 Lev:3 Con:2 | Blocked: no
+
+The engine has no mechanism to enforce context between steps. `Capture:` instructions in step prompts are prose -- the engine accepts `continue_workflow` with empty context on every advance, silently. This is the systemic root of the forEach `[unset]` bug: the agent wrote planning output as notes, not as context, and the engine accepted every advance without complaint. The same failure can happen in any workflow that passes state between steps.
 
 **Things to hash out:**
-- Is `currentSlice.name = [unset]` a bug in `buildLoopRenderContext` (engine fix needed), or is it a workflow authoring issue (the slices array items don't have a `name` property)?
-- Should the engine prevent agents from emitting `wr.loop_control` artifacts inside forEach loops, or simply document that they have no effect?
-- Should forEach loops surface iteration progress ("slice 3 of 8") differently than while loops ("pass 3 of 20") in the step header text?
+- What schema format should `contextContract` use -- JSON Schema subset or a simpler workrail-specific type DSL?
+- Should validation be blocking (engine rejects the advance) or advisory (engine warns in the next step prompt)?
+- Does context contract cover loop entry preconditions, or does the separate forEach guard item handle that?
+
+---
+
+### `todoList` step type: ergonomic abstraction over forEach (Apr 30, 2026)
+
+**Status: idea** | Priority: medium
+
+**Score: 10** | Cor:2 Cap:3 Eff:1 Lev:2 Con:2 | Blocked: no
+
+Workflow authors using forEach must manually wire a prior step to populate the items array, understand iteration variables, avoid emitting `wr.loop_control` artifacts (which have no effect in forEach), and explain the loop framing to the agent. The forEach shape guard (PR #926) now catches primitive-item arrays loudly at loop entry, but the wiring between "the step that produces items" and "the loop that consumes them" remains implicit and invisible to the engine. The `todoList` abstraction would make this wiring structural.
+
+**Things to hash out:**
+- Should `todoList` compile to a forEach loop at the engine layer, or be a new execution primitive?
+- How does the setup step that produces the items array get authored -- inline prompt, routine reference, or both?
+- What does the agent-facing presentation look like: "Item 3 of 8" with item content injected, or something else?
+- Should `wr.loop_control` artifacts be stripped from the step prompt entirely in a `todoList`, or does the agent still need an explicit completion signal?
 
 ---
 
@@ -333,21 +357,7 @@ Five dimensions, each scored 1-3. Score = sum (max 15). Items marked **Blocked**
 
 ### `delivery_failed` unreachable in `getChildSessionResult` -- type promises more than code delivers (Apr 30, 2026)
 
-**Status: bug** | Priority: medium
-
-**Score: 10** | Cor:3 Cap:1 Eff:2 Lev:2 Con:2 | Blocked: no
-
-`ChildSessionResult` has `reason: 'delivery_failed'` as a variant of `kind: 'failed'`. However `fetchChildSessionResult` in `coordinator-deps.ts` reads session status through `ConsoleService.getSessionDetail`, which returns statuses like `complete`/`blocked`/`in_progress` -- it never returns a `delivery_failed` status. `delivery_failed` is a `TriggerRouter`-level concept (callbackUrl POST failure) that is not stored as a session status in the event log. Child sessions spawned via `spawnSession`/`spawnAndAwait` have no `callbackUrl` and cannot produce it through this code path.
-
-The result: coordinators using `getChildSessionResult` can never observe `reason: 'delivery_failed'`, even though the type says they might. This violates the "make illegal states unrepresentable" principle -- the type union promises a variant the implementation cannot produce on this path.
-
-**Architectural fix (not a comment):** surface `delivery_failed` through session status. When `TriggerRouter` records a `delivery_failed` outcome, write a corresponding session event or status that `ConsoleService.getSessionDetail` returns. Then `fetchChildSessionResult` can map it correctly. This closes the gap between what the type promises and what the infrastructure delivers.
-
-Alternative: if `spawnSession`/`spawnAndAwait` child sessions genuinely cannot have `delivery_failed` outcomes by design, remove `reason: 'delivery_failed'` from `ChildSessionResult` entirely and document that it only exists in `spawn_agent`'s direct outcome mapping.
-
-**Things to hash out:**
-- Should `delivery_failed` be surfaced through ConsoleService (requires touching session status storage), or removed from `ChildSessionResult` since the `spawnSession` path provably cannot produce it?
-- If surfaced: what event or field in the session store carries this status, and how does ConsoleService project it?
+**Status: done** | Fixed in `cd8aaeb8` -- `delivery_failed` removed from `ChildSessionResult` entirely. The `spawnSession`/`spawnAndAwait` path cannot produce it by design; it only exists in `spawn_agent`'s direct outcome mapping.
 
 ---
 
@@ -367,19 +377,27 @@ Alternative: if `spawnSession`/`spawnAndAwait` child sessions genuinely cannot h
 
 ### Daemon architecture: remaining migrations (Apr 29, 2026)
 
-**Status: partial** | A9 shipped Apr 29, 2026.
+**Status: partial** | A9 shipped Apr 29, 2026. FC/IS follow-on shipped Apr 30 -- May 1, 2026.
 
 **Score: 8** | Cor:1 Cap:1 Eff:2 Lev:1 Con:3 | Blocked: no
 
 Track A (A1-A9) shipped and the `SessionSource` migration is complete. `WorkflowTrigger._preAllocatedStartResponse` is gone.
 
+**Shipped Apr 30 -- May 1, 2026 (PR #925):**
+- `TerminalSignal` union replaces `stuckReason` + `timeoutReason`. Illegal state (stuck AND timeout simultaneously) now structurally impossible. Stall overwrite bug fixed. `Readonly<SessionState>` at pure read sites.
+- `SessionScope` capability boundary complete: `onTokenUpdate`, `onIssueReported`, `onSteer`, `getCurrentToken`, `sessionWorkspacePath`, spawn depths all named scope fields. `constructTools` signature is `(ctx, apiKey, schemas, scope)` -- zero direct `state.X` references.
+- Early-exit paths unified through `finalizeSession`. `SteerRegistry`/`AbortRegistry` dead exports removed.
+- Architecture tests enforce `state.terminalSignal` write restriction and `constructTools` state-access restriction in CI.
+- `persistTokens` failure early-exit path covered by new outcome invariants tests.
+
 **Remaining items:**
 
 - `CriticalEffect<T>` / `ObservabilityEffect` type distinction -- categorize side effects in `runAgentLoop` and finalization as either crash-relevant or observability-only
-- `StateRef` mutation wrapper -- replace direct `state.pendingSteerParts.push()` mutations with an explicit mutation API
 - Zod tool param validation -- replace manual `typeof` checks in tool factories with Zod schema validation (requires `zodToJsonSchema` or maintaining two sources of truth for param schemas)
 - `createCoordinatorDeps` unit tests -- extraction in B3 improved testability; cover `spawnSession`, `awaitSessions`, `getAgentResult` at minimum
 - ~~Wire `AllocatedSession.triggerSource` to the `run_started` event for session attribution~~ -- **done**, PR #899 (Apr 30, 2026)
+- ~~`SessionStateWriter` capability interfaces~~ -- **done** as part of PR #925 (`SessionScope` now owns all mutation callbacks)
+- ~~Architecture test: forbid `state.terminalSignal =` direct writes outside `setTerminalSignal()`~~ -- **done**, PR #925
 
 ---
 
@@ -444,6 +462,8 @@ Phase 3 (PRs #835, #837): `buildTurnEndSubscriber`, `buildAgentCallbacks`, `buil
 
 **Total workflow-runner.ts reduction: ~4,955 → ~2,800 lines (44%).**
 
+**FC/IS follow-on (PR #925, Apr 30 -- May 1, 2026):** `TerminalSignal` union, `SessionScope` capability boundary completion, early-exit unification through `finalizeSession`, architecture tests. See "Daemon architecture: remaining migrations" entry for full details.
+
 **Follow-on:** `wr.refactoring` workflow (see backlog entry above). Remaining items in "Daemon architecture: remaining migrations" entry below.
 
 ---