Repository navigation
design(pm-stack): durability & host independence — stack state in backed-up durable storage, stack survives the laptop being off #1258
Description
Part of epic #1184 (PM stack coherence — ideal-system design series, 2026-10-26).
Why
The stack lives on one laptop: aggregator-local JSON files hold the comment store and session registry, Grist/Kaneo data lives in laptop containers, and if the laptop is off or dies, the PM system of record is gone with it. The ideal stack keeps its state in backed-up durable storage, can run from a second host or the cluster, and proves recoverability with restore drills — the PM system should be at least as durable as the work it tracks.
Design questions to answer
- State inventory: every store (comments, registry, Grist doc, Kaneo Postgres, Pad data, feed/snapshots, Project is GitHub-side) classified by owner, backup method, and acceptable loss.
- Target home: Turso/Supabase/Postgres-on-cluster vs replicated files — which store goes where, and what stays laptop-local by design?
- Failover shape: second-host warm standby, cluster deployment, or cold restore — what RTO/RPO does Drew actually need for a PM dashboard?
- Restore drills: what is restored, how often, and how is a drill result recorded so 'backed up' is a verified fact, not a hope?
- Secrets and identity in a moved stack: SOPS/Bitwarden flow per host, and how the single-URL/Access entry follows the stack.
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 answering every question listed under "Design questions to answer" is landed in the repo
doc/tree and linked from this issue. - Implementation issues are filed and linked as sub-issues of epic epic(dashboard): PM stack coherence - single-URL, fresh data, triage-able, hierarchical #1184 (developing-today/code), each with its own acceptance criteria — this design issue does not itself carry implementation work.
- Every open question that needs Drew is named explicitly in the design note (not buried in prose).
- Every state store in the inventory gets a named target home, backup method, and acceptable-loss figure; RTO/RPO targets for the PM stack are stated as numbers Drew can accept or adjust.
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)Filed directly by a humanQueue packet kind: verify, reproduce, and route this itemQueue or user escalation state
Activity
developing-today commentedon Oct 27, 2026
CODE-382
dezren39 commentedon Oct 28, 2026
Intake review
Fleet-monitor intake pass (2026-10-28T02:40:00Z): this issue was missing a
priority/*label and/or the standard## Acceptance criteriasection and was not yetmeta/enriched. The criteria section has been appended to the body (original text preserved verbatim above it) and labels normalized.Related: Epic: #1184 (PM stack coherence design series). Siblings in the same series were intake-enriched in prior monitor runs (#1264–#1277).
Notes: Design-series issue (durability & host independence), filed 2026-10-27 by Drew as part of the #1184 batch; body is well-formed (Why + design questions + its own Acceptance section). Still live: merged-PR search this run returns only unrelated PRs whose text coincidentally contains the number — none resolves or implements this design.
Risks: Design-only stall risk (see tail).
Suggested approach: This is one of the #1184 PM-stack coherence design series; its own "Acceptance" section already states the bar (design note in
doc/+ implementation sub-issues), and the appended criteria restate that in the fleet's standard heading so the monitor and queue can gate on it. Risks: design-only items can sit silently — per house rules a design with no implementation link is flagged by the next sweep, so the follow-through that matters is the sub-issue filing, not the note alone. Suggested approach: answer the design questions against the current aggregator/orchestrator code (cite file:line), land the note, file the implementation sub-issues in the same pass.🤖 Agent note · state: handed off
dezren39 commentedon Nov 1, 2026
🤖 Agent note · triaged — CONFIRMED; follow-up task 4958 enqueued
pm-stack/aggregator/src/config.ts:74,76— comments and registry stores are plain JSON files (comments.json,registry.json, env-overridable paths);config.ts:20-21calls the registry file the durable store, merged on every read (sources/live.ts:657 mergeIntoRegistry).~/.local/state/pm-aggregator/on the laptop — actions.json, comments.json, registry.json, fleet-feed.json, snapshots/.pm-stack/compose.yml— Kaneo (ghcr.io/usekaneo/kaneo:2.47.0) onpostgres:16-alpinewith a local named volume; Grist is part of the same laptop deployment.pm-stack/README.md:291-292— the only backup story in the repo is a manualpg_dumpinstruction for Kaneo; no automated backup and no restore drill covers comments/registry/Grist.doc/answering every design question here (per-store target home, backup method, acceptable loss; numeric RTO/RPO; restore-drill design; secrets/identity per host; a dedicated Drew-questions section) and file the implementation issues as sub-issues of epic epic(dashboard): PM stack coherence - single-URL, fresh data, triage-able, hierarchical #1184. This issue stays open as the tracker.6 remaining items
Merge pull request #3993 from developing-today/queue/4958-1258-pm-dur…
dezren39 commentedon Nov 3, 2026
agent-note:v1
state: triaged (coverage pass)
Coverage pass 2026-11-03: reviewed in the fleet-wide per-issue pass (drift / overlap / already-handled / stale / blockers / ordering). Verdict: still live; queued in repo-health-code-pilot as triage at priority 40 (priority/normal). If this is already handled at current main, the triage closes it with evidence; if it needs splitting, the triage files the split.
Found via: coverage pass 2026-11-03
dezren39 commentedon Nov 3, 2026
🤖 Agent note · escalated
doc/2026-11-01T21-12-00Z_pm-stack-durability-host-independence/, implementation issue impl(pm-stack): move stateful services off the laptop and prove host failover #3989, issue pm-stack databases (Kaneo Postgres, Grist, Pad) have no backup routine — docker volumes are the only copy #1514, issue pm-stack backups silently produced empty day-dirs for 3 days (stale container names; no alarm) #3869, epic epic(dashboard): PM stack coherence - single-URL, fresh data, triage-able, hierarchical #1184Triage verdict (2026-11-03, task 7677): design acceptance MET; escalating the design's own Drew questions
Fresh verification this shift (gh, current main):
doc/2026-11-01T21-12-00Z_pm-stack-durability-host-independence/with a per-store inventory (target home, backup method, acceptable loss), numeric proposed RTO/RPO, a restore-drill design, and a dedicated "Questions for Drew" section.Why escalated (user/escalated): the design deliberately proposes, but cannot settle, these decisions — they are Drew's, and issue #3989's cutover waits on them:
muse-dev2(consistent with the recorded decision on issue Long-term: migrate the pm stack into Supabase — refactor component state into schemas for central management #3142)? Or Supabase-host some of Kaneo/Grist/Pad too?doc/pm-stack/restore-drills/YYYY-MM.mdwith monthly rotating / quarterly full / annual laptop-off drills?My recommendation (worker review, per the user/review rule): accept Q1 as proposed; Q2 as proposed (it follows Drew's #3142 Supabase-first ruling and keeps service-owned DBs service-owned); Q4 cold restore — GitHub stays usable as degraded mode, so warm standby's complexity buys little; Q5 approve as proposed. Q3/Q6/Q7 need Drew's retention/exception calls specifically.
Until Drew answers, issue #3989 should not start cutover; issue #1514/issue #3869 backup-correctness work is NOT gated by these answers and can proceed independently.
dezren39 commentedon Nov 3, 2026
Owner ruling (Drew, 2026-11-03, via chat): all in Supabase.
Still open on this issue: Q1 (recovery targets), Q3 (off-machine backup retention), Q4 (failover posture), Q5 (restore-drill evidence), Q6 (Project export retention). The #3989 cutover should treat Q2/Q7 as settled per above and surface any service whose storage model cannot literally live in Supabase Postgres (e.g. file-based document stores) as an explicit mapping in the cutover plan rather than a silent exception.
dezren39 commentedon Nov 3, 2026
Owner ruling (Drew, 2026-11-03, via chat): the recommendations are accepted.
(Q2 and Q7 were settled by the earlier all-in-Supabase ruling, comment 6607071220.) Still open on this issue: Q3 (off-machine backup retention) and Q6 (Project export retention) — the #3989 cutover remains gated on those two only.
dezren39 commentedon Nov 5, 2026
Owner ruling (Drew, 2026-11-03, via chat): retention decided.
All seven design questions are now settled (Q1/Q4/Q5 accepted 2026-11-03, comment 6607099664; Q2/Q7 settled by the all-in-Supabase ruling, comment 6607071220; Q3/Q6 here). The #3989 host-independence cutover is ungated.