@exaudeus/workrail 3.39.0 → 3.40.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.js

@@ -40,6 +40,7 @@ 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");
@@ -135,6 +136,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) {

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.

package/docs/design/coordinator-artifact-protocol-design-review.md

@@ -0,0 +1,103 @@
+# Design Review Findings: Coordinator Artifact Protocol
+
+**Status:** Review complete  
+**Date:** 2026-04-18  
+**Design reviewed:** Candidate A from coordinator-artifact-protocol-design-candidates.md
+
+---
+
+## Tradeoff Review
+
+| Tradeoff | Acceptable? | When it stops being acceptable |
+|----------|-------------|-------------------------------|
+| N+1 HTTP calls for all-node aggregation | Yes (localhost, ~50-100ms) | If coordinator is called for sessions with 50+ nodes |
+| `source?` optional on `ReviewFindings` | Yes (observability only, not routing) | If future code switches exhaustively on `source` |
+| `.strict()` schema | Yes (follows existing precedent) | If LLM consistently emits extra fields causing Zod failures |
+| `required: false` in outputContract | Yes (transition strategy) | Once 10+ consecutive sessions confirm 100% artifact emission |
+
+---
+
+## Failure Mode Review
+
+| Failure Mode | Severity | Handling | Missing Mitigation |
+|-------------|----------|----------|--------------------|
+| Missing `makeContinueWorkflowTool` onComplete update | LOW | TypeScript won't catch (optional param) -- manual verification required | Code comment at both call sites |
+| Per-node HTTP fetch failure during aggregation | LOW | Graceful fallback to keyword scan | Per-node try/catch + WARN logging |
+| Agent emits malformed artifact (wrong enum, missing field) | MEDIUM | `safeParse` fails silently without logging | `[WARN coord:reason=artifact_parse_failed]` logging REQUIRED |
+| `runs[0].nodes` undefined for empty sessions | NONE | Null check + empty-array fallback | None |
+| `required: false` default behavior | NONE | Engine correctly reads `required: false` and skips validation | None |
+
+---
+
+## Runner-Up / Simpler Alternative Review
+
+**Runner-up (tip-node only):** Disqualified by task spec 'CRITICAL: must aggregate artifacts across ALL session nodes'. No elements worth incorporating.
+
+**Simpler variant (skip `lastStepArtifacts`):** The pr-review coordinator reads via HTTP, not via `WorkflowRunSuccess`. Skipping would satisfy the coordinator use case. Rejected because the task spec explicitly requires it, and it's the foundation for `spawn_agent` artifact surfacing (post-MVP).
+
+**Simpler variant (skip `onComplete` change):** Would leave `WorkflowRunSuccess.lastStepArtifacts` always undefined. Rejected -- inconsistent state.
+
+---
+
+## Philosophy Alignment
+
+**Satisfied:** validate-at-boundaries, errors-as-data, functional/declarative, prefer-fakes, exhaustiveness (closed enums), immutability.
+
+**Under tension (accepted):**
+- `source?` optional vs. type-safety-first: minor, observability-only field
+- `required: false` vs. make-illegal-states-unrepresentable: time-boxed transition strategy
+
+---
+
+## Findings
+
+### RED (must fix before shipping)
+
+**R1: `readVerdictArtifact()` must log on malformed artifact**
+If the agent emits an artifact with `kind: 'wr.review_verdict'` but wrong schema, `safeParse` fails silently. Without logging, FM3 (malformed artifact) is invisible and prevents monitoring of the artifact emission rate.
+
+Required: `process.stderr.write('[WARN coord:reason=artifact_parse_failed ...]')` when `safeParse` fails AND the artifact has `kind === 'wr.review_verdict'`.
+
+**R2: Per-node fetch errors must be caught individually**
+The current outer `try/catch` in `getAgentResult` covers the entire function. The new implementation walks multiple nodes -- if one node fetch throws, the outer catch aborts the entire aggregation. Each per-node fetch must be wrapped individually so one failure doesn't discard all other nodes' artifacts.
+
+---
+
+### ORANGE (fix before C1 -> C2 graduation)
+
+**O1: Log when keyword scan fires on a session that had artifacts**
+The coordinator cannot distinguish 'artifact never emitted' from 'artifact emitted but invalid' without checking. Add a log entry when `readVerdictArtifact` returns null but `artifacts.length > 0`. This enables the graduation metric (10+ sessions with 0 fallback warnings).
+
+Required log: `[INFO coord:source=keyword_scan reason=no_valid_artifact artifactCount=N]`
+
+**O2: Divergence detection warning**
+If both artifact severity (from `readVerdictArtifact`) and keyword-scan severity (from `parseFindingsFromNotes`) are available and disagree, log at WARN. Design doc recommends this (ORANGE finding). Protects against semantic inconsistency between notes and artifact.
+
+---
+
+### YELLOW (future consideration)
+
+**Y1: `source?` optional on `ReviewFindings`**
+Making `source` required would improve type safety. Currently deferred to avoid breaking 4 existing test literals. When those tests are updated for other reasons, upgrade `source` to required.
+
+**Y2: Post-graduation: remove keyword scan fallback**
+Once the graduation criterion is met, `parseFindingsFromNotes` callers can be removed from the coordinator routing logic. The `unknown` severity variant can also be removed from `ReviewSeverity`.
+
+---
+
+## Recommended Revisions
+
+1. **R1:** In `readVerdictArtifact()`, check if `raw` object has `kind === 'wr.review_verdict'` before `safeParse`. If kind matches but safeParse fails, log WARN.
+2. **R2:** In `getAgentResult()` implementation, wrap each per-node HTTP fetch in its own try/catch. Failed nodes are skipped with a WARN log; successful nodes contribute their artifacts.
+3. **O1:** After the artifact/keyword-scan decision in the coordinator, log `source` with the artifact count context.
+4. **O2:** Add divergence check: run keyword scan on `recapMarkdown` when an artifact is found; if severities disagree, log WARN.
+
+---
+
+## Residual Concerns
+
+1. **`continue_workflow` onComplete call site:** `makeContinueWorkflowTool` is marked DEPRECATED for daemon sessions, but it still calls `onComplete`. The new `artifacts?` parameter must be passed from `params.artifacts` at line 1046. Must be verified manually -- TypeScript won't catch a missing optional parameter.
+
+2. **`.strict()` vs. LLM reliability:** If the LLM adds extra fields (e.g., `rationale`, `notes`) to the artifact, `.strict()` causes Zod failure. With `required: false`, this just triggers the keyword-scan fallback. Acceptable during transition. If the failure rate is high in production, consider switching to `.strip()`.
+
+3. **Convention only:** `V1` suffix on `ReviewVerdictArtifactV1Schema` is a convention, not enforced. No migration path exists for schema changes. Future schema evolution must use a new type (`ReviewVerdictArtifactV2Schema`) in parallel until old sessions are retired.