Repository navigation
pm-stack(grist): apply external doc changes live — no full server restart #1288
Description
pm-stack(grist): apply external doc changes live — no full server restart
Companion to the Choice-options API gap. Tonight's dropdown fix required stopping and restarting the whole Grist server to make it re-read its own document database; during the window the PM aggregator served fallbacks.
Wanted
A way to make a running Grist server pick up an externally-applied document change without a process restart, any of:
- an admin "reload/reopen document" endpoint,
- a file-watch on the doc store that safely reopens changed docs (with the doc idle / no active editors),
- or a documented, safe
gristCLI subcommand for offline doc edits that a running server tolerates.
Why it matters beyond tonight
The pm-stack direction is more generated content (roadmap seed sync, dashboard build-out #1239). Every generated-schema or bulk-metadata change currently costs a restart window. Live-apply turns those into routine, automatable operations. If upstream Grist can't do this, the fallback ask is a first-class maintenance mode in OUR stack: aggregator drains to fixtures, Grist restarts, health-verified return — scripted end to end instead of by hand.
Acceptance criteria
- A running Grist server picks up an externally-applied document change (e.g. a Choice-options extension) without a full server restart — or, if upstream Grist (OSS v1.7.21, pinned in pm-stack/grist/compose.yml) cannot do this, the fallback ships instead: a scripted maintenance mode in our stack (aggregator drains to fixtures, Grist restarts, health-verified return) that runs end to end unattended.
- During the operation the PM aggregator never serves silent stale/fallback data without signalling it.
- The procedure is documented with the pm-stack docs and exercised once against the Program roadmap doc.
Activity
developing-today commentedon Oct 27, 2026
CODE-411
dezren39 commentedon Oct 27, 2026
Intake review
Related: companion issue #1287 (the Choice-options API gap that forced tonight's restart), epic #1184 (PM stack coherence).
Notes: filed from direct experience (source/human, author dezren39) — the dropdown fix required a full Grist stop/restart and the aggregator served fallbacks during the window. Verified live this run: no open or merged PR implements a live-apply path or the scripted maintenance-mode fallback.
Risks: a partial live-apply could leave Grist's in-memory state diverged from its document database; the fallback's drain step must not drop in-flight aggregator reads silently (the #1110 silent-failure pattern).
Suggested approach: first check upstream Grist for a reload/re-read mechanism or webhook; if absent, build the maintenance-mode script — it is fully in our control and useful regardless.
dezren39 commentedon Nov 1, 2026
🤖 Agent note · picked up
20 remaining items
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 · picked up
dezren39 commentedon Nov 3, 2026
🤖 Agent note · done — triage verdict: ALREADY DONE at current main (task 7688)
pm-stack/grist/reload-doc.shexists on main (blob 22b91c0ece09b2a2bd1853bbe07b7375d2416bc3; header: force Grist to close/reopen a document viaPOST /api/docs/:docId/force-reload, then verify one cell by API read-back; optional idempotent--apply).pm-stack/README.mdon main documents the procedure (§ "Reload a document after an external change", lines 309-340), including distinguishing a document reload from a service restart via the container start time.pm-gristran, force-reloaded and read back through the API, then the exact original value was restored, reloaded and verified; SQLiteintegrity_checkok;pm-gristStartedAtunchanged (2026-10-30T11:29:48Z) before/after — no server restart./api/healthreportedsource.roadmap=live (Grist + projector links)before/during/after; the separate Kaneo-backed board fallback was explicitly reported as fixtures, not silent stale data.