@exaudeus/workrail 3.40.0 → 3.42.0

package/docs/design/coordinator-message-queue-drain-plan.md

@@ -0,0 +1,241 @@
+# Implementation Plan: Coordinator Message Queue Drain
+
+## 1. Problem Statement
+
+`worktrain tell "<message>"` appends to `~/.workrail/message-queue.jsonl` but the PR review
+coordinator (`runPrReviewCoordinator`) never reads this file. Messages sent from a phone,
+terminal, or automation (e.g., "stop", "skip-pr 42") are silently ignored. The coordinator
+must drain this queue at the start of each cycle and act on actionable messages before spawning
+any agent.
+
+## 2. Acceptance Criteria
+
+AC1. When `stop` appears as the first meaningful word in a queued message (matched by
+     `/^\s*stop\b/i`), the coordinator exits cleanly without reviewing any PR, and appends an
+     outbox notification that includes the full triggering message text and timestamp.
+
+AC2. When `skip-pr N` appears in a queued message (matched by `/\bskip[- ]pr[\s#]+(\d+)/i`),
+     PR #N is removed from the list before Stage 1 review dispatch. An outbox notification is
+     appended confirming the skip.
+
+AC3. When `add-pr N` appears in a queued message (matched by `/\badd[- ]pr[\s#]+(\d+)/i`),
+     PR #N is added to the list (with Set dedup to prevent duplicates). An outbox notification
+     is appended confirming the addition.
+
+AC4. Messages that match no recognized pattern are skipped silently (treated as notes).
+
+AC5. After draining, the cursor in `~/.workrail/message-queue-cursor.json` is updated so
+     processed messages are not re-processed on the next coordinator invocation.
+
+AC6. If `~/.workrail/message-queue.jsonl` does not exist (ENOENT), the drain returns a no-op
+     result and the coordinator proceeds normally.
+
+AC7. Malformed JSONL lines (unparseable JSON) are skipped without crashing the coordinator.
+     A stderr warning is emitted for each skipped malformed line.
+
+AC8. All drain I/O (readFile, appendFile, homedir, joinPath, now, generateId) is injected via
+     `CoordinatorDeps`. No direct `fs` imports are added to `pr-review.ts`.
+
+AC9. Unit tests for `drainMessageQueue()` use fake deps (in-memory file map). No real filesystem
+     access in tests.
+
+## 3. Non-Goals
+
+- No `reprioritize` message kind in this PR
+- No workspace routing (workspaceHint matching) -- all messages are consumed regardless of hint
+- No structured `kind` field on `QueuedMessage` (Candidate C) -- that is a follow-up issue
+- No truncation or compaction of consumed messages (queue remains append-only)
+- No real-time / `--watch` mode
+- No multi-coordinator fan-out (single coordinator consumes the queue)
+- No integration test (unit tests with fakes are sufficient)
+
+## 4. Philosophy-Driven Constraints
+
+- Errors as data: `drainMessageQueue` returns `DrainResult`, never throws
+- All I/O injected: `CoordinatorDeps` gains `readFile` and `appendFile`; zero direct fs imports
+- Immutability: `DrainResult` and all new interfaces are fully readonly
+- Prefer fakes over mocks: tests use in-memory fake deps
+- Validate at boundaries: JSONL parsing, ENOENT, cursor desync handled at the read boundary
+- Document WHY: function header explains the cursor pattern and text-matching tradeoff
+
+## 5. Invariants
+
+I1. `message-queue.jsonl` is never written or truncated by the coordinator (append-only)
+I2. The coordinator drains the queue BEFORE Stage 1 (PR discovery) -- never mid-agent-run
+I3. `stop: true` in `DrainResult` takes absolute precedence; coordinator must check stop before
+    acting on `skipPrNumbers` or `addPrNumbers`
+I4. The cursor advances only AFTER successful outbox writes (best-effort; cursor write failure
+    does not block drain -- same pattern as worktrain-inbox.ts)
+I5. ENOENT on message-queue.jsonl = no messages = coordinator proceeds normally (not an error)
+I6. Cursor desync guard: if `cursor > totalLines`, reset to 0 (queue was wiped)
+
+## 6. Selected Approach & Rationale
+
+**Selected: Candidate B** -- `drainMessageQueue()` pure function with cursor + text parsing.
+
+**Rationale:** Direct adaptation of the `worktrain-inbox.ts` cursor pattern (already tested, same
+`InboxCursor` shape `{ lastReadCount: number }`). Additive to `CoordinatorDeps`. Text parsing is
+narrow (`^\\s*stop\\b`) and consistent with how `parseFindingsFromNotes()` works in the same file.
+
+**Runner-up: Candidate C** (structured `kind` field on `QueuedMessage`). Loses because it
+requires a schema change to the public CLI interface (`worktrain tell`), which is out of scope.
+Filed as a follow-up.
+
+## 7. Vertical Slices
+
+### Slice 1: Extend `CoordinatorDeps` and add `DrainResult` type
+
+**Files:** `src/coordinators/pr-review.ts`
+
+**Work:**
+- Add `readFile: (path: string) => Promise<string>` to `CoordinatorDeps`
+- Add `appendFile: (path: string, content: string) => Promise<void>` to `CoordinatorDeps`
+- Add `mkdir: (path: string, options: { recursive: boolean }) => Promise<string | undefined>` to `CoordinatorDeps`
+- Define `DrainResult` interface (readonly: stop, stopReason, skipPrNumbers, addPrNumbers, messagesProcessed)
+
+**Done when:** TypeScript compiles with new interface fields. No runtime behavior change yet.
+
+**Note:** Updating fake deps in `coordinator-pr-review.test.ts` is part of this slice (compile-
+time requirement).
+
+---
+
+### Slice 2: Implement `drainMessageQueue()`
+
+**Files:** `src/coordinators/pr-review.ts`
+
+**Work:**
+- New exported function `drainMessageQueue(deps, workrailDir)` -- deps is the coordinator deps
+  subset; workrailDir defaults to `deps.joinPath(deps.homedir(), '.workrail')`
+- Reads `message-queue.jsonl` (ENOENT -> return empty result)
+- Reads cursor from `message-queue-cursor.json` (missing/corrupt -> 0)
+- Applies cursor desync guard (cursor > totalLines -> reset to 0)
+- Parses new lines (slice from cursor), skips malformed with stderr warning
+- For each parsed `QueuedMessage`:
+  - `^\\s*stop\\b/i` match -> set stop=true, record stopReason=message.message
+  - `/\\bskip[- ]pr[\\s#]+([0-9]+)/i` match -> add to skipSet
+  - `/\\badd[- ]pr[\\s#]+([0-9]+)/i` match -> add to addSet
+  - Otherwise: skip (informational note)
+- After processing all new messages:
+  - For each actionable message: appendFile to outbox.jsonl with confirmation text
+  - Append stderr `[INFO coord:drain kind=... message="..." ts=...]` per actionable message
+  - Update cursor file (non-fatal on failure)
+- Return `DrainResult`
+
+**Done when:** Function exists, TypeScript compiles, unit tests pass.
+
+---
+
+### Slice 3: Integrate drain into `runPrReviewCoordinator()`
+
+**Files:** `src/coordinators/pr-review.ts`
+
+**Work:**
+- Call `drainMessageQueue(deps)` at the top of `runPrReviewCoordinator()` (before Stage 1 log)
+- Check `drainResult.stop` immediately:
+  - If true: log stop reason, write report (empty/aborted), return early with all zeros
+- Apply `drainResult.skipPrNumbers` to remove PRs from the discovered list (after Stage 1)
+- Apply `drainResult.addPrNumbers` to add PRs to the list (with Set dedup, before Stage 1)
+- Log drain activity: `[drain] processed N messages, skip=[...], add=[...]` if messagesProcessed > 0
+
+**Done when:** Integration passes existing coordinator unit tests + new drain integration test.
+
+---
+
+### Slice 4: Wire new deps in `cli-worktrain.ts`
+
+**Files:** `src/cli-worktrain.ts`
+
+**Work:**
+- Add `readFile: (p: string) => fs.promises.readFile(p, 'utf-8')` to CoordinatorDeps wiring
+- Add `appendFile: (p: string, content: string) => fs.promises.appendFile(p, content, 'utf-8')`
+  to CoordinatorDeps wiring
+- Add `mkdir: (p: string, opts: { recursive: boolean }) => fs.promises.mkdir(p, opts)` to
+  CoordinatorDeps wiring
+
+**Done when:** `worktrain run pr-review --dry-run` compiles and runs without error.
+
+---
+
+### Slice 5: Unit tests for `drainMessageQueue()`
+
+**Files:** `tests/unit/coordinator-pr-review.test.ts`
+
+**Work:**
+- Add `readFile` and `appendFile` to the existing fake CoordinatorDeps helper
+- New `describe('drainMessageQueue')` block covering:
+  - ENOENT -> returns empty DrainResult (messagesProcessed=0, stop=false)
+  - Stop message at start of message text -> stop=true, stopReason set
+  - Stop NOT triggered when 'stop' appears mid-sentence ("please stop overthinking" -- note: this
+    still fires with `^\\s*stop` since it doesn't start the message; test confirms this is the
+    designed behavior)
+  - skip-pr with PR number -> skipPrNumbers contains the number
+  - add-pr with PR number -> addPrNumbers contains the number
+  - Malformed JSONL lines skipped, messagesProcessed counts only valid lines
+  - Cursor advances after drain
+  - Cursor desync guard resets to 0 when cursor > totalLines
+  - Multiple messages: stop takes precedence regardless of order in queue
+  - Note-only messages: no action, cursor advances, messagesProcessed = N
+
+**Done when:** All new tests pass; no existing tests broken.
+
+## 8. Test Design
+
+**Strategy:** Fake deps only (in-memory Map for files, Set for dirs). No real filesystem.
+
+**Key test helpers:**
+```ts
+interface FakeDrainFs {
+  files: Map<string, string>;
+}
+
+function makeDrainDeps(fs: FakeDrainFs): Pick<CoordinatorDeps, 'readFile' | 'appendFile' | 'mkdir' | 'homedir' | 'joinPath' | 'now' | 'generateId' | 'stderr'>
+```
+
+**Critical test cases:**
+- `stop` as sole message: stop=true, outbox has triggering text
+- `skip-pr 42` after a note: skipPrNumbers=[42], messagesProcessed=2
+- Two `skip-pr` for same PR: deduplicated in Set (skipPrNumbers=[42] not [42, 42])
+- Cursor = 5, file has 5 lines: messagesProcessed=0 (all previously read)
+- Cursor = 10, file has 5 lines: cursor reset to 0, all 5 processed
+
+## 9. Risk Register
+
+| Risk | Likelihood | Impact | Mitigation |
+|---|---|---|---|
+| `stop` false positive on note message | Low | Medium | `^\\s*stop\\b` anchor; outbox shows triggering text |
+| Cursor file write failure | Very Low | Low | Non-fatal; next run re-reads from 0 (desync reset) |
+| Outbox write failure during stop | Very Low | Low | Non-fatal; stderr log is backup |
+| `readFile`/`appendFile` not wired in cli-worktrain.ts | Low | High | Slice 4 is explicit; TypeScript will catch missing fields at compile time |
+
+## 10. PR Packaging Strategy
+
+Single PR on branch `feat/coordinator-message-queue`. All 5 slices in one PR -- they are
+tightly coupled (type change -> function -> integration -> wiring -> tests). Separating them
+would create a non-compiling intermediate state.
+
+## 11. Philosophy Alignment Per Slice
+
+| Slice | Principle | Status |
+|---|---|---|
+| 1 | Immutability by default | Satisfied -- all new fields are readonly |
+| 1 | Explicit domain types | Tension -- DrainResult uses boolean stop not a discriminated union; documented |
+| 2 | Errors are data | Satisfied -- DrainResult is a value; ENOENT returns empty result |
+| 2 | Dependency injection | Satisfied -- all I/O via injected deps |
+| 2 | Validate at boundaries | Satisfied -- malformed JSONL skipped at parse boundary |
+| 3 | Determinism over cleverness | Satisfied -- same queue + cursor = same result |
+| 4 | Compose with small pure functions | Satisfied -- drainMessageQueue is pure at logic level |
+| 5 | Prefer fakes over mocks | Satisfied -- fake deps, no vi.mock() |
+
+## 12. Follow-Up Tickets
+
+1. **Add `kind` field to `QueuedMessage` for structured dispatch** (Candidate C) -- unblocks
+   automated tooling writing to the message queue without text fragility.
+2. **`worktrain tell --help` should list recognized coordinator command patterns** -- discovery
+   for users who don't know what command words the coordinator recognizes.
+
+## Summary
+
+- `estimatedPRCount`: 1
+- `unresolvedUnknownCount`: 0
+- `planConfidenceBand`: High

package/docs/design/coordinator-message-queue-drain-review.md

@@ -0,0 +1,120 @@
+# Design Review Findings: Coordinator Message Queue Drain
+
+**Design reviewed:** Candidate B from `coordinator-message-queue-drain.md`
+(drainMessageQueue with cursor + text parsing)
+
+---
+
+## Tradeoff Review
+
+### T1: Stringly-typed dispatch (free-form text parsing)
+
+Accepted tradeoff. The `^\\s*stop\\b/i` anchor pattern is narrower than bare `stop` matching
+and covers realistic CLI usage. The risk of false-positive halt is real but diagnosable -- the
+outbox notification includes the triggering message text. Condition for no longer acceptable:
+automated tooling writing to the queue. Explicitly documented as a pivot trigger for Candidate C.
+
+### T2: New cursor file on disk
+
+Fully acceptable. Same format as `InboxCursor`; desync guard handles truncation; write failure
+is non-fatal. No new schema maintenance burden.
+
+### T3: Outbox notifications for all actionable messages
+
+Fully acceptable. Outbox write failure is non-fatal; stderr provides a backup diagnostic.
+Including notifications for all actions (not just `stop`) is the right call -- users need the
+feedback loop.
+
+---
+
+## Failure Mode Review
+
+| FM | Description | Mitigation | Residual risk |
+|---|---|---|---|
+| FM1 | `stop` fires on note message | `^\\s*stop\\b` anchor; outbox shows triggering text | Low -- diagnosable and recoverable |
+| FM2 | Cursor desync after queue wipe | Reset to 0 if cursor > totalLines | Low -- re-triggers past stop if present; outbox makes it visible |
+| FM3 | Duplicate add-pr | Set dedup before Stage 1 | None |
+| FM4 | Outbox write failure during stop | Non-fatal; stderr fallback | None -- stop still honored |
+| FM5 | ENOENT (no queue file) | Return empty DrainResult | None -- expected on fresh install |
+
+**Highest-risk failure mode:** FM1. Must include triggering message text and timestamp in the
+outbox notification and stderr log -- this is a required implementation detail, not optional.
+
+---
+
+## Runner-Up / Simpler Alternative Review
+
+**Candidate C strengths borrowed:** Structured parse result logged to stderr (`[INFO drain:kind=stop
+message=...]`) -- same diagnostic value as a `kind` field at zero schema cost.
+
+**Simpler variant (skip outbox notifications):** Rejected -- silent halt is a UX regression.
+
+**Simpler variant (skip `add-pr`):** Viable as a scope reduction. Included in this PR because the
+implementation cost is ~10 lines, and `skip-pr` without `add-pr` is asymmetric.
+
+---
+
+## Philosophy Alignment
+
+**Clearly satisfied:** Immutability, errors as values, DI, validate at boundaries, determinism,
+fakes over mocks, small pure functions, document WHY.
+
+**Under tension:**
+- "Explicit domain types over primitives" -- free-form text dispatch. Acceptable: pre-existing
+  schema constraint, documented as follow-up.
+- "Make illegal states unrepresentable" -- `DrainResult` can represent `stop: true` with
+  non-empty `skipPrNumbers`. Acceptable: `stop` check is first at call site; documented.
+
+---
+
+## Findings
+
+### YELLOW: `stop` regex false-positive on note messages
+
+The `^\\s*stop\\b/i` pattern is significantly better than bare `stop` matching, but it will still
+fire on a message like "stop and think about this before merging." No additional regex constraint
+is practical without excluding valid stop forms. The mitigation (outbox + stderr with triggering
+message text) is the correct and sufficient response.
+
+**Recommended revision:** None to the pattern itself. Ensure the outbox notification reads:
+`WorkTrain coordinator stopped by queued message: "[full message text]" (queued at [timestamp])`
+rather than a generic "coordinator stopped" message.
+
+### YELLOW: `DrainResult` allows `stop: true` + non-empty `skipPrNumbers`
+
+The call site must check `stop` before anything else. If a future maintainer adds code between
+the drain call and the `stop` check, or moves the check, the skip/add arrays could be acted on
+before the stop is honored.
+
+**Recommended revision:** Add a JSDoc invariant on `DrainResult`: "When `stop` is true, all
+other fields are informational only. The coordinator MUST honor `stop` before inspecting
+`skipPrNumbers` or `addPrNumbers`." Also add a comment at the call site.
+
+### YELLOW (minor): No structured parse log to stderr
+
+Without logging which pattern matched and for which message, diagnosing unexpected behavior
+requires reading the outbox. A one-line stderr log per actionable message helps during
+development and debugging.
+
+**Recommended revision:** For each actionable message (stop, skip-pr, add-pr), emit:
+`[INFO coord:drain kind=stop handle=... message="..." ts=...]` to `deps.stderr`.
+
+---
+
+## Recommended Revisions (summary)
+
+1. Outbox notification for `stop` must include the full triggering message text and timestamp.
+2. Add JSDoc invariant on `DrainResult` documenting that `stop: true` takes absolute precedence.
+3. Add a `[INFO coord:drain]` stderr log line for each actionable message (diagnostics).
+
+None of these revisions change the architecture. All are implementation-level details.
+
+---
+
+## Residual Concerns
+
+1. **Schema follow-up not filed yet.** A GitHub issue or backlog entry for adding a `kind`
+   field to `QueuedMessage` (Candidate C path) should be created as part of this PR.
+2. **No integration test.** Unit tests with fake deps are sufficient for the drain logic, but
+   an end-to-end test (write to real queue file, run coordinator, verify outbox) is not planned.
+   This is acceptable for a developer CLI tool.

package/docs/design/coordinator-message-queue-drain.md

@@ -0,0 +1,289 @@
+# Design Candidates: Coordinator Message Queue Drain
+
+**Task:** The PR review coordinator never reads `~/.workrail/message-queue.jsonl`, so
+messages queued via `worktrain tell` (from phone, terminal, or automation) are silently ignored.
+This document captures the design investigation for draining that queue inside the coordinator.
+
+---
+
+## Problem Understanding
+
+### Core tensions
+
+1. **Append-only invariant vs. consumed-message tracking.** The queue file must never be
+   truncated or rewritten -- the `worktrain-tell` command's documented invariant. But without
+   tracking which messages were processed, the coordinator re-processes the entire history on
+   every invocation. A cursor file (same pattern as `inbox-cursor.json`) resolves this cleanly
+   but adds a second file to manage.
+
+2. **Stringly-typed messages vs. explicit domain types.** `QueuedMessage.message` is free-form
+   text. The repo philosophy demands explicit domain types, but no `kind` field exists in the
+   current schema. Text parsing at the coordinator's read boundary is the only option within
+   the current schema -- it is not a patch, it is adapting to a pre-existing constraint.
+
+3. **Coordinator statefulness vs. single-pass design.** The coordinator is invoked once per run
+   today, not as a persistent loop. A cursor handles both cases correctly: repeat invocations
+   see only new messages; a one-time invocation drains everything queued since last run.
+
+4. **`stop` signal semantics vs. partial progress.** A `stop` in the queue must halt before any
+   spawn. But `stop` might appear alongside `skip-pr 42` in the same drain batch. `stop` takes
+   absolute precedence -- no partial processing, coordinator exits cleanly and writes an outbox
+   acknowledgment.
+
+### Likely seam
+
+The real seam is the top of `runPrReviewCoordinator()`, immediately before Stage 1 (PR discovery).
+This matches the backlog intent: "coordinator loop checks message-queue at the start of each cycle
+before spawning new agents." The coordinator is the right owner, not a shared utility, because
+message routing is coordinator-specific logic.
+
+### What makes this hard
+
+Not technically difficult. The risks are:
+- Forgetting to handle ENOENT (queue file doesn't exist yet = no messages, not a crash)
+- Cursor desync: if the queue is wiped, cursor > total lines; reset to 0 (same guard as `inbox-cursor.json`)
+- Text matching fragility: `stop` in "stop overthinking this" triggers coordinator halt
+
+---
+
+## Philosophy Constraints
+
+From `CLAUDE.md` and observed repo patterns:
+
+- **Errors are values, never thrown** -- `pr-review.ts` uses `Result<T, string>` throughout.
+  The drain result uses a plain `DrainResult` struct (stop is not an error, it is a valid outcome).
+- **All I/O injected via deps** -- new `drainMessageQueue()` must accept deps, not import `fs`.
+- **Immutability by default** -- all interface fields are `readonly`.
+- **Prefer fakes over mocks** -- tests use in-memory fake deps, no `vi.mock()`.
+- **Validate at boundaries, trust inside** -- malformed JSONL lines are skipped at the parse
+  boundary; core routing logic trusts parsed data.
+- **Document WHY, not WHAT** -- comments explain rationale, not mechanics.
+
+**Conflict:** "Explicit domain types over primitives" is under pressure from the free-form message
+text. The mitigation is narrow keyword patterns and clear documentation. This conflict is not
+resolved in this PR -- a `kind` field on `QueuedMessage` is the proper fix but changes the
+public CLI interface (out of scope here).
+
+---
+
+## Impact Surface
+
+Changes that must stay consistent if this design is implemented:
+
+- **`CoordinatorDeps` interface** in `src/coordinators/pr-review.ts`: gains `readFile` and
+  `appendFile`. These are additive -- no existing caller is broken.
+- **`cli-worktrain.ts` pr-review action**: must wire `readFile` and `appendFile` into the deps
+  object (two new lines in the composition root).
+- **`tests/unit/coordinator-pr-review.test.ts`**: every fake `CoordinatorDeps` object needs the
+  two new fields. Mechanical but must not be missed.
+- **`discoverConsolePort` deps** (mini-subset type): no change needed; it already has `readFile`.
+
+New files introduced on disk (runtime, not source):
+- `~/.workrail/message-queue-cursor.json` -- created on first coordinator run after this ships.
+
+---
+
+## Candidates
+
+### Candidate A -- Minimal: full-history drain, no cursor, timestamp filter
+
+**Summary:** On each coordinator run, read all messages in `message-queue.jsonl`, discard messages
+older than the coordinator's start time, act on the remainder.
+
+**Tensions resolved:** Simplest change; no new cursor file.
+
+**Tensions accepted:** Stale messages re-processed if clock skew or same-second invocations.
+A `stop` message from two days ago can halt a coordinator run today if the clock check is ambiguous.
+
+**Boundary:** Inline in `runPrReviewCoordinator()`, no new function or file.
+
+**Why this boundary is wrong:** The timestamp filter is not reliable enough. Same-second writes,
+NTP jumps, or leap-second events can cause a current `stop` to be discarded or a stale `stop` to
+fire. The cursor is strictly more correct.
+
+**Failure mode:** Stale `stop` from a previous session kills today's coordinator run. No recovery
+path -- the coordinator just exits. Users have to manually inspect the queue to understand why.
+
+**Repo-pattern relationship:** Departs -- `worktrain-inbox.ts` uses a cursor precisely to avoid
+the re-processing problem. This candidate ignores the established pattern.
+
+**Gains:** Zero new files.
+
+**Gives up:** Correctness. Behavior depends on queue history, not just current inputs -- violates
+"determinism over cleverness."
+
+**Scope judgment:** Too narrow -- solves the immediate symptom but breaks on any real usage.
+
+**Philosophy fit:** Conflicts with "determinism over cleverness." Does not honor "validate at
+boundaries" (stale messages leak through).
+
+**Verdict: Rejected.** Stale message re-processing is a correctness bug, not a tradeoff.
+
+---
+
+### Candidate B -- Best-fit: `drainMessageQueue()` with cursor, narrow text parsing
+
+**Summary:** Add a pure function `drainMessageQueue(deps, opts)` to `src/coordinators/pr-review.ts`.
+It reads new lines since `~/.workrail/message-queue-cursor.json`, parses message text for `stop` /
+`skip-pr N` / `add-pr N` using narrow regex patterns, writes outbox acknowledgments for actionable
+messages, advances the cursor. Called at the top of `runPrReviewCoordinator()` before Stage 1.
+
+**Tensions resolved:**
+- Append-only invariant respected (cursor tracks progress, queue file never modified)
+- Stale message re-processing eliminated by cursor
+- ENOENT handled (no queue = empty drain result = coordinator proceeds normally)
+- `stop` takes absolute precedence
+
+**Tensions accepted:**
+- Text parsing is not type-safe; fragile to natural language variation
+
+**Boundary solved at:** New exported function in `src/coordinators/pr-review.ts`.
+
+**Why this boundary is best-fit:** Message routing is coordinator-specific. The drain reads a
+coordinator-managed cursor file and writes outbox notifications -- both are coordinator
+responsibilities. Extracting to a shared utility would create coupling without benefit (no other
+coordinator exists today).
+
+**Key data structures:**
+
+```ts
+export interface DrainResult {
+  readonly stop: boolean;
+  readonly stopReason: string | null;
+  readonly skipPrNumbers: readonly number[];
+  readonly addPrNumbers: readonly number[];
+  readonly messagesProcessed: number;
+}
+```
+
+Cursor shape: `{ lastReadCount: number }` -- identical to `InboxCursor` in `worktrain-inbox.ts`.
+
+New `CoordinatorDeps` fields:
+```ts
+readonly readFile: (path: string) => Promise<string>;
+readonly appendFile: (path: string, content: string) => Promise<void>;
+```
+
+Parsing patterns:
+- stop: `/\bstop\b/i`
+- skip-pr: `/\bskip[- ]pr[\s#]+([0-9]+)/i`
+- add-pr: `/\badd[- ]pr[\s#]+([0-9]+)/i`
+
+**Failure mode:** A note message like "stop overthinking this" triggers coordinator halt. Mitigation:
+word-boundary requirement limits false positives; documented as known behavior with workaround
+("add-pr" or "note:" prefix for non-command messages).
+
+**Repo-pattern relationship:** Follows `worktrain-inbox.ts` cursor pattern exactly; follows
+`CoordinatorDeps` injection pattern exactly.
+
+**Gains:** Correct deduplication; clean separation; fully testable with fakes.
+
+**Gives up:** Type-safe dispatch. A `kind` field would be cleaner.
+
+**Impact surface:** `CoordinatorDeps` (additive), `cli-worktrain.ts` (2 new dep wires),
+`coordinator-pr-review.test.ts` (2 new fake dep fields).
+
+**Scope judgment:** Best-fit.
+
+**Philosophy fit:** Honors immutability (readonly result), DI for boundaries, errors as values,
+validate at boundaries. Partial conflict with "explicit domain types" (documented and accepted).
+
+**Verdict: Recommended.**
+
+---
+
+### Candidate C -- Broader: structured `kind` field on `QueuedMessage`
+
+**Summary:** Extend `QueuedMessage` with `readonly kind?: 'stop' | 'skip-pr' | 'add-pr' | 'note'`
+and `readonly payload?: Record<string, unknown>`. Update `worktrain-tell.ts` to accept `--kind`
+flag. Coordinator drains on `kind` field instead of text parsing.
+
+**Tensions resolved:** Eliminates the stringly-typed tension entirely. Discriminated union on
+`kind` makes routing exhaustive and type-safe.
+
+**Tensions accepted:** Schema change affects the public CLI interface. Existing `tell` invocations
+omitting `--kind` fall back to `kind: 'note'` (safe), but natural language commands no longer work
+(`worktrain tell "stop"` becomes a note, not a stop signal).
+
+**Boundary solved at:** `QueuedMessage` type in `worktrain-tell.ts` + coordinator drain in
+`pr-review.ts` + CLI parser in `cli-worktrain.ts`.
+
+**Why this boundary is too broad:** Adds `kind` to `QueuedMessage` -- a public interface change.
+The `tell` command is documented as accepting any free-form text. Adding a required semantic field
+is a separate design decision that should be preceded by discussion of the CLI UX.
+
+**Failure mode:** Users who currently type `worktrain tell "stop the agent"` find it ignored
+unless they learn to use `--kind stop`. The ergonomic regression is silent.
+
+**Repo-pattern relationship:** Honors "explicit domain types" and "make illegal states
+unrepresentable" from philosophy. Departs from current free-form-text CLI design.
+
+**Gains:** Type-safe dispatch, no regex fragility, forward-compatible for new action kinds.
+
+**Gives up:** Natural language ergonomics; requires more CLI plumbing.
+
+**Scope judgment:** Too broad for this task.
+
+**Philosophy fit:** Strongly honors explicit domain types, discriminated unions, exhaustiveness.
+Conflicts with YAGNI -- adds schema complexity before the feature is proven.
+
+**Verdict: Out of scope for this PR. File a follow-up issue.**
+
+---
+
+## Comparison and Recommendation
+
+| | A (timestamp) | B (cursor + text) | C (structured kind) |
+|---|---|---|---|
+| Stale message safety | Weak | Strong | Strong |
+| Schema change | No | No | Yes |
+| Scope fit | Too narrow | Best-fit | Too broad |
+| Testability | Full | Full | Full |
+| Text-parse fragility | Avoided (no parse) | Narrow regexes | Eliminated |
+| Repo-pattern alignment | Poor | Exact | Partial |
+| Philosophy fit | Weak | Good (with caveat) | Strong |
+
+**Recommendation: Candidate B.**
+
+Candidate A fails on correctness. Candidate C solves the right problem but changes the wrong
+boundary for this task. Candidate B is a direct adaptation of the existing `worktrain-inbox.ts`
+cursor pattern to the coordinator context -- it introduces no new architectural ideas, just
+applies the established approach.
+
+---
+
+## Self-Critique
+
+**Strongest argument against Candidate B:**
+
+The text-matching approach creates an implicit, undiscoverable API. Users sending messages from
+phones have no way to know that `stop` means stop but `halt` does not. There is no help text,
+no validation, no error message for unrecognized commands. This is a real UX problem.
+
+**What would tip the decision toward Candidate C:**
+
+Evidence that multiple clients (mobile app, automation scripts) need to send structured commands.
+At that point, the text-parsing approach becomes a reliability liability. The right test: if
+a second coordinator (e.g., a work-queue coordinator) also needs to consume the message queue,
+Candidate C's structured dispatch becomes clearly necessary.
+
+**Invalidating assumption:**
+
+Candidate B assumes the word-boundary `stop` regex is specific enough. If users commonly type
+messages like "stop worrying and trust the process" via phone, the stop regex will fire. Mitigation:
+require the stop keyword to appear as the first meaningful token in the message, or require a
+command prefix (e.g., `/stop`). This can be tightened without changing the architecture.
+
+---
+
+## Open Questions for the Main Agent
+
+1. Should the drain function write an outbox notification for every actionable message, or only
+   for `stop` (where the coordinator is halting and the user needs confirmation)? Suggested:
+   write for all actionable messages (stop, skip-pr, add-pr) to close the feedback loop.
+
+2. The `stop` signal exits cleanly -- should the coordinator report which messages caused the
+   stop in its final report? Suggested: yes, log the message text and timestamp in the run log.
+
+3. Should `add-pr` messages add new PRs to the list before or after deduplication? Suggested:
+   add them to `prs` before Stage 1 begins, guarding against duplicates with a Set.