NEXT: where a control-plane update's outcome lives after it finishes

[onel]

Doc-only. Records the open design question the update-trigger slice (#386) left behind, so it does not get lost.

POST /api/v1/system/update returns a job id and GET /v1/jobs/{id} answers from an in-memory record. Lose the id — closed tab, dashboard reload — or restart host-agent, and the outcome is gone: it survives only as the pair named in images.json and whatever reached the journal. Nothing can answer "did last night's update work, and if not, why."

Three surfaces already promised in locked specs need that answer, which is why the shape is worth settling before any of them is built:

• Settings → Updates (UPDATES.md # 6) — the aggregate view, and where the rollback affordance lives.
• The admin notification (# 8.2, NOTIFICATIONS.md) — explicitly the durable, read-stateful copy for someone who was not watching.
• The hosted report to the cloud (# 8.4 step 5) — a box that reboots mid-window still has to send it.

Filed Tier 2: nothing is blocked today, since the transaction reverts correctly whether or not anyone reads the result — but each of those three would otherwise invent its own record, and discovering three incompatible ones later is the expensive version of this.

The entry weighs the three candidate homes rather than picking one: a system_update row in the brain's SQLite (natural for anything the dashboard reads, but the brain is the thing being replaced and cannot record its own last moments), a small host-agent file beside the ledger (survives the brain, but is a second store), or extending the ledger with the outcome of the transition it already records (fewest moving parts, but turns a declaration into a log). Whichever wins also decides whether job records need persistence at all.

Raised by the maintainer while reviewing #386.

https://claude.ai/code/session_01DpJrjCXiQygMgNsw2AqH25

[greptile-apps]

Confidence Score: 4/5

The PR is safe to merge after a non-blocking documentation correction clarifies the public update-status endpoint.

The persistence discussion matches the current in-memory behavior and locked specifications, but its opening request pair mixes the public brain trigger with an internal host-agent polling route and may misdirect future implementations.

Files Needing Attention: docs/specs/NEXT.md

Important Files Changed

Filename	Overview
docs/specs/NEXT.md	Adds a well-scoped Tier 2 design question, but names the internal host-agent status route as though it were paired with the public update endpoint.

_{Reviews (1): Last reviewed commit: "NEXT: where a control-plane update's out..." | Re-trigger Greptile}

[greptile-apps]

Clarify the status endpoint

This pairs the public POST /api/v1/system/update trigger with the host-agent-internal GET /v1/jobs/{id} route. The corresponding public status endpoint is GET /api/v1/system/update/{job_id}; retaining the internal route here can lead future dashboard or notification implementations to use an unavailable endpoint or confuse it with the unrelated app-job API.

Note: If this suggestion doesn't match your team's coding style, reply to this and let me know. I'll remember it for next time!