@exaudeus/workrail 3.43.0 → 3.45.0

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.

package/docs/design/implementation-plan-stuck-escalation.md

@@ -0,0 +1,172 @@
+# Implementation Plan: WorkTrain Stuck-Escalation
+
+*2026-04-19 | Pitch: .workrail/current-pitch.md*
+
+---
+
+## 1. Problem Statement
+
+When a WorkTrain daemon session enters a `repeated_tool_call` loop, the session
+currently burns turns until wall-clock or max-turn timeout. The result is
+`_tag: 'timeout'`, indistinguishable from a legitimate slow session. Automated
+routing is impossible without string-parsing.
+
+---
+
+## 2. Acceptance Criteria
+
+1. `WorkflowRunStuck` interface exported from `workflow-runner.ts` with fields:
+   `_tag: 'stuck'`, `workflowId`, `reason`, `message`, `stopReason`, `issueSummaries?`
+2. `WorkflowRunResult` union includes `WorkflowRunStuck`.
+3. `ChildWorkflowRunResult` union includes `WorkflowRunStuck` (SAME COMMIT as #2).
+4. `WorkflowTrigger.agentConfig` has `stuckAbortPolicy?` and `noProgressAbortEnabled?`.
+5. `TriggerDefinition.agentConfig` has the same two fields.
+6. When `repeated_tool_call` fires and `stuckAbortPolicy !== 'notify_only'`:
+   outbox entry written, `agent.abort()` called, `stuckReason = 'repeated_tool_call'`.
+7. When `notify_only` is set: outbox written, abort NOT called.
+8. When `noProgressAbortEnabled: true` and `no_progress` fires with `stuckAbortPolicy !== 'notify_only'`:
+   same abort + outbox write.
+9. Return path returns `{ _tag: 'stuck', ... }` before `timeoutReason` check.
+10. `trigger-router.ts` `route()` and `dispatch()` handle `stuck` without assertNever fallthrough.
+11. `notification-service.ts` `buildNotificationBody()` and `buildDetail()` handle `stuck`.
+12. `NotificationPayload.outcome` union includes `'stuck'`.
+13. `makeSpawnAgentTool` handles `stuck` child result, returns `outcome: 'stuck'`.
+14. All 6 test cases in `workflow-runner-stuck-escalation.test.ts` pass.
+15. `npm run build` clean. `npx vitest run` no regressions.
+
+---
+
+## 3. Non-Goals
+
+- No `onStuck:` hook in TriggerDefinition (follow-up)
+- No console live panel stuck indicator
+- No `worktrain logs` formatting changes
+- No automatic retry on stuck
+- No Signal 5 (wall-clock at 80%) wiring
+- No new heuristics beyond Signal 1 and 2
+- No changes to `src/mcp/`
+- No `trigger-store.ts` parser changes
+
+---
+
+## 4. Philosophy-Driven Constraints
+
+- All new fields `readonly`
+- `issueSummaries` spread to new readonly array when included in return value
+- `writeStuckOutboxEntry` is fire-and-forget (void + catch)
+- `stuckReason` flag: first-writer-wins (same as `timeoutReason`)
+- Outbox write and abort are independent effects (write before abort gate check)
+
+---
+
+## 5. Invariants
+
+- **I1**: `ChildWorkflowRunResult` and `WorkflowRunResult` updates ship in the same commit.
+- **I2**: `stuckReason` is checked BEFORE `timeoutReason` in the return path.
+- **I3**: Outbox write fires regardless of `stuckAbortPolicy`.
+- **I4**: `no_progress` never aborts unless `noProgressAbortEnabled: true`.
+- **I5**: `repeated_tool_call` abort fires on the same turn as detection.
+- **I6**: First writer wins on `stuckReason` (guard: `stuckReason === null && timeoutReason === null`).
+
+---
+
+## 6. Selected Approach
+
+New `_tag: 'stuck'` discriminated union variant. Wire abort in `turn_end` subscriber
+after Signal 1 and Signal 2 emitter calls. Return stuck result before `timeoutReason`
+check. Update both union types atomically. Add `writeStuckOutboxEntry` module-level
+helper. Propagate to trigger-router, notification-service, makeSpawnAgentTool.
+
+**Runner-up rejected**: Extend `WorkflowRunTimeout.reason` -- violates make-illegal-states-unrepresentable.
+
+---
+
+## 7. Vertical Slices
+
+### Slice 1: Core types (workflow-runner.ts)
+- Add `WorkflowRunStuck` interface after `WorkflowRunTimeout`
+- Add to `WorkflowRunResult` union
+- Add to `ChildWorkflowRunResult` union (ATOMIC with above)
+- Add `stuckAbortPolicy?` and `noProgressAbortEnabled?` to `WorkflowTrigger.agentConfig`
+- **Done when**: `npm run build` clean after this slice
+
+### Slice 2: TriggerDefinition.agentConfig (types.ts)
+- Add `stuckAbortPolicy?` and `noProgressAbortEnabled?` after `maxTurns`
+- **Done when**: `npm run build` clean
+
+### Slice 3: Runtime wiring (workflow-runner.ts)
+- Add `sessionStartMs` constant after `maxTurns` resolution
+- Add `stuckReason` flag after `timeoutReason` flag
+- Add `writeStuckOutboxEntry` module-level helper
+- Wire abort after Signal 1 emitter call in `turn_end`
+- Wire abort after Signal 2 emitter call in `turn_end`
+- Add stuck return path before `timeoutReason` check
+- Update `makeSpawnAgentTool` resultObj type + add `stuck` arm before `assertNever`
+- **Done when**: `npm run build` clean
+
+### Slice 4: Caller propagation (trigger-router.ts, notification-service.ts)
+- Add `stuck` arm in `route()` exhaustive chain
+- Add `stuck` arm in `dispatch()` exhaustive chain
+- Add `'stuck'` to `NotificationPayload.outcome` union
+- Add `stuck` case in `buildNotificationBody()`
+- Add `stuck` case in `buildDetail()`
+- **Done when**: `npm run build` clean
+
+### Slice 5: Tests
+- Write `tests/unit/workflow-runner-stuck-escalation.test.ts` with 6 test cases
+- **Done when**: all 6 tests pass, no regressions
+
+---
+
+## 8. Test Design
+
+File: `tests/unit/workflow-runner-stuck-escalation.test.ts`
+
+Pattern: replicate turn_end subscriber logic (same as workflow-runner-stuck-detection.test.ts).
+
+**Test 1**: `stuckAbortPolicy: 'abort'` default -- repeated_tool_call fires, stuckReason set, abort called, would return _tag:'stuck'
+**Test 2**: `stuckAbortPolicy: 'notify_only'` -- abort NOT called, emitter still fires
+**Test 3**: `noProgressAbortEnabled: false` default -- no_progress does NOT set stuckReason
+**Test 4**: `noProgressAbortEnabled: true` -- no_progress sets stuckReason = 'no_progress', abort called
+**Test 5**: Compile-time assignability test: `WorkflowRunStuck` is assignable to `ChildWorkflowRunResult`
+**Test 6**: trigger-router exhaustive switch handles 'stuck' (import trigger-router, verify no assertNever path hit)
+
+---
+
+## 9. Risk Register
+
+| Risk | Likelihood | Severity | Mitigation |
+|------|------------|----------|------------|
+| ChildWorkflowRunResult not updated atomically | Low | High | Single-PR, Slice 1 includes both updates, Test 5 catches gap |
+| NotificationPayload.outcome union gap | Low | Medium | Slice 4 adds 'stuck'; build catches it |
+| stuckReason/timeoutReason race | Low | Low | Guard condition (both null check) |
+| writeStuckOutboxEntry silent failure | Low | Low | Fire-and-forget with console.warn |
+
+---
+
+## 10. PR Packaging Strategy
+
+Single PR: `feat/stuck-escalation`
+Single atomic commit with all 4 source files + test file.
+PR title: `feat(daemon): WorkflowRunStuck result variant with abort and outbox notification`
+
+---
+
+## 11. Philosophy Alignment Per Slice
+
+| Slice | Principle | Status |
+|-------|-----------|--------|
+| Slice 1 (types) | Make illegal states unrepresentable | Satisfied |
+| Slice 1 (types) | Exhaustiveness everywhere | Satisfied |
+| Slice 1 (types) | Type safety as first line of defense | Satisfied (ChildWorkflowRunResult updated) |
+| Slice 3 (runtime) | Errors are data | Satisfied |
+| Slice 3 (runtime) | Determinism over cleverness | Satisfied (simple flag) |
+| Slice 3 (runtime) | Fire-and-forget side effects | Satisfied (outbox write) |
+| Slice 4 (callers) | Exhaustiveness everywhere | Satisfied (all assertNever guards updated) |
+| Slice 5 (tests) | Prefer fakes over mocks | Satisfied (replicate subscriber logic, not vi.mock) |
+
+---
+
+**unresolvedUnknownCount**: 0
+**planConfidenceBand**: High
+**estimatedPRCount**: 1

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@exaudeus/workrail",
-  "version": "3.43.0",
+  "version": "3.45.0",
   "description": "Step-by-step workflow enforcement for AI agents via MCP",
   "license": "MIT",
   "repository": {