π 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
TypeScript agentic-aiagentic-frameworkagentic-workflowagentsai-agentsai-assistantai-skillsautonomous-agentsclaudecodexdsh-pluginharnessmcp-servermulti-agentmulti-agent-systemsnpmskillsswarmswarm-intelligencetypescript
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.mdindex 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.mdindex 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.mdindex 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` faiRevert the commit. The files under `.claude-flow/console/` are the console's own and are ignored by older consoles (a line of another schema isskipped, 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.mdindex 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.mdindex 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.mdindex 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 orcorrupt 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 buildthe 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 rowand 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.mdnew file mode 100644index 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.mdindex 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.