row 198: inventory of control-board writer and port 7331 references (#1696)

2026-10-20 14:15:05 -05:00
1 parent a7661ada06
commit 004f133bd6
@@ -0,0 +1,125 @@
+# Row 198 inventory: control board writer and port 7331
+
+Gitea #1696. Brief: `docs/plans/2026-10-20_retire-control-board.md`. Owner Bushroot, reviewer Webby, gate owner Sage.
+Scope: tracked files at `bushroot/row198` (base `refactor`). Excludes `v1/` and other seats' `agents/*/work/` packets.
+Method: `git grep -I` for `control-board`, `control_board`, `controlboard` and `7331`, then a read of each code hit.
+
+## Classes
+
+- **starts**: runs `packages/control-board` `serve`, or a unit, script or default that does.
+- **imports**: loads code from `packages/control-board` at run time or test time.
+- **mentions**: text only (docs, comments, fixture strings, history).
+
+## Result
+
+**Live dependency found. Stop before any removal.** The Console (`packages/webui`) proxies its board reads and
+writes to the writer on 7331. The Console's board view, `/api/board`, `/api/seen`, `/api/reply` and the
+conversation routes all forward to `DEFAULT_BOARD = http://127.0.0.1:7331`. The Console has no board without
+a writer on that port. Mos decides before anything is removed.
+
+Nothing in the repository runs `control-board serve` from a unit. The only starter is the manual command in
+`packages/control-board/README.md` and `packages/webui/README.md`. `ss -ltnp` showed nothing on 7331 at
+2026-10-20T19:05:09Z (brief).
+
+## Hits
+
+### Starts the writer, or defaults to its port
+
+| File | Line | Class | What it does |
+|---|---|---|---|
+| `packages/control-board/src/cli.mjs` | 4, 14 | starts | `serve` subcommand; default `port: 7331` |
+| `packages/control-board/src/serve.mjs` | 312 | starts | `startServer` default `port = 7331` (the writer itself) |
+| `packages/control-board/README.md` | 107, 127 | starts | Tells people to run `serve` and open 7331; documents the default |
+| `packages/webui/README.md` | 10 | starts | Tells people to run `node packages/control-board/src/cli.mjs serve` |
+| `packages/webui/README.md` | 15, 881 | depends | Console reads the board at 7331; rollback uses "the unchanged board at 7331" |
+| `packages/webui/src/cli.mjs` | 14, 18 | depends | `--board` default is `DEFAULT_BOARD` (7331) |
+| `packages/webui/src/serve.mjs` | 12, 473, 561, 578, 610 | **depends (live)** | `DEFAULT_BOARD`; proxies `GET /api/board`, `GET /api/conversation(s)`, `POST /api/seen`, `POST /api/reply` upstream; returns 502 if the writer is absent |
+| `packages/webui/src/public/app.js` | 468, 365 | depends | Page reads `/api/config` board, then `/api/board` through the Console proxy |
+| `packages/webui/src/public/bus.js` | 1037, 1088, 1100 | depends | Routes `#/` to the board page; bus pages link to it |
+| `scripts/webui-service.sh` | 89-163 | depends | Renders the Console unit with `--board URL`; default comes from `serve` |
+| `packages/webui/systemd/mosaic-webui.service.in` | 29 | depends | Unit runs the Console (`webui/src/cli.mjs serve`), not the writer; flags carry `--board` |
+| `scripts/stack-copy.sh` | 88 | mentions | Checks the Console `ExecStart` string; no writer reference |
+| `scripts/stack-release.sh` | 1372 | mentions | Checks the Console command line; no writer reference |
+
+### Imports code from `packages/control-board`
+
+| File | Line | Class | What it imports |
+|---|---|---|---|
+| `packages/webui/tests/fixture.mjs` | 6 | imports | `startServer` from `control-board/src/serve.mjs` (test fixture for the Console) |
+| `packages/webui/tests/history-fixture.mjs` | 8 | imports | same |
+| `packages/webui/tests/discord.test.mjs` | 6 | imports | same |
+| `packages/webui/tests/relaunch.test.mjs` | 6 | imports | same |
+| `packages/webui/tests/return-flow.test.mjs` | 13 | imports | same |
+| `packages/conversation/tests/flows.test.mjs` | 15 | imports | `replyToRow` from `control-board/src/serve.mjs` |
+
+The webui tests run the writer's server in-process. They do not start the writer on 7331 (the tests bind
+their own port), but they need `serve.mjs`. Any removal or refusal in `serve.mjs` breaks these tests unless
+the writer's read-only code moves first.
+
+`packages/webui/src/` (non-test code) does not import `control-board`. Only the tests do.
+
+### Tests that name the writer or its files
+
+| File | Line | Class | Note |
+|---|---|---|---|
+| `packages/control-board/tests/serve.test.mjs` | 37, 744-767 | imports | Tests the writer: reply runner, `REPLY_TRAILER`, `-S <host>:control-board` |
+| `packages/control-board/tests/scan.test.mjs` | 47, 306, 353 | mentions | Tmp dir names and comments |
+| `packages/webui/tests/serve.test.mjs` | 18-19, 35 | mentions | `boardURL` checks on port 7331; reply trailer string |
+| `packages/webui/tests/reads.test.mjs` | 188 | mentions | Expected `board` setting value 7331 |
+| `packages/webui/tests/service.test.mjs` | 225-394 | mentions | Unit `ExecStart` text includes `--board http://127.0.0.1:7331` |
+| `packages/plugins/tests/harness.test.mjs` | 173 | mentions | Path string `packages/control-board/src/scan.mjs` |
+| `packages/ledger/tests/ledger.test.mjs` | 80, 233-327 | mentions | Sender name `control-board` as a test fixture |
+| `packages/queue/tests/fixtures/genesis-render.md` | 6-11 | mentions | Fixture text |
+| `packages/conversation/tests/reader.test.mjs` | 2 | mentions | Comment |
+| `packages/conversation/README.md` | 207 | mentions | Says the control-board suite serves the routes |
+
+### Code that reads the sender name, not the writer
+
+| File | Line | Class | Note |
+|---|---|---|---|
+| `packages/ledger/src/ledger.mjs` | 120 | mentions | Classifies `control-board` as sender kind `board`. No import. |
+
+### Package and script metadata
+
+| File | Line | Class | Note |
+|---|---|---|---|
+| `packages/control-board/package.json` | 2, 5, 9 | starts | Declares `bin: mosaic-board -> src/cli.mjs` (a `mosaic-board serve` entry point) |
+| `package.json` (root) | - | none | No script names the board or 7331 |
+| `scripts/mosaic` | 3 | mentions | Comment only |
+| `packages/seat/package.json` | 5 | mentions | Description: "the control board reads" registration |
+| `packages/seat/README.md` | 139 | mentions | Says the board reads `registration.json` |
+| `packages/plugins/README.md` | 181 | mentions | Names `scan.mjs` in an exception note |
+
+### Docs (mention only)
+
+- `AGENTS.md` lines 144-150: reply convention for control-board attention. Names the package README. Does
+  not tell anyone to start 7331. The brief says to change it only if it does.
+- `docs/SESSIONS.md` (32), `BUILD-LOG.md` (76), `docs/plans/CURRENT.md` (8), `docs/plans/QUEUE.md` (12),
+  `docs/plans/queue.json` (45), `docs/plans/2026-09-12_control-board-mvp.md` (21),
+  `docs/plans/2026-10-*` and other plan pages, `docs/plans/reviews/*`, `docs/design/*`.
+  - `docs/plans/CURRENT.md:171` says "Start it with `node packages/control-board/src/cli.mjs serve`". That is
+    an instruction to start the writer. Update it when the writer is retired.
+  - `docs/plans/2026-10-18_containerized-install-design.md:927` and `-rows.md:213` cite `serve.mjs` line numbers.
+  - `docs/plans/2026-10-19_seen-click-intent.md:29` cites `serve.mjs:257` (`/api/seen`).
+  - `BUILD-LOG.md` is append-only. Leave it alone.
+- `agents/bushroot/README.md`, `agents/README.md`, `docs/design/README.md`, `docs/design/IMPLEMENTING.md`:
+  mention only.
+- `packages/webui/third_party/editor/PROVENANCE.json`: mention only (the vendored editor's clipboard, not the board).
+- `packages/webui/src/public/*` clipboard, board-view and CSS names: unrelated to the writer.
+
+### Excluded
+
+- `v1/*`: archived.
+- `agents/*/work/*`: other seats' packets (darkwing, filbert, rocko and others). Not read for this inventory.
+
+## Open items for Mos
+
+1. The Console's board view and proxy routes need a writer on 7331 or an equivalent read path. Retiring the
+   writer means choosing a replacement first, or accepting that the board view goes dark.
+2. Four plan pages and `CURRENT.md:171` still tell people to start the writer.
+3. The webui tests and `conversation/tests/flows.test.mjs` import `serve.mjs`. Any change to it needs those
+   tests moved first.
+
+## Sha256
+
+Recorded in the send message after commit. This file is the inventory; the commit carries it.