@exaudeus/workrail 3.32.0 → 3.34.0

package/docs/design/daemon-conversation-logging-plan.md

@@ -0,0 +1,98 @@
+# Implementation Plan: Daemon Conversation Logging
+
+## Problem Statement
+
+The WorkRail daemon runs workflows autonomously but provides minimal visibility into what the agent is actually doing. Today you can see `session_started`, `tool_called`, and `session_completed` in the JSONL event log - but you cannot see what the LLM decided, which tools it requested, how long each tool took, or whether a tool succeeded. Adding `llm_turn_started`, `llm_turn_completed`, `tool_call_started`, `tool_call_completed`, and `tool_call_failed` events - plus a `worktrain logs` CLI command - turns the event file into a real-time audit trail of agent behavior.
+
+## Acceptance Criteria
+
+1. After an LLM API call in `_runLoop()`, `llm_turn_started` is written before the call and `llm_turn_completed` after the response.
+2. For every tool execution via `_executeTools()`, `tool_call_started` is written before `tool.execute()`, and either `tool_call_completed` or `tool_call_failed` is written after.
+3. `tool_call_started` args are truncated to max 200 chars. `tool_call_completed` result summary truncated to max 200 chars.
+4. All new events appear in the same daily JSONL file as existing events.
+5. `worktrain logs` reads today's log file and prints each event formatted for humans.
+6. `worktrain logs --follow` polls the file every 500ms and prints new events as they arrive.
+7. `worktrain logs --session <id>` filters events to those with matching `sessionId`.
+8. `worktrain logs --follow` handles midnight file rotation (switches to new date file).
+9. If the log file doesn't exist, `worktrain logs` prints a helpful message; `--follow` waits for the file.
+10. TypeScript compiles without errors. Existing tests pass.
+
+## Non-Goals
+
+- NOT putting events in the v2 session event store
+- NOT adding a Console Timeline tab
+- NOT deprecating `tool_called` events (backward compat)
+- NOT implementing accurate pre-call token counting (message count proxy is sufficient)
+- NOT searching across multiple day files for `--session` filter
+
+## Philosophy-Driven Constraints
+
+- **Fire-and-forget invariant**: All callbacks in AgentLoop are wrapped in try/catch that swallow errors.
+- **DI for boundaries**: AgentLoop receives callbacks, not DaemonEventEmitter itself.
+- **Make illegal states unrepresentable**: New event kinds added to `DaemonEvent` discriminated union.
+- **YAGNI**: Only the specified event kinds and fields.
+
+## Invariants
+
+1. `tool_call_started` is always followed by either `tool_call_completed` or `tool_call_failed`.
+2. `llm_turn_started` may have no matching `llm_turn_completed` on API error - this is intentional signal.
+3. Callbacks in AgentLoop never propagate exceptions to the caller.
+4. `DaemonEvent` union remains exhaustive.
+
+## Selected Approach
+
+AgentLoopOptions callbacks: 5 optional callback properties on `AgentLoopOptions` called in `_runLoop()` and `_executeTools()`. workflow-runner.ts wires them to `emitter?.emit()`.
+
+## Vertical Slices
+
+### Slice 1: New event types in daemon-events.ts
+- Add interfaces: `LlmTurnStartedEvent`, `LlmTurnCompletedEvent`, `ToolCallStartedEvent`, `ToolCallCompletedEvent`, `ToolCallFailedEvent`
+- Extend `DaemonEvent` union with all 5
+
+### Slice 2: AgentLoopOptions callbacks + emission in agent-loop.ts
+- Add 5 optional callbacks to `AgentLoopOptions`
+- Call with try/catch in `_runLoop()` before/after `client.messages.create()`
+- Call with try/catch in `_executeTools()` before/after `tool.execute()`
+- Add `Date.now()` timing for tool calls
+
+### Slice 3: Wire callbacks in workflow-runner.ts
+- In `runWorkflow()`, pass `AgentLoop` constructor the 5 callbacks
+- Each callback calls `emitter?.emit()` with the appropriate new event kind
+
+### Slice 4: `worktrain logs` CLI command
+- Add `program.command('logs')` with `--follow` and `--session <id>` options
+- Read daily JSONL, format each line, handle ENOENT
+- Polling loop with midnight rotation
+
+### Slice 5: Tests
+- `daemon-events.test.ts`: Add 5 new event kinds to exhaustiveness test
+- `agent-loop.test.ts`: Add tests for callback timing, completion, failure, and try/catch guards
+
+## Test Design
+
+- onToolCallStarted fires before tool execute (verified via call order recording)
+- onToolCallCompleted fires after successful execute (verified with durationMs > 0)
+- onToolCallFailed fires when tool throws (loop continues normally)
+- onLlmTurnStarted fires with correct messageCount before API call
+- onLlmTurnCompleted fires with actual token counts from API response
+- Callbacks that throw do not crash the loop
+
+## Risk Register
+
+| Risk | Mitigation |
+|---|---|
+| Callback throws crash the session | try/catch on all 5 callback invocations |
+| --follow misses events at midnight | Date-check on each poll iteration |
+
+## PR Strategy
+
+Single PR: `feat/daemon-conversation-logging`
+
+## Philosophy Alignment
+
+- DI for boundaries: Satisfied (callbacks, not DaemonEventEmitter in AgentLoop)
+- Make illegal states unrepresentable: Satisfied (discriminated union)
+- Errors are data: Satisfied (tool throws -> tool_call_failed, not propagated)
+- Fire-and-forget: Satisfied (try/catch guards)
+- YAGNI: Satisfied
+- Exhaustiveness: Satisfied (union extended + test updated)

package/docs/design/daemon-conversation-logging-review.md

@@ -0,0 +1,55 @@
+# Daemon Conversation Logging: Design Review Findings
+
+## Tradeoff Review
+
+| Tradeoff | Assessment | Conditions for failure |
+|---|---|---|
+| AgentLoopOptions gains 5 optional callbacks | Acceptable - all optional, zero cost when absent | Would matter if AgentLoop were a versioned public library |
+| Dual `tool_called` + `tool_call_started` events in log | Minor duplication, harmless - different fields, different consumers | If a consumer enforced "one event per tool execution" |
+| `llm_turn_started` uses message count (proxy) | Spec-compliant - user explicitly said "estimate from message count" | If accurate pre-call token counts were needed for routing |
+| `--follow` polls at 500ms interval | Acceptable for human-readable monitoring | If sub-100ms stream was required |
+
+## Failure Mode Review
+
+| Failure mode | Status | Mitigation |
+|---|---|---|
+| Callback throws, propagates into agent loop | **UNMITIGATED - REQUIRES FIX** | Add try/catch around all 5 callback invocations in agent-loop.ts |
+| `tool_call_started` without matching `tool_call_completed` | Handled - catch block emits `tool_call_failed` | No action needed |
+| `llm_turn_started` without matching `llm_turn_completed` (API error) | Acceptable - unmatched started = API error signal | No action needed |
+| `--follow` misses events at midnight file rotation | **REQUIRES FIX** | Check `new Date()` on each poll; switch to new file when date changes |
+| Log file doesn't exist (daemon not started) | Handled - ENOENT returns graceful message | No action needed |
+
+## Runner-Up / Simpler Alternative Review
+
+- **Runner-up (Candidate B, per-tool factories)**: No elements worth borrowing. Centralizing in `_executeTools()` is strictly better.
+- **Simpler alternative (no AgentLoop changes + `turn_end` subscriber for LLM events)**: Fails spec - `turn_end` fires after tool results, not after API response. Not a valid simplification.
+- **Hybrid (callbacks for LLM, per-factory for tools)**: Two patterns for the same concern. Worse than either pure approach.
+
+## Philosophy Alignment
+
+**Satisfied**: DI for boundaries, immutability, make illegal states unrepresentable, errors as data, determinism, YAGNI, validate at boundaries.
+
+**Under tension (acceptable)**:
+- Type safety: `argsSummary` is deliberately a truncated string - this is spec-required (max 200 chars) and appropriate for JSONL serialization.
+- Exhaustiveness: DaemonEvent union grows by 5; no switch consumers exist so this is theoretical only.
+
+## Findings
+
+### Red (blocking)
+None.
+
+### Orange (should fix before implementation)
+1. **Missing try/catch around callbacks in agent-loop.ts**: A buggy callback passed to `AgentLoop` would propagate a throw into the agent loop and crash the session. This violates the fire-and-forget invariant that all observability in the daemon upholds. Fix: wrap each of the 5 callback invocations with `try { callback(info); } catch { /* swallow */ }`.
+
+### Yellow (fix during implementation)
+2. **Midnight file rotation in `--follow`**: The polling loop should check `new Date().toISOString().slice(0, 10)` on each iteration and switch to the new file when the date changes. 3-line fix in the polling loop.
+
+## Recommended Revisions
+
+1. Add try/catch guards around all callback invocations in `_runLoop()` and `_executeTools()` in `agent-loop.ts`.
+2. Add date-aware file switching in the `--follow` polling loop in `cli-worktrain.ts`.
+
+## Residual Concerns
+
+- The `tool_called` + `tool_call_started` dual events: a future cleanup task could deprecate `tool_called` once all consumers migrate to `tool_call_started`. Not in scope for this PR.
+- The `worktrain logs` command reads from the daily JSONL file directly. If sessions span multiple days, `--session <id>` would only find events in the current day's file. A future improvement could search across all files. Not in scope.

package/docs/design/daemon-conversation-logging.md

@@ -0,0 +1,129 @@
+# Daemon Conversation Logging: Design Candidates
+
+## Problem Understanding
+
+### Core tensions
+
+1. **AgentLoop decoupling vs. LLM turn visibility**: AgentLoop is intentionally decoupled from all observability infrastructure (no DaemonEventEmitter import). To emit LLM turn events FROM inside `_runLoop()`, we need to bridge this gap without coupling AgentLoop to daemon-specific types. Options: inject callbacks, use the existing AgentEvent subscriber system, or violate the boundary. The subscriber system fires at `turn_end` (after tool results), which is not the right boundary for `llm_turn_started` / `llm_turn_completed`. Callbacks are the right choice.
+
+2. **Single-source vs. dual-source tool events**: Today each tool factory (`makeBashTool`, `makeReadTool`, etc.) emits `tool_called` directly. Adding `tool_call_started/completed/failed` in `_executeTools()` creates a single centralized emission point. The existing `tool_called` events remain for backward compatibility; new event kinds are additive.
+
+3. **Input token estimation**: True token counts require a tokenizer (tiktoken or the API's usage field). The API returns `response.usage.input_tokens` and `response.usage.output_tokens` in the response. For `llm_turn_started`, emit message count as proxy. For `llm_turn_completed`, emit actual token counts from the API response.
+
+4. **`worktrain logs --follow` streaming**: Node.js file watching is noisy; polling every 500ms is reliable and simple for MVP.
+
+### What makes this hard
+
+Nothing is architecturally hard. The tricky parts are:
+- Getting tool event timing exactly right (started before execute, completed/failed after)
+- For `worktrain logs --follow`: handling the case where the log file doesn't exist yet
+- TypeScript type checking: callback signatures must be precise for ts-strict
+
+### Likely seam
+
+The real seam for tool events is `_executeTools()` in `agent-loop.ts` - it's the single place all tools execute. The real seam for LLM turn events is the `client.messages.create()` call in `_runLoop()`. Both are in `agent-loop.ts`.
+
+## Philosophy Constraints
+
+From `CLAUDE.md` (system-wide):
+- **DI for boundaries**: inject external effects (observability) to keep core logic testable
+- **YAGNI with discipline**: no speculative fields beyond what's in the spec
+- **Exhaustiveness everywhere**: new event kinds extend the `DaemonEvent` discriminated union
+- **Fire-and-forget invariant**: `emit()` is void, errors swallowed - observability never affects correctness
+- **Prefer fakes over mocks**: FakeAnthropicClient pattern in agent-loop tests
+
+No philosophy conflicts found between stated principles and existing repo patterns.
+
+## Impact Surface
+
+- `runWorkflow()` in `workflow-runner.ts`: constructs AgentLoop, must pass new callbacks
+- `AgentLoopOptions` interface: extended with optional callbacks (non-breaking)
+- `DaemonEvent` union: extended with new members (exhaustiveness tests must update)
+- `tests/unit/daemon-events.test.ts`: the exhaustiveness test at line 169 must list new event kinds
+- `tests/unit/agent-loop.test.ts`: needs tests for callback invocation timing
+- No public API changes - all daemon-internal
+
+## Candidates
+
+### Candidate A: AgentLoopOptions callbacks (recommended)
+
+**Summary**: Add 5 optional callback properties to `AgentLoopOptions` in `agent-loop.ts`. Call them synchronously in `_runLoop()` and `_executeTools()`. Wire in `workflow-runner.ts` to call `emitter?.emit()`.
+
+**New properties on AgentLoopOptions**:
+```typescript
+onLlmTurnStarted?: (info: { messageCount: number }) => void
+onLlmTurnCompleted?: (info: {
+  stopReason: string;
+  outputTokens: number;
+  inputTokens: number;
+  toolNamesRequested: string[];
+}) => void
+onToolCallStarted?: (info: { toolName: string; argsSummary: string }) => void
+onToolCallCompleted?: (info: { toolName: string; durationMs: number; resultSummary: string }) => void
+onToolCallFailed?: (info: { toolName: string; durationMs: number; errorMessage: string }) => void
+```
+
+**Tensions resolved**: AgentLoop stays decoupled from DaemonEventEmitter. Single source of truth for tool event timing.
+
+**Boundary**: AgentLoop / workflow-runner.ts interface. Correct seam - AgentLoop is a reusable primitive; workflow-runner.ts is the daemon-specific orchestrator.
+
+**Failure mode**: If a callback throws, it propagates into the agent loop. Mitigated by: callbacks call `emitter?.emit()` which is fire-and-forget and never throws.
+
+**Follows existing pattern**: `DaemonRegistry` uses the same inject-as-optional pattern. `toolExecution: 'sequential'` is already a strategy parameter on `AgentLoopOptions`.
+
+**Gains**: Central timing; no changes to individual tool factories; clean separation; new tools get events automatically.
+**Gives up**: `AgentLoopOptions` interface is slightly heavier (5 optional callbacks). Callbacks are less discoverable than per-tool pattern.
+
+**Scope**: best-fit.
+
+**Philosophy**: honors DI-for-boundaries, YAGNI, exhaustiveness. No conflicts.
+
+---
+
+### Candidate B: Extend per-tool factory pattern (adapt existing)
+
+**Summary**: Keep the existing per-tool `emitter?.emit({ kind: 'tool_called' })` approach. Add `tool_call_started` emit before `tool.execute()` and `tool_call_completed`/`tool_call_failed` after, inside each of the 5 tool factory closures. Add LLM turn callbacks to `AgentLoopOptions` only for the LLM-specific events.
+
+**Tensions resolved**: Minimizes changes to AgentLoop (only 2 callbacks instead of 5). Follows the exact existing pattern.
+
+**Boundary**: Each tool factory is the emission point.
+
+**Failure mode**: 5 tool factories x 3 events each = 15 new emit calls. Duplication risk. New tools added later won't automatically get events.
+
+**Follows existing pattern**: Pure adaptation of the existing `tool_called` pattern.
+
+**Gains**: No callbacks for tool events in AgentLoopOptions; no risk of propagated errors.
+**Gives up**: DRY principle - timing logic duplicated 5x. Maintenance trap.
+
+**Scope**: best-fit for existing tools, but creates technical debt.
+
+**Philosophy**: conflicts with "compose with small, pure functions" (duplication). Honors DI-for-boundaries.
+
+## Comparison and Recommendation
+
+**Recommendation: Candidate A**
+
+Candidate A wins on every meaningful dimension:
+- **Best-fit boundary**: `_executeTools()` is the single canonical execution point for all tools.
+- **Most manageable failure mode**: callbacks call `emitter?.emit()` which can never throw.
+- **Best philosophy fit**: "Compose with small, pure functions" and "DI for boundaries" both point to A.
+- **Easiest to evolve**: Adding a 6th tool gets events automatically.
+- **Consistent with repo patterns**: Same pattern as `DaemonRegistry` injection.
+
+## Self-Critique
+
+**Strongest argument against**: Candidate A adds 5 callback properties to `AgentLoopOptions`. If `AgentLoop` is used in tests without an emitter, the interface is heavier. Counter: all 5 are optional (`?`), zero cost when absent.
+
+**Narrower option that was considered**: Only add LLM turn callbacks (skip `tool_call_started/completed/failed`). Doesn't satisfy the spec.
+
+**Broader option**: Put the emitter directly in `AgentLoopOptions`. Would require `AgentLoop` to import `DaemonEventEmitter`, coupling the modules. Unjustified.
+
+**Invalidating assumption**: None. `_executeTools()` is the only tool execution path in `AgentLoop`.
+
+## Open Questions for Implementation
+
+1. The existing `tool_called` events in per-tool factories (`makeBashTool`, `makeReadTool`, `makeWriteTool`, `makeContinueWorkflowTool`) - keep them as-is for backward compat, or remove them now that `tool_call_started` supersedes them? Decision: keep for backward compat since consumers may depend on them.
+
+2. For the `worktrain logs --follow` command, should it print historical lines first then follow? Yes - show existing entries then poll for new ones.
+
+3. Should `worktrain logs --session <id>` filter by exact sessionId match? Yes.

package/docs/design/github-polling-adapter-design-candidates.md

@@ -0,0 +1,226 @@
+# GitHub Polling Adapter: Design Candidates
+
+**Date:** 2026-04-15
+**Type:** Design Candidates
+**Status:** Draft -- for review
+
+---
+
+## Problem Understanding
+
+### The Ask
+
+Add GitHub Issues and GitHub PRs polling adapters that mirror the GitLab adapter pattern. Poll GitHub APIs on a configurable schedule, deduplicate via `PolledEventStore`, dispatch workflows via `TriggerRouter.dispatch()`. Must include `excludeAuthors` filter to prevent self-review loops.
+
+### Infrastructure Context
+
+The GitLab adapter infrastructure lives in the `feat-polling-triggers` worktree (PR #404, in-flight). It is NOT merged to `main` yet. The GitHub adapter work must be built on top of that branch. Files in scope:
+
+- `src/trigger/adapters/gitlab-poller.ts` -- the direct template
+- `src/trigger/polling-scheduler.ts` -- orchestration; calls adapters and dispatches
+- `src/trigger/polled-event-store.ts` -- per-trigger deduplication state on disk
+- `src/trigger/types.ts` -- `GitLabPollingSource`, `TriggerDefinition.pollingSource`
+- `src/trigger/trigger-store.ts` -- YAML parser, `SUPPORTED_PROVIDERS` set
+
+### Core Tensions
+
+**1. Shared `source:` YAML block vs. type-safe discriminated union.**
+The YAML parser uses one `source:` block with shared field names. GitLab uses `projectId`; GitHub uses `repo`. If reusing the same block, the raw parsed type is a union of optional fields -- structurally looser than the assembled typed model. The discriminated union only kicks in after assembly; the raw parser type cannot be discriminated cleanly.
+
+**2. `pollingSource` field migration vs. backward compatibility.**
+The current `TriggerDefinition.pollingSource?: GitLabPollingSource` field has a code comment requesting migration to a discriminated union at adapter #2 (this change). All existing narrowing in `polling-scheduler.ts` and `trigger-store.ts` must be updated. The impact surface is small but must be handled atomically.
+
+**3. GitHub PR `updated_at` vs. GitLab `updated_after` API semantics.**
+GitLab issues endpoint accepts `updated_after=<ISO8601>` as a server-side filter. GitHub PRs endpoint does NOT accept a `since` parameter -- must fetch all open PRs sorted by `updated` desc, then filter client-side where `updated_at > lastPollAt`. This means more items are fetched per cycle and the deduplication load shifts to the client.
+
+**4. `notLabels` client-side filter vs. pagination.**
+GitHub API supports `labels=foo,bar` (include filter) but has no native exclude. The `notLabels` filter runs client-side. But with only 100 items per page and no pagination, filtering out many items means some new items may be missed. Accepted limitation -- same as the GitLab adapter's pagination limitation.
+
+### What Makes This Hard
+
+A junior developer would:
+1. Skip the discriminated union migration and leave `pollingSource` as a bare `GitLabPollingSource | GitHubPollingSource` union -- the compiler cannot enforce which source type accompanies which provider string
+2. Forget to add `github_issues_poll` and `github_prs_poll` to `SUPPORTED_PROVIDERS` in `trigger-store.ts` -- triggers would silently fail with `unknown_provider` at config load
+3. Use `lastPollAt` as a GitHub PRs `since` parameter (the API ignores it -- no such parameter exists for PRs)
+4. Miss the rate limit header check -- at 5000 req/hour the math is fine for normal use, but a burst or misconfiguration could exhaust it without warning
+5. Place the `excludeAuthors` filter AFTER the dispatch call, creating the self-loop it was meant to prevent
+
+### Likely Seam
+
+`polling-scheduler.ts` is the coordination point. It must route to the correct adapter based on `trigger.provider`. The current code calls `pollGitLabMRs` directly -- this must become provider-aware dispatch.
+
+---
+
+## Philosophy Constraints
+
+From `CLAUDE.md` (hard rules):
+
+- **Errors are data** -- all public functions return `Result<T, E>`, never throw
+- **Immutability by default** -- all types `readonly`, all interfaces use `readonly` fields
+- **Make illegal states unrepresentable** -- the TODO in `types.ts` for discriminated union is exactly this principle; the union migration fulfills it
+- **Validate at boundaries, trust inside** -- `trigger-store.ts` validates all fields at parse time; adapters receive already-validated config
+- **Type safety as first line of defense** -- branded `TriggerId`, explicit `Result` types, type guards
+- **Dependency injection for boundaries** -- `fetchFn` is injectable in `gitlab-poller.ts`; required for the GitHub adapter too
+- **Prefer fakes over mocks** -- tests use `vi.fn().mockResolvedValue()` for fetch; maintain this pattern
+- **YAGNI with discipline** -- no registry pattern (premature for 2 providers)
+
+**Philosophy conflict:** The backlog example uses `excludeAuthors: "worktrain-*"` suggesting glob matching. The `CLAUDE.md` principle of determinism and the YAML parser's lack of glob support argue for exact string matching only. **Resolution:** exact string match for MVP; glob support is a documented TODO.
+
+---
+
+## Impact Surface
+
+Files that must remain consistent:
+
+- `src/trigger/types.ts` -- type shape changes here cascade to the assembler and scheduler
+- `src/trigger/trigger-store.ts` -- `SUPPORTED_PROVIDERS`, `ParsedTriggerRaw.source`, assembly code
+- `src/trigger/polling-scheduler.ts` -- `isPollingTrigger`, `buildWorkflowTrigger`, `doPoll` routing
+- `tests/unit/trigger-store.test.ts` -- tests for `github_issues_poll` and `github_prs_poll` providers
+- `tests/unit/gitlab-poller.test.ts` -- template; existing tests must continue to pass
+
+No other files outside `src/trigger/` read `pollingSource` today.
+
+---
+
+## Candidates
+
+### Candidate A: Minimal extension -- bare union type, if/else in scheduler
+
+**Summary:** Add `GitHubPollingSource` to `types.ts` as a bare union (`pollingSource?: GitLabPollingSource | GitHubPollingSource`), add new providers to `SUPPORTED_PROVIDERS`, extend the `source:` parser, add `if/else` branches in `PollingScheduler.doPoll`.
+
+**Tensions resolved:** Zero migration cost. No changes to existing narrowing code.
+
+**Tensions accepted:** The discriminated union TODO is ignored. TypeScript cannot prevent a `GitLabPollingSource` being used with a `github_issues_poll` trigger at the assembled type level. Illegal states remain representable.
+
+**Boundary solved at:** `polling-scheduler.ts` routing -- additive `if/else` only.
+
+**Why this boundary:** Minimum change surface.
+
+**Failure mode:** A future refactor could accidentally call `pollGitLabMRs` with a `GitHubPollingSource` because the compiler cannot distinguish them without the tag. Silent wrong behavior, not a compile error.
+
+**Repo-pattern relationship:** Adapts existing pattern but ignores the explicit codebase TODO for discriminated union.
+
+**Gains:** Zero migration cost, zero risk of breaking existing code.
+
+**Losses:** Correctness guarantee at the type level. The codebase's own comment requests this migration.
+
+**Impact surface:** `polling-scheduler.ts` only (additive). `types.ts` additive.
+
+**Scope judgment:** Correct scope, but incomplete honoring of stated invariants.
+
+**Philosophy fit:** Honors YAGNI. Violates "Make illegal states unrepresentable".
+
+---
+
+### Candidate B: Tagged union migration (RECOMMENDED)
+
+**Summary:** Migrate `TriggerDefinition.pollingSource` to a discriminated union tagged by `provider`:
+
+```ts
+export type PollingSource =
+  | (GitLabPollingSource & { readonly provider: 'gitlab_poll' })
+  | (GitHubPollingSource & { readonly provider: 'github_issues_poll' })
+  | (GitHubPollingSource & { readonly provider: 'github_prs_poll' });
+```
+
+`trigger-store.ts` assembler produces the tagged object (adds `provider` field to the assembled source). `polling-scheduler.ts` uses `switch(trigger.pollingSource.provider)` or typed `if/else` on `provider` to narrow. `github-poller.ts` is a pure function matching the GitLab adapter signature.
+
+**Tensions resolved:** Discriminated union TODO fulfilled. Illegal states unrepresentable at the assembled type level. `switch` on `provider` is compiler-enforced exhaustive.
+
+**Tensions accepted:** Small migration: ~20 lines of changes in existing files. The raw `ParsedTriggerRaw.source` type in `trigger-store.ts` is still an untagged bag of optional fields (the discrimination only applies after assembly, not during parsing).
+
+**Boundary solved at:** `types.ts` (new union), `trigger-store.ts` (tagged assembly), `polling-scheduler.ts` (switch routing).
+
+**Why this boundary is best fit:** The `types.ts` comment explicitly requests this migration at adapter #2. This IS adapter #2. Not doing it defers a known debt item.
+
+**Failure mode:** If a future consumer outside `src/trigger/` reads `pollingSource` and was not updated during migration. Verified: no such consumer exists today.
+
+**Repo-pattern relationship:** Directly follows what the codebase's own TODO comment requests. Mirrors `TriggerId` branded string: same philosophy of making types carry guarantees.
+
+**Gains:** Compile-time guarantee that GitLab source never reaches the GitHub adapter. Exhaustive `switch` on provider. Clean type-level documentation of which sources exist.
+
+**Losses:** ~20 lines of existing code must be updated. The `pollingSource` field shape changes.
+
+**Impact surface:** `trigger-store.ts` assembler, `polling-scheduler.ts` narrowing, `types.ts`. No external consumers.
+
+**Scope judgment:** Best-fit -- the TODO explicitly scopes this to adapter #2.
+
+**Philosophy fit:** Honors "Make illegal states unrepresentable", "Type safety as first line of defense", "Exhaustiveness everywhere". Minor YAGNI tension (resolved by the existing TODO).
+
+---
+
+### Candidate C: Generic `PollingAdapter` interface with registry
+
+**Summary:** Define `interface PollingAdapter<TItem, TSource>` with `poll(source: TSource, since: string, fetchFn?) => Result<TItem[], error>`. A registry `Map<string, PollingAdapter<unknown, unknown>>` holds all adapters. The scheduler looks up by `trigger.provider`. Adding a new provider = registering a new adapter; no scheduler changes.
+
+**Tensions resolved:** Open/closed: adding providers requires zero scheduler changes. Perfect separation of concerns.
+
+**Tensions accepted:** The registry carries `unknown` typed adapters. The scheduler must cast when building `WorkflowTrigger` context -- type safety lost at the registry boundary. Runtime invariant, not compile-time.
+
+**Boundary solved at:** New `adapter-registry.ts`. Scheduler depends on registry, not specific adapters.
+
+**Why this boundary:** Maximum extensibility for future providers.
+
+**Failure mode:** A misregistered adapter (wrong source type registered under wrong provider key) silently produces wrong context at dispatch time. No compile-time catch.
+
+**Repo-pattern relationship:** Departs from existing patterns. Codebase has no registry or DI container for adapters. Introduces a new abstraction not justified by existing use.
+
+**Gains:** Maximum extensibility (Jira, Linear, Sentry adapters add zero scheduler code).
+
+**Losses:** Type safety at the registry boundary. Complexity for 2 providers. Violates YAGNI and the explicit CLAUDE.md warning against speculative abstractions.
+
+**Impact surface:** New `adapter-registry.ts`, changes to `polling-scheduler.ts`, new abstract type in `types.ts`.
+
+**Scope judgment:** Too broad -- 2 providers do not justify a registry.
+
+**Philosophy fit:** Violates YAGNI, violates "Type safety as first line of defense". Honors open/closed but prematurely.
+
+---
+
+## Comparison and Recommendation
+
+**Recommendation: Candidate B (tagged union migration)**
+
+| Dimension | A (minimal) | B (tagged union) | C (registry) |
+|---|---|---|---|
+| Illegal states representable | Yes (bug risk) | No (compile-time) | Partially (cast gap) |
+| Migration cost | Zero | ~20 lines | High |
+| Exhaustive narrowing | No | Yes | No |
+| YAGNI | Honors | Minor (TODO overrides) | Violates |
+| Consistent with TODO | No | Yes | No |
+| Future extensibility | If/else grows | Union grows | Registry extends |
+
+Candidate B is the correct choice for three reasons:
+
+1. **The TODO is a commitment.** `types.ts` already says "TODO(follow-up): migrate to discriminated union at adapter #2." This is adapter #2. Skipping this is explicitly deferring committed technical debt.
+2. **The migration cost is bounded.** `pollingSource` is only read inside `src/trigger/`. No external consumers. The ~20 lines of changes are confined to three files.
+3. **The gain is real.** The `switch(pollingSource.provider)` pattern gives the TypeScript compiler full narrowing -- it is impossible to call `pollGitLabMRs` with a `GitHubPollingSource` after this change. Candidate A has no equivalent safety.
+
+---
+
+## Self-Critique
+
+**Strongest argument against B:** The raw `ParsedTriggerRaw.source` type in `trigger-store.ts` is still an untagged bag of optional fields -- both `projectId` (GitLab) and `repo` (GitHub) fields exist in the same raw type. The discriminated union only applies after assembly. So the "illegal states unrepresentable" benefit does NOT apply during YAML parsing -- only after. Candidate A has identical parse-time behavior. The union migration adds safety only at dispatch time.
+
+Counter-counter: dispatch time is where safety matters. The assembler is the parser boundary. After the assembler, the system should be able to trust the types -- that's where the discriminated union matters.
+
+**Narrower option that almost works:** Candidate A with a runtime assertion in the scheduler: `assert(trigger.provider === 'gitlab_poll')` before calling `pollGitLabMRs`. But TypeScript structural typing means both source types share enough optional fields that the assert is not enforced by the compiler -- it's a runtime check, not a compile-time one.
+
+**Broader option that might be justified:** Candidate C (registry), but only if 4+ providers are added within 6 months. At 2 providers, the registry is premature. Evidence required: 3+ new adapter types confirmed in the near-term roadmap.
+
+**Pivot conditions:**
+- If `pollingSource` is used outside `src/trigger/` in a future PR (expands migration scope)
+- If the `excludeAuthors` exact-string match is insufficient for the WorkTrain bot naming convention (requires glob support)
+- If the GitHub rate limit at 5000 req/hour proves insufficient for high-volume repos (requires backoff strategy)
+
+---
+
+## Open Questions for the Main Agent
+
+1. **`excludeAuthors` matching**: Should it be exact string match (e.g., `worktrain-bot`) or glob pattern (e.g., `worktrain-*`)? The backlog example uses `worktrain-*`. Exact match is simpler and safer for MVP.
+
+2. **`repo` field format**: Should it be `owner/repo` (single string, split at `/`) or two separate fields `owner` and `repo`? Single string `owner/repo` is consistent with how GitHub URLs work and matches the GitLab `projectId: namespace/project` pattern.
+
+3. **Rate limit skip**: When `X-RateLimit-Remaining < 100`, should this be a `GitHubPollError` kind or a silent skip (log only)? The prompt says "skip the current cycle and log a warning" -- so log only, no error return. Confirm this matches desired behavior.
+
+4. **`notLabels` documentation**: The pagination limitation means `notLabels` can silently miss items on busy repos. Should this be documented in the config schema comment, or is it acceptable as an implicit limitation?

package/docs/design/github-polling-adapter-design-review-findings.md

@@ -0,0 +1,131 @@
+# GitHub Polling Adapter: Design Review Findings
+
+**Date:** 2026-04-15
+**Design reviewed:** Candidate B -- tagged `PollingSource` discriminated union
+**Status:** Complete
+
+---
+
+## Tradeoff Review
+
+### Tradeoff 1: Parse-time raw type is still untagged (accepted)
+
+The `ParsedTriggerRaw.source` bag holds both `projectId` (GitLab) and `repo` (GitHub) as optional fields. Discrimination only applies after assembly. This is valid: the assembler validates required fields with explicit `missing_field` errors. A `github_issues_poll` trigger with `projectId` instead of `repo` will fail at assembly with a clear error.
+
+**Hidden assumption verified:** The assembler must explicitly validate `repo` as required for `github_issues_poll`/`github_prs_poll` (not inherited from GitLab path). Must be in the implementation.
+
+### Tradeoff 2: `excludeAuthors` exact string match (accepted)
+
+Valid for a single controlled bot account. Breaks if the bot naming convention uses unpredictable suffixes. Mitigated by: prominent warning in `GitHubPollingSource` comment, TODO for glob support.
+
+### Tradeoff 3: 100 items per page, no pagination (accepted)
+
+Issues API has native `since` filter -- pagination almost never needed. PRs API lacks `since` -- all open PRs fetched and filtered client-side. Burst risk (>100 PRs in one interval) is low for typical repos. Must be documented.
+
+### Tradeoff 4: GitHub PRs client-side `updated_at` filter (accepted)
+
+Higher API cost per cycle (fetch up to 100 PRs vs. only updated ones). Within rate limit budget at normal poll intervals (42 req/hour for PRs at 5-min interval). Rate limit check guards the threshold.
+
+---
+
+## Failure Mode Review
+
+### RED: Self-loop if `excludeAuthors` not configured
+
+**Risk level:** HIGH. An unconfigured `excludeAuthors` creates an infinite loop: WorkTrain PR -> poll picks it up -> workflow dispatched -> another PR -> repeat. Cascading effects: rate limit exhaustion, unbounded sessions, potential cost impact.
+
+**Current mitigation:** None (it's optional config). User must explicitly set it.
+
+**Required mitigation:**
+- `GitHubPollingSource.excludeAuthors` comment must contain: "IMPORTANT: include your WorkTrain bot account login here to prevent infinite self-review loops."
+- `polling-scheduler.ts` dispatch path comment must repeat the warning.
+- A default auto-detection TODO (WorkTrain could know its own GitHub login) should be filed.
+
+### ORANGE: Rate limit skip has no alerting beyond log line
+
+**Risk level:** Medium. When `X-RateLimit-Remaining < 100`, the cycle is silently skipped with only a console warning. Users who don't monitor logs may not notice the adapter has stopped polling.
+
+**Current mitigation:** Log warning per skipped cycle.
+
+**Recommended mitigation:** No code change needed for MVP, but the log message should include the `X-RateLimit-Reset` timestamp so users know when polling will resume.
+
+### YELLOW: >100 PRs in one poll interval causes silent miss
+
+**Risk level:** Low for typical repos, medium for dependency-bot-heavy repos.
+
+**Mitigation:** Document in `GitHubPollingSource.pollIntervalSeconds` comment. No code change.
+
+### YELLOW: `excludeAuthors` exact match may be insufficient for numbered bot accounts
+
+**Risk level:** Low -- most bot accounts have stable names.
+
+**Mitigation:** TODO comment for glob support. No code change.
+
+---
+
+## Runner-Up / Simpler Alternative Review
+
+**Candidate A (bare union + if/else):** Identified one borrow -- using `trigger.provider` for the dispatch switch is valid, but inside the switch arm TypeScript still needs the tag on `pollingSource` to narrow from `GitLabPollingSource | GitHubPollingSource` to the specific type. The hybrid (trigger.provider switch + untagged union) would require unsafe casts. Not worth pursuing.
+
+**Merged `github_poll` provider:** Rejected. Issues and PRs have different endpoints, different shapes, different filter semantics. Merging adds conditional logic to the adapter. Two single-purpose adapters are cleaner.
+
+**Simpler tagged union (add tag to source, but skip updating `isPollingTrigger` guard):** Already analyzed -- `isPollingTrigger` works unchanged when `pollingSource` becomes `PollingSource`. No simplification available.
+
+---
+
+## Philosophy Alignment
+
+| Principle | Status |
+|---|---|
+| Errors are data | Satisfied -- Result<T,E> everywhere |
+| Immutability by default | Satisfied -- all fields readonly |
+| Make illegal states unrepresentable | Satisfied -- tagged union |
+| Type safety as first line of defense | Satisfied -- type guards at boundary |
+| Validate at boundaries, trust inside | Satisfied -- assembler validates |
+| Dependency injection for boundaries | Satisfied -- fetchFn injectable |
+| Prefer fakes over mocks | Satisfied -- vi.fn() fake pattern |
+| Document why not what | Satisfied -- invariant comments required |
+| YAGNI | Minor tension -- overridden by existing TODO |
+| Determinism over cleverness | Minor tension -- excludeAuthors exact match acceptable |
+
+---
+
+## Findings
+
+### RED
+
+**Self-loop risk is not mitigated by default.** `excludeAuthors` is optional config with no default. A WorkTrain PR polling trigger with no `excludeAuthors` creates an infinite loop. The design must include prominent warnings in the `GitHubPollingSource` type comment and in the `polling-scheduler.ts` dispatch path comment.
+
+### ORANGE
+
+**Rate limit skip log message should include reset time.** When `X-RateLimit-Remaining < 100`, include `X-RateLimit-Reset` (Unix timestamp) in the log message so users know when polling resumes without digging into GitHub's documentation.
+
+### YELLOW
+
+**Both pagination and client-side filtering limitations must be documented in the type comment.** Not in code comments only -- in the `GitHubPollingSource` interface comment where users read it when configuring triggers.
+
+### YELLOW
+
+**`excludeAuthors` exact-match limitation must have a TODO for glob support.** The backlog example uses `worktrain-*` which implies glob. The implementation note should clarify that this is exact match and reference the backlog entry.
+
+---
+
+## Recommended Revisions
+
+1. **Add self-loop warning to `GitHubPollingSource.excludeAuthors` field comment** (required, not optional). Example text: "IMPORTANT: always include your WorkTrain bot account login here (e.g., `worktrain-bot`). Omitting this causes an infinite self-review loop where WorkTrain reviews its own PRs."
+
+2. **Include `X-RateLimit-Reset` in the rate limit skip log message.** Change: `console.warn('[GH] Rate limit low: remaining=${remaining}')` to `console.warn('[GH] Rate limit low: remaining=${remaining}, resets at ${new Date(resetTs * 1000).toISOString()}')`.
+
+3. **Document pagination limitation and client-side filter in `GitHubPollingSource` comments** -- one sentence each.
+
+4. **Add TODO for glob support in `excludeAuthors` comment** -- "TODO: exact string match only. Glob support (e.g., worktrain-*) planned but not implemented."
+
+---
+
+## Residual Concerns
+
+- **`github_prs_poll` redundancy with `github_issues_poll`:** GitHub Issues API returns PRs as well (a PR is also an issue). Using `github_issues_poll` with `labelFilter: my-label` could accidentally pick up PRs. Users should be aware that `state=open` on the issues endpoint includes open PRs. The `github_prs_poll` adapter uses the separate `/repos/:owner/:repo/pulls` endpoint which is PR-only. Both adapters should document this distinction.
+
+- **Authentication:** Only personal access tokens are supported (same as GitLab). GitHub App tokens and fine-grained PATs are not addressed. This is an accepted MVP limitation.
+
+- **`filter.notLabels` naming:** The backlog uses `filter.notLabels` as a nested object. The implementation uses `notLabels` as a top-level field on `GitHubPollingSource` for simplicity (consistent with how `events` and `labelFilter` are flat fields). No structural concern but naming should be consistent with any future filter fields.