@exaudeus/workrail 3.59.2 → 3.59.4

package/docs/design/coordinator-in-process-await-candidates.md

@@ -0,0 +1,128 @@
+# Design Candidates: In-Process awaitSessions and getAgentResult
+
+**Date:** 2026-04-19
+**Task:** Replace HTTP-to-self `awaitSessions` and `getAgentResult` in `src/trigger/trigger-listener.ts` with in-process `ConsoleService` calls.
+
+---
+
+## Problem Understanding
+
+### Tensions
+
+1. **Construction order vs. dependency injection**: `coordinatorDeps` must be constructed before `TriggerRouter` (it is a constructor argument), but `ConsoleService` needs to be available inside the closure. The `routerRef` forward-reference pattern already solves a similar ordering problem -- `consoleService` can be constructed before the closure and captured by the closure.
+
+2. **Graceful degradation vs. correctness**: If `ctx.v2.dataDir` or `ctx.v2.directoryListing` is null (the daemon-console.ts path guards against this), should `awaitSessions` degrade to returning all-failed or crash? The design doc says construct before `coordinatorDeps` -- the guard should produce a logged warning and graceful fallback since the coordinator handles `allSucceeded: false`.
+
+3. **Session visibility race**: Sessions created in-process by `spawnSession()` may not be immediately readable via `getSessionDetail()`. This is why `SESSION_LOAD_FAILED` must be treated as "not ready yet" (retry), not as failure.
+
+4. **Interface cleanliness vs. minimal scope**: `CoordinatorDeps.port` is a required field (`readonly port: number`) that is never read by coordinator logic (`grep deps.port` returns nothing). Removing `port: DAEMON_CONSOLE_PORT` from the trigger-listener deps object requires either (a) making `port` optional in the interface, or (b) using a `0` sentinel.
+
+### Likely Seam
+
+The composition root `startTriggerListener()` in `src/trigger/trigger-listener.ts` is the correct and only seam. This is where all other deps are wired, `ctx.v2.*` ports are available, and `ConsoleService` can be constructed.
+
+### What Makes This Hard
+
+- `CoordinatorDeps.port` is required but unused by coordinator logic. The design doc says to remove it, but the interface requires it. TypeScript will reject omitting a required field.
+- The `error` terminal status mentioned in the task description does not exist in `ConsoleRunStatus` (`'in_progress' | 'complete' | 'complete_with_gaps' | 'blocked'`). The design doc is authoritative.
+- The dynamic import pattern is required to avoid circular dependency (same as `daemon-console.ts:113`).
+
+---
+
+## Philosophy Constraints
+
+From `/Users/etienneb/CLAUDE.md`:
+- **Architectural fixes over patches** -- this fix IS the architectural fix (in-process instead of HTTP)
+- **Immutability by default** -- `pending Set` mutation is minimal and contained in the polling loop
+- **Errors are data** -- use `.isOk()` / `.isErr()` on `ResultAsync`, not try/catch
+- **Validate at boundaries, trust inside** -- guard `ctx.v2.dataDir` at construction time
+- **Document "why", not "what"** -- add WHY comments on new implementations
+
+No philosophy conflicts with repo patterns -- `daemon-console.ts` already uses the exact same construction approach.
+
+---
+
+## Impact Surface
+
+- **`AdaptiveCoordinatorDeps` interface**: No change (extends `CoordinatorDeps`, no new fields needed)
+- **`CoordinatorDeps` interface** (`src/coordinators/pr-review.ts:210`): `port` is `required number` -- must be made optional if removing from trigger-listener deps
+- **CLI path** (`src/cli-worktrain.ts:1549`): sets `port` in deps object for out-of-process coordinator -- remains correct either way
+- **Pipeline coordinators** (`full-pipeline.ts`, `implement.ts`, `pr-review.ts`): call `awaitSessions`/`getAgentResult` by interface -- behavior change is transparent
+- **`src/mcp/`**: Not touched (explicit out-of-scope)
+
+---
+
+## Candidates
+
+### Candidate A: Design doc implementation with `port` made optional
+
+**Summary**: Implement exactly per design doc. Construct `ConsoleService` locally in `startTriggerListener()`. Replace `awaitSessions` and `getAgentResult` with in-process calls. Make `readonly port: number` optional (`readonly port?: number`) in `CoordinatorDeps` to allow removing it from the trigger-listener deps object.
+
+**Tensions resolved**: All four tensions resolved cleanly. `SESSION_LOAD_FAILED` = retry. Guard for `ctx.v2` nulls. `port` field made honest (optional, unused by logic).
+
+**Tension accepted**: Requires touching `src/coordinators/pr-review.ts` for one-char interface change.
+
+**Boundary**: `startTriggerListener()` composition root -- correct seam.
+
+**Why best fit**: Fully executes design doc intent. `deps.port` confirmed unused by all coordinator logic.
+
+**Failure mode**: None identified. `grep deps.port` confirmed zero usages in coordinator logic.
+
+**Repo pattern**: Follows `daemon-console.ts` construction pattern exactly. Follows `spawnSession` in-process migration pattern.
+
+**Gains**: Clean interface, no dead required field, full design doc compliance, no `0` sentinel.
+
+**Losses**: Touches `src/coordinators/pr-review.ts` (one-char change).
+
+**Scope judgment**: Best-fit. The scope restriction says "do not touch `src/mcp/`" not "do not touch `src/coordinators/`".
+
+**Philosophy fit**: Honors "architectural fixes over patches", "make illegal states unrepresentable" (no sentinel), "errors are data".
+
+---
+
+### Candidate B: Design doc implementation, keep `port: 0` sentinel
+
+**Summary**: Same `ConsoleService` construction and awaitSessions/getAgentResult replacement, but set `port: 0` in the trigger-listener deps object instead of making the interface field optional.
+
+**Tensions resolved**: Removes HTTP-to-self bugs. Zero interface changes.
+
+**Tension accepted**: Leaves dead required field with a misleading `0` value.
+
+**Failure mode**: Future code reads `deps.port` and uses `0` as a real port, producing silent bugs.
+
+**Repo pattern**: Departs from design doc intent ("remove the constant and port from coordinatorDeps").
+
+**Gains**: No interface touch; purely local change.
+
+**Losses**: Interface stays polluted with unused required field; violates design doc intent; `0` sentinel is an illegal state that can be constructed.
+
+**Scope judgment**: Too narrow (doesn't fully execute design doc intent).
+
+**Philosophy fit**: Conflicts with "make illegal states unrepresentable" and "architectural fixes over patches".
+
+---
+
+## Comparison and Recommendation
+
+**Recommendation: Candidate A.**
+
+`deps.port` is confirmed unused by any coordinator logic (exhaustive grep). Making it optional is a one-character change that eliminates a dead field and fully executes the design doc intent. The scope restriction is explicitly "do not touch `src/mcp/`" -- `src/coordinators/pr-review.ts` is in scope. Candidate A is the correct architectural fix.
+
+The `0` sentinel in Candidate B is precisely the kind of "patch over architectural fix" that CLAUDE.md's philosophy warns against.
+
+---
+
+## Self-Critique
+
+**Strongest argument against Candidate A**: A conservative interpretation of "only touch trigger-listener.ts" would favor the sentinel. If the reviewer intended zero interface changes, Candidate B is the safe choice.
+
+**Pivot condition**: If touching `pr-review.ts` causes unexpected test failures (e.g., tests construct `CoordinatorDeps` with `port` required and would need to add `port: undefined`), fall back to `port: 0` sentinel or make it optional with a default. But since `port` is already unused, this risk is low.
+
+**Assumption that would invalidate**: If some test or code path actually reads `deps.port` and would break if `0` is used or the field is absent. The grep confirms this does not exist.
+
+---
+
+## Open Questions for Main Agent
+
+1. Should the guard for `ctx.v2.dataDir === undefined` cause a process.stderr warning only, or should it cause `startTriggerListener` to return an `err`? (Daemon-console.ts returns `err` -- but trigger-listener has already started by this point. Recommendation: warn + let `awaitSessions`/`getAgentResult` return degraded results.)
+2. Should the `consoleService` local variable be constructed inside a try/catch or guarded more defensively? (No -- the constructor is synchronous and cannot throw given valid inputs.)

package/docs/design/coordinator-in-process-await-design-review.md

@@ -0,0 +1,93 @@
+# Design Review: In-Process awaitSessions and getAgentResult
+
+**Date:** 2026-04-19
+**Candidate reviewed:** Candidate A from `coordinator-in-process-await-candidates.md`
+
+---
+
+## Tradeoff Review
+
+**Tradeoff: `port` field made optional in `CoordinatorDeps`**
+- Verified: `deps.port` is unused by all coordinator logic (grep returns zero results)
+- Condition that invalidates: TypeScript errors showing `port` required elsewhere
+- Mitigation: Run `npm run build` immediately; pivot to `port: 0` sentinel if errors appear
+- **Verdict: Acceptable**
+
+**Tradeoff: `null consoleService` fallback for missing `ctx.v2` ports**
+- Verified: `createToolContext()` always provides non-null values in production
+- Condition that invalidates: Not applicable in production path
+- Mitigation: Warn on stderr + degrade gracefully to same all-failed behavior as current HTTP failure
+- **Verdict: Acceptable**
+
+**Tradeoff: Pending-Set polling over check-all-handles-every-poll**
+- Verified: Terminal state transitions are monotonic (event log is append-only)
+- Condition that invalidates: Not possible given ConsoleRunStatus projection semantics
+- **Verdict: Correct and more efficient**
+
+---
+
+## Failure Mode Review
+
+| Failure Mode | Handled? | Risk |
+|---|---|---|
+| `ctx.v2.dataDir`/`directoryListing` null | Yes -- null guard + graceful fallback | Low |
+| Session not yet visible after spawnSession | Yes -- SESSION_LOAD_FAILED treated as retry | Low |
+| TypeScript error from port optional | Partially -- pivot to sentinel if needed | Low |
+| ConsoleService circular dependency | Yes -- dynamic import pattern | Low |
+| getSessionDetail/getNodeDetail unexpected throw | Yes -- ResultAsync + outer try/catch | Low |
+
+**Highest-risk**: TypeScript port optional change causing build failure. Pivot defined and trivial.
+
+---
+
+## Runner-Up / Simpler Alternative Review
+
+**Candidate B** (port: 0 sentinel): Nothing worth borrowing. The only advantage was zero interface changes, but it introduces a dead required field with a misleading sentinel value.
+
+**Simpler variant** (keep `port: DAEMON_CONSOLE_PORT`): Insufficient -- leaves dead code after removing the HTTP deps that needed it. Design doc explicitly lists port removal as required.
+
+**No hybrid needed.**
+
+---
+
+## Philosophy Alignment
+
+| Principle | Status |
+|---|---|
+| Architectural fixes over patches | SATISFIED -- root-cause fix, not workaround |
+| Make illegal states unrepresentable | SATISFIED -- no sentinel, optional instead |
+| Dependency injection for boundaries | SATISFIED -- ConsoleService gets ports injected |
+| Immutability by default | SATISFIED -- minimal mutable state (pending Set only) |
+| Errors are data | SATISFIED -- ResultAsync.isOk()/isErr() throughout |
+| YAGNI with discipline | SATISFIED -- no speculative abstractions |
+| Document "why", not "what" | REQUIRED -- add WHY comments in implementation |
+
+One acceptable tension: null consoleService uses nullable variable rather than Result type. Acceptable at initialization boundary (not domain logic).
+
+---
+
+## Findings
+
+**No Red (blocking) findings.**
+
+**Orange (should address before shipping):**
+- None identified.
+
+**Yellow (advisory):**
+- Y1: The `ctx.v2` null guard creates a nullable `consoleService` variable. If `ctx.v2` is ever null in production, the stderr warning may be missed. Recommend making the warning prominent: `[CRITICAL trigger-listener:reason=consoleService_unavailable]` prefix.
+
+---
+
+## Recommended Revisions
+
+1. Add `[CRITICAL]` prefix to the `ctx.v2` null guard warning to make it visible in logs.
+2. Add WHY comment on new `awaitSessions` explaining the in-process approach (mirrors the spawnSession WHY comment pattern).
+3. Add WHY comment on `ConsoleService` construction explaining it avoids the HTTP race condition.
+
+---
+
+## Residual Concerns
+
+- **None blocking.** The design is sound, the tradeoffs are acceptable, and the failure modes are covered.
+- Build verification (`npm run build`) will immediately catch any TypeScript issues from the `port` optional change.
+- The implementation is a near-direct transcription of the design doc pseudocode, reducing creative risk.

package/docs/design/coordinator-io-error-handling-candidates.md

@@ -0,0 +1,199 @@
+# Coordinator I/O Error Handling -- Design Candidates
+
+Generated: 2026-04-19
+
+## Problem Understanding
+
+### Core Tensions
+
+1. **Crash-safety vs. DI purity**: The coordinator declares "all phase failures produce
+   `PipelineOutcome { kind: 'escalated' }` -- never thrown" as a design invariant, but three
+   injected dep functions (`getAgentResult`, `postToOutbox`, `pollForPR`) are called without
+   try/catch in the mode files. Any throw from these functions crashes the coordinator silently
+   instead of returning a structured `PipelineOutcome`. The fix must enforce the invariant at
+   the right boundary.
+
+2. **Verbosity vs. DRY**: `postToOutbox` is called at 8+ critical escalation points across
+   `implement-shared.ts` and `full-pipeline.ts`. Each call site needs individual protection.
+   Inline try/catch at 8 sites is repetitive; a helper would reduce duplication but adds
+   abstraction not in the existing codebase pattern.
+
+3. **`process.stderr.write()` vs. `deps.stderr()`**: The prescribed pattern uses
+   `process.stderr.write()` in catch blocks, but the rest of the coordinator uses the injected
+   `deps.stderr()`. The tension is minor -- catch blocks represent unexpected I/O failures,
+   so using `process.stderr.write()` signals this is an emergency log path, not a normal
+   operational log.
+
+### Likely Seam
+
+The mode files are the correct seam. `implement-shared.ts`, `full-pipeline.ts`, and
+`implement.ts` are the callers of the three unsafe deps. The coordinator owns the
+escalation-first invariant -- not the injectors (`trigger-listener.ts`, `cli-worktrain.ts`).
+
+### What Makes This Hard
+
+- `postToOutbox` calls are immediately followed by `return { kind: 'escalated', ... }`. The
+  try/catch must wrap ONLY the `postToOutbox` call, not the return statement. Careful
+  placement required.
+- `pollForPR` is called in BOTH `implement.ts` (explicitly mentioned in task) AND
+  `full-pipeline.ts` line 454 (not mentioned but equally unsafe). Both must be wrapped.
+- UX gate zombie detection: `implement.ts` line 144 assigns `uxHandle` from `uxSpawnResult.value`
+  without a null/empty-string guard before passing to `awaitSessions`. This is the only session
+  handle in the coordinator without the guard -- a separate gap alongside the I/O error handling.
+
+---
+
+## Philosophy Constraints
+
+**From `CLAUDE.md`:**
+- "Errors are data -- represent failure as values (Result/Either), not exceptions as control flow"
+- "Type safety as the first line of defense"
+
+**From `adaptive-pipeline.ts` header (design invariant):**
+- "All phase failures produce PipelineOutcome { kind: 'escalated' } -- never thrown."
+- "All I/O is injected via AdaptiveCoordinatorDeps. Zero direct fs/fetch/exec imports."
+
+**Repo precedent:**
+- `archiveFile` (in `implement.ts` and `full-pipeline.ts`): try/catch inline in finally block, log-and-continue. This is the exact model for `postToOutbox`.
+- `writeFile` routing log (in `adaptive-pipeline.ts`): try/catch inline, log-and-continue.
+
+**Conflicts:** None material. The stated philosophy (errors as data) and the repo pattern (inline try/catch for non-Result deps) are consistent.
+
+---
+
+## Impact Surface
+
+- `runReviewAndVerdictCycle` is called from both `implement.ts` and `full-pipeline.ts`. Fixing
+  `getAgentResult` in `implement-shared.ts` protects both callers automatically.
+- `runAuditChain` (also in `implement-shared.ts`) calls both `getAgentResult` and `postToOutbox`
+  at multiple points.
+- `adaptive-pipeline.ts` line 362 calls `postToOutbox` in the `ESCALATE` routing case -- this is
+  OUT OF SCOPE for this task (task restricts changes to the 3 mode files).
+- No callers outside these files change signature or return type.
+
+---
+
+## Candidates
+
+### Candidate 1: Inline try/catch at each call site (prescribed pattern)
+
+**Summary:** Wrap each `getAgentResult`, `postToOutbox`, and `pollForPR` call individually in
+a try/catch block in the 3 mode files.
+
+**Tensions resolved:** Crash-safety fully addressed. Accepts: slight verbosity from 8+
+`postToOutbox` sites.
+
+**Boundary:** At the mode file call sites -- the correct boundary. The coordinator owns the
+escalation-first invariant; the mode files are where the invariant must be enforced.
+
+**Failure mode:** Missing the `pollForPR` call in `full-pipeline.ts` (not explicitly called out
+in task description but confirmed unsafe by code analysis). Must be systematic.
+
+**Repo-pattern relationship:** Follows `archiveFile` try/catch pattern exactly. Adapts
+`writeFile` routing-log pattern from `adaptive-pipeline.ts`.
+
+**Gains:** Zero risk to happy path. Locally visible -- reviewer can see exactly what is
+protected at each call site. No new abstractions.
+
+**Losses:** Mildly repetitive for `postToOutbox` sites. Functions grow slightly.
+
+**Scope:** Best-fit. The 3 files are exactly the seam.
+
+**Philosophy fit:** Honors "errors are data", "escalation-first invariant", "DI for boundaries".
+Minor: uses `process.stderr.write()` in catch blocks rather than `deps.stderr()`, consistent
+with prescribed pattern and emergency-log semantics.
+
+---
+
+### Candidate 2: Wrap at injection site (safe wrapper functions)
+
+**Summary:** Wrap `getAgentResult`, `postToOutbox`, `pollForPR` in safe adapter functions at
+the injection sites (`trigger-listener.ts`, `cli-worktrain.ts`) so the deps never throw from
+the coordinator's perspective.
+
+**Tensions resolved:** DI purity -- the mode files stay clean. Accepts: changes to 2 files
+outside the permitted scope.
+
+**Boundary:** At the injection layer. Wrong boundary for this task -- the coordinator owns the
+escalation invariant, not the injectors. Injectors wire up the real implementation; they are
+not responsible for the coordinator's recovery behavior.
+
+**Failure mode:** Wrapping at injection site catches throws but cannot return `PipelineOutcome`
+-- would need to return null or a sentinel, which the mode files then check. Adds complexity
+at both ends, solving neither fully.
+
+**Repo-pattern relationship:** Departs -- existing injected deps use Result types for
+error-returning deps; plain-promise deps are not wrapped at injection sites.
+
+**Scope:** Too broad -- reaches outside the permitted 3 files.
+
+**Verdict: Rejected.** Out of scope and wrong seam.
+
+---
+
+### Candidate 3: Private helper `safePostToOutbox(deps, msg, meta)`
+
+**Summary:** Extract a private helper that wraps `deps.postToOutbox` in try/catch, reducing
+repetition at the 8+ `postToOutbox` call sites.
+
+**Tensions resolved:** DRY for `postToOutbox`. Accepts: new abstraction not prescribed by task.
+
+**Boundary:** Same 3 mode files, plus a local helper function in `implement-shared.ts`.
+
+**Failure mode:** Helper abstraction obscures the try/catch from reviewers; may hide future
+misuse (e.g., someone using the helper for a call that SHOULD escalate on failure).
+
+**Repo-pattern relationship:** No precedent for dep-wrapper helpers in the mode files. `archiveFile`
+try/catch is inline without a helper.
+
+**Scope:** Best-fit only if `postToOutbox` had 15+ sites. At 8, YAGNI says no.
+
+**Verdict: Skipped.** Task spec gives explicit inline pattern. YAGNI applies.
+
+---
+
+## Comparison and Recommendation
+
+**Candidate 1 is the clear choice.**
+
+All three candidates converge on the same underlying mechanism (try/catch). The only real
+alternatives differ in location (injection site -- wrong boundary) or DRY abstraction (helper --
+not warranted at 8 sites). Convergence is honest here.
+
+Candidate 1:
+- Follows the prescribed pattern from the task description exactly
+- Follows the repo precedent (`archiveFile`, `writeFile` try/catch)
+- Is locally visible and reviewable
+- Carries zero happy-path risk
+- Can be applied systematically to all confirmed call sites
+
+---
+
+## Self-Critique
+
+**Strongest argument against:** The 8+ `postToOutbox` call sites produce repetitive code. If
+the count grew to 20+, a helper would be clearly warranted. At 8, the verbosity is manageable.
+
+**Narrower option that might work:** Only fix `getAgentResult` and `pollForPR` (HIGH severity),
+skip `postToOutbox` wrapping (MEDIUM severity). Would reduce scope. Loses: `postToOutbox` crash
+at escalation decision points is still a real failure mode that kills the pipeline silently.
+
+**Broader option:** Candidate 2 (wrap at injection). Would be justified only if there were a
+precedent of wrapping injected deps at the injection layer. No such precedent exists.
+
+**Invalidating assumption:** If `postToOutbox` is guaranteed never to throw in production (e.g.,
+the real impl is in-memory rather than disk-based). The audit doc confirms it uses
+`fs.promises.appendFile` -- can fail on disk full or permission error. Assumption holds.
+
+---
+
+## Open Questions for Main Agent
+
+None. The problem, solution, and scope are fully specified. Implementation is mechanical.
+
+- Confirm `pollForPR` in `full-pipeline.ts` line 454 also needs wrapping (not explicitly in
+  task description but confirmed unsafe -- include it).
+- For `postToOutbox`: the task says "log a warning and continue". Use `process.stderr.write()`
+  as prescribed, not `deps.stderr()`.
+- UX gate zombie detection in `implement.ts`: add `if (!uxHandle || uxHandle.trim() === '')` guard
+  after line 144, consistent with all 9 other session handle checks in the coordinator.

package/docs/design/coordinator-io-error-handling-design-review.md

@@ -0,0 +1,120 @@
+# Coordinator I/O Error Handling -- Design Review Findings
+
+Generated: 2026-04-19
+
+## Tradeoff Review
+
+### Verbosity (8+ `postToOutbox` inline try/catch sites)
+
+- **Verdict:** Acceptable. At 8 sites, YAGNI wins. The `archiveFile` precedent in the same files
+  shows inline try/catch is the established pattern.
+- **Break condition:** If `postToOutbox` call sites grow to 15+, extract a private helper.
+- **Hidden assumption:** `postToOutbox` call count stays roughly constant in the near term.
+
+### `deps.stderr()` vs. `process.stderr.write()` in catch blocks
+
+- **Verdict:** Use `deps.stderr()` to match the existing `archiveFile` pattern in `implement.ts`
+  and `full-pipeline.ts`. The task spec example uses `process.stderr.write()` but the actual repo
+  uses `deps.stderr()` for the identical use case. `deps.stderr()` is more consistent and testable.
+- **Break condition:** None. `deps.stderr()` is strictly better here.
+
+### `pollForPR` in `full-pipeline.ts` not in task description but included
+
+- **Verdict:** Include it. It's the same unsafe call pattern, same dep, same risk. Excluding it
+  would leave the fix incomplete.
+- **Hidden assumption:** Both `pollForPR` call sites use the same real implementation -- confirmed.
+
+---
+
+## Failure Mode Review
+
+| Mode | Handled? | Risk | Notes |
+|------|----------|------|-------|
+| Missing a call site | Mitigated | Medium | Grep check after implementation |
+| `postToOutbox` throw during escalation sequence | Yes | Low | `return` is on next line after try/catch |
+| `getAgentResult` throw with non-Error | Yes | Low | `e instanceof Error ? e.message : String(e)` |
+| `pollForPR` throw leaving `prUrl` uninitialized | Yes (with care) | Medium | Must use `let prUrl; try {...} catch -> return escalated` |
+| UX gate empty `uxHandle` zombie | Yes (after fix) | Low | Same 4-line guard as 9 other handles |
+
+**Highest-risk failure mode:** `pollForPR` catch block structure. If written incorrectly (catch
+logs but falls through), `prUrl` would be undefined and the subsequent `if (!prUrl)` check would
+catch it -- but the `prUrl` variable would need to be declared with `let` outside the try block.
+The fix requires care in the variable declaration pattern.
+
+---
+
+## Runner-Up / Simpler Alternative Review
+
+**Runner-up:** Private `safePostToOutbox` helper.
+- **Strength worth borrowing:** Standardized log message format across all `postToOutbox` sites.
+- **Adopted:** Standardize the log message format inline (consistent `[WARN coordinator] postToOutbox failed: ...` prefix across all sites).
+- **Rejected:** Full helper extraction. YAGNI at 8 sites. No precedent in repo.
+
+**Simpler alternative:** Skip `postToOutbox` wrapping (only fix `getAgentResult` and `pollForPR`).
+- **Rejected:** `postToOutbox` crashes at critical escalation points. Medium severity is still a
+  production crash path that must be fixed.
+
+---
+
+## Philosophy Alignment
+
+| Principle | Status |
+|-----------|--------|
+| Errors are data | Fully satisfied -- throws become `PipelineOutcome` values |
+| Escalation-first invariant | Enforced -- no throw-exit paths remain after fix |
+| Make illegal states unrepresentable | Satisfied -- coordinator now always returns a value |
+| DI for boundaries | Satisfied -- no new imports, changes are in mode files only |
+| Compose with small functions | Under acceptable tension -- functions grow slightly |
+| Document why not what | Needs 1-line comment per postToOutbox catch explaining non-fatal rationale |
+| YAGNI with discipline | Satisfied -- no speculative helper |
+
+---
+
+## Findings
+
+### Yellow: `pollForPR` variable declaration pattern
+
+The `let prUrl` declaration must be placed BEFORE the try/catch block (not inside it) so that
+the catch block can `return` an escalated outcome and the variable remains in scope after. If
+the variable is declared inside `try`, TypeScript will not compile. This is a known TypeScript
+pattern but worth flagging explicitly.
+
+**Fix:** Use the explicit two-step pattern from the task spec:
+```typescript
+let prUrl: string | null;
+try {
+  prUrl = await deps.pollForPR(branchPattern, PR_POLL_TIMEOUT_MS);
+} catch (e) {
+  const msg = e instanceof Error ? e.message : String(e);
+  deps.stderr(`[WARN coordinator] pollForPR threw: ${msg}`);
+  return { kind: 'escalated', escalationReason: { phase: 'pr-detection', reason: `pollForPR threw: ${msg}` } };
+}
+if (!prUrl) { ... }
+```
+
+### Yellow: `deps.stderr()` vs. `process.stderr.write()`
+
+Use `deps.stderr()` in catch blocks. The task spec example uses `process.stderr.write()` but the
+repo's `archiveFile` catch blocks use `deps.stderr()`. Consistency with repo pattern wins.
+
+---
+
+## Recommended Revisions
+
+1. Use `deps.stderr()` (not `process.stderr.write()`) in all catch blocks.
+2. Use `let prUrl: string | null` declared before the try block for `pollForPR` calls.
+3. Add a one-line comment in each `postToOutbox` catch explaining non-fatal policy:
+   `// postToOutbox write failure is non-fatal -- escalation still returns below`
+4. Include `pollForPR` in `full-pipeline.ts` even though task description only names `implement.ts`.
+5. Include UX gate zombie detection fix in `implement.ts` line 144.
+
+---
+
+## Residual Concerns
+
+- **No tests for throw injection:** This PR fixes the runtime behavior but adds no tests for
+  the throw paths. Tests are a planned follow-up (per the audit doc). The absence of tests means
+  a regression in this fix would not be caught by CI. Low concern for this PR -- the fix is
+  mechanical and the pattern is simple.
+- **`adaptive-pipeline.ts` line 362 `postToOutbox` is unguarded** but is explicitly out of scope
+  for this task. Should be addressed in a follow-up.

package/docs/ideas/backlog.md

@@ -7251,3 +7251,103 @@ Option C (hybrid): Heuristic pass first, LLM for anything ambiguous or conflicti
 This IS the implementation of that feature. The manually-authored `.worktrain/rules/*.md` files are the canonical output. The preprocessing is how you get there automatically without having to write them by hand.
 
 **Priority:** Medium. Useful for any workspace with multiple tools. Essential for team repos where Cursor rules, AGENTS.md, and custom conventions might conflict. Build the categorized injection path (phase-scoped rules) first; add the automated preprocessing as a follow-up.
+
+---
+
+## True session status for WorkTrain: live agent state, not activity inference (Apr 21, 2026)
+
+**The problem:** The console currently infers session status from last event timestamp. A session with no events for >1 hour becomes "dormant." For the WorkRail MCP server this is unavoidable -- it doesn't have access to the agent loop state. But WorkTrain does. It should show true status.
+
+### What WorkTrain knows that the MCP server doesn't
+
+WorkTrain has direct access to:
+- `DaemonRegistry` -- tracks every active session by workrailSessionId in memory. If a session is in the registry, it's running. If not, it's not.
+- `DaemonEventEmitter` -- structured events fired synchronously by the agent loop
+- `daemon_heartbeat` -- fires every 30s. If last heartbeat >90s ago, daemon is down.
+- Turn-level events -- `llm_turn_started/completed`, `tool_call_started/completed` -- know exactly what the agent is doing RIGHT NOW
+- `agent_stuck` -- stuck heuristic fired, session may be stalled
+- `session_aborted` -- daemon killed mid-session (now emitted on SIGTERM)
+
+### True session status taxonomy
+
+| Status | Meaning | Detection |
+|---|---|---|
+| `active:thinking` | LLM API call in progress | `llm_turn_started` without `llm_turn_completed` |
+| `active:tool` | Tool executing | `tool_call_started` without `tool_call_completed`, name=Bash/Read/etc. |
+| `active:idle` | Between turns | Last event was `llm_turn_completed`, session in DaemonRegistry |
+| `stuck` | Stuck heuristic fired | `agent_stuck` event, session still in DaemonRegistry |
+| `completed:success` | Done successfully | `session_completed` outcome=success |
+| `completed:timeout` | Hit wall-clock limit | `session_completed` outcome=timeout |
+| `completed:stuck` | Aborted by stuck policy | `session_completed` outcome=stuck |
+| `completed:max_turns` | Hit turn limit | `session_completed` outcome=timeout detail=max_turns |
+| `aborted` | Daemon killed mid-run | `session_aborted` event |
+| `daemon:down` | No recent heartbeat | Last `daemon_heartbeat` >90s ago |
+
+### Where to surface this
+
+1. **`worktrain status`** -- already shows session overview. Replace activity-inferred "RUNNING" with true status labels.
+2. **`worktrain health <sessionId>`** -- already shows per-session summary. Add "Current state: active:tool (Bash, 23s)" line.
+3. **Console workspace view** -- each session row should show true status badge, not just "live" vs "dormant."
+4. **`worktrain logs --follow`** -- prefix each event with the derived session state so the log stream is self-explanatory.
+
+### Implementation
+
+The status is derivable from the event log in O(N) where N is events for this session -- scan from the end, find the most recent relevant event. For live sessions, also check DaemonRegistry membership.
+
+The daemon heartbeat + DaemonRegistry membership is the key insight: if the session's workrailSessionId is in DaemonRegistry AND the daemon is alive (recent heartbeat), the session is definitely running. If it's not in DaemonRegistry, the session is done regardless of what the event log says.
+
+### Priority
+
+Medium-high. True session status makes WorkTrain trustworthy as an autonomous system -- operators can see exactly what's happening without guessing. Especially important as session durations get longer (55-minute discovery sessions, 120-minute pipeline runs).
+
+---
+
+## Workflows tab: incorrect source attribution for bundled workflows (Apr 21, 2026)
+
+**The bug:** The Workflows tab in the console shows bundled workflows (e.g. `coding-task-workflow-agentic`, `workflow-for-workflows`) as coming from "User Library" instead of "WorkRail Built-in". This is a WorkRail MCP server issue, not a WorkTrain issue.
+
+**Likely cause:** The source attribution logic reads from the workflow's loaded source (the `WorkflowSource` type). When a workflow exists in both the bundled set AND a user's managed sources or remembered roots, the source returned is the one that "wins" in the storage layer -- which may be the user path rather than the bundled path. Or the `source.kind` field is incorrectly set to `'personal'` for workflows that were loaded from the bundled workflows directory.
+
+**Where to look:**
+- `src/infrastructure/storage/schema-validating-workflow-storage.ts` -- source kind propagation
+- `src/mcp/handlers/shared/workflow-source-visibility.ts` -- how source is mapped to display label in `list_workflows`
+- `src/infrastructure/storage/file-workflow-storage.ts` -- how `source.kind` is assigned when loading from disk
+
+**Expected behavior:** Workflows in the `workflows/` directory of the workrail package should always display as "WorkRail Built-in" regardless of whether the user also has a managed source that happens to include the same directory.
+
+**Priority:** Low for WorkTrain (doesn't affect functionality). Medium for WorkRail MCP (misleading UI, users may think they accidentally modified bundled workflows).
+
+---
+
+## Coordinator-managed git state and agent crash recovery (Apr 21, 2026)
+
+### Git state management (coordinator's job)
+
+Before dispatching any WorkTrain session that does git work:
+1. Check for `.git/index.lock` -- if present, verify the owning PID is dead (via `lsof` on macOS), then remove it
+2. Abort any in-progress git operations: `git rebase --abort; git merge --abort`
+3. Verify the workspace is in a clean state before handing off to the agent
+
+Every session that touches files gets a worktree (already implemented). The coordinator ensures worktrees are created cleanly and removed after session completion. The orphan TTL cleanup (24h) handles crash cases.
+
+### Agent crash recovery (coordinator's job)
+
+An agent can die from: stream watchdog timeout (600s no progress), OOM kill, or SIGKILL. In all cases the session event log is intact -- the full conversation history is preserved.
+
+**The coordinator should detect and recover automatically:**
+
+1. Monitor child sessions via `worktrain await`
+2. If a session returns `_tag: 'aborted'` or `_tag: 'timeout'` mid-pipeline:
+   - Check if the session made meaningful progress (step advances > 0, or notes written)
+   - If yes: resume the session -- same session ID, same context, agent picks up at last checkpoint
+   - If no (zero progress): retry from scratch with a fresh session, same context bundle
+3. Retry up to N times (configurable, default 2) before escalating to Human Outbox
+4. Track which phase failed and inject a hint on retry: "Previous attempt failed at this step. Retry with fresh approach."
+
+**This is session continuation applied to crash recovery.** The agent's conversation history is fully preserved. Resuming puts it back exactly where it was. The 600s watchdog timeout (the most common failure) almost always means a hung LLM call or a tool timeout -- resuming naturally retries the step.
+
+**Implementation:** `runFullPipeline` and `runImplementPipeline` already have per-phase error handling. Extend each `awaitSessions` call: on non-success outcome, attempt resume before returning escalated. The resume logic is `worktrain session continue <sessionId>` (once that command exists) or `dispatchAdaptivePipeline` with the existing session's context.
+
+### Priority
+
+High. Agent crash recovery makes the overnight-autonomous bar achievable. Without it, any hung LLM call or tool timeout fails the entire pipeline silently. With it, transient failures are automatically retried and the pipeline continues.

package/package.json

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