Fallback reconcile probe: detect missed webhooks via polling

[mfittko]

Scope

This issue owns the fallback reconcile probe: a periodic background poller that detects missed, delayed, or dropped webhook events and restores expected container execution state.

Responsibilities:

• Poll GitHub API on a configurable interval for open PRs/issues that match dev-loop targets
• Compare GitHub state against worker registry (Worker registry: track active containers, ensure idempotency, handle stale workers #729) to identify targets that should have an active container but do not
• Trigger container spawn (via Container lifecycle manager: spawn, wait, teardown for dev-loop sessions #723) for any unattended target, subject to lease/lock (Container lease/lock manager: prevent concurrent runs on same target #727) check
• Deduplicate: skip targets already running or recently completed
• Coexist with the live webhook path (GitHub webhook endpoint: validate, normalize, route events to target identity #726) — probe fills gaps, does not replace event-driven flow
• Expose configurable poll interval (env or config key); sensible default (e.g. 5 min)
• Log reconcile decisions (skipped, spawned, deferred) at structured DEBUG level

Acceptance Criteria

• AC-1 Probe runs on configurable interval; default ≥ 1 min, configurable via env/config
• AC-2 Probe queries GitHub API for targets in scope (open PRs / issues with active dev-loop label or equivalent)
• AC-3 Probe reads worker registry to determine which targets already have an active container
• AC-4 For each unattended target, probe acquires lease (Container lease/lock manager: prevent concurrent runs on same target #727) before spawning — no spawn without lease
• AC-5 Probe does not spawn if container already running or lease already held (dedup enforced)
• AC-6 Probe and webhook path coexist; a webhook-spawned container is not re-spawned by probe within same lifecycle
• AC-7 Poll interval is tunable at runtime without code change (env var or config reload)
• AC-8 Structured log entry per reconcile cycle: targets checked, skipped, spawned, errors

Definition of Done

• DoD-1 Probe implemented as standalone background loop, isolated from webhook ingestion path
• DoD-2 Integration test: simulate missed webhook → probe detects unattended target → container spawned
• DoD-3 Unit tests for reconcile decision logic (running vs. unattended vs. recently-completed)
• DoD-4 Dedup logic tested: probe skips target with active lease/running container
• DoD-5 Configurable interval documented in repo config reference
• DoD-6 npm run verify passes

Non-Goals

• Receiving or validating webhook payloads — owned by GitHub webhook endpoint: validate, normalize, route events to target identity #726
• Managing container lifecycle (spawn/teardown implementation) — owned by Container lifecycle manager: spawn, wait, teardown for dev-loop sessions #723
• Issuing or revoking leases — owned by Container lease/lock manager: prevent concurrent runs on same target #727
• Tracking worker liveness or heartbeats — owned by Worker registry: track active containers, ensure idempotency, handle stale workers #729
• Replacing the webhook path with polling-only delivery
• Real-time event delivery (probe is best-effort catch-up, not SLA-bound)

AC / DoD Matrix

Criterion	Type	Verified by
AC-1 Configurable interval	AC	Integration test + manual smoke
AC-2 GitHub API query	AC	Unit test (mock API)
AC-3 Registry read	AC	Unit test (mock registry)
AC-4 Lease before spawn	AC	Integration test
AC-5 Dedup enforced	AC	Unit test
AC-6 Coexist with webhook path	AC	Integration test
AC-7 Runtime tunable	AC	Config reload test or doc
AC-8 Structured logs	AC	Log output assertion
DoD-1 Isolated loop	DoD	Code review
DoD-2 Missed-webhook scenario	DoD	Integration test
DoD-3 Decision logic unit tests	DoD	npm run verify
DoD-4 Dedup unit tests	DoD	npm run verify
DoD-5 Interval documented	DoD	Doc review
DoD-6 verify passes	DoD	CI