@exaudeus/workrail 3.59.3 → 3.59.5

package/docs/design/coordinator-in-process-await-design-review.md

@@ -0,0 +1,93 @@
+# Design Review: In-Process awaitSessions and getAgentResult
+
+**Date:** 2026-04-19
+**Candidate reviewed:** Candidate A from `coordinator-in-process-await-candidates.md`
+
+---
+
+## Tradeoff Review
+
+**Tradeoff: `port` field made optional in `CoordinatorDeps`**
+- Verified: `deps.port` is unused by all coordinator logic (grep returns zero results)
+- Condition that invalidates: TypeScript errors showing `port` required elsewhere
+- Mitigation: Run `npm run build` immediately; pivot to `port: 0` sentinel if errors appear
+- **Verdict: Acceptable**
+
+**Tradeoff: `null consoleService` fallback for missing `ctx.v2` ports**
+- Verified: `createToolContext()` always provides non-null values in production
+- Condition that invalidates: Not applicable in production path
+- Mitigation: Warn on stderr + degrade gracefully to same all-failed behavior as current HTTP failure
+- **Verdict: Acceptable**
+
+**Tradeoff: Pending-Set polling over check-all-handles-every-poll**
+- Verified: Terminal state transitions are monotonic (event log is append-only)
+- Condition that invalidates: Not possible given ConsoleRunStatus projection semantics
+- **Verdict: Correct and more efficient**
+
+---
+
+## Failure Mode Review
+
+| Failure Mode | Handled? | Risk |
+|---|---|---|
+| `ctx.v2.dataDir`/`directoryListing` null | Yes -- null guard + graceful fallback | Low |
+| Session not yet visible after spawnSession | Yes -- SESSION_LOAD_FAILED treated as retry | Low |
+| TypeScript error from port optional | Partially -- pivot to sentinel if needed | Low |
+| ConsoleService circular dependency | Yes -- dynamic import pattern | Low |
+| getSessionDetail/getNodeDetail unexpected throw | Yes -- ResultAsync + outer try/catch | Low |
+
+**Highest-risk**: TypeScript port optional change causing build failure. Pivot defined and trivial.
+
+---
+
+## Runner-Up / Simpler Alternative Review
+
+**Candidate B** (port: 0 sentinel): Nothing worth borrowing. The only advantage was zero interface changes, but it introduces a dead required field with a misleading sentinel value.
+
+**Simpler variant** (keep `port: DAEMON_CONSOLE_PORT`): Insufficient -- leaves dead code after removing the HTTP deps that needed it. Design doc explicitly lists port removal as required.
+
+**No hybrid needed.**
+
+---
+
+## Philosophy Alignment
+
+| Principle | Status |
+|---|---|
+| Architectural fixes over patches | SATISFIED -- root-cause fix, not workaround |
+| Make illegal states unrepresentable | SATISFIED -- no sentinel, optional instead |
+| Dependency injection for boundaries | SATISFIED -- ConsoleService gets ports injected |
+| Immutability by default | SATISFIED -- minimal mutable state (pending Set only) |
+| Errors are data | SATISFIED -- ResultAsync.isOk()/isErr() throughout |
+| YAGNI with discipline | SATISFIED -- no speculative abstractions |
+| Document "why", not "what" | REQUIRED -- add WHY comments in implementation |
+
+One acceptable tension: null consoleService uses nullable variable rather than Result type. Acceptable at initialization boundary (not domain logic).
+
+---
+
+## Findings
+
+**No Red (blocking) findings.**
+
+**Orange (should address before shipping):**
+- None identified.
+
+**Yellow (advisory):**
+- Y1: The `ctx.v2` null guard creates a nullable `consoleService` variable. If `ctx.v2` is ever null in production, the stderr warning may be missed. Recommend making the warning prominent: `[CRITICAL trigger-listener:reason=consoleService_unavailable]` prefix.
+
+---
+
+## Recommended Revisions
+
+1. Add `[CRITICAL]` prefix to the `ctx.v2` null guard warning to make it visible in logs.
+2. Add WHY comment on new `awaitSessions` explaining the in-process approach (mirrors the spawnSession WHY comment pattern).
+3. Add WHY comment on `ConsoleService` construction explaining it avoids the HTTP race condition.
+
+---
+
+## Residual Concerns
+
+- **None blocking.** The design is sound, the tradeoffs are acceptable, and the failure modes are covered.
+- Build verification (`npm run build`) will immediately catch any TypeScript issues from the `port` optional change.
+- The implementation is a near-direct transcription of the design doc pseudocode, reducing creative risk.

package/docs/design/coordinator-io-error-handling-candidates.md

@@ -0,0 +1,199 @@
+# Coordinator I/O Error Handling -- Design Candidates
+
+Generated: 2026-04-19
+
+## Problem Understanding
+
+### Core Tensions
+
+1. **Crash-safety vs. DI purity**: The coordinator declares "all phase failures produce
+   `PipelineOutcome { kind: 'escalated' }` -- never thrown" as a design invariant, but three
+   injected dep functions (`getAgentResult`, `postToOutbox`, `pollForPR`) are called without
+   try/catch in the mode files. Any throw from these functions crashes the coordinator silently
+   instead of returning a structured `PipelineOutcome`. The fix must enforce the invariant at
+   the right boundary.
+
+2. **Verbosity vs. DRY**: `postToOutbox` is called at 8+ critical escalation points across
+   `implement-shared.ts` and `full-pipeline.ts`. Each call site needs individual protection.
+   Inline try/catch at 8 sites is repetitive; a helper would reduce duplication but adds
+   abstraction not in the existing codebase pattern.
+
+3. **`process.stderr.write()` vs. `deps.stderr()`**: The prescribed pattern uses
+   `process.stderr.write()` in catch blocks, but the rest of the coordinator uses the injected
+   `deps.stderr()`. The tension is minor -- catch blocks represent unexpected I/O failures,
+   so using `process.stderr.write()` signals this is an emergency log path, not a normal
+   operational log.
+
+### Likely Seam
+
+The mode files are the correct seam. `implement-shared.ts`, `full-pipeline.ts`, and
+`implement.ts` are the callers of the three unsafe deps. The coordinator owns the
+escalation-first invariant -- not the injectors (`trigger-listener.ts`, `cli-worktrain.ts`).
+
+### What Makes This Hard
+
+- `postToOutbox` calls are immediately followed by `return { kind: 'escalated', ... }`. The
+  try/catch must wrap ONLY the `postToOutbox` call, not the return statement. Careful
+  placement required.
+- `pollForPR` is called in BOTH `implement.ts` (explicitly mentioned in task) AND
+  `full-pipeline.ts` line 454 (not mentioned but equally unsafe). Both must be wrapped.
+- UX gate zombie detection: `implement.ts` line 144 assigns `uxHandle` from `uxSpawnResult.value`
+  without a null/empty-string guard before passing to `awaitSessions`. This is the only session
+  handle in the coordinator without the guard -- a separate gap alongside the I/O error handling.
+
+---
+
+## Philosophy Constraints
+
+**From `CLAUDE.md`:**
+- "Errors are data -- represent failure as values (Result/Either), not exceptions as control flow"
+- "Type safety as the first line of defense"
+
+**From `adaptive-pipeline.ts` header (design invariant):**
+- "All phase failures produce PipelineOutcome { kind: 'escalated' } -- never thrown."
+- "All I/O is injected via AdaptiveCoordinatorDeps. Zero direct fs/fetch/exec imports."
+
+**Repo precedent:**
+- `archiveFile` (in `implement.ts` and `full-pipeline.ts`): try/catch inline in finally block, log-and-continue. This is the exact model for `postToOutbox`.
+- `writeFile` routing log (in `adaptive-pipeline.ts`): try/catch inline, log-and-continue.
+
+**Conflicts:** None material. The stated philosophy (errors as data) and the repo pattern (inline try/catch for non-Result deps) are consistent.
+
+---
+
+## Impact Surface
+
+- `runReviewAndVerdictCycle` is called from both `implement.ts` and `full-pipeline.ts`. Fixing
+  `getAgentResult` in `implement-shared.ts` protects both callers automatically.
+- `runAuditChain` (also in `implement-shared.ts`) calls both `getAgentResult` and `postToOutbox`
+  at multiple points.
+- `adaptive-pipeline.ts` line 362 calls `postToOutbox` in the `ESCALATE` routing case -- this is
+  OUT OF SCOPE for this task (task restricts changes to the 3 mode files).
+- No callers outside these files change signature or return type.
+
+---
+
+## Candidates
+
+### Candidate 1: Inline try/catch at each call site (prescribed pattern)
+
+**Summary:** Wrap each `getAgentResult`, `postToOutbox`, and `pollForPR` call individually in
+a try/catch block in the 3 mode files.
+
+**Tensions resolved:** Crash-safety fully addressed. Accepts: slight verbosity from 8+
+`postToOutbox` sites.
+
+**Boundary:** At the mode file call sites -- the correct boundary. The coordinator owns the
+escalation-first invariant; the mode files are where the invariant must be enforced.
+
+**Failure mode:** Missing the `pollForPR` call in `full-pipeline.ts` (not explicitly called out
+in task description but confirmed unsafe by code analysis). Must be systematic.
+
+**Repo-pattern relationship:** Follows `archiveFile` try/catch pattern exactly. Adapts
+`writeFile` routing-log pattern from `adaptive-pipeline.ts`.
+
+**Gains:** Zero risk to happy path. Locally visible -- reviewer can see exactly what is
+protected at each call site. No new abstractions.
+
+**Losses:** Mildly repetitive for `postToOutbox` sites. Functions grow slightly.
+
+**Scope:** Best-fit. The 3 files are exactly the seam.
+
+**Philosophy fit:** Honors "errors are data", "escalation-first invariant", "DI for boundaries".
+Minor: uses `process.stderr.write()` in catch blocks rather than `deps.stderr()`, consistent
+with prescribed pattern and emergency-log semantics.
+
+---
+
+### Candidate 2: Wrap at injection site (safe wrapper functions)
+
+**Summary:** Wrap `getAgentResult`, `postToOutbox`, `pollForPR` in safe adapter functions at
+the injection sites (`trigger-listener.ts`, `cli-worktrain.ts`) so the deps never throw from
+the coordinator's perspective.
+
+**Tensions resolved:** DI purity -- the mode files stay clean. Accepts: changes to 2 files
+outside the permitted scope.
+
+**Boundary:** At the injection layer. Wrong boundary for this task -- the coordinator owns the
+escalation invariant, not the injectors. Injectors wire up the real implementation; they are
+not responsible for the coordinator's recovery behavior.
+
+**Failure mode:** Wrapping at injection site catches throws but cannot return `PipelineOutcome`
+-- would need to return null or a sentinel, which the mode files then check. Adds complexity
+at both ends, solving neither fully.
+
+**Repo-pattern relationship:** Departs -- existing injected deps use Result types for
+error-returning deps; plain-promise deps are not wrapped at injection sites.
+
+**Scope:** Too broad -- reaches outside the permitted 3 files.
+
+**Verdict: Rejected.** Out of scope and wrong seam.
+
+---
+
+### Candidate 3: Private helper `safePostToOutbox(deps, msg, meta)`
+
+**Summary:** Extract a private helper that wraps `deps.postToOutbox` in try/catch, reducing
+repetition at the 8+ `postToOutbox` call sites.
+
+**Tensions resolved:** DRY for `postToOutbox`. Accepts: new abstraction not prescribed by task.
+
+**Boundary:** Same 3 mode files, plus a local helper function in `implement-shared.ts`.
+
+**Failure mode:** Helper abstraction obscures the try/catch from reviewers; may hide future
+misuse (e.g., someone using the helper for a call that SHOULD escalate on failure).
+
+**Repo-pattern relationship:** No precedent for dep-wrapper helpers in the mode files. `archiveFile`
+try/catch is inline without a helper.
+
+**Scope:** Best-fit only if `postToOutbox` had 15+ sites. At 8, YAGNI says no.
+
+**Verdict: Skipped.** Task spec gives explicit inline pattern. YAGNI applies.
+
+---
+
+## Comparison and Recommendation
+
+**Candidate 1 is the clear choice.**
+
+All three candidates converge on the same underlying mechanism (try/catch). The only real
+alternatives differ in location (injection site -- wrong boundary) or DRY abstraction (helper --
+not warranted at 8 sites). Convergence is honest here.
+
+Candidate 1:
+- Follows the prescribed pattern from the task description exactly
+- Follows the repo precedent (`archiveFile`, `writeFile` try/catch)
+- Is locally visible and reviewable
+- Carries zero happy-path risk
+- Can be applied systematically to all confirmed call sites
+
+---
+
+## Self-Critique
+
+**Strongest argument against:** The 8+ `postToOutbox` call sites produce repetitive code. If
+the count grew to 20+, a helper would be clearly warranted. At 8, the verbosity is manageable.
+
+**Narrower option that might work:** Only fix `getAgentResult` and `pollForPR` (HIGH severity),
+skip `postToOutbox` wrapping (MEDIUM severity). Would reduce scope. Loses: `postToOutbox` crash
+at escalation decision points is still a real failure mode that kills the pipeline silently.
+
+**Broader option:** Candidate 2 (wrap at injection). Would be justified only if there were a
+precedent of wrapping injected deps at the injection layer. No such precedent exists.
+
+**Invalidating assumption:** If `postToOutbox` is guaranteed never to throw in production (e.g.,
+the real impl is in-memory rather than disk-based). The audit doc confirms it uses
+`fs.promises.appendFile` -- can fail on disk full or permission error. Assumption holds.
+
+---
+
+## Open Questions for Main Agent
+
+None. The problem, solution, and scope are fully specified. Implementation is mechanical.
+
+- Confirm `pollForPR` in `full-pipeline.ts` line 454 also needs wrapping (not explicitly in
+  task description but confirmed unsafe -- include it).
+- For `postToOutbox`: the task says "log a warning and continue". Use `process.stderr.write()`
+  as prescribed, not `deps.stderr()`.
+- UX gate zombie detection in `implement.ts`: add `if (!uxHandle || uxHandle.trim() === '')` guard
+  after line 144, consistent with all 9 other session handle checks in the coordinator.

package/docs/design/coordinator-io-error-handling-design-review.md

@@ -0,0 +1,120 @@
+# Coordinator I/O Error Handling -- Design Review Findings
+
+Generated: 2026-04-19
+
+## Tradeoff Review
+
+### Verbosity (8+ `postToOutbox` inline try/catch sites)
+
+- **Verdict:** Acceptable. At 8 sites, YAGNI wins. The `archiveFile` precedent in the same files
+  shows inline try/catch is the established pattern.
+- **Break condition:** If `postToOutbox` call sites grow to 15+, extract a private helper.
+- **Hidden assumption:** `postToOutbox` call count stays roughly constant in the near term.
+
+### `deps.stderr()` vs. `process.stderr.write()` in catch blocks
+
+- **Verdict:** Use `deps.stderr()` to match the existing `archiveFile` pattern in `implement.ts`
+  and `full-pipeline.ts`. The task spec example uses `process.stderr.write()` but the actual repo
+  uses `deps.stderr()` for the identical use case. `deps.stderr()` is more consistent and testable.
+- **Break condition:** None. `deps.stderr()` is strictly better here.
+
+### `pollForPR` in `full-pipeline.ts` not in task description but included
+
+- **Verdict:** Include it. It's the same unsafe call pattern, same dep, same risk. Excluding it
+  would leave the fix incomplete.
+- **Hidden assumption:** Both `pollForPR` call sites use the same real implementation -- confirmed.
+
+---
+
+## Failure Mode Review
+
+| Mode | Handled? | Risk | Notes |
+|------|----------|------|-------|
+| Missing a call site | Mitigated | Medium | Grep check after implementation |
+| `postToOutbox` throw during escalation sequence | Yes | Low | `return` is on next line after try/catch |
+| `getAgentResult` throw with non-Error | Yes | Low | `e instanceof Error ? e.message : String(e)` |
+| `pollForPR` throw leaving `prUrl` uninitialized | Yes (with care) | Medium | Must use `let prUrl; try {...} catch -> return escalated` |
+| UX gate empty `uxHandle` zombie | Yes (after fix) | Low | Same 4-line guard as 9 other handles |
+
+**Highest-risk failure mode:** `pollForPR` catch block structure. If written incorrectly (catch
+logs but falls through), `prUrl` would be undefined and the subsequent `if (!prUrl)` check would
+catch it -- but the `prUrl` variable would need to be declared with `let` outside the try block.
+The fix requires care in the variable declaration pattern.
+
+---
+
+## Runner-Up / Simpler Alternative Review
+
+**Runner-up:** Private `safePostToOutbox` helper.
+- **Strength worth borrowing:** Standardized log message format across all `postToOutbox` sites.
+- **Adopted:** Standardize the log message format inline (consistent `[WARN coordinator] postToOutbox failed: ...` prefix across all sites).
+- **Rejected:** Full helper extraction. YAGNI at 8 sites. No precedent in repo.
+
+**Simpler alternative:** Skip `postToOutbox` wrapping (only fix `getAgentResult` and `pollForPR`).
+- **Rejected:** `postToOutbox` crashes at critical escalation points. Medium severity is still a
+  production crash path that must be fixed.
+
+---
+
+## Philosophy Alignment
+
+| Principle | Status |
+|-----------|--------|
+| Errors are data | Fully satisfied -- throws become `PipelineOutcome` values |
+| Escalation-first invariant | Enforced -- no throw-exit paths remain after fix |
+| Make illegal states unrepresentable | Satisfied -- coordinator now always returns a value |
+| DI for boundaries | Satisfied -- no new imports, changes are in mode files only |
+| Compose with small functions | Under acceptable tension -- functions grow slightly |
+| Document why not what | Needs 1-line comment per postToOutbox catch explaining non-fatal rationale |
+| YAGNI with discipline | Satisfied -- no speculative helper |
+
+---
+
+## Findings
+
+### Yellow: `pollForPR` variable declaration pattern
+
+The `let prUrl` declaration must be placed BEFORE the try/catch block (not inside it) so that
+the catch block can `return` an escalated outcome and the variable remains in scope after. If
+the variable is declared inside `try`, TypeScript will not compile. This is a known TypeScript
+pattern but worth flagging explicitly.
+
+**Fix:** Use the explicit two-step pattern from the task spec:
+```typescript
+let prUrl: string | null;
+try {
+  prUrl = await deps.pollForPR(branchPattern, PR_POLL_TIMEOUT_MS);
+} catch (e) {
+  const msg = e instanceof Error ? e.message : String(e);
+  deps.stderr(`[WARN coordinator] pollForPR threw: ${msg}`);
+  return { kind: 'escalated', escalationReason: { phase: 'pr-detection', reason: `pollForPR threw: ${msg}` } };
+}
+if (!prUrl) { ... }
+```
+
+### Yellow: `deps.stderr()` vs. `process.stderr.write()`
+
+Use `deps.stderr()` in catch blocks. The task spec example uses `process.stderr.write()` but the
+repo's `archiveFile` catch blocks use `deps.stderr()`. Consistency with repo pattern wins.
+
+---
+
+## Recommended Revisions
+
+1. Use `deps.stderr()` (not `process.stderr.write()`) in all catch blocks.
+2. Use `let prUrl: string | null` declared before the try block for `pollForPR` calls.
+3. Add a one-line comment in each `postToOutbox` catch explaining non-fatal policy:
+   `// postToOutbox write failure is non-fatal -- escalation still returns below`
+4. Include `pollForPR` in `full-pipeline.ts` even though task description only names `implement.ts`.
+5. Include UX gate zombie detection fix in `implement.ts` line 144.
+
+---
+
+## Residual Concerns
+
+- **No tests for throw injection:** This PR fixes the runtime behavior but adds no tests for
+  the throw paths. Tests are a planned follow-up (per the audit doc). The absence of tests means
+  a regression in this fix would not be caught by CI. Low concern for this PR -- the fix is
+  mechanical and the pattern is simple.
+- **`adaptive-pipeline.ts` line 362 `postToOutbox` is unguarded** but is explicitly out of scope
+  for this task. Should be addressed in a follow-up.

package/docs/design/dispatch-dedup-prealloc-bypass-candidates.md

@@ -0,0 +1,187 @@
+# Design Candidates: Bypass Dispatch Dedup for Pre-Allocated Sessions
+
+**Date:** 2026-04-19
+**Status:** Decided -- Option A (guard before dedup block)
+**Scope:** `src/trigger/trigger-router.ts`, `dispatch()` method only
+
+---
+
+## Problem Understanding
+
+### Core Tensions
+
+1. **Dedup protection vs session liveness** -- The 30s dedup window in `dispatch()` exists to prevent
+   duplicate pipeline sessions from webhook retries. But the same mechanism incorrectly kills child
+   sessions spawned by `spawnSession()`, which already pre-created the session in the store via
+   `executeStartWorkflow()`. The invariant 'same key = duplicate' is false for pre-allocated sessions.
+
+2. **Shared state vs path-specific logic** -- `_recentAdaptiveDispatches` is intentionally shared
+   across `route()`, `dispatch()`, and `dispatchAdaptivePipeline()`. This cross-path coupling causes
+   the key collision: `dispatchAdaptivePipeline()` writes `goal::workspace` at t=0, then `dispatch()`
+   reads it at t~=0 and returns early. The fix must carve out an exception for one specific case
+   without breaking the shared-state intent.
+
+3. **Code reuse vs early-exit clarity** -- The dedup block is a scoped `{...}` block at the top of
+   `dispatch()`. Adding the guard before it avoids duplicating the enqueue block, but requires
+   careful restructuring to keep one enqueue call reached by both paths.
+
+### Likely Seam
+
+The real seam is `dispatch()` lines 851-866 (the dedup block). The symptom (zombie session) is
+downstream, but the root cause (early return that bypasses `queue.enqueue()`) is exactly here.
+
+### What Makes It Hard
+
+A junior developer might:
+- Add `_preAllocatedStartResponse` as a new parameter instead of checking the existing field.
+- Delete the dedup block from `dispatch()` entirely (Option B) -- too broad.
+- Add the guard inside the dedup block as a `return` that skips `_recentAdaptiveDispatches.set()`,
+  which is technically acceptable (the map entry from `dispatchAdaptivePipeline()` is still valid
+  for blocking duplicate top-level calls) but less clear.
+- Accidentally duplicate the `queue.enqueue()` callback body, creating divergent result-handling.
+
+---
+
+## Philosophy Constraints
+
+**Source: `/Users/etienneb/CLAUDE.md`**
+
+- **Architectural fixes over patches** -- the guard models the invariant, not a special case
+- **Make illegal states unrepresentable** -- `_preAllocatedStartResponse !== undefined` is a
+  compile-time discriminator; the guard makes 'dedup fires for pre-allocated session' impossible
+- **YAGNI with discipline** -- Option A is the minimal fix; no speculative abstractions
+- **Document why, not what** -- the guard comment must explain the invariant, not describe the code
+
+No conflicts between stated philosophy and repo patterns detected.
+
+---
+
+## Impact Surface
+
+- `spawnSession()` in `src/trigger/trigger-listener.ts` is the only caller that sets
+  `_preAllocatedStartResponse`. The fix must not change its call signature.
+- `queue.enqueue()` callback body in `dispatch()` handles the full `WorkflowRunResult` union
+  (success, error, timeout, stuck, delivery_failed). Both the guard path and the normal path must
+  reach the same callback body -- no duplication.
+- `_recentAdaptiveDispatches` -- for non-prealloc calls, cleanup-on-entry and set must still run.
+- `route()` and `dispatchAdaptivePipeline()` -- no changes to either.
+
+---
+
+## Candidates
+
+### Candidate A: Early-return guard before the dedup block (Option A from design doc)
+
+**Summary:** Add `if (workflowTrigger._preAllocatedStartResponse !== undefined) { void this.queue.enqueue(...); return workflowTrigger.workflowId; }` before the scoped dedup block. The dedup block is only reached when the field is absent.
+
+**Tensions resolved:** Dedup protection vs session liveness (fully resolved for pre-alloc path).
+**Tensions accepted:** Shared state coupling remains -- the map is still shared.
+
+**Boundary solved at:** `dispatch()` entry, before the dedup block. This is the real seam.
+
+**Why this boundary:** The bug fires at the dedup block. The guard is placed exactly where the
+divergence must happen. No other location would be more direct.
+
+**Failure mode:** If the guard path and the normal path have separate `queue.enqueue()` callback
+bodies, any future change to one body must be mirrored to the other. Mitigated by restructuring
+so both paths reach the same enqueue call.
+
+**Repo pattern:** Follows the `dispatchCondition` early-exit pattern in `route()` (lines 641-653).
+Departs in that `dispatch()` previously had no such guard.
+
+**Gains:** Minimal blast radius. Self-documenting -- the guard directly encodes the invariant.
+**Loses:** Slightly more complex method structure if naively implemented with two enqueue blocks.
+
+**Scope:** Best-fit. Single method, single guard.
+
+**Philosophy:** Honors 'Architectural fixes', 'Make illegal states unrepresentable', 'YAGNI'.
+No conflicts.
+
+---
+
+### Candidate B: Wrap dedup block in `if (!_preAllocatedStartResponse)` (same intent, cleaner structure)
+
+**Summary:** Wrap the entire scoped dedup block in `if (workflowTrigger._preAllocatedStartResponse === undefined)`. Both paths then fall through to the same `void this.queue.enqueue(...)` call at the bottom of the method.
+
+**Tensions resolved:** Same as A, plus eliminates code duplication risk.
+**Tensions accepted:** Same as A.
+
+**Boundary:** Same as A.
+
+**Failure mode:** `_recentAdaptiveDispatches.set()` must still run for non-prealloc paths that
+pass dedup. This is naturally handled by the wrap -- the set is inside the block.
+
+**Repo pattern:** More consistent with the existing scoped-block style in `dispatch()`.
+
+**Gains:** Single enqueue block -- no duplication risk.
+**Loses:** The `_preAllocatedStartResponse` check is farther from the enqueue call than in A,
+making the intent slightly less immediate.
+
+**Scope:** Best-fit. Same scope as A.
+
+**Philosophy:** Same as A.
+
+---
+
+### Candidate C: Remove dedup from `dispatch()` entirely (Option B from design doc)
+
+**Summary:** Delete the entire dedup block from `dispatch()`. The dedup that protects against
+webhook retries lives in `dispatchAdaptivePipeline()` and `route()`, both of which are the
+actual entry points for external events.
+
+**Tensions resolved:** Eliminates the shared-state coupling entirely.
+
+**Boundary:** Too broad -- removes protection from the HTTP console route at `console-routes.ts:868`
+which calls `dispatch()` directly.
+
+**Failure mode:** Rapid-fire console dispatches could spawn duplicates if the HTTP layer does not
+deduplicate. No evidence exists that this protection is currently needed, but removing it is a
+behavioral change beyond the scope of this fix.
+
+**Repo pattern:** Departs from the established shared-dedup-map pattern.
+
+**Scope:** Too broad. The task explicitly specifies Option A.
+
+**Philosophy:** Conflicts with 'YAGNI with discipline' -- speculative fix for an unproven gap.
+
+---
+
+## Comparison and Recommendation
+
+All three candidates converge on the same fundamental fix. C is ruled out (too broad). A and B
+are structurally equivalent -- the choice is whether to use an early-return guard (A) or a
+wrapping if-block (B).
+
+**Recommendation: Implement B's structure with A's intent.**
+
+Use `if (workflowTrigger._preAllocatedStartResponse === undefined)` to wrap the dedup block,
+with the `void this.queue.enqueue(...)` call appearing once after the if-block. This gives:
+- No code duplication (single enqueue call)
+- Clear separation: 'if non-prealloc, check dedup; then enqueue regardless'
+- Consistent with the scoped-block style already in `dispatch()`
+
+**Rationale:** The task pseudocode suggests A's early-return pattern, but B is equivalent and
+avoids the duplication risk. Any reviewer familiar with the design doc will understand either shape.
+
+---
+
+## Self-Critique
+
+**Strongest counter-argument:** The task pseudocode explicitly shows an early-return guard (A).
+A reviewer seeing the design doc side-by-side with the implementation may expect exactly that
+pattern. Diverging to a wrap (B) adds a tiny friction.
+
+**Pivot conditions:**
+- If the enqueue callback body diverges between paths in A, switch to B immediately.
+- If `dispatch()` gains a third call path that also needs dedup bypass, consider Option C or
+  a separate dedup map (Option C from design doc) at that point.
+
+**Assumption that would invalidate this design:** If `_preAllocatedStartResponse` could ever be
+set on a call where dedup should still fire. The JSDoc is explicit: the field is only set by
+`spawnSession`/`spawn_agent` which already hold a pre-created session. This assumption is safe.
+
+---
+
+## Open Questions for the Main Agent
+
+None. The problem, solution, boundary, and tests are fully specified.