@exaudeus/workrail 3.42.0 → 3.44.0

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

@@ -0,0 +1,176 @@
+# Design Candidates: Stuck Escalation for Overnight-Autonomous WorkTrain Sessions
+
+> Raw investigative material for main-agent review. Not a final decision.
+
+## Problem Understanding
+
+### Core Tensions
+
+1. **Early certainty vs. false positives.** Aborting at threshold 3 for `repeated_tool_call` saves up to 27 minutes of a 30-minute session. But a legitimate retry loop (transient network error, idempotent file read called 3x) also triggers at 3. Higher threshold = fewer false positives but less wall-clock savings; lower = more savings but more false positives.
+
+2. **Structural correctness vs. maintenance surface.** Adding `_tag: 'stuck'` to `WorkflowRunResult` is structurally clean (make illegal states unrepresentable) but widens the maintenance surface: every switch on the union must be updated. The naive alternative (add `reason: 'stuck_loop'` to `WorkflowRunTimeout`) avoids the new variant but conflates stuck abort with wall-clock timeout -- these have categorically different implications for retry logic.
+
+3. **Abort power vs. future recoverability.** `agent.abort()` is terminal. A `steer()` injection could warn the agent and let it self-correct. Aborting closes the door to LLM-driven self-recovery. For overnight-autonomous use, abort is deterministic and saves resources. For supervised use, steer-and-warn might be preferred.
+
+4. **Outbox write timing vs. fire-and-forget contract.** The outbox write must happen as close as possible to the abort moment. But `turn_end` is synchronous, and any blocking `await` would stall the abort path. Resolution: initiate outbox write as a detached fire-and-forget Promise in `turn_end`, same contract as `DaemonEventEmitter.emit()`.
+
+### Likely Seam
+
+`turn_end` subscriber in `workflow-runner.ts`. Confirmed -- not just where the symptom appears, but where all relevant state exists (`turnCount`, `stepAdvanceCount`, `lastNToolCalls`, `timeoutReason`). The `max_turns` abort at lines 3088-3104 is the exact template: set closure variable, emit event, call `agent.abort()`, return.
+
+### What Makes This Hard
+
+1. `ChildWorkflowRunResult` type alias (line 396) -- must be updated alongside `WorkflowRunResult`. If missed, the cast at line 2014 silently hides the new variant from `makeSpawnAgentTool`'s switch, producing a runtime `assertNever` error in production.
+
+2. The fire-and-forget contract -- any `await` in the `turn_end` subscriber blocks the abort path. The outbox write must be a detached Promise.
+
+3. Double-emit of `timeout_imminent` -- the max_turns path emits it AND the `timeoutReason !== null` check at line 3157 would also emit it. The design must not add a third abort here.
+
+4. `maybeRunDelivery` gate in TriggerRouter -- must exclude `stuck` results from autoCommit delivery (there is no successful output to commit).
+
+## Philosophy Constraints
+
+From `CLAUDE.md` and codebase patterns:
+
+- **Make illegal states unrepresentable** -- stuck and timeout are categorically different; a new discriminant is required.
+- **Exhaustiveness everywhere** -- all `assertNever` guards must be updated when the union grows.
+- **Errors are data** -- `WorkflowRunStuck` as a result value, not an exception.
+- **Fire-and-forget observability** -- `DaemonEventEmitter.emit()` and `NotificationService.notify()` both return void and swallow errors. Outbox write must follow this contract.
+- **YAGNI with discipline** -- do not add `issue_reported severity=fatal` abort without production evidence.
+- **Pure functions for message building** -- `buildNotificationBody`, `buildOutcome`, `buildDetail` are pure switch-dispatch functions; new cases extend them cleanly.
+- **WHY comments** -- every non-obvious decision must have an inline rationale comment.
+
+No conflicts between stated philosophy and repo patterns.
+
+## Impact Surface
+
+Changes required beyond the immediate task if `WorkflowRunResult` is widened:
+
+| Location | File | Required Change |
+|---|---|---|
+| `WorkflowRunResult` type alias | `workflow-runner.ts` | Add `WorkflowRunStuck` variant |
+| `ChildWorkflowRunResult` type alias | `workflow-runner.ts` | Add `WorkflowRunStuck` variant |
+| `makeSpawnAgentTool` switch | `workflow-runner.ts` | Add `stuck` case (assertNever guard) |
+| `turn_end` subscriber | `workflow-runner.ts` | Add abort logic for `repeated_tool_call` and `no_progress` |
+| `runWorkflow()` catch block | `workflow-runner.ts` | Add branch: if `stuckContext !== null` return `WorkflowRunStuck` |
+| `TriggerRouter.route()` | `trigger-router.ts` | Add `stuck` log branch before `assertNever` |
+| `TriggerRouter.dispatch()` | `trigger-router.ts` | Add `stuck` log branch before `assertNever` |
+| `maybeRunDelivery` gate | `trigger-router.ts` | Exclude `stuck` from delivery |
+| `buildNotificationBody` | `notification-service.ts` | Add `stuck` case |
+| `buildOutcome` | `notification-service.ts` | Add `stuck` to return type |
+| `buildDetail` | `notification-service.ts` | Add `stuck` case |
+| `NotificationPayload.outcome` | `notification-service.ts` | Add `'stuck'` to union |
+| `TriggerDefinition.agentConfig` | `types.ts` | Add `stuckAbortPolicy?: 'abort' | 'notify_only'` |
+
+## Candidates
+
+### Candidate A: Minimal -- Abort with existing result types
+
+**Summary:** Wire `agent.abort()` after `repeated_tool_call` emit, add `reason: 'stuck_loop'` to `WorkflowRunTimeout` (new string value), skip outbox write and notification extension.
+
+**Tensions resolved:** Maintenance surface (2 files changed).
+
+**Tensions accepted:** Structural correctness (conflates stuck with wall-clock timeout), coordinator readiness (no toolName/argsSummary in result), notification distinctness (NotificationService cannot distinguish stuck from timeout).
+
+**Boundary solved at:** `turn_end` subscriber + `WorkflowRunTimeout` extension. This is a symptom-level fix -- it stops the waste but provides no diagnostic value.
+
+**Failure mode:** A coordinator script reading `result._tag === 'timeout'` has no way to distinguish stuck abort from wall-clock timeout without parsing `result.reason`. This is string parsing -- exactly what discriminated unions are designed to prevent.
+
+**Repo pattern relationship:** Adapts max_turns abort template. Does NOT follow the `WorkflowRunTimeout` vs. `WorkflowRunError` precedent of 'one variant per categorically distinct outcome.'
+
+**Gains:** 2 files changed. Minimal assertNever surface.
+
+**Gives up:** Semantic precision (stuck != timeout), coordinator readiness, notification distinctness.
+
+**Scope judgment:** Too narrow. Violates 'make illegal states unrepresentable.'
+
+**Philosophy:** Honors YAGNI. Conflicts with 'make illegal states unrepresentable', 'exhaustiveness everywhere', 'errors are data.'
+
+---
+
+### Candidate B: Full -- New `WorkflowRunStuck` variant + outbox + notification (RECOMMENDED)
+
+**Summary:** Add `WorkflowRunStuck` to `WorkflowRunResult` and `ChildWorkflowRunResult`; abort on `repeated_tool_call` and `no_progress`; write a 10-field outbox entry as a fire-and-forget Promise; extend `NotificationService` with a `stuck` case; add `stuckAbortPolicy: 'abort' | 'notify_only'` to `WorkflowTrigger.agentConfig`.
+
+**Tensions resolved:** All four. Structural correctness (new variant), coordinator readiness (toolName/argsSummary/turnCount/stepAdvanceCount on the result), notification distinctness (new message body), policy expressiveness (stuckAbortPolicy with abort default).
+
+**Tensions accepted:** Maintenance surface (5 files, all switch statements widened), policy granularity (no per-signal policy within a trigger -- only per-trigger).
+
+**Boundary solved at:**
+- `turn_end` subscriber: abort + fire-and-forget outbox write
+- `runWorkflow()` catch block: construct `WorkflowRunStuck` from `stuckContext` closure variable
+- `TriggerRouter.route()`/`dispatch()`: log and skip delivery
+- `NotificationService.notify()`: new message body
+
+**Failure mode:** The outbox write initiates in `turn_end` as a detached Promise but the `WorkflowRunStuck` result is returned synchronously from the catch block. The outbox write may complete AFTER the result reaches TriggerRouter. Acceptable (outbox is diagnostic, not delivery) but must be documented.
+
+**Repo pattern relationship:** Follows the `WorkflowRunTimeout` precedent exactly. Uses `DaemonEventEmitter` fire-and-forget pattern for outbox write. Uses max_turns abort template. Extends `NotificationService` pure-function pattern.
+
+**Gains:** Full semantic precision, coordinator-ready structured data, notification distinctness, type-safe exhaustiveness.
+
+**Gives up:** 5-file maintenance surface, `ChildWorkflowRunResult` and `makeSpawnAgentTool` must be updated.
+
+**Scope judgment:** Best-fit. Directly addresses all 4 decision criteria. No speculative abstractions.
+
+**Philosophy:** Honors all core principles. Minor YAGNI pressure vs. Candidate A, but the added files are necessary consequences of correct union design.
+
+---
+
+### Candidate C: Extended -- Candidate B + `issue_reported severity=fatal` abort trigger
+
+**Summary:** All of Candidate B, plus: abort when the `onIssueSummary` callback receives `severity: 'fatal'`, implemented via a `fatalIssueAbortPending` closure flag set by the callback and checked/cleared in `turn_end`. Adds `stuckReason: 'fatal_issue_report'` to `WorkflowRunStuck` and an optional `issueSummary` field.
+
+**Tensions resolved:** All of Candidate B's tensions, plus the primary framing risk (agent self-report is more reliable than heuristics per session ea2de6e5).
+
+**Tensions accepted:** Higher implementation complexity, one-turn abort latency for fatal issues (the flag is checked in `turn_end`, not inline in the callback).
+
+**Boundary solved at:** All of Candidate B's boundaries, plus `onIssueSummary` callback wiring.
+
+**Failure mode:** One-turn latency -- the abort fires on the turn AFTER `report_issue` calls, not immediately. For a fatal issue, one extra LLM turn is acceptable but must be documented.
+
+**Repo pattern relationship:** Extends Candidate B. Adapts the existing `onIssueSummary` callback infrastructure.
+
+**Gains:** Catches the most reliable real-world stuck signal. Directly addresses primary framing risk.
+
+**Gives up:** Higher initial complexity. `stuckReason` union grows to 3 values. Requires production evidence to justify over Candidate B.
+
+**Scope judgment:** Slightly broad for the initial design. The primary use case (blind tool loop) is covered by Candidate B. Candidate C is the correct Phase 2 extension.
+
+**Philosophy:** Fully honors all principles. Marginal YAGNI pressure vs. Candidate B -- grounded in real log evidence (session ea2de6e5) but requires more than one data point to justify the added complexity upfront.
+
+## Comparison and Recommendation
+
+| Criterion | A | B | C |
+|---|---|---|---|
+| Structural correctness | FAIL | PASS | PASS |
+| Coordinator readiness | FAIL | PASS | PASS |
+| Notification distinctness | FAIL | PASS | PASS |
+| Policy expressiveness | PARTIAL | PASS | PASS |
+| Maintenance surface | Best | Medium | Highest |
+| Covers primary framing risk | No | No | Yes |
+| YAGNI compliance | Best | Good | Marginal |
+| Reversibility | Hard | Easy | Easy |
+
+**Recommendation: Candidate B.**
+
+Reasoning: Structural correctness is non-negotiable (CLAUDE.md: 'make illegal states unrepresentable'). Candidate A fails this criterion regardless of its maintenance advantage. Candidate C is architecturally correct but the `issue_reported severity=fatal` trigger requires production evidence beyond session ea2de6e5. The 5-file surface of Candidate B is manageable because all changes are additive switch-case additions, and TypeScript exhaustiveness enforcement catches any missed location at compile time.
+
+## Self-Critique
+
+**Strongest counter-argument against Candidate B:** The `repeated_tool_call` heuristic may have an unacceptable false-positive rate in production. If it aborts legitimate sessions frequently, operators will set `stuckAbortPolicy: 'notify_only'` everywhere, negating the feature. A minimal Candidate A approach would have caused less collateral damage in this scenario.
+
+**Response:** The `stuckAbortPolicy: 'notify_only'` escape hatch directly addresses this. The structural correctness argument still stands -- conflating stuck with timeout is a design debt that compounds over time.
+
+**Pivot to Candidate A:** If there is a hard constraint against widening `WorkflowRunResult` (e.g., a serialization layer or cross-process protocol that can't handle new variants). No such constraint exists.
+
+**Pivot to Candidate C:** If production logs show `repeated_tool_call` false-positive rate exceeds 20% while `issue_reported severity=fatal` false-positive rate is under 5%.
+
+## Open Questions for the Main Agent
+
+1. **Verify abort propagation:** Does `agent.abort()` called in `turn_end` correctly propagate to the `runWorkflow()` catch block without clearing closure state? The `stuckContext` variable must be readable in the catch block after abort. Confirm by reading `AgentLoop.abort()` implementation.
+
+2. **`sessionStartMs` presence:** Is `const sessionStartMs = Date.now()` already set before the agent loop in `runWorkflow()`? If not, it must be added to support `elapsedMs` in the outbox entry.
+
+3. **`no_progress` false-positive rate:** The 80%-turns threshold fires even on a legitimate research session. Should the initial design wire `no_progress` abort, or start with only `repeated_tool_call` abort and add `no_progress` in a follow-on?
+
+4. **`stuckAbortPolicy` placement:** Should the policy live in `WorkflowTrigger.agentConfig` (as proposed), or in a separate top-level `TriggerDefinition.stuckPolicy` field to distinguish session-behavior knobs from routing knobs?

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

@@ -0,0 +1,70 @@
+# Design Review: Stuck Escalation for Overnight-Autonomous WorkTrain Sessions
+
+> Findings from adversarial review of the selected direction (Candidate B, adjusted).
+
+## Tradeoff Review
+
+| Tradeoff | Verdict | Condition That Invalidates It |
+|---|---|---|
+| 5-file maintenance surface for type safety | ACCEPTABLE | Union grows to 20+ consumers without a code-gen layer |
+| `sessionStartMs` must be added | TRIVIALLY ACCEPTABLE | None |
+| `no_progress` abort gated by `noProgressAbortEnabled` (default false) | ACCEPTABLE | Production evidence shows `no_progress` is the dominant failure mode |
+
+## Failure Mode Review
+
+| Failure Mode | Design Handling | Missing Mitigation | Risk |
+|---|---|---|---|
+| `ChildWorkflowRunResult` not updated | Called out in design doc as required update | Add explicit WARNING comment at cast site (line 2014) | HIGH -- silent compile-time pass, runtime crash |
+| `await` in `turn_end` subscriber blocks abort | Fire-and-forget pattern specified explicitly | Add WHY comment at the outbox write call | MEDIUM -- junior devs may add await by analogy |
+| `maybeRunDelivery` not updated | Existing gate `if (result._tag !== 'success') return` already handles it | None needed | LOW -- already handled |
+
+## Runner-Up / Simpler Alternative Review
+
+**Candidate C element borrowed:** `issueSummaries?: readonly string[]` added to `WorkflowRunStuck`. The `issueSummaries` array is already tracked in session closures (zero new collection code). Adds coordinator-readiness at near-zero cost.
+
+**Simplest alternative:** Abort on `repeated_tool_call` only, no `no_progress` gate, no `issueSummaries`. Satisfies all 6 acceptance criteria. Excluded because `issueSummaries` and `noProgressAbortEnabled` add meaningful value at minimal cost.
+
+**Hybrid result:** Candidate B adjusted = Candidate B + `issueSummaries` field (borrowed from C) + `noProgressAbortEnabled: boolean` gate (default false) for `no_progress` abort.
+
+## Philosophy Alignment
+
+| Principle | Alignment |
+|---|---|
+| Make illegal states unrepresentable | FULL -- new discriminant, not reused timeout |
+| Exhaustiveness everywhere | FULL -- all assertNever guards updated |
+| Errors are data | FULL -- result value, not exception |
+| Immutability by default | FULL -- all new fields readonly |
+| Fire-and-forget observability | FULL -- outbox write is void+detached+swallowed |
+| YAGNI | TENSION -- 5-file surface; resolved in favor of structural correctness |
+| Determinism over cleverness | TENSION -- no_progress is a heuristic; resolved by gating it behind explicit opt-in |
+
+## Findings
+
+### RED (Blocking)
+None. No design-correctness violations found.
+
+### ORANGE (High Risk)
+**Finding O1: `ChildWorkflowRunResult` update is easy to miss.**\nThe coding agent must update `ChildWorkflowRunResult` alongside `WorkflowRunResult`. If missed, a `_tag: 'stuck'` result from a child session spawned via `makeSpawnAgentTool` will reach `assertNever` at runtime and crash. The design doc mentions it but the failure mode is severe enough to warrant a WARNING comment in the code at the cast site (line 2014 in workflow-runner.ts).\n\n**Recommended action:** Add to design doc: 'CRITICAL: Update ChildWorkflowRunResult on the SAME commit as WorkflowRunResult. Do not split across commits.'
+
+### YELLOW (Medium Risk)
+**Finding Y1: `no_progress` false-positive rate is unvalidated.**\nThe 80%-turns threshold with 0 step advances can fire on legitimate deep-research sessions. The `noProgressAbortEnabled: false` default mitigates this but means the feature is effectively inactive until explicitly enabled. Users who expect `no_progress` to work out-of-the-box will be surprised.\n\n**Recommended action:** Document the default explicitly in the trigger YAML schema comment and in the CLI help text.
+
+**Finding Y2: Fire-and-forget outbox write timing.**\nThe outbox write initiates in `turn_end` as a detached Promise but the `WorkflowRunStuck` result reaches TriggerRouter before the write completes. If the process exits immediately after TriggerRouter logs the result (e.g. during a rapid daemon shutdown), the outbox write may be lost.\n\n**Recommended action:** Accept this risk -- it is the same risk accepted by `DaemonEventEmitter`. Document it in the code with a WHY comment.
+
+## Recommended Revisions to Design Doc
+
+1. Add a **CRITICAL** callout in the '5-File Change Estimate' section: 'ChildWorkflowRunResult must be updated in the same commit as WorkflowRunResult. A cast at line 2014 allows a stuck result to bypass the makeSpawnAgentTool switch's assertNever if ChildWorkflowRunResult is not updated.'
+
+2. Add `issueSummaries?: readonly string[]` to the `WorkflowRunStuck` interface definition. Update the outbox entry schema to include `issueSummaries`.
+
+3. Add `noProgressAbortEnabled?: boolean` (default: false) to `WorkflowTrigger.agentConfig` as a separate field from `stuckAbortPolicy`. The abort policy controls whether to abort or notify; this flag controls whether `no_progress` is an active trigger at all.
+
+4. Update the '5-File Change Estimate' table to show 5 files clearly (the confusion is that workflow-runner.ts has multiple edit locations).
+
+## Residual Concerns
+
+1. **`repeated_tool_call` false-positive rate**: Not empirically validated. The `stuckAbortPolicy: 'notify_only'` escape hatch is the mitigation. If the false-positive rate is high in production, the recommended path is: set `stuckAbortPolicy: 'notify_only'` by default and make `'abort'` opt-in, reversing the current default.
+
+2. **Coordinator consumption of outbox.jsonl**: `outbox.jsonl` has no automated consumer today. The stuck entry will persist in the file until a human or coordinator reads it. This is a 'build it now, connect it later' tradeoff -- acceptable for the initial design.
+
+3. **No shadow-mode validation**: Ideally, the heuristics would run in shadow mode (emit but never abort) for 20+ production sessions before enabling abort. This design does not include shadow mode. The `stuckAbortPolicy: 'notify_only'` setting can serve as a manual shadow mode.

package/docs/design/stuck-escalation.md

@@ -0,0 +1,326 @@
+# Design: Stuck Escalation for Overnight-Autonomous WorkTrain Sessions
+
+## Context / Ask
+
+**Stated goal:** Design automatic escalation when WorkTrain sessions get stuck, so overnight-autonomous runs don't burn their full 30-minute wall clock on a broken tool call.
+
+**This goal is a solution statement.** The underlying problem is:
+
+> Overnight-autonomous sessions have no early-exit path when the agent enters a stuck loop. The system must detect the stuck state, abort cleanly, and produce structured diagnostic output without requiring a human to check the logs after the full wall-clock budget is consumed.
+
+**Scope:** `src/daemon/workflow-runner.ts` and `src/trigger/trigger-router.ts` only. Do NOT touch `src/mcp/`.
+
+**Prior art:** `docs/design/daemon-stuck-detection-discovery.md` -- discovery that defined the three stuck heuristics, added `AgentStuckEvent` to `daemon-events.ts`, and wired `repeated_tool_call`, `no_progress`, and `timeout_imminent` into the `turn_end` subscriber. Those signals exist and fire today. They are advisory-only -- no abort, no outbox, no notification.
+
+## Path Recommendation
+
+**`full_spectrum`** -- both landscape grounding (where to hook abort/outbox in the existing code) and concept shaping (abort policy, result variant design) are real risks. The proposed approach is well-matched to the problem, but the integration point and the result type design need careful analysis.
+
+## Constraints / Anti-goals
+
+**Constraints:**
+- Abort only within `src/daemon/` and `src/trigger/`. No changes to `src/mcp/`.
+- `WorkflowRunResult` is a discriminated union consumed by `assertNever` in `TriggerRouter.route()` and `dispatch()` -- any new variant must be handled exhaustively in both callers.
+- Outbox write must be best-effort (non-fatal) -- same contract as `DaemonEventEmitter.emit()`.
+- Notifications are fire-and-forget -- same contract as `NotificationService.notify()`.
+- `stuckAbortPolicy` must be opt-in, defaulting to `'abort'` for new triggers and to `'notify_only'` for any existing trigger that doesn't specify it (to avoid breaking existing behavior).
+
+**Anti-goals:**
+- Do not build a watchdog daemon or restart mechanism.
+- Do not implement coordinator retry logic in this design (that is a future fix-coordinator concern).
+- Do not change the `turn_end` subscriber's detection thresholds -- this design wires actions to existing signals, not new signals.
+- Do not make `outbox.jsonl` the sole escalation path -- it has no automated consumer.
+
+## Challenged Assumptions
+
+1. **Assumption: The three heuristics reliably distinguish stuck from legitimately slow.**
+   - Risk: `make all` called 3x triggers `repeated_tool_call` but is not stuck. `no_progress` at 80% turns fires during valid deep research.
+   - Mitigation: `stuckAbortPolicy: 'notify_only'` available per trigger. For `repeated_tool_call`, the abort is justified because the exact same `argsSummary` (200-char JSON) repeating 3x is a stronger signal than mere tool-name repetition.
+
+2. **Assumption: Aborting on first heuristic trigger is better than one warning turn.**
+   - Risk: a transient 500 error resolves on the next turn; abort kills a recovering session.
+   - Mitigation: allow `stuckAbortThreshold` (future extension) to increase the repeat count before abort. For the initial design, threshold stays at 3 (existing `STUCK_REPEAT_THRESHOLD`).
+
+3. **Assumption: `outbox.jsonl` is the right escalation target.**
+   - Reality: `outbox.jsonl` has no automated consumer -- only `worktrain-inbox` (manual CLI) and `pr-review.ts` `drainMessageQueue` read it. The primary actionable signal is the macOS/webhook notification.
+   - Resolution: write to both outbox (for coordinator scripts) AND fire notification (for human overnight use). Neither is the sole path.
+
+## Landscape Packet
+
+### Integration point: where abort already happens
+
+In `workflow-runner.ts` the `turn_end` subscriber already has two abort paths:
+
+```
+// max_turns path (line 3088-3104)
+if (maxTurns > 0 && turnCount >= maxTurns && timeoutReason === null) {
+  timeoutReason = 'max_turns';
+  emitter?.emit({ kind: 'agent_stuck', reason: 'timeout_imminent', ... });
+  agent.abort();
+  return;
+}
+
+// stuck detection heuristics (lines 3106-3165)
+// -- repeated_tool_call: emit only, no abort
+// -- no_progress: emit only, no abort
+// -- timeout_imminent: emit only (abort already fired in setTimeout callback)
+```
+
+The stuck abort must be inserted immediately after each heuristic `emitter?.emit()` call, guarded by `stuckAbortPolicy`.
+
+### WorkflowRunResult union (current)
+
+```typescript
+type WorkflowRunResult =
+  | WorkflowRunSuccess        // _tag: 'success'
+  | WorkflowRunError          // _tag: 'error'
+  | WorkflowRunTimeout        // _tag: 'timeout'
+  | WorkflowDeliveryFailed    // _tag: 'delivery_failed'
+```
+
+`TriggerRouter.route()` and `dispatch()` both have `assertNever(result)` guards. Adding a new `_tag: 'stuck'` variant requires handling in both.
+
+### outbox.jsonl write pattern (from pr-review.ts)
+
+```typescript
+const outboxPath = path.join(os.homedir(), '.workrail', 'outbox.jsonl');
+await fs.mkdir(workrailDir, { recursive: true });
+await fs.appendFile(outboxPath, JSON.stringify(entry) + '\n', 'utf8');
+```
+
+No shared utility -- each writer does it directly. The stuck-escalation writer should follow the same pattern, injected via `WorkflowTrigger` deps or called as a module-level helper.
+
+### NotificationService (notification-service.ts)
+
+`notify(result: WorkflowRunResult, goal: string)` -- already dispatches on `result._tag`. Adding a `stuck` variant requires a new case in `buildNotificationBody()`, `buildOutcome()`, and `buildDetail()`.
+
+### agentConfig in WorkflowTrigger (workflow-runner.ts line 214)
+
+```typescript
+readonly agentConfig?: {
+  readonly model?: string;
+  readonly maxSessionMinutes?: number;
+  readonly maxTurns?: number;
+  // NEW:
+  readonly stuckAbortPolicy?: 'abort' | 'notify_only';
+  readonly noProgressAbortEnabled?: boolean;
+};
+```
+
+This is the correct location for both new fields. They are session-behavior knobs, same as `maxSessionMinutes` and `maxTurns` -- not trigger-routing knobs.
+
+## Problem Frame Packet
+
+The three stuck heuristics (`repeated_tool_call`, `no_progress`, `timeout_imminent`) fire today as advisory events. There is no action. For overnight-autonomous use, the invariant must change:
+
+- `repeated_tool_call` is a **hard abort signal** -- same tool+args 3x is definitionally broken.
+- `no_progress` at 80% turns is a **soft abort signal** -- may have false positives; the policy controls whether to abort or just notify.
+- `timeout_imminent` already has an abort (the wall-clock timer fires `agent.abort()` independently) -- no new abort needed here, but a stuck-escalation outbox entry and notification should fire.
+
+After abort, `runWorkflow()` must return a new `WorkflowRunResult` variant that carries enough structured data for a human and a future fix-coordinator to understand the failure without reading logs.
+
+## Recommended Design
+
+### 1. Abort Policy
+
+| Signal | Default action | With `stuckAbortPolicy: 'notify_only'` | Gating flag |
+|---|---|---|---|
+| `repeated_tool_call` | Abort immediately | Emit event only, no abort | Always active |
+| `no_progress` | Emit + notify only | Emit + notify only | `noProgressAbortEnabled: true` required to abort |
+| `timeout_imminent` | No new abort (already aborting) | Same | N/A |
+
+**`stuckAbortPolicy: 'abort' | 'notify_only'`** (default: `'abort'`): controls whether a stuck signal triggers an abort or only an event emission and notification. Per-trigger, lives in `agentConfig`.
+
+**`noProgressAbortEnabled: boolean`** (default: `false`): separately gates whether the `no_progress` heuristic (80% turns, 0 step advances) can trigger an abort. When false, `no_progress` only emits the `agent_stuck` event and fires a notification -- it never aborts. This flag exists because `no_progress` has a meaningful false-positive rate on legitimate deep-research sessions (e.g. a wr.discovery run spending 50 turns before its first step advance).
+
+**Rationale for the default `noProgressAbortEnabled: false`:** The primary overnight-autonomous failure mode is `repeated_tool_call` (the same failing command called 15x). The `no_progress` heuristic is a secondary signal that benefits from explicit opt-in after the false-positive rate is observed in production.
+
+### 2. New `WorkflowRunResult` Variant
+
+```typescript
+/** Workflow aborted by stuck detection before the wall-clock timeout fired. */
+export interface WorkflowRunStuck {
+  readonly _tag: 'stuck';
+  readonly workflowId: string;
+  /**
+   * Which heuristic triggered the abort.
+   * Matches AgentStuckEvent.reason to allow correlation with daemon event log.
+   */
+  readonly stuckReason: 'repeated_tool_call' | 'no_progress';
+  /** Human-readable description of why stuck was detected. */
+  readonly detail: string;
+  /** The tool name that was called repeatedly (present for repeated_tool_call). */
+  readonly toolName?: string;
+  /** The argsSummary of the repeated call (present for repeated_tool_call). */
+  readonly argsSummary?: string;
+  /** Total LLM turns consumed at the time of abort. */
+  readonly turnCount: number;
+  /** Number of workflow step advances at the time of abort. */
+  readonly stepAdvanceCount: number;
+  /**
+   * Wall-clock milliseconds elapsed from session start to abort.
+   * Lets a coordinator compute wall-clock savings vs. a full timeout.
+   * Requires `sessionStartMs = Date.now()` to be added before the agent loop.
+   */
+  readonly elapsedMs: number;
+  /**
+   * Summaries of all issue_reported calls during this session (if any).
+   * Populated from the `issueSummaries` ring tracked by the onIssueSummary callback.
+   * Provides additional context for a fix-coordinator without requiring log parsing.
+   */
+  readonly issueSummaries?: readonly string[];
+}
+
+// Updated union:
+export type WorkflowRunResult =
+  | WorkflowRunSuccess
+  | WorkflowRunError
+  | WorkflowRunTimeout
+  | WorkflowDeliveryFailed
+  | WorkflowRunStuck;    // NEW
+```
+
+**Why a new variant instead of reusing `WorkflowRunError` or `WorkflowRunTimeout`:**
+- `WorkflowRunError` means a tool or engine error, not a stuck loop. Conflating them forces consumers to parse message strings.
+- `WorkflowRunTimeout` means the wall-clock fired -- stuck abort happens _before_ the wall clock fires.
+- A distinct `_tag: 'stuck'` lets `TriggerRouter`, `NotificationService`, and future coordinators distinguish the case at compile time with `assertNever` exhaustiveness.
+
+**`ChildWorkflowRunResult` must also be updated** to include `WorkflowRunStuck` since `runWorkflow()` now produces it directly (not via `TriggerRouter`).
+
+### 3. Outbox Entry Schema
+
+Written to `~/.workrail/outbox.jsonl` as a single JSONL line immediately after abort:
+
+```json
+{
+  "id": "<uuid-v4>",
+  "kind": "stuck_session",
+  "sessionId": "<local-uuid>",
+  "workrailSessionId": "<sess_...>",
+  "workflowId": "<workflow-id>",
+  "stuckReason": "repeated_tool_call",
+  "detail": "Same tool+args called 3 times: Bash",
+  "toolName": "Bash",
+  "argsSummary": "{\"command\":\"npm test\"}",
+  "turnCount": 12,
+  "stepAdvanceCount": 0,
+  "elapsedMs": 94000,
+  "issueSummaries": ["Tool call failed: ENOENT /path/to/file"],
+  "timestamp": "2026-04-19T03:14:15.926Z"
+}
+```
+
+**Fields needed by a future fix-coordinator:**
+- `stuckReason` + `toolName` + `argsSummary` -- to classify the failure and decide whether to retry
+- `turnCount` + `stepAdvanceCount` -- to understand how much progress was lost
+- `workrailSessionId` -- to correlate with WorkRail session store for checkpoint resumption
+- `elapsedMs` -- to measure wall-clock savings vs. a full timeout
+
+### 4. Integration Point
+
+**Location: inside the `turn_end` subscriber in `runWorkflow()`, immediately after each stuck heuristic `emitter?.emit()` call.**
+
+Rationale:
+- This is where `agent.abort()` already lives for `max_turns`.
+- `turnCount`, `stepAdvanceCount`, `sessionStartMs`, `toolName`, `argsSummary` are all in scope as closures.
+- Post-run handling in `TriggerRouter.route()` is the wrong layer: by the time `runWorkflow()` returns, the outbox write should already have happened (it's diagnostic context for the abort, not post-hoc delivery).
+
+**Abort sequence (for `repeated_tool_call`):**
+1. Check: `stuckAbortPolicy !== 'notify_only'` (default: abort)
+2. Set `stuckReason` and `stuckContext` closure variables
+3. Call `agent.abort()`
+4. Write outbox entry (best-effort, non-fatal, fire-and-forget pattern)
+5. Return from `turn_end` subscriber (same as `max_turns` path)
+6. `runWorkflow()` catches the abort and returns `WorkflowRunResult` with `_tag: 'stuck'`
+
+**`runWorkflow()` return path:**
+The existing error-catch block needs a branch for the stuck abort. The `stuckContext` closure variable (set in step 2 above) distinguishes stuck abort from other aborts:
+
+```typescript
+// Existing error catch in runWorkflow():
+} catch (err) {
+  if (stuckContext !== null) {
+    return {
+      _tag: 'stuck',
+      workflowId: trigger.workflowId,
+      ...stuckContext,
+    };
+  }
+  // ... existing error handling
+}
+```
+
+### 5. TriggerRouter Changes
+
+Both `route()` and `dispatch()` need a new branch before the `assertNever` guard:
+
+```typescript
+} else if (result._tag === 'stuck') {
+  console.log(
+    `[TriggerRouter] Workflow stuck: triggerId=${trigger.id} ` +
+    `workflowId=${trigger.workflowId} reason=${result.stuckReason} ` +
+    `tool=${result.toolName ?? 'n/a'} turns=${result.turnCount}`,
+  );
+}
+```
+
+Delivery (`maybeRunDelivery`) should NOT run for stuck results -- there is no successful output to commit.
+
+### 6. NotificationService Changes
+
+Three pure functions need new cases:
+
+```typescript
+// buildNotificationBody:
+case 'stuck':
+  return `Session aborted (stuck loop): ${truncated}`;
+
+// buildOutcome: NotificationPayload['outcome'] needs 'stuck' added
+// buildDetail:
+case 'stuck':
+  return `stuckReason: ${result.stuckReason}; tool: ${result.toolName ?? 'n/a'}; ` +
+         `turns: ${result.turnCount}; stepAdvances: ${result.stepAdvanceCount}`;
+```
+
+`NotificationPayload.outcome` currently is `'success' | 'error' | 'timeout' | 'delivery_failed'`. Add `'stuck'`.
+
+## 5-File Change Estimate
+
+| File | Change |
+|---|---|
+| `src/daemon/workflow-runner.ts` | (1) Add `WorkflowRunStuck` interface and update `WorkflowRunResult` union. (2) **CRITICAL: Also update `ChildWorkflowRunResult` type alias** -- if missed, the cast at line 2014 silently allows `_tag: 'stuck'` to reach `makeSpawnAgentTool`'s assertNever, causing a runtime crash in child sessions. (3) Add `stuckAbortPolicy` and `noProgressAbortEnabled` to `WorkflowTrigger.agentConfig`. (4) Add `sessionStartMs = Date.now()` alongside `turnCount`. (5) Wire abort + fire-and-forget outbox write in `turn_end` subscriber. (6) Add `stuckContext` closure variable + branch in catch block to return `_tag: 'stuck'`. (7) Add `stuck` case to `makeSpawnAgentTool` switch. |
+| `src/trigger/trigger-router.ts` | Add `stuck` branch in `route()` and `dispatch()` before `assertNever`; `maybeRunDelivery` already skips non-success results (no change needed). |
+| `src/trigger/notification-service.ts` | Add `stuck` case to `buildNotificationBody`, `buildOutcome`, `buildDetail`; add `'stuck'` to `NotificationPayload.outcome`. |
+| `src/trigger/types.ts` | Add `stuckAbortPolicy?: 'abort' | 'notify_only'` and `noProgressAbortEnabled?: boolean` to `TriggerDefinition.agentConfig`. |
+| `src/daemon/daemon-events.ts` | No changes required -- `AgentStuckEvent` already exists and fires. |
+
+**Total: 4 files changed** (`daemon-events.ts` is unchanged). `workflow-runner.ts` has multiple edit locations -- all must be done in a single commit to avoid TypeScript exhaustiveness errors at intermediate states.
+
+## Decision Log
+
+- **`full_spectrum` path chosen** because both the integration point (landscape) and the result type design (concept) are genuine risks.
+- **New `_tag: 'stuck'` variant** preferred over reusing `WorkflowRunTimeout` because stuck abort fires _before_ the wall clock -- conflating them loses diagnostic precision.
+- **Outbox write in `turn_end` subscriber** (not in `TriggerRouter`) because the outbox entry is diagnostic context for the abort, not post-hoc delivery.
+- **`stuckAbortPolicy` in `agentConfig`** (not a top-level `TriggerDefinition` field) because it belongs with `maxSessionMinutes` and `maxTurns` -- all are session-behavior knobs, not trigger-routing knobs.
+- **`timeout_imminent` does not get a new abort** -- the wall-clock timer already calls `agent.abort()` independently; adding a second abort would be redundant and could race.
+- **Default `stuckAbortPolicy: 'abort'`** for all triggers. Overnight-autonomous is the primary use case. Human-supervised users who want softer behavior must opt in to `'notify_only'`.
+- **`noProgressAbortEnabled: false` default** -- `no_progress` has a real false-positive rate on deep-research sessions. Separating the gate from `stuckAbortPolicy` allows independent control: a trigger can have `stuckAbortPolicy: 'abort'` (abort on `repeated_tool_call`) without also aborting on `no_progress`.
+- **`issueSummaries` field borrowed from Candidate C** -- the `issueSummaries` array is already tracked in session closures at zero additional collection cost. Adding it to `WorkflowRunStuck` now avoids a future breaking interface change when a fix-coordinator needs it.
+- **outbox is best-effort** (fire-and-forget, errors swallowed) -- consistent with the `DaemonEventEmitter` contract. A failed write must never affect the `WorkflowRunResult`.
+- **`sessionStartMs = Date.now()`** must be added before the agent loop -- it does not currently exist in workflow-runner.ts. Trivial one-line addition.
+- **Candidate A rejected** -- adding `reason: 'stuck_loop'` to `WorkflowRunTimeout` conflates stuck-abort with wall-clock timeout, violating 'make illegal states unrepresentable'. The 5-file vs. 2-file maintenance advantage does not justify this semantic violation.
+- **Candidate C deferred** -- `issue_reported severity=fatal` abort is the correct Phase 2 extension once `repeated_tool_call` abort is validated in production. The `issueSummaries` field on `WorkflowRunStuck` provides partial Candidate C value at near-zero cost.
+
+## Residual Concerns
+
+1. **`repeated_tool_call` false-positive rate in production is unvalidated.** The `stuckAbortPolicy: 'notify_only'` escape hatch mitigates. If false-positive rate exceeds ~20%, consider flipping the default to `'notify_only'` and making `'abort'` opt-in.
+
+2. **Outbox write may be lost on rapid daemon shutdown.** The fire-and-forget write initiates before `runWorkflow()` returns, but completes asynchronously. On SIGKILL, the entry may be lost. Same risk as `DaemonEventEmitter` -- accepted by design.
+
+3. **No shadow-mode validation.** Ideally, heuristics would run in shadow mode (emit only) for 20+ production sessions before enabling abort. `stuckAbortPolicy: 'notify_only'` serves as a manual shadow mode.
+
+## Final Summary
+
+The design adds `WorkflowRunStuck` as a new `WorkflowRunResult` variant (`_tag: 'stuck'`), wires abort into the `repeated_tool_call` heuristic (unconditional, subject to `stuckAbortPolicy`) and optionally into `no_progress` (gated by `noProgressAbortEnabled: true`) in the `turn_end` subscriber, writes a structured outbox entry on abort, and extends `NotificationService` to distinguish stuck from timeout. The result carries `issueSummaries` for coordinator context. The policy is per-trigger via `agentConfig.stuckAbortPolicy` and `agentConfig.noProgressAbortEnabled`. The change touches 4 files and follows all existing patterns (fire-and-forget outbox, best-effort notification, `assertNever` exhaustiveness, max_turns abort template). A future fix-coordinator can read the outbox entry and extract all fields needed to classify and potentially retry the stuck session without parsing log text.
+
+**Critical implementation note:** `ChildWorkflowRunResult` must be updated in the same commit as `WorkflowRunResult`. Failure to do so causes a runtime `assertNever` crash in child sessions spawned by `makeSpawnAgentTool`.