@exaudeus/workrail 3.27.0 → 3.29.0

package/docs/design/daemon-owns-console-plan.md

@@ -0,0 +1,168 @@
+# Implementation Plan: Daemon-Owned HTTP Console
+
+**Status:** Ready for implementation
+**Branch:** `feat/daemon-owns-console`
+**Date:** 2026-04-16
+
+---
+
+## 1. Problem Statement
+
+The console dashboard (`localhost:3456`) goes down whenever the MCP server crashes or Claude Code restarts, because the console is hosted by whichever MCP server wins the primary election. The daemon -- the actual long-running process -- has no role in hosting the console today. The fix: the daemon starts and owns the HTTP console on port 3456.
+
+---
+
+## 2. Acceptance Criteria
+
+- [ ] When `workrail daemon` starts, the console dashboard is available at `http://localhost:3456/console`
+- [ ] The console stays available as long as the daemon process is running
+- [ ] The console goes down when the daemon stops (SIGTERM or SIGINT)
+- [ ] `POST /api/v2/auto/dispatch` on the daemon console dispatches through the daemon's `TriggerRouter` queue
+- [ ] When port 3456 is already held by an MCP server, the daemon logs a clear human-readable message and continues (trigger listener on 3200 still starts)
+- [ ] When the daemon is running, the MCP server's `HttpServer` becomes secondary (no port conflict, no double console)
+- [ ] The `workrail daemon` process does NOT exit on port 3456 conflict -- only the console is degraded
+
+---
+
+## 3. Non-Goals
+
+- Merging port 3200 (webhook) and port 3456 (console) into a single port
+- Modifying `HttpServer.ts` class internals
+- Streaming live agent output in the console (separate backlog item)
+- Adding token auth to `POST /api/v2/auto/dispatch` (filed as a TODO in console-routes.ts)
+- Adding an integration test for the full daemon startup flow (out of scope, complex process harness needed)
+- Exposing the `timingRingBuffer` / perf endpoint on the daemon console (dev-only, acceptable gap)
+
+---
+
+## 4. Philosophy-Driven Constraints
+
+| Constraint | Source |
+|------------|--------|
+| `startDaemonConsole()` must return `Result<DaemonConsoleHandle, DaemonConsoleError>`, not throw | CLAUDE.md: errors are data |
+| `DaemonConsoleHandle` properties are `readonly` | CLAUDE.md: immutability by default |
+| `ctx: V2ToolContext` is injected at the composition root, not read from env inside the function | CLAUDE.md: dependency injection for boundaries |
+| No `composeServer()` lock check (deferred) -- accept cosmetic double-watcher | CLAUDE.md: YAGNI with discipline |
+| Port conflict is surfaced to the user via log message, not silently swallowed | CLAUDE.md: validate at boundaries |
+
+---
+
+## 5. Invariants
+
+1. The daemon console and MCP server console never both serve traffic on port 3456 simultaneously (enforced by OS port exclusivity -- EADDRINUSE)
+2. When `DaemonConsoleHandle.stop()` is called, the `fs.watch` disposer from `mountConsoleRoutes()` is called before the HTTP server closes
+3. `daemon-console.lock` contains `{ pid: number, port: number }` and is deleted by `stop()` or on daemon exit
+4. The trigger listener on port 3200 starts regardless of whether the daemon console starts successfully
+
+---
+
+## 6. Selected Approach
+
+**Simpler hybrid of Candidate B:** Extract `startDaemonConsole()` with Result type and lifecycle handle. Write `daemon-console.lock`. Do NOT add lock check to `composeServer()` (deferred).
+
+**Runner-up:** Candidate A (inline, no guard). Lost because it doesn't extract the function (poor testability) and doesn't write the lock file (useful for future tooling).
+
+**Rationale:** Follows established `TriggerListenerHandle` pattern exactly. Minimal surface area (2 files). Clean error handling. Deferred `composeServer()` optimization avoids premature complexity.
+
+---
+
+## 7. Vertical Slices
+
+### Slice 1: `src/trigger/daemon-console.ts` (new file)
+
+**Scope:** New module that starts a standalone Express HTTP server on port 3456, mounts console routes, writes the lock file.
+
+**Acceptance criteria:**
+- Exports `DaemonConsoleHandle: { readonly port: number; stop(): Promise<void> }`
+- Exports `DaemonConsoleError: { kind: 'port_conflict'; port: number } | { kind: 'io_error'; message: string }`
+- Exports `startDaemonConsole(ctx: V2ToolContext, options: StartDaemonConsoleOptions): Promise<Result<DaemonConsoleHandle, DaemonConsoleError>>`
+  where `StartDaemonConsoleOptions = { port?: number; triggerRouter?: TriggerRouter; serverVersion?: string; workflowService?: WorkflowService }`
+- Creates Express app with CORS middleware (`cors({ origin: '*', methods: ['GET', 'HEAD', 'OPTIONS', 'POST'], allowedHeaders: ['Content-Type'] })`)
+- Creates `ConsoleService` from `ctx.v2`
+- Calls `mountConsoleRoutes(app, consoleService, workflowService, undefined, undefined, serverVersion, ctx, triggerRouter)`
+- Binds to `127.0.0.1:port` (default 3456)
+- On bind success: writes `~/.workrail/daemon-console.lock = JSON.stringify({ pid: process.pid, port: actualPort })`
+- Returns `{ port: actualPort, stop: async () => { stopWatcher(); server.close(); await releaseLock(); } }`
+- On EADDRINUSE: returns `err({ kind: 'port_conflict', port })`
+- On other bind error: returns `err({ kind: 'io_error', message })`
+- Lock file write failures are non-fatal: log warning, proceed
+
+**Files changed:** `src/trigger/daemon-console.ts` (new)
+
+### Slice 2: `src/cli.ts` daemon command wiring
+
+**Scope:** After `startTriggerListener()` succeeds, call `startDaemonConsole()`. Handle port conflict with clear log. Add shutdown cleanup.
+
+**Acceptance criteria:**
+- `startDaemonConsole(ctx, { triggerRouter: handle.router, workflowService: rawCtx.workflowService })` is called after trigger listener starts
+- On `ok(consoleHandle)`: log `WorkRail console available at http://localhost:${consoleHandle.port}/console`
+- On `err({ kind: 'port_conflict' })`: log `[DaemonConsole] Port ${port} is already held (likely by an MCP server). The daemon is running but the console is unavailable. Restart the MCP server while the daemon is running to enable the daemon console.`
+- On `err({ kind: 'io_error' })`: log the error, continue (non-fatal)
+- In `shutdown()`: if `consoleHandle` exists, `await consoleHandle.stop()` before `await handle.stop()`
+
+**Files changed:** `src/cli.ts`
+
+---
+
+## 8. Test Design
+
+### Unit tests for `startDaemonConsole()`
+
+**File:** `src/trigger/daemon-console.test.ts`
+
+**Test cases:**
+1. **Happy path**: `startDaemonConsole()` with a mock `V2ToolContext` and port=0 (OS-assigned). Verify returns `ok(handle)`, handle.port is non-zero, `GET /api/v2/sessions` returns 200.
+2. **Port conflict**: Start two instances on the same port. Second returns `err({ kind: 'port_conflict' })`.
+3. **stop() cleans up**: After `handle.stop()`, the port is released (can bind again). Verify `stopWatcher` was called (spy).
+4. **Lock file written**: After start, `~/.workrail/daemon-console.lock` exists with correct `{ pid, port }`.
+5. **Lock file deleted on stop**: After `handle.stop()`, lock file is deleted.
+
+**Pattern:** Follow `trigger-listener.test.ts` for test structure. Use `port: 0` for OS-assigned ports to avoid conflicts.
+
+---
+
+## 9. Risk Register
+
+| Risk | Likelihood | Impact | Mitigation |
+|------|-----------|--------|------------|
+| EADDRINUSE because MCP server starts before daemon | High | Low -- daemon still works on 3200 | Clear log message (Slice 2) |
+| stopWatcher disposer not called in stop() | Low | Low -- fd leak | Implementation requirement, verified by test 3 |
+| Lock file on NFS home directory (latency) | Very low | None -- lock write is fire-and-forget | Non-fatal lock write (log warning, proceed) |
+| CORS headers missing on daemon Express app | Was a risk | None | Fixed in Slice 1 |
+
+---
+
+## 10. PR Packaging Strategy
+
+Single PR: `feat/daemon-owns-console`
+- Slice 1 and Slice 2 together (they're co-dependent -- no value without both)
+- Include test file
+- PR description links to `docs/design/daemon-owns-console.md`
+
+**estimatedPRCount:** 1
+
+---
+
+## 11. Philosophy Alignment
+
+| Slice | Principle | Status |
+|-------|-----------|--------|
+| Slice 1 | Errors are data | Satisfied -- `Result<DaemonConsoleHandle, DaemonConsoleError>` |
+| Slice 1 | Immutability by default | Satisfied -- `readonly port` |
+| Slice 1 | Dependency injection | Satisfied -- ctx injected, no env reads inside function |
+| Slice 1 | Compose with small pure functions | Satisfied -- delegates to `mountConsoleRoutes()` |
+| Slice 2 | Validate at boundaries | Satisfied -- port conflict logged with clear UX message |
+| Slice 2 | YAGNI with discipline | Satisfied -- no composeServer() lock check |
+
+---
+
+## 12. Follow-up Tickets
+
+1. **Add token auth to `POST /api/v2/auto/dispatch`** -- the daemon console makes the always-up no-auth endpoint more exposed (existing TODO in console-routes.ts)
+2. **Add `composeServer()` lock check** -- if MaxListenersExceededWarning is observed in practice during daemon+MCP co-runs, add the lock file check to prevent watcher accumulation
+3. **NFS latency mitigation** -- if someone reports slow daemon startup on NFS home dir, add a 100ms timeout on the lock file write
+
+---
+
+**planConfidenceBand:** High
+**unresolvedUnknownCount:** 0

package/docs/design/daemon-owns-console-review.md

@@ -0,0 +1,91 @@
+# Design Review Findings: Daemon-Owned HTTP Console
+
+**Design doc:** `docs/design/daemon-owns-console.md`
+**Review date:** 2026-04-16
+
+---
+
+## Tradeoff Review
+
+### T1: Async file I/O in startup path
+**Status:** Acceptable.
+`composeServer()` already does far heavier I/O at startup (keyring load, token alias store). A `fs.readFile` on a ~100-byte lock file is negligible on local disk. Edge case: NFS home directory. Mitigated by try-catch with graceful fallback (treat missing/unreadable lock as no-daemon).
+
+### T2: New lock file convention
+**Status:** Acceptable.
+Pattern is identical to `dashboard.lock`. Stale lock after daemon crash fully mitigated by pid-liveness check (`process.kill(pid, 0)`). Directory creation must use `{ recursive: true }` to handle fresh installs.
+
+### T3: `timingRingBuffer` unavailable in daemon console
+**Status:** Acceptable.
+Perf endpoint (`/api/v2/perf/tool-calls`) mounts but returns empty observations in daemon console context. This is dev-mode only. A log note at daemon console startup makes the limitation visible.
+
+---
+
+## Failure Mode Review
+
+### FM1: Stale lock after daemon crash
+**Coverage:** Fully handled by pid-liveness check. MCP server proceeds to mount normally after crash.
+
+### FM2: EADDRINUSE when daemon starts after MCP server (most likely in practice)
+**Coverage:** Handled -- `startDaemonConsole()` returns `err({ kind: 'port_conflict' })`. Daemon still runs (trigger listener on 3200 works). Console unavailable until MCP server releases port.
+**Gap:** No user-facing log message explaining how to recover. Needs: `[DaemonConsole] Port 3456 held by MCP server; restart the MCP server with the daemon already running to enable the daemon console.`
+
+### FM3: Startup race (daemon writes lock, MCP reads stale state)
+**Coverage:** Accepted as cosmetic -- MCP server mounts routes on a server that never listens (secondary path). One extra file watcher per concurrent MCP start. Bounded, not accumulating.
+
+### FM4: `stopWatcher` disposer not called on daemon stop
+**Coverage:** Implementation requirement: `DaemonConsoleHandle.stop()` must call the disposer returned by `mountConsoleRoutes()`. Same pattern as `HttpServer._runStop()` calling `_routeDisposers`.
+
+---
+
+## Runner-Up / Simpler Alternative Review
+
+**Revised recommendation:** The simpler hybrid (Candidate B minus `composeServer()` lock check) is sufficient:
+- Extracts `startDaemonConsole()` with Result type and clean stop lifecycle
+- Writes `daemon-console.lock` (available for future tooling)
+- Does NOT add lock check to `composeServer()` -- deferred (YAGNI)
+- 2 files changed (new `daemon-console.ts`, modified `cli.ts`) instead of 3
+
+The cosmetic double-watcher from the startup race is acceptable. MaxListenersExceededWarning would require 10+ simultaneous MCP server starts -- implausible.
+
+---
+
+## Philosophy Alignment
+
+| Principle | Status |
+|-----------|--------|
+| Errors are data | Satisfied -- `Result<DaemonConsoleHandle, DaemonConsoleError>` |
+| YAGNI with discipline | Satisfied -- deferred `composeServer()` lock check |
+| Immutability by default | Satisfied -- readonly handle properties |
+| Dependency injection | Satisfied -- `ctx: V2ToolContext` injected at composition root |
+| Make illegal states unrepresentable | Acceptable tension -- process-boundary invariants cannot be type-enforced |
+| Validate at boundaries | Minor tension -- `composeServer()` skips daemon check. Consequence is cosmetic. |
+
+---
+
+## Findings
+
+### Yellow: Missing user-facing log on port conflict
+When `startDaemonConsole()` returns `port_conflict`, the daemon CLI should log a clear message explaining the start-order dependency. Without this, users will be confused why the console isn't available.
+
+### Yellow: `stopWatcher` disposer must be called in `stop()`
+Implementation-level requirement: the disposer returned by `mountConsoleRoutes()` must be stored in the `DaemonConsoleHandle` closure and called in `stop()`. Missing this leaks an `fs.watch` on the sessions directory.
+
+### Yellow: CORS headers needed on daemon console Express app
+`mountConsoleRoutes()` does not add CORS headers -- that's the caller's responsibility. The daemon console's Express app must add CORS middleware (same as `HttpServer.setupMiddleware()`) or browser clients will be blocked when accessing from a dev tool that runs on a different origin.
+
+---
+
+## Recommended Revisions
+
+1. In `startDaemonConsole()`, add CORS middleware (`cors({ origin: '*', methods: ['GET', 'HEAD', 'OPTIONS'] })`) to the Express app before calling `mountConsoleRoutes()`.
+2. In `cli.ts daemon`, log a clear message when `startDaemonConsole()` returns `port_conflict`.
+3. Ensure `DaemonConsoleHandle.stop()` calls the `stopWatcher` disposer before closing the server.
+
+---
+
+## Residual Concerns
+
+1. **NFS home directory latency**: If `~/.workrail/` is on a slow network filesystem, the lock file write at daemon startup may add visible latency. Not a correctness concern.
+2. **No integration test**: The daemon startup path (`workrail daemon` command) is not covered by existing automated tests. The new `startDaemonConsole()` function should have unit tests, but end-to-end daemon startup testing is out of scope for this task.
+3. **Future: when to add the `composeServer()` lock check**: If `MaxListenersExceededWarning` is observed in practice during daemon+MCP co-runs, the lock check should be added to `composeServer()` at that point.

package/docs/design/daemon-owns-console.md

@@ -0,0 +1,195 @@
+# Design: Daemon-Owned HTTP Console
+
+**Status:** Discovery complete, ready for implementation
+**Date:** 2026-04-16
+
+---
+
+## Problem Understanding
+
+### Core tensions
+
+1. **Daemon-owned console vs. DI-managed HttpServer**: The `HttpServer` class in DI is a singleton with primary/secondary election, heartbeat, and lock logic. The daemon already uses DI. But `HttpServer` has `SessionManager` injected as a required dependency -- the daemon's use case is different (it needs `ConsoleService` routes from `console-routes.ts`, not the old V1 session routes). Tension: use the existing `HttpServer` class (complex, unneeded deps) vs. a minimal standalone server (simpler, parallel infrastructure).
+
+2. **`mountRoutes()` called before `start()` in `composeServer()`**: Today the MCP server calls `mountRoutes()` in `composeServer()` before the transport entry point calls `start()`. If the daemon holds port 3456, `start()` returns `null` (secondary), but `mountRoutes()` was already called -- the SSE file watcher and enrichment callback are already running on a server that will never serve traffic. This causes file descriptor waste and potential `MaxListenersExceededWarning` on stderr (which corrupts the MCP stdio channel).
+
+3. **Lock file reliability vs. complexity**: A `daemon-console.lock` file is the most explicit signal, but it adds a new file, a new lifecycle, and a new failure mode (stale lock after daemon crash). The existing `dashboard.lock` in `HttpServer.ts` already handles this pattern. The lock file check must include a pid-liveness probe (same pattern as `HttpServer.shouldReclaimLock()`) to handle stale locks after daemon crash.
+
+4. **AUTO dispatch queue ownership**: `POST /api/v2/auto/dispatch` uses `triggerRouter.dispatch()` when a `TriggerRouter` is provided. If the daemon owns the console, it should pass its `TriggerRouter` instance (from `TriggerListenerHandle.router`) so dispatched workflows go through the daemon's serialized queue, not direct `runWorkflow()`.
+
+### What makes this hard
+
+`mountConsoleRoutes()` registers `fs.watch` on the sessions directory **immediately** on call -- not just when the server starts listening. So even in the MCP server's secondary path (where it never serves HTTP traffic), the watcher is live. A naive fix (guard on whether `start()` returns null) doesn't work because `start()` is called from the transport entry point, after `composeServer()` has already called `mountRoutes()`.
+
+The correct fix requires preventing `mountRoutes()` from being called at all in the secondary path, which means the mount guard must live in `composeServer()` or the mount call must move to after `start()` in the transport entry point.
+
+### Likely seam
+
+- Daemon console startup: `cli.ts daemon` command action (composition root)
+- MCP server mount guard: `composeServer()` in `server.ts` OR `stdio-entry.ts` after `httpServer.start()`
+
+---
+
+## Philosophy Constraints
+
+From `CLAUDE.md` (authoritative):
+- **YAGNI with discipline**: don't create elaborate abstractions, but fix real seams when they're wrong
+- **Errors are data**: new `startDaemonConsole()` should return a `Result` type, not throw
+- **Explicit domain types**: `DaemonConsoleHandle = { port: number; stop(): Promise<void> }` mirrors `TriggerListenerHandle`
+- **Validate at boundaries**: port-conflict and lock-check are boundary validations, belong in the composition root
+
+Repo patterns (consistent with CLAUDE.md):
+- `trigger-listener.ts` uses `http.createServer(express())` directly -- the daemon console follows this pattern
+- Lock files use `~/.workrail/` base directory (`DashboardHeartbeat.ts`, `HttpServer.ts`)
+- Result types (`ok`/`err`) used consistently
+
+No philosophy conflicts observed.
+
+---
+
+## Impact Surface
+
+Changes that must stay consistent:
+- `TriggerListenerHandle` (no change -- the daemon console handle is a separate type)
+- `mountConsoleRoutes()` signature (no change -- all params remain optional)
+- `composeServer()` return type (no change -- `mountRoutes()` call moves or is guarded)
+- `stdio-entry.ts` transport entry point (requires `mountRoutes()` + `finalize()` after `start()` if daemon not live)
+- Any other transport entry points that call `httpServer.start()` must be checked
+
+Other transport entry points to check: `src/mcp/transports/` -- need to enumerate to ensure none are missed.
+
+---
+
+## Candidates
+
+### Candidate A: Minimal inline console in daemon, no MCP guard
+
+**Summary:** In `cli.ts daemon`, after `startTriggerListener()`, inline `express()` + `mountConsoleRoutes()` + `http.createServer().listen(3456)`. No changes to `server.ts` or `HttpServer.ts`.
+
+**Tensions resolved:** Daemon owns the console. Console stays up as long as daemon runs.
+
+**Tensions accepted:** Double SSE watcher problem persists (MCP server still calls `mountRoutes()` unconditionally). Port 3456 EADDRINUSE if MCP server is already running -- daemon console silently fails unless error is surfaced.
+
+**Boundary:** `cli.ts daemon` action -- correct composition root.
+
+**Failure mode:** EADDRINUSE when MCP server starts before daemon. Silent watcher accumulation in secondary MCP server processes.
+
+**Repo pattern:** Follows `trigger-listener.ts` inline Express pattern exactly.
+
+**Gains/losses:** Minimal diff (~25 lines, 1 file). Loses: no error handling, no watcher guard.
+
+**Scope:** Too narrow -- leaves watcher leak unfixed.
+
+**Philosophy:** Honors YAGNI. Conflicts with "validate at boundaries" (no EADDRINUSE feedback).
+
+---
+
+### Candidate B: `startDaemonConsole()` + `daemon-console.lock` + move `mountRoutes()` to transport entry (RECOMMENDED)
+
+**Summary:** New `src/trigger/daemon-console.ts` exports `startDaemonConsole(ctx, options)` returning `Result<DaemonConsoleHandle, DaemonConsoleError>`. Writes `~/.workrail/daemon-console.lock` with `{ pid, port }`. In `stdio-entry.ts` (and other transports), move `mountRoutes()` + `finalize()` to after `httpServer.start()`; skip when daemon-console.lock has a live pid. `cli.ts daemon` calls `startDaemonConsole()` after trigger listener starts.
+
+**Tensions resolved:** Daemon owns 3456 with explicit lifecycle. MCP server SSE watcher is never registered when daemon is live. Clean error handling on port conflict. Testable via extracted function.
+
+**Tensions accepted:** More surface area -- new file, new lock convention, change to transport entry points.
+
+**Boundary:** `cli.ts` for daemon startup, `stdio-entry.ts` for MCP mount guard.
+
+**Failure mode:** Stale lock after daemon crash -> MCP server perpetually skips console mount. Mitigated by pid-liveness check (same pattern as `HttpServer.shouldReclaimLock()`).
+
+**Repo pattern:** `DaemonConsoleHandle` mirrors `TriggerListenerHandle`. Lock file follows `dashboard.lock` pattern. Moving `mountRoutes()` to transport entry is an architectural improvement, not a new pattern.
+
+**Gains/losses:** Clean lifecycle, no double watchers, testable, proper error reporting. Loses: 4 files changed instead of 1.
+
+**Scope:** Best-fit.
+
+**Philosophy:** Honors YAGNI with discipline (seam was architecturally wrong, fixing it is correct), errors as data, explicit domain types, validate at boundaries.
+
+---
+
+### Candidate C: Daemon uses full `HttpServer` class with env var gate
+
+**Summary:** Daemon starts the `HttpServer` DI singleton. Sets `WORKRAIL_DAEMON_CONSOLE=3456`; MCP server checks this in `composeServer()` and skips `mountRoutes()`.
+
+**Tensions resolved:** Reuses existing `HttpServer` infrastructure. No new lock file.
+
+**Tensions accepted:** `HttpServer` requires `SessionManager` injection (unneeded). Env var check is less reliable than a lock file (inherited by child processes, not owned by a specific process). Daemon must run full primary election machinery unnecessarily.
+
+**Failure mode:** `SessionManager` initialization overhead. Env var persists after daemon death if MCP server is a subprocess.
+
+**Repo pattern:** Forces `HttpServer` into a use case it wasn't designed for. Env-var coupling between processes is an antipattern in this codebase.
+
+**Scope:** Too broad.
+
+**Philosophy:** Conflicts with YAGNI (forces unneeded `SessionManager` dep), conflicts with "make illegal states unrepresentable" (env var as cross-process signal is fragile).
+
+---
+
+## Comparison and Recommendation
+
+| | A | B | C |
+|---|---|---|---|
+| Daemon owns 3456 | Yes | Yes | Yes |
+| No MCP watcher leak | No | Yes | Fragile |
+| Error handling | No | Yes | Partial |
+| Testable | Poor | Good | Poor |
+| Files changed | 1 | 4 | 5+ |
+| Follows repo patterns | Yes | Yes | Forced fit |
+
+**Recommendation: Candidate B**
+
+The watcher leak is the key differentiator. `fs.watch` in secondary-mode MCP server processes doesn't serve traffic but wastes file descriptors and generates `MaxListenersExceededWarning` to stderr -- which is the MCP stdio channel, and stderr writes corrupt it. This is a real crash driver (referenced in the backlog). Candidate A leaves it unfixed.
+
+Candidate B moves `mountRoutes()` to after `httpServer.start()` in the transport entry point, which is architecturally correct (the routes should only be mounted if the server is actually listening). This is not speculative -- it fixes a real seam that was wrong.
+
+### Concrete implementation shape
+
+**New file: `src/trigger/daemon-console.ts`**
+```typescript
+export interface DaemonConsoleHandle { port: number; stop(): Promise<void>; }
+export type DaemonConsoleError = { kind: 'port_conflict'; port: number } | { kind: 'io_error'; message: string };
+export async function startDaemonConsole(
+  ctx: V2ToolContext,
+  options: { port?: number; triggerRouter?: TriggerRouter; serverVersion?: string }
+): Promise<Result<DaemonConsoleHandle, DaemonConsoleError>>
+```
+- Creates `ConsoleService` from `ctx.v2`
+- Creates Express app, calls `mountConsoleRoutes(app, consoleService, ctx.workflowService, undefined, undefined, serverVersion, ctx, triggerRouter)`
+- Writes `~/.workrail/daemon-console.lock: { pid, port }`
+- Binds to port 3456 (default) on `127.0.0.1`
+- Returns handle with `stop()` that closes server + deletes lock file + calls stopWatcher disposer
+
+**Modified: `src/mcp/server.ts` `composeServer()`**
+- Remove the `if (ctx.v2 && ctx.httpServer && ...) { ctx.httpServer.mountRoutes(...); ctx.httpServer.finalize(); }` block
+- Export a new `mountConsoleRoutesIfOwner(httpServer, ctx, timingRingBuffer, toolCallsPerfFile, serverVersion): void` function that performs the lock check and mount
+
+**Modified: `src/mcp/transports/stdio-entry.ts`**
+- After `httpServer.start()` call, invoke `mountConsoleRoutesIfOwner(httpServer, ctx, ...)`
+
+**Modified: `src/cli.ts` daemon command**
+- After `startTriggerListener()` succeeds, call `startDaemonConsole(ctx, { triggerRouter: handle.router })`
+- In `shutdown()`, call `await consoleHandle.stop()` before `handle.stop()`
+
+---
+
+## Self-Critique
+
+**Strongest counter-argument against B:**
+Moving `mountRoutes()` from `composeServer()` to transport entry points creates a contract where every transport entry point must remember to call `mountConsoleRoutesIfOwner()` after `start()`. If a new transport entry point is added and misses this call, the console silently doesn't mount. Candidate A avoids this risk entirely.
+
+**Pivot condition:** If there are more than 2 transport entry points (stdio + HTTP), or if any transport entry point has complex branching that makes inserting the mount call risky, fall back to a lock-file check inside `composeServer()` (without moving `mountRoutes()`). The check would be: read `daemon-console.lock` before `mountRoutes()`; if daemon pid is live, skip. This is slightly worse (the watcher leak persists in the race window at startup) but avoids modifying transport entry points.
+
+**Narrower option (A) loses because:** The double-watcher problem is a real bug that corrupts the MCP stdio channel. Leaving it unfixed would mean the daemon-console feature creates a new crash scenario (MCP server logs watchers to stderr while the daemon console is up, corrupting the JSON channel).
+
+**Assumption that would invalidate this design:** If `MaxListenersExceededWarning` from `fs.watch` accumulation is NOT the actual mechanism for MCP stdio corruption, then Candidate A's simplicity wins. But the watcher accumulation is observable (each `mountConsoleRoutes()` call adds one watcher), so the fix is correct regardless.
+
+---
+
+## Open Questions for the Main Agent
+
+1. **Transport entry points inventory**: Are there transport entry points beyond `stdio-entry.ts`? Check `src/mcp/transports/` for all files that call `httpServer.start()`. Any missed entry point will silently drop console mounting.
+
+2. **Lock file name convention**: Use `daemon-console.lock` (new, explicit) or repurpose/extend `dashboard.lock` (existing, but conflates daemon console with MCP primary)? The latter avoids a new file but creates coupling between two different ownership concepts.
+
+3. **`timingRingBuffer` for daemon console**: The daemon doesn't create a `ToolCallTimingRingBuffer`. Pass `undefined` to `mountConsoleRoutes()` for this param. The `WORKRAIL_DEV=1` perf endpoint will be unavailable from the daemon console -- is this acceptable?
+
+4. **CORS for daemon console**: The standalone Express server in `startDaemonConsole()` should add CORS headers (same as `HttpServer.setupMiddleware()`). The `mountConsoleRoutes()` function doesn't add CORS itself -- it relies on the caller's Express app middleware.

package/docs/design/data-model-erd.md

@@ -0,0 +1,11 @@
+# Data Model (ERD) for Native Context Management
+
+> **Not pursuing**
+>
+> WorkRail is not planning to implement native context management.
+>
+> This file is kept only as a stable tombstone so old links do not break.
+>
+> See:
+> - `docs/roadmap/legacy-planning-status.md`
+> - `docs/plans/native-context-management-epic.md`

package/docs/design/design-candidates-consolidate-dev-staleness.md

@@ -0,0 +1,98 @@
+# Design Candidates: Consolidate WORKRAIL_DEV_STALENESS into WORKRAIL_DEV
+
+## Problem Understanding
+
+**Goal:** Remove the separate `WORKRAIL_DEV_STALENESS` env var so that `WORKRAIL_DEV=1` controls all dev features, including staleness visibility for all workflow categories.
+
+**Core tensions:**
+1. Module-load-time vs call-time evaluation -- `DEV_STALENESS` is evaluated once at module load; `isDevMode()` evaluates per call via DI. Not a real tension in practice because the flag doesn't change mid-request.
+2. Backward compat vs clean design -- `WORKRAIL_DEV_STALENESS` was never publicly documented and never allowed in `~/.workrail/config.json`. Dropping it is clean with essentially zero user impact.
+
+**Likely seam:** The default parameter value of `shouldShowStaleness()` in `src/mcp/handlers/v2-workflow.ts` line 55. This is both where the symptom appears and the correct fix location.
+
+**What makes it hard:** Nothing structurally hard. The main subtlety is that the replacement (`isDevMode()`) is a function, not a constant, so it must be in a default parameter (call-time) rather than a module-level assignment (load-time).
+
+---
+
+## Philosophy Constraints
+
+From `CLAUDE.md` and `AGENTS.md`:
+- **Dependency injection for boundaries** -- use DI-injected flags, not raw `process.env` reads in handler code.
+- **Determinism** -- call-time evaluation of `isDevMode()` is deterministic; the flag doesn't change during a request.
+- **YAGNI** -- drop `WORKRAIL_DEV_STALENESS` entirely; no deprecated alias needed.
+- **Document "why", not "what"** -- update JSDoc to explain the consolidation.
+
+No conflicts between stated philosophy and repo patterns.
+
+---
+
+## Impact Surface
+
+**Must stay consistent:**
+- `shouldShowStaleness()` exported function signature -- stays the same (optional `devMode` param)
+- `tests/unit/mcp/workflow-staleness.test.ts` -- tests pass `devMode` explicitly, no impact
+- `buildV2WorkflowListItem` (line 528) and inspect handler (line 435) -- both call `shouldShowStaleness(visibility?.category)` with no second arg; they will now get `isDevMode()` as the default
+
+**Docs requiring updates:**
+- `src/config/feature-flags.ts` line 109: description says staleness is controlled by `WORKRAIL_DEV_STALENESS` separately
+- `AGENTS.md` line 141: documents `WORKRAIL_DEV_STALENESS=1`
+- `docs/authoring-v2.md` line 495: says `Set WORKRAIL_DEV_STALENESS=1`
+- `docs/configuration.md` line 44: lists `WORKRAIL_DEV_STALENESS` as excluded key
+- `src/config/config-file.ts` lines 10, 32: comments mention `WORKRAIL_DEV_STALENESS`
+
+---
+
+## Candidates
+
+### Candidate 1: Change default parameter to `isDevMode()` (recommended)
+
+**Summary:** Remove the `DEV_STALENESS` const; change `shouldShowStaleness`'s default from `= DEV_STALENESS` to `= isDevMode()`; import `isDevMode`.
+
+- **Tensions resolved:** Eliminates second env var; staleness now flows through DI like other dev features.
+- **Accepts:** Tiny per-call DI resolution overhead (already done by other dev features; negligible).
+- **Boundary:** Default parameter in `shouldShowStaleness` -- exactly where the flag is consumed.
+- **Failure mode:** If `isDevMode()` is called in a context where DI isn't initialized. Mitigated by `dev-mode.ts` fallback to `process.env['WORKRAIL_DEV']`.
+- **Repo pattern:** Follows -- perf timing and perf endpoint already use `isDevMode()` at call time.
+- **Gain:** Single flag; DI-consistent; config-file compatible (`WORKRAIL_DEV` can be set in `~/.workrail/config.json`).
+- **Give up:** `WORKRAIL_DEV_STALENESS` env var no longer works. Acceptable since it was never publicly documented.
+- **Scope judgment:** best-fit.
+- **Philosophy:** Honors DI-for-boundaries, determinism, YAGNI. No conflicts.
+
+### Candidate 2: Pass `isDevMode()` explicitly at each call site
+
+**Summary:** Remove `DEV_STALENESS` const; pass `isDevMode()` as the second argument at each of the 2 call sites rather than via default parameter.
+
+- **Tensions resolved:** Same runtime behavior as Candidate 1; slightly more explicit at call sites.
+- **Accepts:** More code to maintain; must update 2 call sites instead of 1 location.
+- **Failure mode:** Easy to miss a call site if more are added later.
+- **Scope judgment:** Slightly too verbose -- 2 call sites, no benefit over Candidate 1.
+- **Philosophy:** Marginally better on "explicit over implicit" but outweighed by the existing default-parameter design.
+
+---
+
+## Comparison and Recommendation
+
+Both candidates produce identical runtime behavior. Candidate 1 is preferred:
+- Touches fewer lines (1 location vs 3)
+- Preserves the existing public API of `shouldShowStaleness` (tests already pass explicit values)
+- Follows the established pattern in the file
+
+**Recommendation: Candidate 1**
+
+---
+
+## Self-Critique
+
+**Strongest counter-argument:** Candidate 2 makes the dev flag visible at the call site, which is slightly more transparent. With only 2 call sites, this would be readable. However, the existing default-parameter design was deliberately chosen for testability, and Candidate 1 respects that invariant.
+
+**Narrower option that could work:** Only update the source code but leave the docs unchanged. Would still work but creates documentation drift -- rejected.
+
+**Broader option:** Inject `devMode` into the handler via `ToolContext` and thread it through. This would be a larger architectural change with no benefit for a single boolean flag that already has a clean accessor via `isDevMode()`.
+
+**Assumption that would invalidate:** If `isDevMode()` DI resolution became unreliable or slow. Currently it's a simple map lookup; this assumption is safe.
+
+---
+
+## Open Questions
+
+None. The path is clear.

package/docs/design/design-candidates-walk-cache-depth-limit.md

@@ -0,0 +1,80 @@
+# Design Candidates: Walk Cache, Depth Limit, Skip Dirs, Graceful Degradation
+
+## Problem Understanding
+
+### Tensions
+1. **Walk cancellation vs simplicity**: `withTimeout` races the promise but cannot cancel the Node.js fs walk. The walk continues in the background. Subsequent calls within the 30s TTL window will hit the cache (acceptable tradeoff; must be documented).
+2. **Cache freshness vs staleness window**: A 30s TTL means a `.workrail` dir created inside a remembered root within that window returns stale (missing) results. Spec explicitly accepts this.
+3. **Module-level mutable state vs testability**: The cache is process-global. `clearWalkCacheForTesting()` is the escape hatch for tests.
+4. **Graceful degradation vs error visibility**: `listRememberedRoots` currently throws, which is actually LESS visible (propagates uncaught). Changing to return `[]` + log is more operator-visible.
+
+### Likely Seam
+All changes are at the correct seams: `request-workflow-reader.ts` owns walk/discovery/cache logic; `v2-workflow.ts` owns handler error boundaries.
+
+### What Makes This Hard
+- **Depth guard placement**: The spec says "A `.workrail` entry at depth 5 must still be discoverable -- the limit stops recursing into children, not reading the current directory's entries." If the guard is placed at the TOP of `walkForRootedWorkflowDirectories` (`if (depth >= MAX_WALK_DEPTH) return`), then `.workrail` at depth 5 is missed (the function returns before reading any entries). The correct placement is INSIDE the loop, AFTER the `.workrail` check, BEFORE the recursive call:
+  ```
+  if (entry.name === '.workrail') { ... continue; }
+  if (depth >= MAX_WALK_DEPTH) { /* log if dev mode */ continue; }
+  await walkForRootedWorkflowDirectories(entryPath, discoveredPaths, depth + 1);
+  ```
+
+## Philosophy Constraints
+- **Errors are data**: `listRememberedRoots` must return `[]` instead of throwing (matching `listManagedSourceRecords` pattern)
+- **Immutability by default**: `SKIP_DIRS` is a `const Set` (immutable after module load)
+- **Document why not what**: Comments required on cache TTL tradeoff, non-cancelling timeout, why `listRememberedRoots` returns instead of throwing
+- **Validate at boundaries**: Timeout and cache are boundary concerns in `createWorkflowReaderForRequest`
+- **Module-level mutable Map**: Technically violates "immutability by default" but is the correct tradeoff for a process-global TTL cache; mutation is minimal and confined
+
+## Impact Surface
+- Existing tests for `discoverRootedWorkflowDirectories` use unique `fs.mkdtempSync` paths so they will always miss the cache (no cross-contamination)
+- New cache tests must call `clearWalkCacheForTesting()` in `afterEach`
+- Both `handleV2ListWorkflows` and `handleV2InspectWorkflow` in `v2-workflow.ts` have the same `createWorkflowReaderForRequest` bare-await pattern -- both need fixing
+
+## Candidates
+
+### Candidate 1: Implement as Specified (only real candidate)
+
+**Summary:** Apply all 10 changes exactly as specified, following established patterns already present in the file.
+
+**Tensions resolved:**
+- Walk cancellation: documented with comment, accepted as by-design
+- Cache freshness: 30s TTL with explicit stale-window comment
+- Error visibility: `listRememberedRoots` logs and returns `[]`
+- Handler error boundary: try/catch returning `errNotRetryable`
+
+**Boundary:** `request-workflow-reader.ts` for walk/discovery/cache; `v2-workflow.ts` for handler errors.
+
+**Failure mode:** Depth guard placement. If placed at top of function, `.workrail` at depth 5 is missed. Must be inside the loop after `.workrail` check.
+
+**Repo pattern:** Follows. `listManagedSourceRecords` already does graceful `{ records: [], storeError }`. `withTimeout` already in `v2-workflow.ts`. `errNotRetryable` used throughout.
+
+**Gains:** Bounded walk, process-level caching, handlers never throw unexpectedly, operator-visible walk errors.
+
+**Losses:** Module-level mutable state (acceptable).
+
+**Scope:** Best-fit. Changes confined to two specified files plus test file.
+
+**Philosophy:** Honors errors-as-data, immutability for the Set, document-why, validate-at-boundaries. Minor conflict with immutability for the module-level Map (accepted, documented).
+
+## Comparison and Recommendation
+
+Only one real candidate. The spec fully prescribes the design -- data structures (Map with TTL, Set for skip dirs), function signatures (depth param), and behavior (graceful degradation). No architectural choice needed.
+
+**Recommendation:** Implement as specified.
+
+## Self-Critique
+
+**Strongest counter-argument:** The module-level Map cache could instead be passed as a dependency injection parameter to `discoverRootedWorkflowDirectories`. This would be stricter about "immutability by default". It loses because: no repo precedent for injecting caches, the cache is a pure optimization, `clearWalkCacheForTesting()` provides sufficient testability.
+
+**Narrower option:** Just add depth limit + skip dirs, skip the cache and timeout. Loses because the spec requires both.
+
+**Broader option:** Make TTL configurable via env var. Not justified -- YAGNI applies, no evidence of multiple TTL requirements.
+
+**Invalidating assumption:** If `discoverRootedWorkflowDirectories` were called from multiple threads simultaneously, the module-level Map would need synchronization. Node.js is single-threaded so this does not apply.
+
+**Pivot condition:** If depth-5 boundary test fails, the guard is likely placed at the top of the function instead of inside the loop.
+
+## Open Questions for the Main Agent
+
+None -- the spec is complete and the implementation path is clear.