stack/agents/rocko/work/queue-77/BUILD.md

# Row 77 (#1571): Console pinned copy, update step and service hardening, candidate packet, round 1

Author: Rocko. Reviewers: Darkwing and Filbert. Gate: Sage. Brief:
`docs/plans/2026-10-12_console-pinned-copy.md`, section "Console pinned
copy, update step and service hardening" (lead decision 112). Base:
`27a1a2bb` (`base.txt`); `refactor` has not touched any of the files below
since (`git log 27a1a2bb..1d4ba6bb` on them is empty). The packet is
uncommitted. I made no commits, pushes or Gitea calls, read no token or
private binding, and never started, stopped, restarted or installed the
live unit. Every test run uses `--dir`, a stand-in `systemctl` and
fixture copies.

## Files (`files.txt`, `candidate-manifest.sha256`)

| File | Change |
|---|---|
| `scripts/webui-service.sh` | `copy` verb; `install`/`render --copy ID [--copies DIR]`; `--allow-worktree`; N1 to N5; the uid rule; `status` copy and drift lines |
| `packages/webui/systemd/mosaic-webui.service.in` | header comment only: `@REPO@` is the copy, `--checkout`, and decision 102's wording (Jason or Mos) in lines 6-9 |
| `packages/webui/src/cli.mjs` | `serve --checkout PATH` (absolute directory, else exit 2), passed to `consoleReads` as `queueRoot`; a `Queue:` start line |
| `packages/webui/src/reads.mjs` | `consoleReads({ root, queueRoot = root })`; the queue reader takes `queueRoot`, nothing else changes |
| `packages/webui/tests/service.test.mjs` | existing tests moved to `--copy`, the uid and the state read; +7 tests |
| `packages/webui/tests/pinned-copy.test.mjs` | new, 6 tests |
| `packages/webui/README.md` | one paragraph at the end of the service section |
| `docs/TOOLS.md` | the "Console service" entry only |
| `agents/rocko/work/queue-77/mutants.py` | the mutant rerun: `python3 mutants.py <tree>` |
| `agents/rocko/work/queue-77/byte-check.sh` | render without `--copy`, base script against candidate: `byte-check.sh <tree> <base> <out>` |

## The copy

`copy COMMIT [--copies DIR]`:

- Refuses outside the canonical checkout (`$REPO/.git` must be a
  directory) unless `--allow-worktree` (tests only; the help text says so).
- COMMIT must start with a letter or digit and use only `A-Za-z0-9._/-`;
  it resolves with `rev-parse --verify "$commit^{commit}"` to the full id,
  and `merge-base --is-ancestor` against `refs/heads/refactor` refuses
  anything off the branch. `--copies` must be absolute, in the unit's
  character set.
- An existing `DIR/<id>` prints `exists:` and exits 0, untouched.
- Otherwise `git archive <id> -- COPY_PATHS | tar -x` into
  `mktemp -d DIR/.<id>.XXXXXX` (removed by a trap on any failure),
  `chmod a-w` on every file, `chmod 0755` on the temp directory, then
  `mv -T` to `DIR/<id>`. A rename that loses a race to another `copy`
  prints `exists:`.

Two choices against the brief's wording, both stricter:

- **chmod before the rename.** The brief says rename, then remove write
  permission. I do it the other way round, so the final path is never
  seen whole-but-writable, and a crash between the steps leaves only a
  temp directory, not a writable copy at the id.
- **Files read-only, directories not.** Directories keep their write bit,
  so the copy can still be removed with plain `rm -rf` ("copies are kept
  until someone removes them"). A file can't be edited in place; a new
  file could be added to a directory. Making directories read-only too is
  a one-line change if the reviewers want it.

`COPY_PATHS` (in the script, with a comment): the `src` of bus, business,
cli, conversation, discord, harness, seat and webui, `packages/webui/README.md`,
`scripts/mosaic-config.mjs`, `roles` and `RELEASE`. `packages/queue` is
deliberately left out: the queue read runs in the checkout.

## The unit

- `install` and `render` take `--copy ID` (40 lower-case hex) and
  `--copies DIR`. The copy must hold `packages/webui/src/cli.mjs`, else
  "no copy ... make it with: scripts/webui-service.sh copy ID". `@REPO@`
  becomes the copy path, and the flags get `--checkout <REPO>` in front.
- `install` refuses without `--copy`. `render` without `--copy` is the
  base unit byte for byte (byte check below), and `render` takes no
  `--allow-worktree` (it only prints).
- `status` reads `WorkingDirectory`. If its last part is 40 hex it prints
  `copy: <id>` and one of `refactor: <sha>, the copy's commit`,
  `refactor: <sha>, another commit; the copy is <id>`, or
  `refactor: unknown; ...`. Otherwise `copy: none; the unit runs from <wd>`.

## N1 to N5 and the uid rule

- **N1, broader than the brief.** `running()` reads
  `systemctl --user list-units --no-legend --plain mosaic-webui.service`
  and treats any ACTIVE state but `inactive` or `failed` as running, so
  `reloading` (and any state systemd adds) refuses too, not only the
  brief's three. `install` refuses with "refusing: mosaic-webui.service is
  running (STATE); Jason or Mos stops it first (systemctl --user stop
  mosaic-webui), then install, then start it", and nothing is written.
- **N2.** `copy` and `install` call `canonical()`.
- **N3, I chose "always checks".** `uninstall` reads the state with or
  without `--no-reload`; `--no-reload` skips only `daemon-reload`.
  `install` does the same. The docs say so.
- **N4.** A failed state read dies with one line: "refusing: systemctl
  --user list-units --no-legend --plain mosaic-webui.service failed, so
  the unit's state is unknown; nothing was changed". systemctl's own
  stderr is dropped so the line stays one line.
- **N5.** `--public-host` and `--auth-header` already had leading-character
  checks that no test covered; `--allow-user` gains one ("allowed user must
  start with a letter or digit"). Tests cover `-` and `.` on all three.
  This also retires the case row 83 documented, `--allow-user --send`
  without sending: it is now refused, and the old test that installed it
  now asserts the refusal.
- **uid rule.** With `--auth-header` equal to `x-authentik-uid` in any
  case (`${AUTH_HEADER,,}`), `--allow-user` must match `^[0-9a-f]{64}$`,
  or render and install refuse naming the rule and decision 101.

Order in `install`: flags, canonical, `--copy` present, render (all value
checks), then the state read, then the write. A refused value never
reaches systemctl.

## Tests

`node --test tests/service.test.mjs tests/pinned-copy.test.mjs`: 28 pass.

service.test.mjs: every run now gets a stand-in `systemctl` (a quiet one
that lists nothing by default), since `install` reads the unit's state; no
run can reach the real systemd. New tests: install refuses in four
running states with and without `--no-reload` and goes ahead for
inactive, failed, another unit and nothing; a failed state read refuses
install and uninstall with one exact line; `--copy` refusals, `--copies`,
and the worktree refusal (the suite runs in a worktree, so it asserts the
refusal when `.git` is a file); `render --copy` byte for byte; the uid
rule in four header spellings, six bad values, render and install, and
the username header still taking a username; leading `-` and `.`; status
copy, drift and `copy: none`.

pinned-copy.test.mjs builds a fixture canonical repository on `refactor`
from this tree's packages, scripts and roles, with its own RELEASE. It
copies by short id, checks the top level, that every file is read-only,
`exists:` on repeats, the default XDG directory, and that the checkout is
untouched; refuses off-branch commits, bad names, bad copies directories
and a linked worktree, and accepts the worktree with `--allow-worktree`;
leaves the copies directory empty when `git archive` fails; serves from
the copy; refuses a bad `--checkout`; and checks `consoleReads` uses each
root.

The serve test against the brief: it starts `cli.mjs serve` from the copy
and gets `/healthz` 200, `Bus: acme` (the config check, from the copy),
RELEASE `0.0.0-fixture` and the business read through the copy's roles,
and the queue read in the `--checkout` directory with its cwd there.
Without `--checkout` the copy's own queue read fails closed (503), since
the copy has no `packages/queue`. Two departures, stated plainly: there
is no literal stand-in socket, because `/healthz` and the reads above make
no bus call (serve only builds the caller at start); and the bus child,
`packages/bus/src/human-cli.mjs`, spawned per bus call from the copy's
`packages/cli/src/transport.mjs`, is not exercised, because tests never
spawn the real human-cli. Both files are inside `COPY_PATHS`
(`packages/bus/src`, `packages/cli/src`), and serve imports from both at
start, so a missing one fails the serve test. The `seat` mutant below
shows the test catches a package missing from the list.

## Mutants (`mutants.py`, `out/mutants.txt`)

18 mutants, each applied alone to the candidate tree, all killed:
failed counted as running; reloading not running; a failed state read
ignored; install skipping the state read; uninstall skipping it under
`--no-reload`; the uid header case-sensitive; upper-case hex accepted;
allowed user free to start with `-`; no `--checkout` in the unit;
`canonical()` always passing; install without `--copy`; a missing copy
accepted; status drift always "the copy's commit"; `packages/seat/src`
dropped from the list; files left writable; off-branch commits accepted;
the queue reader on `root`; a relative `--checkout` accepted.

The last one first survived: the test's relative path didn't exist, so
`stat` refused it either way. The test now uses an existing relative
directory under the child's cwd, with a 10 s spawn timeout so a mutant
that really serves fails instead of hanging the suite (it hung once; I
killed my own fixture serve on port 0).

## Byte check (`byte-check.sh`, `out/byte-check.txt`, `out/byte-check/`)

The base script, placed beside the candidate for the run and removed
afterwards, and the candidate render eight flag sets without `--copy`,
including both preview headers, `--send`, a refused `--port 0` and a
dotted business id. With comment lines dropped (the template's header
changed by design), all 8 match, exit codes too, and the template's
non-comment body is identical.

## Gate (`out/gate/`, `out/gate.sh`)

Sequential, in the scratch worktree at `27a1a2bb` with the candidate and
`node_modules` linked, full output kept per suite, load average 20-33:

| Suite | Result |
|---|---|
| webui node (`packages/webui/tests/*.test.mjs`) | 94 pass, 0 fail |
| test-auth | 15 passed, 0 failed |
| test-conductor | 17 passed, 0 failed |
| test-config | 24 passed, 0 failed |
| test-discord | 66 passed, 0 failed |
| test-extension-package | 18 passed, 0 failed |
| test-foundation | 44 passed, 0 failed |
| test-queue | 27 passed, 0 failed (the canonical-root checks skip in a worktree, as always) |
| test-release | 14 passed, 0 failed |
| test-task | 98 passed, 0 failed |

No `✖` or `not ok` in any output file. `rocko-r77_default` was removed
after the Docker suites.

## For the reviewers

- The stale comment in `status` about `--allow-user --send` is updated:
  the allowed user can no longer be `--send`.
- The live unit is untouched. Mos's reinstall after the landing is
  `copy` at the landed commit, stop, `install --copy ID` with the uid,
  start (brief, "Gate").