stack/agents/dewey/work/queue-83/build.md

# Row 83 (#1576): Console service, the unit script takes --send, round 1

Owner: Dewey. Reviewers: Darkwing and Filbert, then Sage's gate. Brief:
`docs/plans/2026-10-12_console-service-send.md` § "The unit script takes
--send", blob `f8d14d70` (re-pinned at rev 630 for lead decision 102; first
pinned as `739bea66` at rev 627, briefed at rev 628). Lead decision 101
gives the reason. Base `d13b9300`. None of the candidate's paths, nor the
template, changed between `d13b9300` and `refactor` HEAD (`a1c5c8fc`) when
the packet was built.

`build.patch` is `git diff --cached --binary d13b9300 --` the four paths
below. Apply it with `git apply --index` to a detached worktree of the base;
`candidate-manifest.sha256` then checks 4/4 OK (checked on a fresh
worktree).

## What ships

- `render` and `install` take `--send`, a flag with no value. It is
  accepted only with all three preview flags. Otherwise `serve_flags`
  refuses before anything is written: exit 1, empty stdout, and on stderr
  `webui-service: --send needs the preview mode (--public-host,
  --auth-header and --allow-user)`, serve's own wording (cli.mjs:37).
  `install` renders before `mkdir`, so a refusal creates no directory and
  leaves an installed unit alone (tested).
- With `--send`, ExecStart ends `... --allow-user ID --send`. Nothing else
  in the unit changes (tested line by line against the same render without
  `--send`).
- Without `--send`, every render is the template with its four
  placeholders filled, byte for byte (new test), and the base and
  candidate scripts give the same stdout, stderr, status and installed
  files on every argument list the base tests use (`identity.txt`).
- `uninstall` and `status` take no `--send`: it sets SERVE_SET like the
  other serve flags, so both exit 4 (tested with a stand-in systemctl).
- `status` prints one new line when a unit is installed: `send: on
  (--send; human messages to roles)` or `send: off (read-only)`. The brief
  allowed this "if small"; it is five lines plus a comment. With no unit
  installed there is no send line.
- `USAGE` and the header comment name `[--send]` inside the preview set.
  README's service paragraph and TOOLS.md's "Console service" section say
  the script takes `--send` only with the preview set (exit 1, nothing
  written), that ExecStart then ends with `--send`, and that the Console
  needs the system config at start (`--send needs the bus configured`,
  exit 2, which the unit doesn't restart: `RestartPreventExitStatus=2` in
  the template). README's "Message a role" `--send` paragraph gets one
  sentence pointing at `scripts/webui-service.sh install` with `--send`.
- The start wording (lead decision 102). The script's header comment, its
  install message, TOOLS.md's "Console service" and README's service
  paragraph now say Jason starts and restarts the Console, and so may Mos
  under decision 102, which accepts that sends from a Console Mos started
  enter the trail as Jason (`human-cli`). Any other agent starting it,
  even through systemd, still works around the human proof (decisions 62
  and 94). The script still has no start, stop or restart verb. A test
  checks the install message's wording.

The template (`packages/webui/systemd/mosaic-webui.service.in`) is
unchanged. `install` prints no new line; its `serve:` line already shows
the ExecStart, `--send` included. The install message's opening sentence
changed wording only (decision 102).

## Decisions and tradeoffs

- **Refusal order.** The `--send` check runs before the all-three check.
  `--send` with one or two preview flags therefore gets the `--send`
  message, not "all three or none". The brief asks for a message naming
  the preview flags the way serve refuses, and serve checks the preview
  set first. Both messages name the three flags. A partial preview set
  without `--send` still gets "all three or none" (base test unchanged).
- **Status detection is anchored on the allowed user.** My first version
  matched `^ExecStart=.* --send$`. The mutant `status-send-anywhere`
  survived it, and that showed a real gap: `--allow-user` accepts the value
  `--send` (its character set allows `-`, and serve's `USER` pattern
  accepts it), so a read-only unit's ExecStart can end
  `--allow-user --send`. The check is now
  `^ExecStart=.* --allow-user [^ ][^ ]* --send$`. render always puts
  `--send` right after the allowed user, so a sending unit ends with both
  the allowed user and `--send`. A test installs both cases, read-only
  `--allow-user --send` and sending `--allow-user --send --send`, and
  checks status for each.
- **No config or bus check in the script** (out of scope per the brief).
  A unit installed with `--send` on a host without the system config
  installs fine and exits 2 at start; the docs say so.

## Files

- `scripts/webui-service.sh`: `SEND=0`, the `--send` case, the refusal
  and the append in `serve_flags`, the status line, USAGE and header.
- `packages/webui/tests/service.test.mjs`: 5 new tests, 2 widened.
- `packages/webui/README.md`: the service paragraph, one sentence in
  "Message a role".
- `docs/TOOLS.md`: the "Console service" FLAGS comment and prose.

## Tests

`packages/webui/tests/service.test.mjs`, 15 tests (10 base, 5 new). The
helper `filled(flags)` is the template with `@REPO@`, `@PATH@`, `@NODE@`
and `@FLAGS@` replaced, computed in the test the way the base script does
it.

- *without --send, render is the template with its placeholders filled,
  byte for byte*: five flag combinations, from none to every flag.
- *render --send with the preview set ends ExecStart with --send and
  changes nothing else*: four argument orders (`--send` first, last, in the
  middle of the preview set, with `--port` and `--business`). Each equals
  `filled(flags + ' --send')`, and against the same render without
  `--send` exactly one line differs, the ExecStart, by ` --send`.
- *--send without the whole preview set is refused and writes nothing*:
  `--send` alone, with `--port`, with `--business`, with each one of the
  three preview flags, and with each two of the three. Each `render` gives
  exit 1, empty stdout and serve's message. Each `install` into a fresh
  `--dir` gives the same, and the directory is never created. An install
  of `--send` with two preview flags over an installed unit leaves it byte
  for byte, with no temp file and no systemctl call.
- *install --send into --dir with --no-reload writes the sending unit, and
  status says whether it sends*: `written:`, the `serve:` line ending
  `--send`, the file equal to `filled(...)`, mode 0644, no temp file;
  status `send: on`; reinstall `unchanged:`; install without `--send`
  writes the read-only unit and status says `send: off (read-only)`; the
  odd allowed user `--send` case above; no `send:` line without a unit.
  The only systemctl calls are status's reads. Status's `/healthz` goes to
  a loopback port that was just closed, so it reaches no real Console.
- *uninstall and status take no --send*: exit 4 for `uninstall --send`
  (with and without `--no-reload`) and `status --send`, against a stand-in
  systemctl that records no call; the unit stays installed.
- Widened: the agent-marker test also renders `[...PREVIEW, '--send']`;
  the usage test adds `render --send yes ...PREVIEW` (`--send` takes no
  value); the install test checks the decision 102 start wording in the
  install message.

Why the uninstall and status cases sit in their own test: in the usage
loop they run with the real `/usr/bin/systemctl` on PATH. A mutant where
`--send` doesn't set SERVE_SET would let `uninstall --send` reach a real
`systemctl --user daemon-reload`. With the stand-in, no mutant can.

## Byte identity (`identity.mjs`, `identity.txt`)

One scratch worktree of `d13b9300` holds the base script as
`scripts/webui-service-base.sh` and the candidate as
`scripts/webui-service.sh`, so REPO and the template are the same for
both. Each script runs the same 86 argument lists from a clean scratch:
every render the base tests make (the value and port refusals included),
the usage list, `--help`, and an install, reinstall, refused install,
install over, status, uninstall, uninstall and status sequence, all with
`--no-reload` and a stand-in systemctl.

Result: 69 identical, 17 expected differences, 0 unexpected. The 17 are
the usage text on 12 exit-4 cases plus `--help` (the FLAGS line names
`[--send]`), three installs whose message differs only in the decision 102
start wording (the base message's opening lines replaced by the
candidate's, then everything else identical, installed unit included),
and one status with a unit installed (the added `send: off (read-only)`
line, nothing else). A self-check: with the append made
unconditional, the same run reports 13 unexpected differences.

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

15 single-site mutants of `scripts/webui-service.sh`, each run against the
base tests (`d13b9300`'s `service.test.mjs`), the candidate tests and
`identity.mjs`. Baselines: all three pass on the unmutated candidate.
Rerun on the decision 102 candidate, 2026-10-12T03:53Z; same results as
the first run.

| mutant | base tests | candidate tests |
|---|---|---|
| send-no-preview-check | survived | killed |
| send-needs-any-preview | survived | killed |
| send-message-reworded | survived | killed |
| send-no-append | survived | killed |
| send-append-always | killed | killed |
| send-append-before-preview | survived | killed |
| send-default-on | killed | killed |
| send-no-serve-set | survived | killed |
| send-takes-value | survived | killed |
| send-flag-unknown | survived | killed |
| status-send-always-off | survived | killed |
| status-send-always-on | survived | killed |
| status-no-send-line | survived | killed |
| status-send-anywhere | survived | killed |
| status-send-suffix-only | survived | killed |

The candidate tests kill 15 of 15. The two the brief names,
`send-no-preview-check` and `send-no-append`, survive the base tests.
`send-append-always` and `send-default-on` are killed by the base tests
too, as a change to every render should be.

## Gate (my run on the candidate)

On the staged candidate in a worktree of `d13b9300`, run sequentially,
2026-10-12T03:54:20Z to 03:58:42Z (`gate-summary.txt`):

- `packages/webui`, `node --test 'tests/*.test.mjs'`: 81 tests, 81 pass,
  rc=0.
- `scripts/test-auth.sh`, `test-conductor.sh`, `test-config.sh`,
  `test-discord.sh`, `test-extension-package.sh`, `test-foundation.sh`,
  `test-queue.sh`, `test-release.sh`, `test-task.sh`: all rc=0.

## For reviewers

- **Allowed user starting with `-`.** The base script and serve both accept
  an allowed user like `--send` or `-x`. That isn't new here, and changing
  it would change no-`--send` renders, which the brief rules out. The only
  effect on this row was status detection, now anchored. If it should be
  refused, that's a follow-up for the script and serve together.
- **The template's comment still says Jason starts it.**
  `mosaic-webui.service.in` lines 6-9 say Jason starts it from a personal
  shell and that an agent starting it works around the human proof. The
  template isn't in this row's files and is rendered into every unit, so
  changing it would break the byte identity the brief asks for. Bringing
  it in line with decision 102 is a follow-up (a template change plus the
  render tests that pin it).
- Nothing here starts, enables or restarts a unit, and no test reaches the
  real systemd: every install and uninstall uses `--no-reload` or a
  stand-in systemctl.