@exaudeus/workrail 3.27.0 → 3.29.0

package/docs/design/temporal-patterns-design-candidates.md

@@ -0,0 +1,312 @@
+# Temporal Patterns Design Candidates for WorkRail Auto
+
+**Status:** Candidates generated from Temporal.io / Prefect / Dagster discovery (Apr 14, 2026)
+**Discovery doc:** `docs/ideas/temporal-discovery.md`
+**For:** WorkRail Auto daemon -- four pattern areas: durability, approval gates, versioning, trigger system
+
+---
+
+## Problem Understanding
+
+### Core tensions
+
+**T1: Temporal's determinism assumption vs AI non-determinism**
+Temporal's entire event-sourcing replay model assumes workflow code is deterministic. WorkRail's domain (AI agent tool calls) is inherently non-deterministic. WorkRail cannot adopt Temporal's replay model. WorkRail's step-level checkpoint token is the correct architecture for the domain -- but it means a crashed step restarts from the beginning of the step, not from the last completed tool call.
+
+**T2: Portability (`npx -y`) vs durability infrastructure**
+Temporal, Prefect, and Dagster all require a server (PostgreSQL/Cassandra + UI). WorkRail must run with zero infrastructure beyond a filesystem. All durability must be file-based. Atomic writes (temp \u2192 fsync \u2192 rename) are the correct primitive.
+
+**T3: Zero compute while waiting for human approval**
+Temporal's `condition(fn, timeout)` is elegant: workflow has no active WFT while waiting, server holds state. WorkRail's daemon cannot hold a connection open indefinitely. Approach: persist checkpoint token to disk, daemon exits or loops, REST endpoint triggers resume from persisted token.
+
+**T4: Multi-tenancy seams without current single-user complexity**
+Adding `orgId` everywhere now = premature complexity. Not adding it now = future breaking refactor. Correct: design as a DI-injected port (`OrgContext`), default to single-user, make multi-tenancy an adapter.
+
+### What makes this hard
+
+WorkRail is a novel category (AI agent process governance). Every Temporal pattern must be adapted at the right abstraction level -- not too literally (adopt replay model), not too abstractly (just 'be durable'). The correct level: take each *invariant* Temporal enforces and find the WorkRail-appropriate mechanism that enforces the same invariant without Temporal's infrastructure.
+
+### Likely seam
+
+The daemon loop (`src/daemon/runWorkflow()` -- not yet built). It sits between trigger dispatch and engine calls. All four pattern areas land here:
+- Durability: token persistence before each `continue_workflow` call
+- Approval gate: polling loop entered after `approvalGate` step is detected
+- Versioning: pinned snapshot loaded at session start, passed through each step
+- Trigger system: cursor committed after session start
+
+### Key discovery
+
+`PinnedWorkflowStorePortV2` already exists (`src/v2/ports/pinned-workflow-store.port.ts`). It stores compiled workflow snapshots by content-addressed `workflowHash`. The `run_started` event already records `workflowHash`. The versioning "gap" may already be solved -- requires verification before building new code.
+
+---
+
+## Philosophy Constraints
+
+From `CLAUDE.md` and confirmed by codebase:
+
+- **Errors as data** -- `neverthrow` `Result`/`ResultAsync` throughout. No exceptions in business logic.
+- **Make illegal states unrepresentable** -- `WithHealthySessionLock` as capability token. `WAITING_FOR_APPROVAL` must be a typed domain state in the event log, not a context variable flag.
+- **Explicit domain types** -- `SessionId`, `WorkflowHash`, `TriggerId` as branded types, not raw strings.
+- **Validate at boundaries** -- Webhook payloads and approval REST calls validated at HTTP boundary; core logic trusts the validated result.
+- **Immutability** -- Session event log is append-only. Pinned workflow snapshots are never mutated in place.
+- **DI for all I/O** -- All new ports injected via `V2Dependencies`. No global state.
+
+**Philosophy conflicts in candidates:**
+- Approval gate REST endpoint that accepts unsigned approvals violates 'validate at boundaries' -- requires HMAC-signed approval token.
+- `TriggerId` as raw string would violate 'explicit domain types' -- must be a branded type.
+
+---
+
+## Impact Surface
+
+- `src/mcp/handlers/v2-workflow.ts` -- `executeContinueWorkflow` path. Versioning candidate must verify this path uses pinned snapshots before building new code.
+- `src/v2/durable-core/schemas/session/events.ts` -- Adding `step_approval_pending` and `step_approval_received` domain events requires extending the `DomainEventV1` discriminated union.
+- `src/v2/ports/` -- Four new ports: `DaemonStateStore`, `ApprovalGatePort`, `TriggerSourcePortV2`, `TriggerCursorStore`.
+- Console service (`src/v2/usecases/console-service.ts`) -- Must surface `WAITING_FOR_APPROVAL` sessions as a distinct state in the DAG.
+- Daemon token persistence (`~/.workrail/daemon-state.json`) -- New file, new path. Does not interact with existing `~/.workrail/config.json` or session store.
+
+---
+
+## Candidates
+
+### Candidate A: Daemon Durability (crash recovery)
+
+**Summary:** Atomic token persistence to `~/.workrail/daemon-state.json` before each `continue_workflow` call. On daemon restart, read file and call `continue_workflow(token)` to rehydrate. No new session-store machinery.
+
+**Approach in concrete terms:**
+```typescript
+// DaemonStateStore port
+interface DaemonStateStore {
+  persistContinueToken(sessionId: SessionId, token: string, stepIndex: number): ResultAsync<void, DaemonStateError>;
+  loadContinueToken(sessionId: SessionId): ResultAsync<{ token: string; stepIndex: number } | null, DaemonStateError>;
+}
+// Implementation: atomic write to ~/.workrail/daemon-state.json
+// Pattern: temp file + fsync + rename (same as session-store/index.ts)
+```
+
+**Tensions resolved:** T2 (no infra, just a file).
+**Tensions accepted:** T1 -- tool-call-level durability not addressed. A 30-tool-call step that crashes at call 25 restarts from call 1.
+
+**Boundary:** `DaemonStateStore` port in `src/v2/ports/`. Implementation in `src/v2/infra/local/daemon-state-store/`. Called by `runWorkflow()` before every `continue_workflow`.
+
+**Why this boundary is best-fit:** The checkpoint token is outside the session lock scope by design. The session store cannot hold the recovery token because acquiring the lock is part of the recovery process. These are two separate concerns.
+
+**Failure mode:** Disk write fails between token receipt and state file write -- session orphaned with no recovery token. Mitigation: atomic temp\u2192rename write (same pattern as session store). If write fails, daemon logs error and exits cleanly; operator retries from last persisted token.
+
+**Repo-pattern relationship:** Directly follows `session-store/index.ts` atomic write pattern. Follows `token-alias-store.port.ts` interface shape.
+
+**Gains:** Zero new infra. Crash recovery for all daemon sessions. Easy to test (mock the file write).
+**Loses:** Sub-step (tool-call-level) crash recovery -- accepted tradeoff for v1.
+
+**Scope judgment:** Best-fit. Does exactly what's needed for daemon crash recovery. Not too narrow (covers all daemon session types), not too broad (doesn't touch session engine internals).
+
+**Philosophy fit:** Immutability (token file is write-once-per-step). Errors as data (ResultAsync). Explicit domain types (SessionId branded type, not raw string key).
+
+---
+
+### Candidate B: Human Approval Gate
+
+**Summary:** New workflow step field `approvalGate: { notifyChannels: string[], timeoutMs: number }` causes daemon to emit a typed `step_approval_pending` domain event, persist checkpoint token, dispatch notifications, and enter a polling loop. REST endpoint `POST /api/v2/sessions/:id/approve` with HMAC-signed approval token appends `step_approval_received` event and releases the gate.
+
+**Approach in concrete terms:**
+
+New domain events (extend `DomainEventV1` discriminated union):
+```typescript
+{ kind: 'step_approval_pending';  sessionId: SessionId; stepId: string; timeoutAt: ISOString; notifyChannels: string[] }
+{ kind: 'step_approval_received'; sessionId: SessionId; stepId: string; approvedBy: string; approvedAt: ISOString }
+{ kind: 'step_approval_timeout';  sessionId: SessionId; stepId: string; timedOutAt: ISOString }
+```
+
+Daemon flow:
+1. `continue_workflow` returns `{ awaitingApproval: true, stepId, timeoutMs }`
+2. Daemon appends `step_approval_pending` event
+3. Persists checkpoint token to `DaemonStateStore`
+4. Dispatches notifications (best-effort -- gate is not blocked by notify failure)
+5. Enters 1s polling loop: checks session event log for `step_approval_received` or `step_approval_timeout`
+6. On approval: calls `continue_workflow` with stored checkpoint token to resume
+7. On timeout: appends `step_approval_timeout`, marks session FAILED
+
+REST endpoint: `POST /api/v2/sessions/:id/approve` -- body includes HMAC-signed approval token (keyed to session + stepId). Appends `step_approval_received` event. Signed token prevents unauthorized advances.
+
+**Tensions resolved:** T3 (process may exit while waiting -- checkpoint token persisted before approval wait, daemon can restart and re-enter polling loop from session store state).
+**Tensions accepted:** T4 -- multi-tenancy (per-org notification routing) deferred to cloud tier.
+
+**Boundary:** Daemon loop (`runWorkflow()`) + new REST route in existing Express server + new domain events in session event log.
+
+**Why this boundary is best-fit:** The approval gate is a daemon concern, not an engine concern. The engine just needs to tell the daemon 'this step requires approval before advancing.' The engine already has a step-blocking mechanism (assessment gates) -- approval gate reuses the same blocking pattern.
+
+**Failure mode:** Approval REST endpoint unreachable (daemon not running, firewall). Mitigation: console UI always works (same REST server). If daemon is not running, the approval write still succeeds -- daemon picks it up on next start via DaemonStateStore recovery.
+
+**Repo-pattern relationship:** New domain events follow `events.ts` discriminated union pattern. REST route follows existing Express server pattern (`src/infrastructure/session/HttpServer.ts`).
+
+**Gains:** Human approval is a first-class typed state in the session history. Survives daemon restarts. Extensible notification channels. Console can show `[WAITING]` badge.
+**Loses:** REST polling (1s interval) is less elegant than Temporal's condition(). For human-scale waits (minutes to hours), polling at 1s is completely acceptable.
+
+**Scope judgment:** Best-fit. Scoped to the approval gate use case. The notification channel list is extensible without design changes.
+
+**Philosophy fit:** Make illegal states unrepresentable -- `step_approval_pending` is a typed event, not a context variable flag. Errors as data -- notification failure returns `Result<void, NotifyError>`, gate not failed. Validate at boundaries -- HMAC-signed approval token validated at REST boundary.
+
+---
+
+### Candidate C: Workflow Versioning for Daemon
+
+**Summary:** Verify first whether `executeContinueWorkflow` already uses the pinned workflow snapshot from `PinnedWorkflowStorePortV2`. If yes: document and move on (no new code). If no: add a 5-line path to load pinned snapshot instead of re-resolving from registry.
+
+**Critical context:** `PinnedWorkflowStorePortV2` already exists and is designed exactly for this purpose (from port docstring: "Enable deterministic execution even when source workflow changes"). The `run_started` event already records `workflowHash`. Export bundles already embed pinned workflows.
+
+**Verification path:**
+```bash
+grep -n "pinnedWorkflow\|PinnedWorkflow\|workflowHash.*get\|pinnedStore" \
+  /Users/etienneb/git/personal/workrail/src/mcp/handlers/v2-workflow.ts
+```
+
+**If already solved (most likely):** The daemon just passes the token from `continue_workflow` response to the next call. The engine resolves the pinned snapshot internally via `workflowHash` in the token. No daemon-level versioning code needed.
+
+**If NOT solved:** Add to `executeContinueWorkflow`:
+```typescript
+const pinned = await pinnedWorkflowStore.get(session.workflowHash);
+if (!pinned) return err({ code: 'PINNED_WORKFLOW_NOT_FOUND', workflowHash: session.workflowHash });
+// Use `pinned` for step interpretation instead of registry lookup
+```
+
+**Tensions resolved:** T2 (no new infra -- existing store). Content-addressed pinning means workflow redeploys cannot affect in-flight sessions.
+**Tensions accepted:** None new -- this is the designed behavior.
+
+**Boundary:** Verification of existing engine path. Possible 5-line addition to `src/mcp/handlers/v2-workflow.ts`.
+
+**Failure mode (if pinned snapshot missing):** `get(workflowHash)` returns null for a session started before pinned store was implemented. Mitigation: existing engine likely falls back to registry -- this is the pre-pinning behavior and is safe for same-version redeploys.
+
+**Repo-pattern relationship:** 100% follows existing pattern. PinnedWorkflowStore is already a registered port in `V2Dependencies`.
+
+**Gains:** Deploy-safe in-flight sessions with zero new code (if verification passes).
+**Loses:** Nothing. This is a verification task masquerading as a design decision.
+
+**Scope judgment:** Too narrow if verification fails. Best-fit if verification passes.
+
+**Philosophy fit:** Determinism over cleverness -- same workflowHash = same compiled workflow content. Immutability -- pinned snapshots never mutated.
+
+---
+
+### Candidate D: Trigger System Cursor Model
+
+**Summary:** Each trigger source (GitLab webhook, Jira webhook, cron) implements a `TriggerSourcePortV2<TEvent, TCursor>` port with a typed cursor. `TriggerCursorStore` persists cursor to `~/.workrail/triggers/<sourceId>.cursor`. On each poll, the dispatcher compares cursor, starts sessions for new events, commits cursor after session start. Adapted from Dagster's sensor pattern.
+
+**Approach in concrete terms:**
+
+```typescript
+// Core port
+interface TriggerSourcePortV2<TEvent, TCursor> {
+  readonly sourceId: TriggerId; // branded type
+  poll(cursor: TCursor | null): ResultAsync<TriggerPollResult<TEvent, TCursor>, TriggerError>;
+}
+
+interface TriggerPollResult<TEvent, TCursor> {
+  readonly events: readonly TEvent[];
+  readonly nextCursor: TCursor; // always present, even if events is empty
+}
+
+// Cursor store
+interface TriggerCursorStore {
+  getCursor(sourceId: TriggerId): ResultAsync<string | null, TriggerCursorError>;
+  setCursor(sourceId: TriggerId, cursor: string): ResultAsync<void, TriggerCursorError>;
+}
+
+// Implementations
+class GitLabMRTrigger implements TriggerSourcePortV2<GitLabMREvent, GitLabCursor> {
+  poll(cursor) { /* GET /api/v4/merge_requests?updated_after=cursor */ }
+}
+class CronTrigger implements TriggerSourcePortV2<CronTickEvent, ISOTimestamp> {
+  poll(cursor) { /* compute missed ticks since cursor */ }
+}
+
+// Dispatcher
+class TriggerDispatcher {
+  async pollOnce(source): Promise<void> {
+    const cursor = await cursorStore.getCursor(source.sourceId);
+    const { events, nextCursor } = await source.poll(cursor);
+    for (const event of events) {
+      // Use event.id as workflowId for idempotency (Dagster's run_key pattern)
+      await engine.startWorkflow({ workflowId: event.id, ... });
+    }
+    await cursorStore.setCursor(source.sourceId, String(nextCursor));
+  }
+}
+```
+
+**Idempotency key:** Event ID used as workflowId. If cursor commit fails and the same event is dispatched twice, `start_workflow` with the same workflowId returns `WORKFLOW_ALREADY_EXISTS` (or equivalent) -- no duplicate session. This is Dagster's `run_key` pattern exactly.
+
+**Cron missed runs:** `CronTrigger.poll(cursor)` computes all missed ticks from `cursor` (last fired time) to `now`. Fires one session per missed tick. Max catchup configurable (`maxMissedRuns` per source).
+
+**Tensions resolved:** T2 (cursor files, no infra). Daemon restart safety (cursor persisted atomically after each batch of sessions started).
+**Tensions accepted:** T4 -- per-org trigger sources deferred to cloud tier (add `orgId` to `TriggerCursorStore` key path).
+
+**Boundary:** New `src/trigger/` module. Isolated from session engine. `TriggerDispatcher` calls `executeStartWorkflow` directly (in-process model).
+
+**Failure mode:** Cursor commit failure after session start -- same event dispatched twice. Mitigated by workflowId idempotency key.
+
+**Repo-pattern relationship:** New ports follow `src/v2/ports/` pattern. Cursor files follow same atomic-write pattern as session store. `TriggerId` follows branded type pattern (`SessionId`, `WorkflowHash`).
+
+**Gains:** Restart-safe trigger dispatch. No missed events. No double-fires (with idempotency key). Extensible: any new trigger source implements the port. Dagster's sensor cursor model is proven at scale.
+**Loses:** Webhook triggers still need an HTTP receiver (separate concern from the cursor model). The cursor model handles durability; the HTTP receiver handles ingestion.
+
+**Scope judgment:** Best-fit. The `TriggerSourcePortV2` interface is the right abstraction boundary. Not too narrow (covers cron, webhook, and future event-based triggers). Not too broad (does not redesign session start flow).
+
+**Philosophy fit:** Explicit domain types (`TriggerId`, `TriggerPollResult`). Errors as data (`TriggerError` as discriminated union). Validate at boundaries (webhook payloads validated before entering trigger system). Functional/declarative (trigger sources are stateless functions; cursor is explicit state).
+
+---
+
+## Comparison and Recommendation
+
+### Matrix
+
+| Criterion | A (Durability) | B (Approval Gate) | C (Versioning) | D (Trigger Cursor) |
+|-----------|---------------|-------------------|----------------|-------------------|
+| Resolves portability (T2) | Yes | Yes | Yes | Yes |
+| Resolves approval-without-open-connection (T3) | N/A | Yes | N/A | N/A |
+| Step-level vs tool-call-level (T1) | Accepts step-level | N/A | N/A | N/A |
+| Multi-tenancy seam (T4) | Partial | Partial | Resolved | Deferred |
+| Repo pattern fit | Excellent | Good | Excellent | Good |
+| Philosophy compliance | Full | Full (with HMAC) | Full | Full |
+| New code volume | ~80 LOC | ~200 LOC | 0-5 LOC | ~300 LOC |
+
+### Recommendations
+
+**Candidate A: ADOPT immediately.** Highest priority -- without crash recovery, the daemon cannot be trusted for any production use. Minimal code, follows existing patterns exactly. No design risk.
+
+**Candidate B: ADOPT for v2 (after daemon MVP).** Approval gates are essential for WorkRail Auto's differentiation ('human in the loop'). Not MVP-blocking -- v1 daemon can run fully autonomous sessions first. The HMAC-signed approval token is required before this ships; unsigned approvals violate the security model.
+
+**Candidate C: VERIFY first (this week).** Run the grep to confirm whether `executeContinueWorkflow` uses pinned snapshots. This is a 5-minute task. If yes, document it and move on. If no, the 5-line fix is the highest-ROI code change in the entire codebase.
+
+**Candidate D: ADOPT for trigger system v1.** The cursor model is the correct foundation. Build `CronTrigger` + `GitLabMRTrigger` as the first two implementations. The HTTP webhook receiver is a separate concern (build it, but don't conflate it with the cursor model).
+
+### Build order
+
+1. Candidate A (DaemonStateStore) -- prerequisite for any daemon session
+2. Candidate C verification -- possibly zero code, immediately valuable
+3. Candidate D (TriggerCursorStore + CronTrigger) -- enables autonomous dispatch
+4. Candidate B (ApprovalGate) -- enables human-in-the-loop after autonomous mode works
+
+---
+
+## Self-Critique
+
+### Candidate A: strongest counter-argument
+"Why not store the checkpoint token in the session event log itself, so there's only one durable store?" The session lock is the obstacle: to append to the session store, you need to acquire the lock. But you need the token to recover from a crashed lock. The out-of-band `daemon-state.json` correctly breaks this circular dependency. The counter-argument loses.
+
+### Candidate B: what would tip the decision
+If approval notifications are unreliable (Slack down, email spam-filtered), the approval gate becomes unusable even though it's technically correct. The console badge must always work even when external notifications fail. This is a UX dependency, not a design flaw.
+
+### Candidate C: what assumption invalidates the design
+If the engine does NOT use pinned snapshots (verification finds that `executeContinueWorkflow` re-resolves from registry), then the entire versioning story relies on workflow definitions never changing between steps. For the current MCP use case (human drives the session in one sitting), this is fine. For daemon sessions (which can run for hours), a redeploy mid-session would break the session. The 5-line fix then becomes a required safety property, not a nice-to-have.
+
+### Candidate D: narrower option considered and rejected
+"Just listen for webhooks and immediately start sessions -- no cursor." D1 loses because daemon restarts drop events. For Jira and GitLab webhooks (transient, not stored), a missed event during a 30-second daemon restart cannot be recovered. The cursor model only adds ~80 LOC to D1 and completely solves restart safety. D2 dominates D1.
+
+---
+
+## Open Questions
+
+1. Does `executeContinueWorkflow` currently use `PinnedWorkflowStore` or re-resolve from registry? (Verify before building C.)
+2. What is the maximum approval wait time WorkRail should support? (Affects whether 1s polling is acceptable or a file-watch is needed.)
+3. Should `TriggerDispatcher` be a separate long-running process or part of the daemon's main event loop? (Related to `src/trigger/` vs `src/daemon/` module boundary.)
+4. How should `step_approval_pending` sessions appear in the existing console DAG? (Requires console-service DTO extension.)

package/docs/design/temporal-patterns-design-review-findings.md

@@ -0,0 +1,163 @@
+# Temporal Patterns Design Review Findings
+
+**Status:** Review complete (Apr 14, 2026)
+**Candidates doc:** `docs/design/temporal-patterns-design-candidates.md`
+**Discovery doc:** `docs/ideas/temporal-discovery.md`
+
+---
+
+## Tradeoff Review
+
+### T1: Step-level crash recovery (accepted)
+A crashed step restarts from its beginning, not from the last completed tool call. Acceptable for v1.
+
+**Condition that invalidates this tradeoff:** A step with non-idempotent destructive side effects (send email, create branch, post Slack message) executes those effects, then crashes before the next step is committed. On restart, the side effect fires again.
+
+**Mitigation required before production:** The `requiredEvidence` field (planned in backlog) must be considered a prerequisite for daemon production use, not just a nice-to-have. It closes this gap for destructive-side-effect steps by requiring the agent to confirm evidence before advancing.
+
+### T2: 1s approval gate polling (accepted)
+For human-scale approval waits (minutes to hours), 1s polling is negligible.
+
+**Condition that invalidates:** 100+ concurrent sessions simultaneously in approval-wait state = 6,000 file reads/minute. Upgrade path: `fs.watch` on the session log directory. No interface change needed.
+
+### T3: Trigger cursor commit failure = possible double-fire (accepted)
+Idempotency key (trigger event ID as workflowId) prevents actual duplicate sessions.
+
+**Condition that invalidates:** Trigger sources without stable event IDs. Resolution: document as a `TriggerSourcePortV2` contract requirement; provide a deterministic hash utility for sources without native IDs.
+
+### T4: No horizontal daemon scale (accepted)
+Single-process, single-machine for v1. Multi-instance deferred to cloud tier.
+
+**Condition that invalidates:** User attempts to run two daemon instances on the same machine with the same `~/.workrail/` directory. The trigger cursor store must use atomic writes (temp\u2192rename) to prevent corruption -- this is already in the design.
+
+---
+
+## Failure Mode Review
+
+### FM1: Disk full at token persistence window (HIGHEST RISK)
+
+A daemon step completes (session advances) but the disk-full condition prevents `daemon-state.json` write. On restart, the daemon re-executes the completed step.
+
+**Coverage:** Atomic temp\u2192rename prevents partial writes. The re-execution failure mode remains for the window between step completion and token file write.
+
+**Missing mitigation:** `requiredEvidence` field. Until it ships, steps with destructive side effects should be explicitly marked as "restart-safe" in workflow authoring guidelines.
+
+### FM2: Approval notification silent failure
+
+All notification channels fail (Slack rate limit, email spam). Session is waiting for approval but no one knows.
+
+**Coverage:** `step_approval_pending` event in session log. Console badge.
+
+**Missing mitigation:** Console MUST display approval-waiting sessions prominently in the session list (not just in session detail). This is a UI requirement.
+
+### FM3: Trigger cursor commit failure (LOW RISK)
+
+Covered by idempotency key. Correctly handled.
+
+### FM4: Two daemons on same machine (LOW RISK)
+
+`LocalSessionLockV2` prevents session corruption. Trigger cursor atomic writes prevent cursor corruption. Idempotency key prevents duplicate sessions. Well-covered.
+
+---
+
+## Runner-Up / Simpler Alternative Review
+
+### Candidate B (Approval Gate) -- runner-up
+
+Not weaker -- correctly deferred (post-daemon-MVP). One element worth pulling forward:
+
+**GREEN finding:** Add `step_approval_pending/received/timeout` to `DomainEventV1` discriminated union NOW (zero behavior change, prevents future schema-breaking change). The schema reservation costs zero LOC.
+
+### Simplification of Candidate A
+
+Plain `fs.writeFile` (20 LOC) instead of a `DaemonStateStore` port (80 LOC) was considered and rejected. The port abstraction is required for testability (all I/O through injected ports -- consistent with 20+ existing ports). Inconsistency cost exceeds simplicity gain.
+
+Scope correction: daemon ports live in `src/daemon/ports/`, not `src/v2/ports/`. This is a correct separation -- not a simplification.
+
+### Hybrid A+B
+
+`PersistedDaemonState` should include an optional `approvalGate` field:
+```typescript
+interface PersistedDaemonState {
+  sessionId: string;
+  continueToken: string;
+  stepIndex: number;
+  approvalGate?: { stepId: string; timeoutAt: string; notifyChannels: string[] };
+}
+```
+Zero additional LOC in Candidate A. Makes Candidate B restart trivial when it ships.
+
+### Simplification of Candidate D
+
+Generic `TriggerDispatcher` can be simplified: v1 hardcodes a loop over configured trigger sources instead of a generic dispatcher. Saves ~100 LOC. `TriggerSourcePortV2` interface kept (justified by 3 required v1 trigger sources). `TriggerDispatcher` added when a third source is needed.
+
+---
+
+## Philosophy Alignment
+
+| Principle | A | B | C | D |
+|-----------|---|---|---|---|
+| Errors as data | SATISFIED | SATISFIED | N/A | SATISFIED |
+| Make illegal states unrepresentable | SATISFIED | SATISFIED (pending schema) | N/A | SATISFIED |
+| Explicit domain types | SATISFIED | SATISFIED | N/A | SATISFIED |
+| Validate at boundaries | SATISFIED | TENSION* | N/A | SATISFIED |
+| Immutability | SATISFIED | SATISFIED | N/A | SATISFIED |
+| DI for boundaries | SATISFIED | SATISFIED | N/A | SATISFIED |
+| YAGNI | SATISFIED | SATISFIED | N/A | TENSION** |
+
+*B tension: HMAC approval token must be validated at the Express middleware layer (before session lock acquired), not inside the engine.
+**D tension: `TriggerSourcePortV2` interface added before second source exists. Justified by v1 scope (3 sources needed).
+
+---
+
+## Findings
+
+### RED findings (blocking)
+
+**None.** No blocking issues found. The four candidates are sound.
+
+### ORANGE findings (important, fix before shipping)
+
+**O1: `requiredEvidence` is a production prerequisite for daemon use.**
+Destructive-side-effect steps + daemon crash = side effect re-executed on restart. The daemon should not be used in production for workflows with destructive steps until `requiredEvidence` is implemented. This is not a design flaw -- it's a scope dependency.
+
+**O2: HMAC approval token validation must be at Express middleware layer, not engine layer.**
+Unsigned or malformed approval requests must be rejected before the session lock is acquired. This is a 'validate at boundaries' requirement.
+
+### YELLOW findings (improve soon)
+
+**Y1: Console must display approval-waiting sessions prominently in session list.**
+Not just in session detail. If the console badge is buried, approval gates become unusable. This is a UI requirement for Candidate B.
+
+**Y2: Add `step_approval_pending/received/timeout` to `DomainEventV1` discriminated union before ANY approval gate ships.**
+Schema reservation costs zero LOC. Prevents future breaking schema changes.
+
+**Y3: `TriggerSourcePortV2` contract must document stable event ID requirement.**
+Trigger sources must either provide a stable event ID or a deterministic hash utility. Undocumented contract = subtle bugs when a new trigger source is implemented.
+
+**Y4: Daemon port scope correction.**
+New daemon ports should live in `src/daemon/ports/`, not `src/v2/ports/`. Daemon concerns are not engine concerns.
+
+---
+
+## Recommended Revisions
+
+1. **Add `approvalGate?` field to `PersistedDaemonState`** (Candidate A hybrid with B). Zero extra LOC, makes B trivial to implement later.
+
+2. **Add `step_approval_pending/received/timeout` event kinds to `DomainEventV1` union** (Y2). Schema reservation only.
+
+3. **Document `requiredEvidence` as a production prerequisite** (O1). Add a warning to the daemon `README` or `backlog.md` build order notes.
+
+4. **Simplify `TriggerDispatcher` for v1** (Candidate D simplification). Hardcoded loop over configured sources. Generic dispatcher deferred.
+
+5. **Document `TriggerSourcePortV2` stable-ID contract** (Y3). One-line JSDoc comment on the `poll()` method.
+
+---
+
+## Residual Concerns
+
+1. **Candidate C false gap.** The landscape research incorrectly identified workflow versioning as an open gap. `PinnedWorkflowStorePortV2` already solves it completely. The discovery process caught this, but it's worth noting: the landscape research should have checked the existing codebase before concluding there was a gap. Future discovery workflows should include a codebase search step before declaring a design gap.
+
+2. **Sub-step durability is an open question for long-running AI operations.** A WorkRail step that calls an LLM for 45 minutes (multi-hop reasoning, large context operations) would lose all progress on crash. For v1 (typical step = 1-5 minutes), this is acceptable. For WorkRail Auto cloud (long-running autonomous coding tasks), this deserves a design session when the evidence of need materializes.
+
+3. **Multi-tenancy seams were identified but not fully designed.** `orgId` as a prefix in `TriggerCursorStore` and `DaemonStateStore` paths is the right seam, but the full multi-tenancy design (credential vault, per-org rate limits, namespace isolation) is deferred. This is correctly deferred for the local daemon -- it must be designed before cloud deployment.