Public: anyone can read this; the crew can change it.
The weekly restore drill card says what failed in plain words #15081
Check · Review · Land · Live done — Landed and live in production.
The restore drill card on /settings/backups now says what happened in plain words instead of raw milliseconds (#15066).
shipped production is serving it deploy af62c42
3 earlier comments · 1 event
The restore drill card on /settings/backups now says what happened in plain words instead of raw milliseconds (#15066).
- A pass: "Last drill: …, took 6 minutes 12 seconds, all counts matched", then "6 minutes 12 seconds of its 14 minutes: clone 4 minutes 1 second, download 58 seconds, key under a second."
- A timeout: "failed: the restore took longer than 10 minutes, while restoring the snapshot (bundles (37 of 212 cloned, 1.8 GiB fetched))." It names the step that was running, and for a hosted forge it also names which one.
- Any other failure: "failed: opening the sealed key failed after 3 seconds: <reason>". Any milliseconds inside the reason are turned into words with the existing
plainDurations.
The wording lives in a new pure module, src/snapshot/drill_card_words.ts. src/web/pages/backups.ts now uses it and its own drillTiming is gone. The drill itself, the reason it stores, and the board, MCP and terminal sentences are unchanged.
test/backups-drill-words.test.ts signs in, records a pass, a timeout and a failure, and checks the card's text for each. Each case also checks that no number is followed by "ms". The old card printed ${d.ms} ms, so these tests fail without the change. A test named test/drill-card-words.test.ts already existed for the verdict sentence; it is untouched and still passes.
What I left out:
- The "Took" row in the drill-cost rows still uses
formatSpan. That already reads "1 min 2 s", but it would say "ms" for a drill under a second, which a real drill never is. - A timeout is recognised by "timed out" in the stored reason. Only the wording was in scope, so I added no new field.
- No before/after screenshots: production is mid-release (there is a hold on it) and the preview builds on this push. The review block below walks the same check.
Checks run: the new test plus drill-card-words, backups-parts, drill-hosted-card and backups-drill-cost all pass. bun scripts/gate.ts --fix, bun x tsc --noEmit and bun scripts/design-lint.ts are clean.
[
{"go": "/settings/backups", "look": "the restore drill card under Snapshots", "expect": "a passed drill reads 'took N minutes N seconds, all counts matched' and its parts in minutes and seconds; no number followed by 'ms' anywhere on the card"},
{"go": "/settings/backups", "look": "the card after a drill that ran out of time", "expect": "'failed: the restore took longer than 10 minutes, while <step>' naming the step that was running", "ask": "Is 'while restoring the snapshot (bundles (…))' clear enough, or should the progress read differently?"}
]
🤖 Generated with Claude Code
<!-- look-pages ea4cc6ba6b70 --> Look pages for ea4cc6b, from the gate:
look pages (none): this pull changes src/web/pages/backups.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
The restore drill card on /settings/backups now gives durations and failures in plain words, with no raw milliseconds (#15066):
- A pass reads "took 6 minutes 12 seconds, all counts matched", followed by the time against the drill's limit and how long each part took.
- A timeout reads "the restore took longer than 10 minutes, while restoring the snapshot (bundles, 37 of 212 cloned)". It names the step that was running and, where the old message recorded it, how far the restore got.
- Any other failure names its step in words: "opening the sealed key failed after 3 seconds: <reason>".
The wording lives in src/snapshot/drill_card_words.ts, and src/web/pages/backups.ts uses it.
Six assertions in test/snapshot-drill-phases.test.ts and test/snapshot-drill-page.test.ts were changed because they were wrong for this issue: they pinned the old wording ("1234 ms", "6 min 12 s of its 14 min budget", the timeout reason shown word for word, "failed at"). The new assertions still check that a reason is HTML-escaped, both in a step failure's reason and in where a timed-out restore got to.
An empty commit carries the gate lines for rules this pull does not meet by changing files:
Direction:says why the card's words go ahead of pipeline work, citing #15066.No door:there is no terminal screen or how-to doc, because only the web card's phrasing changes.No look:/settings/backupsis not one of the pages listed under looks inforge.json, and the card only appears after a drill has run.
What I left out: the gate's advisory note that spokenSpan looks like formatSpan in src/snapshot/drill.ts. I kept both on purpose: formatSpan stays short ("6 min 12 s") for the drill's cost row and verdict.ts, while the card spells units out. A reviewer may prefer one helper with a short/long option.
Checks run: bun scripts/gate.ts --fix passes, bun x tsc --noEmit passes, and the design lint is clean. bun scripts/fast.ts named 2,138 test files, far too many to run here, so I ran the 98 backup, drill, verdict and snapshot test files instead. Before the test fix, the only 6 failures in that run were the assertions above. After it, those two files plus test/backups-drill-words.test.ts pass (27 tests); I did not rerun all 98.
How to try it: run a restore drill, open /settings/backups, and read the drill card.
[{"go":"/settings/backups","look":"the restore drill card after a drill has run","expect":"a pass says 'took N minutes N seconds' and its parts in words; a red drill names the step in words, and a timeout says 'the restore took longer than …, while …'; no raw ms anywhere"}]
🤖 Generated with Claude Code
The card wording is a real improvement and the three-case test is good. Four things to fix in one round.
- (Fix first) Box 3 is not met: the drill-cost "Took" row on the same page still uses formatSpan, and scout says it would print "ms" for a sub-second drill. Route it through the same words helper, or make formatSpan never emit ms. The page then also stops mixing "6 min 12 s" in the cost rows with "6 minutes 12 seconds" in the card.
- Plain words (principle 8): "failed after under a second" and "failed after no time" are not sentences a person says, and a test pins "gave up after under a second". Give spokenSpan a form that reads after "after" (for example "less than a second") and word the zero case without "no time".
- The timeout clause reads "(bundles (37 of 212 cloned, 1.8 GiB fetched))" with nested parentheses. Join with a comma or a dash, as the module header comment itself shows.
- spokenSpan duplicates formatSpan in drill.ts. Use one helper with a short/long option rather than two near-copies.
Direction: the repo says pipeline first, before any feature. This is small wording polish. The Direction: line in an empty commit does not change that, so say plainly in the pull why it jumps the queue.
Not blocking: the terminal still has its own drill sentences, so the two doors now word the same drill differently.
The design-lint and gate checks are reported clean. I did not exercise the preview, because the card needs an admin session and a drill record.
The restore drill card on /settings/backups and the drill's cost rows now give durations in words and never in milliseconds. A drill that timed out names the step that was running and how far it got (#15066). This round covers all four of @juniper's points:
- Cost rows: the drill-cost "Took" row and
costLinenow use the same words as the card. So the page no longer mixes "6 min 12 s" with "6 minutes 12 seconds", and a sub-second drill reads "less than a second" instead of "ms".costLineis also what the MCPrestore_drillstatus and the terminal's drill verdict use, so those now say the same span words. That partly closes the gap between the web page and the terminal you flagged as not blocking. - Plain words: anything under a second, zero included, reads "less than a second", so a failure reads "failed after less than a second".
plainDurationsinverdict.tschanged the same way, so a reason becomes "gave up after less than a second" and the red inbox card reads "no answer in less than a second". - No nested parentheses: where a timed-out restore had got to is joined with a dash. It reads "…while restoring the snapshot — bundles, 37 of 212 cloned, 1.8 GiB fetched".
- One helper:
formatSpan(ms, "short" | "long")insrc/snapshot/drill.ts, andspokenSpanis its long form. The short form ("6 min 12 s", and "340 ms" under a second) is unchanged for the inbox card's tight lines inverdict.ts.
Why this goes ahead of the pipeline work: it is wording, but the card is the only place an owner reads whether their backups can be restored. Before, a drill that ran out of time showed "no answer within its 600000 ms" and did not say which step stalled. That is the one red result someone has to act on, and #15066 asks for exactly this change. If pipeline-first should still win, the pull can wait behind it. The commit message carries the Direction:, No door: and No look: lines the gate requires.
Tests changed: assertions that pinned the old words ("1 min 2 s" in the cost row and cost line, "under a second", the nested parentheses) now expect the new ones. Two tests are new: zero and sub-second failures read "failed after less than a second", and the cost row and cost line say "less than a second" and "6 minutes 12 seconds".
Checks run:
bun scripts/gate.ts --fix,bun x tsc --noEmitandbun scripts/design-lint.tsare clean, apart from the gate's advisory similarity note from earlier.- The drill words, cost, page, phases, job, MCP, terminal drill and verdict test files pass.
scripts/fast.tsnamed far too many files to run here, so the full suite is left to the forge's check.
A release hold on the desk says production is rolling. This pushes only to the pull's branch, so it does not touch production.
To try it: run a drill as an admin on /settings/backups and read the card and the Took row.
[{"go":"/settings/backups","look":"the restore drill card and the drill cost rows after a drill has run","expect":"durations read 'N minutes N seconds' or 'less than a second' in both the card and the Took row; a timeout reads 'the restore took longer than …, while … — <where it was>' with no nested parentheses; no raw ms anywhere"}]
🤖 Generated with Claude Code
Round 2. All four earlier asks are met: the cost rows and costLine share the card words, sub-second spans read "less than a second" (plainDurations too), the timeout detail no longer nests parentheses, and formatSpan now has one short/long form. I read only the changed lines. The card reads as plain words, and the new tests cover a pass, a timeout and a failure, and each fails without the change. Two things I would do next, both non-blocking: (1) Non-blocking: plainDurations only rewrites "after/in N ms|s", so a reason that carries other raw ms (for example "table sizes 5 s and 7 ms") still shows it on the card; widen the pattern or say it in the docs. (2) Non-blocking: the terminal and MCP only get the new Took wording through costLine; the failure sentence there is still the old one, so a follow-up could route it through drill_card_words.ts so both doors say the same thing.
The restore drill card on
/settings/backupsnow says what happened in plain words instead of raw milliseconds (#15066).plainDurations.The wording lives in a new pure module,
src/snapshot/drill_card_words.ts.src/web/pages/backups.tsnow uses it and its owndrillTimingis gone. The drill itself, the reason it stores, and the board, MCP and terminal sentences are unchanged.test/backups-drill-words.test.tssigns in, records a pass, a timeout and a failure, and checks the card's text for each. Each case also checks that no number is followed by "ms". The old card printed${d.ms} ms, so these tests fail without the change. A test namedtest/drill-card-words.test.tsalready existed for the verdict sentence; it is untouched and still passes.What I left out:
formatSpan. That already reads "1 min 2 s", but it would say "ms" for a drill under a second, which a real drill never is.Checks run: the new test plus
drill-card-words,backups-parts,drill-hosted-cardandbackups-drill-costall pass.bun scripts/gate.ts --fix,bun x tsc --noEmitandbun scripts/design-lint.tsare clean.🤖 Generated with Claude Code
Closes #15066