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

Row 75 (#1569): Console as a user service, candidate packet, round 1

Author: Rocko. Reviewer: Filbert. Brief: docs/plans/2026-10-11_dogfood-cutover.md, section "Console as a user service" (blob 1b124173 at 57f36a96; the rev 501 re-pin to blob f5d56554 changes only row 76's section). Lead decisions 94 and 95. Base: 43d2328f (base.txt). At 2026-10-11T22:32Z the checkout HEAD 2d04426c has no change to any candidate path since the base, and build.patch applies to it cleanly. The packet is uncommitted. I made no commits, pushes or Gitea calls, read no token or private binding, and started no unit.

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

File	What
scripts/webui-service.sh (new, 0755)	render, install [--dir DIR] [--no-reload], uninstall [--dir DIR] [--no-reload], status [--dir DIR] on the bus-service.sh pattern; exit 0 ok, 1 failed, 4 usage
packages/webui/systemd/mosaic-webui.service.in (new)	the unit template
packages/webui/tests/service.test.mjs (new)	10 tests
docs/TOOLS.md	one new section, "Console service (scripts/webui-service.sh)", before the Discord connector section; nothing else touched

No src/ file and no README. Row 74 owns those.

What it does

• The serve flags are --port N (default 7332, 1..65535), --business ID, --board URL and the preview set --public-host NAME --auth-header HEADER --allow-user ID, all three or none.
• Each value has its own plain character set:
  • business: serve's ID pattern, [a-z0-9][a-z0-9._-]{0,63}.
  • board: http:// followed by [A-Za-z0-9.:/_-]. Serve checks the rest itself: a loopback origin with no path.
  • public host: [A-Za-z0-9.-] with a leading alphanumeric, so no port and no scheme.
  • header: [A-Za-z0-9-].
  • user: [A-Za-z0-9._@+-].
• None of the sets allows a space, newline, %, $, quote, backslash, & or |. That means neither systemd nor the sed render can read a value as anything other than the value.
• Every refusal exits 1 and writes nothing. A refused install doesn't create the unit directory.
• ExecStart=@NODE@ @REPO@/packages/webui/src/cli.mjs serve @FLAGS@. NODE is command -v node at render time, kept as given (here /usr/bin/node). systemd doesn't look up an ExecStart command in Environment=PATH, so a bare node would not be found the way the brief's wording suggests. The REPO and node paths are held to [A-Za-z0-9/._+-].
• WorkingDirectory and PATH are filled in as the bus unit fills them: /usr/local/bin:/usr/bin:/bin, with node's directory prepended if it isn't already there. The other settings are Restart=on-failure, RestartPreventExitStatus=2, KillSignal=SIGTERM, TimeoutStopSec=30, NoNewPrivileges=yes and WantedBy=default.target. There is no other Environment= line and no MOSAIC_*, CLAUDE*, CODEX* or PI_* variable.
• install prints the systemctl --user enable --now mosaic-webui line for the human to run. The script has no start, stop, enable or restart verb; the header and TOOLS.md say why (lead decisions 62 and 94).
• uninstall refuses while list-units shows the unit active, activating or deactivating, unless --no-reload is given, as in bus-service.
• status prints is-enabled, is-active and show, then reads --port from the installed unit's ExecStart and prints GET http://127.0.0.1:<port>/healthz: the status code and body, or unreachable (<code>). It exits 0 either way, as bus-service status does.

Points for the reviewer

1. Exit 2 isn't retried. serve exits 2 for usage, config and listen errors, EADDRINUSE included (serve.mjs lines 149–150 reject, cli.mjs sets exitCode 2). With RestartPreventExitStatus=2, a port conflict stops the unit rather than looping. I chose that on purpose, and the template comment says so. Serve has no separate config exit code: a missing system config still serves, and the bus routes answer not-configured.
2. The preview flags need row 74. Until row 74 lands, a unit rendered with the preview set makes serve refuse with exit 2 (unknown option) and not restart. Rendering and installing are unaffected.
3. Serve runs under systemd. It runs as written. The user manager's environment (systemctl --user show-environment) carries none of the human.mjs markers, and the ancestry walk accepts at ppid 1. That is the gap lead decisions 62 and 94 name, and it's why only Jason starts the unit. I did not start it to prove this; systemd-analyze --user verify on the rendered unit exits 0.
4. An empty value counts as unset. --board "" and --business "" are treated as unset, the way bus-service treats an empty value. An empty member of the preview set counts as missing, so a set with one empty member is refused as partial.

Tests (packages/webui/tests/service.test.mjs)

The brief asks for six things:

• render with and without the preview flags;
• a partial set refused, in all three two-of-three shapes;
• space, %, newline, $, quote, backslash, | and & refused for each value flag, plus bad ports, business ids, boards, hosts and headers;
• the rendered unit names none of the MARKERS that the test parses from packages/bus/src/human.mjs, and its only Environment key is PATH;
• install into --dir with --no-reload writes the file whole and identical to render, at mode 0644, with no temp file left and no systemctl call; a second install reports unchanged; a refused install leaves the installed unit alone;
• uninstall refuses for active, activating and deactivating through a stand-in systemctl on PATH, then removes the unit once it is inactive.

I added three tests beyond the brief:

• install without --no-reload calls only daemon-reload;
• status against an in-process /healthz server on port 0, then with the server down, then with no unit installed;
• usage exits 4, including the start, stop, enable and restart verbs.

No test reaches the real systemd or spawns human-cli.mjs. XDG_CONFIG_HOME and HOME point into a temp directory.

Gate (out/gate/, sequential, scratch worktree at 43d2328f with the patch, node_modules linked)

Suite	Result
webui node --test 'packages/webui/tests/*.test.mjs'	50/50 (service: 10/10)
test-auth	15 passed, 0 failed
test-conductor	17 passed, 0 failed
test-config	24 passed, 0 failed
test-discord	66 passed, 0 failed (node 178 pass)
test-extension-package	18 passed, 0 failed
test-foundation	44 passed, 0 failed
test-queue	27 passed, 0 failed
test-release	14 passed, 0 failed
test-task	98 passed, 0 failed (Docker)

After the gate I removed the rocko-r75_default Docker network. out/gate/start.txt and out/gate/end.txt hold the times. shellcheck isn't installed on dragon-lin; bash -n passes.