@exaudeus/workrail 3.67.0 → 3.68.0

package/docs/design/implementation-plan-discovery-loop-fix.md

@@ -0,0 +1,199 @@
+# Implementation Plan: Discovery Loop Fix
+
+**Date:** 2026-04-19
+**Branch:** `fix/discovery-loop-timeout-and-label`
+**Commit:** `fix(coordinator): thread session timeouts, inspect PipelineOutcome, add sidecar idempotency`
+
+---
+
+## 1. Problem Statement
+
+WorkTrain's pipeline re-ran `wr.discovery` on issue #393 at least 73 times over 19+ hours. Three root causes create an infinite re-selection loop:
+
+1. `spawnSession()` passes no `agentConfig` -- sessions inherit `DEFAULT_SESSION_TIMEOUT_MINUTES=30`, but the coordinator waits 55 minutes. Sessions die at 30m; coordinator times out at 55m and escalates.
+2. `PipelineOutcome` is silently discarded in `polling-scheduler.ts` -- no label is applied on escalation, so the issue is re-selected on every poll cycle.
+3. `checkIdempotency()` sidecar scan is dead -- `persistTokens()` never writes a `context` field, so every session file is treated as `'clear'`.
+
+---
+
+## 2. Acceptance Criteria
+
+- `spawnSession` with `agentConfig.maxSessionMinutes` threads through to `runWorkflowFn` (Fix 1)
+- On `PipelineOutcome.kind === 'escalated'`, `applyGitHubLabel` is called with `worktrain:in-progress` (Fix 2)
+- On `PipelineOutcome.kind === 'success'`, no label is applied (Fix 2)
+- Issue-ownership sidecar is written before dispatch and deleted on completion (Fix 3)
+- Expired sidecar (TTL exceeded) returns `'clear'` from `checkIdempotency` (Fix 3)
+- `npm run build` passes with no errors
+- `npx vitest run` passes with no regressions
+
+---
+
+## 3. Non-Goals
+
+- Do NOT touch `src/mcp/`
+- N-strike mechanism (label applied only after N escalations) -- deferred
+- Coordinator-owns-termination refactor -- deferred
+- Unassigning bot from issue on escalation -- not in spec
+- Daemon startup sidecar cleanup -- deferred
+- Exhaustive TypeScript switch on PipelineOutcome kinds -- deferred (if-check satisfies spec)
+
+---
+
+## 4. Philosophy-Driven Constraints
+
+- All new interface fields are `readonly`
+- `applyGitHubLabel` uses injected `fetchFn` (not `globalThis.fetch` directly)
+- Sidecar write failure must NOT block dispatch (fire-and-forget, log warn)
+- `applyGitHubLabel` failure must NOT block poll cycle cleanup (log warn, continue)
+- ESM imports use `.js` extension
+- New types: discriminated union `PipelineOutcome` already exists -- use it, don't re-create
+
+---
+
+## 5. Invariants
+
+1. **Fix 1 + Fix 2 ship together** -- deploying Fix 2 without Fix 1 causes every FULL-mode issue to escalate (30m timeout) and get permanently labeled
+2. **Label = `worktrain:in-progress`** -- already in `queueConfig.excludeLabels` (polling-scheduler.ts:505); using a new label requires operator config change with no enforcement
+3. **Sidecar TTL = `DISCOVERY_TIMEOUT_MS + 60_000`** ms -- handles crash case; expired sidecar = eligible for re-dispatch
+4. **Conservative idempotency**: malformed sidecar = 'active' (never allow double-dispatch)
+5. **Sidecar written before dispatch, deleted in both .then() and .catch()**
+
+---
+
+## 6. Selected Approach
+
+**Candidate A**: Exact spec implementation.
+
+- Fix 1: Add optional 5th param `agentConfig?` to `CoordinatorDeps.spawnSession` in `pr-review.ts`, thread through `trigger-listener.ts` to `routerRef.dispatch()`, pass correct timeouts at 4 spawn sites in `full-pipeline.ts`
+- Fix 2: Change `Promise<unknown>` to `Promise<PipelineOutcome>` in `polling-scheduler.ts`, inspect outcome, add `applyGitHubLabel` private method
+- Fix 3: Write `queue-issue-<N>.json` sidecar in `doPollGitHubQueue`, extend `checkIdempotency` to check sidecar files by filename pattern with TTL check
+
+**Runner-up**: Candidate B (separate sidecar function). Lost: creates coordination risk with two callsites.
+
+---
+
+## 7. Vertical Slices
+
+### Slice 1: Fix 1 -- Thread maxSessionMinutes through spawnSession
+
+**Files changed**:
+- `src/coordinators/pr-review.ts` -- add optional `agentConfig?: { readonly maxSessionMinutes?: number; readonly maxTurns?: number }` as 5th param to `CoordinatorDeps.spawnSession`
+- `src/coordinators/adaptive-pipeline.ts` -- `AdaptiveCoordinatorDeps` extends `CoordinatorDeps`, so this is automatically propagated; no change needed here
+- `src/trigger/trigger-listener.ts` -- add `agentConfig?: { readonly maxSessionMinutes?: number; readonly maxTurns?: number }` as 5th param to `spawnSession` closure, forward to `routerRef.dispatch({ ..., agentConfig })`
+- `src/coordinators/modes/full-pipeline.ts` -- pass `{ maxSessionMinutes: Math.ceil(DISCOVERY_TIMEOUT_MS / 60_000) }` (=55) at discovery spawn, `{ maxSessionMinutes: Math.ceil(SHAPING_TIMEOUT_MS / 60_000) }` (=35) at shaping spawn, `{ maxSessionMinutes: Math.ceil(REVIEW_TIMEOUT_MS / 60_000) }` (=25) at UX design spawn, `{ maxSessionMinutes: Math.ceil(CODING_TIMEOUT_MS / 60_000) }` (=65) at coding spawn
+
+**Done when**: TypeScript compiles cleanly; `spawnSession` at all call sites passes the correct agentConfig
+
+### Slice 2: Fix 2 -- Inspect PipelineOutcome and apply worktrain:in-progress label
+
+**Files changed**:
+- `src/trigger/polling-scheduler.ts`:
+  - Add import: `import type { PipelineOutcome } from '../coordinators/adaptive-pipeline.js';`
+  - Add import: `import { DISCOVERY_TIMEOUT_MS } from '../coordinators/adaptive-pipeline.js';`
+  - Change `Promise<unknown>` to `Promise<PipelineOutcome>` at L605-610
+  - Change `.then(() => {` to `.then((outcome: PipelineOutcome) => {`
+  - Add label application for `outcome.kind === 'escalated' || outcome.kind === 'dry_run'`
+  - Add private method `applyGitHubLabel(issueNumber: number, label: string, token: string, repo: string): Promise<void>`
+    - POST `https://api.github.com/repos/${repo}/issues/${issueNumber}/labels`
+    - Body: `JSON.stringify({ labels: [label] })`
+    - Headers: `Authorization: Bearer ${token}`, `Accept: application/vnd.github+json`, `Content-Type: application/json`
+    - Uses `(this.fetchFn as QueueFetchFn | undefined) ?? globalThis.fetch`
+    - Non-fatal: catch error, console.warn, return
+
+**Done when**: On escalated/dry_run outcome, `applyGitHubLabel` is called with `('worktrain:in-progress', queueConfig.token, source.repo)`
+
+### Slice 3: Fix 3 -- Write/delete sidecar and extend checkIdempotency
+
+**Files changed**:
+- `src/trigger/polling-scheduler.ts`:
+  - Before dispatch call: write `queue-issue-<N>.json` to `sessionsDir` with `{ issueNumber, triggerId, dispatchedAt: Date.now(), ttlMs: DISCOVERY_TIMEOUT_MS + 60_000 }`
+  - In `.then()` handler: delete the sidecar file (fire-and-forget, ignore errors)
+  - In `.catch()` handler: delete the sidecar file (fire-and-forget, ignore errors)
+- `src/trigger/adapters/github-queue-poller.ts`:
+  - In `checkIdempotency`, before the main scan loop, check if `queue-issue-${issueNumber}.json` exists in `sessionsDir`
+  - If file exists: parse it, check `dispatchedAt + ttlMs > Date.now()` -- if true (not expired), return 'active'; if false (expired), return 'clear' for this file
+  - On any parse error for the sidecar: return 'active' (conservative)
+  - Update JSDoc to describe sidecar file format
+
+**Done when**: Sidecar is written before dispatch, deleted on completion; `checkIdempotency` returns 'active' for active sidecar and 'clear' for expired sidecar
+
+### Slice 4: Tests
+
+**New file**: `tests/unit/discovery-loop-fix.test.ts`
+
+**Test cases**:
+
+1. `spawnSession with agentConfig.maxSessionMinutes threads through to dispatch call`
+   - Create a fake `routerRef` that captures dispatch calls
+   - Call `coordinatorDeps.spawnSession('wr.discovery', goal, workspace, undefined, { maxSessionMinutes: 55 })`
+   - Assert dispatch was called with `agentConfig: { maxSessionMinutes: 55 }`
+   - Note: This tests trigger-listener.ts via integration or by testing the coordinator deps implementation directly
+
+2. `On PipelineOutcome.kind === escalated, applyGitHubLabel is called with worktrain:in-progress`
+   - Create a fake router with `dispatchAdaptivePipeline` returning `{ kind: 'escalated', escalationReason: { phase: 'discovery', reason: 'timeout' } }`
+   - Create a fake fetchFn that captures calls
+   - Run `doPollGitHubQueue` (via private method cast)
+   - Assert fetchFn was called with URL containing `/labels` and body containing `worktrain:in-progress`
+
+3. `On PipelineOutcome.kind === success, no label is applied`
+   - Same setup but `dispatchAdaptivePipeline` returns `{ kind: 'merged', prUrl: 'https://github.com/...' }`
+   - Assert fetchFn was NOT called with a labels URL
+
+4. `Issue-ownership sidecar is written before dispatch and deleted on completion`
+   - Create a tmpDir for sessionsDir
+   - Run `doPollGitHubQueue`
+   - Assert sidecar file exists after dispatch setup but is deleted after completion
+   - Note: Since dispatch is async, check sidecar presence inside the `dispatchAdaptivePipeline` mock
+
+5. `Expired sidecar (TTL exceeded) returns 'clear' from checkIdempotency`
+   - Write a sidecar file with `{ issueNumber: 42, triggerId: 'x', dispatchedAt: 0, ttlMs: 1 }` (already expired)
+   - Call `checkIdempotency(42, tmpDir)`
+   - Assert result is `'clear'`
+
+---
+
+## 8. Test Design
+
+**File**: `tests/unit/discovery-loop-fix.test.ts`
+**Framework**: Vitest with `vi.fn()` fakes
+**Fixtures**: tmpDir for session files, fake fetchFn capturing calls, fake router returning specific PipelineOutcome kinds
+
+Key patterns from existing tests:
+- Private method access: `(scheduler as unknown as { doPollGitHubQueue(...) }).doPollGitHubQueue(...)`
+- Fake router: `{ dispatchAdaptivePipeline: async (...) => { return { kind: 'escalated', ... } } }`
+- Queue config: use `vi.mock` or provide a mock `loadQueueConfig`
+
+Note: The `spawnSession` agentConfig threading test (test case 1) may be better placed in an integration test that creates a real `trigger-listener.ts` environment. Given the complexity, a unit test that mocks the router and verifies the dispatch call args is acceptable.
+
+---
+
+## 9. Risk Register
+
+| Risk | Likelihood | Impact | Mitigation |
+|---|---|---|---|
+| GitHub token expired at label application time | Low | Issue loops again | Warn log is the signal; no code mitigation needed |
+| Sidecar accumulation if delete fails | Low | Manual cleanup needed | TTL handles cleanup after 56m |
+| TypeScript error from 5th optional param on test fakes | Low | Build fails | vi.fn() mocks don't enforce param count |
+| Import of DISCOVERY_TIMEOUT_MS creates circular dep | Low | Build fails | adaptive-pipeline.ts has no deps on polling-scheduler.ts |
+
+---
+
+## 10. PR Packaging Strategy
+
+**Single PR** on branch `fix/discovery-loop-timeout-and-label`
+All 3 fixes + tests in one PR. Fixes 1 and 2 are coupled -- they cannot be split.
+
+---
+
+## 11. Philosophy Alignment
+
+| Principle | Slice | Status |
+|---|---|---|
+| Immutability by default | 1 (agentConfig fields readonly) | Satisfied |
+| Type safety | 2 (Promise<PipelineOutcome>) | Satisfied |
+| Errors are data | 2 (applyGitHubLabel fire-and-forget) | Tension -- acceptable for non-fatal I/O |
+| Dependency injection | 2 (fetchFn injected) | Satisfied |
+| Exhaustiveness | 2 (all 3 outcome kinds handled) | Satisfied |
+| YAGNI | All | Satisfied -- no extra abstractions |
+| Document why not what | 3 (JSDoc update for checkIdempotency) | Satisfied |
+| Determinism | 3 (TTL check adds wall-clock dep) | Tension -- acceptable for crash recovery |

package/docs/design/implementation-plan-queue-poll-rotation.md

@@ -0,0 +1,102 @@
+# Implementation Plan: queue-poll.jsonl rotation
+
+_Date: 2026-04-21_
+
+## 1. Problem Statement
+
+`~/.workrail/queue-poll.jsonl` grows without bound. At 5-minute polling intervals it accumulates ~8.7 MB/month; at 1-minute intervals ~87 MB/month. The daemon memory audit rates this Critical. Additionally, the `worktrain logs --follow` command uses an offset-based reader that assumes the file only grows -- after rotation (when the file is replaced), the stale offset permanently stops the reader from showing new events.
+
+## 2. Acceptance Criteria
+
+1. `queue-poll.jsonl` never exceeds ~10 MB + one write cycle.
+2. `queue-poll.jsonl.1` exists after the first rotation and contains the most recent pre-rotation entries.
+3. `worktrain logs --follow` continues showing events after rotation (offset reset on shrink detection).
+4. Rotation failures log a warning via `console.warn` and do not crash or stop polling.
+5. The 'permanent file that never rotates' comment in `src/cli-worktrain.ts` is updated.
+6. `npx tsc --noEmit` passes.
+7. `npx vitest run` passes.
+
+## 3. Non-Goals
+
+- No configurable size threshold (hardcoded 10 MB).
+- No date-named rotation files (backup is `queue-poll.jsonl.1` only).
+- No changes to `daemon.stderr.log`.
+- `worktrain logs` does NOT show backup file content.
+- No multiple backup generations (no `.2`, `.3`, etc.).
+
+## 4. Philosophy-Driven Constraints
+
+- **Errors are data**: rotation failures use `console.warn`, never throw.
+- **YAGNI**: no helper function extracted (single use case).
+- **Architectural fixes over patches**: update the 'permanent file' comment so code and documentation stay in sync.
+- **Determinism**: stat before append ensures rotation decision is based on current state.
+
+## 5. Invariants
+
+- I1: File size checked BEFORE each append (stat before appendFile).
+- I2: If size >= 10 MB, rename to `.1` (overwriting existing backup) before appending.
+- I3: Reader: if `stat.size < queuePollOffset`, reset `queuePollOffset = 0`.
+- I4: Rotation is fire-and-forget -- inner try/catch around stat/rename; outer try/catch for the full function.
+- I5: ENOENT on stat is caught by inner try/catch and falls through to appendFile (creates file).
+
+## 6. Selected Approach + Rationale + Runner-Up
+
+**Selected**: Candidate A -- inline stat+rename in `appendQueuePollLog` + shrink detection in `--follow` loop.
+
+**Rationale**: Minimal footprint, follows existing fire-and-forget pattern exactly, zero new abstractions. Both writer and reader fixes in the correct location.
+
+**Runner-up**: Candidate B (extracted `rotateIfNeeded` helper). Lost because YAGNI -- no other callers need the function.
+
+## 7. Vertical Slices
+
+### Slice 1: Writer fix (`src/trigger/polling-scheduler.ts`)
+- Add `const MAX_QUEUE_POLL_FILE_SIZE = 10 * 1024 * 1024` constant before the class.
+- Rewrite `appendQueuePollLog` to: stat file, rename to `.1` if size >= threshold, then append.
+- Update or remove the existing comment about never rotating (if any).
+- Done when: `appendQueuePollLog` rotates the file at >= 10 MB and the backup exists.
+
+### Slice 2: Reader fix (`src/cli-worktrain.ts`)
+- Update the comment at lines 685 and 892-893 from 'permanent file that never rotates' to reflect rotation.
+- Add shrink detection before `readNewLines(queuePollPath, queuePollOffset)` in the `--follow` loop: `if (stat.size < queuePollOffset) { queuePollOffset = 0; }`.
+- Done when: `--follow` resets offset on file shrinkage and continues showing events.
+
+### Slice 3: Verification
+- Run `npx tsc --noEmit` -- must pass.
+- Run `npx vitest run` -- must pass.
+
+## 8. Test Design
+
+The existing `tests/unit/polling-scheduler.test.ts` does not mock `os.homedir()`, making it difficult to test `appendQueuePollLog` rotation in isolation without significant test infrastructure changes. The pitch does not require new unit tests for the rotation logic (only 'CI passes'). Verification is through TypeScript compilation and the existing test suite.
+
+If future tests are added for rotation, they should mock `fs.stat`, `fs.rename`, and `fs.appendFile` using vitest's `vi.mock` or inject a file-system abstraction.
+
+## 9. Risk Register
+
+| Risk | Severity | Mitigation |
+|---|---|---|
+| Concurrent rotation race | Yellow | Acknowledged and accepted per pitch. At most 1-2 log lines lost. |
+| EACCES causing unbounded growth | Yellow | console.warn via try/catch. Acceptable for diagnostic log. |
+| Reader fix missed (writer-only PR) | Red | Both slices MUST ship in the same PR. |
+
+## 10. PR Packaging Strategy
+
+**SinglePR**: `fix/etienneb/queue-poll-rotation`
+- Commit: `fix(engine): add size-capped rotation for queue-poll.jsonl at 10 MB`
+- Both slices in one commit.
+- MUST NOT be split into writer-only and reader-only PRs.
+
+## 11. Philosophy Alignment per Slice
+
+### Slice 1 (Writer)
+- Errors are data -> satisfied (console.warn not throw)
+- YAGNI -> satisfied (no helper extracted)
+- Determinism -> satisfied (stat before append)
+- Architectural fixes over patches -> satisfied (not a special case, changes the invariant)
+
+### Slice 2 (Reader)
+- Architectural fixes over patches -> satisfied (shrink detection is the correct invariant change)
+- Document why not what -> satisfied (comment update explains rotation now happens)
+- Errors are data -> N/A (statSync in try block for reader)
+
+### Slice 3 (Verification)
+- Type safety as first line of defense -> satisfied (tsc --noEmit)

package/docs/design/in-process-http-audit.md

@@ -0,0 +1,190 @@
+# In-Process HTTP Audit: Daemon Calling Its Own API
+
+**Date:** 2026-04-19
+**Scope:** WorkTrain daemon coordinator deps -- calls from inside the daemon process to the daemon's own HTTP console (port 3456) or webhook (port 3200) servers.
+
+---
+
+## Summary
+
+The daemon's in-process `coordinatorDeps` block (wired in `src/trigger/trigger-listener.ts:410-752`) contains **two functions** that make HTTP calls to the daemon's own console server at port 3456. Both functions should use `ConsoleService` directly instead.
+
+**Bugs confirmed: 2**
+**False positives excluded: CLI HTTP calls (correct design)**
+
+---
+
+## 1. Every HTTP-to-Self Call Found
+
+### Bug 1: `awaitSessions` -- HTTP polling for session status
+
+**File:line:** `src/trigger/trigger-listener.ts:499-540`
+
+**What it does:**
+
+```typescript
+awaitSessions: async (handles: readonly string[], timeoutMs: number) => {
+  const { executeWorktrainAwaitCommand } = await import('../cli/commands/worktrain-await.js');
+  await executeWorktrainAwaitCommand(
+    {
+      fetch: (url: string) => globalThis.fetch(url),  // <-- real HTTP fetch
+      ...
+    },
+    {
+      sessions: [...handles].join(','),
+      port: DAEMON_CONSOLE_PORT,  // 3456
+      ...
+    },
+  );
+```
+
+`executeWorktrainAwaitCommand` calls `pollSession()` in `worktrain-await.ts` which builds:
+
+```
+GET http://127.0.0.1:3456/api/v2/sessions/<sessionHandle>
+```
+
+...every 3 seconds until the session status is terminal (`complete`, `complete_with_gaps`, `blocked`, `dormant`).
+
+**Is it broken today?** Yes. Two active failure modes:
+1. **Port unavailable:** If another process holds port 3456, or if `startDaemonConsole()` hasn't been called yet, the `fetch()` calls return `ECONNREFUSED` and all sessions are reported as `failed`.
+2. **Race condition:** A session created in-process by `spawnSession()` may not yet be visible to the HTTP layer when the first poll fires. The HTTP layer reads from the same session store, but there is no synchronization guarantee between the in-process write and the HTTP server's view.
+
+**Used by:** `full-pipeline.ts` (discovery, shaping, ux-gate, coding sessions), `implement.ts` (ux-gate, coding), `implement-shared.ts` (review, fix-agent, audit, re-review), `pr-review.ts` (review, fix, re-review).
+
+---
+
+### Bug 2: `getAgentResult` -- HTTP fetching for artifacts and recap
+
+**File:line:** `src/trigger/trigger-listener.ts:542-609`
+
+**What it does:**
+
+```typescript
+getAgentResult: async (sessionHandle: string) => {
+  // Step 1: get session detail
+  const sessionUrl = `http://127.0.0.1:${DAEMON_CONSOLE_PORT}/api/v2/sessions/${encodeURIComponent(sessionHandle)}`;
+  const sessionRes = await globalThis.fetch(sessionUrl, { signal: AbortSignal.timeout(30_000) });
+  // ... extracts runs[0].preferredTipNodeId and all nodeIds ...
+
+  // Step 2: fetch each node
+  const baseNodeUrl = `http://127.0.0.1:${DAEMON_CONSOLE_PORT}/api/v2/sessions/${encodeURIComponent(sessionHandle)}/nodes/`;
+  for (const nodeId of nodeIdsToFetch) {
+    const nodeRes = await globalThis.fetch(baseNodeUrl + encodeURIComponent(nodeId), ...);
+    // ... extracts recapMarkdown and artifacts ...
+  }
+}
+```
+
+Makes 1 + N HTTP calls (1 for session detail, N for each node) to the daemon's own console server to collect `recapMarkdown` (for verdict keyword-scan fallback) and `artifacts` (for typed verdict reading via `readVerdictArtifact`).
+
+**Is it broken today?** Yes. Same failure modes as Bug 1. Additionally:
+- Artifacts written during in-process session execution may not be flushed to the HTTP-visible layer before `getAgentResult` is called
+- Each node fetch has a 30-second timeout; for sessions with many nodes this adds latency
+
+**Used by:** `full-pipeline.ts` (after discovery, to read handoff artifact), `implement-shared.ts` (after review, to read verdict artifact and recap).
+
+---
+
+## 2. Priority Ranking
+
+| Rank | Bug | Impact | Blocks pipeline today? |
+|------|-----|--------|----------------------|
+| 1 | `awaitSessions` HTTP polling (Bug 1) | All pipelines hang or report sessions as failed if port 3456 unavailable | Yes |
+| 2 | `getAgentResult` HTTP fetching (Bug 2) | Discovery handoff context missing; review verdict read fails if port 3456 unavailable | Yes -- silently degrades to empty artifacts / keyword-scan only |
+
+Both bugs are blocking, not cosmetic. Bug 1 is higher priority because it affects every pipeline phase (all spawned sessions must be awaited). Bug 2 causes a cascade: if `getAgentResult` returns empty artifacts after a coding session, the review verdict cannot be read via the typed path and falls back to keyword-scan on `recapMarkdown`, which is itself also empty -- causing an escalation with reason `review verdict parse failed`.
+
+---
+
+## 3. Recommended Fix for Each
+
+### Fix for Bug 1: `awaitSessions` -- In-process polling via ConsoleService
+
+**Replace** the `executeWorktrainAwaitCommand` delegation with a direct polling loop using `ConsoleService.getSessionDetail()`.
+
+**In-process equivalent:** `ConsoleService.getSessionDetail(sessionId)` returns `ConsoleSessionDetail` which includes `runs[0].status: ConsoleRunStatus`. The status values (`complete`, `complete_with_gaps`, `blocked`) map directly to the existing `statusToOutcome()` logic in `worktrain-await.ts`.
+
+**What to build:**
+- Construct a `ConsoleService` instance in `startTriggerListener()` using the `ctx.v2` deps already available (`ctx.v2.sessionStore`, `ctx.v2.snapshotStore`, `ctx.v2.pinnedStore`, `ctx.v2.dataDir`, `ctx.v2.directoryListing`)
+- Replace `awaitSessions` with an in-process polling loop that calls `consoleService.getSessionDetail(handle)` every ~3 seconds until `runs[0].status` is terminal
+- Handle `dormant` separately: since `ConsoleService.getSessionDetail()` returns `ConsoleRunStatus` (not `ConsoleSessionStatus`), `dormant` won't appear in `runs[0].status`. The polling loop's own timeout covers the dormant case -- sessions that go quiet will be caught by `timeoutMs`
+- Wire the `ConsoleService` instance into `coordinatorDeps` via closure (same pattern as `routerRef`)
+
+**Key files:**
+- `src/trigger/trigger-listener.ts` -- replace `awaitSessions` implementation
+- `src/v2/usecases/console-service.ts` -- `ConsoleService.getSessionDetail()` -- no changes needed
+- `src/v2/usecases/console-types.ts` -- `ConsoleSessionDetail`, `ConsoleRunStatus` -- no changes needed
+
+---
+
+### Fix for Bug 2: `getAgentResult` -- In-process node detail via ConsoleService
+
+**Replace** the two-phase HTTP fetch with `ConsoleService.getSessionDetail()` (for node IDs) and `ConsoleService.getNodeDetail()` (for per-node recap and artifacts).
+
+**In-process equivalent:**
+- `ConsoleService.getSessionDetail(sessionId)` returns `ConsoleSessionDetail.runs[0].nodes: readonly ConsoleDagNode[]` where each `ConsoleDagNode` has `nodeId` and `isPreferredTip`
+- `ConsoleService.getNodeDetail(sessionId, nodeId)` returns `ConsoleNodeDetail` with `recapMarkdown: string | null` and `artifacts: readonly ConsoleArtifact[]` -- exactly what the current HTTP implementation extracts
+
+**What to build:**
+- Reuse the same `ConsoleService` instance constructed for Bug 1 fix
+- Replace `getAgentResult` with an in-process version that calls `getSessionDetail` then `getNodeDetail` for each node
+- Preserve the existing logic: collect artifacts from all nodes; collect `recapMarkdown` from the preferred-tip node only
+
+**Key files:**
+- `src/trigger/trigger-listener.ts` -- replace `getAgentResult` implementation
+- `src/v2/usecases/console-service.ts` -- `ConsoleService.getNodeDetail()` -- no changes needed
+- `src/v2/usecases/console-types.ts` -- `ConsoleNodeDetail` -- no changes needed
+
+---
+
+## 4. The Correct Architecture
+
+### Current (broken) wiring
+
+```
+TriggerListener (daemon process)
+  ├── startTriggerListener() constructs coordinatorDeps
+  │   ├── awaitSessions: calls executeWorktrainAwaitCommand
+  │   │   └── polls http://127.0.0.1:3456/api/v2/sessions/<id>  ← HTTP-to-self
+  │   └── getAgentResult: calls globalThis.fetch
+  │       └── fetches http://127.0.0.1:3456/api/v2/sessions/<id>/nodes/... ← HTTP-to-self
+  └── startDaemonConsole() constructs ConsoleService (separately)
+      └── ConsoleService.getSessionDetail()  ← in-process, not used by coordinatorDeps
+      └── ConsoleService.getNodeDetail()     ← in-process, not used by coordinatorDeps
+```
+
+### Target (correct) wiring
+
+```
+TriggerListener (daemon process)
+  └── startTriggerListener() constructs:
+      ├── consoleService = new ConsoleService({ ctx.v2.sessionStore, ... })
+      └── coordinatorDeps
+          ├── awaitSessions: in-process polling loop
+          │   └── consoleService.getSessionDetail(handle).runs[0].status  ← no HTTP
+          └── getAgentResult: in-process node reading
+              ├── consoleService.getSessionDetail(handle).runs[0].nodes   ← no HTTP
+              └── consoleService.getNodeDetail(handle, nodeId)            ← no HTTP
+```
+
+### Why the same ConsoleService instance works for both
+
+`ConsoleService` is a stateless projection reader -- it reads from `ctx.v2.sessionStore` (the same append-only event log written by the in-process session execution). Sessions created in-process by `spawnSession()` write their events to the same store that `ConsoleService` reads. There is no HTTP layer in this path -- the data is immediately available after commit.
+
+### What should NOT use in-process access
+
+The CLI `run pr-review` command (`src/cli-worktrain.ts:1265-1501`) is a **separate process** from the daemon. Its `spawnSession`, `awaitSessions`, and `getAgentResult` implementations correctly use HTTP to communicate with a running daemon. These are NOT bugs and should not be changed.
+
+### AdaptiveCoordinatorDeps interface notes
+
+The `AdaptiveCoordinatorDeps` interface (`src/coordinators/adaptive-pipeline.ts:131-169`) and the `CoordinatorDeps` interface it extends (`src/coordinators/pr-review.ts:131+`) define the dep function signatures but make no assumptions about transport. The interface is correct as-is. Only the concrete implementations in `trigger-listener.ts` need to change.
+
+---
+
+## Excluded from Scope
+
+- WorkRail MCP server HTTP calls (out of scope per investigation brief)
+- CLI `run pr-review` HTTP calls (external process, correct design)
+- Webhook server (port 3200) -- no HTTP-to-self calls to this port found
+- `polling-scheduler.ts`, `trigger-router.ts` -- no HTTP-to-self calls found

package/docs/design/layer3b-ghost-nodes-design-candidates.md

@@ -16,7 +16,7 @@ The console's session detail view shows a DAG of workflow execution nodes via `R
 
 ### Core Tensions
 
-1. **Labels vs simplicity**: Step labels (human-readable titles like "Phase 0: Triage and classify") are what make ghost nodes useful. But resolving them requires the compiled workflow, which is a backend I/O operation. Skipping labels is simpler but produces raw step IDs (`routine-context-gathering-depth`) that users can't parse.
+1. **Labels vs simplicity**: Step labels (human-readable titles like "Phase 0: Triage and classify") are what make ghost nodes useful. But resolving them requires the compiled workflow, which is a backend I/O operation. Skipping labels is simpler but produces raw step IDs (`wr.routine-context-gathering-depth`) that users can't parse.
 
 2. **Type safety vs ease**: Adding `isGhost: boolean` to `ConsoleDagNode` is one line but violates "make illegal states unrepresentable" -- ghost steps have no `hasRecap`, `hasFailedValidations`, `isTip`, `parentNodeId`, `createdAtEventIndex`, etc. A separate `ConsoleGhostStep` interface is correct but requires touching both mirrored type files.
 
@@ -91,7 +91,7 @@ The `buildLineageDagModel` signature does NOT need to change -- ghost positionin
 **Summary**: Extract skipped step IDs from `evaluated_condition` SKIP trace items on the frontend; render ghost nodes without step labels (show raw step ID).
 
 **Tensions resolved**: Zero backend changes. No mirrored type file sync needed.
-**Tensions accepted**: No step labels. Ghost nodes show raw IDs like `routine-context-gathering-depth`.
+**Tensions accepted**: No step labels. Ghost nodes show raw IDs like `wr.routine-context-gathering-depth`.
 
 **Boundary**: `session-detail-use-cases.ts` -- new pure function `getSkippedStepsFromTrace(items: readonly ConsoleExecutionTraceItem[]): readonly string[]` returning step IDs. `RunLineageDag.tsx` -- new sub-feature D `useMemo` computes ghost positions from active lineage model, renders absolute-positioned `GhostNodeOverlay` components.
 

package/docs/design/loadSessionNotes-candidates.md

@@ -0,0 +1,108 @@
+# Candidate Directions: loadSessionNotes Test Coverage
+
+**Context:** Issue #393. A complete test implementation (14 tests, all passing) already exists
+uncommitted on disk. The design question is: which approach to land?
+
+---
+
+## Candidate A: Ship the existing implementation as-is (Direct export + vi.mock)
+
+**Summary:** Export `loadSessionNotes` from `src/daemon/workflow-runner.ts` (already done in
+working tree) and ship `tests/unit/workflow-runner-load-session-notes.test.ts` (already written,
+14/14 passing) as a single focused PR closing issue #393.
+
+**Why it fits the path:** This is the `design_first` fast-exit conclusion. The design decision
+was already made by a prior session. Shipping it closes the triggering issue and stops the
+"done but not shipped" daemon loop.
+
+**Strongest evidence for it:**
+- Implementation is 100% complete, verified, and ready. Zero additional work required.
+- `workflow-runner-spawn-agent.test.ts` establishes the vi.mock + vi.hoisted precedent for the
+  same pattern of module-level dependency stubbing.
+- All 7 success criteria (Phase 1f) are satisfied.
+
+**Strongest risk against it:**
+- The export adds a name to `workflow-runner.ts`'s public surface that wasn't there before.
+  If the module is later refactored, the export may need to move. Low probability — the
+  function is already stable and the module is protected.
+- vi.mock is considered a weaker pattern than fakes per project philosophy. The test is
+  correct but not architecturally ideal.
+
+**When it wins:** When the goal is closing #393 cleanly with zero additional implementation
+risk. This is the correct choice for an autonomous agent operating with surgical constraints.
+
+---
+
+## Candidate B: Extract first, then ship (Module extraction + pure fake tests)
+
+**Summary:** Move `loadSessionNotes` (and its constants `MAX_SESSION_NOTE_CHARS`,
+`MAX_SESSION_RECAP_NOTES`) into a new module `src/daemon/session-recap-loader.ts`. Export
+from there. Update the single import in `workflow-runner.ts`. Rewrite
+`tests/unit/workflow-runner-load-session-notes.test.ts` to import from the new module and
+use real fakes instead of vi.mock.
+
+**Why it fits the path:** This is the "stronger reframe" the design_first path asks for.
+It solves the underlying architectural concern: `workflow-runner.ts` is already large
+(3500+ lines), and session recap loading is a separable concern. Better module boundaries
+reduce future vi.mock dependency in tests.
+
+**Strongest evidence for it:**
+- Prior session's discovery (see design doc) explicitly recommended Option A (extraction)
+  over Option B (direct export).
+- Project philosophy: "prefer fakes over mocks" and "compose with small, pure functions."
+- A separate module makes `loadSessionNotes` testable without any vi.mock overhead.
+- `src/daemon/session-recap-loader.ts` would be a natural home alongside
+  `session-recap` related code.
+
+**Strongest risk against it:**
+- Requires undoing the already-implemented working-tree changes and writing ~150 additional
+  lines across two files.
+- `src/daemon/` is listed as a protected directory in AGENTS.md — autonomous modification
+  requires the change to be strictly surgical. Extraction is more invasive than export.
+- Every day this work sits undone, issue #393 stays open and the daemon fires more
+  discovery sessions. Candidate B takes longer.
+- The test file written for Candidate A (vi.mock) is perfectly functional and follows
+  established precedent.
+
+**When it wins:** When the project owner explicitly prefers module extraction over direct
+export for architectural cleanliness, and is willing to accept a slightly larger PR.
+
+---
+
+## What would change the verdict
+
+Switch from Candidate A to Candidate B if **either** of these is true:
+1. The project owner confirms that `src/daemon/session-recap-loader.ts` was the intended
+   approach before implementation started (i.e., Option A from the prior session was
+   the authoritative decision, not merely a recommendation).
+2. A code review of the PR for Candidate A explicitly requests module extraction as a
+   blocking concern before merge.
+
+In the absence of either signal, Candidate A wins: it is already implemented, already
+tested, follows established project precedent, and closes the issue immediately.
+
+---
+
+## Candidate C (considered, not recommended): Make contracts visible via Result types
+
+**Summary:** Change `loadSessionNotes` to return `Result<readonly string[], Error>` instead
+of silently returning `[]` on failure. Force the caller to decide how to handle each failure
+mode explicitly. Tests then assert on `Result` discriminants rather than `[]` shortcircuits.
+
+**Why it is genuinely different:** This reframes the problem from "test the silent-fail
+function" to "make the function's contracts visible at the type level." It addresses the
+root cause: the function hides its failure modes from callers and from tests.
+
+**Why it is not recommended:**
+- Requires changing `loadSessionNotes` signature AND the `Promise.all` caller at line 3498
+  in `src/daemon/workflow-runner.ts` (protected file, more invasive than export-only).
+- The three failure paths are ALL best-effort recoveries — there is no meaningful action
+  the caller can take differently based on which failure occurred. Silent `[]` IS the correct
+  contract for a best-effort context-injection helper.
+- Result types add value when the caller needs to branch. Here, the caller always passes
+  `[]` to `buildSessionRecap`, which returns `''` for empty. The Result type would be
+  immediately `.unwrapOr([])`'d — adding type complexity with no behavioral change.
+- Scope creep relative to issue #393.
+
+**When it wins:** Never, for this specific problem. Might be correct in a future refactor
+that redesigns the session recap injection architecture more broadly.