docs: run-sheet doc row brief, five operator gaps (mos-1566, ops-0282, ops-0291, ops-0292)

This commit is contained in:
jason.woltje committed 2026-10-23 22:47:34 -05:00
1 parent 3d2569ce25
commit 4ec279dc43
1 file changed
+78
@@ -0,0 +1,78 @@
# Host run sheet: five operator gaps from the .53 and Run B installs (#414 stage 2)
Written 2026-10-24 by Sage for Mos's mos-1566 item 1, from ops-0282, ops-0288, ops-0291, ops-0292,
Duckworth's 323 N2 and Mos's rulings mos-1563 and mos-1565.
## Brief: five run-sheet gaps
**Why.** Five things stopped or slowed operators on the .53 stage 2 install and 433 Run B. Each is a gap
in `docs/guides/host-run-sheet.md` (checked at 3d2569ce2), not a product bug. The code they describe has
landed. This row writes them down.
**What to write.** Edit only `docs/guides/host-run-sheet.md`. Source every command, path and message from
the code or the receipts named here, and cite the line you read, the way the sheet already does
(`scripts/stack-release.sh:14`). Don't invent a flag, path or exit code.
1. **B2-2, the Console proof file format** (DEFERRED.md "ops-0282 B2-2", ops-0282). In section 9's .54
library table (:321), the proof file row's File cell gives mode and owner but no format. Add it: one
base64url line of at least 32 characters, `[A-Za-z0-9_-]` only (packages/webui/src/serve.mjs:264). The
Console exits 2 at start otherwise (:267). `case2-unit.sh` doesn't open the file, so a bad proof fails
only at Console start. Read serve.mjs:255-270 yourself and match what it checks, including whether a
trailing newline is accepted.
2. **N2, a missing project file only warns** (Duckworth 323 round 1 N2, ROUND1-6a0f0f4f8.md). When the
project root a business file names has no `.mosaic/project.json`, `mosaic business validate` passes
with the warning "no project file at ... it has no project variables" (packages/business/src/cli.mjs:74-78).
An install on such a host passes step 7 with the project's variables missing. Say so where the sheet
describes `case2-install.sh` (near :278), and tell the operator to treat that warning as a stop.
3. **The pre-install validate step** (mos-1563, ops-0288). Before `case2-install.sh`, check by hand that
each `projects` key in the business file equals the `id` in `<that project's root>/.mosaic/project.json`
in the stack's user's clone, and that the file exists. The loader refuses a mismatch
(packages/business/src/cli.mjs:80) at step 7, after the copy is made. The check must use only what the
host has at that point: coreutils, grep, or the pinned node under `/opt/mosaic-stack/node-<v>/bin`
(section 2), run as the stack's user. Give the expected output for a match and say a mismatch is a
stop: fix the business file, not the project id (mos-1563).
4. **The retry path after a failed first install** (mos-1565, ops-0291). Section 6 has no retry form.
What happened on .53: a refused `case2-install.sh` left `<home>/.config/mosaic-dev/config.json` behind
(bootstrap ran at step 1), and the first refusal also left an empty `businesses/` dir in that config
dir. The operator then used the upgrade form's fetch, which writes the bundle to
`refs/remotes/origin/refactor` and doesn't move `refs/heads/refactor`, so `stack-copy.sh copy` refused
with "not reachable from refs/heads/refactor". Mos's ruling: move the clones aside and rerun section
6's first-install form. Write that as a short "If the first install refuses" block in section 6:
- which paths move aside: root's checkout `/root/mosaic-stack`, the stack's user's clone
`/srv/mosaic/src/mosaic-stack`, and the stack's user's config dir. Read `scripts/case2-install.sh`
(bootstrap at step 1, :172, :200, :210-211) and `scripts/bootstrap.sh` to list what an install
writes before it can refuse, and name only those paths;
- move, never delete: `mv` to a name with a UTC timestamp suffix, as root, keeping owner and mode;
- what the operator must re-place afterwards if a credential slot under that config dir was already
filled (section 9). If nothing in section 9 can be filled before the first install, say that;
- then rerun the first-install block from its first line. Never use the upgrade form's fetch on a
clone that a first install hasn't finished with.
5. **Checking a backup's SHA256SUMS by hand** (ops-0292). The sheet has no backup check today. A backup set
under `<dataRoot>/backups/stack/<activation>/` holds `SHA256SUMS` with paths relative to `bus/`
(scripts/stack-release.sh:482 writes `(cd "$o/bus" && sha256sum bus.sqlite) > "$o/SHA256SUMS"`), and
the tool checks it with `(cd "$o/bus" && sha256sum -c --quiet ../SHA256SUMS)` (:502, :2244). Running
`sha256sum -c SHA256SUMS` from the backup dir itself fails (rc 1, "FAILED"), because `bus.sqlite` is
in `bus/`. Add a short paragraph after the upgrade exits in section 6 that gives the `bus/` form for an
operator who wants to check a backup before a rollback or restore. Read :475-510 to confirm the
layout first.
Keep the sheet's voice: short sentences, the path and line for each claim, no em dashes. Don't renumber
sections. Don't touch any other file except your BUILD.md.
**Test.** None ships. Before the review request, show that no test or script reads the sheet:
`git grep -n host-run-sheet -- 'packages/*/tests/*' 'scripts/*'` prints nothing, with a positive control
that the same command form finds a path you know a test reads. Also grep the tests for a 64-hex pin next
to the sheet's name. If any test reads the sheet, stop and tell Sage.
**Gate.** Doc only (decision 137). No suite run is needed from you, and no CLEAR. Sage's landing gate
runs every suite (mos-1455). The reviewer checks every new claim against the cited line.
**Boundaries.** No host action, no .53, .54 or 1013 contact, no credential reads, no push to refactor.
Claimant queue moves are yours (start, in-review). Work in a new worktree off refactor at 3d2569ce2 or
later, on branch `goldie/row-run-sheet`. Push the branch and report the tip, base and manifest to Sage
and to the reviewer. Record choices in `agents/goldie/work/queue-<row>/BUILD.md`.
**Acceptance.** An operator following the sheet can see the proof file format, treats the missing
project file warning as a stop, checks the project key before install, has a written retry path after a
refused first install, and can check a backup by hand with the form that works. Every new claim cites a
line that says it.