@exaudeus/workrail 3.59.3 → 3.59.4

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

@@ -7299,3 +7299,55 @@ The daemon heartbeat + DaemonRegistry membership is the key insight: if the sess
 ### 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.3",
+  "version": "3.59.4",
   "description": "Step-by-step workflow enforcement for AI agents via MCP",
   "license": "MIT",
   "repository": {