@exaudeus/workrail 3.44.0 → 3.45.0

package/dist/daemon/workflow-runner.js

@@ -1081,6 +1081,16 @@ function makeSpawnAgentTool(sessionId, ctx, apiKey, thisWorkrailSessionId, curre
                     notes: childResult.message,
                 };
             }
+            else if (childResult._tag === 'stuck') {
+                resultObj = {
+                    childSessionId,
+                    outcome: 'stuck',
+                    notes: childResult.message,
+                    ...(childResult.issueSummaries !== undefined
+                        ? { issueSummaries: childResult.issueSummaries }
+                        : {}),
+                };
+            }
             else {
                 (0, assert_never_js_1.assertNever)(childResult);
             }
@@ -1093,6 +1103,31 @@ function makeSpawnAgentTool(sessionId, ctx, apiKey, thisWorkrailSessionId, curre
         },
     };
 }
+async function writeStuckOutboxEntry(opts) {
+    try {
+        const outboxPath = path.join(os.homedir(), '.workrail', 'outbox.jsonl');
+        await fs.mkdir(path.dirname(outboxPath), { recursive: true });
+        const entry = JSON.stringify({
+            id: (0, node_crypto_1.randomUUID)(),
+            kind: 'stuck',
+            message: `Session stuck (${opts.reason}): workflowId=${opts.workflowId}` +
+                (opts.issueSummaries && opts.issueSummaries.length > 0
+                    ? ` -- issues: ${opts.issueSummaries.join('; ')}`
+                    : ''),
+            timestamp: new Date().toISOString(),
+            workflowId: opts.workflowId,
+            reason: opts.reason,
+            ...(opts.issueSummaries && opts.issueSummaries.length > 0
+                ? { issueSummaries: opts.issueSummaries }
+                : {}),
+        });
+        await fs.appendFile(outboxPath, entry + '\n');
+    }
+    catch (err) {
+        console.warn(`[WorkflowRunner] Could not write stuck outbox entry: ` +
+            `${err instanceof Error ? err.message : String(err)}`);
+    }
+}
 async function appendIssueAsync(issuesDir, sessionId, record) {
     await fs.mkdir(issuesDir, { recursive: true });
     const filePath = path.join(issuesDir, `${sessionId}.jsonl`);
@@ -1449,19 +1484,6 @@ async function runWorkflow(trigger, ctx, apiKey, daemonRegistry, emitter, steerR
     if (startContinueToken) {
         await persistTokens(sessionId, startContinueToken, startCheckpointToken);
     }
-    if (trigger.botIdentity) {
-        try {
-            await execFileAsync('git', ['-C', trigger.workspacePath, 'config', 'user.name', trigger.botIdentity.name]);
-            await execFileAsync('git', ['-C', trigger.workspacePath, 'config', 'user.email', trigger.botIdentity.email]);
-            console.log(`[WorkflowRunner] Bot identity set: sessionId=${sessionId} ` +
-                `name=${trigger.botIdentity.name} email=${trigger.botIdentity.email}`);
-        }
-        catch (identityErr) {
-            console.warn(`[WorkflowRunner] WARNING: Failed to set bot identity for sessionId=${sessionId}: ` +
-                `${identityErr instanceof Error ? identityErr.message : String(identityErr)}. ` +
-                `Commits will use default git config.`);
-        }
-    }
     let sessionWorkspacePath = trigger.workspacePath;
     let sessionWorktreePath;
     if (trigger.branchStrategy === 'worktree') {
@@ -1497,6 +1519,19 @@ async function runWorkflow(trigger, ctx, apiKey, daemonRegistry, emitter, steerR
             };
         }
     }
+    if (trigger.botIdentity) {
+        try {
+            await execFileAsync('git', ['-C', sessionWorkspacePath, 'config', 'user.name', trigger.botIdentity.name]);
+            await execFileAsync('git', ['-C', sessionWorkspacePath, 'config', 'user.email', trigger.botIdentity.email]);
+            console.log(`[WorkflowRunner] Bot identity set: sessionId=${sessionId} ` +
+                `name=${trigger.botIdentity.name} email=${trigger.botIdentity.email}`);
+        }
+        catch (identityErr) {
+            console.warn(`[WorkflowRunner] WARNING: Failed to set bot identity for sessionId=${sessionId}: ` +
+                `${identityErr instanceof Error ? identityErr.message : String(identityErr)}. ` +
+                `Commits will use default git config.`);
+        }
+    }
     if (firstStep.isComplete) {
         await fs.unlink(path.join(exports.DAEMON_SESSIONS_DIR, `${sessionId}.json`)).catch(() => { });
         emitter?.emit({ kind: 'session_completed', sessionId, workflowId: trigger.workflowId, outcome: 'success', detail: 'stop', ...withWorkrailSession(workrailSessionId) });
@@ -1588,7 +1623,10 @@ async function runWorkflow(trigger, ctx, apiKey, daemonRegistry, emitter, steerR
     });
     const sessionTimeoutMs = (trigger.agentConfig?.maxSessionMinutes ?? DEFAULT_SESSION_TIMEOUT_MINUTES) * 60 * 1000;
     const maxTurns = trigger.agentConfig?.maxTurns ?? DEFAULT_MAX_TURNS;
+    const sessionStartMs = Date.now();
+    void sessionStartMs;
     let timeoutReason = null;
+    let stuckReason = null;
     let turnCount = 0;
     const unsubscribe = agent.subscribe(async (event) => {
         if (event.type !== 'turn_end')
@@ -1623,6 +1661,17 @@ async function runWorkflow(trigger, ctx, apiKey, daemonRegistry, emitter, steerR
                 argsSummary: lastNToolCalls[0]?.argsSummary,
                 ...withWorkrailSession(workrailSessionId),
             });
+            void writeStuckOutboxEntry({
+                workflowId: trigger.workflowId,
+                reason: 'repeated_tool_call',
+                ...(issueSummaries.length > 0 ? { issueSummaries: [...issueSummaries] } : {}),
+            });
+            const stuckPolicy = trigger.agentConfig?.stuckAbortPolicy ?? 'abort';
+            if (stuckPolicy !== 'notify_only' && stuckReason === null && timeoutReason === null) {
+                stuckReason = 'repeated_tool_call';
+                agent.abort();
+                return;
+            }
         }
         if (maxTurns > 0 &&
             turnCount >= Math.floor(maxTurns * 0.8) &&
@@ -1634,6 +1683,20 @@ async function runWorkflow(trigger, ctx, apiKey, daemonRegistry, emitter, steerR
                 detail: `${turnCount} turns used, 0 step advances (${maxTurns} turn limit)`,
                 ...withWorkrailSession(workrailSessionId),
             });
+            const noProgressAbortEnabled = trigger.agentConfig?.noProgressAbortEnabled ?? false;
+            if (noProgressAbortEnabled) {
+                void writeStuckOutboxEntry({
+                    workflowId: trigger.workflowId,
+                    reason: 'no_progress',
+                    ...(issueSummaries.length > 0 ? { issueSummaries: [...issueSummaries] } : {}),
+                });
+                const noProgressPolicy = trigger.agentConfig?.stuckAbortPolicy ?? 'abort';
+                if (noProgressPolicy !== 'notify_only' && stuckReason === null && timeoutReason === null) {
+                    stuckReason = 'no_progress';
+                    agent.abort();
+                    return;
+                }
+            }
         }
         if (timeoutReason !== null) {
             emitter?.emit({
@@ -1693,6 +1756,26 @@ async function runWorkflow(trigger, ctx, apiKey, daemonRegistry, emitter, steerR
         }
         console.log(`[WorkflowRunner] Agent loop ended: sessionId=${sessionId} stopReason=${stopReason}${errorMessage ? ` error=${errorMessage.slice(0, 120)}` : ''}`);
     }
+    if (stuckReason !== null) {
+        emitter?.emit({
+            kind: 'session_completed',
+            sessionId,
+            workflowId: trigger.workflowId,
+            outcome: 'timeout',
+            detail: stuckReason,
+            ...withWorkrailSession(workrailSessionId),
+        });
+        if (workrailSessionId !== null)
+            daemonRegistry?.unregister(workrailSessionId, 'failed');
+        return {
+            _tag: 'stuck',
+            workflowId: trigger.workflowId,
+            reason: stuckReason,
+            message: `Session aborted: stuck heuristic fired (${stuckReason})`,
+            stopReason: 'aborted',
+            ...(issueSummaries.length > 0 ? { issueSummaries: [...issueSummaries] } : {}),
+        };
+    }
     if (timeoutReason !== null) {
         emitter?.emit({ kind: 'session_completed', sessionId, workflowId: trigger.workflowId, outcome: 'timeout', detail: timeoutReason, ...withWorkrailSession(workrailSessionId) });
         if (workrailSessionId !== null)

package/dist/manifest.json

@@ -449,8 +449,8 @@
       "sha256": "5fe866e54f796975dec5d8ba9983aefd86074db212d3fccd64eed04bc9f0b3da",
       "bytes": 8011
     },
-    "console-ui/assets/index-Bi38ITiQ.js": {
-      "sha256": "e3229116ac20f315184c69ef9eaa33267457e5e7aac1e22015ed830cb098e39a",
+    "console-ui/assets/index-BpanIvmi.js": {
+      "sha256": "e5c3e897dbda3f810ce737422d3f84d06b8e146c7923041fbd96b276538435c6",
       "bytes": 760528
     },
     "console-ui/assets/index-DGj8EsFR.css": {
@@ -458,7 +458,7 @@
       "bytes": 60631
     },
     "console-ui/index.html": {
-      "sha256": "fb9efa806376b8f8f18d3c5d7853d04b9dfc9abc305b0ed22782379bc13a2c86",
+      "sha256": "587aa7591502ca4dadbea5c7f5c56136d19f18d179c735abe693e9ee2c290e1e",
       "bytes": 417
     },
     "console/standalone-console.d.ts": {
@@ -550,12 +550,12 @@
       "bytes": 1512
     },
     "daemon/workflow-runner.d.ts": {
-      "sha256": "0406654be8c6eb147706e81e0ba666ce372db140f4720246258e0f001653181e",
-      "bytes": 6628
+      "sha256": "4c67cc7a44c934469c190f11a71bd18bf0dfc31f59ab0c315b98315b96d59cce",
+      "bytes": 7048
     },
     "daemon/workflow-runner.js": {
-      "sha256": "f40f265284aa1e32168d8a0cf28c08007186eafac6d55182b7ec6ddb53bed5a8",
-      "bytes": 89592
+      "sha256": "a5d74ec723ff0dce45d2335b811959ff0c6e6f8851edf399a70853f6bf127893",
+      "bytes": 93222
     },
     "di/container.d.ts": {
       "sha256": "003bb7fb7478d627524b9b1e76bd0a963a243794a687ff233b96dc0e33a06d9f",
@@ -1606,12 +1606,12 @@
       "bytes": 1222
     },
     "trigger/notification-service.d.ts": {
-      "sha256": "c78406d3748953548f7879df8ac60cecd5e42f2f3b283f777343168ce2470b8d",
-      "bytes": 1572
+      "sha256": "25509f290a11ac9a8aa03e5d7e44011950c841436e9458eb855b94d15d036d68",
+      "bytes": 1582
     },
     "trigger/notification-service.js": {
-      "sha256": "693f617adc30b3a4fcebeca6a78b0da1c58819001660c017a4d0901652d675b8",
-      "bytes": 6373
+      "sha256": "9d9a5951229f2c6ffaa413a7421efa6611d9ca0ed456edf5c297a4506e84a80e",
+      "bytes": 6521
     },
     "trigger/polled-event-store.d.ts": {
       "sha256": "2952a25804177b2389d4273bfc41192477d100bc26100683861dedf28520dec1",
@@ -1642,8 +1642,8 @@
       "bytes": 2123
     },
     "trigger/trigger-router.js": {
-      "sha256": "605cdce397bd19e5b991fe7378faf17b4f25b4421749e1b5349413a208a4f3dd",
-      "bytes": 17250
+      "sha256": "8a4a4699df4210b5631211e7370ed6b70d972e82321cf8c66dcc9f60661e5d2c",
+      "bytes": 17750
     },
     "trigger/trigger-store.d.ts": {
       "sha256": "7afb05127d55bc3757a550dd15d4b797766b3fff29d1bfe76b303764b93322e7",
@@ -1654,8 +1654,8 @@
       "bytes": 38148
     },
     "trigger/types.d.ts": {
-      "sha256": "4ccedde5b927f17edbb96203083e8ffd2d578e2cc007ff2427511112ae262e30",
-      "bytes": 3475
+      "sha256": "a1336ad769dbe4760e7acd3b2a92961251492aa29245b5d906ad89011ea934fa",
+      "bytes": 3587
     },
     "trigger/types.js": {
       "sha256": "45b4e4f23a6d1a2b07350196871b0c53840e5d8142b47f7acedd2f40ae7a6b73",
@@ -2970,8 +2970,8 @@
       "bytes": 798
     },
     "v2/usecases/console-routes.js": {
-      "sha256": "89749c3462728cd2a821af7e4cad61d2d42b8f580765f644c9f4e9d1e9187bd1",
-      "bytes": 29558
+      "sha256": "3e8bd3adfdc66926d91044506d2c77253b784b9e4356a8610c585e6a27153d4b",
+      "bytes": 29776
     },
     "v2/usecases/console-service.d.ts": {
       "sha256": "fc8fe65427fa9f4f3535344b385b36f66ca06b7e3bfaea708931817a3edcad2b",

package/dist/trigger/notification-service.d.ts

@@ -21,7 +21,7 @@ export interface NotificationConfig {
 export interface NotificationPayload {
     readonly event: 'session_completed';
     readonly workflowId: string;
-    readonly outcome: 'success' | 'error' | 'timeout' | 'delivery_failed';
+    readonly outcome: 'success' | 'error' | 'timeout' | 'stuck' | 'delivery_failed';
     readonly detail: string;
     readonly goal: string;
     readonly timestamp: string;

package/dist/trigger/notification-service.js

@@ -48,6 +48,8 @@ function buildNotificationBody(result, goal) {
             return `Session failed: ${truncated}`;
         case 'timeout':
             return `Session timed out: ${truncated}`;
+        case 'stuck':
+            return `Session stuck (${result.reason}): ${truncated}`;
         case 'delivery_failed':
             return `Session completed but result delivery failed: ${truncated}`;
     }
@@ -63,6 +65,8 @@ function buildDetail(result) {
             return result.message;
         case 'timeout':
             return result.message;
+        case 'stuck':
+            return result.message;
         case 'delivery_failed':
             return `stopReason: ${result.stopReason}; deliveryError: ${result.deliveryError}`;
     }

package/dist/trigger/trigger-router.js

@@ -327,6 +327,10 @@ class TriggerRouter {
                 console.log(`[TriggerRouter] Workflow failed: triggerId=${trigger.id} ` +
                     `workflowId=${trigger.workflowId} error=${result.message} stopReason=${result.stopReason}`);
             }
+            else if (result._tag === 'stuck') {
+                console.log(`[TriggerRouter] Workflow stuck: triggerId=${trigger.id} ` +
+                    `workflowId=${trigger.workflowId} reason=${result.reason} message=${result.message}`);
+            }
             else {
                 (0, assert_never_js_1.assertNever)(result);
             }
@@ -366,6 +370,10 @@ class TriggerRouter {
                 console.log(`[TriggerRouter] Dispatch failed: workflowId=${workflowTrigger.workflowId} ` +
                     `error=${result.message} stopReason=${result.stopReason}`);
             }
+            else if (result._tag === 'stuck') {
+                console.log(`[TriggerRouter] Dispatch stuck: workflowId=${workflowTrigger.workflowId} ` +
+                    `reason=${result.reason} message=${result.message}`);
+            }
             else {
                 (0, assert_never_js_1.assertNever)(result);
             }

package/dist/trigger/types.d.ts

@@ -71,6 +71,8 @@ export interface TriggerDefinition {
         readonly model?: string;
         readonly maxSessionMinutes?: number;
         readonly maxTurns?: number;
+        readonly stuckAbortPolicy?: 'abort' | 'notify_only';
+        readonly noProgressAbortEnabled?: boolean;
     };
     readonly concurrencyMode: 'serial' | 'parallel';
     readonly callbackUrl?: string;

package/dist/v2/usecases/console-routes.js

@@ -604,6 +604,9 @@ function mountConsoleRoutes(app, consoleService, workflowService, timingRingBuff
                 else if (result._tag === 'error') {
                     console.log(`[ConsoleRoutes] Auto dispatch failed: workflowId=${workflowId} error=${result.message}`);
                 }
+                else if (result._tag === 'stuck') {
+                    console.log(`[ConsoleRoutes] Auto dispatch stuck: workflowId=${workflowId} reason=${result.reason} message=${result.message}`);
+                }
                 else {
                     (0, assert_never_js_1.assertNever)(result);
                 }

package/docs/design/design-candidates-stuck-escalation.md

@@ -0,0 +1,183 @@
+# Design Candidates: WorkTrain Stuck-Escalation
+
+*Generated: 2026-04-19 | Pitch: .workrail/current-pitch.md*
+
+---
+
+## Problem Understanding
+
+### Core Tensions
+
+1. **Stuck vs timeout conflation**: When `repeated_tool_call` fires, the session
+   currently runs until wall-clock or max-turns timeout. The result is
+   `_tag: 'timeout'`, which is indistinguishable from a legitimate slow session.
+   Automated routing requires a distinct discriminant.
+
+2. **Abort vs notify-only independence**: Outbox notification and `agent.abort()`
+   are two separate effects. `notify_only` policy suppresses the abort but must
+   not suppress the outbox write. These effects must not be coupled.
+
+3. **ChildWorkflowRunResult atomic update**: The `as ChildWorkflowRunResult` cast
+   at line 2172 in `makeSpawnAgentTool` suppresses any compile-time error from a
+   missing union update. Only the `assertNever(childResult)` at line 2212 catches
+   the omission -- at runtime, crashing the parent session.
+
+4. **no_progress false-positive risk**: The no_progress heuristic fires on
+   legitimate research workflows that spend many turns reading before advancing.
+   It must be opt-in (default: false) to avoid breaking existing sessions.
+
+### Likely Seam
+
+The `turn_end` subscriber in `runWorkflow()` is the correct location. All
+required state (lastNToolCalls, stepAdvanceCount, timeoutReason, issueSummaries)
+is available there as closure variables. Detection fires at the right moment
+(after each turn, synchronously before next step injection).
+
+### What Makes This Hard
+
+- The `as ChildWorkflowRunResult` cast is a type-safety trap: it silences
+  TypeScript while leaving a runtime crash. Only careful reading of the pitch
+  reveals the issue.
+- `buildOutcome()` in notification-service.ts has return type
+  `NotificationPayload['outcome']`. Adding 'stuck' to WorkflowRunResult causes
+  a compile error there unless the outcome union is also widened.
+
+---
+
+## Philosophy Constraints
+
+From CLAUDE.md:
+
+- **Make illegal states unrepresentable**: the stuck discriminant prevents
+  conflating stuck with timeout at the type level.
+- **Exhaustiveness everywhere**: assertNever guards in trigger-router and
+  makeSpawnAgentTool enforce this -- adding stuck arm is required.
+- **Errors are data**: WorkflowRunResult is a Result type; WorkflowRunStuck is
+  a new variant, not an exception.
+- **Type safety as first line of defense**: ChildWorkflowRunResult update in
+  same commit restores the compile-time invariant that the cast broke.
+- **Fire-and-forget for side effects**: outbox write uses void + catch, same
+  as DaemonEventEmitter and issue recording.
+
+No conflicts between stated philosophy and repo patterns.
+
+---
+
+## Impact Surface
+
+Paths that must stay consistent when WorkflowRunResult gains a new variant:
+
+1. `makeSpawnAgentTool` -- `assertNever(childResult)` at line 2212; requires
+   ChildWorkflowRunResult update and a new `stuck` arm in the result mapping.
+2. `trigger-router.ts` `route()` -- exhaustive if-else chain ending in
+   `assertNever(result)` at line ~689.
+3. `trigger-router.ts` `dispatch()` -- same exhaustive chain at line ~770.
+4. `notification-service.ts` `buildNotificationBody()` -- exhaustive switch.
+5. `notification-service.ts` `buildDetail()` -- exhaustive switch.
+6. `notification-service.ts` `buildOutcome()` -- return type
+   `NotificationPayload['outcome']`; 'stuck' must be added to that union.
+7. `NotificationPayload.outcome` union -- currently
+   `'success' | 'error' | 'timeout' | 'delivery_failed'`; must add `'stuck'`.
+
+---
+
+## Candidates
+
+### Candidate A: New `_tag: 'stuck'` discriminated union variant (SELECTED)
+
+**Summary**: Add `WorkflowRunStuck` interface with `_tag: 'stuck'`, wire abort
+in turn_end subscriber after Signal 1 and Signal 2 emitter calls, return stuck
+result before timeout check, update both `WorkflowRunResult` and
+`ChildWorkflowRunResult` unions atomically, add `writeStuckOutboxEntry` helper.
+
+**Tensions resolved**:
+- Stuck/timeout conflation: separate discriminant, separate return path.
+- Abort/notify independence: outbox write fires before the abort gate check.
+- ChildWorkflowRunResult crash: atomic update with assertNever arm added.
+- no_progress false-positive: gated by `noProgressAbortEnabled: false` default.
+
+**Boundary solved at**: `turn_end` subscriber (detection + abort), result
+construction (return), 4 files for propagation to callers.
+
+**Why best-fit boundary**: The turn_end subscriber is the only location with
+access to all required state. The result construction is the canonical output
+boundary for runWorkflow(). Propagation to callers follows the existing
+WorkflowRunResult variant fan-out pattern.
+
+**Failure mode**: Forgetting to update `NotificationPayload.outcome` union --
+caught by `npm run build` (TypeScript compile error in `buildOutcome()`).
+
+**Repo-pattern relationship**: Mirrors `timeoutReason` flag pattern exactly.
+Mirrors `WorkflowRunTimeout` interface field shape. Follows assertNever guard
+pattern already established in trigger-router and makeSpawnAgentTool.
+
+**Gains**: Distinct routing for stuck sessions, type-safe callers, clean
+separation of abort and notification effects.
+
+**Losses**: One more variant in the union (minor cognitive load increase).
+
+**Scope judgment**: Best-fit. 4 files, mechanical wiring, all design resolved.
+
+**Philosophy fit**: Honors all relevant CLAUDE.md principles. No conflicts.
+
+---
+
+### Candidate B: Extend `WorkflowRunTimeout.reason` with stuck sub-values
+
+**Summary**: Add `'stuck_repeated_tool_call' | 'stuck_no_progress'` to
+`WorkflowRunTimeout.reason` -- reuse the timeout discriminant.
+
+**Tensions resolved**: None of the core ones. Stuck and timeout still share
+`_tag: 'timeout'`, requiring callers to inspect reason to distinguish them.
+
+**Failure mode**: Violates make-illegal-states-unrepresentable. Callers using
+`result._tag === 'timeout'` would silently handle stuck sessions as timeouts.
+
+**Repo-pattern relationship**: Departs from the exhaustiveness-everywhere
+pattern. The assertNever guard pattern exists precisely to avoid this.
+
+**Scope judgment**: Too narrow -- preserves the routing problem this pitch
+exists to solve.
+
+**Rejected because**: Violates philosophy, does not resolve the core tension,
+and the pitch explicitly rejects conflating stuck with timeout.
+
+---
+
+## Comparison and Recommendation
+
+Candidate A is the only viable candidate. All analysis converges.
+
+The core recommendation is to implement Candidate A exactly as specified in
+`.workrail/current-pitch.md`, with one addition not noted in the pitch:
+update `NotificationPayload.outcome` union to include `'stuck'` (required for
+`buildOutcome()` to compile).
+
+---
+
+## Self-Critique
+
+**Strongest counter-argument**: Adding a 5th variant to WorkflowRunResult
+increases cognitive load for callers. Counter: assertNever guards make missing
+cases compile errors, which is the correct safeguard. The complexity cost is
+paid once (at implementation) and enforced automatically.
+
+**Narrower option that lost**: Update only WorkflowRunResult, skip
+ChildWorkflowRunResult. Lost because: runtime crash in makeSpawnAgentTool
+when a child hits stuck-abort. The cast at line 2172 provides no protection.
+
+**Broader option not justified**: Adding `onStuck:` hook to TriggerDefinition.
+Explicitly deferred per pitch No-Gos. Would require trigger-store.ts parser
+changes -- outside the 4-file scope.
+
+**Pivot condition**: If `assertNever(childResult)` were removed in favor of a
+logged fallback, ChildWorkflowRunResult update would be less critical. It is
+not removed, so the atomic update is required.
+
+---
+
+## Open Questions for the Main Agent
+
+None. All design decisions are resolved in the pitch. The only implementation
+detail requiring attention is the `NotificationPayload.outcome` union widening
+(add 'stuck') -- verify this compiles before finalizing.

package/docs/design/design-review-findings-stuck-escalation.md

@@ -0,0 +1,93 @@
+# Design Review Findings: WorkTrain Stuck-Escalation
+
+*Generated: 2026-04-19 | Pitch: .workrail/current-pitch.md*
+
+---
+
+## Tradeoff Review
+
+| Tradeoff | Status | Condition for Failure |
+|----------|--------|-----------------------|
+| One more union variant in WorkflowRunResult | Acceptable | All callers use assertNever guards -- compile error enforces handling |
+| ChildWorkflowRunResult atomic update relies on discipline | Managed | Fails only if commit is split; mitigated by single-PR implementation and compile-time test |
+| NotificationPayload.outcome union widening (gap, not tradeoff) | Resolved | Add 'stuck' to outcome union; caught by npm run build |
+
+---
+
+## Failure Mode Review
+
+| Failure Mode | Severity | Design Handling | Missing Mitigation |
+|--------------|----------|-----------------|--------------------|
+| ChildWorkflowRunResult not updated | High | Atomic commit, compile-time assignability test | None beyond discipline |
+| stuckReason / timeoutReason race | Low | First-writer-wins guard; max_turns early return prevents race | None needed |
+| writeStuckOutboxEntry fails | Low | Fire-and-forget, console.warn on error | None -- intentional |
+| no_progress fires on research workflow | Low | noProgressAbortEnabled defaults to false | None needed |
+| NotificationPayload.outcome compile error | Medium | Add 'stuck' to union | None -- caught at build |
+
+---
+
+## Runner-Up / Simpler Alternative Review
+
+- **Candidate B** (extend WorkflowRunTimeout.reason): No elements worth borrowing.
+  Does not resolve the core routing tension.
+- **Skip ChildWorkflowRunResult**: Not acceptable -- runtime crash in parent session.
+- **Skip sessionStartMs**: Not recommended -- pitch explicitly adds it for Signal 5 follow-up
+  to avoid future restructuring.
+- **Inline outbox write**: Works but reduces turn_end subscriber readability. Not worth it.
+
+No hybrid opportunities identified.
+
+---
+
+## Philosophy Alignment
+
+| Principle | Status |
+|-----------|--------|
+| Make illegal states unrepresentable | Satisfied |
+| Exhaustiveness everywhere | Satisfied |
+| Errors are data | Satisfied |
+| Immutability by default | Satisfied |
+| Type safety as first line of defense | Under tension (pre-existing cast; improved but not fully resolved) |
+| Fire-and-forget for side effects | Satisfied |
+
+---
+
+## Findings
+
+### Yellow: NotificationPayload.outcome union widening not specified in pitch
+
+The pitch states 'buildOutcome() returns result._tag directly -- no change needed'.
+However, the return type annotation `NotificationPayload['outcome']` will cause a
+TypeScript compile error when 'stuck' is added to WorkflowRunResult but not to the
+outcome union. **Resolution**: add `'stuck'` to `NotificationPayload.outcome` union
+in notification-service.ts. This is a mechanical fix, not a design change.
+
+### Yellow: Pre-existing `as ChildWorkflowRunResult` cast at line 2172
+
+The cast suppresses TypeScript's compile-time check that would otherwise catch a
+missing ChildWorkflowRunResult update. This PR updates the union and adds a
+compile-time assignability test to partially compensate. Removing the cast is
+out of scope. **Residual concern**: future union additions must be caught by the
+test rather than the compiler.
+
+---
+
+## Recommended Revisions
+
+1. Add `'stuck'` to `NotificationPayload.outcome` union (not in pitch, required for compile).
+2. Add compile-time assignability test for `ChildWorkflowRunResult` in the test file.
+3. Document the `as ChildWorkflowRunResult` cast issue in a code comment at line 2172
+   (or verify existing comment is sufficient).
+
+---
+
+## Residual Concerns
+
+- The `as ChildWorkflowRunResult` cast remains. Future contributors adding a new
+  WorkflowRunResult variant may forget to update ChildWorkflowRunResult. The
+  compile-time test in the stuck-escalation test file partially mitigates this,
+  but only for the stuck variant. A broader structural fix (removing the cast)
+  is a follow-up.
+- Webhook consumers reading `outcome: 'stuck'` must handle the new value.
+  This is a new feature, not a breaking change, but operators consuming the
+  webhook should be aware.