@exaudeus/workrail 3.39.0 → 3.41.0

package/docs/discovery/late-bound-goals-review.md

@@ -0,0 +1,82 @@
+# Design Review Findings: Late-Bound Goals
+
+**Feature**: Default `goalTemplate: "{{$.goal}}"` when no static `goal` and no `goalTemplate` is configured.  
+**Design**: Candidate A -- parse-time sentinel injection in `validateAndResolveTrigger()`.
+
+---
+
+## Tradeoff Review
+
+| Tradeoff | Conditions for failure | Status |
+|---|---|---|
+| Synthetic sentinel `'Autonomous task'` in `goal` field | If `trigger.goal` were used for routing/dedup (not display only). Verified: only used in `interpolateGoalTemplate` fallback and logs. | Acceptable |
+| No `console.warn` on load for late-bound triggers | Operators may not discover this feature. Mitigated by adding a `console.log` at daemon startup when injection fires. | Acceptable with INFO log |
+| Sentinel shows in console trigger list | Cosmetic only. Sessions get the interpolated goal from payload, not the sentinel. | Acceptable |
+
+---
+
+## Failure Mode Review
+
+| Failure Mode | Handled? | Missing Mitigation | Risk |
+|---|---|---|---|
+| Console UI shows 'Autonomous task' | Yes -- cosmetic, not functional | Future: show `goalTemplate` in trigger list | Low |
+| Payload has no `goal` field | Yes -- `interpolateGoalTemplate` already warns (line 127) | None needed | Low |
+| Non-null assertion `raw.goal!.trim()` panics | Handled by replacing with `resolvedGoal: string` | TypeScript compile-time check | Low |
+| `goalTemplate`-only trigger with no `goal` | Handled -- inject sentinel for this case too | None needed | Low |
+
+No high-risk failure modes.
+
+---
+
+## Runner-Up / Simpler Alternative Review
+
+- **Candidate B** (optional type): nothing worth borrowing. Cascades null checks to 3+ files.
+- **Simpler variant** (only inject when both absent, skip goalTemplate-only case): does NOT satisfy acceptance criteria -- existing triggers using only `goalTemplate` would still fail with `missing_field`.
+- **Hybrid improvement**: extract `'Autonomous task'` to a named constant `LATE_BOUND_GOAL_SENTINEL` for searchability. Low cost, worth including.
+
+---
+
+## Philosophy Alignment
+
+**Satisfied**: validate-at-boundaries, make-illegal-states-unrepresentable, immutability, YAGNI, determinism.
+
+**Under tension**: prefer-explicit-domain-types -- a `goalSource` discriminant would be more type-honest. Acceptable: documented as a future enhancement, not blocking this fix.
+
+---
+
+## Findings
+
+### Yellow: Named constant for sentinel
+
+**Severity**: Yellow (code quality, not correctness)  
+**Finding**: `'Autonomous task'` hardcoded inline is harder to search and understand than a named constant.  
+**Fix**: `const LATE_BOUND_GOAL_SENTINEL = 'Autonomous task';` at module scope.
+
+### Yellow: Missing INFO log at injection time
+
+**Severity**: Yellow (operator experience)  
+**Finding**: Operators who configure a trigger without `goal`/`goalTemplate` get silent late-bound behavior. A `console.log` at injection time helps discoverability.  
+**Fix**: `console.log('[TriggerStore] Trigger "%s" has no static goal or goalTemplate -- defaulting to goalTemplate: "{{$.goal}}" (goal from payload)', rawId);`
+
+### Yellow: Missing WHY comment in code
+
+**Severity**: Yellow (maintainability)  
+**Finding**: The injection block needs a comment explaining the late-bound goal contract and the sentinel value.
+
+No Red or Orange findings.
+
+---
+
+## Recommended Revisions
+
+1. Extract sentinel to named constant: `const LATE_BOUND_GOAL_SENTINEL = 'Autonomous task';`
+2. Add `console.log` when injecting the default.
+3. Add WHY comment above the injection block.
+4. Update `docs/discovery/late-bound-goals.md` with these minor additions.
+
+---
+
+## Residual Concerns
+
+1. **Console UI display**: Late-bound triggers show 'Autonomous task' in the trigger list until a UI enhancement adds `goalTemplate` as a separate display field. Documented as a known limitation, not a bug.
+2. **Future discriminant**: A `goalSource: 'static' | 'payload'` field on `TriggerDefinition` would be the cleaner long-term design. Filed in backlog. This change does not block it.

package/docs/discovery/late-bound-goals.md

@@ -0,0 +1,118 @@
+# Design Candidates: Late-Bound Goals
+
+**Feature**: Default `goalTemplate: "{{$.goal}}"` when no static `goal` and no `goalTemplate` is configured, enabling dynamic goals from the webhook payload.
+
+**Date**: 2026-04-18
+
+---
+
+## Problem Understanding
+
+### Core Tensions
+
+1. **Type safety vs relaxed validation**: `TriggerDefinition.goal: string` is a required field by type. Relaxing the YAML validation (allowing `goal` to be absent) must not violate the type. Resolved by injecting a sentinel.
+
+2. **Parse-time vs dispatch-time defaulting**: Injecting at parse time (trigger-store.ts) keeps the router clean. Injecting at dispatch time (trigger-router.ts) would require making `goal` optional in the type or adding defensive null checks everywhere `trigger.goal` is used.
+
+3. **Sentinel vs empty string**: The fallback goal for "payload had no goal field" must be human-readable in logs and the console UI. `'Autonomous task'` is the minimum useful value.
+
+4. **Backward compat**: Existing triggers in `triggers.yml` have a static `goal`. The change must be zero-impact for them.
+
+### Likely Seam
+
+`validateAndResolveTrigger()` in `src/trigger/trigger-store.ts` -- specifically between the `requiredStringFields` check (line 553) and the `goalTemplate` assembly (line 654). The new logic fits naturally there: after required non-goal fields are checked, handle the `goal`/`goalTemplate` pair together.
+
+### What Makes It Hard
+
+Technically simple, but the non-null assertion `goal: raw.goal!.trim()` on line 974 would panic if `goal` is removed from `requiredStringFields` without also ensuring injection. A junior developer might instead make `goal` optional in `TriggerDefinition`, cascading null checks across all consumers.
+
+---
+
+## Philosophy Constraints
+
+- **Validate at boundaries, trust inside** (CLAUDE.md): inject the default at parse time in trigger-store.ts, not at dispatch time in trigger-router.ts.
+- **Make illegal states unrepresentable** (CLAUDE.md): `TriggerDefinition.goal` must always be a valid `string`. Sentinel injection preserves this.
+- **YAGNI with discipline** (CLAUDE.md): `'Autonomous task'` is the minimum viable fallback. Do not add configurable fallback strings.
+- **Repo pattern** (trigger-store.ts line 756): `concurrencyMode` defaults to `'serial'` at parse time -- exactly the pattern to follow.
+
+No philosophy conflicts detected.
+
+---
+
+## Impact Surface
+
+- `src/trigger/trigger-store.ts` line 553: `goal` removed from `requiredStringFields`
+- `src/trigger/trigger-store.ts` line 974: `goal: raw.goal!.trim()` must become `goal: resolvedGoal`
+- `src/trigger/trigger-router.ts`: no change -- `interpolateGoalTemplate` already handles `{{$.goal}}` and falls back to `staticGoal`
+- `src/trigger/types.ts`: no change -- `goal: string` stays required
+- `src/v2/usecases/console-routes.ts` line 677: returns `t.goal` in trigger list -- will show `'Autonomous task'` for late-bound triggers (acceptable UX)
+- `tests/unit/trigger-store.test.ts`: add 2-3 new test cases
+- `tests/unit/trigger-router.test.ts`: add 1 test for `{{$.goal}}` dispatch
+
+---
+
+## Candidates
+
+### Candidate A: Parse-time sentinel injection (recommended)
+
+**Summary**: Remove `goal` from `requiredStringFields`. After the required checks, add a block: if `raw.goal` absent AND `raw.goalTemplate` absent, set `resolvedGoal = 'Autonomous task'` and inject `goalTemplate = '{{$.goal}}'`; if `raw.goal` absent AND `raw.goalTemplate` present, set `resolvedGoal = 'Autonomous task'`; otherwise use `raw.goal.trim()`. Replace `raw.goal!.trim()` on line 974 with `resolvedGoal`.
+
+- **Tensions resolved**: type safety (sentinel ensures `string`), backward compat, parse-time defaulting
+- **Tension accepted**: sentinel is synthetic -- `'Autonomous task'` shows in console for unconfigured triggers
+- **Boundary**: `validateAndResolveTrigger()` in trigger-store.ts -- the correct validation boundary
+- **Why this boundary**: all other defaults (`concurrencyMode`, `referenceUrls`, `agentConfig`) are applied here, not in the router
+- **Failure mode**: operators reading the console trigger list see `'Autonomous task'` as the goal for late-bound triggers; acceptable since the real goal comes from the payload
+- **Repo pattern**: follows `concurrencyMode` default exactly
+- **Gains**: ~8 lines changed, zero downstream changes, fully backward-compatible
+- **Losses**: nothing material
+- **Scope**: best-fit
+- **Philosophy**: honors validate-at-boundaries, make-illegal-states-unrepresentable, YAGNI
+
+### Candidate B: Make `goal` optional in TriggerDefinition
+
+**Summary**: Change `readonly goal: string` to `readonly goal?: string` in `TriggerDefinition`. Remove `goal` from `requiredStringFields`. Update trigger-router.ts and console-routes.ts to handle `goal | undefined`.
+
+- **Tensions resolved**: type honesty -- `goal` really is absent for late-bound triggers
+- **Tensions accepted**: type change cascades -- every consumer of `trigger.goal` must handle `undefined`
+- **Boundary**: types.ts (type contract) + all consumers
+- **Failure mode**: cascading null checks; `trigger.goal ?? ''` as the router fallback is worse UX than `'Autonomous task'`
+- **Repo pattern**: departs from existing pattern where all `TriggerDefinition` fields are either required or explicitly optional
+- **Gains**: type honesty
+- **Losses**: type safety guarantee; cascading changes across router, console-routes, tests
+- **Scope**: too broad -- type change touches 3+ files unnecessarily
+- **Philosophy**: conflicts with make-illegal-states-unrepresentable, YAGNI
+
+---
+
+## Comparison and Recommendation
+
+| Dimension | Candidate A | Candidate B |
+|---|---|---|
+| Type safety | Full -- `goal: string` always holds | Weakened -- `goal?: string` propagates |
+| Files changed | 1 source + tests | 3+ source files + tests |
+| Backward compat | 100% | 100% but requires null guards |
+| Repo pattern fit | Exact (concurrencyMode) | Departs from established pattern |
+| Reversibility | Trivial | Requires re-tightening type across consumers |
+
+**Recommendation: Candidate A.** Resolves all tensions at the correct boundary with the minimum change surface. Exact match to the established `concurrencyMode` default pattern. Zero downstream impact.
+
+---
+
+## Self-Critique
+
+**Strongest counter-argument**: Candidate B is more type-honest. The sentinel `'Autonomous task'` is a lie -- the goal is really absent at config time. Operators reading the console trigger list may be confused.
+
+**Why it still loses**: The console trigger list already shows `goalTemplate` as a separate field (if set). For late-bound triggers, the UI can be enhanced later to show `goalTemplate` instead of `goal` -- but that is a separate concern. The type lie is contained to display; routing behavior is correct.
+
+**Narrower option**: Only inject `goalTemplate` without a sentinel `goal`, using a conditional on the object literal. But `TriggerDefinition.goal: string` is required, so this path leads back to Candidate B (type change required).
+
+**Broader option**: Add `goalSource: 'static' | 'template' | 'payload'` discriminant to `TriggerDefinition` for explicit tracking. Useful for a future console UI enhancement, but out of scope for this 10-line fix.
+
+**Invalidating assumption**: If `trigger.goal` is used anywhere to make routing decisions (not just as a display value or fallback), the sentinel could cause incorrect behavior. Verified: `trigger.goal` is only used in `interpolateGoalTemplate` as the `staticGoal` fallback and in log messages. Safe.
+
+---
+
+## Open Questions for the Main Agent
+
+1. Should the sentinel string be `'Autonomous task'` or something else (e.g. `'No goal configured'`, `'(goal from payload)'`)? The backlog does not specify. `'Autonomous task'` matches the product language used elsewhere.
+2. Should a `console.warn` be emitted when both `goal` and `goalTemplate` are absent, so operators know the trigger is using late-bound goals? This would help debugging misconfigured triggers.

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.