@exaudeus/workrail 3.39.0 → 3.41.0

package/dist/v2/durable-core/schemas/session/outputs.d.ts

@@ -90,8 +90,6 @@ export declare const NodeOutputAppendedDataV1Schema: z.ZodEffects<z.ZodObject<{
         content?: unknown;
     }>]>;
 }, "strip", z.ZodTypeAny, {
-    outputId: string;
-    outputChannel: "recap" | "artifact";
     payload: {
         payloadKind: "notes";
         notesMarkdown: string;
@@ -102,10 +100,10 @@ export declare const NodeOutputAppendedDataV1Schema: z.ZodEffects<z.ZodObject<{
         byteLength: number;
         content?: unknown;
     };
-    supersedesOutputId?: string | undefined;
-}, {
     outputId: string;
     outputChannel: "recap" | "artifact";
+    supersedesOutputId?: string | undefined;
+}, {
     payload: {
         payloadKind: "notes";
         notesMarkdown: string;
@@ -116,10 +114,10 @@ export declare const NodeOutputAppendedDataV1Schema: z.ZodEffects<z.ZodObject<{
         byteLength: number;
         content?: unknown;
     };
-    supersedesOutputId?: string | undefined;
-}>, {
     outputId: string;
     outputChannel: "recap" | "artifact";
+    supersedesOutputId?: string | undefined;
+}>, {
     payload: {
         payloadKind: "notes";
         notesMarkdown: string;
@@ -130,10 +128,10 @@ export declare const NodeOutputAppendedDataV1Schema: z.ZodEffects<z.ZodObject<{
         byteLength: number;
         content?: unknown;
     };
-    supersedesOutputId?: string | undefined;
-}, {
     outputId: string;
     outputChannel: "recap" | "artifact";
+    supersedesOutputId?: string | undefined;
+}, {
     payload: {
         payloadKind: "notes";
         notesMarkdown: string;
@@ -144,5 +142,7 @@ export declare const NodeOutputAppendedDataV1Schema: z.ZodEffects<z.ZodObject<{
         byteLength: number;
         content?: unknown;
     };
+    outputId: string;
+    outputChannel: "recap" | "artifact";
     supersedesOutputId?: string | undefined;
 }>;

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

@@ -40,10 +40,12 @@ exports.mountConsoleRoutes = mountConsoleRoutes;
 const express_1 = __importDefault(require("express"));
 const path_1 = __importDefault(require("path"));
 const fs_1 = __importDefault(require("fs"));
+const os_1 = __importDefault(require("os"));
 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) {
@@ -89,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() {
@@ -135,6 +137,183 @@ function mountConsoleRoutes(app, consoleService, workflowService, timingRingBuff
         req.on('close', () => { sseClients.delete(res); });
         res.on('close', () => { sseClients.delete(res); });
     });
+    const daemonEventsDir = path_1.default.join(process.env['HOME'] ?? os_1.default.homedir(), '.workrail', 'events', 'daemon');
+    async function tailDaemonEvents(filePath, prevSize) {
+        try {
+            const stat = await fs_1.default.promises.stat(filePath);
+            if (stat.size <= prevSize)
+                return [];
+            const fd = await fs_1.default.promises.open(filePath, 'r');
+            const length = stat.size - prevSize;
+            const buf = Buffer.alloc(length);
+            try {
+                await fd.read(buf, 0, length, prevSize);
+            }
+            finally {
+                await fd.close();
+            }
+            const chunk = buf.toString('utf8');
+            return chunk
+                .split('\n')
+                .filter(Boolean)
+                .flatMap((line) => {
+                try {
+                    return [JSON.parse(line)];
+                }
+                catch {
+                    return [];
+                }
+            });
+        }
+        catch {
+            return [];
+        }
+    }
+    const SESSION_SSE_EVENT_KINDS = new Set([
+        'tool_called',
+        'tool_call_started',
+        'tool_call_completed',
+        'tool_call_failed',
+        'tool_error',
+        'step_advanced',
+        'session_completed',
+        'issue_reported',
+        'agent_stuck',
+        'llm_turn_started',
+        'llm_turn_completed',
+        'signal_emitted',
+    ]);
+    app.get('/api/v2/sessions/:sessionId/events', async (req, res) => {
+        const { sessionId } = req.params;
+        const sessionResult = await consoleService.getSessionDetail(sessionId);
+        if (sessionResult.isErr()) {
+            const status = sessionResult.error.code === 'SESSION_LOAD_FAILED' ? 404 : 500;
+            res.status(status).json({ success: false, error: sessionResult.error.message });
+            return;
+        }
+        const sessionDetail = sessionResult.value;
+        if (!sessionDetail || !sessionDetail.runs || sessionDetail.runs.length === 0) {
+            res.status(404).json({ success: false, error: `Session not found: ${sessionId}` });
+            return;
+        }
+        res.setHeader('Content-Type', 'text/event-stream');
+        res.setHeader('Cache-Control', 'no-cache');
+        res.setHeader('Connection', 'keep-alive');
+        res.setHeader('X-Accel-Buffering', 'no');
+        res.flushHeaders();
+        res.write(`data: ${JSON.stringify({ kind: 'connected', sessionId })}\n\n`);
+        let currentLogDate = new Date().toISOString().slice(0, 10);
+        let currentLogPath = path_1.default.join(daemonEventsDir, `${currentLogDate}.jsonl`);
+        let fileOffset = 0;
+        try {
+            const stat = await fs_1.default.promises.stat(currentLogPath);
+            fileOffset = stat.size;
+        }
+        catch {
+        }
+        let isClosed = false;
+        let isProcessing = false;
+        let watcher = null;
+        const cleanup = () => {
+            if (isClosed)
+                return;
+            isClosed = true;
+            try {
+                watcher?.close();
+            }
+            catch { }
+            try {
+                if (!res.writableEnded)
+                    res.end();
+            }
+            catch { }
+        };
+        const processNewEvents = async () => {
+            if (isClosed || isProcessing)
+                return;
+            isProcessing = true;
+            const todayDate = new Date().toISOString().slice(0, 10);
+            if (todayDate !== currentLogDate) {
+                currentLogDate = todayDate;
+                currentLogPath = path_1.default.join(daemonEventsDir, `${currentLogDate}.jsonl`);
+                fileOffset = 0;
+            }
+            const newEvents = await tailDaemonEvents(currentLogPath, fileOffset);
+            for (const event of newEvents) {
+                if (isClosed)
+                    break;
+                const kind = typeof event['kind'] === 'string' ? event['kind'] : null;
+                const evtSessionId = typeof event['workrailSessionId'] === 'string'
+                    ? event['workrailSessionId']
+                    : null;
+                if (!kind || !SESSION_SSE_EVENT_KINDS.has(kind))
+                    continue;
+                if (evtSessionId !== sessionId)
+                    continue;
+                try {
+                    res.write(`data: ${JSON.stringify(event)}\n\n`);
+                }
+                catch {
+                    cleanup();
+                    return;
+                }
+                if (kind === 'session_completed') {
+                    cleanup();
+                    return;
+                }
+            }
+            try {
+                const stat = await fs_1.default.promises.stat(currentLogPath);
+                fileOffset = stat.size;
+            }
+            catch {
+                fileOffset = 0;
+            }
+            isProcessing = false;
+        };
+        try {
+            fs_1.default.mkdirSync(daemonEventsDir, { recursive: true });
+        }
+        catch { }
+        try {
+            watcher = fs_1.default.watch(daemonEventsDir, { recursive: false }, (_eventType, filename) => {
+                if (filename !== null && filename.endsWith('.jsonl')) {
+                    void processNewEvents();
+                }
+            });
+            watcher.on('error', cleanup);
+        }
+        catch {
+        }
+        const keepaliveInterval = setInterval(() => {
+            if (isClosed) {
+                clearInterval(keepaliveInterval);
+                return;
+            }
+            try {
+                res.write(': keepalive\n\n');
+            }
+            catch {
+                clearInterval(keepaliveInterval);
+                cleanup();
+            }
+        }, 30000);
+        const maxConnectionTimeout = setTimeout(() => {
+            clearInterval(keepaliveInterval);
+            cleanup();
+        }, 4 * 60 * 60 * 1000);
+        req.on('close', () => {
+            clearInterval(keepaliveInterval);
+            clearTimeout(maxConnectionTimeout);
+            cleanup();
+        });
+        res.on('close', () => {
+            clearInterval(keepaliveInterval);
+            clearTimeout(maxConnectionTimeout);
+            cleanup();
+        });
+        void processNewEvents();
+    });
     const THIRTY_DAYS_MS = 30 * 24 * 60 * 60 * 1000;
     const PERF_FILE_READ_LIMIT_BYTES = 5 * 1024 * 1024;
     async function readDiskEntries(perfFile) {
@@ -412,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);
                 }
             });
         }
@@ -443,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-artifact-protocol-design-candidates.md

@@ -0,0 +1,155 @@
+# Design Candidates: Coordinator Artifact Protocol
+
+**Status:** Candidate analysis complete  
+**Date:** 2026-04-18  
+**Task:** Implement wr.review_verdict schema, fix onComplete callback, update mr-review workflow to emit it, update coordinator to read artifacts before keyword-scanning
+
+---
+
+## Problem Understanding
+
+### Core Tensions
+
+**T1: Breaking interface vs. backward compatibility**
+`CoordinatorDeps.getAgentResult` returns `Promise<string | null>` today. Changing it to `Promise<{ recapMarkdown: string | null; artifacts: readonly unknown[] }>` is a compile-time breaking change. All call sites (2 in coordinator, 2 in test fakes, 1 real implementation) must change simultaneously. TypeScript catches this at build, so risk is low -- but the change must be complete.
+
+**T2: N+1 HTTP calls vs. tip-node-only simplicity**
+ALL-node aggregation requires walking `runs[0].nodes` and fetching each node's detail individually. For a 6-phase workflow, that's 6 HTTP calls to localhost per session. The simple approach (tip node only) would miss a verdict artifact from any non-final step.
+
+**T3: `required: false` vs. engine enforcement**
+`outputContract` with `required: false` means the engine won't block if the artifact is absent. This is the correct transition strategy but means the coordinator must maintain two code paths (artifact + keyword-scan fallback) until the graduation criterion (10+ consecutive sessions with 0 fallback warnings) is met.
+
+**T4: Schema strictness vs. forward compatibility**
+`.strict()` rejects unknown fields (forward-incompatible). `.strip()` strips them silently (forward-compatible). The task spec says `.strict()`, which matches the `loop-control.ts` precedent. The design doc recommends `.strip()` for forward-compat. **Task spec wins** -- use `.strict()` to be consistent with existing schema patterns.
+
+### Likely Seam
+
+`CoordinatorDeps.getAgentResult` is the real boundary. It is already the I/O abstraction layer where the coordinator interacts with sessions. Changing the return type here forces all consumers to acknowledge the new shape without touching coordinator routing logic.
+
+### What Makes This Hard
+
+1. **Three separate `onComplete` sites:** `makeCompleteStepTool` (line 1249), `makeContinueWorkflowTool` (line 1046), and the closure definition (line 2096). TypeScript will catch signature mismatches on the closure but not at the two call sites if the closure's new parameter is optional.
+2. **Exhaustiveness in the switch:** `artifact-contract-validator.ts` switch currently handles only `LOOP_CONTROL_CONTRACT_REF`. Adding `'wr.contracts.review_verdict'` to `ARTIFACT_CONTRACT_REFS` without adding a switch case causes `validateArtifactContract()` to hit the default `UNKNOWN_CONTRACT_REF` error for any step declaring this contract.
+3. **`source?` field on ReviewFindings:** Adding `source` as required breaks 4 existing test literals. Making it optional (`source?`) is a minor type weakness but preserves backward compat.
+
+---
+
+## Philosophy Constraints
+
+From CLAUDE.md:
+- **Make illegal states unrepresentable:** `verdict: 'clean'|'minor'|'blocking'` not `string`. `source: 'artifact'|'keyword_scan'` not `string`.
+- **Validate at boundaries:** Zod parse at coordinator read time + engine validation at advance time.
+- **Errors are data:** `readVerdictArtifact()` returns `ReviewFindings | null`, not throws.
+- **Functional/declarative:** `readVerdictArtifact()` is a pure function, composable with `parseFindingsFromNotes()`.
+- **Prefer fakes over mocks:** The `makeFakeDeps()` pattern in tests is the established style.
+
+**Conflict:** `required: false` during transition temporarily violates 'make illegal states unrepresentable' at the coordinator level. Accepted per design doc -- the fallback is explicit and time-boxed.
+
+---
+
+## Impact Surface
+
+Files that must change:
+- `src/v2/durable-core/schemas/artifacts/review-verdict.ts` (new)
+- `src/v2/durable-core/schemas/artifacts/index.ts` (ARTIFACT_CONTRACT_REFS)
+- `src/v2/durable-core/domain/artifact-contract-validator.ts` (switch case)
+- `src/daemon/workflow-runner.ts` (onComplete signature, WorkflowRunSuccess, final return)
+- `src/cli-worktrain.ts` (getAgentResult implementation + return type)
+- `src/coordinators/pr-review.ts` (CoordinatorDeps, ReviewFindings, readVerdictArtifact, call sites)
+- `workflows/mr-review-workflow.agentic.v2.json` (phase-6 outputContract + prompt)
+- `tests/unit/coordinator-pr-review.test.ts` (new tests + updated fakes)
+
+Must remain consistent:
+- `ConsoleNodeDetail.artifacts` -- no change needed, already returns artifacts
+- `projectArtifactsV2()` -- no change needed, already projects artifacts
+- `delivery-action.ts` -- reads `lastStepNotes`, not artifacts; no change needed
+- `makeSpawnAgentTool()` -- returns `{ notes: string }` only; `lastStepArtifacts` gap acknowledged, post-MVP
+
+---
+
+## Candidates
+
+### Candidate A: Exact task spec implementation (RECOMMENDED)
+
+**Summary:** Implement all three changes exactly as specified: fix `onComplete` to forward `params.artifacts`, add `wr.review_verdict` schema with `.strict()`, update `getAgentResult` to aggregate ALL-node artifacts, add `readVerdictArtifact()` pure function with keyword-scan fallback.
+
+**Tensions resolved:**
+- T1: TypeScript compile-time catch ensures completeness
+- T3: `required: false` + keyword-scan fallback avoids session blocking
+
+**Tensions accepted:**
+- T2: N+1 calls (accepted -- localhost, negligible latency)
+- T4: `.strict()` over `.strip()` (follows existing precedent)
+
+**Boundary:** `CoordinatorDeps.getAgentResult` return type change. Best-fit because it is already the established abstraction boundary for coordinator-to-session I/O. All consumers must acknowledge the change at this single point.
+
+**Failure mode:** Missing the `makeContinueWorkflowTool` `onComplete` call site (line 1046) when updating `makeCompleteStepTool` (line 1249). Both tools call `onComplete` but are in separate functions. TypeScript will not catch this if `artifacts?` is optional in the signature -- the closure will be called with `undefined` for `artifacts` from `continue_workflow`, and `lastStepArtifacts` will be silently empty.
+
+**Repo-pattern relationship:** Follows `loop-control.ts` schema pattern exactly. Follows `WorkflowRunSuccess.lastStepNotes` conditional spread pattern. Follows `makeFakeDeps()` fake deps testing pattern. No new patterns introduced.
+
+**Gains:**
+- Coordinator reads typed data for sessions that emit the artifact
+- Additive: all existing sessions continue to work via fallback
+- Zero new infrastructure: 7 file changes + 1 new file
+- Artifact visible in console (`hasArtifacts: true` on phase-6 node)
+- Observability: `source: 'artifact'|'keyword_scan'` + logging enables emission rate tracking
+
+**Losses:**
+- N+1 HTTP calls per session for artifact aggregation
+- Two coordinator code paths until graduation
+
+**Scope:** Best-fit. Minimal delta, highest backward compatibility, clear graduation path.
+
+**Philosophy:** Honors validate-at-boundaries, functional/declarative, prefer-fakes, exhaustiveness (closed enum `source`). Minor tension: `source?` optional field vs. type-safety-first. Temporary conflict with 'make illegal states unrepresentable' (accepted).
+
+---
+
+### Candidate B: Tip-node only (simpler, misses design intent)
+
+**Summary:** Only read tip node's artifacts -- matching the existing `preferredTipNodeId` pattern in `getAgentResult` today. Avoids N+1 calls.
+
+**Tensions resolved:**
+- T2: 1 HTTP call vs. N+1
+
+**Tensions accepted:**
+- Violates task spec 'CRITICAL: must aggregate artifacts across ALL session nodes'
+- If a verdict artifact is on step N-1 and the workflow gains a post-synthesis confirmation step N, coordinator silently gets zero artifacts
+
+**Failure mode:** Silent data loss when artifact is on a non-final node. This is the ORANGE-1 constraint from the design doc.
+
+**Scope:** Too narrow -- explicitly contradicts task requirement.
+
+**Why rejected:** The task spec uses 'CRITICAL' emphasis for ALL-node aggregation. Disqualified.
+
+---
+
+## Comparison and Recommendation
+
+**Recommendation: Candidate A.** No contest -- Candidate B is disqualified by the task spec.
+
+| Criterion | A | B |
+|-----------|---|---|
+| ALL-node aggregation (task spec) | Correct | WRONG |
+| N+1 calls | Accepted | Avoided |
+| Backward compat | Full | Same |
+| Schema precedent | Follows exactly | N/A |
+| Philosophy fit | Best | N/A |
+
+---
+
+## Self-Critique
+
+**Strongest counter-argument:** N+1 calls add latency. For a 6-step session, that's 6 additional HTTP calls. Acceptable on localhost (~50-100ms) but could be optimized with a `/api/v2/sessions/:id/artifacts` aggregation endpoint (Candidate C from the design doc). Evidence required: a second coordinator that needs this, or performance data showing N+1 calls are a problem.
+
+**Narrower option that almost works:** Tip-node only. Loses for the explicit task-spec reason.
+
+**Broader option:** Add `/api/v2/sessions/:id/artifacts` server-side endpoint. Right long-term direction, premature now.
+
+**Assumption that would invalidate:** If `runs[0].nodes` in the session detail response returns objects without `nodeId` fields. Confirmed from `ConsoleDagNode` type that `nodeId: string` is always present.
+
+---
+
+## Open Questions for the Main Agent
+
+1. Should `source?` be optional or required on `ReviewFindings`? Optional breaks fewer existing tests but weakens the type. The 4 existing `ReviewFindings` literals in tests would need `source` added if required.
+2. Should `readVerdictArtifact()` log a divergence warning when both artifact severity and keyword-scan severity are available but disagree? The design doc recommends this (ORANGE finding). Adds ~10 LOC but improves observability.