@exaudeus/workrail 3.38.0 → 3.40.0

package/docs/discovery/hypothesis-challenge-report.md

@@ -0,0 +1,44 @@
+# Hypothesis Challenge: PR Review Coordinator HTTP-First Design
+
+*Generated: 2026-04-18*
+
+## Target Claim
+
+The PR review coordinator's HTTP-first design (Candidate B) is sound: the 2-call HTTP notes extraction is reliable, the two-tier keyword parser correctly classifies review severity, and the 5 robustness rules are sufficient.
+
+## Strongest Counter-Argument
+
+`phase-6-final-handoff` has `requireConfirmation: true`. The preferredTipNodeId may point to a checkpoint/confirmation node whose recapMarkdown is sparse or absent, causing the keyword scanner to misclassify clean PRs as 'unknown' and escalate them unnecessarily.
+
+**Verdict:** Mitigated. In autonomous mode, the agent calls `continue_workflow` with substantive notes before the confirmation gate. WorkRail stores these notes as the RECAP payload for the node. The recapMarkdown IS populated for autonomous sessions completing phase-6. The requireConfirmation flag only blocks advancement until notes are written -- which the autonomous agent does.
+
+## Weak Assumptions / Evidence Gaps
+
+1. **`runs[0]` is always the most recent run:** True in practice. WorkRail appends new runs; index 0 is the most recent. Confirmed in worktrain-await.ts pollSession() which uses `runs[0]`.
+
+2. **Keyword scan is context-unaware:** 'blocking' appearing in negative context ('this is not blocking') would trigger a false positive. Mitigation: require BLOCKING keyword to be present without a preceding negation. Simpler: use priority order -- any blocking keyword -> blocking, regardless of context. The conservative default is acceptable.
+
+3. **go/no-go time check needs adaptation:** Rule 3 (don't spawn if remaining time < 20 minutes) was designed for daemon sessions with known maxSessionMinutes. A CLI coordinator has no such limit. Adaptation: track wall-clock time since coordinator start, refuse to spawn new sessions if elapsed > coordinator_max_minutes - 20.
+
+## Likely Failure Modes
+
+1. **recapMarkdown null for final step** -> 'unknown' severity -> escalate (conservative, correct)
+2. **Fix-agent loop max 3 passes exceeded** -> escalate after 3 (loop counter enforces this)
+3. **ECONNREFUSED on daemon calls** -> early exit with clear error message
+4. **Keyword false positive** -> PR escalated as blocking when actually clean (false negative on merge, acceptable)
+5. **Merge conflict at merge time** -> `gh pr merge` fails, coordinator reports error and escalates
+
+## Critical Tests
+
+- `parseFindingsFromNotes(null)` -> returns err, classifies as 'unknown'
+- `parseFindingsFromNotes(markdown with 'not blocking but...')` -> must NOT return 'blocking'
+- Loop counter: 3 passes with persistent minor -> escalate on pass 3, NOT pass 4
+- ECONNREFUSED: spawnSession failure propagates cleanly to stderr and exit code 1
+
+## Verdict: Keep
+
+The design is sound. The 2-call HTTP extraction works for autonomous sessions. The two-tier parser with conservative defaults is sufficient. The 5 robustness rules need one adaptation: Rule 3 (go/no-go time check) should use wall-clock time since coordinator start, not daemon session remaining time.
+
+## Next Action
+
+Proceed with Candidate B implementation. Add adaptation to Rule 3: track coordinator wall-clock start time; refuse new spawns if `now() - startTime > (coordinatorMaxMs - 20*60*1000)`. Default coordinatorMaxMs = 90 minutes.

package/docs/discovery/simulation-report.md

@@ -0,0 +1,85 @@
+# Execution Simulation Report: PR Review Coordinator Failure Paths
+
+*Generated: 2026-04-18*
+
+## Summary
+
+Three failure paths simulated for the PR review coordinator design. All three produce correct outcomes under the proposed design. One gap identified: Rule 3 (go/no-go time check) needs adaptation for CLI context.
+
+## Scenario 1: recapMarkdown is Null
+
+**Setup:** Session completes successfully, but `GET /api/v2/sessions/:id/nodes/:nodeId` returns `recapMarkdown: null`.
+
+**Trace:**
+```
+getAgentResult('handle-419')
+  GET /api/v2/sessions/handle-419 -> runs[0].preferredTipNodeId = 'node-xyz'
+  GET /api/v2/sessions/handle-419/nodes/node-xyz -> recapMarkdown = null
+  returns null
+
+parseFindingsFromNotes(null) -> err('notes is null or empty')
+classifySeverity(err) -> 'unknown'
+route('unknown') -> escalate
+```
+
+**Divergence from expected:** None -- conservative escalation is the designed behavior.
+
+**Outcome:** PR escalated, not merged. No crash. Clear escalation note written.
+
+## Scenario 2: Fix-Agent Loop Exhaustion (3 Passes, Persistent Minor)
+
+**Setup:** PR #406 has minor findings. Fix agent runs 3 times but each re-review still returns minor.
+
+**Trace:**
+```
+Pass 1: passCount=0 -> review: 'minor' -> passCount becomes 1 -> spawn fix agent -> re-review
+Pass 2: passCount=1 -> review: 'minor' -> passCount becomes 2 -> spawn fix agent -> re-review
+Pass 3: passCount=2 -> review: 'minor' -> passCount becomes 3 -> CHECK: 3 >= 3 -> STOP
+  -> escalate, write: 'PR #406: 3 fix passes exhausted, still minor. Manual review required.'
+```
+
+**Divergence from expected:** None -- loop terminates correctly at pass 3.
+
+**Key invariant verified:** `passCount >= MAX_FIX_PASSES` check happens BEFORE spawning fix agent, not after. This prevents a 4th spawn.
+
+**Outcome:** PR escalated after exactly 3 passes. Not merged.
+
+## Scenario 3: Daemon Not Running (ECONNREFUSED)
+
+**Setup:** No daemon running on port 3456. No lock files present.
+
+**Trace:**
+```
+discoverPort() -> no lock files -> falls back to 3456
+spawnSession('mr-review-workflow-agentic', 'Review PR #419...', '/workspace')
+  POST http://127.0.0.1:3456/api/v2/auto/dispatch
+  -> fetch throws Error: ECONNREFUSED 127.0.0.1:3456
+  -> spawnSession catches -> returns err('Could not connect to WorkTrain daemon on port 3456')
+runPrReviewCoordinator() receives err
+  -> deps.stderr('Could not connect to WorkTrain daemon on port 3456. Start with: worktrain daemon')
+  -> returns { kind: 'failure', exitCode: 1 }
+```
+
+**Divergence from expected:** None.
+
+**Outcome:** Clear error message, exit code 1, no hang, no partial state.
+
+## Divergence Analysis
+
+No divergences found. All 3 scenarios produce correct outcomes.
+
+## Gap Identified: Rule 3 Adaptation for CLI Context
+
+**Problem:** The original Rule 3 (go/no-go time check: don't spawn if remaining time < 20 minutes) was written for daemon sessions that have a `maxSessionMinutes` parameter. A CLI coordinator script has no such parameter.
+
+**Adaptation required:** Track wall-clock time since coordinator script start (`const startTimeMs = deps.now()` at beginning). Before spawning any new child session (review OR fix agent), check: `if (deps.now() - startTimeMs > coordinatorMaxMs - 20 * 60 * 1000)` -> refuse to spawn.
+
+**Default:** `coordinatorMaxMs = 90 * 60 * 1000` (90 minutes). Configurable via `--max-runtime` flag if needed.
+
+## Recommendations
+
+1. Implement `parseFindingsFromNotes(null)` path explicitly -- don't rely on empty string check.
+2. Keyword parser priority: BLOCKING/CRITICAL/REQUEST CHANGES takes absolute precedence over APPROVE/CLEAN/LGTM (blocking wins even if both present).
+3. Fix-agent loop: check `passCount >= MAX_FIX_PASSES` BEFORE spawning, not after.
+4. Add `coordinatorStartMs` tracking and Rule 3 go/no-go check adapted for CLI (wall-clock elapsed time).
+5. `gh pr merge` failures: catch, write to stderr, escalate -- do NOT retry automatically.

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.38.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
     }
   ]