@exaudeus/workrail 3.40.0 → 3.41.0

package/dist/trigger/trigger-listener.d.ts

@@ -3,6 +3,7 @@ import express from 'express';
 import type { V2ToolContext } from '../mcp/types.js';
 import type { TriggerStoreError } from './trigger-store.js';
 import { TriggerRouter, type RunWorkflowFn } from './trigger-router.js';
+import type { SteerRegistry } from '../daemon/workflow-runner.js';
 import type { WorkspaceConfig } from './types.js';
 import type { DaemonEventEmitter } from '../daemon/daemon-events.js';
 import type { FetchFn } from './adapters/gitlab-poller.js';
@@ -17,6 +18,7 @@ export type TriggerListenerError = TriggerStoreError | {
 export interface TriggerListenerHandle {
     readonly port: number;
     readonly router: TriggerRouter;
+    readonly steerRegistry: SteerRegistry;
     stop(): Promise<void>;
 }
 export interface StartTriggerListenerOptions {

package/dist/trigger/trigger-listener.js

@@ -183,8 +183,9 @@ async function startTriggerListener(ctx, options) {
     const notificationService = (notifyMacOs || (notifyWebhook !== undefined && notifyWebhook !== ''))
         ? new notification_service_js_1.NotificationService({ macOs: notifyMacOs, webhookUrl: notifyWebhook })
         : undefined;
+    const steerRegistry = new Map();
     const runWorkflowFn = options.runWorkflowFn ?? workflow_runner_js_1.runWorkflow;
-    const router = new trigger_router_js_1.TriggerRouter(triggerIndex, ctx, apiKey, runWorkflowFn, undefined, maxConcurrentSessions, options.emitter, notificationService);
+    const router = new trigger_router_js_1.TriggerRouter(triggerIndex, ctx, apiKey, runWorkflowFn, undefined, maxConcurrentSessions, options.emitter, notificationService, steerRegistry);
     const app = createTriggerApp(router);
     const allTriggers = [...triggerIndex.values()];
     const polledEventStore = new polled_event_store_js_1.PolledEventStore(env);
@@ -219,6 +220,7 @@ async function startTriggerListener(ctx, options) {
             resolve({
                 port: actualPort,
                 router,
+                steerRegistry,
                 stop: async () => {
                     pollingScheduler.stop();
                     return new Promise((res, rej) => {

package/dist/trigger/trigger-router.d.ts

@@ -1,4 +1,4 @@
-import type { WorkflowTrigger, WorkflowRunResult } from '../daemon/workflow-runner.js';
+import type { WorkflowTrigger, WorkflowRunResult, SteerRegistry } from '../daemon/workflow-runner.js';
 import type { V2ToolContext } from '../mcp/types.js';
 import type { TriggerDefinition, WebhookEvent } from './types.js';
 import type { ExecFn } from './delivery-action.js';
@@ -20,7 +20,7 @@ export type RouteResult = {
     readonly _tag: 'error';
     readonly error: RouteError;
 };
-export type RunWorkflowFn = (trigger: WorkflowTrigger, ctx: V2ToolContext, apiKey: string, daemonRegistry?: import('../v2/infra/in-memory/daemon-registry/index.js').DaemonRegistry, emitter?: DaemonEventEmitter) => Promise<WorkflowRunResult>;
+export type RunWorkflowFn = (trigger: WorkflowTrigger, ctx: V2ToolContext, apiKey: string, daemonRegistry?: import('../v2/infra/in-memory/daemon-registry/index.js').DaemonRegistry, emitter?: DaemonEventEmitter, steerRegistry?: SteerRegistry) => Promise<WorkflowRunResult>;
 export declare function interpolateGoalTemplate(template: string, staticGoal: string, payload: Readonly<Record<string, unknown>>, triggerId: string): string;
 export declare class TriggerRouter {
     private readonly index;
@@ -33,7 +33,8 @@ export declare class TriggerRouter {
     private readonly _maxConcurrentSessions;
     private readonly emitter;
     private readonly notificationService;
-    constructor(index: ReadonlyMap<string, TriggerDefinition>, ctx: V2ToolContext, apiKey: string, runWorkflowFn: RunWorkflowFn, execFn?: ExecFn, maxConcurrentSessions?: number, emitter?: DaemonEventEmitter, notificationService?: NotificationService);
+    private readonly steerRegistry;
+    constructor(index: ReadonlyMap<string, TriggerDefinition>, ctx: V2ToolContext, apiKey: string, runWorkflowFn: RunWorkflowFn, execFn?: ExecFn, maxConcurrentSessions?: number, emitter?: DaemonEventEmitter, notificationService?: NotificationService, steerRegistry?: SteerRegistry);
     get activeSessions(): number;
     get maxConcurrentSessions(): number;
     route(event: WebhookEvent): RouteResult;

package/dist/trigger/trigger-router.js

@@ -183,7 +183,7 @@ class Semaphore {
 }
 const DEFAULT_MAX_CONCURRENT_SESSIONS = 3;
 class TriggerRouter {
-    constructor(index, ctx, apiKey, runWorkflowFn, execFn, maxConcurrentSessions, emitter, notificationService) {
+    constructor(index, ctx, apiKey, runWorkflowFn, execFn, maxConcurrentSessions, emitter, notificationService, steerRegistry) {
         this.index = index;
         this.ctx = ctx;
         this.apiKey = apiKey;
@@ -192,6 +192,7 @@ class TriggerRouter {
         this.execFn = execFn ?? execFileAsync;
         this.emitter = emitter;
         this.notificationService = notificationService;
+        this.steerRegistry = steerRegistry;
         const requested = maxConcurrentSessions ?? DEFAULT_MAX_CONCURRENT_SESSIONS;
         const cap = Number.isNaN(requested) ? DEFAULT_MAX_CONCURRENT_SESSIONS : requested;
         if (cap < 1) {
@@ -260,7 +261,7 @@ class TriggerRouter {
             await this.semaphore.acquire();
             let result;
             try {
-                result = await this.runWorkflowFn(workflowTrigger, this.ctx, this.apiKey, undefined, this.emitter);
+                result = await this.runWorkflowFn(workflowTrigger, this.ctx, this.apiKey, undefined, this.emitter, this.steerRegistry);
             }
             finally {
                 this.semaphore.release();
@@ -321,7 +322,7 @@ class TriggerRouter {
             await this.semaphore.acquire();
             let result;
             try {
-                result = await this.runWorkflowFn(workflowTrigger, this.ctx, this.apiKey, undefined, this.emitter);
+                result = await this.runWorkflowFn(workflowTrigger, this.ctx, this.apiKey, undefined, this.emitter, this.steerRegistry);
             }
             finally {
                 this.semaphore.release();

package/dist/trigger/trigger-store.js

@@ -426,7 +426,6 @@ function validateAndResolveTrigger(raw, env, workspaces = {}) {
     const requiredStringFields = [
         'provider',
         'workflowId',
-        'goal',
     ];
     for (const field of requiredStringFields) {
         const v = raw[field];
@@ -491,7 +490,21 @@ function validateAndResolveTrigger(raw, env, workspaces = {}) {
             return secretResult;
         hmacSecret = secretResult.value;
     }
-    const goalTemplate = raw.goalTemplate?.trim();
+    const LATE_BOUND_GOAL_SENTINEL = 'Autonomous task';
+    let resolvedGoal;
+    let resolvedGoalTemplate = raw.goalTemplate?.trim();
+    if (!raw.goal?.trim()) {
+        resolvedGoal = LATE_BOUND_GOAL_SENTINEL;
+        if (!resolvedGoalTemplate) {
+            resolvedGoalTemplate = '{{$.goal}}';
+            console.log(`[TriggerStore] Trigger "${rawId}" has no static goal or goalTemplate -- ` +
+                `defaulting to goalTemplate: "{{$.goal}}" (goal taken from webhook payload). ` +
+                `Fallback goal if payload has no goal field: "${LATE_BOUND_GOAL_SENTINEL}".`);
+        }
+    }
+    else {
+        resolvedGoal = raw.goal.trim();
+    }
     const referenceUrlsRaw = raw.referenceUrls?.trim();
     const referenceUrls = referenceUrlsRaw
         ? referenceUrlsRaw.split(/\s+/).filter(Boolean)
@@ -712,13 +725,13 @@ function validateAndResolveTrigger(raw, env, workspaces = {}) {
         provider,
         workflowId: raw.workflowId.trim(),
         workspacePath: resolvedWorkspacePath,
-        goal: raw.goal.trim(),
+        goal: resolvedGoal,
         concurrencyMode,
         ...(hmacSecret !== undefined ? { hmacSecret } : {}),
         ...(raw.contextMapping !== undefined
             ? { contextMapping: assembleContextMapping(raw.contextMapping) }
             : {}),
-        ...(goalTemplate ? { goalTemplate } : {}),
+        ...(resolvedGoalTemplate ? { goalTemplate: resolvedGoalTemplate } : {}),
         ...(referenceUrls !== undefined && referenceUrls.length > 0 ? { referenceUrls } : {}),
         ...(agentConfig !== undefined ? { agentConfig } : {}),
         ...(callbackUrl !== undefined ? { callbackUrl } : {}),

package/dist/v2/usecases/console-routes.d.ts

@@ -4,4 +4,5 @@ import type { WorkflowService } from '../../application/services/workflow-servic
 import type { ToolCallTimingRingBuffer } from '../../mcp/tool-call-timing.js';
 import type { TriggerRouter } from '../../trigger/trigger-router.js';
 import type { V2ToolContext } from '../../mcp/types.js';
-export declare function mountConsoleRoutes(app: Application, consoleService: ConsoleService, workflowService?: WorkflowService, timingRingBuffer?: ToolCallTimingRingBuffer, toolCallsPerfFile?: string, serverVersion?: string, v2ToolContext?: V2ToolContext, triggerRouter?: TriggerRouter): () => void;
+import type { SteerRegistry } from '../../daemon/workflow-runner.js';
+export declare function mountConsoleRoutes(app: Application, consoleService: ConsoleService, workflowService?: WorkflowService, timingRingBuffer?: ToolCallTimingRingBuffer, toolCallsPerfFile?: string, serverVersion?: string, v2ToolContext?: V2ToolContext, triggerRouter?: TriggerRouter, steerRegistry?: SteerRegistry): () => void;

package/dist/v2/usecases/console-routes.js

@@ -45,6 +45,7 @@ const worktree_service_js_1 = require("./worktree-service.js");
 const workflow_js_1 = require("../../types/workflow.js");
 const dev_mode_js_1 = require("../../mcp/dev-mode.js");
 const workflow_runner_js_1 = require("../../daemon/workflow-runner.js");
+const assert_never_js_1 = require("../../runtime/assert-never.js");
 const start_js_1 = require("../../mcp/handlers/v2-execution/start.js");
 const v2_token_ops_js_1 = require("../../mcp/handlers/v2-token-ops.js");
 function watchSessionsDir(sessionsDir, onChanged) {
@@ -90,7 +91,7 @@ function loadWorkflowTags() {
         return { version: 0, tags: [], workflows: {} };
     }
 }
-function mountConsoleRoutes(app, consoleService, workflowService, timingRingBuffer, toolCallsPerfFile, serverVersion, v2ToolContext, triggerRouter) {
+function mountConsoleRoutes(app, consoleService, workflowService, timingRingBuffer, toolCallsPerfFile, serverVersion, v2ToolContext, triggerRouter, steerRegistry) {
     const sseClients = new Set();
     let sseDebounceTimer = null;
     function broadcastChange() {
@@ -590,18 +591,21 @@ function mountConsoleRoutes(app, consoleService, workflowService, timingRingBuff
             triggerRouter.dispatch(trigger);
         }
         else {
-            void (0, workflow_runner_js_1.runWorkflow)(trigger, v2ToolContext, apiKey ?? '').then((result) => {
+            void (0, workflow_runner_js_1.runWorkflow)(trigger, v2ToolContext, apiKey ?? '', undefined, undefined, steerRegistry).then((result) => {
                 if (result._tag === 'success') {
                     console.log(`[ConsoleRoutes] Auto dispatch completed: workflowId=${workflowId} stopReason=${result.stopReason}`);
                 }
+                else if (result._tag === 'delivery_failed') {
+                    console.log(`[ConsoleRoutes] Auto dispatch delivery failed: workflowId=${workflowId}`);
+                }
                 else if (result._tag === 'timeout') {
                     console.log(`[ConsoleRoutes] Auto dispatch timed out: workflowId=${workflowId}`);
                 }
-                else if (result._tag === 'delivery_failed') {
-                    console.log(`[ConsoleRoutes] Auto dispatch delivery failed: workflowId=${workflowId}`);
+                else if (result._tag === 'error') {
+                    console.log(`[ConsoleRoutes] Auto dispatch failed: workflowId=${workflowId} error=${result.message}`);
                 }
                 else {
-                    console.log(`[ConsoleRoutes] Auto dispatch failed: workflowId=${workflowId} error=${result.message}`);
+                    (0, assert_never_js_1.assertNever)(result);
                 }
             });
         }
@@ -621,6 +625,26 @@ function mountConsoleRoutes(app, consoleService, workflowService, timingRingBuff
         }));
         res.json({ success: true, data: { triggers } });
     });
+    app.post('/api/v2/sessions/:sessionId/steer', express_1.default.json(), (req, res) => {
+        if (!steerRegistry) {
+            res.status(503).json({ success: false, error: 'Steer not available (not a daemon context).' });
+            return;
+        }
+        const { sessionId } = req.params;
+        const body = req.body;
+        const text = typeof body.text === 'string' ? body.text.trim() : '';
+        if (!text) {
+            res.status(400).json({ success: false, error: 'text is required and must be a non-empty string.' });
+            return;
+        }
+        const callback = steerRegistry.get(sessionId);
+        if (!callback) {
+            res.status(404).json({ success: false, error: 'Session not found or not a daemon session.' });
+            return;
+        }
+        callback(text);
+        res.json({ success: true });
+    });
     const consoleDist = resolveConsoleDist();
     if (consoleDist) {
         app.use('/console', express_1.default.static(consoleDist, {

package/dist/v2/usecases/console-service.js

@@ -585,6 +585,17 @@ function extractRepoRoot(events) {
     }
     return workspacePathFallback;
 }
+function extractParentSessionId(events) {
+    for (const e of events) {
+        if (e.kind === constants_js_1.EVENT_KIND.SESSION_CREATED) {
+            const parentId = e.data.parentSessionId;
+            if (typeof parentId === 'string' && parentId.length > 0)
+                return parentId;
+            return null;
+        }
+    }
+    return null;
+}
 function truncateTitle(text, maxLen = 120) {
     if (text.length <= maxLen)
         return text;
@@ -612,6 +623,7 @@ function projectSessionSummary(sessionId, truth, completionByRunId, workflowName
     const sessionTitle = sortedEventsRes.isOk() ? deriveSessionTitle(sortedEventsRes.value) : null;
     const gitBranch = extractGitBranch(events);
     const repoRoot = extractRepoRoot(events);
+    const parentSessionId = extractParentSessionId(events);
     const isAutonomous = (() => {
         if (!sortedEventsRes.isOk())
             return false;
@@ -643,6 +655,7 @@ function projectSessionSummary(sessionId, truth, completionByRunId, workflowName
             lastModifiedMs,
             isAutonomous,
             isLive,
+            parentSessionId,
         };
     }
     const workflow = run.workflow;
@@ -688,6 +701,7 @@ function projectSessionSummary(sessionId, truth, completionByRunId, workflowName
         lastModifiedMs,
         isAutonomous,
         isLive,
+        parentSessionId,
     };
 }
 function projectSessionDetail(sessionId, truth, completionByRunId, stepLabels, workflowNames, skippedStepsMap = {}) {

package/dist/v2/usecases/console-types.d.ts

@@ -20,6 +20,7 @@ export interface ConsoleSessionSummary {
     readonly lastModifiedMs: number;
     readonly isAutonomous: boolean;
     readonly isLive: boolean;
+    readonly parentSessionId: string | null;
 }
 export interface ConsoleSessionListResponse {
     readonly sessions: readonly ConsoleSessionSummary[];

package/docs/authoring.md

@@ -42,7 +42,7 @@ Canonical current rules for authoring good WorkRail workflows. workflow.schema.j
 **Source refs**
 - `spec/workflow.schema.json` (schema) — Legal structure and supported fields.
 - `src/application/services/validation-engine.ts` (runtime) — Validator-enforced authoring rules.
-- `workflows/coding-task-workflow-agentic.lean.v2.json` (example) — Current modern example.
+- `workflows/coding-task-workflow-agentic.json` (example) — Current modern example.
 
 ### validate-early-and-often
 - **Level**: required
@@ -141,7 +141,7 @@ Canonical current rules for authoring good WorkRail workflows. workflow.schema.j
 - Part A / Part B / Rules: ... when the structure adds ceremony rather than clarity
 
 **Example refs**
-- `workflows/coding-task-workflow-agentic.lean.v2.json` — See the sharpened user-voiced prompts in the current lean coding workflow.
+- `workflows/coding-task-workflow-agentic.json` — See the sharpened user-voiced prompts in the current lean coding workflow.
 
 ### protocol-footers-stay-explicit
 - **Level**: required
@@ -160,10 +160,10 @@ Canonical current rules for authoring good WorkRail workflows. workflow.schema.j
 - Replacing exact capture requirements with vague summary prose
 
 **Example refs**
-- `workflows/coding-task-workflow-agentic.lean.v2.json` — Uses compact Capture footers and explicit loop-control wording.
+- `workflows/coding-task-workflow-agentic.json` — Uses compact Capture footers and explicit loop-control wording.
 
 **Source refs**
-- `workflows/coding-task-workflow-agentic.lean.v2.json` (example) — Uses explicit capture footers and shape-preserving loop outputs.
+- `workflows/coding-task-workflow-agentic.json` (example) — Uses explicit capture footers and shape-preserving loop outputs.
 
 
 ## Prompt composition
@@ -185,11 +185,11 @@ Canonical current rules for authoring good WorkRail workflows. workflow.schema.j
 - Encoding runtime logic in prose when promptFragments or templates are the right mechanism
 
 **Example refs**
-- `workflows/coding-task-workflow-agentic.lean.v2.json` — Uses prompt fragments and context templates to keep prompts slimmer at render time.
+- `workflows/coding-task-workflow-agentic.json` — Uses prompt fragments and context templates to keep prompts slimmer at render time.
 
 **Source refs**
 - `docs/authoring.md` (documentation) — Documents context templates and prompt fragments.
-- `workflows/coding-task-workflow-agentic.lean.v2.json` (example) — Uses prompt fragments to slim mode-specific prompt branches.
+- `workflows/coding-task-workflow-agentic.json` (example) — Uses prompt fragments to slim mode-specific prompt branches.
 
 ### templates-are-for-simple-substitution
 - **Level**: recommended
@@ -405,11 +405,11 @@ Canonical current rules for authoring good WorkRail workflows. workflow.schema.j
 - Prompt text says to stop, but the example output only permits continue
 
 **Example refs**
-- `workflows/coding-task-workflow-agentic.lean.v2.json` — Current loop decision steps show shape-only output examples.
+- `workflows/coding-task-workflow-agentic.json` — Current loop decision steps show shape-only output examples.
 
 **Source refs**
 - `scripts/validate-workflows-registry.ts` (validator) — Registry validation should preserve semantically correct discoverable workflows.
-- `workflows/coding-task-workflow-agentic.lean.v2.json` (example) — Current loop decision prompts show shape-only output examples.
+- `workflows/coding-task-workflow-agentic.json` (example) — Current loop decision prompts show shape-only output examples.
 
 ### loops-need-real-exit-rules
 - **Level**: required
@@ -445,7 +445,7 @@ Canonical current rules for authoring good WorkRail workflows. workflow.schema.j
 - `contextAuditNeeded = true|false` without an explicit rubric
 
 **Example refs**
-- `workflows/coding-task-workflow-agentic.lean.v2.json` — Phase 0 uses a context-clarity rubric instead of a vibes-only confidence flag.
+- `workflows/coding-task-workflow-agentic.json` — Phase 0 uses a context-clarity rubric instead of a vibes-only confidence flag.
 
 
 ## Confirmation discipline
@@ -466,7 +466,7 @@ Canonical current rules for authoring good WorkRail workflows. workflow.schema.j
 - Using requireConfirmation as a substitute for clear loop or rigor policy
 
 **Source refs**
-- `workflows/coding-task-workflow-agentic.lean.v2.json` (example) — Uses confirmation for real review barriers like MultiPR checkpoints.
+- `workflows/coding-task-workflow-agentic.json` (example) — Uses confirmation for real review barriers like MultiPR checkpoints.
 
 
 ## Assessment gates
@@ -544,7 +544,7 @@ Canonical current rules for authoring good WorkRail workflows. workflow.schema.j
 - Treating named builder or researcher roles as alternate owners
 
 **Source refs**
-- `workflows/coding-task-workflow-agentic.lean.v2.json` (example) — Delegation checkpoints keep the main agent as the synthesizer and decision-maker.
+- `workflows/coding-task-workflow-agentic.json` (example) — Delegation checkpoints keep the main agent as the synthesizer and decision-maker.
 
 ### batched-checkpoints-over-ad-hoc-optionality
 - **Level**: recommended
@@ -563,7 +563,7 @@ Canonical current rules for authoring good WorkRail workflows. workflow.schema.j
 - Optional challenge wording at high-value decision points
 
 **Example refs**
-- `workflows/coding-task-workflow-agentic.lean.v2.json` — Uses explicit challenge, audit, and verification barriers.
+- `workflows/coding-task-workflow-agentic.json` — Uses explicit challenge, audit, and verification barriers.
 
 
 ## Subagent synthesis and claim adoption
@@ -601,10 +601,10 @@ Canonical current rules for authoring good WorkRail workflows. workflow.schema.j
 - Using delegated findings as blockers or green lights without verification
 
 **Example refs**
-- `workflows/coding-task-workflow-agentic.lean.v2.json` — Major synthesis checkpoints use Confirmed / Plausible / Rejected for decision-driving findings.
+- `workflows/coding-task-workflow-agentic.json` — Major synthesis checkpoints use Confirmed / Plausible / Rejected for decision-driving findings.
 
 **Source refs**
-- `workflows/coding-task-workflow-agentic.lean.v2.json` (example) — Major synthesis checkpoints use Confirmed / Plausible / Rejected for adopted claims.
+- `workflows/coding-task-workflow-agentic.json` (example) — Major synthesis checkpoints use Confirmed / Plausible / Rejected for adopted claims.
 
 
 ## Discouraged legacy patterns
@@ -670,7 +670,7 @@ Canonical current rules for authoring good WorkRail workflows. workflow.schema.j
 - Keeping a canonical example ref after the workflow has drifted into a legacy style
 
 **Example refs**
-- `workflows/coding-task-workflow-agentic.lean.v2.json` — Current example of modern prompt composition, delegation barriers, and loop semantics.
+- `workflows/coding-task-workflow-agentic.json` — Current example of modern prompt composition, delegation barriers, and loop semantics.
 
 
 ## Validation
@@ -728,7 +728,7 @@ Canonical current rules for authoring good WorkRail workflows. workflow.schema.j
 - Verification steps check one artifact while planning updates a different one
 
 **Example refs**
-- `workflows/coding-task-workflow-agentic.lean.v2.json` — Uses explicit spec vs implementation-plan ownership.
+- `workflows/coding-task-workflow-agentic.json` — Uses explicit spec vs implementation-plan ownership.
 
 
 ## Planned guidance

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