Public: anyone can read this; the crew can change it.
A hosted forge's own owner sees when their forge was last backed up, on their forge's settings, in plain words #14035
Check · Review · Land · Live done — Landed and live in production.
A hosted forge's admins now see a Backup row on their own /settings, telling them when their host last backed the forge up. The forge learns this from its host through the heartbeat it already sends. It never reads the host's disk.
shipped production is serving it deploy 4adf612
7 earlier comments · 2 events
A hosted forge's admins now see a Backup row on their own /settings, telling them when their host last backed the forge up. The forge learns this from its host through the heartbeat it already sends. It never reads the host's disk.
- Host side (
src/spawn/heartbeat.ts): after a beat is verified,beatAnsweraddsbackup: {at, bytes}for the forge that sent it. The entry comes from the record the nightly already keeps (readHosted→snapshot/hosted.json); no second record is added. A forge the newest snapshot left out (its entry has awhy), or never kept, gets nobackup. A forge is told only about itself. - Hosted forge side: after each beat the host accepts,
sendBeatstores the answer, plus the host's name fromparent.json's upstream, in its ownparent-backup.json. An answer withoutbackupresets it to none. The new modulesrc/snapshot/hosted_backup.tsholds the parent lookup, the input checks, the stored file and the wording. - Settings (
src/web/pages/account.ts): a hosted forge's admins get one more row next to Started from / Cores: "Backed up by forge.example 5 h ago" or "Not backed up yet". Past 36 hours it adds "; that is more than 36 hours without a backup". That is plain text: no red, no banner. Forges without aparent.jsondon't show the row. - Merge with
main:account.tsconflicted becausemainrenamed the row above to "Started from" and changed how it is drawn. The merge keepsmain's row as it is and adds the Backup row after it.
Left out:
- I put the code in a new module instead of
src/snapshot/backups_line.tsas the issue suggested, because that file pulls in the snapshot service and the heartbeat would have had to import it. - The size is carried in the answer but not shown on the page.
- A forge left out of the newest snapshot shows "Not backed up yet", because the host's record keeps only the newest snapshot, not the last time that forge was kept.
- There is no terminal screen for the row. The gate asked for one, and the merge commit answers it with a "No door:" line saying it can follow.
src/http/server.tsis untouched.
Tests: test/hosted-backup-line.test.ts covers:
- the host's answer for a kept forge, for one it left out, and for one it never kept;
- a hosted forge with no word yet showing "Not backed up yet";
- after a beat carrying a backup, /settings showing "Backed up by forge.test 3 h ago";
- an answer without a backup turning the row back;
- the 36-hour wording.
After the merge, the type check passes, and so do these tests together with spawn-template-record, family-heartbeat and account-rows (41 pass, 0 fail). The gate still prints one note it leaves to the reviewer: it could not tell which page account.ts belongs to, and "Looks: /settings" is not one of the pages listed in forge.json.
To try it: on a hosted forge, open /settings as an admin and read the Backup row. It fills in after the host's next nightly backup and the next beat (beats go every 10 minutes).
🤖 Generated with Claude Code
<!-- look-pages 1ff1a0ab8735 --> Look pages for 1ff1a0a, from the gate:
look pages (none): "Looks: /settings" is not a page of app.looks in forge.json; this pull changes src/web/pages/account.ts but the forge could not trace the route of /settings/security/controls (an inline or wrapped handler), so it could not infer a page; the reviewer decides. A "Looks: <path>" line naming the nearest page, or a "No look: <why>" line (10+ characters), says it
A hosted forge's admin now sees a Backup row on /settings that says when its host last backed it up (#13918). The host includes its newest record for that forge in the reply to each heartbeat the forge sends. The forge saves the reply in parent-backup.json in its own data directory.
The row reads "Backed up by <host> <age> ago". Past 36 hours it adds "that is more than 36 hours without a backup", and with no backup on record it reads "Not backed up yet". It shows only to admins, and only when parent.json names the upstream the heartbeats go to (hasHost in src/snapshot/hosted_backup.ts).
The upstream rule is what fixed the failed check. The preview writes a parent.json holding only an organisation (#11285), and the row used to appear whenever that file existed. So the preview admin's /settings changed with the file, which broke the test "parent.json leaves the admin's settings page and /apps as they were" in test/preview-newcomer.test.ts. The test was right and the code was wrong.
A new test in test/hosted-backup-line.test.ts checks the rule:
- no
parent.json: not hosted; - a
parent.jsonwith only an organisation: not hosted; - a
parent.jsonnaming an upstream: hosted.
Not done: the forge's terminal UI has no backup line, and the host's word is not saved anywhere but the hosted forge's own data directory.
Checks run: bun scripts/gate.ts --fix (it rewrapped one comment, which is committed), bun x tsc --noEmit passed, and test/hosted-backup-line.test.ts plus test/preview-newcomer.test.ts passed (14 tests). The full suite was left to the forge's check.
No look: the Backup row appears only on a hosted forge with an upstream, and the preview isn't one, so a screenshot of the preview would not show it.
To try it, on a hosted forge sign in as its admin and open /settings. It says "Not backed up yet" until the host's next heartbeat reply carries a backup. On a preview, the row should not appear.
🤖 Generated with Claude Code
A hosted forge's admin now sees a Backup row on /settings that says when its host last backed it up (#13918). The host includes its newest record for that forge in the reply to each heartbeat the forge sends. The forge saves the reply in parent-backup.json in its own data directory.
The row reads "Backed up by <host> <age> ago". Past 36 hours it adds "that is more than 36 hours without a backup", and with no backup on record it reads "Not backed up yet". It shows only to admins, and only when parent.json names the upstream the heartbeats go to (hasHost in src/snapshot/hosted_backup.ts).
The upstream rule matters because the preview writes a parent.json holding only an organisation (#11285). Keyed on the file alone, the row also changed the preview admin's /settings, which test/preview-newcomer.test.ts rightly refused.
What to look at:
beatAnswerandsendBeatinsrc/spawn/heartbeat.ts: the host adds the backup to its reply, and the hosted forge saves it.hostedBackupRowinsrc/web/pages/account.ts: the row itself.test/hosted-backup-line.test.ts: the wording, the host's reply, what the hosted forge keeps, and whichparent.jsonfiles count as hosted.
The look-pages note is answered: a new empty commit carries a No look: line. No page the forge photographs can show this row. The preview has no upstream, so the row never appears there, and /settings is not among the pages listed in forge.json (app.looks). Running the gate's rule over this branch's commit messages now returns nothing.
Not done: the forge's terminal UI has no backup line, and the host's word is not saved anywhere but the hosted forge's own data directory.
Checks run: bun scripts/gate.ts --fix, bun x tsc --noEmit, and test/hosted-backup-line.test.ts plus test/preview-newcomer.test.ts all passed. The full suite was left to the forge's check.
To try it, on a hosted forge sign in as its admin and open /settings. It says "Not backed up yet" until the host's next heartbeat reply carries a backup. On a preview, the row should not appear.
🤖 Generated with Claude Code
The mechanism is sound: the child learns it through the signed beat answer, never the parent disk. It reuses the #13832 record, shows the row to admins only, uses no red and no banner, and the tests cover both states. Two things are missing, and each is a miss against the bar.
- Both doors: there is no terminal screen. What an admin reads on /settings must be readable in src/tui/ too, with its entry where AGENTS.md says. Answering the gate with a "No door" line does not meet it. Add the Backup line to the TUI settings/plan screen and test it, reusing parentBackupWords.
- There is no docs/features/<name>.md. Add one saying where the row appears, what the three wordings mean, and that it fills in after the next beat (within 10 minutes). Keep it out of README.
Smaller points to fix in the same round:
- The late wording "...ago; that is more than 36 hours without a backup" is clumsy (principle 8). Say "Last backed up by X 40 h ago, more than 36 hours" or similar in plain words.
- beatAnswer now does a sync readHosted disk read on every beat from every child. Cache it by file mtime or read it once per answer batch, so the beat stays fast.
- Principle 1 (nothing explains itself twice): a one-line row is fine, but the dt "Backup" together with the dd "Backed up by" says it twice. Make the dt "Backup" and the dd "By <host>, 5 h ago", or the other way round.
A hosted forge's admins can now see when their host last backed the forge up, both on /settings and in the terminal. The child forge learns this from its host's signed answer to each beat. It never reads the host's disk, and the host only tells each forge about itself.
- Where it shows: /settings has a "Backup" row under the plan, for admins only. The terminal's admin-only Plan screen shows the same words as a second line,
Backup: …, built from the sameparentBackupWords. Forges with no host, previews included, show neither. - Wording: the row's title is "Backup" and the value says the rest, so nothing is said twice:
- "By forge.example, 5 h ago"
- "By forge.example, 40 h ago, more than 36 hours" once it is late. Plain words only, no red, no banner.
- "None yet" when the host hasn't answered, or its newest backup left this forge out.
- Beat cost: the host keeps its backup record (
snapshot/hosted.json) in memory and reads it again only when the file's modification time or size changes. A beat now costs one file stat, not a read. - Docs:
docs/features/hosted-backup-line.mdexplains where the row shows, what each wording means, and that it fills in within 10 minutes of the host's backup. It is listed under "Backups and moving" indocs/features/README.md; the top-level README is unchanged. The page that already sat athosted-backup.md(hosted forges in the host's nightly backup) is unchanged, and the new note links to it.
Tests:
test/tui-plan-row.test.tschecks that an admin on a hosted forge sees "Backup: None yet", then "Backup: By host.example, 3 h ago" once the host has answered.test/hosted-backup-line.test.tscovers the new wordings, the terminal line on hosted, unhosted and preview data, and that a rewritten host record is read again rather than served from memory.gate,tscand design-lint pass, and so do the beat, hosted-backup, palette, settings, plan and both-doors suites.scripts/fast.tspicked about 2,300 test files for this diff, far over its 5-minute budget, so I picked the covering suites myself rather than running that set; the forge's check runs the full suite.
To try it: on a hosted forge, sign in as an admin and open /settings, or press Ctrl-K → Plan in the terminal. It says "None yet" until the next beat after the host's nightly backup.
🤖 Generated with Claude Code
A hosted forge's settings page now has a Backup row. It reads "Backed up by <host> <relative time>" from the record the nightly backup (#13832) already keeps on the parent, or "Not backed up yet" when there is no record. After 36 hours without a backup the row says so in words, with no red and no banner. The time travels over the existing child-to-parent beat, so the child never reads the parent's disk. The row only appears on a forge that a host beats for, so a preview's seeded parent record doesn't show one. The terminal shows the same line.
The last check failed on the gate's "pipeline first" rule: the pull adds a feature doc (docs/features/hosted-backup-line.md) and changes no pipeline paths. The code is the same as in that run. The only new commit is an empty one whose message carries a Direction: line. It says #13918 is the planned next step of #13819 after #13832, and that it reads the backup record the pipeline already writes without adding pipeline work. bun scripts/gate.ts now passes here. The type check and tests were not run again for this push because no code changed.
To try it: on the preview, open /settings on a hosted forge whose parent has a backup record and look for the Backup row.
🤖 Generated with Claude Code
A hosted forge's own settings page now has one Backup row saying when its host last backed it up. It reads "By <host>, 5 h ago", adds ", more than 36 hours" when the backup is late (in words, not red, no banner), or says "None yet". The terminal's Plan row shows the same line.
How the time gets there: the host already records what its newest nightly snapshot kept of each forge in snapshot/hosted.json (#13832). It reads that record on every signed beat, a forge's regular check-in with its host, and answers with that forge's entry only (backupFor in src/spawn/heartbeat.ts). The child saves the answer in its own data directory, so it never reads the host's disk. A forge that no host beats for shows no row. That includes a preview, whose seeded parent.json names only an organisation.
The host reads its record on each beat, with no cache kept in the process (src/snapshot/hosted_backup.ts). An earlier version kept one and broke the rule in test/module-state.test.ts. A beat comes every ten minutes per forge, so the plain read costs little. The Plan entry in the palette now says "this forge's plan, its last backup, and where its owner manages billing". I updated the roster pin in test/palette-roster.test.ts to that wording: the test was right, the hint changed on purpose. A Direction: line in the commits explains why this goes ahead of the pipeline items: it is the planned next step of #13819 and only reads a record the pipeline already writes.
bun scripts/gate.ts, bun x tsc --noEmit and the covering tests pass locally. That covers test/hosted-backup-line.test.ts, test/tui-plan-row.test.ts, test/module-state.test.ts, test/palette-roster.test.ts and test/capacity.test.ts. The capacity test failed in the forge's check by hitting its 30-second limit and passed here, so I left it unchanged.
To try it: open /settings on a hosted forge whose host has a backup of it and look for the Backup row.
🤖 Generated with Claude Code
The mechanism is sound: the answer rides the signed beat, the child never reads the host disk, the host tells a forge only about itself, the record is #13832 reused, the row is admin-only, the late wording is plain with no red, the terminal shows the same line, and the feature doc is under docs/features (not README). No security finding.
One thing to fix first: the words do not match what the issue asked. Box 2 says the line reads "Backed up by <host> <relative time>" or "Not backed up yet"; the pull ships "By host, 5 h ago" and "None yet". Box 4 asks a test to show "Not backed up yet", and the tests pin "None yet". Make the dd read "Backed up by <host> <age> ago" / "Not backed up yet" (keep dt Backup out, or make the dt the whole sentence so nothing is said twice), keep ", more than 36 hours" for the late case, derive that text from BACKUP_LATE_MS rather than a literal, and update the tests, the TUI line, and docs/features/hosted-backup-line.md to the same words.
Smaller: the fixed .tmp name in noteParentBackup can race two beats; use a unique temp name.
A hosted forge's own settings page now says when its host last backed it up, in the issue's words: "Backed up by <host>, 5 h ago", or "Not backed up yet". Past 36 hours the line adds ", more than 36 hours", in plain words with no red and no banner. That text is built from BACKUP_LATE_MS, not written as a literal.
Where it shows. Only admins see it, and only on a forge that a host beats for, so a preview shows nothing. The settings row puts "Backed up by <host>" or "Not backed up yet" as its label and "5 h ago" as its value, so nothing is said twice. A row with no backup has an empty value. The terminal's Plan screen shows the whole sentence on one line (src/tui/screens/planrow.ts).
How it gets there. The host already records each forge's newest backup in snapshot/hosted.json (#13832). On each signed beat it answers with that forge's own entry and nothing about any other forge (backupFor in src/snapshot/hosted_backup.ts). The hosted forge saves the answer as parent-backup.json in its own data directory and never reads the host's disk. The host reads its record on every beat and keeps no copy in memory between beats.
Review fixes.
- The words now match the issue in the code, both tests and
docs/features/hosted-backup-line.md. - The saved answer is written through a temp file with a new name each time, so two beats can't write to the same temp file. No test covers this, because the write is synchronous and can't race within one test process.
Checks. The gate, type check and design lint pass. test/hosted-backup-line.test.ts, test/tui-plan-row.test.ts, test/palette-roster.test.ts and test/module-state.test.ts pass (29 tests). test/palette-roster.test.ts now expects the Plan entry's new hint, "this forge's plan, its last backup, and where its owner manages billing": the hint changed on purpose, and the test was not wrong.
A Direction: line in the commits explains why this goes ahead of the pipeline items: it is the planned next step of #13819 and only reads a record the pipeline already writes.
To try it: on a hosted forge whose host has a backup of it, open /settings as an admin, or the Plan screen in the terminal.
🤖 Generated with Claude Code
Earlier asks, all met in this head: the words are the issue ("Backed up by <host>, 5 h ago" / "Not backed up yet"), the late text is built from BACKUP_LATE_MS, the temp file name is unique per write, and the tests, TUI line and feature doc carry the same words. The record is #13832 reused, the answer rides the signed beat, a forge is told only of itself, admin only, no red or banner, how-to is in docs/features (README untouched), and the terminal Plan screen shows the same line. The row is a dl row with no new component class, so I found no break of the DESIGN.md principles. The preview is not hosted, so it correctly shows no row; the tests cover the row.
Next two things, both non-blocking:
- Non-blocking: "Not backed up yet" renders an empty <dd></dd> (src/web/pages/account.ts, hostedBackupRow). Screen readers announce an empty definition; put the sentence in the dd under a fixed dt such as "Backup", or omit the dd.
- Non-blocking: when the host stays silent for days the line still shows the last stored age; consider noting when the host was last heard.
A hosted forge's admins now see a Backup row on their own /settings, telling them when their host last backed the forge up. The forge learns this from its host through the heartbeat it already sends. It never reads the host's disk.
src/spawn/heartbeat.ts): after a beat is verified,beatAnsweraddsbackup: {at, bytes}for the forge that sent it. The entry comes from the record the nightly already keeps (readHosted→snapshot/hosted.json); no second record is added. A forge the newest snapshot left out (its entry has awhy), or never kept, gets nobackup. A forge is told only about itself.sendBeatstores the answer, plus the host's name fromparent.json's upstream, in its ownparent-backup.json. An answer withoutbackupresets it to none, so the row falls back to "Not backed up yet". The new modulesrc/snapshot/hosted_backup.tsholds the parent lookup, the input checks, the stored file and the wording.src/web/pages/account.ts): a hosted forge's admins get one more row next to Made from / Cores: "Backed up by forge.example 5 h ago" or "Not backed up yet". Past 36 hours it adds "; that is more than 36 hours without a backup". That is plain text: no red, no banner. Forges without aparent.jsondon't show the row.Left out:
src/snapshot/backups_line.tsas the issue suggested, because that file pulls in the snapshot service and the heartbeat would have had to import it.src/http/server.tsis untouched.keep_planorestimate(not available in this run), so the issue has no plan list and no time promise.Tests:
test/hosted-backup-line.test.tscovers:It passes, and it can't pass without the change (it imports the new module and checks the new row). The type check, the gate and the design lint pass. These suites also pass: family-heartbeat, beat, spawn-app-links, spawn-template-record, spawn-chain, forge-link-expiry, account-rows, account-timing, snapshot-hosted, hosted-surfaces and tui-plan-row.
scripts/fast.tsnamed 2,299 files, so I didn't run that full set; the forge's check runs everything.To try it: on a hosted forge, open /settings as an admin and read the Backup row. It fills in after the host's next nightly backup and the next beat (beats go every 10 minutes).
🤖 Generated with Claude Code
Closes #13918