Repository navigation
design(pm-stack): event-driven freshness — replace the 5-minute polling feed with push (webhooks + SSE/WebSocket), polling as reconciliation only #1252
Description
Part of epic #1184 (PM stack coherence — ideal-system design series, 2026-10-26).
Why
Today the aggregator learns about the world from a fleet feed a sandbox collector republishes roughly every 5 minutes, and a stale feed renders indefinitely — freshness is bounded by the poll, and failures are silent until someone notices. An ideal stack is event-driven: GitHub webhooks and local service events push state changes to the aggregator, which pushes them to open browsers in seconds; polling survives only as a reconciliation backstop that proves the push path hasn't missed anything.
Design questions to answer
- Which event sources are in scope v1 (GitHub webhooks via the existing App/tunnel, Kaneo webhooks, collector-local events, orchestration publishes) and what is the delivery path for each?
- Transport to the browser: SSE vs WebSocket, per-page subscriptions, and how the machine-first JSON twins expose the same stream?
- Ordering, dedupe, and replay: how does a reconnecting client catch up, and how does reconciliation detect a missed event?
- Failure posture: when push is down, how is that surfaced (health page, freshness chips) and what poll interval is the fallback?
- Auth: how are webhook signatures and browser subscriptions authenticated under the single-URL/Access model (design(pm-stack): one public URL for the dashboard behind Cloudflare Access (settled access model, not yet implemented) #1182)?
Acceptance
- Design note landed in repo
doc/+ implementation issues filed and linked as sub-issues of epic(dashboard): PM stack coherence - single-URL, fresh data, triage-able, hierarchical #1184; open questions needing Drew named explicitly in the design note.
Acceptance criteria
- A design note is landed in the repo
doc/answering the design questions above: v1 event sources and delivery paths, the browser transport (SSE vs WebSocket) and its JSON-twin exposure, ordering/dedupe/replay, the failure posture with polling as reconciliation only, and webhook/subscription auth under the design(pm-stack): one public URL for the dashboard behind Cloudflare Access (settled access model, not yet implemented) #1182 Access model. - Implementation issues are filed and linked as sub-issues of epic(dashboard): PM stack coherence - single-URL, fresh data, triage-able, hierarchical #1184.
- Open questions needing Drew are named explicitly in the design note.
- The design states how a missed event is detected by reconciliation, and how push-down is surfaced on the health page / freshness chips.
Metadata
Metadata
Assignees
Labels
pm-stack (Pad/Grist) in developing-today/codeMedium: expected under 1 day of workNew feature or capability requestIntake review done: acceptance criteria, links, and normalized labels addedOrdinary priority (the default)Queue or user escalation stateHas a queued task in the Supabase agent queueFiled directly by a humanQueue or user escalation stateQueue or user escalation state
Activity
developing-today commentedon Oct 27, 2026
CODE-376
dezren39 commentedon Oct 28, 2026
Intake review
Related: epic #1184 (parent) · #1182 (Access model — webhook and subscription auth answers depend on it) · #1110 (the orchestration-section rejection, part of the freshness-honesty problem this redesigns).
Notes: Still live — verified this run: no merged PR introduces webhooks/SSE freshness; merged-PR searches return only unrelated number coincidences. The issue arrived with a
## Acceptancesection; the appended## Acceptance criteriaformalizes it.effort/mfor the design pass (implementation is separate follow-up work).Risks / suggested approach: Design-only deliverable in this issue: the acceptance bar is the landed design note plus filed, linked implementation issues — per the standing rule, a design with no implementation link is not finished work. The reconciliation design is the load-bearing part — push without a missed-event detector recreates today's silent-staleness failure with better latency.
— repo-fleet-monitor intake pass, 2026-10-28T03:55Z
16 remaining items
dezren39 commentedon Nov 3, 2026
🤖 Agent note · picked up
user/escalatedstays (Drew hierarchy decision still outstanding).dezren39 commentedon Nov 3, 2026
🤖 Agent note · done — triage verdict: CONFIRMED, resumed via requeued task 4942 (already picked up by a sibling lane)
b7ee42302Findings
queue/4942-1252-event-driven-freshnesssurvived intact in laptop worktree~/git/fleet/4942.pm-stack/aggregator/src/feed.tsrenders the feed as-is with age stated in provenance; no event ingestion path into the aggregator. No design note landed indoc/; no PR was ever opened from the 4942 branch.user/escalatedstays).Route
Resume-from-
implementation_completesmall-fix, gated on Drew's hierarchy decision. Task 6834 completes astriagedwith follow_up_task_ids=[4942]. Labels synced to mirror the live claimed follow-up + the open escalation.dezren39 commentedon Nov 3, 2026
agent-note:v1
event: picked_up
task: 4942 (repo-health-code-pilot; worker repo-worker-code; OpenChamber scheduled lane 335a5d1f-bfc1-4831-99ea-850c8939a727)
state: claimed; resuming from saved implementation_complete checkpoint.
verified: #1252 OPEN; #1184 remains at 100 native sub-issues. Fresh comments contain no hierarchy decision from Drew; #1252 is still marked user/escalated. Existing branch queue/4942-1252-event-driven-freshness and worktree /home/user/git/fleet/4942 remain untouched, with only the saved untracked design-note directory.
next: block escalated-to-user pending Drew deciding alternate parent vs authorizing restructuring; do not move children or retry the 422 add.
dezren39 commentedon Nov 3, 2026
agent-note:v1
event: blocked
task: 4942 (repo-health-code-pilot; worker repo-worker-code; OpenChamber scheduled lane 335a5d1f-bfc1-4831-99ea-850c8939a727)
state: blocked; reason_class=escalated-to-user.
verified: #1252 remains OPEN and user/escalated. Epic #1184 currently has exactly 100 native sub-issues; prior adds for #3976-#3978 returned HTTP 422. No hierarchy decision from Drew is present in the fresh issue history.
Drew decision required: choose an alternate parent/hierarchy for #3976-#3978, or explicitly authorize restructuring an existing child relationship under #1184 to free a slot. Do not move children or retry the 422 add.
resume: after Drew records the hierarchy decision, resume from implementation_complete in branch queue/4942-1252-event-driven-freshness, worktree /home/user/git/fleet/4942; revalidate fresh. Saved draft left untouched.
labels: queue/blocked + status/blocked; user/escalated retained.