@exaudeus/workrail 3.40.0 → 3.42.0

package/docs/discovery/steer-endpoint-design-candidates.md

@@ -0,0 +1,288 @@
+# Design Candidates: POST /api/v2/sessions/:sessionId/steer
+
+> Raw investigative material for main agent synthesis. Not a final decision.
+
+---
+
+## Problem Understanding
+
+### Core Tensions
+
+**T1: Closure-scoped state vs. HTTP endpoint accessibility.**
+`pendingSteerParts` (the fixed form of `pendingSteerText`) lives inside the `runWorkflow()` closure
+in `src/daemon/workflow-runner.ts`. The HTTP handler lives in `mountConsoleRoutes()` in
+`src/v2/usecases/console-routes.ts`. These modules have no shared reference. The naive fix
+(module-level `Map`) violates the per-instance isolation invariant that motivated moving `sseClients`
+into the `mountConsoleRoutes()` closure: module-level state is shared across test instances and
+hypothetical daemon restarts, causing cross-session contamination. Solution: explicit DI.
+
+**T2: Silent discard on `pendingSteerText` overwrite.**
+The R1 finding from `design-review-findings-mid-session-signaling.md`: `onAdvance()` currently does
+`pendingSteerText = stepText` (assignment). A coordinator steer written between step advances would be
+silently overwritten when `onAdvance()` fires. Fix: rename to `pendingSteerParts: string[]` and use
+`push()`. The turn_end subscriber joins all parts and clears. Order: step text first (workflow advance
+is primary), coordinator text appended. This is a blocking prerequisite for the endpoint.
+
+**T3: Daemon-only semantics vs. shared `mountConsoleRoutes` function.**
+The steer endpoint is only meaningful for daemon-managed sessions. The standalone console must NOT
+expose it. If the endpoint is always registered (even in standalone mode), it returns 404 for every
+call -- silently wrong. Better: the endpoint is structurally absent when no steer registry is injected.
+
+**T4: Registry lifecycle -- registration timing gap.**
+The registry key is the WorkRail `sess_xxx` ID, decoded from the continueToken after
+`executeStartWorkflow()` returns. For sessions using `_preAllocatedStartResponse` (dispatch path),
+the session ID is already decoded before `runWorkflow()` is called. For sessions that call
+`executeStartWorkflow()` internally, there is a brief window (< 1 turn) where the session exists but
+is not yet in the registry. v1 acceptable (documented); coordinator should retry once on 404.
+
+### Likely Seam
+
+The real seam is the `turn_end` subscriber in `runWorkflow()` at lines ~2523-2531. This is both where
+the fix lands (drain `pendingSteerParts`) AND where steer delivery happens. The HTTP endpoint is
+purely the write path into the array; the delivery mechanism (`agent.steer()`) is unchanged.
+
+### What Makes This Hard
+
+1. The registry must be constructed by the daemon layer and passed to BOTH the HTTP server and the
+   workflow runner. These are currently linked only through `runWorkflow()` being called from
+   `console-routes.ts` or `TriggerRouter`. Threading a new dependency through both callers requires
+   identifying all call sites (`daemon-console.ts`, `console-routes.ts` direct dispatch).
+
+2. JavaScript single-threadedness means there is NO race condition between the HTTP write path and the
+   turn_end read path -- Node.js event loop serializes them. This is the key insight junior devs miss;
+   they add unnecessary locking.
+
+3. The `pendingSteerParts` array-based fix changes the join semantics: multiple concurrent steers from
+   the coordinator (if the coordinator calls the endpoint twice before the next turn_end) both land.
+   This is correct behavior but must be explicit in the code.
+
+---
+
+## Philosophy Constraints
+
+Sources: `/Users/etienneb/CLAUDE.md`, `docs/discovery/design-review-findings-mid-session-signaling.md`,
+existing `console-routes.ts` route patterns.
+
+- **DI for boundaries**: The registry must be injected, not imported as a module singleton.
+  Existing pattern: `triggerRouter?: TriggerRouter` in `mountConsoleRoutes()`.
+- **Errors as data**: The lookup result should be a typed value (`'ok' | 'not_found'`), not a boolean
+  or thrown exception. HTTP handler maps to 200/404.
+- **Explicit domain types over primitives**: A named `SteerRegistry` type is preferred over a raw
+  `Map<string, (text: string) => void>` even if functionally identical.
+- **Make illegal states unrepresentable**: Standalone console should structurally not have a steer
+  registry, making it impossible to accidentally steer non-daemon sessions.
+- **YAGNI**: No auth token in v1 (documented per O3 finding). No `waitForCoordinator` blocking gate.
+  No crash recovery for in-flight steers.
+- **Validate at boundaries**: Endpoint validates `{ text: string }` body before calling invoke.
+
+**Conflicts:** None found. All three candidates can be made to honor these principles.
+
+---
+
+## Impact Surface
+
+Files that must remain consistent if the boundary changes:
+
+- `src/daemon/workflow-runner.ts` -- rename `pendingSteerText` \u2192 `pendingSteerParts`, add registry
+  registration/deregistration, add optional `steerRegistry` param
+- `src/v2/usecases/console-routes.ts` -- add `steerRegistry` optional param, add POST endpoint
+- `src/trigger/daemon-console.ts` -- create registry, pass to both `mountConsoleRoutes()` and the
+  workflow runner (via TriggerRouter or direct call)
+- `src/console/standalone-console.ts` -- no change needed (passes `undefined` for new param)
+
+Contracts that must remain consistent:
+- `runWorkflow()` public signature -- any change must be additive (optional param, default undefined)
+- `mountConsoleRoutes()` public signature -- same constraint
+- `pendingSteerText` variable name change: search for any existing references (none found outside
+  `workflow-runner.ts` itself)
+
+---
+
+## Candidates
+
+### Candidate 1: Minimal -- raw Map parameter added to existing signatures
+
+**Summary:** Add `steerRegistry?: Map<string, (text: string) => void>` as an optional trailing param
+to both `mountConsoleRoutes()` and `runWorkflow()`. Fix `pendingSteerParts` inline. Endpoint guarded by
+`!steerRegistry \u2192 503`.
+
+**Tensions resolved:**
+- T1 (closure vs. HTTP): plain `Map` is passed explicitly.
+- T2 (silent discard): `pendingSteerParts.push()` fix.
+- T3 (daemon-only): absent Map \u2192 503.
+
+**Tensions accepted:**
+- Lifecycle of registration is caller-managed; caller must remember to deregister in a finally block
+  (not enforced by the type).
+- `boolean` return from `Map.has()` coerces to HTTP 200/404 implicitly.
+
+**Boundary:** `runWorkflow()` and `mountConsoleRoutes()` signatures. Additive, backward-compatible.
+
+**Why this boundary:** These are the exact two call sites that need the registry; adding it here adds
+no abstraction layer above what's needed.
+
+**Failure mode:** Caller forgets to delete from Map after `runWorkflow()` completes \u2192 stale entry
+remains. HTTP endpoint calls the stale callback, which calls `pendingSteerParts.push()` on a
+completed session's closed-over array (harmless but semantically wrong). Mitigation: put the delete
+inside `runWorkflow()`'s finally block (not caller-managed). Risk: low.
+
+**Repo pattern:** Follows `triggerRouter?: TriggerRouter` exactly -- highest pattern consistency.
+
+**Gains:** Minimal new code (\u223c15 lines net new). No new files. No new abstractions.
+
+**Losses:** Raw `Map` type is not self-documenting. The `(text: string) => void` callback signature
+has no name. Mild 'explicit domain types' philosophy violation.
+
+**Impact surface:** Three files (workflow-runner.ts, console-routes.ts, daemon-console.ts). No new
+files.
+
+**Scope:** Best-fit. Exactly what's needed, nothing more.
+
+**Philosophy:** Honors DI-for-boundaries, YAGNI. Mild conflict with 'prefer explicit domain types'.
+
+---
+
+### Candidate 2: Encapsulated -- SteerRegistry class in src/daemon/steer-registry.ts
+
+**Summary:** Create a named `SteerRegistry` class with `register(sessionId, cb): () => void` (returns
+disposer), `invoke(sessionId, text): 'ok' | 'not_found'`, and private `_sessions: Map`. Pass instances
+to `mountConsoleRoutes()` and `runWorkflow()`.
+
+**Tensions resolved:**
+- T1: explicit DI, same as C1.
+- T2: `pendingSteerParts.push()` fix.
+- T3: absent registry \u2192 503.
+- Lifecycle: `register()` returns a disposer function. `runWorkflow()` stores it and calls it in
+  finally. Impossible to forget -- the disposer IS the deregistration.
+
+**Tensions accepted:**
+- New file (~50 lines). Marginal over C1.
+
+**Boundary:** New file `src/daemon/steer-registry.ts`. Both callers import from there. The named class
+is the domain object; the Map is an implementation detail hidden behind the API.
+
+**Why this boundary:** Encapsulates the invariant that 'a session is registered when running and
+deregistered when done'. The disposer pattern makes this lifecycle explicit at the type level.
+
+**Failure mode:** Same as C1 in theory, but structurally prevented: `register()` returns the disposer,
+so the only way to use `SteerRegistry` correctly is to store and call the disposer. Forgetting to call
+it requires actively ignoring the return value (which TypeScript can warn about with `@typescript-eslint/no-unused-vars`).
+
+**Repo pattern:** Consistent with `ToolCallTimingRingBuffer` (small class for narrow concern). Slight
+departure from 'just add a param' pattern, but consistent with broader codebase style of named
+infrastructure types.
+
+**Gains:** Self-documenting API. `'ok' | 'not_found'` maps directly to HTTP 200/404 with no coercion.
+Disposer pattern prevents stale registration. Testable in isolation.
+
+**Losses:** New file. ~35 more lines than C1.
+
+**Impact surface:** Four files (workflow-runner.ts, console-routes.ts, daemon-console.ts, new
+steer-registry.ts).
+
+**Scope:** Best-fit. Marginal scope increase over C1 justified by lifecycle safety.
+
+**Philosophy:** Fully honors 'prefer explicit domain types', DI-for-boundaries, 'errors as data'.
+No conflicts.
+
+---
+
+### Candidate 3: Ambient injection via V2ToolContext
+
+**Summary:** Add `steerRegistry?: SteerRegistry` as an optional field to `V2Dependencies` (or
+`V2ToolContext` directly in `src/mcp/types.ts`). `runWorkflow()` reads it from context; `mountConsoleRoutes()`
+already receives `v2ToolContext`. No new params on either function.
+
+**Tensions resolved:**
+- T1: V2ToolContext flows everywhere, no new wiring needed.
+
+**Tensions accepted:**
+- T3: V2ToolContext is shared between daemon AND MCP server sessions. Adding a daemon-specific field
+  pollutes the shared context. MCP sessions would have `steerRegistry: undefined`, but the type allows
+  it to be set -- no structural prevention.
+- Architecture pollution: `src/mcp/types.ts` is a high-traffic type with many consumers. Adding a
+  daemon-only field there couples the MCP abstraction to the daemon's runtime state.
+
+**Boundary:** `src/mcp/types.ts` V2Dependencies interface. High-traffic, many consumers.
+
+**Why this boundary is wrong:** V2ToolContext is the MCP/engine shared context. Daemon-specific state
+(like which sessions have live agent loops) should not bleed into the MCP layer. If MCP sessions ever
+become steer-able, C3 would be correct then; today it's premature.
+
+**Failure mode:** Misconfigured test or future consumer accidentally sets `steerRegistry` on an MCP
+session, making it steer-able from the HTTP endpoint. Not structurally prevented -- only prevented by
+convention.
+
+**Repo pattern:** Consistent with how `v2ToolContext` is used everywhere, but departs from the 'inject
+specific dependencies for specific concerns' principle.
+
+**Gains:** Zero new params to thread; registry flows naturally wherever V2ToolContext goes.
+
+**Losses:** Architectural pollution. Structurally harder to reason about which sessions are
+steer-able. High-traffic type change.
+
+**Impact surface:** `src/mcp/types.ts` + all consumers that need to be checked for exhaustive handling.
+
+**Scope:** Too broad. The registry is a daemon-only concern.
+
+**Philosophy:** Conflicts with 'make illegal states unrepresentable'. Partially honors DI.
+
+---
+
+## Comparison and Recommendation
+
+### Matrix
+
+| Factor | C1 (raw Map) | C2 (SteerRegistry) | C3 (V2ToolContext) |
+|---|---|---|---|
+| Resolves T1 | Yes | Yes | Yes |
+| Resolves T2 | Yes | Yes | Yes |
+| Resolves T3 structurally | Partially | Yes | No |
+| Lifecycle safety | Caller convention | Enforced by disposer | Caller convention |
+| Philosophy fit | Good | Excellent | Poor (T3) |
+| Repo pattern | Exact match | Adapted match | Wrong boundary |
+| New files | 0 | 1 | 0 |
+| Impact surface | 3 files | 4 files | High (types.ts) |
+
+### Recommendation: Candidate 2 (SteerRegistry class)
+
+**Rationale:** The disposer pattern from `register()` structurally prevents the only meaningful
+failure mode (stale registration). The `'ok' | 'not_found'` return type eliminates implicit coercion
+at the HTTP layer. The new file adds \u223c50 lines but pays for itself in self-documentation and
+testability. C1 and C2 are functionally identical; C2 wins on type safety and lifecycle enforcement.
+
+### Self-Critique
+
+**Strongest argument against C2:** C1 with a type alias `type SteerRegistry = Map<string, (text: string) => void>` and a disposer convention in `runWorkflow()`'s finally block is functionally
+identical to C2. The new file in C2 is purely for encapsulation. If the codebase convention is 'small
+files for small concerns', C2 is right. If the convention is 'minimize files', C1 wins. The codebase
+has `ToolCallTimingRingBuffer` as a precedent for small dedicated infrastructure files -- C2 follows
+this pattern.
+
+**Narrower option that could work:** C1. Loses only the explicit lifecycle type; gains nothing beyond
+fewer files. C1 is acceptable if YAGNI pressure is high.
+
+**Broader option that might be justified:** C3 if MCP sessions become steer-able in v2. Not justified
+today. Evidence required: MCP server calling `runWorkflow()`-style loop.
+
+**Pivot condition:** If a new engineer misuses C2 by holding the registry object and calling
+`invoke()` directly (bypassing the disposer), C2's safety guarantee fails. Risk: low (internal API).
+
+---
+
+## Open Questions for Main Agent
+
+1. Does `daemon-console.ts` own registry construction, or should it be constructed in `trigger-router.ts`
+   and passed down? `TriggerRouter.dispatch()` calls `runWorkflow()` -- it would need the registry.
+   `daemon-console.ts` constructs the `TriggerRouter`. The cleanest path: construct registry in
+   `daemon-console.ts`, pass to `TriggerRouter` constructor and to `mountConsoleRoutes()`.
+
+2. Should the endpoint return `{ success: true }` (no data) on 200, or echo back something useful
+   (e.g., `{ queued: true, sessionId }`)?
+
+3. Should coordinator steers be appended before or after the step text in `pendingSteerParts`?
+   Current proposal: step text first (via `onAdvance()` which fires first), coordinator appended.
+   The agent sees the step instructions before the coordinator enrichment.
+
+4. Is there an existing test for `runWorkflow()` that needs to be updated when `pendingSteerText`
+   is renamed? (Check `src/daemon/workflow-runner.test.ts` or similar.)

package/docs/discovery/steer-endpoint-design-review-findings.md

@@ -0,0 +1,104 @@
+# Design Review Findings: POST /api/v2/sessions/:sessionId/steer
+
+> Concise, actionable findings from the tradeoff review, failure mode analysis,
+> runner-up comparison, and philosophy alignment check.
+
+---
+
+## Tradeoff Review
+
+| Tradeoff | Acceptable? | Condition for unacceptability |
+|---|---|---|
+| No auth on endpoint | Yes | Multi-tenant or remote daemon deployment (not today) |
+| Registration gap window (~50ms) | Yes | Coordinator steers immediately on session creation, before first tool call |
+| No crash recovery for in-flight steers | Yes | Real-time human approval with no retry mechanism (not a v1 use case) |
+| `pendingSteerParts` is mutable array | Yes | Mutation is bounded to two explicit write paths, one read path |
+| `SteerRegistry` as type alias, not class | Yes | Only if richer lifecycle API is needed (it isn't for 3 operations) |
+
+---
+
+## Failure Mode Review
+
+| Failure Mode | Risk | Design Handling |
+|---|---|---|
+| Coordinator calls before session registered | LOW | 404 returned; gap is ~50ms not 1 LLM turn |
+| Coordinator calls after session completes | NONE | 404 returned (registry cleared in finally block) |
+| Stale registration leaking closure reference | NONE | Structurally prevented: disposer lambda in finally block |
+| Concurrent push + drain (JS single-threaded) | NONE | Event loop serializes; no interleaving possible |
+| Unbounded `pendingSteerParts` array | VERY LOW | Bounded by network pressure; no cap needed in v1 |
+| Invalid body (missing/non-string `text`) | NONE | 400 returned after boundary validation |
+
+---
+
+## Runner-Up / Simpler Alternative Review
+
+**From C2 (SteerRegistry class):** Borrow the disposer pattern -- `register()` returns the deregistration lambda. Even with the hybrid (type alias, no class), the disposer pattern is implemented as a closure in `runWorkflow()`'s finally block. The value is in the pattern, not the wrapper.
+
+**Simpler variant (inline Map, no type alias):** Works, but the parameter type `Map<string, (text: string) => void>` in function signatures has no name. A type alias `SteerRegistry` costs zero lines and buys readability at all call sites.
+
+**Hybrid (selected):** Named type alias `SteerRegistry` in `workflow-runner.ts` + no new file. Satisfies 'explicit domain types' at low cost. Disposer lambda in finally block satisfies lifecycle safety. Three trivial operations (set, delete, call) don't warrant a class.
+
+---
+
+## Philosophy Alignment
+
+**Strongly satisfied:**
+- DI for boundaries (registry injected as parameter)
+- Errors as data (HTTP returns typed shape; no exceptions)
+- Validate at boundaries (400/503/404 before hitting registry)
+- YAGNI (no auth, no waitForCoordinator, no crash recovery -- all documented)
+
+**Acceptable tension:**
+- 'Prefer explicit domain types' -- type alias satisfies naming without full class
+- 'Make illegal states unrepresentable' -- structurally possible to pass registry to standalone console, but mitigated by explicit `undefined` + comment
+- 'Immutability by default' -- mutable array bounded behind two explicit write paths
+
+**No conflicts.**
+
+---
+
+## Findings
+
+### GREEN (no blocking issues)
+
+The selected design (hybrid: type alias + parameter injection) satisfies all acceptance criteria, resolves all identified tensions, and has no unaddressed failure modes.
+
+### ORANGE (significant -- address before or during implementation)
+
+**O1: TriggerRouter constructor must receive `steerRegistry`.**
+`TriggerRouter.dispatch()` calls `this.runWorkflowFn(workflowTrigger, this.ctx, this.apiKey, undefined, this.emitter)`. The steer registry must be passed here too, or daemon-triggered sessions cannot be steered. Solution: add `private readonly steerRegistry?: SteerRegistry` to TriggerRouter constructor; pass as 6th arg to `runWorkflowFn()` calls. Update `RunWorkflowFn` type to include optional `steerRegistry` param.
+
+**O2: `runWorkflow()` registration window must be explicit in code comments.**
+The registration gap (~50ms after `executeStartWorkflow()` returns) should be documented with a comment in `runWorkflow()` near the `steerRegistry?.set()` call, explaining that coordinators calling the endpoint immediately after session creation should retry once on 404.
+
+### YELLOW (low risk -- watch during implementation)
+
+**Y1: `pendingSteerParts` clearing semantics.**
+The drain in turn_end should assign `pendingSteerParts = []` (reassign) rather than `pendingSteerParts.length = 0` (mutate-in-place). Either works (JS is single-threaded), but reassignment is more obviously immutable at the read site. Note: the steer callback closes over `pendingSteerParts` by reference to the variable, so if we reassign the variable, the closure's reference becomes stale. Solution: use `pendingSteerParts.length = 0` (truncate in-place) OR close over a container object. Prefer: `pendingSteerParts.splice(0)` (splice to empty, returns removed elements). Alternatively, declare with `const pendingSteerParts: string[] = []` and use `splice(0)` to drain.
+
+**Y2: Ordering of parts in the joined steer message.**
+Step text (from `onAdvance()`) should appear first, coordinator text second. This is the natural order since `onAdvance()` fires first (inside `makeContinueWorkflowTool`), then the steer callback fires from the HTTP handler (which arrives as a later event loop callback). Verify this ordering is preserved after the `pendingSteerText` rename.
+
+---
+
+## Recommended Revisions
+
+1. **Implement hybrid approach:** Named type alias `export type SteerRegistry = Map<string, (text: string) => void>` in `workflow-runner.ts`. No new file. Import alias in `console-routes.ts` and `daemon-console.ts`.
+
+2. **Extend `RunWorkflowFn` type** in `trigger-router.ts` to include optional `steerRegistry?: SteerRegistry` as 6th param. Update both `route()` and `dispatch()` call sites. Add `steerRegistry` to `TriggerRouter` constructor.
+
+3. **Fix `pendingSteerText` -> `pendingSteerParts`** (R1 from prior review). Use `const pendingSteerParts: string[] = []`. Drain with `pendingSteerParts.splice(0)` in turn_end subscriber (splices all items out, returns them for joining).
+
+4. **Registration gap comment**: in `runWorkflow()` near `steerRegistry?.set(workrailSessionId, ...)`, add a comment: "Registration gap: the HTTP endpoint returns 404 for ~50ms between session creation and this call. Coordinators should retry once on 404 during session start-up."
+
+5. **Endpoint response shape**: return `{ success: true }` on 200 (no data needed; steer is fire-and-forget from coordinator's perspective).
+
+---
+
+## Residual Concerns
+
+1. **MCP-mode injection remains deferred.** The steer endpoint is daemon-only. If MCP sessions ever become steer-able, the registry abstraction extends cleanly -- just wire the MCP session's AgentLoop to its own steer callback. Document this explicitly with a TODO comment in the endpoint.
+
+2. **`report_issue` coexistence (Y3 from prior review).** The `signal_coordinator` tool (if added later) and `report_issue` partially overlap. This endpoint does not resolve that overlap. Track separately.
+
+3. **The steer text is unstructured.** The coordinator pushes arbitrary `text: string`. There is no schema for what the text should contain. For v1 this is fine (coordinator constructs the text); for v2, a structured `{ role, content, signal_id }` shape would enable better audit tracing.

package/docs/discovery/steer-endpoint-implementation-plan.md

@@ -0,0 +1,284 @@
+# Implementation Plan: POST /api/v2/sessions/:sessionId/steer
+
+**Branch:** `feat/session-steer-endpoint`
+**Confidence:** High
+**PR count:** 1
+
+---
+
+## Problem Statement
+
+A coordinator script needs to inject text into an agent's next turn during a running daemon session.
+The `steer()` mechanism in `AgentLoop` already delivers injected text. The gap is a bridge between
+an HTTP endpoint and the closure-scoped `pendingSteerText` variable in `runWorkflow()`.
+
+Additionally, the existing `pendingSteerText: string | null` is a single-value field that silently
+drops coordinator steers when overwritten by `onAdvance()`. This must be fixed first (R1 finding).
+
+---
+
+## Acceptance Criteria
+
+1. `POST /api/v2/sessions/:sessionId/steer` with body `{ "text": "..." }` returns HTTP 200
+   `{ "success": true }` when the sessionId belongs to an active daemon session.
+2. The injected text is delivered to the agent via `agent.steer()` on the next `turn_end` event,
+   concatenated after the step text from `onAdvance()`.
+3. Returns HTTP 404 `{ "success": false, "error": "Session not found or not a daemon session" }`
+   when the sessionId is not in the registry.
+4. Returns HTTP 503 `{ "success": false, "error": "Steer not available..." }` in standalone console
+   mode (no steerRegistry injected).
+5. Returns HTTP 400 for missing or non-string `text` body.
+6. Multiple calls to the endpoint between `turn_end` events: all injected texts are delivered in the
+   same steer message, joined with `\n\n`.
+7. After the session completes, calling the endpoint returns 404.
+8. The existing `pendingSteerText` variable is replaced by `pendingSteerParts: string[]` and
+   `onAdvance()` behavior is unchanged from the caller's perspective (step advance still works).
+
+---
+
+## Non-Goals
+
+- Auth token on the endpoint (v1 is localhost-only, network binding is the security layer)
+- `waitForCoordinator` blocking gate mechanism (Phase 2B, separate task)
+- `wr.coordinator_signal` artifact schema (Phase A, separate task)
+- MCP-mode injection (deferred to v2)
+- Crash recovery for in-flight steers (in-memory only, v1 known limitation)
+- Structured request body beyond `{ text: string }` (v2 concern)
+
+---
+
+## Philosophy-Driven Constraints
+
+- **DI for boundaries**: `SteerRegistry` must be injected into `mountConsoleRoutes()` and
+  `runWorkflow()`. No module-level singletons.
+- **Errors as data**: HTTP responses use `{ success: bool, error?: string }` shape. No thrown
+  exceptions at the route level.
+- **Validate at boundaries**: 400 for invalid body, 503 for disabled, 404 for not-found -- all
+  checked before touching the registry.
+- **YAGNI**: Only what's listed in acceptance criteria. No speculative extension points.
+- **Explicit domain types**: Named type alias `SteerRegistry` (not raw `Map<string, fn>` literal).
+
+---
+
+## Invariants
+
+1. `pendingSteerParts` is only mutated in two places: `onAdvance()` (push step text) and the steer
+   callback registered in the `SteerRegistry` (push coordinator text). No other writer.
+2. `pendingSteerParts` is only read and drained in the `turn_end` subscriber. Single reader.
+3. JavaScript single-threaded event loop: no race between push and drain.
+4. The steer callback is registered after `workrailSessionId` is decoded from the continueToken,
+   and deregistered in `runWorkflow()`'s `finally` block. No stale entries possible.
+5. The endpoint is only active when `steerRegistry` is provided to `mountConsoleRoutes()`.
+   The standalone console does not provide it.
+6. The `steerRegistry` param is optional on all functions. No existing callers are broken.
+
+---
+
+## Selected Approach
+
+**Hybrid (type alias + parameter injection):**
+- Named type alias `export type SteerRegistry = Map<string, (text: string) => void>` in
+  `src/daemon/workflow-runner.ts`.
+- `pendingSteerText: string | null` replaced by `const pendingSteerParts: string[] = []`.
+- `onAdvance()` uses `pendingSteerParts.push(stepText)`.
+- turn_end subscriber drains with `const parts = pendingSteerParts.splice(0)` and calls
+  `agent.steer(buildUserMessage(parts.join('\n\n')))` if `parts.length > 0`.
+- `runWorkflow()` gains optional `steerRegistry?: SteerRegistry` param. After workrailSessionId
+  is decoded, calls `steerRegistry?.set(workrailSessionId, (text) => pendingSteerParts.push(text))`.
+  In `finally`: `steerRegistry?.delete(workrailSessionId)`.
+- `mountConsoleRoutes()` gains optional `steerRegistry?: SteerRegistry` param after `triggerRouter`.
+- `POST /api/v2/sessions/:sessionId/steer` endpoint added in `console-routes.ts`.
+- `TriggerRouter` constructor gains optional `steerRegistry?: SteerRegistry`; passes to
+  `runWorkflowFn()` calls in `route()` and `dispatch()`.
+- `RunWorkflowFn` type in `trigger-router.ts` extended with optional 6th param.
+
+**Runner-Up:** C2 (SteerRegistry class). Loses only for having a new file for 3 trivial operations.
+Use if the registry gains additional methods or needs isolated unit tests.
+
+---
+
+## Vertical Slices
+
+### Slice 1: Fix `pendingSteerText` -> `pendingSteerParts` (R1 prerequisite)
+
+**Files:** `src/daemon/workflow-runner.ts` only.
+
+**Change:**
+- Rename `pendingSteerText: string | null` to `const pendingSteerParts: string[] = []`.
+- Update `onAdvance()`: `pendingSteerText = stepText` -> `pendingSteerParts.push(stepText)`.
+- Update turn_end subscriber drain:
+  - Before: `if (pendingSteerText !== null && !isComplete) { ... }`
+  - After: `if (!isComplete) { const parts = pendingSteerParts.splice(0); if (parts.length > 0) { agent.steer(buildUserMessage(parts.join('\n\n'))); } }`
+- Note: `isComplete` guard moves outside the `splice(0)` -- drain always happens, steer only if not complete and parts non-empty.
+
+**Acceptance:** Existing behavior unchanged. Session still receives step text on each advance.
+No coordinator injection yet. Build+type-check passes. Existing tests pass.
+
+**Risk:** Low. Pure refactor, no behavior change from external perspective.
+
+---
+
+### Slice 2: SteerRegistry type alias + runWorkflow() registration
+
+**Files:** `src/daemon/workflow-runner.ts`.
+
+**Change:**
+- Add: `export type SteerRegistry = Map<string, (text: string) => void>;`
+- Add optional param to `runWorkflow()`: `steerRegistry?: SteerRegistry`
+- After `workrailSessionId` is decoded (line ~2190): register callback:
+  ```typescript
+  if (steerRegistry && workrailSessionId) {
+    steerRegistry.set(workrailSessionId, (text: string) => { pendingSteerParts.push(text); });
+  }
+  ```
+- In `finally` block: `if (steerRegistry && workrailSessionId) { steerRegistry.delete(workrailSessionId); }`
+- Add code comment on the `set()` call documenting the registration gap.
+
+**Acceptance:** `runWorkflow()` compiles with new optional param. Existing callers unchanged.
+Manual test: if a steerRegistry Map is passed and a callback is registered/called during a session,
+text is pushed to `pendingSteerParts`.
+
+**Risk:** Low. Additive change, no behavior change when `steerRegistry` is undefined.
+
+---
+
+### Slice 3: TriggerRouter wiring
+
+**Files:** `src/trigger/trigger-router.ts`.
+
+**Change:**
+- Import `SteerRegistry` from `workflow-runner.js`.
+- Extend `RunWorkflowFn` type with optional 6th param:
+  `steerRegistry?: SteerRegistry` after `emitter?`.
+- Add `private readonly steerRegistry?: SteerRegistry` to `TriggerRouter`.
+- Add `steerRegistry?: SteerRegistry` to TriggerRouter constructor params.
+- Assign in constructor: `this.steerRegistry = steerRegistry`.
+- Update `route()` call: `this.runWorkflowFn(workflowTrigger, this.ctx, this.apiKey, undefined, this.emitter, this.steerRegistry)`
+- Update `dispatch()` call: same.
+
+**Acceptance:** TriggerRouter compiles. `runWorkflow` in production TriggerRouter path passes
+steerRegistry to the agent loop. Existing trigger tests unaffected (registry is optional).
+
+**Risk:** Low. Additive param. All existing test calls to `TriggerRouter` pass `undefined` or
+omit the param.
+
+---
+
+### Slice 4: HTTP endpoint in console-routes.ts
+
+**Files:** `src/v2/usecases/console-routes.ts`.
+
+**Change:**
+- Import `SteerRegistry` from `../../daemon/workflow-runner.js`.
+- Add `steerRegistry?: SteerRegistry` to `mountConsoleRoutes()` param list (after `triggerRouter`).
+- Add endpoint after the `POST /api/v2/auto/dispatch` block:
+
+```typescript
+// POST /api/v2/sessions/:sessionId/steer
+// Injects text into a running daemon session's next agent turn.
+// Daemon-only: requires steerRegistry to be provided at server startup.
+// Auth: localhost-only (127.0.0.1 binding). No token auth in v1.
+// TODO(v2): Add token auth before any multi-user or remote deployment.
+app.post('/api/v2/sessions/:sessionId/steer', express.json(), (req: Request, res: Response) => {
+  if (!steerRegistry) {
+    res.status(503).json({ success: false, error: 'Steer not available (not a daemon context).' });
+    return;
+  }
+  const { sessionId } = req.params;
+  const body = req.body as { text?: unknown };
+  const text = typeof body.text === 'string' ? body.text.trim() : '';
+  if (!text) {
+    res.status(400).json({ success: false, error: 'text is required and must be a non-empty string.' });
+    return;
+  }
+  const callback = steerRegistry.get(sessionId);
+  if (!callback) {
+    res.status(404).json({ success: false, error: 'Session not found or not a daemon session.' });
+    return;
+  }
+  callback(text);
+  res.json({ success: true });
+});
+```
+
+**Acceptance:** All 5 HTTP response cases work correctly (200, 400, 404, 503). Session receives
+injected text on next turn_end. Standalone console returns 503.
+
+**Risk:** Low. New endpoint, no changes to existing routes.
+
+---
+
+### Slice 5: Daemon wiring in daemon-console.ts
+
+**Files:** `src/trigger/daemon-console.ts`.
+
+**Change:**
+- Import `SteerRegistry` from `../daemon/workflow-runner.js`.
+- Before constructing `TriggerRouter`: `const steerRegistry: SteerRegistry = new Map();`
+- Pass to `TriggerRouter` constructor: `new TriggerRouter(index, ctx, apiKey, runWorkflow, execFn, ..., steerRegistry)`
+- Pass to `mountConsoleRoutes()`: add `steerRegistry` as the last argument (after `triggerRouter`).
+- Also update the direct `runWorkflow()` call in `console-routes.ts` `POST /auto/dispatch` path
+  (when `triggerRouter` is absent): pass `steerRegistry` as 6th arg.
+
+**Acceptance:** End-to-end: daemon starts, `POST /auto/dispatch` creates a session, coordinator
+calls `POST /sessions/:id/steer`, agent receives injected text on next turn.
+
+**Risk:** Medium. This is the wiring step that connects all slices. Most likely source of missed
+call sites.
+
+---
+
+## Test Design
+
+### Unit tests (workflow-runner.ts)
+- Test that `onAdvance()` pushes to `pendingSteerParts`.
+- Test that turn_end subscriber joins and steers when `pendingSteerParts.length > 0`.
+- Test that multiple pushes (simulate both `onAdvance` and steer callback) produce joined text.
+- Test that `steerRegistry.set()` is called after workrailSessionId decoded.
+- Test that `steerRegistry.delete()` is called in finally (mock registry, verify delete).
+
+### Integration test (console-routes.ts)
+- Mock `steerRegistry` with a Map. POST to endpoint with valid body -> 200, callback called.
+- POST with empty body -> 400.
+- POST with unknown sessionId -> 404.
+- POST without steerRegistry injected -> 503.
+
+### Regression: existing tests
+- All existing `runWorkflow()` tests must pass unchanged (optional param, default undefined).
+- All existing `mountConsoleRoutes()` tests must pass unchanged.
+- All existing TriggerRouter tests must pass unchanged.
+
+---
+
+## Risk Register
+
+| Risk | Likelihood | Impact | Mitigation |
+|---|---|---|---|
+| Missed call site for steerRegistry in dispatch/route | Medium | High | Search for all `runWorkflowFn(` calls in trigger-router.ts before submitting |
+| `pendingSteerParts.splice(0)` stale closure ref | Low | High | splice(0) mutates in-place; closure over array variable (not array contents) is safe |
+| Registration gap causes 404 for early steers | Very low | Low | Document with code comment; coordinator retries on 404 |
+| `mountConsoleRoutes` callers not updated | Low | Medium | Only 3 callers: daemon-console.ts, standalone-console.ts (no change), console-routes.ts |
+
+---
+
+## PR Packaging Strategy
+
+Single PR on branch `feat/session-steer-endpoint`. All 5 slices together. The R1 fix (Slice 1) is
+small enough that it doesn't need its own PR. The endpoint is only usable when all slices are present.
+
+PR title: `feat(console): add POST /api/v2/sessions/:sessionId/steer for coordinator injection`
+
+---
+
+## Philosophy Alignment Per Slice
+
+| Slice | Principle | Status |
+|---|---|---|
+| S1 pendingSteerParts | Immutability by default | Tension (mutable array) -- acceptable, mutation bounded |
+| S1 pendingSteerParts | Compose with small pure functions | Satisfied -- drain is one expression |
+| S2 SteerRegistry type | Explicit domain types | Satisfied -- named alias |
+| S2 runWorkflow registration | DI for boundaries | Satisfied -- injected, not global |
+| S3 TriggerRouter | Make illegal states unrepresentable | Satisfied -- optional param can't be confused with required |
+| S4 HTTP endpoint | Validate at boundaries | Satisfied -- 400/503/404 before touching registry |
+| S4 HTTP endpoint | Errors as data | Satisfied -- { success: bool } shape |
+| S5 daemon wiring | YAGNI | Satisfied -- single Map, no extra abstraction |