Skip to content

armgit / ruflo

Public Imported from GitHub
0

🌊 The original agent harness. Deploy intelligent multi-player swarms, coordinate autonomous workflows, and build conversational AI systems. Features adaptive memory, self-learning intelligence, federation, vector RAG integration, and native Claude Code / Codex / Hermes and many more Integrated

docs(adr): update 407, 428, 474, 475, 476, 477 to what shipped; add ADR-479 (MCP HTTP bearer auth); index 477-479

ruv3ab89ab38e41
diff --git a/v3/docs/adr/ADR-407-ruflo-console-cockpit.md b/v3/docs/adr/ADR-407-ruflo-console-cockpit.md
index 3e2e7592b4..3917b7cc8b 100644
--- a/v3/docs/adr/ADR-407-ruflo-console-cockpit.md
+++ b/v3/docs/adr/ADR-407-ruflo-console-cockpit.md
@@ -239,3 +239,29 @@ The recording driver aborts rather than type into Claude's own prompt. It never
- `plugins/ruflo-console/hooks/{state,harness,stream,bindings,controller}.ts`, `hooks/views/{pane,frames,menu,bar,terminal,xruv}.ts`, `hooks/gfx/{neon,boot,pictures}.ts`
- PRs #3625–#3632 (band, BBS look, Wildcat round, neon boot, AI terminal, compact and focus fixes) and the 0.7.0 release (Skills, Hive-Mind, MetaHarness lab, scrollable framed terminal, clickable band and strip, now-first band, grouped menu)
+
+## Update 2026-10-07: the Settings page's section order (PR #3887)
+
+Section 11c describes Settings as an editor driven by `claude plugin configure`; it does not fix an order. The order is now deliberate, most
+consequential first, and long lists last. Checked against `plugins/ruflo-console/hooks/views/settings.ts` (the render function from the
+`rows.push(...section(...))` calls near its end; the change is commit 5a0e5bff4, merged as #3887).
+
+With no search text, the page shows these sections, top to bottom. Each is a folding section (`section()` in `hooks/views/common.ts`):
+its header toggles it for the session, and all are open by default except where noted.
+
+| # | section (header) | what is in it |
+|---|---|---|
+| 1 | Claude control & spending | the five items `ai-model-control`, `ai-model-confirm`, `ai-accept`, `ai-budget`, `ai-mission-cap`, and a dim line saying claude runs read-only in plan mode and codex in a read-only sandbox, which this view never widens |
+| 2 | AI terminal | the remaining `ai-*` items (model and other per-turn settings, saved here and applied to the next turn) |
+| 3 | Interface & updates | the `ui-*` items: nav style, Updates (ADR-428), Toasts and the per-source mute chips (ADR-477). Its right-hand note reads "the main nav, update checks, toasts" |
+| 4 | Remembered actions | the kinds the person chose "Always allow" for; folded by default when there are none |
+| 5 | ruflo config | the curated `ruflo config get / set` keys (`core-*`) |
+| 6 | Plugin options | the plugin picker, then the selected plugin's options from `claude plugin configure <plugin> --json` |
+
+What changed: Plugin options and ruflo config used to be the first two sections and are now the last two; the model-control, confirm,
+auto-accept and budget items moved out of AI terminal into their own first section; "Interface" became "Interface & updates". The
+levels (simple or advanced), "changed only", "read again" and the search box are unchanged and sit above the sections.
+
+With search text the page is a flat list grouped by source (`── UI`, `── ruflo-console`, and so on), not sections, so the order above does
+not apply and any setting is found in either level. `hooks/settings-palette.ts` lists headless commands (`settings-set` and the like), not
+sections; it needs no change and has none.
diff --git a/v3/docs/adr/ADR-428-console-update-check-and-auto-update.md b/v3/docs/adr/ADR-428-console-update-check-and-auto-update.md
index 8eb9a4fdd4..b64a682b14 100644
--- a/v3/docs/adr/ADR-428-console-update-check-and-auto-update.md
+++ b/v3/docs/adr/ADR-428-console-update-check-and-auto-update.md
@@ -58,3 +58,44 @@ The pure rules and the whole flow are tested with fakes (no host, no network): w
- **Rules:** a version is only `major.minor.patch`; a bump is patch, minor or major and never a downgrade, a pre-release or garbage; the manifest is ours or null; the daily gate, including a stored time in the future; another session updating holds off for ten minutes and no longer; `off` does nothing, `auto` installs minor and patch but asks for a major, and anything not exactly `auto` or `off` is `ask`; the question ends in a question mark, names the repository and what Always means, and has no Always for a major version; the installed list prefers the user scope, then an enabled entry, and ignores other plugins.
- **Flow:** does not even look when off, non-interactive, or a development checkout; at most once a day; skips a version already installed; fails quietly, and tries again next time, when GitHub cannot be reached, hangs (on the host's clock, not `setTimeout`), or sends something that is not our manifest; never throws, even when the store does; Not now, a dismissed dialog and typed text install nothing; Update now runs exactly the list, the marketplace update, the plugin update in the installed scope, and the list; Always turns auto on and installs; auto installs without asking and toasts; auto still asks for a major version, and "Always" cannot be taken for one; "check now" ignores the gate and off but asks and skips a development checkout.
- **What it will not do:** no `-y`, `--yes` or `--accept-command` in any run (checked by adding `-y` and watching two tests fail, then restoring it); Claude Code's own confirmation is reported with the command to run; it does not say installed when the list still shows the old version; it has nothing to update, and says why, when the plugin is not installed from the marketplace (a `--plugin-dir` session); it stops, saying why, when the marketplace will not update; and it always releases the other sessions, whether the install worked or not.
+
+## Update 2026-10-07: what the code does now, and who reads its state
+
+Checked against `plugins/ruflo-console/hooks/{updates,update-flow,register,state}.ts`. The decision above stands. Four things in the
+text are behind the code, and one new reader of the state exists.
+
+**Drift from sections 2.1 to 2.4**
+
+- **A long session re-checks.** `register.ts` starts a timer every `RECHECK_EVERY_MS` (6 hours, `updates.ts`) that runs the check in
+ `quiet` mode. A quiet check never opens the dialog in the middle of someone's work: when the answer would be "ask", it only notes the
+ newer version, once per version (the store key `ruflo-console/update-notified`), as an `info` toast and as the band link to Settings, and
+ it leaves the daily gate open so the next session start asks properly. In `auto` mode the quiet check installs as before. The daily
+ gate in 2.1 applies to the re-check too (it returns `checked in the last day` when the gate is closed). Because a quiet note leaves the
+ gate open, a session that has a newer version pending and unanswered fetches the manifest again on each 6-hour tick until the person
+ installs, declines for good (`off`) or the version is installed; when nothing newer exists the gate closes and the ticks do no network work.
+- **Every install that is behind is updated, not one scope.** Section 2.4 says one `claude plugin update ... --scope <that scope>`.
+ `applyUpdate` now lists every install that applies to the session (the user one and the project's, `installedEntries` in `updates.ts`),
+ and runs `claude plugin update ruflo-console@ruflo --scope <s>` for each scope whose version is behind; one already at the new version is
+ left alone. The rest of 2.4 is unchanged: still no `-y` or `--accept-command`, still not "installed" until the list afterwards shows the
+ new version in every scope (otherwise the result is `unverified` and says what the list shows).
+- **Where the setting lives.** "Settings β†’ Updates" in sections 2.3 and 2.4, and in the toast text, is the Updates row, which is now inside
+ the section **Interface & updates** (ADR-407, update of 2026-10-07). The toast still says "Settings β†’ Updates".
+- **The toasts go through ADR-477.** The toasts in 2.3 and in the flow are no longer direct `$.ui.toast` calls: `host.toast` runs them
+ through the shared policy, so they obey the person's Toasts setting and are recorded on the Events page whether drawn or not. Levels:
+ "is available" and "Updating" are `info`, "installed" is `ok`, any other result is `warn`. With toasts set to `off` or the console muted,
+ the quiet note is therefore silent, but the band link and `state.updateAvailable` still show it.
+
+**The state, and its readers.** A check leaves these in the console's state (`state.ts`, set in `runUpdateCheck`):
+
+- `updates`: the mode (`ask`, `auto`, `off`);
+- `updateNote`: the one line Settings shows for the last result (`result.detail`);
+- `updateAvailable`: the version a declined or quiet-noted check found, or `''`. It is set when the outcome is `declined` and cleared
+ when the outcome is `installed`, `current` or `unverified`; a `skipped` or `failed` check leaves it as it was.
+
+The store (shared by sessions) keeps `update-checked-at`, `update-applying-at`, `update-installed` and the notified version.
+
+The What's new page (ADR-478) reads this state to say whether a newer version is published, and adds no request of its own: the
+only network call in the update flow is the one `fetchText(MANIFEST_URL)` in `update-flow.ts`, a small file that holds `name` and
+`version` and nothing else (`versionFromManifest` accepts nothing more), so the page cannot get release notes from this check and does not
+try to. That the page makes no call of its own is ADR-478's side of the contract and was not checked here, because the page was
+being written on another branch when this note was made.
diff --git a/v3/docs/adr/ADR-474-events-page-capabilities.md b/v3/docs/adr/ADR-474-events-page-capabilities.md
index 650cca3e61..00b25aa04c 100644
--- a/v3/docs/adr/ADR-474-events-page-capabilities.md
+++ b/v3/docs/adr/ADR-474-events-page-capabilities.md
@@ -134,3 +134,46 @@ over 200 lanes x 24 h, append 100 events, append 100 lane samples; `--check` fai
Revert the commit. The files under `.claude-flow/console/` are the console's own and are ignored by older consoles (a line of another schema is
skipped, a prefs file of a newer schema is left alone), so a rollback needs no cleanup; `rm .claude-flow/console/events.jsonl lanes.jsonl events-prefs.json`
removes the history.
+
+## Update 2026-10-07: toast digests are events (ADR-477)
+
+Section 2 lists `notices` as an event kind and `src` as the part of the console that saw it. The toast system (ADR-477) is a new source of
+such events. Checked against `plugins/ruflo-console/hooks/toasts.ts` (`eventOf`, `pullToasts`), `hooks/activity-live.ts` (`gather`, `tick`,
+`TICK_MS`), `hooks/data/event-mask.ts` (`maskLine`), `hooks/data/event-severity.ts` (`levelOf`) and `hooks/data/activity-store.ts`
+(`encodeEvent`, `EVENTS_CAP`).
+
+**What an event looks like.** Every toast the plugins decided on, drawn or not, becomes one event with `kind: "notices"` and
+`src: "toast"` (the `src` is the literal `toast`; the toast's own plugin is in the text). The text is built by `eventOf` as
+
+ toast <source> <prefix> <washed text>[ [<why>]][ Γ—<n>]
+
+for example `toast swarm βœ— swarm: lead failed (timeout) [rate-limited] Γ—2`. `<prefix>` is the level glyph (`β€Ί` `βœ“` `⚠` `βœ—`), `<why>` is
+the outcome and is left out when the toast was `shown`, and `Γ—<n>` appears when identical neighbouring digests were folded.
+Outcomes that can appear are `deduped`, `rate-limited`, `coalesced`, `muted`, `off`, `filtered`, `away` and `refused` (ADR-477,
+matrix). The event time is the digest's time, not the time the console read it.
+
+**Masking and caps.**
+
+- Masked twice before anything is persisted. The plugin's policy washes the text to one line of at most 120 characters (credentials,
+ e-mail addresses, home paths, escapes, control, zero-width, bidi and tag characters). The console then decodes every ring line again
+ (`decodeRing` re-washes the text; a file is not trusted) and `eventOf` passes the whole line through `maskLine(…, 200)`, the page's one
+ washing function. So a toast event is at most 200 characters, tighter than the 240 of section 2's schema; `encodeEvent` masks it once more
+ on write.
+- Sources: four plugins write digests (`console` in memory, `swarm`, `protector`, `mods` in files, ADR-477), but the reader accepts any
+ file name of the right shape: it reads `.claude-flow/console/toasts/<name>.jsonl`
+ for names matching `^[a-z][a-z0-9-]{0,23}$`, at most 12 files per pass, skips its own (`console` has no file; its digests are in memory),
+ and drops any line whose own source field differs from the file's name.
+- Volume: the console's in-memory digest queue is capped at 200 (`MAX_LOG`) and emptied by each pass; a ring file holds the plugin's last 60
+ digests and is read in its last 300 000 characters, lines over 600 characters skipped. A file is re-read only when its modification
+ time moved. De-duplication of what was already taken in uses a key of source, time, outcome, count and text, bounded at 600 keys.
+- Only digests newer than the console's own start are taken in (`sinceMs`), so history from an earlier session is not replayed as new events.
+- Timing: the same 1.5 s pass as the other sources (`TICK_MS`); a toast appears on the page within about that long of its digest being
+ written.
+- Retention and the off switch are the existing ones: appended to `events.jsonl` under the 2 MiB cap with the newest half kept past it, and
+ nothing is written when the `eventsPersist` option is off (the page still shows them for the session).
+
+**One behaviour to know.** The Events page does not carry the toast's own level. The level shown, filtered on and written as `level` is
+`levelOf("notices", text)` from the words (a bad word wins over a warn word, which wins over an ok word, else info). A `βœ—` toast whose
+words contain none of those reads as `info`, and the outcome flag can colour the line: `[refused]` is a bad word, so a toast the host
+refused reads as `bad`, and a `warn` toast that was only `rate-limited` or `deduped` reads by its words alone. Filter or alert on the word
+(`refused`, `failed`, `blocked`) rather than on the glyph.
diff --git a/v3/docs/adr/ADR-475-policy-ledger-anchor.md b/v3/docs/adr/ADR-475-policy-ledger-anchor.md
index b38e886608..c14bffa54d 100644
--- a/v3/docs/adr/ADR-475-policy-ledger-anchor.md
+++ b/v3/docs/adr/ADR-475-policy-ledger-anchor.md
@@ -48,3 +48,50 @@ In `enforce` mode `state.json` was already HMAC-authenticated through `state.anc
- `verifyPolicyLedger` gains `{ establishAnchor }` and results may carry `secondaryAnchor`. `LedgerVerification.anchor` is only set by an explicit establish.
- `AgenticPolicyEngine.verifyLedger({ establishAnchor })` is the only engine path that anchors existing receipts.
- Touches `@claude-flow/security` (bundled) and `@claude-flow/cli`.
+
+## Update 2026-10-07: checked against the merged code
+
+Read against `v3/@claude-flow/cli/src/services/policy-ledger-anchor.ts` (the log, mirror and `assessAnchors`),
+`v3/@claude-flow/cli/src/services/policy-runtime.ts` (`reconcileLedger`, `verifyPolicyLedger`, `withPolicyTransaction`,
+`writePolicyState`), `v3/@claude-flow/cli/src/commands/policy.ts`, `v3/@claude-flow/cli/src/mcp-tools/policy-tools.ts`,
+`v3/@claude-flow/security/src/policy/engine.ts` and `types.ts`. The decision and the threat model hold. The sections above are
+correct in what they decide; these are the places where the code is more specific than the text, or uses different names.
+
+**Confirmed, no drift**
+
+- Receipts present and no anchor: `engine.verifyLedger()` returns `anchor-missing` and `appendReceipt` throws `policy-ledger-anchor-missing`
+ (`engine.ts`); only an empty ledger (`state: 'empty'`) anchors on its first receipt.
+- `--establish-anchor` calls `requireInteractiveAdministrator()` (a TTY on stdin and stdout) in `commands/policy.ts`. The MCP verify tool
+ (`mcp-tools/policy-tools.ts`) calls `verifyPolicyLedger(root)` with no options, so it cannot establish.
+- The log is `.claude-flow/policy/ledger-anchors.json`, `{version: 1, entries: [...]}`, each entry `{seq, length, headHash, prevAnchorHash, ts,
+ event, by?, hash}` with a SHA-256 over `[seq, length, headHash, prevAnchorHash, ts, event, by]`; the log is written after `state.json`
+ (`writePolicyState`), and a state ahead of the log is caught up (`behind`), not read as truncation. `by` is set only for
+ `establish-anchor`, from the OS user name.
+- A readable mirror must appear in the log, else `policy-anchor-log-rolled-back`. A read-only home logs `[policy] anchor mirror not written`
+ and continues.
+- `LedgerVerification.anchor` is only ever `'established-now'` (`types.ts`), set by the explicit establish.
+- Bundled in `@claude-flow/security` 3.0.2 and the CLI.
+
+**Where the code is more specific than the text**
+
+1. **The mirror's directory is a hash, not a project name.** It is
+ `~/.config/ruflo/policy-trust/<sha256 of the project's real path>/ledger-anchor-head.json`, under the home directory from
+ `os.userInfo()`, created 0700. Moving or re-linking the project to a different real path starts a new mirror.
+2. **Two vocabularies.** The log's `event` field has three values: `append`, `migrated-from-state` and `establish-anchor`. What
+ `verify` prints in `secondaryAnchor` is a different set: `recorded-from-state` (written to the log as `migrated-from-state`),
+ `restored-primary` (written as `append`) and `established-explicitly` (written as `establish-anchor`). Section 2.4's
+ "(`migrated-from-state`)" and "(`restored-primary`)" name one of each.
+3. **More failure codes than the one the text names.** Besides `anchor-missing`, `verify` and every policy transaction can fail with
+ `policy-anchor-log-corrupt`, `policy-anchor-mirror-corrupt`, `policy-anchor-log-missing` (a mirror exists but the log is gone),
+ `policy-anchor-log-rolled-back`, `policy-ledger-truncated` and `policy-ledger-anchor-mismatch`. In a transaction only `anchor-missing`
+ gets the long "run `ruflo policy verify --establish-anchor`, otherwise treat it as tampering" message; the others surface as the bare
+ code. With `--establish-anchor` a corrupt log or mirror is treated as absent, and a readable remaining anchor must still agree with the
+ chain (`policy-ledger-truncated` or `policy-ledger-anchor-mismatch` otherwise), as 2.3 says.
+4. **Migration and restore need no operator.** Section 2.4's migration is not an explicit step: any `verify`, including the MCP one, and
+ any policy transaction writes the second anchor for a ledger that has a primary anchor and no log (`migrated-from-state`), and
+ restores a deleted primary from an authentic log (`restored-primary`), when the chain agrees. This is intended (only
+ `--establish-anchor` is gated), but it means a read-only-looking `verify` call can write files.
+5. **A mirror-only state is a failure, not a restore.** If the log is missing and only the mirror remains, a plain `verify` fails with
+ `policy-anchor-log-missing`; only `--establish-anchor` rebuilds the log, and only when the receipts still agree with the mirror.
+
+Nothing in the threat model (section 3) is contradicted: the mirror and log are under the same user's control, so the stated limit stands.
diff --git a/v3/docs/adr/ADR-476-hive-mind-gating.md b/v3/docs/adr/ADR-476-hive-mind-gating.md
index 2df60f9fa7..11486e99a4 100644
--- a/v3/docs/adr/ADR-476-hive-mind-gating.md
+++ b/v3/docs/adr/ADR-476-hive-mind-gating.md
@@ -75,3 +75,44 @@ Hardening that applies to everyone:
- Remote HTTP clients: refused until the operator sets `RUFLO_HIVE_BOOTSTRAP_SECRET` (or reads the file) and passes it as `bootstrapSecret`.
- `hive-mind_join` and `hive-mind_leave` no longer list `hiveToken` as required in their schemas.
- Semver: minor. The break is a security fix to a surface that was an unauthenticated hole.
+
+## Update 2026-10-07: checked against the merged code; #3599 has landed
+
+Read against `v3/@claude-flow/cli/src/mcp-tools/hive-mind-tools.ts` (`classifyCaller`, `readBootstrapSecret`, `ensureBootstrapSecret`,
+`authorizeHive`, `constantTimeEqual`, the eleven `authorizeHive(` call sites, the state write), `v3/@claude-flow/cli/src/mcp-server.ts`
+(the transport labels at the two `callMCPTool` calls), `v3/@claude-flow/cli/src/commands/mcp.ts` and `v3/@claude-flow/cli/src/mcp-client.ts`.
+The decision and the behaviour matrix hold. There is no drift in what is gated or who is exempt; these are details the text leaves out or
+states slightly more strongly than the code.
+
+**Confirmed, no drift**
+
+- Classification is from the server-built `context` and never a tool argument: no context is local (in-process: the CLI, library,
+ tests; `callMCPTool` passes `context` through untouched, so none means none); `transport` `stdio` and `cli` are local; `http`,
+ `websocket`, an unknown string or a context without one are remote. The labels are set at `mcp-server.ts` (`stdio` for the stdio server,
+ `http` or `websocket` for the port-bound transports) and `commands/mcp.ts` (`cli` for `mcp exec`). `RUFLO_HIVE_REQUIRE_AUTH` makes every
+ caller remote only when it is exactly `1`.
+- The eleven gated call sites are `spawn`, `init`, `join`, `leave`, `consensus` (`propose` and `vote`), `broadcast`, `shutdown`,
+ `memory` (`set` and `delete`) and `optimize-memory`. `status`, `memory` `get`/`list` and `consensus` `status` are not gated, as the Limits say.
+- `init` accepts only the operator secret (`allowToken: false`); the other ten accept the secret or the hive token. A local `init` creates
+ `.claude-flow/hive-mind/bootstrap.secret` (`wx`, 0600); a remote one never does.
+- Constant-time compare is over SHA-256 digests (`constantTimeEqual`); `state.json` is written 0600 through a temp file and rename; the
+ hive directory is 0700.
+
+**Where the text is looser than the code**
+
+1. **A short env secret is ignored; a short file secret is not.** `RUFLO_HIVE_BOOTSTRAP_SECRET` must be at least 16 characters or it is
+ skipped and the file is used. The file has no length floor: any non-empty content (after trimming) is the secret. A server with a valid
+ env secret never creates the file.
+2. **"Wrong secret/token: refused" means neither credential was valid.** `authorizeHive` tries the secret, then the hive token; a call that
+ carries a wrong `bootstrapSecret` and a valid `hiveToken` is allowed (except for `init`).
+3. **The denial text depends on what was sent.** Nothing supplied: `bootstrapSecret is required (...)` for `init`, `hiveToken is required
+ (...)` for the others; something supplied: `Invalid bootstrapSecret` if a secret was sent, else `Invalid hiveToken`. Neither names a value.
+4. **A remote server with no secret configured** (the third row of the matrix) can still be driven with a valid `hiveToken` for every
+ gated tool except `init`, which can then never succeed remotely: only a local `init` creates the secret.
+
+**Interaction with the HTTP bearer token (ADR-479, #3599).** The Related line says #3599 owns HTTP authentication, and it now does:
+the HTTP transport can require `Authorization: Bearer <token>` and refuses a non-loopback bind without one. The two are separate layers and
+neither satisfies the other. A request that passes the bearer check still arrives with `transport: 'http'` and is a remote caller here, so
+hive-mind tools still need the operator secret or the hive token, on loopback as well (this ADR still rejects "trust HTTP on loopback").
+Conversely, holding the hive credential authenticates nothing at the HTTP layer. An operator exposing the HTTP transport needs both
+(`RUFLO_MCP_HTTP_TOKEN` for the transport, `RUFLO_HIVE_BOOTSTRAP_SECRET` for the hive tools).
diff --git a/v3/docs/adr/ADR-477-mod-toasts.md b/v3/docs/adr/ADR-477-mod-toasts.md
index d8f3612836..8891b75fdd 100644
--- a/v3/docs/adr/ADR-477-mod-toasts.md
+++ b/v3/docs/adr/ADR-477-mod-toasts.md
@@ -111,234 +111,9 @@ answers it.
after the hook returned was tried and lost digests in the engine kit, so the mods await the toast, not the write.
- Muting is the person's alone and only narrows: no plugin can unmute another, and the default with no file is "all", so a deleted or
corrupt setting never silences an error for good.
-- The engine's static validation follows `$` only into a function declared in the same file: the mods bind the engine's calls from the `# ADR 477: Mods: one toast system, with levels, de-duplication, a record and a setting
-
-Status: Accepted
-
-Date: 2026-10-07
-
-Builds on: ADR-404 (ruflo as a mod), ADR-453 (Project Anatole), ADR-474 (the Events store), ADR-466 (the autopilot's notices)
-
-Numbering: ADR-475 (policy ledger anchor) and ADR-476 (hive-mind gating) were taken by other changes while this was written.
-
-## 1. Context
-
-A mod's toast is `$.ui.toast(text, { timeoutMs })`: transient, one line, no click, fire and forget, and the host may refuse it. Four ruflo
-plugins used it, each with its own wrapper: `ruflo-console` (`quietly(...)` in `register.ts`, `update-flow.ts`, the autopilot's `say`),
-`ruflo-swarm` (`host.toast`, the `Next:` fallback), `ruflo-protector` (a local `toast()` that swallows errors) and `ruflo-mods` (the budget
-ladder, the delivery screen and `agentTrim`, each with its own `try`). Only the autopilot also queued a notice.
-
-What that left:
-
-- no shared helper: four wrappers that trim, swallow and fail differently;
-- no levels: a budget CRITICAL and an informational "update available" looked the same;
-- nothing kept: a toast the person looked away from was gone, and so was its text;
-- no de-duplication or rate limit: one loop could stack twenty identical lines;
-- no control: a person who wanted quiet could not have it, and one who wanted only the important ones could not say so;
-- silence where it mattered: a mission finishing or failing, a subagent dying and a loop going round in circles said nothing.
-
-## 2. Decision
-
-**One policy, carried by every plugin; one setting, owned by the console; one digest per toast, read by the console.**
-
-### 2.1 The policy (one canonical file, byte-identical copies)
-
-`plugins/ruflo-mods/hooks/toast/policy.ts` is the canonical source. It has no import and never touches `$`. A plugin ships alone through
-the marketplace and cannot import a sibling's file at run time, so each other plugin carries a copy at `hooks/toast-policy.ts`.
-`scripts/sync-toast-policy.mjs` writes the copies; `--check` fails naming any that differ. The same check is a step of each plugin's
-`scripts/smoke.sh` (which CI runs through `smoke-all`) and of `tests/toast-policy.spec.ts`. Edit the canonical file, run the script, never
-a copy.
-
-### 2.2 Contract
-
-| rule | value |
-|---|---|
-| levels | `info` `ok` `warn` `error`, drawn with the prefix `β€Ί` `βœ“` `⚠` `βœ—` |
-| one line | escape sequences and control, zero-width, bidi and tag characters removed; white space collapsed; credentials, e-mail addresses and home paths masked; the whole line, prefix included, is at most 120 characters, cut with `…` |
-| de-duplication | an identical (source, text) is not drawn again for 60 s (the level is not part of the identity) |
-| rate limit | at most 4 drawn toasts per source per 60 s |
-| errors | an error past the limit is never dropped: it is held and said once when the window has room, as `βœ— <first> … and N more`; muting or switching toasts off drops what is held (it is already recorded) |
-| setting | `all`: every level; `important`: `warn`, `error`, and anything marked `always`; `off`: none |
-| mute | a source in the muted list draws nothing, whatever its level, errors included |
-| away only | `awayOnly` holds a toast back only when the host says the person is present; with no such signal it draws as usual |
-| failure | a host that throws is a `refused` toast; a failing clock, setting or recorder falls back to the wall clock, the defaults, or nothing. Nothing in the policy throws to its caller |
-
-Every toast, whatever became of it (`shown`, `deduped`, `rate-limited`, `coalesced`, `muted`, `off`, `filtered`, `away`, `refused`), is
-recorded as a **digest**: time, source, level, the washed text, the outcome. Empty text records nothing.
-
-### 2.3 The setting
-
-Owned by the console (Settings β†’ Interface and updates β†’ Toasts): `all | important | off`, and one mute chip per source (`console`, `swarm`,
-`protector`, `mods`). Kept in the console's plugin store like `updates` and the nav style (no confirm: it only narrows what is shown), and
-mirrored to `.claude-flow/console/toast-prefs.json` (`{"v":1,"mode":...,"muted":[...]}`), which the other plugins read through
-`$.fs.read` at most every 4 s. No file, or one that does not parse, is `all` with nothing muted. A plugin with no console runs on the
-defaults.
-
-### 2.4 The record
-
-- The console records its own digests in memory; the Events pass turns them into events.
-- The other plugins keep a ring of their last 60 digests in **their own file**, `.claude-flow/console/toasts/<source>.jsonl`, rewritten
- whole with `$.fs.write` (a plugin has no append, and the Events file is appended by `dd` from the console, so a plugin never writes it).
- Identical neighbours are counted (`n`), not repeated. A plugin writes only when `.claude-flow/console/` exists: that folder is the
- console's, and its own `.gitignore` covers it. Without the console nothing is written.
-- The console reads those files on its 1.5 s pass (when a file's modification time moved), decodes and washes every line again (a file is
- not trusted), ignores a line that claims another source, and takes in only digests newer than its own start. They become `notices` events
- with `src: toast`, written to `events.jsonl` under the existing masking, caps and the `eventsPersist` option.
-- Only masked, length-capped digests are written or read. No network.
-
-### 2.5 Call sites
-
-| plugin | toast | level |
-|---|---|---|
-| mods | budget INFO / WARNING / CRITICAL / HARD_STOP | info / warn / error / error |
-| mods | delivery screen dropped or held back a message | error |
-| mods | `agentTrim` hid agent types (once) | info |
-| protector | blocked a call | error |
-| protector | noticed (an alert, not a block) | warn |
-| protector | baseline mature, mode moved to notify | info, `always` |
-| swarm | `Next: …` when the prompt box could not be filled | info, `awayOnly` |
-| console | update available, updating | info |
-| console | update installed / failed | ok / warn |
-| console | autopilot notices (`say`) | their own level (`bad` is `error`) |
-
-New sources, each behind the same setting:
-
-| source | when | level |
-|---|---|---|
-| console | a mission finished (every task done) | ok |
-| console | a mission lost a task (the task store shows `failed`) | error |
-| swarm | a subagent's turn ended with a reason other than `answer` or `aborted` | error |
-| swarm | a loop failed the same call (same tool, same subject) three times running | warn |
-
-**Not built: a watched-PR CI result.** No watcher exists in the console or any mod; one would be a new network call, which this change
-does not add. **`Next:` is not away-only in practice:** the engine exposes no terminal-focus signal to a mod (`isFocused` in the engine's
-types is a pane's focus, not the terminal's), so `awayOnly` draws as usual until it does; the policy honours the flag the day a host
-answers it.
-
-## 3. Threat and robustness
-
-- A toast is attacker-influenced text (a rule name, a peer's origin, an agent's label). It is washed to one line and masked before it is
- drawn or written; the digest is washed again when read; a ring file is not trusted to name its own source.
-- A toast changes no verdict, answer or hook result: every call is in a `try`, a refusal is swallowed, and the mods' verdicts wait at most for
- the clock and one setting read (cached for 4 s), never for a digest write (the recorder is fire and forget). A fire-and-forget toast
- after the hook returned was tried and lost digests in the engine kit, so the mods await the toast, not the write.
-- Muting is the person's alone and only narrows: no plugin can unmute another, and the default with no file is "all", so a deleted or
- corrupt setting never silences an error for good.
-- The engine's static validation follows `$` only into a function declared in the same file:
- built beneath (`engine.create`, as `ui.status` already is) and, if that did not run first (a test harness), from `session.start`'s own `# ADR 477: Mods: one toast system, with levels, de-duplication, a record and a setting
-
-Status: Accepted
-
-Date: 2026-10-07
-
-Builds on: ADR-404 (ruflo as a mod), ADR-453 (Project Anatole), ADR-474 (the Events store), ADR-466 (the autopilot's notices)
-
-Numbering: ADR-475 (policy ledger anchor) and ADR-476 (hive-mind gating) were taken by other changes while this was written.
-
-## 1. Context
-
-A mod's toast is `$.ui.toast(text, { timeoutMs })`: transient, one line, no click, fire and forget, and the host may refuse it. Four ruflo
-plugins used it, each with its own wrapper: `ruflo-console` (`quietly(...)` in `register.ts`, `update-flow.ts`, the autopilot's `say`),
-`ruflo-swarm` (`host.toast`, the `Next:` fallback), `ruflo-protector` (a local `toast()` that swallows errors) and `ruflo-mods` (the budget
-ladder, the delivery screen and `agentTrim`, each with its own `try`). Only the autopilot also queued a notice.
-
-What that left:
-
-- no shared helper: four wrappers that trim, swallow and fail differently;
-- no levels: a budget CRITICAL and an informational "update available" looked the same;
-- nothing kept: a toast the person looked away from was gone, and so was its text;
-- no de-duplication or rate limit: one loop could stack twenty identical lines;
-- no control: a person who wanted quiet could not have it, and one who wanted only the important ones could not say so;
-- silence where it mattered: a mission finishing or failing, a subagent dying and a loop going round in circles said nothing.
-
-## 2. Decision
-
-**One policy, carried by every plugin; one setting, owned by the console; one digest per toast, read by the console.**
-
-### 2.1 The policy (one canonical file, byte-identical copies)
-
-`plugins/ruflo-mods/hooks/toast/policy.ts` is the canonical source. It has no import and never touches `$`. A plugin ships alone through
-the marketplace and cannot import a sibling's file at run time, so each other plugin carries a copy at `hooks/toast-policy.ts`.
-`scripts/sync-toast-policy.mjs` writes the copies; `--check` fails naming any that differ. The same check is a step of each plugin's
-`scripts/smoke.sh` (which CI runs through `smoke-all`) and of `tests/toast-policy.spec.ts`. Edit the canonical file, run the script, never
-a copy.
-
-### 2.2 Contract
-
-| rule | value |
-|---|---|
-| levels | `info` `ok` `warn` `error`, drawn with the prefix `β€Ί` `βœ“` `⚠` `βœ—` |
-| one line | escape sequences and control, zero-width, bidi and tag characters removed; white space collapsed; credentials, e-mail addresses and home paths masked; the whole line, prefix included, is at most 120 characters, cut with `…` |
-| de-duplication | an identical (source, text) is not drawn again for 60 s (the level is not part of the identity) |
-| rate limit | at most 4 drawn toasts per source per 60 s |
-| errors | an error past the limit is never dropped: it is held and said once when the window has room, as `βœ— <first> … and N more`; muting or switching toasts off drops what is held (it is already recorded) |
-| setting | `all`: every level; `important`: `warn`, `error`, and anything marked `always`; `off`: none |
-| mute | a source in the muted list draws nothing, whatever its level, errors included |
-| away only | `awayOnly` holds a toast back only when the host says the person is present; with no such signal it draws as usual |
-| failure | a host that throws is a `refused` toast; a failing clock, setting or recorder falls back to the wall clock, the defaults, or nothing. Nothing in the policy throws to its caller |
-
-Every toast, whatever became of it (`shown`, `deduped`, `rate-limited`, `coalesced`, `muted`, `off`, `filtered`, `away`, `refused`), is
-recorded as a **digest**: time, source, level, the washed text, the outcome. Empty text records nothing.
-
-### 2.3 The setting
-
-Owned by the console (Settings β†’ Interface and updates β†’ Toasts): `all | important | off`, and one mute chip per source (`console`, `swarm`,
-`protector`, `mods`). Kept in the console's plugin store like `updates` and the nav style (no confirm: it only narrows what is shown), and
-mirrored to `.claude-flow/console/toast-prefs.json` (`{"v":1,"mode":...,"muted":[...]}`), which the other plugins read through
-`$.fs.read` at most every 4 s. No file, or one that does not parse, is `all` with nothing muted. A plugin with no console runs on the
-defaults.
-
-### 2.4 The record
-
-- The console records its own digests in memory; the Events pass turns them into events.
-- The other plugins keep a ring of their last 60 digests in **their own file**, `.claude-flow/console/toasts/<source>.jsonl`, rewritten
- whole with `$.fs.write` (a plugin has no append, and the Events file is appended by `dd` from the console, so a plugin never writes it).
- Identical neighbours are counted (`n`), not repeated. A plugin writes only when `.claude-flow/console/` exists: that folder is the
- console's, and its own `.gitignore` covers it. Without the console nothing is written.
-- The console reads those files on its 1.5 s pass (when a file's modification time moved), decodes and washes every line again (a file is
- not trusted), ignores a line that claims another source, and takes in only digests newer than its own start. They become `notices` events
- with `src: toast`, written to `events.jsonl` under the existing masking, caps and the `eventsPersist` option.
-- Only masked, length-capped digests are written or read. No network.
-
-### 2.5 Call sites
-
-| plugin | toast | level |
-|---|---|---|
-| mods | budget INFO / WARNING / CRITICAL / HARD_STOP | info / warn / error / error |
-| mods | delivery screen dropped or held back a message | error |
-| mods | `agentTrim` hid agent types (once) | info |
-| protector | blocked a call | error |
-| protector | noticed (an alert, not a block) | warn |
-| protector | baseline mature, mode moved to notify | info, `always` |
-| swarm | `Next: …` when the prompt box could not be filled | info, `awayOnly` |
-| console | update available, updating | info |
-| console | update installed / failed | ok / warn |
-| console | autopilot notices (`say`) | their own level (`bad` is `error`) |
-
-New sources, each behind the same setting:
-
-| source | when | level |
-|---|---|---|
-| console | a mission finished (every task done) | ok |
-| console | a mission lost a task (the task store shows `failed`) | error |
-| swarm | a subagent's turn ended with a reason other than `answer` or `aborted` | error |
-| swarm | a loop failed the same call (same tool, same subject) three times running | warn |
-
-**Not built: a watched-PR CI result.** No watcher exists in the console or any mod; one would be a new network call, which this change
-does not add. **`Next:` is not away-only in practice:** the engine exposes no terminal-focus signal to a mod (`isFocused` in the engine's
-types is a pane's focus, not the terminal's), so `awayOnly` draws as usual until it does; the policy honours the flag the day a host
-answers it.
-
-## 3. Threat and robustness
-
-- A toast is attacker-influenced text (a rule name, a peer's origin, an agent's label). It is washed to one line and masked before it is
- drawn or written; the digest is washed again when read; a ring file is not trusted to name its own source.
-- A toast changes no verdict, answer or hook result: every call is in a `try`, a refusal is swallowed, and the mods' verdicts wait at most for
- the clock and one setting read (cached for 4 s), never for a digest write (the recorder is fire and forget). A fire-and-forget toast
- after the hook returned was tried and lost digests in the engine kit, so the mods await the toast, not the write.
-- Muting is the person's alone and only narrows: no plugin can unmute another, and the default with no file is "all", so a deleted or
- corrupt setting never silences an error for good.
-- The engine's static validation follows `$` only into a function declared in the same file: , protector passes `$` to a top-level function, and swarm and the console build
+- The engine's static validation follows `$` only into a function declared in the same file: the mods bind the engine's calls from the `$`
+ built beneath (`engine.create`, as `ui.status` already is) and, if that did not run first (a test harness), from `session.start`'s own `$`;
+ protector passes `$` to a top-level function, and swarm and the console build
the toaster inside the function that holds `$`.
- Each plugin adds no hook event and no network or process call; `ruflo-mods`' smoke still lists exactly the events it did.
- A write by two sessions of one plugin is last-writer-wins on a 60-line courtesy ring; nothing depends on it.
@@ -371,3 +146,74 @@ answers it.
events, the ring files' trust rules, the pass, the bound on the log, the mission notices; end to end through Settings (the Toasts row
and chips, the toast drawn, repeated, off, muted, and on the Events page flagged).
- Each plugin's `scripts/smoke.sh` compares its copy with the canonical file.
+
+## Update 2026-10-07
+
+Checked against `plugins/ruflo-mods/hooks/toast/policy.ts` (the canonical policy, 461 lines; the copies at
+`plugins/ruflo-console/hooks/toast-policy.ts`, `plugins/ruflo-swarm/hooks/toast-policy.ts` and
+`plugins/ruflo-protector/hooks/toast-policy.ts` are the same length), `plugins/ruflo-console/hooks/toasts.ts`,
+`plugins/ruflo-console/hooks/register.ts` and the call sites in `plugins/ruflo-swarm/hooks/register.ts`,
+`plugins/ruflo-protector/hooks/register.ts`, `plugins/ruflo-mods/hooks/{session,noun}.ts`. Nothing in section 2.2 is contradicted by the
+code. What was missing is the order in which the rules run, which decides the outcome when two apply. It is below.
+
+**Editorial repair.** The first bullet of section 3 about the engine's static validation had been overwritten by a replacement-string
+accident (the whole document was pasted into the middle of it, three times). It is restored to one bullet above; no decision text changed.
+
+### The behaviour matrix, as shipped
+
+A toast is decided by `run()` in `policy.ts`, which tests these rules **in this order and stops at the first that applies**:
+
+| # | rule | outcome (the digest's `why`) |
+|---|---|---|
+| 0 | the washed text is empty | `empty`: nothing drawn, nothing recorded |
+| 1 | mode is `off` | `off` |
+| 2 | the source is in the muted list | `muted` |
+| 3 | mode is `important`, the level is `info` or `ok`, and the toast is not `always` | `filtered` |
+| 4 | the toast is `awayOnly` and the host answers `false` for "away" | `away` |
+| 5 | the same washed text was drawn or held in the last 60 s | `deduped` |
+| 6 | fewer than 4 toasts drawn in the last 60 s | draw it: `shown`, or `refused` if the host throws (a refused toast is not remembered, so it may be tried again) |
+| 7 | no room, and the level is `error` | `coalesced`: held (first text kept, a count of more) |
+| 8 | no room, any other level | `rate-limited`: dropped (recorded) |
+
+Mode and level, for a source that is not muted and a toast with no `always` flag (rules 1 to 3, then rule 6 when there is room):
+
+| mode | `info` | `ok` | `warn` | `error` |
+|---|---|---|---|---|
+| `all` | shown | shown | shown | shown |
+| `important` | filtered | filtered | shown | shown |
+| `off` | off | off | off | off |
+
+- A toast marked `always` passes the `important` filter at any level (the only such call is protector's "baseline mature" `info`). It does
+ not pass `off` or a mute.
+- Order matters in two places. `off` is reported as `off` even for a muted source, and a muted source in `important` mode reports `muted`,
+ not `filtered`, because the mute is tested first.
+- A muted source draws nothing at any level, `error` included. No plugin can unmute another: the setting is the person's file.
+- Rules 4 to 8 apply only to a toast that got past 1 to 3, so a `filtered`, `muted` or `off` toast never touches the de-duplication
+ table or the rate window.
+- Rule 5 keys on the washed text alone, not the level, and only a toast that was `shown` or `coalesced` is remembered. A `rate-limited`,
+ `refused`, `filtered` or `away` toast is not, so the same line can still be drawn later. De-duplication is tested **before** the rate
+ limit, so a repeated error line is `deduped`, never counted into a held batch: the K in "and K more" is the number of further distinct held error lines.
+- Held errors: one slot, released when the 60 s window has room, by the next toast of that source or by a timer. All four plugins pass
+ an `after` timer (`$.clock.after`), so a held error is said without waiting for another toast. The released line is
+ `βœ— <first> … and K more` (just `βœ— <first>` when only one was held). The release itself is not a new digest: each held error was already recorded as
+ `coalesced`. At release time a source that is now `off` or muted drops what it holds.
+- `away`: `awayOnly` is honoured only when the host supplies the `away` function. No plugin supplies it today (checked in the four
+ registrations above), so `away` is never the outcome in the shipped code. This is the same limit section 2.5 states for swarm's `Next:`.
+- Every outcome except `empty` is recorded as a digest, drawn or not. The console keeps its own in `state.toastLog`
+ (200 at most, `plugins/ruflo-console/hooks/toasts.ts`); the other plugins write their ring file when `.claude-flow/console/` exists.
+- The console's toaster reads its setting from memory (`state.toastPrefs`) with no file read; the other three read
+ `.claude-flow/console/toast-prefs.json` through a 4 s cache (`PREFS_TTL_MS`). So a change in Settings reaches the console at once and the
+ others within about 4 s.
+
+### Call sites, re-checked
+
+The tables in section 2.5 match the code: swarm's failed subagent (`error`, any end reason except `answer` and `aborted`) and stuck loop
+(`warn`) are in `plugins/ruflo-swarm/hooks/register.ts`; protector's `blocked` (`error`), `noticed` (`warn`) and mature baseline
+(`info`, `always`) are in `plugins/ruflo-protector/hooks/register.ts`; the console's mission finished or failed toasts are the
+`mission-done` and `mission-failed` notices (`TOASTED_KEYS` in `plugins/ruflo-console/hooks/notices.ts`, sent from `controller.ts`);
+the update toasts are in `plugins/ruflo-console/hooks/update-flow.ts` (see ADR-428). The autopilot's `say` maps level `bad` to `error`
+(`ap-live.ts`).
+
+### What's new
+
+The What's new page (ADR-478) raises one console-source info toast per new version.
diff --git a/v3/docs/adr/ADR-479-mcp-http-bearer-auth.md b/v3/docs/adr/ADR-479-mcp-http-bearer-auth.md
new file mode 100644
index 0000000000..34c756e010
--- /dev/null
+++ b/v3/docs/adr/ADR-479-mcp-http-bearer-auth.md
@@ -0,0 +1,126 @@
+# ADR 479: MCP HTTP transport: bearer token, and refusal to serve a network without one
+
+Status: Accepted
+
+Date: 2026-10-07
+
+Related: ADR-012 (MCP security features), ADR-476 (hive-mind gating, a separate layer on the same transport)
+
+Numbering: ADR-478 is reserved for the console's What's new page. This ADR documents what #3598 and #3599 (merged as 42ce158f0, shipped in
+3.55.0) built; it was written afterwards, from the code, because no ADR existed for them.
+
+## 1. Context
+
+`ruflo mcp start -t http` served every registered MCP tool (`memory_*`, `hooks_*`, `agentdb_*`, `hive-mind_*`, and the rest) to any client
+that could reach its host and port, with no authentication, and it would bind any `--host`. `@claude-flow/mcp` has an authorization
+mechanism for tool calls, but it is opt-in (`requireToolAuthorization`, `toolAuthorizer`) and the CLI never turned it on. The shape is the
+one behind CVE-2026-81735 (an optional auth middleware never wired by the integrating CLI, plus a non-loopback bind). In
+`@claude-flow/mcp` an enabled auth config with an empty token list also accepted any bearer value (fail open).
+
+## 2. Decision
+
+**Two controls, both in the places that already existed.** The CLI refuses a network-reachable bind that has no authentication. The
+HTTP transport requires `Authorization: Bearer <token>` on every request when a token is configured.
+
+### 2.1 The gate (CLI, before anything binds)
+
+`startHttpServer()` in `v3/@claude-flow/cli/src/mcp-server.ts` evaluates `shouldRefuseUnauthenticatedHttp(host, env, authenticated)` before it
+imports or binds anything. It refuses (the start throws, `mcp start` exits 1) exactly when
+
+ host is not loopback AND no token is configured AND RUFLO_MCP_ALLOW_UNAUTHENTICATED_HTTP is not set
+
+- **Loopback** is exact-string: `localhost`, `127.0.0.1`, `::1`. Nothing is resolved. `0.0.0.0`, `[::1]`, `127.0.0.2`, `LOCALHOST` and every
+ hostname or LAN address count as non-loopback, so a spelling nobody anticipated fails closed.
+- `RUFLO_MCP_ALLOW_UNAUTHENTICATED_HTTP` is on for the values `1` and `true`, nothing else. It is the documented opt-out for a server behind
+ a reverse proxy or a network boundary that enforces authentication itself.
+- A loopback bind is never refused, with or without a token.
+
+### 2.2 The token
+
+Supplied three ways, in this precedence (`resolveMcpHttpAuthToken`): `--auth-token <value>`, then `--auth-token-file <path>`, then the
+environment variable `RUFLO_MCP_HTTP_TOKEN`. An unset or empty variable means no token. Rules:
+
+- 16 to 512 printable ASCII characters, no space (`[\x21-\x7e]`). A token that is set but malformed is an error, never "no token": the
+ start fails with a message that does not echo the value, so a typo cannot start an unauthenticated server.
+- A file is read as UTF-8 and one trailing newline is removed. An unreadable file is an error.
+- `--auth-token` is visible in `ps` and shell history; the command's own help says to prefer the file or the variable. The `starting` event
+ redacts it.
+- Resolution runs before the transport is looked at, so a malformed `RUFLO_MCP_HTTP_TOKEN` also stops `mcp start` for the stdio transport. A
+ valid token with stdio is ignored. With `-t websocket` a token is refused (`An MCP HTTP auth token is only supported with --transport
+ http`): see 2.4.
+
+### 2.3 What the transport enforces
+
+`v3/@claude-flow/mcp/src/transport/http.ts`. With a token configured the CLI passes `auth: { enabled: true, method: 'token', tokens: [token] }`:
+
+- A middleware, mounted after CORS and the rate limiter (so failed attempts are bounded: 120 per minute on `/rpc` and `/mcp` by default) and
+ before the JSON body parser (so an unauthenticated client cannot make the server read a body), requires a valid bearer token on every
+ route except `GET` or `HEAD` of `/health`. That covers `POST /rpc`, `GET` and `POST /mcp` (the SSE and legacy path) and `GET /info`.
+- The comparison hashes both sides with SHA-256 and uses `timingSafeEqual`, with no early exit across the configured tokens.
+- Every failure is the same response: HTTP 401, `WWW-Authenticate: Bearer`, body `{"jsonrpc":"2.0","id":null,"error":{"code":-32001,
+ "message":"Unauthorized"}}`. The header and token are never logged.
+- Fail closed: auth enabled with an empty token list accepts nothing (this was the fail-open fixed with this change).
+- `GET /health` stays public and, when auth is on, answers only `{"status":"ok"}`: no timestamp, no connection count.
+- The WebSocket endpoint on this transport (`/ws`) checks the token in its connection handler, from `Authorization: Bearer` or from a
+ `?token=` query parameter, and closes the socket with 4001 (none) or 4003 (invalid). An HTTP upgrade does not pass through the middleware
+ above, so this handler is the only check on that path.
+- Tool calls reach the handler with `transport: 'http'` (or `'websocket'`), which is what ADR-476 uses to classify a caller as remote.
+
+### 2.4 Behaviour matrix
+
+`mcp start -t http`. Token set means a valid token from 2.2.
+
+| host | token | `RUFLO_MCP_ALLOW_UNAUTHENTICATED_HTTP` | result |
+|---|---|---|---|
+| loopback | unset | any | starts; **unauthenticated**; the CLI prints a warning naming local processes and DNS rebinding |
+| loopback | set | any | starts; bearer required on everything except `/health` |
+| non-loopback | unset | unset | **refused**, exit 1, the error names the three ways out |
+| non-loopback | unset | `1` or `true` | starts; unauthenticated; the CLI prints a warning |
+| non-loopback | set | any | starts; bearer required (the opt-out does not weaken a token that is set) |
+
+Other transports: `-t stdio` has no network surface and is not gated. `-t websocket` goes through the same refusal rule, but the CLI cannot
+authenticate it (a token is refused, and the standalone websocket transport has no working token check), so a non-loopback websocket server
+starts only with `RUFLO_MCP_ALLOW_UNAUTHENTICATED_HTTP`, and a loopback one is unauthenticated.
+
+### 2.5 Environment and flags
+
+| name | what it does |
+|---|---|
+| `RUFLO_MCP_HTTP_TOKEN` | the bearer token (2.2), lowest precedence |
+| `--auth-token-file <path>` | read the token from a file; preferred over `--auth-token` |
+| `--auth-token <value>` | the token as an argument (visible in argv) |
+| `RUFLO_MCP_ALLOW_UNAUTHENTICATED_HTTP` | `1` or `true`: allow a non-loopback bind with no token |
+
+## 3. Not closed (stated plainly)
+
+- **Loopback with no token is unauthenticated.** Any local process, and any web page that can reach `127.0.0.1` from the person's browser,
+ can call every tool. This is deliberate for the default (`localhost`), documented, and warned about at start; it is not fixed.
+- **There is no `Host` allow-list.** Nothing in `@claude-flow/mcp` rejects a request by its `Host` header, so DNS rebinding is not blocked.
+ By reasoning (not tested here), a rebound page is same-origin to the browser, so the CORS settings do not help. Set a token whenever the
+ HTTP transport is used, loopback included.
+- **A valid token grants every tool.** No ToolAuthorizer is wired, so there is no per-tool or per-caller authorization, no scopes, no
+ identity beyond "holds the token". Only the hive-mind tools add their own check (ADR-476), and it is a different credential.
+- **One static shared secret.** No rotation, expiry, revocation list, or per-client token; the configured token list has one entry.
+- **No TLS.** The transport is Node's plain `http` server; `tlsEnabled`, `tlsCert` and `tlsKey` exist in the config types but nothing reads
+ them. A bearer token on a non-loopback bind crosses the network in clear text unless a TLS-terminating proxy sits in front.
+- **The WebSocket token can ride in the URL** (`?token=`), where proxies and access logs may record it. Use the header form where the client
+ allows.
+- **`/health` is public** by design (liveness only), and `GET /health` is the one request that works without the token.
+- **The opt-out is a footgun by design.** `RUFLO_MCP_ALLOW_UNAUTHENTICATED_HTTP=1` on a reachable host is the pre-change behaviour; the
+ only guard is the warning.
+
+## 4. Consequences
+
+- A deployment that bound a non-loopback host (Docker with `--host 0.0.0.0` is the usual one) stops starting until it sets
+ `RUFLO_MCP_HTTP_TOKEN` and its clients send the header, or sets the opt-out. Loopback users are unaffected. This is listed under Breaking
+ changes in the 3.55.0 changelog.
+- The refusal is a pure function and the wiring is tested through the real `MCPServerManager.start()` with `@claude-flow/mcp` mocked, so
+ deleting the `throw` fails the tests (`v3/@claude-flow/cli/__tests__/mcp-http-nonloopback-auth-gate.test.ts`). Transport enforcement is
+ tested in `v3/@claude-flow/mcp/__tests__/http-transport-auth.test.ts`.
+- Touches `@claude-flow/cli` and `@claude-flow/mcp` (bundled). Semver: minor.
+
+## 5. Not done, and why
+
+- **A `Host` allow-list**, and per-tool authorization, would close two of the gaps in section 3. Both are larger changes to
+ `@claude-flow/mcp` than this one and were left for their own decision.
+- **Defaulting a token on for loopback** was not done: it would break every existing local HTTP client at once.
diff --git a/v3/docs/adr/INDEX-mod-system.md b/v3/docs/adr/INDEX-mod-system.md
index 89e29c837e..f564002942 100644
--- a/v3/docs/adr/INDEX-mod-system.md
+++ b/v3/docs/adr/INDEX-mod-system.md
@@ -64,9 +64,17 @@ Two files carry the number 430 (the menu's accents, and the menu-design amendmen
| 443 | Missions Claude knows about; verified evidence; spend | Accepted | 10-04 | 406, 437, 441 | β€” | #3695 | console 0.29.0, cost-tracker 0.27.1 | `mission-context`, `mission-cost`, `mission-loop` |
| 444 | Claude controls the console | Accepted | 10-04 | 406, 443 | β€” | #3696 | console 0.30.0 (autopilot default 0.32.0) | `model-tools`, `e2e-control.sh` |
| 448 | The Room: a shared live feed | Accepted | 10-04 | 407, 416, 444 | β€” | #3704 (doc), #3705 (page) | console 0.33.0 (expiry event 0.32.2) | `room`, `nav`, `runner`, `watch` |
+| 477 | Mods: one toast system, with levels, de-duplication, a record and a setting | Accepted | 10-07 | 404, 453, 474, 466 | β€” | #3889 | console 0.37.0, swarm 0.3.4, protector 0.1.1, mods 0.3.16 | `toast-policy.spec`, `toasts.spec`, `toasts.test`, `toast.test` |
+| 478 | Console What's new page, plugin changelogs | Accepted | 10-07 | 428, 477 | β€” | β€” | [ADR-478](ADR-478-console-whats-new.md) | β€” |
Other ADRs outside 404-451 that the mod ADRs lean on: 150 (removable integrations), 174 (failures as a learning signal), 322 and 322A/B/C (flywheel, evaluation and promotion, receipts), 324 and 325 (policy engine, claims plane), 103 (witness). The console's Mods section (`hooks/data/mods.ts`, console 0.33.1, PR #3707) reads the status files ADR 446 defines.
+## MCP server
+
+| ADR | Title | Status | Date | Builds on / extends | Superseded by | PR | Shipped in | Tests |
+|---|---|---|---|---|---|---|---|---|
+| 479 | MCP HTTP transport: bearer token, and refusal to serve a network without one | Accepted | 10-07 | related 012, 476 | β€” | #3599 (#3598) | cli 3.55.0, mcp 3.1.0 | `mcp-http-nonloopback-auth-gate.test.ts`, `http-transport-auth.test.ts` |
+
## Notes
- **Dates.** ADRs 444, 445 and 446 were dated 2026 10 05 but were committed on 2026-10-04 (14:36 -0400, merged 19:24 UTC); corrected. ADR 450 is still dated 2026 10 05 in its own header although its file was added on 2026-10-04 (7725b867f); the owner should fix the file.
@@ -74,3 +82,4 @@ Other ADRs outside 404-451 that the mod ADRs lean on: 150 (removable integration
- **Forward links.** 449, 450 and 451 are on `main`. 447 names all three as followers. They do not yet cite each other: 449 cites 404, 446, 447 but not 450 or 451; 450 cites 444 to 448 but not 449 or 451; 451 cites 445 to 447 but not 449 or 450; 452 cites 450 and 451. As of this update 450 and 451 name 449 and 452 and each other in a `Related`/`Builds on` line; 449 still does not name 450 or 451 (not edited here).
- **ADR files whose own Status line differs from this index:** none for 450 and 451, whose Status lines now carry the same implementation summary (section 9 of 450, section 8 of 451 hold the tables). 405, 406 and 449 are "Proposed" in both.
- **ADRs with no stated parent:** 434, 436, 437, 438, 439, 440, 441 carry no `Builds on` or `Extends` line.
+- **2026-10-07 additions.** Rows for 477, 478 and 479 were added. 478's link is to a file added by the change that builds that page. 479 is not a mod ADR; it is listed because 476 (hive-mind gating) and the toasts sit on the same MCP and console surfaces. ADRs 454 to 476 are not in these tables.