plans: Q169 brief, the human and the chief of staff configure the assistant (#1649)

Co-Authored-By: Claude Opus 5.5 <[email protected]>

docs/plans/2026-10-16_q169-assistant-config.md

@@ -0,0 +1,130 @@
+# Q169: who configures and removes the assistant
+
+Status: written by Sage, lead, on Mos's directive for Jason's ruling Q169
+(DECISIONS in the brain repo), issue #1649. It follows `docs/plans/BRIEF-TEMPLATE.md`,
+one `##` heading per row.
+
+Jason's ruling, verbatim: "The only agent that should be able to remove
+the assistant role is the chief of staff. The COS and the user should
+have the ability to (re)configure the assistant role and seat name. The
+user via WebUI or CLI, the COS via the proper tooling."
+
+Row 139 builds the first sentence's refusal: only the chief of staff or a
+human-resolved decision gets past `END_PROTECTED`, and PRD version 1.6
+records all of Q169. This row builds the rest.
+
+## The human and the chief of staff configure the assistant
+
+### Problem
+
+What exists on base 9aa90193d:
+
+- The model the assistant runs. The human sets it through
+  `mosaic limits set --file` (`packages/cli/src/limits.mjs:52`) and the
+  Console's POST /api/settings (`packages/webui/src/serve.mjs:233-235`).
+  The chief of staff sets it with `change_organization`
+  (`packages/harness/src/tools.mjs:163-170`, broker
+  `packages/bus/src/broker.mjs:890-922`). Both reach
+  `packages/business/src/launch-settings.mjs:46-53`, which writes only
+  `vars.model`.
+- Nothing else in the assistant's organization entry. The entry keys are
+  `definition`, `holder`, `vars`, `tracker` and `credentials`
+  (`packages/business/src/business.mjs:89`). Neither actor can change
+  them except by editing the file by hand. `roles/chief-of-staff.md:34-35`
+  tells the chief to raise `policy.change`, and no code applies one.
+- The seat name. No field holds it, although REQ-ROLE-4 says the
+  organization file sets it. Row 141 (#1635, queued) adds an
+  instance-names table, a human-only CLI writer and `to_name`. It has no
+  Console route and no chief of staff tool. Row 139 says whichever of 139
+  and 141 lands second gives the chief of staff the grant to set names.
+- Ending the assistant's run. `end_run` (`tools.mjs:157-162`) is refused
+  at `broker.mjs:1131`. Once row 139 lets the chief of staff past that
+  check, the end still can't work: `#holder` reads `role_claims`
+  (`broker.mjs:215-220`), and the assistant's runs claim in
+  `thread_claims` (`broker.mjs:1071-1088`), so the answer is `not-held`
+  (`broker.mjs:1137`). The cited path also compares a null and an
+  undefined holder run and answers `decision-mismatch` (Dewey, row 139
+  round 2, finding 2). The human can stop any run with `mosaic stop`
+  (`packages/cli/src/cli.mjs:298-305`). The Console has no stop route;
+  its bus verbs are read-only (`serve.mjs:52`).
+
+### Owner and reviewer
+
+- Owner: Darkwing, after row 141, because the seat name uses row 141's
+  names table.
+- Reviewers: Dewey, for security until row 149's security-reviewer role
+  exists, and Filbert.
+
+### Files owned
+
+- `packages/bus/src/broker.mjs`: `organization.set`, the role.end and
+  role.revoke execution for a threaded instance, and the name verb's
+  grant check.
+- `packages/business/src/launch-settings.mjs` and `business.mjs`, only
+  the assistant entry writer and its checks.
+- `packages/harness/src/tools.mjs`: the chief of staff's tools below.
+- `packages/cli/src/`: the human's commands below.
+- `packages/webui/src/serve.mjs` and `packages/webui/src/public/`: the
+  Console's settings view and routes below.
+- `roles/chief-of-staff.json` and `roles/chief-of-staff.md`, only the
+  grants and instructions below.
+- Tests in those packages, the webui browser tests, READMEs and
+  `docs/TOOLS.md`.
+
+### What ships
+
+1. Configuring the assistant means changing its organization entry:
+   `vars` and `tracker`, and `definition` only among definitions the
+   broker treats as the assistant (`THREAD_DEFINITION`,
+   `broker.mjs:122`), so a change can't strip the protection.
+   `holder` and `credentials` stay out of this row. The repository's
+   role files in `roles/` still change only through reviewed commits.
+2. The human configures it through a CLI command and the Console's
+   settings view. The chief of staff configures it through
+   `change_organization` or one new typed tool, carrying the file's
+   revision, so a stale revision is refused with `revision-conflict`.
+   Every other role is refused. Each change logs the actor and the
+   before and after values.
+3. The seat name. The Console gets a route to set it, using row 141's
+   human writer. The chief of staff gets a typed tool to set it, using
+   the grant row 139 or 141 adds. Every other role is refused.
+4. Removing the assistant means ending or revoking its runs, as Mos read
+   Q169 for row 139. A chief of staff `role.end` of the assistant, and a
+   revoke citing a decision the human resolved through the CLI, end
+   every assistant thread run: the end path reads `thread_claims` for a
+   threaded instance, and the null and undefined holder runs compare
+   equal. The Console gets a route for the human to end an assistant
+   run. Removing the instance from the organization file is out of
+   scope.
+5. Tests:
+   - the human's CLI and Console changes of the assistant's vars,
+     tracker and definition succeed and log the human as actor;
+   - the chief of staff's change succeeds and logs the chief as actor;
+   - another role's change is refused;
+   - a definition change to one without the assistant's protection is
+     refused;
+   - a stale revision is refused;
+   - the human's and the chief's name changes succeed and another
+     role's is refused;
+   - the chief of staff's end of the assistant stops every assistant
+     thread run, and its own run's end stays refused;
+   - a revoke citing a human-resolved decision stops them too, and one
+     resolved by an arbiter stays refused;
+   - the Console's stop route ends an assistant run.
+
+### Out of scope
+
+Adding or deleting role instances. Changing `holder` or `credentials`.
+Editing the repository's role files. The refusal itself, which is row
+139.
+
+### Gate
+
+- Dewey and Filbert approve on the row's issue naming the candidate
+  manifest.
+- Mos's decision 123 go on the `public/` diff.
+- Bus, business, harness, cli and webui suites and every
+  `scripts/test-*.sh` green. If the names table or the claims change
+  needs a schema step, the row gets its own window and a migration
+  tested on a copy, as row 141 does.
+- Needs rows 139 and 141 done.