stack/agents/darkwing/work/queue-165/BUILD.md

Row 165 (#1662): the human adds and changes role instances

Owner Darkwing. Reviewers Dewey (security) and Filbert. Gate owner Sage. Brief docs/plans/2026-10-18_role-instance-verb.md, first at blob 0aeb5f5adb, corrected in b8036b608 to blob b3cf580a (rev 1873, mos-0823). Built on b8036b608, rebased onto 70c9131f0 before the slot run (sage-0939, sage-0941). Claimed 2026-10-18T21:25Z (rev 1871).

Rebase onto 70c9131f0 (sage-0939)

Row 154 landed as 9353675d1 and moved origin/refactor to 70c9131f0. Four of my manifest paths changed in b8036b608..70c9131f0: docs/TOOLS.md, packages/webui/README.md, packages/webui/src/public/bus.js and packages/webui/src/serve.mjs. I took the whole diff against b8036b608 and applied it with git apply --3way in a fresh worktree at 70c9131f0. All 16 changed files applied cleanly, and I copied the 7 new files over unchanged.

The public/ diff against the new base is public-70c9131f0.diff. Its +/- lines, hunk headers and context match public.diff. Only the index line differs (40c6b6758..b2bb52d0a, where it was 1e0be849d..67abd41f6). Sage ruled (sage-0941) that mos-0826 covers the +/- lines, so no new delta goes to Mos. To make the match checkable, each digest below is grep '^[+-]' FILE | grep -vE '^(\+\+\+|---) ' | sha256sum:

Diff	Whole-file sha256	+/- lines	+/- digest
public.diff (on b8036b608)	e5e3435b542fbbe2f69c64ac05ea200c02adc606a1c41020341620ddc19d13e0	55	04856a57c70cd6d96d33fd43aa285a17c0bb52a596c643145a52bf52c93db4e4
public-70c9131f0.diff (on 70c9131f0)	ee57b150ca92664bb6a62bc9874d26340710a6ac2e5fc703eceba84505f48f96	55	04856a57c70cd6d96d33fd43aa285a17c0bb52a596c643145a52bf52c93db4e4

On 70c9131f0, human.mjs, human-cli.mjs, cli/src/transport.mjs, harness/src/tools.mjs, stack-release.sh and stack-copy.sh are byte-equal to b8036b608 and to the candidate. The channel-proof pin dfbc2289...9a4c matches the rebased webui/src/bus.mjs. The 64-hex grep also hit webui/tests/service.test.mjs and bus/tests/thread-migration.test.mjs, but those strings are a fixture UID and a DDL hash, not pins on manifest files. Both tests run in singles. The 28-mutant dry run anchors on the new base.

Stack scripts: this row doesn't touch scripts/stack-release.sh, scripts/stack-copy.sh or the 8e7ea89a1 re-pin target. If that changes, Sage hears before the review request (sage-0918).

Paths beyond the brief's list (sage-0918)

Sage approved the expansion at 21:30:34Z. The brief lists the writer, its test, the CLI command and the Console section. Everything below is beyond that list:

• packages/bus/src/broker.mjs: the instances and instances.set verbs, human-only, with INSTANCE_KEYS. Neither is in ORGANIZATION_KEYS;
• packages/bus/src/runtime.mjs: routes the two verbs to instanceSettings;
• packages/bus/tests/instances-verb.test.mjs (new);
• packages/bus/tests/channel-proof.test.mjs: the webui/src/bus.mjs pin, below;
• packages/harness/tests/tools.test.mjs: proves no tool reaches the two verbs;
• packages/cli/src/cli.mjs: routes business instances and business instance to the new packages/cli/src/instances.mjs;
• packages/webui/src/cli.mjs: the wiring, under --send only;
• packages/webui/src/bus.mjs: seven STATUS codes, below;
• packages/webui/src/serve.mjs: GET /api/bus/instances and POST /api/instances;
• packages/webui/src/public/bus.js: the Settings section (decision 123, below);
• packages/webui/tests/instances.test.mjs and instances-browser.test.mjs (new);
• packages/webui/tests/shell.test.mjs: its pinned list of bus.js POST fetches gets the /api/instances write, and the method: count goes to 6. I missed it in the reader grep. It reads bus.js's text, not a 64-hex pin. Slot run 1 caught it (see below);
• scripts/mosaic: sends business instances and business instance to packages/cli;
• packages/bus/README.md, packages/business/README.md, packages/cli/README.md, packages/webui/README.md;
• docs/TOOLS.md and docs/acceptance/314.md, which the brief assigns.

Untouched: scripts/stack-release.sh, scripts/stack-copy.sh and the 8e7ea89a1 re-pin target (git diff --stat b8036b608 on the two scripts is empty).

The seven STATUS codes and the channel-proof pin

packages/webui/src/bus.mjs maps the writer's new codes to HTTP:

Code	Status
organization-instance-exists	409
organization-unknown-instance	400
organization-credentials-out-of-scope	400
organization-launch-not-configured	400
organization-no-change	400
organization-project-mismatch	400
organization-unresolvable-instance	400

human-required (403), revision-conflict (409), organization-definition-refused (400), unknown-model (400) and invalid-request were already there. The pin moves in its own commented hunk:

- "packages/webui/src/bus.mjs": "d1f3a274f7aa15eb7ecc2267c65bf4fe7e45c898f77c34235b4e9c29cd1be241", // Row 155 (#1649): eight STATUS entries for the assistant routes, no proof or transport change
+ // Row 165 (#1662): seven STATUS entries for the role instance routes (organization-instance-exists,
+ // organization-unknown-instance, organization-credentials-out-of-scope, organization-launch-not-configured,
+ // organization-no-change, organization-project-mismatch, organization-unresolvable-instance), no proof or
+ // transport change. Row 155 (#1649) added eight for the assistant routes.
+ "packages/webui/src/bus.mjs": "dfbc2289337376b94a399a61599fd4af402b802deb2267dcffc5cf23502c9a4c",

The other three frozen files are byte-equal to b8036b608 (git diff --quiet exits 0 on each): packages/bus/src/human.mjs, packages/bus/src/human-cli.mjs and packages/cli/src/transport.mjs. packages/harness/src/tools.mjs is unchanged too.

The public/ diff (decision 123)

Nothing in public/ is generated, so there is no separate handwritten-only diff.

File	sha256	Lines
public.diff (git diff b8036b608 -- packages/webui/src/public/, bus.js +54/-1)	e5e3435b542fbbe2f69c64ac05ea200c02adc606a1c41020341620ddc19d13e0	76
public-delta-cb79be2e.diff (the change from the first diff)	ff2cbf6bc80a60c24fee374f2e14e9caa5c9619fd4d0a26ae722f54bb324adfe	42

The first diff was cb79be2eaa010e0974d64a38beafb5b8bc55a933e83dad7945cb7c0c4aaa5c8d (74 lines). Mos gave a conditional go on it (mos-0825) with one finding to fix and one note:

• F1: the page took a 200 answer as its next view after checking only the revision and restart, so an answer without definitions would throw in the next render. The page now checks the whole shape (instanceAnswer: a 64-hex revision, a boolean restart, and instances and definitions as non-array objects). A 200 that fails it keeps the view and the draft and says "Outcome unknown. Read the role instances again before trying. Draft kept." serve.mjs makes the same check on the bus answer and refuses with 503 outcome-unknown, sent: "unknown". Sage asked for both (sage-0931): the page doesn't trust the server's shape.
• F2: the restart text named a seat. Sage folded it in (sage-0931). The page now says "Restart needed: the running bus keeps the roles it loaded at start. The Console does not restart it." and the CLI says "restart needed: the running bus keeps the roles it loaded at start; this command does not restart it".

Mos's go on e5e3435b is mos-0826. It replaces the conditional go. It holds while the slot run is green (28 mutants included), the reviewers cover the writer's checks and the new 503 on a bad answer shape, and the +/- lines are unchanged at landing. Any later public/ change goes back to Mos as a delta against e5e3435b.

The warn line and mos-0832 (current go)

Slot run 1 on 70c9131f0 found that views.test.mjs waits for Settings' notifier empty state as #bus-view .empty b. When the instances read failed, my section drew empty() above Notifications, so the wait matched my box. On this page empty() is for a view with nothing in it. A section whose read failed shows a <p class="small warn"> line (bus.js 268 and 284). Line 683 now follows that convention:

-    if(!view)return `...${title}${empty('The role instances could not be read.','They are read from the bus host with your identity.')}</section>`;
+    if(!view)return `...${title}<p class="small warn">The role instances could not be read, so there is nothing to add or change. Read again to retry; they come from the bus host with your identity.</p></section>`;

instances-browser.test.mjs reloads Settings with the read failing. It checks the exact warn text, and that the section has no .empty box and no instance form. Mutant G5 puts the old line back.

File	sha256	Lines	+/- digest
public-70c9131f0-warn.diff (the candidate's whole public/ diff, bus.js +54/-1)	4181b7f649346aa9bb166cd5597e6474fa7011e5f1f9adb1780c0586c648f7a7	76	939ecd28f80bc2f4a36a9468be0ccc2b0f08c8a630508060572491357f1f9444
public-delta-e5e3435b.diff (the one-line change)	fa1012afba5651abaa50b38a304696469a797db485ff0383bf16df5a6f5cd176	11

Mos gave the decision 123 go on 4181b7f6 in mos-0832. It replaces the go on e5e3435b, and the mos-0826 conditions still apply:

1. a green slot run, with the singles and all 29 mutants recorded here;
2. reviewer approvals that cover the server-side writer and the 503 outcome-unknown;
3. the +/- digest is still 939ecd28 at landing.

Any later public/ change goes back to Mos as a delta against 4181b7f6.

ORGANIZATION_KEYS already has an instances key. It is row 125's model selection, which sets vars.model on an existing instance and nothing else. The new verb shares the word and nothing more: its args use the singular instance.

The credential refusal (mos-0823)

The code is organization-credentials-out-of-scope. In the business vocabulary a role's credentials are what credentials binds, and binding them stays a hand edit in this row. The organization- prefix lets the broker pass the code through unchanged (broker.mjs, the organization branch's error mapping), so the CLI and the Console show it by name.

The writer has three behaviors here, each with its own test and its own mutant:

1. An add whose definition declares credentials is refused, and the message names the services: reviewer declares gitea and vikunja credentials; binding them is a hand edit. The same refusal covers a change of definition to such a definition. The file's bytes don't change.
2. The writer never writes an instance without its credential binding. A change away from a definition that declares credentials is refused too, with <instance> holds <definition> credentials; moving them to another definition is a hand edit. checkCredentialMap would refuse most of these anyway. The writer's own check names the reason instead of a validation message.
3. A vars or launch change on an instance that holds its binding succeeds, and credentials and tracker come back unchanged.

The other codes, all with the organization- prefix:

Code	When
organization-instance-exists	add names an instance already in roles
organization-unknown-instance	change names an instance not in roles
organization-definition-refused	the old or new definition is in END_PROTECTED, or the instance is protected
organization-launch-not-configured	launch given and the file has no launch block
organization-no-change	the result is the same document
organization-project-mismatch	a project file's id differs from its key
organization-unresolvable-instance	resolveInstance refuses an instance for a project

A stale revision is revision-conflict. A bad shape and a document validate would refuse are invalid-request, and an instance whose model isn't in launch.models is unknown-model.

The restart report (sage-0918 point 3)

The writer's answer carries restart: true after an add or a definition change. The CLI prints restart needed: the running bus keeps the roles it loaded at start; this command does not restart it. The Console receipt says "Restart needed: the running bus keeps the roles it loaded at start. The Console does not restart it." Product text names no seat (sage-0931). A vars or launch change prints no restart: the launcher reads the change at its next launch check, and the page says the same. Neither surface offers to run a restart, and the tests assert that: the CLI test checks the exact string and that it doesn't match Mos or Jason, and the page test checks there is no button that mentions a restart.

The restart itself needs Mos's go or Jason's hand. TOOLS.md, acceptance 314 and the bus and cli READMEs say so as policy. No test reads TOOLS.md, acceptance 314 or the bus README.

The REASONS tables

The CLI (packages/cli/src/instances.mjs, REASONS) and the Console (serve.mjs, INSTANCE_REASONS) each keep a reason per code, worded for their own surface: the CLI names mosaic business instances and the Console names the read. A code without a reason prints refused by the bus. A refusal is <code>: <reason>. Nothing changed. and the page adds "Draft kept.". Mutants W6 and L2 drop the lookups.

Tests that read a manifest path (sage-0918 point 1)

I grepped every packages/*/tests/*.mjs, scripts/test-*.sh and scripts/foundation/*.test.mjs. For each manifest path the grep looked for the repo path, a ../../<pkg>/<path> import and a ../<path> import. Hits, by path:

Path	Test files
packages/bus/src/broker.mjs	60 (bus, cli, harness, seat, tasks via world.mjs, webui)
packages/bus/src/runtime.mjs	16
packages/cli/src/cli.mjs	27
packages/cli/src/instances.mjs	1, cli/tests/instances.test.mjs
packages/business/src/instance-settings.mjs	1, business/tests/instance-settings.test.mjs
packages/webui/src/bus.mjs	12, among them the channel-proof.test.mjs pin, the only 64-hex pin on a manifest path
packages/webui/src/cli.mjs	29, among them cli/tests/stack-copy.test.mjs and stack-release.test.mjs
packages/webui/src/serve.mjs	33
packages/webui/src/public/bus.js	0 by repo path. The browser tests load it through the server, and webui/tests/shell.test.mjs reads it as read('bus.js'), which the path grep missed
scripts/mosaic	16, among them scripts/test-config.sh, test-queue.sh and test-task.sh
packages/cli/README.md	cli/tests/host.test.mjs (the unit file's name must appear)
packages/webui/README.md	webui/tests/bus-browser.test.mjs (row 61's refused field table wording)
packages/bus/README.md, packages/business/README.md, docs/TOOLS.md, docs/acceptance/314.md	none

The README hits correct my earlier note that no test reads the READMEs: findings on the cli and webui READMEs aren't doc-only. A finding on the bus or business README, TOOLS.md or acceptance 314 is doc-only (decisions 136/137).

Some hits came from a package's own ../src/serve.mjs or ../src/cli.mjs (control-board, discord) or from .mosaic in scripts/foundation/cli.test.mjs. I read each one, and none reads a manifest path. Every real reader is in singles.sh: each *.test.mjs in bus, business, cli and webui (143 files), harness runner and tools, seat sandbox and session, the eight tasks tests that import world.mjs, queue dispatch, runs task-cli, then scripts/test-config.sh, test-queue.sh and test-task.sh. Each file runs singly from its package directory.

Mutants

There are 29, each paired with the tests that should kill it. The second column says what the mutant changes:

Id	Change	Tests	Result
K1	the broker's ORGANIZATION_KEYS gets the instance keys	bus, harness tools	killed
K2	all three key lists get them	bus, harness tools	killed
K3	change_organization sends instances.set	harness tools	killed
H1	the human-required check skips the instances verbs	bus	killed
H2	the broker's INSTANCE_KEYS gets holder	bus	killed
C1	the add credentials check is off (mos-0823 behavior 1)	business, bus, cli, webui	killed
C2	the old-definition credentials check is off (behavior 2)	business, bus, cli, webui	killed
C3	a vars change drops the binding (behavior 3)	business, cli	killed
P1	definitionFor skips END_PROTECTED	business, bus	killed
P2	a protected instance can change	business	killed
V1	no validation of the next document	business	killed
V2	no no-change check	business	killed
R1	the write takes the current revision, not the caller's	business, bus, cli, webui	killed
A1	the actor is system	business, bus, cli, webui	killed
S1	restart is always false	business, bus, cli, webui	killed
W1	the route ignores --send	webui	killed
W2	no Origin check	webui	killed
W3	no Sec-Fetch-Site check	webui	killed
W4	the Console's INSTANCE_KEYS gets holder	webui	killed
W5	the body limit is 64 KiB	webui	killed
W6	the Console drops the reason	webui	killed
W7	the Console passes an answer without definitions (F1)	webui	killed
G1	the page never names a restart	page	killed
G2	a refusal drops the draft	page	killed
G3	the page offers definitions that declare credentials	page	killed
G4	the page takes a 200 without definitions as its view (F1)	page	killed
G5	an unread instances view draws the page's empty state, not a section warning	page	killed
L1	the CLI never names a restart	cli	killed
L2	the CLI drops the reason	cli	killed

DRY=1 finds every anchor exactly once (DRY 29 mutants ok). The results above are from mutants run 2 on wt2, out/mutants-20261018T224704Z: 29 killed, none survived.

Slot run (sage-0939)

Sage gave the slot at 22:18:52Z after Dewey cleared. Everything ran in ~/darkwing-scratch/r165/wt2 at 70c9131f0 plus the candidate, with COMPOSE_PROJECT_NAME=darkwing-r165, pipefail, and the counts summed with awk over the logs.

Run	Output dir under ~/darkwing-scratch/r165/out/	Result
Singles run 1	singles-20261018T222149Z	pass 1417, fail 2
Singles run 2	singles-20261018T223459Z	pass 1419, fail 0 over 163 logs, overall green
Mutants run 1	mutants-20261018T224446Z	28 of 29 killed, W1 survived
W1 alone	mutants-20261018T224658Z	killed
Mutants run 2	mutants-20261018T224704Z	29 of 29 killed

Singles run 2 includes scripts/test-config.sh, test-queue.sh and test-task.sh, which passed 24, 28 and 98.

Singles run 1 had two real failures, neither a flake or board-held:

• shell.test.mjs pins bus.js's POST fetches, and the new /api/instances write wasn't in its list. Fixed in the test (above).
• views.test.mjs matched #bus-view .empty b against my instances empty state. The page now uses the section-warning convention, which is the public/ change Mos approved in mos-0832. The new last step in instances-browser.test.mjs and mutant G5 cover it.

W1 survived mutants run 1 because of a test gap. In webui/tests/instances.test.mjs, the send-off server also had no writer, so a route that skipped !send still refused on !instancesWrite. The test now starts a third server with a writer and send off, and expects 403 and no write. That file passed singly (5 pass, 0 fail, out/fix3-webui-instances.log), W1 alone was killed, and mutants run 2 killed all 29. The change is test-only, so the public/ +/- digest is still 939ecd28...9444 (mos-0832 condition 3).

After the runs, the /proc sweep found 0 of my processes, and the darkwing-r165_default network is gone with 0 containers.

Round 2 (Dewey 29037, Filbert 29036)

Filbert approved round 1 with three notes. Dewey asked for changes on F1 and F2. Round 2 changes 7 files against the round 1 candidate and adds none. webui/src/bus.mjs is unchanged, so the channel-proof pin stays put. The public/ +/- digest is still 939ecd28...9444, so mos-0832 still covers the page.

Dewey F1. The writer took human and tester as instance ids. Both match ID_PATTERN, and validateBusinessDocument only runs requireId. The broker refuses a business whose roles use either name when it loads (broker.mjs, pinned by bus/tests/tester.test.mjs), so an add said "Restart needed" and the next bus start failed closed. instance-settings.mjs now refuses both names with invalid-request, before it reads the file. The business test covers each name, and mutant F1 removes the check. I chose invalid-request over a new code because a new code needs REASONS, INSTANCE_REASONS and a STATUS entry, and that moves the channel-proof pin. The cost is that the human sees invalid-request without the writer's message, because the broker drops it (Dewey N3, Filbert note 1). I left the rule out of validateBusinessDocument, since that would change what every business file accepts. That's a follow-up for Sage to place.

Dewey F2. The route's 503 shape check had a test only for definitions. The table in webui/tests/instances.test.mjs now has three more cases, each wrong in one part: revision: 'x', restart: 'yes', and instances: {}. Mutants F2a, F2b and F2c each drop one check. I also took the two optional GET cases. An answer without instances or without definitions gets 502, and mutants E1 and E2 drop each check. These are test changes only.

Filbert note 2. The organization-definition-refused reason said "an assistant instance changes only through ...", which reads wrong for an add or change that names the assistant definition. Both tables now say the command or form "neither adds nor changes an assistant, and moves no instance to the assistant definition". The CLI test and a real-broker case in the webui route test pin the new wording. Mutants N2a and N2b put the old wording back.

Filbert note 3. The route test already has a revision-conflict case through a real broker, at webui/tests/instances.test.mjs:90. Nothing changed for it.

Follow-ups, not in this row. Dewey N1: check a stale revision before anything else. Dewey N2: a new instance key can take the name of a held seat. Dewey N3 and Filbert note 1: the broker drops the writer's message, so a refusal reaches the human as its code alone.

The business README has a new bullet under "Role instances" for the human/tester refusal.

Round 2 slot run (sage-0950)

~/darkwing-scratch/r165/wt2 at 70c9131f0 plus the round 2 candidate, with COMPOSE_PROJECT_NAME=darkwing-r165.

Run	Result
singles, 163 files, 23:12:51 to 23:22:25	every rc 0; awk sum over the 163 logs pass 1419, fail 0
mutants.py, 37 mutants	37 killed, none survived

Logs: ~/darkwing-scratch/r165/out/singles-20261018T231251Z and ~/darkwing-scratch/r165/out/mutants-20261018T232237Z. After the mutants wt2 matched the candidate manifest, the sweep found no process and no darkwing network was left.

Dewey F2's three 503 checks, all in serve.mjs:314, each with its own mutant that webui/tests/instances.test.mjs kills (rc 1, 1 fail):

Mutant	Check it removes	Case that kills it
F2a	!/^[a-f0-9]{64}$/.test(result?.revision ?? '')	revision: 'x'
F2b	typeof result.restart !== 'boolean'	restart: 'yes'
F2c	!result.instances[instance]	instances: {}
E1	GET 502, serve.mjs:91: !value.instances || typeof value.instances !== 'object'	an answer without instances
E2	GET 502, serve.mjs:91: !value.definitions || typeof value.definitions !== 'object'	an answer without definitions

F1 (the human/tester refusal) dies in instance-settings.test.mjs. N2a and N2b (the old wording in the CLI and the Console) die in instances.test.mjs.

Round 3: rebase onto 4f45cadc0 (sage-0957, sage-0958)

Row 156 landed as 4f45cadc0, and its paths include 4 of this row's 24: docs/TOOLS.md, packages/bus/src/broker.mjs, packages/bus/src/runtime.mjs and packages/cli/README.md. The round 3 worktree is ~/darkwing-scratch/r165/wt3, a fresh detached worktree at 4f45cadc0 with round 2's build.patch (cc886c47...) applied. git apply --check was clean and git apply needed no fuzz or 3-way merge. No round 2 line changes.

Per path, against round 2:

Path	Result
the 20 paths row 156 doesn't touch	byte-equal to wt2
docs/TOOLS.md	the file differs by row 156's lines. This row's +/- lines are identical to round 2's (2 hunks, digest prefix b74e6dd8)
packages/bus/src/broker.mjs	the same, 2 hunks, 446ffd46
packages/bus/src/runtime.mjs	the same, 3 hunks, 3bb624f8
packages/cli/README.md	the same, 1 hunk, bf46a856

The digest prefix is the sha256 of the file's git diff BASE -- FILE +/- lines, without the +++ and --- headers, with BASE 70c9131f0 for round 2 and 4f45cadc0 for round 3.

The public/ diff against 4f45cadc0 has +/- lines byte-equal to round 2's, and their digest is still 939ecd28f80bc2f4a36a9468be0ccc2b0f08c8a630508060572491357f1f9444, so mos-0832's go covers it unchanged. Row 156 doesn't touch public/.

What row 156 changes in the shared code files, and why it doesn't meet this row:

• broker.mjs: 156 adds #received (set in message.receive), landHolders, landRelease, the #held generator behind landHeld, and a landing-turn case in #requestUsage. This row adds INSTANCE_KEYS and the instances and instances.set cases in Broker.request's organization branch. No function has lines from both rows.
• runtime.mjs: 156 adds landHolders and landRelease to the launch API. This row adds the instanceSettings import and writer, and the two verb lines in the organization callback. Both rows' lines are inside startBroker (lines 42 to 223 in wt3), in separate statements: this row's at 70-71 and 99-100, 156's at 202-204 in the launch API object.

Correction (round 3, Filbert 29053): the sentence "No function has lines from both rows" holds for broker.mjs only. In that file 156 doesn't touch request(); its lines are the #received field, landHeld, landHolders, landRelease, three comment lines between request() and #requestUsage, and #requestUsage itself. My review requests to Dewey and Filbert applied the sentence to all four shared paths, which was wrong for runtime.mjs. The statements don't share a line or a variable that either row changes, so the result above stands.

• 156's other code paths are bus/src/process.mjs, cli/src/launcher.mjs and harness/src/runner.mjs. No file of this row imports them, and they don't import this row's new modules.

One reading I checked: landHolders skips a role that #threaded reports as a thread instance, and an instance this row adds is unknown to the broker until a bus restart, as "How a change reaches a running bus" says. So an added instance can't hold a merge decision before the restart. The CLI's and Console's "no restart" receipt rests on the launcher reloading the business file at each launch check. After row 156 it still does, at launcher.mjs:227 (198 at 70c9131f0).

Round 3 build, from a temp index (git read-tree 4f45cadc0, git add the 24 paths, git diff --cached --binary 4f45cadc0):

File	sha256
manifest of the 24 files	e30b54da42d5552b7320a458a5f1c808ac2c5ae6027f554ddc01e3ffc844f580
build.patch against 4f45cadc0	cefce7a49c3bbe7863a68449a5eb7f74af0cefbbb5d1d8fb55c3be416d5e08aa

Round 3 slot run (sage-0959)

On wt3, TMPDIR=~/darkwing-scratch/r165/tmp, COMPOSE_PROJECT_NAME=darkwing-r165:

Run	Result
singles.sh with WT=wt3: 160 test files singly, then test-config.sh, test-queue.sh and test-task.sh	every one of the 163 exits 0. The awk sum over the logs is pass 1436, fail 0 (round 2 was 1419). The 17 more are row 156's: land 11 to 17, launcher 19 to 24, thread-launch 10 to 11 and runner 27 to 32. Every other file's count is unchanged
mutants.py with WT=wt3, all 37	37 killed, none survived

Logs: ~/darkwing-scratch/r165/out/singles-20261018T234323Z and ~/darkwing-scratch/r165/out/mutants-20261018T235312Z. wt3 matched the manifest after both runs, the sweep found no process and no darkwing-r165 network was left. test-queue.sh skips its verify and render --check cases outside the canonical checkout, as in round 2.

The candidate

The candidate is wt3: 4f45cadc0 plus 24 files, 17 changed and 7 new. Round 3 is round 2 rebased onto row 156's landing commit, with no line of this row changed (see "Round 3").

File	sha256
candidate-manifest.sha256 (the 24 files)	e30b54da42d5552b7320a458a5f1c808ac2c5ae6027f554ddc01e3ffc844f580
build.patch (the whole diff against 4f45cadc0)	cefce7a49c3bbe7863a68449a5eb7f74af0cefbbb5d1d8fb55c3be416d5e08aa

Round 2 was manifest 4bcd6a2e... and build.patch cc886c47... against 70c9131f0; the packet keeps them as candidate-manifest-r2.sha256 and build-r2.patch. Round 1 was 89ca3fcf... and d84406b8.... The public/ +/- digest is still 939ecd28...9444, the one mos-0832's go names. The commit message is commit-msg.txt, unchanged from round 2.

Proposal, before any code (brief item 2)

Line numbers are at d88613bac.

The command

scripts/mosaic sends business instances and business instance to packages/cli/src/cli.mjs. validate and resolve still go to packages/business/src/cli.mjs. The human commands live in packages/cli because that is where the human proof and the other-tree check (packages/cli/src/cli.mjs:581-586) already are.

mosaic business instances <business> [--json]
mosaic business instance add <business> <instance> --definition DEF [--vars FILE] [--launch] --revision REV
mosaic business instance set <business> <instance> [--definition DEF] [--vars FILE] [--launch | --no-launch] --revision REV

• instances prints the revision and, for each instance, its definition, its vars, whether it is in launch.instances, and whether it is launch.by or protected. It also lists the definitions in roles/ that add and set accept.
• --vars FILE is a JSON object that replaces the instance's vars whole, the way the assistants key does in row 155.
• --revision is required. A stale one is refused with revision-conflict (exit 2).
• A write prints the business, the new revision, the transaction id, and whether the change waits for a bus restart (below).
• The business is positional, the way it is for validate and resolve.

The bus verbs

There are two new human-only verbs, instances and instances.set. They go into the organization branch of Broker.request (packages/bus/src/broker.mjs:1157), next to plugins and plugins.set, and fail("human-required") covers them the same way. They aren't added to ORGANIZATION_KEYS, and organization.set never maps to them. That keeps them out of the chief of staff's tool, because packages/harness/tests/tools.test.mjs holds the tool's keys equal to SETTINGS_KEYS, and those stay as they are.

instances.set args: { revision, instance, op: "add" | "change", definition?, vars?, launch?: boolean }. add needs definition. change needs at least one of definition, vars and launch.

The writer

There is one new module, packages/business/src/instance-settings.mjs, which is instanceSettings({ dir, rolesDir, system }) with read(id) and set(id, args, actor), built on organizationWriter().write. That follows plugin-settings.mjs. In order, it:

1. checks the shape: the instance id goes through requireId. add refuses an existing id with organization-instance-exists, and change refuses a missing one with organization-unknown-instance;
2. refuses with organization-definition-refused when the instance's old or new definition is in END_PROTECTED. Every change to a protected instance, its vars and launch membership included, is refused here, because the assistant's settings go only through row 155's assistants key. This also covers adding an instance with a protected definition;
3. builds the next document. launch: true adds the instance to launch.instances, and false removes it. With no launch block it is refused with organization-launch-not-configured;
4. runs validateBusinessDocument, then the unknown-model check from launch-settings.mjs:159-165, then the project check mosaic business validate runs (packages/business/src/cli.mjs:290-301). For each project whose project file exists, it runs loadProject, checks the id, and runs resolveInstance for every instance;
5. writes through writer.write(id, next, { revision, actor }). That entry records the actor, the before and after hashes and the changes in changes.jsonl.

validate also stat-checks credential references. This writer can't add or change one, because credentials, holder and tracker are out of scope. A change of definition that needs different services fails checkCredentialMap, so the writer doesn't re-stat references.

The Console

The Settings page gets a "Role instances" section. It has a table from GET /api/instances and two forms, add and change, that POST /api/instances. The routes call the bus through webui/src/cli.mjs under --send only, the way settingsWrite does. The form posts the revision it read. Mos's decision 123 go covers this public/ diff.

How a change reaches a running bus (brief item 6)

• The launcher reloads the business file at every launch check (launcher.mjs:198), so launch membership and vars changes count at the next launch.
• The broker keeps the business it loaded at bus start. bindLaunch refuses a role it doesn't know with unknown-role (broker.mjs:414), so an added instance can't launch until the bus restarts.
• A definition change reaches the broker's authority checks only after a restart. Until then the launcher would start the new contract while the broker checks the old definition's authority. So the writer's answer carries restart: true for an add or a definition change. The CLI and the Console say so, and the restart is Jason's or Mos's call.

Questions for Sage (answered)

Sage answered all three in sage-0918: the expansion is approved, the build keeps the brief's scope with a named refusal for credentials, and the restart is reported, not run. The questions as sent, in the order they blocked code:

1. Files beyond the brief's list. The verbs need these:

   • packages/bus/src/broker.mjs and runtime.mjs, for the two verbs;
   • a new packages/bus/tests/instances-verb.test.mjs;
   • packages/bus/README.md;
   • packages/webui/src/cli.mjs, for the wiring;
   • packages/webui/src/bus.mjs, which gets two STATUS codes, so the channel-proof.test.mjs pin needs a commented bump, as in row 155 r3;
   • scripts/mosaic, for the routing.

   I can't build the verbs without them. Do you approve the expansion?

2. A second reviewer can't be added in this row. reviewer, coder, pm and cto declare gitea and vikunja credentials, so an instance of any of them needs credentials and tracker, which the brief keeps out of scope. security-reviewer and merge-gate declare none, so acceptance 314's two instances do work. I'd keep the brief's scope and record a follow-up for credentials and tracker, but Q171's example was "a second reviewer", and that reading is Jason's.

3. The definition mismatch until a bus restart (above). Within this row I'd only report it. A launcher refusal on a mismatch would be a separate bus row.

Unrelated finding

mosaic plugins (row 145, 467a313c7) isn't in the case list at scripts/mosaic:33, so it looks like it falls through to the seat CLI. I haven't run it. This is a follow-up, not part of this row.