@exaudeus/workrail 3.35.1 → 3.37.0

package/docs/design/notification-design-candidates.md

@@ -0,0 +1,131 @@
+# WorkTrain User Notifications: Design Candidates
+
+Raw investigative material for the main implementation agent. Honest analysis over polished presentation.
+
+---
+
+## Problem Understanding
+
+**What is being asked:** fire user-facing notifications (macOS native, generic webhook) when the WorkTrain daemon completes a session or encounters a problem. Config via `~/.workrail/config.json`.
+
+**Tensions:**
+
+1. **Fire-and-forget vs. correctness guarantee** -- notifications involve async I/O (osascript subprocess, HTTP POST). They must never delay semaphore release, affect the workflow result, or propagate errors upward. Solution: `notify()` is void/sync, async work is detached in a void Promise that unconditionally swallows all errors (DaemonEventEmitter model).
+
+2. **Global config vs. per-trigger config** -- the simplest and most consistent design is global config (`~/.workrail/config.json`). Per-trigger config is additive later. Per YAGNI: global-only for MVP.
+
+3. **Child session isolation** -- `spawn_agent` calls `runWorkflow()` directly for child sessions. If notifications fire from inside `runWorkflow()`, sub-agent completions notify the user. The correct seam is at the top-level dispatch boundary (TriggerRouter), not inside the workflow executor.
+
+4. **Platform detection** -- osascript is macOS-only. If `WORKTRAIN_NOTIFY_MACOS=true` on Linux, the call fails silently (or logs a warning). Runtime `process.platform === 'darwin'` guard required.
+
+**Likely seam:** `TriggerRouter.route()` and `TriggerRouter.dispatch()` -- after `runWorkflowFn()` returns. This is the only call site that: (a) has a complete `WorkflowRunResult`, (b) is called only for root-level sessions, (c) already has the pattern for injected optional behaviors.
+
+**What makes this hard:** The child session problem. A junior developer would add notifications inside `runWorkflow()` and flood the user with sub-agent notifications. The correct boundary is `TriggerRouter` because it is the external dispatch surface.
+
+---
+
+## Philosophy Constraints
+
+From `CLAUDE.md` and repo patterns:
+
+- **Errors-as-data:** `notify()` swallows all async errors internally (never returns a Result -- it is observability, not delivery). The webhook channel can log the error; it must not propagate.
+- **DI for I/O boundaries:** `execFileFn` (for osascript) and `fetchFn` (for webhook HTTP) are injected constructor parameters, allowing test fakes without mocking child_process or global fetch.
+- **Immutability by default:** `NotificationService` is immutable after construction. Config is a plain readonly struct passed to the constructor.
+- **YAGNI:** No retry logic, no per-trigger config, no Slack/email integrations.
+- **Single-responsibility:** TriggerRouter dispatches; NotificationService notifies. Not mixed.
+
+**Conflicts:** None. CLAUDE.md and repo patterns align.
+
+---
+
+## Impact Surface
+
+Files that must remain consistent after this change:
+
+- `src/trigger/trigger-router.ts` -- gains one optional constructor param (`notificationService?`)
+- `src/trigger/trigger-listener.ts` -- constructs `NotificationService` from config and injects
+- `src/config/config-file.ts` -- gains 2 new allowed keys: `WORKTRAIN_NOTIFY_MACOS`, `WORKTRAIN_NOTIFY_WEBHOOK`
+- `src/trigger/__tests__/trigger-router.test.ts` -- existing tests should be unaffected (new param is optional); new tests verify notify() is called with correct args
+
+No breaking changes to public types or existing behavior.
+
+---
+
+## Candidates
+
+### Candidate 1: Inline notification in TriggerRouter
+
+**Summary:** Add `notifyMacOs: boolean` and `notifyWebhookUrl: string | undefined` constructor params to TriggerRouter. After `runWorkflowFn()` returns in `route()` and `dispatch()`, call `execFile('osascript', [...])` and/or `fetch(webhookUrl, {...})` inline. Errors caught and swallowed.
+
+- **Tensions resolved:** fire-and-forget (detached void Promise), child isolation (TriggerRouter boundary). Accepts: single-responsibility violation.
+- **Boundary:** TriggerRouter -- correct for child isolation.
+- **Failure mode:** TriggerRouter test suite must mock execFile and fetch; future channels (Slack, Linux) bloat the class.
+- **Repo pattern:** departs from optional-injection pattern (emitter, execFn are injected services, not bare params).
+- **Gains:** smallest diff, no new files.
+- **Losses:** testability burden, extensibility, single-responsibility.
+- **Scope:** too narrow -- makes future channels harder.
+- **Philosophy:** violates DI (no injection seam for osascript/fetch in tests), single-responsibility.
+
+---
+
+### Candidate 2: New NotificationService class (recommended)
+
+**Summary:** `NotificationService` class in `src/trigger/notification-service.ts`. Constructor: `{ macOs: boolean, webhookUrl?: string, execFileFn?: ExecFileFn, fetchFn?: FetchFn }`. Method: `notify(result: WorkflowRunResult, goal: string): void` -- fire-and-forget. TriggerRouter gets optional `notificationService?: NotificationService` constructor param. `trigger-listener.ts` constructs it from config. Tests inject fakes.
+
+- **Tensions resolved:** all 4. Fire-and-forget via detached void Promise. Child isolation via TriggerRouter boundary. DI for testability. Platform detection inside `notify()`.
+- **Boundary:** NotificationService owns notification; TriggerRouter owns routing. Clean split.
+- **Why this boundary is best fit:** mirrors `DaemonEventEmitter` exactly -- same optional-injection, same fire-and-forget contract, same "observability must never affect correctness" invariant.
+- **Failure mode:** if the void Promise is not truly detached (e.g., `await notify()` accidentally holds the semaphore). Must verify the pattern. Low risk given DaemonEventEmitter precedent.
+- **Repo pattern:** directly follows `DaemonEventEmitter` (daemon-events.ts) and `execFn` injection (trigger-router.ts, delivery-client.ts).
+- **Gains:** clean seam, testable with fakes, extensible (future channels are additive), follows all repo conventions.
+- **Losses:** one new file (negligible).
+- **Scope:** best-fit.
+- **Philosophy:** honors DI, errors-as-data, immutability, single-responsibility, YAGNI. No conflicts.
+
+---
+
+### Candidate 3: DaemonEventEmitter subscriber (rejected)
+
+**Summary:** Add subscriber pattern to `DaemonEventEmitter`. On `session_completed` events, a `NotificationService` listener fires notifications.
+
+- **Critical failure:** `session_completed` fires for all `runWorkflow()` calls including child sessions spawned by `spawn_agent`. Violates child isolation invariant -- users get flooded with sub-agent notifications.
+- **Additional problem:** `DaemonEventEmitter` is an append-only JSONL logger, not a pub/sub bus. Adding subscriber semantics is a disproportionate architectural change.
+- **Scope:** too broad.
+- **Rejected.**
+
+---
+
+## Comparison and Recommendation
+
+| Tension | Candidate 1 | Candidate 2 | Candidate 3 |
+|---|---|---|---|
+| Fire-and-forget | resolved | resolved | resolved |
+| Child session isolation | resolved | resolved | **violated** |
+| Testability | weak | strong | n/a |
+| Extensibility | poor | good | n/a |
+| Repo pattern fit | departs | follows | departs |
+
+**Recommendation: Candidate 2 (NotificationService).**
+
+Reasons: follows the exact DaemonEventEmitter optional-injection precedent, clean single-responsibility boundary, strong testability via injected fakes, extensible for future channels without touching TriggerRouter. Cost is one small new file.
+
+---
+
+## Self-Critique
+
+**Strongest counter-argument against Candidate 2:** Candidate 1 is a smaller diff with no new files. If notifications are low-priority and never extended, NotificationService is over-engineered. YAGNI could justify inline.
+
+**Why Candidate 1 still loses:** The testability argument is concrete and immediate. TriggerRouter already has complex semaphore/delivery/autoCommit logic. Adding osascript/fetch inline makes the test suite harder now. NotificationService is one small file -- the cost is negligible.
+
+**Broader option that might be justified:** A `NotificationBus` with channel registration and routing (like an EventEmitter). Only justified if multiple channels need independent retry, priority, or filtering. No evidence of that in the backlog.
+
+**Invalidating assumption:** If console-dispatched sessions (via `dispatch()`) should NOT notify the user (because they are interactive). Currently both `route()` and `dispatch()` are treated the same. If this is wrong, `notify()` gains a `source?: 'webhook' | 'console'` parameter and gates on it.
+
+---
+
+## Open Questions for the Main Agent
+
+1. Should `dispatch()` (console-initiated) fire notifications the same as `route()` (webhook/poll)? Current assumption: yes -- both are daemon-executed sessions the user cannot directly observe.
+2. What message format for the macOS notification? Suggested: title = "WorkTrain", subtitle = workflowId, body = human-readable outcome + goal snippet.
+3. What JSON payload for the webhook POST? Suggested: `{ event: "session_completed", workflowId, outcome: "success"|"error"|"timeout"|"delivery_failed", detail: string, goal: string, timestamp: ISO8601 }`.
+4. Should `delivery_failed` generate a distinct notification message vs. plain `error`? Suggested: yes -- "session succeeded but result delivery failed" is a different user action than "session failed".

package/docs/design/notification-design-review.md

@@ -0,0 +1,84 @@
+# WorkTrain Notifications: Design Review Findings
+
+Concise findings for the implementation agent.
+
+---
+
+## Tradeoff Review
+
+All accepted tradeoffs are sound under realistic conditions:
+
+- **Global-only config** -- acceptable for single-user local daemon. Additive per-trigger config is possible without touching NotificationService.
+- **No retry on webhook** -- best-effort delivery matches DaemonEventEmitter contract. Acceptable.
+- **No Linux/Windows** -- webhook is the universal channel. Linux `notify-send` is additive.
+- **Fire-and-forget errors swallowed** -- `console.warn` inside catch provides minimal observability. Correct for observability infrastructure.
+
+---
+
+## Failure Mode Review
+
+All failure modes covered:
+
+| Failure mode | Mitigation | Risk |
+|---|---|---|
+| osascript stall | execFile `timeout: 5000` + SIGKILL | Low |
+| Webhook unreachable | AbortController 30s + catch/warn/swallow | Low |
+| Webhook non-2xx | res.ok check + warn + swallow | Low |
+| Invalid webhook URL | URL.canParse at construction, warn + treat as absent | Low |
+| macOS permission denied | osascript exits non-zero, caught and swallowed | Low |
+| Future accidental await | notify() returns void (not Promise<void>) -- TypeScript rejects await | None |
+
+No high-risk failure modes.
+
+---
+
+## Runner-Up / Simpler Alternative Review
+
+- **Runner-up (inline in TriggerRouter):** no strengths worth borrowing. Loses on testability and single-responsibility.
+- **Simpler (module-level function instead of class):** viable but class matches DaemonEventEmitter precedent, enables constructor-time URL validation, and makes injection cleaner in tests.
+- **Hybrid:** none warranted. Selected approach already is the pattern-following hybrid.
+
+---
+
+## Philosophy Alignment
+
+All CLAUDE.md principles satisfied:
+
+- DI for I/O boundaries: execFileFn and fetchFn injected
+- Immutability: NotificationService immutable post-construction
+- Errors are data: async errors logged, discarded at boundary
+- YAGNI: MVP scope only
+
+Minor tensions (acceptable):
+- macOS-on-Linux: runtime guard (`process.platform === 'darwin'`) rather than type-level. Acceptable for config flags.
+
+---
+
+## Findings
+
+**No Red or Orange findings.** Design is implementation-ready.
+
+**Yellow (informational):**
+
+- Y1: `notify()` should return `void` (not `Promise<void>`) to make the fire-and-forget contract type-enforced. Async work is detached via `void this._doNotify(...).catch(...)` inside a sync method -- exactly as DaemonEventEmitter does.
+- Y2: osascript execFile call should use `timeout: 5000` option (ms). Do not use the shell timeout command -- execFile handles this natively.
+- Y3: The `delivery_failed` outcome notification message should distinguish 'session completed, result delivery failed' from 'session failed'. Both are error states but from the user's perspective they are different actions.
+- Y4: Config-load warning: if `WORKTRAIN_NOTIFY_MACOS=true` but `process.platform !== 'darwin'`, log one `console.warn` at construction time (not on every notify() call).
+
+---
+
+## Recommended Revisions
+
+None to the architecture. Implement as designed:
+
+1. `src/trigger/notification-service.ts` -- NotificationService class, void notify(), macOS + webhook channels
+2. `src/trigger/trigger-router.ts` -- add optional `notificationService?` constructor param; call `notificationService?.notify(result, trigger.goal)` in route() after runWorkflowFn() and `notificationService?.notify(result, workflowTrigger.goal)` in dispatch() after runWorkflowFn()
+3. `src/config/config-file.ts` -- add WORKTRAIN_NOTIFY_MACOS and WORKTRAIN_NOTIFY_WEBHOOK to ALLOWED_CONFIG_FILE_KEYS
+4. `src/trigger/trigger-listener.ts` -- read the two config values, construct NotificationService if either is set, inject into TriggerRouter
+5. `src/trigger/__tests__/notification-service.test.ts` -- unit tests with injected fakes
+
+---
+
+## Residual Concerns
+
+None material. Design is sound and implementation-ready.

package/docs/design/notification-implementation-plan.md

@@ -0,0 +1,181 @@
+# WorkTrain Notifications: Implementation Plan
+
+---
+
+## 1. Problem Statement
+
+WorkTrain daemon silently starts and finishes sessions. Unless the user watches the console or tails a log, they have no awareness that work happened. This plan implements macOS native notifications (via `osascript`) and a generic webhook channel, firing on session completion (success/error/timeout/delivery_failed). Config lives in `~/.workrail/config.json`.
+
+---
+
+## 2. Acceptance Criteria
+
+- When `WORKTRAIN_NOTIFY_MACOS=true` in `~/.workrail/config.json` and `process.platform === 'darwin'`, a macOS notification appears after every root-level session completes (success, error, timeout, or delivery_failed).
+- When `WORKTRAIN_NOTIFY_WEBHOOK=<url>` in `~/.workrail/config.json`, an HTTP POST is sent to that URL after every root-level session completes.
+- Notification fires for both webhook-triggered sessions (`route()`) and console-dispatched sessions (`dispatch()`).
+- A failed notification (osascript crash, network error) never affects the workflow result and never causes the daemon to throw.
+- Child sessions spawned via `spawn_agent` do NOT fire user notifications.
+- If both `WORKTRAIN_NOTIFY_MACOS` and `WORKTRAIN_NOTIFY_WEBHOOK` are absent or false/empty, zero overhead (no NotificationService constructed).
+- If `WORKTRAIN_NOTIFY_MACOS=true` but `process.platform !== 'darwin'`, a `console.warn` is logged once at daemon startup and notifications are skipped.
+- If `WORKTRAIN_NOTIFY_WEBHOOK` is set to a non-URL value, a `console.warn` is logged once at startup and webhook channel is disabled.
+- All new behavior is unit-testable via injected fakes (no test mocks of child_process or global fetch needed).
+
+---
+
+## 3. Non-goals
+
+- Linux/Windows OS notifications (`notify-send`, PowerShell toast)
+- Slack/Discord/Teams/email first-class channel integrations
+- Mobile push notifications
+- Outbox.jsonl integration
+- Per-trigger notification config (global-only for MVP)
+- Retry logic for webhook delivery
+- Notification batching or debouncing
+- Child session notifications (spawn_agent sub-tasks)
+
+---
+
+## 4. Philosophy-driven Constraints
+
+- `notify()` returns `void` (not `Promise<void>`). Async work is detached via `void this._doNotify(...).catch(() => {})`. TypeScript rejects `await` on void -- fire-and-forget is type-enforced.
+- `execFileFn` (for osascript) and `fetchFn` (for HTTP POST) are injected constructor parameters. Tests use fakes, never mock child_process or global fetch.
+- `NotificationService` is immutable after construction. All config is resolved in the constructor.
+- All async errors are swallowed unconditionally inside NotificationService. Logging via `console.warn` is the only observability.
+- macOS platform check and webhook URL validation happen at construction time (validate at boundaries, trust inside).
+
+---
+
+## 5. Invariants
+
+1. `notify()` never throws, never propagates errors, never affects `WorkflowRunResult`.
+2. `notify()` fires only from `TriggerRouter` (not inside `runWorkflow()` or `spawn_agent` child sessions).
+3. osascript is invoked via `execFile` (never `exec`). No shell injection risk.
+4. Webhook is a global config channel, not per-trigger.
+5. All 4 `WorkflowRunResult._tag` variants (`success`, `error`, `timeout`, `delivery_failed`) are notifiable.
+6. `delivery_failed` notification message body is distinct: "session completed but result delivery failed".
+
+---
+
+## 6. Selected Approach
+
+**NotificationService class** in `src/trigger/notification-service.ts`. Optional-injection into `TriggerRouter` constructor. Follows `DaemonEventEmitter` optional-injection pattern exactly.
+
+**Runner-up:** Inline in TriggerRouter. Lost on testability and single-responsibility. No strengths worth borrowing.
+
+**Rationale:** TriggerRouter is the only call site that processes root-level sessions exclusively (child sessions use `runWorkflow()` directly). NotificationService follows `DaemonEventEmitter` precedent -- same pattern, same contract, same rationale. Clean separation of concerns. Injected fakes eliminate test mocking burden.
+
+---
+
+## 7. Vertical Slices
+
+### Slice 1: NotificationService core + config keys
+
+**Scope:**
+- `src/trigger/notification-service.ts` -- new file
+- `src/config/config-file.ts` -- add 2 allowed keys
+- `src/trigger/__tests__/notification-service.test.ts` -- new test file
+
+**Done when:**
+- `NotificationService` constructor accepts `{ macOs: boolean, webhookUrl?: string, execFileFn?: ExecFileFn, fetchFn?: FetchFn }`
+- `notify(result: WorkflowRunResult, goal: string): void` is implemented
+- macOS channel: calls `execFileFn('osascript', ['-e', `display notification "..." with title "WorkTrain"`], { timeout: 5000 })`
+- Webhook channel: POSTs `{ event: 'session_completed', workflowId, outcome, detail, goal, timestamp }` to webhookUrl with 30s AbortController
+- Platform guard: if macOs=true and platform !== darwin, logs warn at construction and skips osascript
+- URL validation: if webhookUrl is provided but not a valid URL, logs warn at construction and disables webhook channel
+- Unit tests cover: success fires both channels; error/timeout/delivery_failed each fire; macOS-on-linux is guarded; invalid webhook URL is disabled; failed osascript does not throw; failed webhook does not throw; injected fake execFileFn receives correct args
+- `WORKTRAIN_NOTIFY_MACOS` and `WORKTRAIN_NOTIFY_WEBHOOK` are in `ALLOWED_CONFIG_FILE_KEYS`
+
+### Slice 2: TriggerRouter injection
+
+**Scope:**
+- `src/trigger/trigger-router.ts` -- add optional `notificationService?` param to constructor; call in `route()` and `dispatch()`
+
+**Done when:**
+- `TriggerRouter` constructor accepts optional `notificationService?: NotificationService` (7th param position or via an options bag -- check existing param order)
+- `route()` calls `this.notificationService?.notify(result, trigger.goal)` after `runWorkflowFn()` resolves and before `maybeRunDelivery()`
+- `dispatch()` calls `this.notificationService?.notify(result, workflowTrigger.goal)` after `runWorkflowFn()` resolves
+- Existing TriggerRouter tests are unaffected (new param is optional, defaults to undefined)
+- New test verifies notify() is called with the correct result and goal in both route() and dispatch() paths
+
+### Slice 3: trigger-listener.ts wiring
+
+**Scope:**
+- `src/trigger/trigger-listener.ts` -- read config values and inject NotificationService
+
+**Done when:**
+- After reading `~/.workrail/config.json`, `trigger-listener.ts` reads `WORKTRAIN_NOTIFY_MACOS` and `WORKTRAIN_NOTIFY_WEBHOOK`
+- If either is set, constructs `NotificationService` and injects into `TriggerRouter`
+- If neither is set, `notificationService` is undefined (no overhead)
+- Manual integration test: set `WORKTRAIN_NOTIFY_MACOS=true` in config.json, start daemon, trigger a session, verify notification appears on macOS
+
+---
+
+## 8. Test Design
+
+**Unit tests (Vitest, fakes):**
+
+`notification-service.test.ts`:
+- success result fires macOS notification with title "WorkTrain" and body containing workflowId and "completed"
+- error result fires notification with "failed" in body
+- timeout result fires notification with "timed out" in body
+- delivery_failed result fires notification with "delivery failed" in body (distinct from generic error)
+- macOS=true + platform=darwin: execFileFn called with correct args
+- macOS=true + platform=linux: execFileFn NOT called, console.warn emitted at construction
+- webhookUrl set + valid URL: fetchFn called with correct URL and JSON body
+- webhookUrl set + invalid URL: fetchFn NOT called, console.warn emitted at construction
+- execFileFn throws: notify() does not throw, error is swallowed
+- fetchFn rejects: notify() does not throw, error is swallowed
+- fetchFn returns non-2xx: notify() does not throw, console.warn emitted
+
+`trigger-router.test.ts` additions:
+- route() with notificationService: notificationService.notify() called with correct WorkflowRunResult and goal after workflow completes
+- dispatch() with notificationService: same
+- route() without notificationService: no error (undefined?.notify() is safe)
+
+**Integration test (manual):**
+- `WORKTRAIN_NOTIFY_MACOS=true` in config.json -> trigger a session -> verify macOS notification appears
+- `WORKTRAIN_NOTIFY_WEBHOOK=https://httpbin.org/post` -> trigger a session -> verify POST received
+
+---
+
+## 9. Risk Register
+
+| Risk | Likelihood | Impact | Mitigation |
+|---|---|---|---|
+| osascript stall | Low | Low | execFile timeout: 5000ms |
+| Webhook timeout | Low | Low | AbortController 30s |
+| Future accidental await on notify() | Low | Medium | notify() returns void (not Promise<void>) |
+| macOS permission denied | Medium | Low | errors swallowed, user sees nothing |
+| Wrong TriggerRouter param position | Low | Low | Check existing param order before editing |
+
+---
+
+## 10. PR Packaging Strategy
+
+**SinglePR** on branch `feat/daemon-notifications`. All 3 slices in one PR -- they are cohesive and none makes sense without the others. Slices are committed sequentially so the diff is reviewable.
+
+---
+
+## 11. Philosophy Alignment
+
+| Principle | Status | Note |
+|---|---|---|
+| DI for I/O boundaries | Satisfied | execFileFn and fetchFn injected |
+| Immutability by default | Satisfied | NotificationService immutable post-construction |
+| Errors are data | Satisfied | async errors logged then discarded at boundary |
+| Validate at boundaries | Satisfied | URL and platform validated at construction |
+| YAGNI | Satisfied | No retry, no per-trigger, no Slack |
+| Make illegal states unrepresentable | Tension | macOS-on-Linux is representable via config; mitigated by construction-time guard |
+| Single-responsibility | Satisfied | TriggerRouter routes; NotificationService notifies |
+| Prefer fakes over mocks | Satisfied | execFileFn and fetchFn are injectable fakes |
+
+---
+
+## 12. Metrics
+
+- `implementationPlan`: complete
+- `slices`: 3 (NotificationService core, TriggerRouter injection, trigger-listener wiring)
+- `estimatedPRCount`: 1
+- `unresolvedUnknownCount`: 0
+- `planConfidenceBand`: High
+- `followUpTickets`: Linux `notify-send` support, per-trigger notification config, webhook retry

package/docs/design/spawn-agent-failure-modes.md

@@ -0,0 +1,161 @@
+# spawn_agent result handling: delivery_failed bug discovery
+
+**Status:** Discovery complete. Recommendation: Candidate 2 (ChildWorkflowRunResult alias + assertNever).
+
+---
+
+## Problem Understanding
+
+### The bug
+
+`makeSpawnAgentTool` in `src/daemon/workflow-runner.ts` (lines 1572-1579) maps `delivery_failed` to `outcome: 'success'` when constructing the structured result returned to the parent LLM. The code's own comment acknowledges that `delivery_failed` is unreachable from `runWorkflow()` -- yet the branch maps it to success instead of error.
+
+### Core tensions
+
+1. **Type completeness vs. type accuracy at a boundary.** `WorkflowRunResult` includes `delivery_failed` (correct for TriggerRouter). But `runWorkflow()` itself never returns `delivery_failed` (only TriggerRouter does, post-HTTP-callback). The type is wider than the actual behavior at this call site.
+
+2. **Exhaustiveness vs. unreachability.** TypeScript requires handling all union variants. The current `else` fallthrough achieves exhaustiveness but assigns wrong behavior to the impossible case.
+
+3. **Soft failure vs. hard failure for impossible states.** Existing `delivery_failed not expected here` callsites in `console-routes.ts` and `trigger-router.ts` use soft handling (log + ignore). For spawn_agent, the outcome directly affects the parent LLM's next action -- soft handling (mapping to success) is a data integrity bug.
+
+### Where the problem lives
+
+Symptom: result-mapping block in `makeSpawnAgentTool` (`else` branch, lines 1572-1579).
+
+Architectural seam: the return type of `runWorkflow()`. It returns `WorkflowRunResult` (4 variants) but can only produce 3 (`success | error | timeout`). The `delivery_failed` variant was added in GAP-3 when TriggerRouter gained callback support, and `runWorkflow()`'s return type was widened to match -- even though `runWorkflow()` itself doesn't produce it.
+
+### What makes it hard
+
+The existing comment is correct ("delivery_failed is unreachable") but the chosen handling is wrong ("return as success"). The author conflated "the workflow work is done" (true at TriggerRouter level) with "the parent should treat this as success" (wrong at spawn_agent level, where the parent LLM acts on the outcome).
+
+---
+
+## Philosophy Constraints
+
+**Principles that apply:**
+- **Make illegal states unrepresentable** -- `delivery_failed` is architecturally impossible at this call site; the type should reflect that
+- **Exhaustiveness everywhere** -- discriminated union handling must be complete and refactor-safe
+- **Errors are data** -- impossible/unexpected states must surface as errors, not be silently mapped to success
+- **Type safety as the first line of defense** -- compile-time guarantee preferred over runtime defensive check
+- **Document "why", not "what"** -- the fix must update the WHY comment to accurately reflect the invariant
+
+**Philosophy conflict:**
+- CLAUDE.md says "exhaustiveness everywhere" but `console-routes.ts` and `trigger-router.ts` both use soft `delivery_failed not expected here` handling without assertNever. This is a gap between stated and practiced philosophy. Resolution: spawn_agent's user-visible consequence warrants the stricter approach; leave the other two callsites unchanged and document the intentional difference.
+
+---
+
+## Impact Surface
+
+- `src/daemon/workflow-runner.ts` -- primary change site (makeSpawnAgentTool result mapping + new ChildWorkflowRunResult type alias)
+- `src/trigger/trigger-router.ts` -- assigns `runWorkflow()` result to `WorkflowRunResult`; unaffected (still uses full union)
+- `src/v2/usecases/console-routes.ts` -- same; unaffected
+- `tests/unit/workflow-runner-*.test.ts` -- no changes needed to existing tests
+- New: `tests/unit/workflow-runner-spawn-agent.test.ts` -- new test file for makeSpawnAgentTool result mapping
+
+---
+
+## Candidates
+
+### Candidate 1: Minimal patch (one-line fix)
+
+**Summary:** Change `outcome: 'success'` to `outcome: 'error'` in the `delivery_failed` else branch, update the comment.
+
+**Tensions resolved:** errors-are-data (delivery_failed no longer maps to success).
+**Tensions accepted:** type lie stays; no compile-time guard; implicit else fallthrough.
+**Boundary:** runtime-only fix at the result-mapping block.
+**Failure mode:** if WorkflowRunResult gains a 5th variant, the else silently maps it to error with a confusing `deliveryError` message (TypeScript won't warn).
+**Repo pattern:** follows the soft-handling pattern from console-routes.ts and trigger-router.ts.
+**Gains:** zero blast radius; one line.
+**Loses:** compile-time exhaustiveness; type lie persists.
+**Scope:** too narrow -- leaves the architectural debt in place.
+**Philosophy:** honors "errors are data"; conflicts with "make illegal states unrepresentable" and "exhaustiveness everywhere."
+
+---
+
+### Candidate 2: ChildWorkflowRunResult alias + assertNever (recommended)
+
+**Summary:** Add `export type ChildWorkflowRunResult = WorkflowRunSuccess | WorkflowRunError | WorkflowRunTimeout`, cast `childResult` to it after the `runWorkflowFn` call, replace the `else` with `assertNever(childResult)`.
+
+**Concrete shape:**
+```typescript
+// Near WorkflowRunResult in workflow-runner.ts:
+export type ChildWorkflowRunResult = WorkflowRunSuccess | WorkflowRunError | WorkflowRunTimeout;
+// WHY: runWorkflow() never produces delivery_failed. That variant is only created by TriggerRouter
+// after an HTTP callbackUrl POST fails. Child sessions spawned by spawn_agent bypass TriggerRouter
+// and have no callbackUrl. This type makes the architectural invariant unrepresentable at compile time.
+
+// In makeSpawnAgentTool execute():
+const childResult = await runWorkflowFn(...) as ChildWorkflowRunResult;
+// WHY cast: runWorkflow() returns WorkflowRunResult for TriggerRouter compatibility, but
+// structurally only produces success/error/timeout. The cast documents this invariant;
+// assertNever below catches any future violation at compile time.
+
+if (childResult._tag === 'success') { ... }
+else if (childResult._tag === 'error') { ... }
+else if (childResult._tag === 'timeout') { ... }
+else { assertNever(childResult); } // unreachable; compiler verifies exhaustiveness
+```
+
+**Tensions resolved:** exhaustiveness (assertNever catches new variants at compile time); illegal state unrepresentable (ChildWorkflowRunResult excludes delivery_failed); errors-are-data (impossible state throws, not maps to success).
+**Tensions accepted:** the cast is a runtime assertion TypeScript can't statically verify on runWorkflow()'s body.
+**Boundary:** type-system boundary at the call site in makeSpawnAgentTool.
+**Failure mode:** if runWorkflow() is modified to produce delivery_failed, the assertNever throws at runtime instead of being caught at compile time on the function body. But the throw is loud and clear.
+**Repo pattern:** adapts the repo's discriminated union + explicit tag-matching style; assertNever is idiomatic TypeScript; departs from the soft-handling pattern in console-routes/trigger-router (justified by user-visible consequence).
+**Gains:** compile-time exhaustiveness over the 3 real variants; architectural invariant expressed in type system; future WorkflowRunResult additions caught by compiler.
+**Loses:** one additional exported type alias; the cast is a soft assertion.
+**Scope:** best-fit.
+**Philosophy:** honors "make illegal states unrepresentable," "exhaustiveness everywhere," "errors are data," "type safety as the first line of defense," "document why."
+
+---
+
+### Candidate 3: Narrow runWorkflow()'s return type
+
+**Summary:** Change `runWorkflow()`'s declared return type to `Promise<WorkflowRunSuccess | WorkflowRunError | WorkflowRunTimeout>`, introduce a `TriggerWorkflowRunResult = WorkflowRunResult` alias for TriggerRouter.
+
+**Tensions resolved:** type lie eliminated at source; TypeScript statically verifies runWorkflow() cannot produce delivery_failed; no cast needed.
+**Tensions accepted:** requires TriggerRouter to re-widen locally; higher blast radius.
+**Boundary:** runWorkflow()'s public signature.
+**Failure mode:** TriggerRouter assigns `let result: WorkflowRunResult = await runWorkflowFn(...)` then reassigns to delivery_failed later -- this still works since delivery_failed is assigned after runWorkflow() returns, not returned by it. Actually safe.
+**Repo pattern:** departure -- WorkflowRunResult is the universal type across all callers.
+**Gains:** strongest compile-time guarantee; type fully reflects runtime behavior.
+**Loses:** higher blast radius; potential for unaudited callsite breakage.
+**Scope:** too broad for this bug fix.
+**Philosophy:** most strongly honors "make illegal states unrepresentable"; conflicts with YAGNI for this scope.
+
+---
+
+## Comparison and Recommendation
+
+| Tension | C1 (patch) | C2 (alias+assertNever) | C3 (narrow runWorkflow) |
+|---|---|---|---|
+| delivery_failed -> error (not success) | Resolved | Resolved | Resolved |
+| Compile-time exhaustiveness | Not resolved | Resolved | Resolved |
+| Illegal state unrepresentable | Not resolved | Partially (cast) | Fully resolved |
+| Blast radius | Zero | Minimal | Medium |
+| Future-variant safety | Weak | Strong | Strongest |
+| Consistency with existing patterns | High | Medium | Low |
+
+**Recommendation: Candidate 2.**
+
+Candidate 2 resolves the core tension at the right boundary: it makes the architectural invariant (delivery_failed is impossible at this call site) explicit in the type system, adds compile-time exhaustiveness over the 3 real variants, and fixes the wrong outcome mapping -- all without touching runWorkflow()'s public signature or any other caller.
+
+---
+
+## Self-Critique
+
+**Strongest argument against Candidate 2:** The cast `as ChildWorkflowRunResult` is a developer pinky-promise. If runWorkflow() is modified to produce delivery_failed, the compiler won't catch it at the assignment site -- only at the assertNever branch at runtime. Candidate 3 would catch it at compile time.
+
+**Why Candidate 1 loses:** Fixes the behavior without fixing the design. The type lie persists. If WorkflowRunResult gains a 5th variant, the else silently maps it to error with a message about `deliveryError` that may not exist on the new variant -- TypeScript wouldn't warn. This replicates the same structural weakness.
+
+**What would justify Candidate 3:** Evidence that other direct callers of runWorkflow() (bypassing TriggerRouter) have the same unreachable delivery_failed problem, or that runWorkflow() is being given a callbackUrl parameter in a near-future PR.
+
+**Assumption that would invalidate Candidate 2:** If runWorkflow() itself gains direct callbackUrl support and starts producing delivery_failed, the ChildWorkflowRunResult alias becomes stale. The WHY comment makes this assumption immediately visible during that future PR's review.
+
+---
+
+## Open Questions for Main Agent
+
+1. Is there an existing `assertNever` utility in the codebase, or does it need to be added? (Check `src/utils/` or similar.)
+2. Should `ChildWorkflowRunResult` be exported (for test use) or kept module-private? Recommendation: export it -- tests need to construct values of this type.
+3. The tool description string on line 1434-1436 already lists `"success"|"error"|"timeout"` as the outcome values -- this matches the fix. No change needed there.
+4. Confirm the test file naming convention: existing files are `workflow-runner-{feature}.test.ts`. New file should be `workflow-runner-spawn-agent.test.ts`.