@exaudeus/workrail 3.39.0 → 3.40.0

package/docs/design/coordinator-artifact-protocol-implementation-plan.md

@@ -0,0 +1,259 @@
+# Implementation Plan: Coordinator Artifact Protocol
+
+**Date:** 2026-04-18  
+**Branch:** `feat/coordinator-artifact-protocol`
+
+---
+
+## Problem Statement
+
+The PR review coordinator (`src/coordinators/pr-review.ts`) extracts review severity from completed review sessions by running a keyword scan on free-form step notes. The coordinator ignores the `artifacts[]` field that `GET /api/v2/sessions/:id/nodes/:nodeId` already returns. This makes severity extraction brittle and unmeasurable.
+
+The fix: define a `wr.review_verdict` artifact schema, update the final handoff step to emit it, update `getAgentResult()` to return artifacts alongside notes, and update the coordinator to try the artifact path before the keyword scan.
+
+---
+
+## Acceptance Criteria
+
+1. `npm run build` completes with 0 TypeScript errors
+2. `tests/unit/coordinator-pr-review.test.ts` passes (all existing tests + new `readVerdictArtifact` tests)
+3. `readVerdictArtifact([{ kind: 'wr.review_verdict', verdict: 'clean', ... }])` returns `{ severity: 'clean', source: 'artifact', ... }`
+4. `readVerdictArtifact([])` returns `null`
+5. `readVerdictArtifact([{ kind: 'wr.review_verdict', verdict: 'INVALID' }])` returns `null` and logs WARN
+6. `CoordinatorDeps.getAgentResult` return type is `Promise<{ recapMarkdown: string | null; artifacts: readonly unknown[] }>`
+7. `WorkflowRunSuccess` has optional field `lastStepArtifacts?: readonly unknown[]`
+8. `mr-review-workflow.agentic.v2.json` phase-6-final-handoff has `outputContract: { contractRef: 'wr.contracts.review_verdict', required: false }`
+9. `isValidContractRef('wr.contracts.review_verdict')` returns `true`
+10. `validateArtifactContract([{ kind: 'wr.review_verdict', verdict: 'clean', ... }], { contractRef: 'wr.contracts.review_verdict' })` returns `{ valid: true, artifact: ... }`
+
+---
+
+## Non-Goals
+
+- Do NOT add a `/api/v2/sessions/:id/artifacts` server-side aggregation endpoint
+- Do NOT change `required: false` to `required: true` (post-graduation decision)
+- Do NOT remove the keyword-scan fallback from `parseFindingsFromNotes`
+- Do NOT add a `coordinatorProtocol` field to the workflow JSON (deferred)
+- Do NOT add artifacts to `spawn_agent` return value (post-MVP)
+- Do NOT make `source` required on `ReviewFindings` (breaking change deferred)
+
+---
+
+## Philosophy Constraints
+
+- **Make illegal states unrepresentable:** `verdict`, `source`, `confidence` use closed enums
+- **Validate at boundaries:** Zod `safeParse` in `readVerdictArtifact()`; engine validation via `validateArtifactContract()`
+- **Errors are data:** `readVerdictArtifact()` returns `ReviewFindings | null`, not throws
+- **Functional/declarative:** `readVerdictArtifact()` is a pure function
+- **Prefer fakes over mocks:** New tests use `makeFakeDeps()` pattern
+
+---
+
+## Invariants
+
+1. `required: false` in outputContract -- never block sessions during transition
+2. Schema registration (`ARTIFACT_CONTRACT_REFS`) MUST be done before workflow JSON update (compiler validates at load time via `isValidContractRef()`)
+3. Keyword-scan fallback MUST remain live in `parseFindingsFromNotes`
+4. All call sites of `CoordinatorDeps.getAgentResult` MUST handle `{ recapMarkdown, artifacts }` shape
+5. `readVerdictArtifact()` MUST log `[WARN coord:reason=artifact_parse_failed]` when kind matches but safeParse fails
+6. Per-node HTTP fetch failures MUST be caught individually (not by outer try/catch)
+7. `makeContinueWorkflowTool` AND `makeCompleteStepTool` MUST both pass artifacts to `onComplete`
+
+---
+
+## Selected Approach
+
+**Candidate A:** Three ordered changes, all additive, following existing repo patterns exactly.
+
+**Rationale:** Zero new infrastructure; follows `loop-control.ts` schema pattern; follows `WorkflowRunSuccess.lastStepNotes` conditional spread pattern; follows `makeFakeDeps()` testing pattern; backward compatible via `required: false` + keyword-scan fallback.
+
+**Runner-up:** Tip-node only artifact read. Disqualified by task spec 'CRITICAL: must aggregate artifacts across ALL session nodes'.
+
+---
+
+## Slices
+
+### Slice 1: Schema registration (prerequisite for all other changes)
+
+**Files:**
+- `src/v2/durable-core/schemas/artifacts/review-verdict.ts` (NEW)
+- `src/v2/durable-core/schemas/artifacts/index.ts` (update)
+- `src/v2/durable-core/domain/artifact-contract-validator.ts` (update)
+
+**Work:**
+1. Create `review-verdict.ts` following `loop-control.ts` pattern:
+   - `REVIEW_VERDICT_CONTRACT_REF = 'wr.contracts.review_verdict' as const`
+   - `ReviewVerdictArtifactV1Schema = z.object({ kind: z.literal('wr.review_verdict'), verdict: z.enum(['clean', 'minor', 'blocking']), confidence: z.enum(['high', 'medium', 'low']), findings: z.array(z.object({ severity: z.enum(['critical', 'major', 'minor', 'nit']), summary: z.string().min(1) }).strict()), summary: z.string().min(1) }).strict()`
+   - `isReviewVerdictArtifact()` type guard
+   - `parseReviewVerdictArtifact()` convenience function
+2. Update `index.ts`: export all new symbols, add `'wr.contracts.review_verdict'` to `ARTIFACT_CONTRACT_REFS`
+3. Update `artifact-contract-validator.ts`: import new symbols, add `case REVIEW_VERDICT_CONTRACT_REF:` to switch with `validateReviewVerdictContract()` helper
+
+**Done when:** `isValidContractRef('wr.contracts.review_verdict')` returns `true`; `validateArtifactContract([{ kind: 'wr.review_verdict', ... }], { contractRef: 'wr.contracts.review_verdict' })` returns `{ valid: true, artifact: ... }`.
+
+---
+
+### Slice 2: Fix onComplete callback signature
+
+**Files:**
+- `src/daemon/workflow-runner.ts`
+
+**Work:**
+1. Change `onComplete` closure definition (line 2096) from `(notes: string | undefined): void` to `(notes: string | undefined, artifacts?: readonly unknown[]): void`
+2. Add `let lastStepArtifacts: readonly unknown[] | undefined;` near `let lastStepNotes`
+3. Update `onComplete` body to set `lastStepArtifacts = artifacts`
+4. Add `lastStepArtifacts?: readonly unknown[]` to `WorkflowRunSuccess` interface
+5. Update `makeCompleteStepTool` call to `onComplete(notes)` -> `onComplete(notes, params.artifacts as readonly unknown[] | undefined)` (line 1249)
+6. Update `makeContinueWorkflowTool` call to `onComplete(params.notesMarkdown)` -> `onComplete(params.notesMarkdown, params.artifacts as readonly unknown[] | undefined)` (line 1046)
+7. Update the final `return` in `runWorkflow()` (line 2622) to spread `lastStepArtifacts` conditionally
+
+**Done when:** `WorkflowRunSuccess` has `lastStepArtifacts` field; both tool factory call sites pass artifacts; `npm run build` passes.
+
+---
+
+### Slice 3: Update getAgentResult to return artifacts
+
+**Files:**
+- `src/cli-worktrain.ts`
+
+**Work:**
+1. Change `getAgentResult: async (sessionHandle: string): Promise<string | null>` -> `Promise<{ recapMarkdown: string | null; artifacts: readonly unknown[] }>`
+2. In the implementation body:
+   - After reading `runs[0]`, read `runs[0].nodes` as `Array<{ nodeId: string; [key: string]: unknown }>` (with null check)
+   - Walk all nodes, fetch each node detail with individual `try/catch`:
+     ```
+     for (const node of nodes) {
+       try {
+         const nodeRes = await fetch(nodeUrl + '/' + node.nodeId)
+         // collect artifacts from nodeData['artifacts'] 
+       } catch { /* log WARN, continue */ }
+     }
+     ```
+   - Return `{ recapMarkdown: recap, artifacts: collectedArtifacts }` (or `{ recapMarkdown: null, artifacts: [] }` on failure)
+3. Early-return failures must also return `{ recapMarkdown: null, artifacts: [] }` instead of `null`
+
+**Done when:** Return type is `Promise<{ recapMarkdown: string | null; artifacts: readonly unknown[] }>`; TypeScript compile-time errors at call sites force updates.
+
+---
+
+### Slice 4: Update coordinator to use artifact path
+
+**Files:**
+- `src/coordinators/pr-review.ts`
+
+**Work:**
+1. Import `ReviewVerdictArtifactV1Schema` from artifacts schema
+2. Update `CoordinatorDeps.getAgentResult` return type to match new shape
+3. Add `source?: 'artifact' | 'keyword_scan'` to `ReviewFindings` interface
+4. Add `readVerdictArtifact(artifacts: readonly unknown[]): ReviewFindings | null` pure function:
+   - Walk artifacts array
+   - For each, check `(raw as any).kind === 'wr.review_verdict'`
+   - If kind matches, call `ReviewVerdictArtifactV1Schema.safeParse(raw)`
+   - On success: return `{ severity: v.verdict, findingSummaries: v.findings.map(f => f.summary), raw: JSON.stringify(v), source: 'artifact' }`
+   - On failure: log `[WARN coord:reason=artifact_parse_failed]`, continue to next artifact
+   - If no valid artifact found and artifacts.length > 0: log `[INFO coord:source=keyword_scan reason=no_valid_artifact artifactCount=N]`
+   - Return `null`
+5. Update both call sites in `runPrReviewCoordinator()`:
+   - `const { recapMarkdown: notes, artifacts } = await deps.getAgentResult(handle);`
+   - `const findingsResult = readVerdictArtifact(artifacts) ? ok(readVerdictArtifact(artifacts)!) : parseFindingsFromNotes(notes);`
+   - Log `[INFO coord:source=artifact]` or `[INFO coord:source=keyword_scan]`
+6. Add divergence check (O2): if artifact verdict and keyword-scan severity disagree, log WARN
+7. Update traceability JSON block to include `source` field
+
+**Done when:** Coordinator tries artifact path first; keyword-scan fallback works; logging emits; `npm run build` passes.
+
+---
+
+### Slice 5: Update mr-review workflow
+
+**Files:**
+- `workflows/mr-review-workflow.agentic.v2.json`
+
+**Work:**
+1. In `phase-6-final-handoff` step, add `outputContract: { "contractRef": "wr.contracts.review_verdict", "required": false }`
+2. Append to the step `prompt` field the artifact emission instruction:
+   ```
+   \n\nAfter completing your notes, emit a structured verdict via complete_step artifacts[] parameter. Use exactly this schema:\n{ "kind": "wr.review_verdict", "verdict": "clean|minor|blocking", "confidence": "high|medium|low", "findings": [{ "severity": "critical|major|minor|nit", "summary": "one-line description" }], "summary": "one-line overall summary" }\nFor a clean review with no findings, use findings: [].
+   ```
+
+**Done when:** Workflow JSON validates via `npm run build`; `isValidContractRef('wr.contracts.review_verdict')` returns `true` (prerequisite: Slice 1 must be done first).
+
+---
+
+### Slice 6: Tests
+
+**Files:**
+- `tests/unit/coordinator-pr-review.test.ts`
+
+**Work:**
+1. Update `makeFakeDeps()` to return `{ recapMarkdown: string | null; artifacts: readonly unknown[] }` from `getAgentResult` (change return type from `string | null`)
+2. Update `ReviewFindings` literal objects in `buildFixGoal` tests to add `source: 'artifact'` or `source: 'keyword_scan'` (or leave as optional -- `source?` means no update needed)
+3. Add new `describe('readVerdictArtifact')` block:
+   - `it('returns ReviewFindings with source artifact for valid artifact')`
+   - `it('returns null for invalid schema (wrong verdict enum)')`
+   - `it('returns null for empty artifacts array')`
+   - `it('returns null for artifact with different kind')`
+   - `it('returns first valid artifact when multiple present')`
+4. Import `readVerdictArtifact` from `pr-review.js`
+
+**Done when:** All existing tests pass; 5 new `readVerdictArtifact` tests pass.
+
+---
+
+## Test Design
+
+**Unit tests (pure function):**
+- `readVerdictArtifact` with valid `wr.review_verdict` artifact -> returns `ReviewFindings` with `severity` mapped from `verdict`, `source: 'artifact'`
+- `readVerdictArtifact` with invalid schema (wrong enum) -> returns `null`
+- `readVerdictArtifact` with empty array -> returns `null`
+- `readVerdictArtifact` with artifact of different `kind` -> returns `null` (no false positives)
+- `readVerdictArtifact` with valid + invalid artifacts -> returns valid one (first match wins)
+
+**Integration tests (fake deps):**
+- Existing `runPrReviewCoordinator` tests must pass with updated `getAgentResult` return type
+- The fake `getAgentResult` returns `{ recapMarkdown: 'APPROVE ...', artifacts: [] }` by default
+
+---
+
+## Risk Register
+
+| Risk | Likelihood | Impact | Mitigation |
+|------|-----------|--------|------------|
+| Missing `makeContinueWorkflowTool` onComplete update | Low | Silent -- artifacts not forwarded from continue_workflow path | Manual verification; code comment at both call sites |
+| Per-node HTTP fetch error aborting aggregation | Low | Graceful fallback to keyword scan | Per-node try/catch (Slice 3 R2) |
+| LLM emits extra fields in artifact (`.strict()` reject) | Medium | Zod fail -> WARN log -> keyword scan fallback | Acceptable during `required: false` transition |
+| `runs[0].nodes` undefined or empty | Low | Empty artifact array -> keyword scan fallback | Null check in Slice 3 |
+
+---
+
+## PR Packaging Strategy
+
+Single PR: `feat/coordinator-artifact-protocol`
+
+All 6 slices in one PR. Changes are tightly coupled (schema + validator + coordinator must be consistent). Breaking the PR into multiple would require interface stubs that add noise.
+
+**PR description structure:**
+1. Summary: what was done and why
+2. Change 1 (schema), Change 2 (onComplete), Change 3 (coordinator + workflow)
+3. Test plan: `npm run build`, `npx vitest run tests/unit/coordinator-pr-review.test.ts`
+
+---
+
+## Philosophy Alignment
+
+| Slice | Principle | Status |
+|-------|-----------|--------|
+| 1 (schema) | Make illegal states unrepresentable | Satisfied -- closed enums, kind literal |
+| 1 (schema) | Validate at boundaries | Satisfied -- Zod strict schema |
+| 2 (onComplete) | Immutability by default | Satisfied -- `readonly unknown[]` |
+| 3 (getAgentResult) | Errors are data | Satisfied -- returns `{ recapMarkdown: null, artifacts: [] }` not null |
+| 4 (coordinator) | Functional/declarative | Satisfied -- `readVerdictArtifact()` is pure |
+| 4 (coordinator) | Make illegal states unrepresentable | Tension -- `source?` optional; accepted tradeoff |
+| 6 (tests) | Prefer fakes over mocks | Satisfied -- `makeFakeDeps()` pattern |
+
+---
+
+## planConfidenceBand: High
+
+- unresolvedUnknownCount: 0
+- followUpTickets: Y1 (make source required post-graduation), Y2 (remove keyword scan post-graduation), spawn_agent artifacts gap (post-MVP)

package/docs/ideas/backlog.md

@@ -5700,136 +5700,194 @@ Tested empirically today. This is what actually works, not what's specced.
 
 ---
 
-### Self-healing daemon: detect internal failures, kill, diagnose, fix, reboot, resume (Apr 18, 2026)
+### Autonomous feature development: scope → breakdown → parallel execution → merge (Apr 18, 2026)
 
-**The problem:** today if WorkRail's MCP connection drops or the daemon's internal tooling fails, agents continue running without enforcement -- producing unverified output that looks correct but bypassed all workflow gates. The user has no way to know this happened until they manually inspect session completion events.
+**The vision:** give WorkTrain a feature scope -- from a vague idea to a fully groomed ticket -- and it figures out the rest. Discovery if needed, design if needed, breakdown into parallel slices, execution across worktrees, context management across agents, bringing it all back together.
 
-**What happened today:** WorkRail MCP went down mid-session across ~10 concurrent agents. All sessions show INCOMPLETE (no `run_completed` event). Agents produced PRs, reviews, and merges -- two PRs landed on main -- without any confirmed workflow completion. Required manual audit after the fact.
+**The four pillars the user cares about:**
+1. **Autonomy** -- WorkTrain takes a scope and figures out the work breakdown without hand-holding
+2. **Quality** -- comes FROM autonomy + workflow enforcement + coordination. Each slice goes through the right phases.
+3. **Throughput** -- parallel slices across worktrees simultaneously. N agents working while you focus elsewhere.
+4. **Visibility** -- one coherent work unit you can track at a glance, not N unrelated sessions in a flat list.
 
-**What WorkTrain needs:**
+**The pipeline for a scope:**
 
-**1. Detect its own tooling failures**
-- Monitor whether `complete_step` / `continue_workflow` tool calls are succeeding or timing out
-- Detect when the WorkRail session store becomes unreachable
-- Detect when the MCP connection (for agents that use MCP-mode) is lost
-- Distinguish: "agent is thinking" vs "agent is stuck" vs "agent's tools are broken"
+```
+Input: "add GitHub polling support" (any level of definition -- idea to full spec)
+  │
+  ├── [if vague] ideation + spec authoring → output: BRD / acceptance criteria
+  ├── classify-task → taskComplexity, hasUI, touchesArchitecture, taskMaturity
+  ├── [if Medium/Large] discovery → context bundle, invariants, candidate files
+  ├── [if touchesArchitecture] design → candidates, review, selected approach
+  ├── breakdown → parallel slices with dependency graph
+  │     ├── Slice 1: types + schema         (worktree A)
+  │     ├── Slice 2: polling adapter        (worktree B, depends: 1)
+  │     ├── Slice 3: scheduler integration  (worktree C, depends: 2)
+  │     └── Slice 4: tests                 (worktree D, depends: 1-3)
+  ├── [parallel execution] each slice: implement → review → (fix if needed) → approved
+  ├── [serial integration] merge slices in dependency order, verify after each
+  └── [final] integration test → PR created → notification to user
+```
 
-**2. Kill the agent cleanly on detected failure**
-- When internal tooling is detected broken, stop the agent immediately -- do NOT let it continue without enforcement
-- Retain the full conversation history and step notes up to the point of failure
-- Mark the session as `interrupted_tooling_failure` (distinct from `error` or `timeout`)
-- Write the failure event to the daemon event log with the exact cause
+**Context management across agents:**
+- Coordinator maintains a "work unit manifest": current phase, slice status, shared invariants, decisions made in design phase
+- Each spawned agent receives a context bundle: relevant portion of the manifest + files it needs + decisions from upstream phases
+- Agents don't rediscover what the coordinator already knows
+- After each agent completes, its findings update the manifest (new invariants found, scope changes, follow-up tickets)
 
-**3. Self-diagnose**
-- Run a lightweight health check: can we reach the session store? Can we decode the continueToken? Is the WorkRail engine responding?
-- Identify the root cause: MCP disconnect? Session store corruption? Token decode failure? Port conflict?
-- Distinguish recoverable (restart and resume) from non-recoverable (session data corrupted, must restart from scratch)
+**Worktree coordination:**
+- Each slice gets its own worktree (already done via `--isolation worktree`)
+- Coordinator tracks which files each slice touches -- detects conflicts before they happen
+- Independent slices run in parallel; dependent slices queue automatically
+- Merge order follows the dependency graph, not wall-clock completion time
 
-**4. Fix and reboot**
-- For recoverable failures: restart the WorkRail engine in-process, re-register tools, verify health before resuming
-- For MCP-mode failures: reconnect without killing the parent session
-- For port conflicts: clear the lock and rebind
-- All of this happens automatically, without user intervention
+**Knowing when to spawn a new main agent:**
+- When a slice is too large or discovers unexpected scope, it requests a breakdown from the coordinator
+- When a review finds a Critical finding, the coordinator spawns a dedicated fix agent with the finding + relevant context
+- When integration reveals a regression, coordinator spawns an investigation agent before retrying the merge
 
-**5. Resume with context**
-- Resume the session from the last confirmed `complete_step` / `advance_recorded` event
-- Inject a `<context>` block into the resumed session: "Your previous session was interrupted due to [reason]. Here is what you completed before the interruption: [last 3 step notes]. Resume from where you left off."
-- The agent never knows the interruption happened -- it just continues
-- If resume fails (token expired, session corrupted), escalate to the user with full context on what was completed and what wasn't
+**The coordinator's job (what stays in scripts, not LLM):**
+- Maintain the manifest (JSON file, append-only)
+- Compute the dependency graph
+- Decide parallelism vs serialization
+- Route: clean → merge, minor findings → fix agent, critical → escalate
+- Track worktrees, detect conflicts
+- Sequence the merge order
 
-**6. Audit trail**
-- Every self-heal event is recorded in `~/.workrail/events/daemon/YYYY-MM-DD.jsonl` as `tooling_failure_detected`, `self_heal_started`, `self_heal_succeeded` / `self_heal_failed`
-- The console shows a `⚠️ self-healed` badge on sessions that were interrupted and resumed
-- The user can query: "which sessions were interrupted today?" and get the full list with causes
+**What requires LLM cognition:**
+- Discovery (what are the invariants, which files matter)
+- Design (which approach, what tradeoffs)
+- Implementation (write the code)
+- Review (is this correct and complete)
+- Breakdown (what are the right slice boundaries)
 
-**Implementation path:**
-- Phase 1: detection only -- log `tooling_failure_detected` when a session produces output without `run_completed`. Surface in console and status command.
-- Phase 2: kill on detection -- stop agents immediately when tooling failure detected. No more unverified output reaching main.
-- Phase 3: auto-resume -- restart and resume for recoverable failures.
-- Phase 4: full self-heal loop -- diagnose, fix, reboot, resume automatically.
+**The minimum viable version:**
+A coordinator that handles a Medium/Small scoped task (already classified, no need for ideation or design). Takes 2-4 parallel slices, runs them, reviews each, merges when clean. No escalation handling in v1 -- if anything fails, notify the user.
 
-**The invariant that must hold:** no output from a WorkTrain agent should be acted on (committed, merged, posted) unless its session has a confirmed `run_completed` event. This is the enforcement guarantee. Self-healing is what makes that guarantee survivable.
+This is the thing that makes WorkTrain feel like a senior engineer taking ownership of a task, not a tool you have to supervise step by step.
 
 ---
 
-### CRITICAL architectural clarity: three systems, one shared engine (permanent reference)
+### Coordinator design decision: MVP-first, generalize after (Apr 18, 2026)
 
-This is the most important architectural fact about this codebase. Every agent and contributor must understand this before touching anything.
+**Decision:** Build the first coordinator as a PR review-specific script. Generalize to a reusable coordinator framework after proving it works end-to-end.
 
-**WorkRail/WorkTrain is three separate systems sharing one engine:**
+**Rationale:** Three discovery runs all converged on the architecture (TypeScript script, `CoordinatorDeps` interface, 2-call HTTP for notes). The risk is over-engineering for hypothetical pipelines before validating the real one. PR review is the highest-value first use case with a clear success criterion.
 
-```
-                    Shared core
-          ┌─────────────────────────────┐
-          │  WorkRail engine            │
-          │  src/v2/durable-core/       │
-          │  ~/.workrail/data/sessions/ │
-          │  workflow registry          │
-          └────────┬──────────┬─────────┘
-                   │          │          │
-    ┌──────────────▼─┐  ┌─────▼──────┐  ┌▼─────────────┐
-    │ WorkRail MCP   │  │ WorkTrain  │  │ WorkRail     │
-    │ Server         │  │ Daemon     │  │ Console      │
-    │ workrail start │  │ worktrain  │  │ worktrain    │
-    │ src/mcp/       │  │ daemon     │  │ console      │
-    │                │  │ src/daemon/│  │ src/console/ │
-    │ Claude Code    │  │ src/trigger│  │              │
-    │ connects here  │  │            │  │ Shows BOTH   │
-    │ via stdio      │  │ autonomous │  │ MCP + daemon │
-    │                │  │ agent loop │  │ sessions     │
-    └────────────────┘  └────────────┘  └──────────────┘
-```
+**The generic coordinator architecture is already designed** (see `docs/discovery/coordinator-script-design.md`). The `CoordinatorDeps` interface and `AgentResult` bridge type make migration to a generic coordinator trivial -- the PR review script uses these types, so generalizing is additive, not a rewrite.
+
+**Migration path:** once PR review coordinator is proven in production, extract the routing logic (`parseFindings`, `routeByFindings`) and `CoordinatorDeps` interface into `src/coordinators/base.ts`. The PR review coordinator becomes one implementation of the base pattern.
+
+---
+
+### Architecture decisions from Apr 17-18 sessions (to record before files are cleaned up)
+
+**Decision 1: Structured output + tool calls can coexist (Apr 18)**
+Validated empirically via integration test. The beta API (`client.beta.messages.create()`) supports both JSON schema enforcement AND tool calls in the same request. Schema enforcement applies at `end_turn` only. Bedrock is more consistent than direct Anthropic API for system-prompt fallback behavior. This opens a future path for replacing `complete_step` with structured output, but `complete_step` remains the chosen primitive for now.
+
+**Decision 2: `complete_step` is the preferred daemon workflow-control primitive (Apr 18)**
+PR #569 merged. The daemon holds the continueToken in a closure; LLM calls `complete_step(notes)` and never handles the token directly. Structured output (`beta.messages.create` with JSON schema) was evaluated as an alternative and deferred -- it's a viable migration path for a future version but adds API complexity today. Follow-up: track a structured output migration as a future improvement, not a current priority.
+
+**Decision 3: AgentLoop error handling contract -- FatalToolError (Apr 16)**
+`FatalToolError` subclass selected for distinguishing recoverable from non-recoverable tool failures in the AgentLoop. The contract: user-facing tools (Bash, Read, Write) catch failures and return `isError: true` in the tool_result (loop continues, LLM can retry). Coordination tools with unrecoverable failures (session store corruption, token decode failure) throw `FatalToolError` -- `_executeTools` instanceof-checks this and kills the session rather than surfacing a confusing error to the LLM. This contract is part of the AgentLoop architecture and must be followed by any new tool implementations.
+
+**Decision 4: Use `wr.discovery` for discovery-only tasks, not `coding-task-workflow-agentic` (Apr 17)**
+Discovered from a broken session: `coding-task-workflow-agentic` dispatched with "do discovery only, no code" ran 11 step advances then stopped without `run_completed`. The workflow's implementation phases fired even with explicit instructions not to code. Lesson: when a trigger or coordinator wants pure discovery/research, use `wr.discovery` as the workflowId. `coding-task-workflow-agentic` should only be dispatched when implementation is the actual goal.
+
+**Decision 5: Bug -- MCP server EPIPE crash (Apr 18)**
+Root cause confirmed with 15 production crash log entries: `process.stderr` is missing an `'error'` event handler in `registerFatalHandlers()`. When an MCP client disconnects, Node.js emits `EPIPE` on stderr which crashes the process with an unhandled error. `process.stdout` already has equivalent protection via `wireStdoutShutdown()`. Fix: mirror the stdout protection for stderr. One-line fix being implemented in PR `fix/mcp-stderr-epipe-crash`.
+
+---
+
+### worktrain status → console integration (Apr 18, 2026)
+
+The `worktrain status` CLI command is Phase 1. Phase 2: the same data and rendering lives inside the console as the default landing view when you open it -- not the sessions list, the overview. Same `StatusDataPacket` type, two surfaces. The console overview replaces the need to run a CLI command; it auto-refreshes and stays live.
 
-**WorkRail MCP Server:** `workrail start` → stdio MCP server. Claude Code connects here. Provides `start_workflow`, `complete_step`, `list_workflows` etc. as MCP tools. Source: `src/mcp/`. Must be bulletproof -- a crash kills all Claude Code workflow tools.
+---
+
+### WorkTrain as a native macOS app (Apr 18, 2026)
+
+Long-term vision: WorkTrain becomes a full native Mac app -- not just a CLI + web console, but a proper macOS application with a menubar icon, system notifications, windows, and native UX.
 
-**WorkTrain Daemon:** `worktrain daemon` → autonomous agent runner. Drives sessions without human involvement. Calls the WorkRail engine **directly in-process** -- does NOT go through the MCP server. Source: `src/daemon/`, `src/trigger/`.
+**What this unlocks:**
+- Always-on menubar presence showing daemon status at a glance
+- Native macOS notifications (already built via osascript -- the app version uses UserNotifications framework directly)
+- The `worktrain status` overview as a native window, not a browser tab
+- Message queue and inbox as a native interface (type a message from anywhere on your Mac, not just the terminal)
+- Background daemon management -- start/stop/restart from the menubar without terminal
+- Deep system integration: file system events, calendar, Contacts, native share sheet
 
-**WorkRail Console:** `worktrain console` → unified read-only session viewer. Shows sessions from **both** the MCP server and the daemon (they share the same session store). Requires neither the MCP server nor the daemon to be running.
+**Tech stack options:**
+- Swift/SwiftUI: full native, best macOS integration, steeper learning curve from TypeScript
+- Electron + existing console UI: fastest path, same TypeScript codebase, but heavy
+- Tauri: Rust core + existing web frontend, lighter than Electron, good macOS support
+- React Native macOS: reuses React knowledge, not quite native feel
 
-**Rules that follow from this:**
-- MCP server code must never import from `src/daemon/` or `src/trigger/`
-- Daemon code must never depend on the MCP server being alive
-- Console code reads the session store directly -- no IPC with MCP or daemon needed
-- These are separate processes. A crash in one does not affect the others.
+**Recommended path:** Tauri wrapping the existing console UI. The console is already a React/Vite app. Tauri gives native menubar, notifications, and system APIs without rewriting the frontend. The WorkTrain daemon stays as a separate process managed by the app.
+
+**This is a post-v1 platform decision** -- not a near-term priority, but worth designing toward. Don't make architectural decisions that would make the Tauri wrapper hard later.
 
 ---
 
-### CRITICAL architectural clarity: three systems, one shared engine (permanent reference)
+### Long-running sessions: stay open across agent handoffs (Apr 18, 2026)
+
+**The problem:** today when an MR review session completes, it writes its findings and exits. If the findings require fixes, a new fix agent starts from scratch with no shared context. When the fix is done, a new re-review agent also starts from scratch. Three sessions that are logically one unit of work are isolated from each other.
 
-This is the most important architectural fact about this codebase. Every agent and contributor must understand this before touching anything.
+**The vision:** a session can stay open and wait -- dormant but alive -- while another agent does work. When that work completes, the waiting session resumes with full context continuity.
 
-**WorkRail/WorkTrain is three separate systems sharing one engine:**
+**The MR review example:**
 
 ```
-                    Shared core
-          ┌─────────────────────────────┐
-          │  WorkRail engine            │
-          │  src/v2/durable-core/       │
-          │  ~/.workrail/data/sessions/ │
-          │  workflow registry          │
-          └────────┬──────────┬─────────┘
-                   │          │          │
-    ┌──────────────▼─┐  ┌─────▼──────┐  ┌▼─────────────┐
-    │ WorkRail MCP   │  │ WorkTrain  │  │ WorkRail     │
-    │ Server         │  │ Daemon     │  │ Console      │
-    │ workrail start │  │ worktrain  │  │ worktrain    │
-    │ src/mcp/       │  │ daemon     │  │ console      │
-    │                │  │ src/daemon/│  │ src/console/ │
-    │ Claude Code    │  │ src/trigger│  │              │
-    │ connects here  │  │            │  │ Shows BOTH   │
-    │ via stdio      │  │ autonomous │  │ MCP + daemon │
-    │                │  │ agent loop │  │ sessions     │
-    └────────────────┘  └────────────┘  └──────────────┘
+[MR review session]  finds: 2 critical, 3 minor
+  → stays open, waiting for fixes
+  
+  [Fix agent session]  addresses all 5 findings
+    → completes, signals "fixes ready"
+  
+[MR review session resumes]  re-reads the diff, re-evaluates
+  → all 5 verified fixed, 0 new findings
+  → completes with APPROVE verdict
 ```
 
-**WorkRail MCP Server:** `workrail start` → stdio MCP server. Claude Code connects here. Provides `start_workflow`, `complete_step`, `list_workflows` etc. as MCP tools. Source: `src/mcp/`. Must be bulletproof.
+The same session that found the issues verifies the fixes. No context reconstruction. No risk of re-review missing something the original reviewer knew.
+
+**Other use cases for waiting sessions:**
+
+- **Architecture review waiting for approval:** architect session identifies a design gap, waits for the human to decide on direction, resumes when the decision is recorded
+- **Discovery session waiting for data:** a research session identifies that it needs a specific file or API response, signals "blocked on: fetch X", waits for a retrieval agent to deliver it, resumes with the data injected
+- **Coordinator waiting on child completion:** instead of a coordinator script polling `worktrain await`, the coordinator session can yield and be resumed by the daemon when child sessions complete -- same session, same context, no polling overhead
+- **Spec authoring waiting for stakeholder input:** a spec session writes a draft, flags "needs: human review of acceptance criteria", waits, resumes when the human adds a comment
+- **Integration test waiting for deployment:** a test coordination session waits for a deploy to complete before running integration tests
+
+**The key insight: the LLM doesn't experience waiting.**
 
-**WorkTrain Daemon:** `worktrain daemon` → autonomous agent runner. Drives sessions without human involvement. Calls the WorkRail engine **directly in-process**. Does NOT go through the MCP server. Source: `src/daemon/`, `src/trigger/`.
+LLMs have no concept of time. Between one turn and the next, zero time passes from the agent's perspective. This means "waiting" is not a thing that happens to the agent -- it just doesn't receive its next turn until the coordinator has something to give it.
 
-**WorkRail Console:** `worktrain console` → unified read-only session viewer. Shows sessions from **both** the MCP server and the daemon (shared session store). Requires neither to be running.
+The session is paused at the engine level (DAG holds at a node, no new turns issued). The agent submitted its output and simply hasn't received a response yet. When the coordinator is ready -- fix agent completed, human reviewed, deployment finished -- it advances the session with a turn that contains the new context. From the agent's perspective: it submitted findings and immediately received "here are the fixes, verify them."
+
+**No `wait_for` primitive needed at the workflow level.** The coordinator is the timing mechanism. This is the coordinator's job: know when each session is ready for its next input, and deliver that input at the right time.
+
+```
+Coordinator logic:
+
+1. Advance review session to "findings complete" node
+2. Read findings from session output
+3. Spawn fix agent with those findings
+4. Wait for fix agent to complete (worktrain await)
+5. Inject fix summary into review session's next turn
+6. Advance review session: "Here are the fixes. Verify them."
+   → LLM receives this as the natural next step, no time gap perceived
+```
+
+**Why this is more powerful than re-running a fresh session:**
+
+- **Context continuity:** the reviewer remembers what it found, why it flagged it, what invariants it was checking. A fresh session has to re-discover all of that.
+- **Relational memory:** "does this fix address the root cause I identified, or just the symptom?" -- only the original session knows the root cause reasoning.
+- **Efficiency:** no redundant context gathering. The resumed session picks up exactly where it left off.
+- **The agent doesn't know it's coordinating:** from the agent's view, it's a continuous workflow. The coordinator manages the timing externally.
+
+**Implementation path:**
 
-**Rules:**
-- MCP server code must never import from `src/daemon/` or `src/trigger/`
-- Daemon code must never depend on the MCP server being alive
-- Console reads the session store directly -- no IPC with either needed
-- These are separate processes. A crash in one does not affect the others.
+- Phase 1: coordinator scripts withhold `complete_step` advancement until the condition is met. This already works today -- the coordinator just doesn't advance the session until the fix agent is done.
+- Phase 2: the coordinator passes structured context when advancing: `complete_step(session, { injectedContext: fixSummary })`. The session receives it as part of the next step's prompt.
+- Phase 3: declarative pipelines -- workflow JSON declares that step N waits for an external condition before proceeding. The coordinator reads this and manages the timing automatically. No hand-coded coordinator script needed for common patterns.

package/package.json

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

package/workflows/mr-review-workflow.agentic.v2.json

@@ -312,7 +312,11 @@
     {
       "id": "phase-6-final-handoff",
       "title": "Phase 6: Final Handoff",
-      "prompt": "Provide the final MR review handoff.\n\nInclude:\n- MR title and purpose\n- review mode used\n- final recommendation and confidence band\n- confidence assessment summary, including the most important reason confidence was capped if it was not High\n- counts of Critical / Major / Minor / Nit findings\n- top findings with rationale\n- strongest remaining areas of uncertainty, if any\n- summary of the coverage ledger, especially any still-uncertain domains\n- ready-to-post MR comments summary\n- any validation outcomes a human reviewer should see\n- review environment status:\n  - what review target/context sources were successfully used\n  - what important sources were missing or ambiguous\n  - boundary confidence and context confidence\n  - how those limits affected the review\n- path to the full human-facing review artifact (`reviewDocPath`) only if one was created\n\nRules:\n- the final recommendation assists a human reviewer; it does not replace them\n- if `reviewDocPath` exists, treat it as a human-facing companion artifact only\n- be explicit when missing PR/ticket/doc/boundary context limited confidence\n- do not post comments, approve, reject, or merge unless the user explicitly asks",
+      "prompt": "Provide the final MR review handoff.\n\nInclude:\n- MR title and purpose\n- review mode used\n- final recommendation and confidence band\n- confidence assessment summary, including the most important reason confidence was capped if it was not High\n- counts of Critical / Major / Minor / Nit findings\n- top findings with rationale\n- strongest remaining areas of uncertainty, if any\n- summary of the coverage ledger, especially any still-uncertain domains\n- ready-to-post MR comments summary\n- any validation outcomes a human reviewer should see\n- review environment status:\n  - what review target/context sources were successfully used\n  - what important sources were missing or ambiguous\n  - boundary confidence and context confidence\n  - how those limits affected the review\n- path to the full human-facing review artifact (`reviewDocPath`) only if one was created\n\nRules:\n- the final recommendation assists a human reviewer; it does not replace them\n- if `reviewDocPath` exists, treat it as a human-facing companion artifact only\n- be explicit when missing PR/ticket/doc/boundary context limited confidence\n- do not post comments, approve, reject, or merge unless the user explicitly asks\n\nIMPORTANT: After writing your notes, emit a structured verdict via complete_step's artifacts[] parameter using EXACTLY this schema (no extra fields):\n{\n  \"kind\": \"wr.review_verdict\",\n  \"verdict\": \"clean\" | \"minor\" | \"blocking\",\n  \"confidence\": \"high\" | \"medium\" | \"low\",\n  \"findings\": [ { \"severity\": \"critical\" | \"major\" | \"minor\" | \"nit\", \"summary\": \"one-line description\" } ],\n  \"summary\": \"one-line overall verdict summary\"\n}\nFor a clean review with no findings, use findings: []. The verdict field maps to severity: clean = no blocking issues, minor = small issues only, blocking = critical or major issues found.",
+      "outputContract": {
+        "contractRef": "wr.contracts.review_verdict",
+        "required": false
+      },
       "requireConfirmation": true
     }
   ]