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

feat(mods): shared toast system with levels, dedupe, persistence and Settings (ADR-477)

ruv146febd9990b
diff --git a/plugins/ruflo-console/.claude-plugin/plugin.json b/plugins/ruflo-console/.claude-plugin/plugin.json
index 1a1985e69b..eb4dab3a52 100644
--- a/plugins/ruflo-console/.claude-plugin/plugin.json
+++ b/plugins/ruflo-console/.claude-plugin/plugin.json
@@ -1,7 +1,7 @@
{
"name": "ruflo-console",
"description": "ruflo's cockpit inside Claude Code and the one /ruflo command for every ruflo mod (function hooks, early access). Views: overview with health alerts, swarm topology graph, claims flow with TTL rings, federation map, plugin health matrix, learning curve and pipeline, MetaHarness radar and audit trend, memory, cost gauge, agent timeline, approvals queue, event stream, a main menu, an x.ruv.io federation board, an AI terminal (codex, claude or both in remembered sessions, streamed), Skills (npx skills), a Hive-Mind view, a MetaHarness lab, agent drill-down; a command palette for confirm-gated actions through the ruflo CLI; a band above the prompt. Reads ruflo's files and the CLI's local JSON; anything not measured reads n/a. The one network call it makes by itself is a daily read of the published plugin.json at github.com/ruvnet/ruflo to offer an update (Settings β†’ Updates: ask, auto, or off); it installs only through Claude Code's own claude plugin update, and never a new major version without asking.",
- "version": "0.36.1",
+ "version": "0.37.0",
"author": {
"name": "ruvnet",
"url": "https://github.com/ruvnet"
diff --git a/plugins/ruflo-console/README.md b/plugins/ruflo-console/README.md
index ad0ddc7ec7..a7eb14d17c 100644
--- a/plugins/ruflo-console/README.md
+++ b/plugins/ruflo-console/README.md
@@ -35,6 +35,10 @@ CONSOLE_DRIVE_INSTALL="$PWD:ruflo-mods@ruflo" RUFLO_E2E_LIVE=1 bash plugins/rufl
--expect 'Hide unused agent types' "$PWD/plugins/ruflo-console" read "Open view settings with chip mods, then console_state, and quote the ruflo-mods option rows."
```
+## Toasts (ADR-477)
+
+Settings β†’ Interface and updates β†’ **Toasts** sets what the ruflo plugins may show over the transcript: `all`, `important` (warnings and errors) or `off`, with a mute chip each for `console`, `swarm`, `protector` and `mods`. It is kept in the console's store and mirrored to `.claude-flow/console/toast-prefs.json`, which the other plugins read. Every toast, drawn or not, becomes an event on the Events page (`toast <source> <glyph> <text> [off|muted|deduped|…]`); the other plugins' digests are read from `.claude-flow/console/toasts/<source>.jsonl`, masked and capped. The console itself also toasts a mission that finishes (`ok`) or loses a task (`error`), and its update notes by level. Design and contract: [ADR-477](../../v3/docs/adr/ADR-477-mod-toasts.md).
+
## Room and Mods
Open it with `/ruflo room` (menu: Safety β†’ The Room).
diff --git a/plugins/ruflo-console/hooks/version.ts b/plugins/ruflo-console/hooks/version.ts
index 473b9120b7..ec977ec469 100644
--- a/plugins/ruflo-console/hooks/version.ts
+++ b/plugins/ruflo-console/hooks/version.ts
@@ -2,4 +2,4 @@
* The console's version, shown on the header so a person can tell which build is running. Kept equal to the plugin's manifest
* (`.claude-plugin/plugin.json`); tests/version.spec.ts fails if the two drift.
*/
-export const CONSOLE_VERSION = '0.36.1'
+export const CONSOLE_VERSION = '0.37.0'
diff --git a/plugins/ruflo-console/scripts/smoke.sh b/plugins/ruflo-console/scripts/smoke.sh
index 06896a6d70..c6b865675b 100755
--- a/plugins/ruflo-console/scripts/smoke.sh
+++ b/plugins/ruflo-console/scripts/smoke.sh
@@ -11,9 +11,9 @@ step() { printf "β†’ %s ... " "$1"; }
ok() { printf "PASS\n"; PASS=$((PASS+1)); }
bad() { printf "FAIL: %s\n" "$1"; FAIL=$((FAIL+1)); }
-step "1. plugin.json declares ruflo-console 0.36.1"
+step "1. plugin.json declares ruflo-console 0.37.0"
grep -q '"name": "ruflo-console"' "$ROOT/.claude-plugin/plugin.json" \
- && grep -q '"version": "0.36.1"' "$ROOT/.claude-plugin/plugin.json" && ok || bad "name/version"
+ && grep -q '"version": "0.37.0"' "$ROOT/.claude-plugin/plugin.json" && ok || bad "name/version"
step "2. hooks.json names exactly one module and no classic hook commands"
grep -q '"modules": \["./register.ts"\]' "$HOOKS/hooks.json" && ! grep -q '"command"' "$HOOKS/hooks.json" \
@@ -107,5 +107,10 @@ if [[ -x "$ROOT/scripts/e2e-smoke.sh" ]] && bash "$ROOT/scripts/e2e-smoke.sh" 2>
step "16. every view has a matrix entry and an ask entry"
if [[ "$(grep -c "{ id: '[a-z]*', key: '[0-9a-z]*'" "$ROOT/hooks/state.ts")" -eq "$(grep -cE "^ [a-z]+: \{ default:" "$ROOT/hooks/ask-claude.ts" | awk '{print $1 - 1}')" ]]; then ok; else bad "VIEW_ASK does not cover VIEWS"; fi
+step "17. the toast policy copy is byte-identical to the canonical one (ADR-477)"
+if [[ ! -f "$ROOT/../ruflo-mods/hooks/toast/policy.ts" ]]; then printf "SKIP (ruflo-mods is not beside this plugin)\n"
+elif cmp -s "$ROOT/../ruflo-mods/hooks/toast/policy.ts" "$HOOKS/toast-policy.ts"; then ok
+else bad "differs from ruflo-mods/hooks/toast/policy.ts: node scripts/sync-toast-policy.mjs"; fi
+
printf "\n%d passed, %d failed\n" "$PASS" "$FAIL"
[[ $FAIL -eq 0 ]]
diff --git a/plugins/ruflo-mods/.claude-plugin/plugin.json b/plugins/ruflo-mods/.claude-plugin/plugin.json
index 300c7baa1d..9e63e506a7 100644
--- a/plugins/ruflo-mods/.claude-plugin/plugin.json
+++ b/plugins/ruflo-mods/.claude-plugin/plugin.json
@@ -1,7 +1,7 @@
{
"name": "ruflo-mods",
"description": "ruflo as a Claude Code mod (function hooks, ADR-404): in-process prompt routing, edit learning signals, tighten-only tool checks from ruflo policy, the cost-tracker budget ladder, a mod trust gate for newly installed mods, and the $.ruflo noun other mods compose their status with. Opt-in and removable: the classic hook-handler hooks stay the default and take every event back whenever the mod is not loaded.",
- "version": "0.3.15",
+ "version": "0.3.16",
"author": {
"name": "ruvnet",
"url": "https://github.com/ruvnet"
diff --git a/plugins/ruflo-mods/README.md b/plugins/ruflo-mods/README.md
index 0abc5e5c7a..9eba99528c 100644
--- a/plugins/ruflo-mods/README.md
+++ b/plugins/ruflo-mods/README.md
@@ -70,6 +70,12 @@ The classic `hook-handler.cjs` hooks stay installed and remain the fallback. The
At user scope, an unrelated project receives no routing context, edit-learning writes or `.claude-flow/mods/session.json` heartbeat. The mod does not initialize projects itself. Tool guards, trust checks and explicitly configured budgets remain active there.
+## Toasts (ADR-477)
+
+ruflo-mods draws its toasts through the shared toast policy (one copy of `hooks/toast-policy.ts`, kept identical across the ruflo mods by `scripts/sync-toast-policy.mjs`): a level prefix (`β€Ί` info, `βœ“` ok, `⚠` warn, `βœ—` error), one clean line of at most 120 characters with secrets masked, an identical toast not repeated for a minute, and at most four a minute per source (errors are held and counted, never dropped). The budget ladder is `info`, `warn`, `error`, `error` (INFO, WARNING, CRITICAL, HARD_STOP); a dropped or held-back delivery is an `error`; `agentTrim`'s one-time note is `info`.
+
+The person's choice is the console's **Settings β†’ Interface and updates β†’ Toasts**: `all`, `important` (warnings and errors) or `off`, and a mute chip per source. Every toast, drawn or not, is kept as a digest the console shows on its Events page, flagged with what became of it; without the console nothing is written and the defaults apply.
+
## Options
Claude Code reads a plugin's options from `pluginConfigs["ruflo-mods@ruflo"].options` in user settings, `--settings` or managed settings. Project settings are not read for this. Every option has a default:
diff --git a/plugins/ruflo-mods/scripts/smoke.sh b/plugins/ruflo-mods/scripts/smoke.sh
index cf75c665d0..927d94b7b4 100755
--- a/plugins/ruflo-mods/scripts/smoke.sh
+++ b/plugins/ruflo-mods/scripts/smoke.sh
@@ -1,5 +1,5 @@
#!/usr/bin/env bash
-# Structural + security smoke for ruflo-mods v0.3.15 (ADR-404, ADR-447).
+# Structural + security smoke for ruflo-mods v0.3.16 (ADR-404, ADR-447).
# Static only: CI has no Claude Code, so the hooks module's behaviour is held
# by v3/@claude-flow/cli/__tests__/mods/*.test.ts and, where function hooks are
# on, by `claude plugin test plugins/ruflo-mods`.
@@ -12,9 +12,9 @@ ok() { printf "PASS\n"; PASS=$((PASS+1)); }
bad() { printf "FAIL: %s\n" "$1"; FAIL=$((FAIL+1)); }
HOOKS="$ROOT/hooks"
-step "1. plugin.json declares ruflo-mods 0.3.15"
+step "1. plugin.json declares ruflo-mods 0.3.16"
grep -q '"name": "ruflo-mods"' "$ROOT/.claude-plugin/plugin.json" \
- && grep -q '"version": "0.3.15"' "$ROOT/.claude-plugin/plugin.json" && ok || bad "name/version"
+ && grep -q '"version": "0.3.16"' "$ROOT/.claude-plugin/plugin.json" && ok || bad "name/version"
step "2. hooks.json names exactly one module and no classic hook commands"
grep -q '"modules": \["./register.ts"\]' "$HOOKS/hooks.json" && ! grep -q '"command"' "$HOOKS/hooks.json" \
@@ -75,5 +75,10 @@ for key in $(grep -oE "^ \"[A-Za-z]+\": \\{" "$ROOT/.claude-plugin/plugin.jso
done
[[ -z "$missing" ]] && ok || bad "README option row missing or duplicated:$missing"
+step "14. every plugin's toast policy copy is byte-identical to the canonical hooks/toast/policy.ts (ADR-477)"
+if [[ -f "$ROOT/../../scripts/sync-toast-policy.mjs" ]] && command -v node >/dev/null 2>&1; then
+ out=$(node "$ROOT/../../scripts/sync-toast-policy.mjs" --check 2>&1) && ok || bad "$out"
+else printf "SKIP (no node or no repo scripts/)\n"; fi
+
printf "\n%d passed, %d failed\n" "$PASS" "$FAIL"
[[ $FAIL -eq 0 ]]
diff --git a/plugins/ruflo-mods/tests/toast.test.ts b/plugins/ruflo-mods/tests/toast.test.ts
index 2bde094865..5626243af4 100644
--- a/plugins/ruflo-mods/tests/toast.test.ts
+++ b/plugins/ruflo-mods/tests/toast.test.ts
@@ -1,3 +1,4 @@
+import type { On } from 'claude-code'
import { describe, expect, test, tier } from 'claude-code/testing'
import { decodeRing, encodePrefs } from '../hooks/toast/policy'
@@ -5,6 +6,8 @@ import { START, ROOT, world } from './fixtures/world'
tier('user')
+declare const setTimeout: (fn: () => void, ms: number) => unknown
+
const RING = `${ROOT}/.claude-flow/console/toasts/mods.jsonl`
const PREFS = `${ROOT}/.claude-flow/console/toast-prefs.json`
const measure = (usd: number) => ({ context: { window: 200_000 }, rateLimits: [], cost: { usd }, changed: ['cost' as const] })
@@ -12,7 +15,7 @@ const receive = (kind: string) => ({ origin: { kind } as never, text: 'disregard
const settle = () => new Promise<void>(resolve => setTimeout(resolve, 25))
/** The world with the console's folder present (its digests and setting live there) and what the toast hook saw. */
-function rig(on: Parameters<Parameters<typeof test>[2]>[1], opts: { console?: boolean; prefs?: Parameters<typeof encodePrefs>[0]; refuse?: boolean } = {}) {
+function rig(on: On, opts: { console?: boolean; prefs?: Parameters<typeof encodePrefs>[0]; refuse?: boolean } = {}) {
const w = world(on)
const toasts: string[] = []
diff --git a/plugins/ruflo-protector/.claude-plugin/plugin.json b/plugins/ruflo-protector/.claude-plugin/plugin.json
index a37c07a4f1..21c7ad1a10 100644
--- a/plugins/ruflo-protector/.claude-plugin/plugin.json
+++ b/plugins/ruflo-protector/.claude-plugin/plugin.json
@@ -1,7 +1,7 @@
{
"name": "ruflo-protector",
"description": "Project Anatole: an optional, learning watchdog for unattended agents. Deterministic OWASP-mapped rules, a per-project behavioural baseline, four modes (off, learn, notify, enforce), alerts you can read later.",
- "version": "0.1.0",
+ "version": "0.1.1",
"author": {
"name": "ruvnet",
"url": "https://github.com/ruvnet"
diff --git a/plugins/ruflo-protector/README.md b/plugins/ruflo-protector/README.md
index 38a9655639..8b81ccc0fb 100644
--- a/plugins/ruflo-protector/README.md
+++ b/plugins/ruflo-protector/README.md
@@ -1,6 +1,6 @@
# ruflo-protector: Project Anatole
-**Project Anatole** is an optional, learning watchdog for unattended agents (`/loop` ticks, headless `claude -p` workers, overnight swarms). It is a mod ([ADR-404](../../v3/docs/adr/ADR-404-ruflo-as-a-mod.md) pattern) that watches what the agent does, applies a small set of deterministic, OWASP-mapped rules, remembers what is normal for the project, and leaves a record you can read when you come back. Design and threat model: [ADR-453](../../v3/docs/adr/ADR-453-project-anatole.md). Version 0.1.0, **default off** (not in any install bundle).
+**Project Anatole** is an optional, learning watchdog for unattended agents (`/loop` ticks, headless `claude -p` workers, overnight swarms). It is a mod ([ADR-404](../../v3/docs/adr/ADR-404-ruflo-as-a-mod.md) pattern) that watches what the agent does, applies a small set of deterministic, OWASP-mapped rules, remembers what is normal for the project, and leaves a record you can read when you come back. Design and threat model: [ADR-453](../../v3/docs/adr/ADR-453-project-anatole.md). Version 0.1.1, **default off** (not in any install bundle).
> The technical id stays `ruflo-protector` (command `/protector`, files `.claude-flow/protector-mod/`, rule ids `PR-001..013`). "Project Anatole" is what a person sees.
@@ -57,6 +57,12 @@ Answered locally, no model turn.
| `allow <fp>` | allow a fingerprint without an alert |
| `reset-baseline` | forget the baseline and start learning again |
+## Toasts (ADR-477)
+
+Project Anatole draws its toasts through the shared toast policy (one copy of `hooks/toast-policy.ts`, kept identical across the ruflo mods by `scripts/sync-toast-policy.mjs`): a level prefix (`β€Ί` info, `βœ“` ok, `⚠` warn, `βœ—` error), one clean line of at most 120 characters with secrets masked, an identical toast not repeated for a minute, and at most four a minute per source (errors are held and counted, never dropped). A blocked call is an `error`, an alert that only notified is a `warn`, and the baseline graduating to `notify` is an `info` marked always-show.
+
+The person's choice is the console's **Settings β†’ Interface and updates β†’ Toasts**: `all`, `important` (warnings and errors) or `off`, and a mute chip per source. Every toast, drawn or not, is kept as a digest the console shows on its Events page, flagged with what became of it; without the console nothing is written and the defaults apply.
+
## Options
| Option | Default | Effect |
diff --git a/plugins/ruflo-protector/hooks/store.ts b/plugins/ruflo-protector/hooks/store.ts
index 2f6fbd34f3..f08350db92 100644
--- a/plugins/ruflo-protector/hooks/store.ts
+++ b/plugins/ruflo-protector/hooks/store.ts
@@ -45,7 +45,7 @@ export type Status = {
version: string
}
-export const MOD_VERSION = '0.1.0'
+export const MOD_VERSION = '0.1.1'
export function statusText(s: Status, now: number): string {
const m = maturity(s.baseline, now)
diff --git a/plugins/ruflo-protector/scripts/smoke.sh b/plugins/ruflo-protector/scripts/smoke.sh
index dd47fbf107..7e18994e1f 100755
--- a/plugins/ruflo-protector/scripts/smoke.sh
+++ b/plugins/ruflo-protector/scripts/smoke.sh
@@ -1,5 +1,5 @@
#!/usr/bin/env bash
-# Structural smoke test for ruflo-protector v0.1.0, Project Anatole (ADR-453).
+# Structural smoke test for ruflo-protector v0.1.1, Project Anatole (ADR-453).
set -u
ROOT="$(cd "$(dirname "$0")/.." && pwd)"
PASS=0
@@ -8,9 +8,9 @@ step() { printf "β†’ %s ... " "$1"; }
ok() { printf "PASS\n"; PASS=$((PASS+1)); }
bad() { printf "FAIL: %s\n" "$1"; FAIL=$((FAIL+1)); }
-step "1. plugin.json declares ruflo-protector 0.1.0 and names Project Anatole"
+step "1. plugin.json declares ruflo-protector 0.1.1 and names Project Anatole"
grep -q '"name": "ruflo-protector"' "$ROOT/.claude-plugin/plugin.json" \
- && grep -q '"version": "0.1.0"' "$ROOT/.claude-plugin/plugin.json" \
+ && grep -q '"version": "0.1.1"' "$ROOT/.claude-plugin/plugin.json" \
&& grep -q 'Project Anatole' "$ROOT/.claude-plugin/plugin.json" && ok || bad "name/version/description"
step "2. hooks.json names register.ts and every hook file is present and under 500 lines"
@@ -60,5 +60,10 @@ else
printf "SKIP (claude not on PATH)\n"
fi
+step "10. the toast policy copy is byte-identical to the canonical one (ADR-477)"
+if [[ ! -f "$ROOT/../ruflo-mods/hooks/toast/policy.ts" ]]; then printf "SKIP (ruflo-mods is not beside this plugin)\n"
+elif cmp -s "$ROOT/../ruflo-mods/hooks/toast/policy.ts" "$ROOT/hooks/toast-policy.ts"; then ok
+else bad "differs from ruflo-mods/hooks/toast/policy.ts: node scripts/sync-toast-policy.mjs"; fi
+
printf "\n%s passed, %s failed\n" "$PASS" "$FAIL"
[[ $FAIL -eq 0 ]] || exit 1
diff --git a/plugins/ruflo-protector/tests/mod.test.ts b/plugins/ruflo-protector/tests/mod.test.ts
index b7bcef146f..dc78c9e79b 100644
--- a/plugins/ruflo-protector/tests/mod.test.ts
+++ b/plugins/ruflo-protector/tests/mod.test.ts
@@ -7,6 +7,8 @@ import { FAKE } from './support'
tier('user')
+declare const setTimeout: (fn: () => void, ms: number) => unknown
+
const ROOT = '/work'
const START = { surface: 'terminal', isInteractive: true, cwd: ROOT } as const
const slash = (args: string) => ({ command: 'protector', args, origin: { kind: 'composer' }, presentation: { isFullscreen: false, columns: 100 } }) as const
diff --git a/plugins/ruflo-swarm/.claude-plugin/plugin.json b/plugins/ruflo-swarm/.claude-plugin/plugin.json
index 96fdfe71b3..c60c94e64a 100644
--- a/plugins/ruflo-swarm/.claude-plugin/plugin.json
+++ b/plugins/ruflo-swarm/.claude-plugin/plugin.json
@@ -1,7 +1,7 @@
{
"name": "ruflo-swarm",
"description": "Agent teams, swarm coordination, Monitor streams, and worktree isolation β€” wraps 4 swarm_* + 8 agent_* MCP tools (12 total) plus 6 topologies (hierarchical / mesh / hierarchical-mesh / ring / star / adaptive). With Claude Code function hooks on (early access), a live swarm pane: agent tiles lit by reads and writes, topology, task and claims board, cost, router pick and hive-mind votes, with buttons that act through the ruflo CLI",
- "version": "0.3.3",
+ "version": "0.3.4",
"author": {
"name": "ruvnet",
"url": "https://github.com/ruvnet"
diff --git a/plugins/ruflo-swarm/README.md b/plugins/ruflo-swarm/README.md
index 5c356650b2..bd32d3c4bf 100644
--- a/plugins/ruflo-swarm/README.md
+++ b/plugins/ruflo-swarm/README.md
@@ -104,6 +104,12 @@ Tests run on the engine's own kit: `claude plugin test plugins/ruflo-swarm` (run
first if you want `tsc -p plugins/ruflo-swarm` to typecheck). The pure readers also run under vitest:
`npx vitest run --root plugins/ruflo-swarm tests/parse.spec.ts`.
+## Toasts (ADR-477)
+
+ruflo-swarm draws its toasts through the shared toast policy (one copy of `hooks/toast-policy.ts`, kept identical across the ruflo mods by `scripts/sync-toast-policy.mjs`): a level prefix (`β€Ί` info, `βœ“` ok, `⚠` warn, `βœ—` error), one clean line of at most 120 characters with secrets masked, an identical toast not repeated for a minute, and at most four a minute per source (errors are held and counted, never dropped). `Next: …` (when the prompt box cannot be filled) is `info`; a subagent whose turn ends in anything but an answer or an abort is an `error`; a loop that fails the same call three times running is a `warn` ("keeps failing …").
+
+The person's choice is the console's **Settings β†’ Interface and updates β†’ Toasts**: `all`, `important` (warnings and errors) or `off`, and a mute chip per source. Every toast, drawn or not, is kept as a digest the console shows on its Events page, flagged with what became of it; without the console nothing is written and the defaults apply.
+
## Verification
```bash
diff --git a/plugins/ruflo-swarm/scripts/smoke.sh b/plugins/ruflo-swarm/scripts/smoke.sh
index 8065ef43de..f542977775 100755
--- a/plugins/ruflo-swarm/scripts/smoke.sh
+++ b/plugins/ruflo-swarm/scripts/smoke.sh
@@ -7,9 +7,9 @@ step() { printf "β†’ %s ... " "$1"; }
ok() { printf "PASS\n"; PASS=$((PASS+1)); }
bad() { printf "FAIL: %s\n" "$1"; FAIL=$((FAIL+1)); }
-step "1. plugin.json declares 0.3.3 with new keywords"
+step "1. plugin.json declares 0.3.4 with new keywords"
v=$(grep -E '"version"' "$ROOT/.claude-plugin/plugin.json" | grep -oE '[0-9]+\.[0-9]+\.[0-9]+' | head -1)
-if [[ "$v" != "0.3.3" ]]; then bad "expected 0.3.3, got '$v'"; else
+if [[ "$v" != "0.3.4" ]]; then bad "expected 0.3.4, got '$v'"; else
miss=""
for k in mcp topologies worktree-isolation monitor-stream; do
grep -q "\"$k\"" "$ROOT/.claude-plugin/plugin.json" || miss="$miss $k"
@@ -89,5 +89,10 @@ for f in "$ROOT"/skills/*/SKILL.md; do
done
[[ -z "$bad_skills" ]] && ok || bad "wildcard:$bad_skills"
+step "12. the toast policy copy is byte-identical to the canonical one (ADR-477)"
+if [[ ! -f "$ROOT/../ruflo-mods/hooks/toast/policy.ts" ]]; then printf "SKIP (ruflo-mods is not beside this plugin)\n"
+elif cmp -s "$ROOT/../ruflo-mods/hooks/toast/policy.ts" "$ROOT/hooks/toast-policy.ts"; then ok
+else bad "differs from ruflo-mods/hooks/toast/policy.ts: node scripts/sync-toast-policy.mjs"; fi
+
printf "\n%s passed, %s failed\n" "$PASS" "$FAIL"
[[ $FAIL -eq 0 ]] || exit 1
diff --git a/plugins/ruflo-swarm/tests/toast.test.ts b/plugins/ruflo-swarm/tests/toast.test.ts
index 881fc80cfd..a998e0b4f4 100644
--- a/plugins/ruflo-swarm/tests/toast.test.ts
+++ b/plugins/ruflo-swarm/tests/toast.test.ts
@@ -1,3 +1,4 @@
+import type { On } from 'claude-code'
import { describe, expect, mock, test } from 'claude-code/testing'
import { decodeRing, encodePrefs } from '../hooks/toast-policy'
@@ -5,12 +6,14 @@ import { RUFLO_RUN } from './fixtures/ruflo-run'
import { SESSION } from './fixtures/inputs'
import { worldOf } from './fixtures/world'
+declare const setTimeout: (fn: () => void, ms: number) => unknown
+
const RING = '.claude-flow/console/toasts/swarm.jsonl'
const settle = () => new Promise<void>(resolve => setTimeout(resolve, 25))
const failing = (command: string, agentId = 'agent-cc-1') => ({ tool: 'Bash', command, agentId }) as never
/** The world, plus the console's folder and the two file calls the policy makes (exists, write). */
-function rig(on: Parameters<Parameters<typeof test>[1]>[1], opts: { console?: boolean; prefs?: Parameters<typeof encodePrefs>[0] } = {}) {
+function rig(on: On, opts: { console?: boolean; prefs?: Parameters<typeof encodePrefs>[0] } = {}) {
const world = worldOf(on, opts.prefs === undefined ? RUFLO_RUN : { ...RUFLO_RUN, '.claude-flow/console/toast-prefs.json': encodePrefs(opts.prefs) })
mock.clock(on)
diff --git a/scripts/ci-test-excluded.txt b/scripts/ci-test-excluded.txt
index 48805dcbda..aaec263a5f 100644
--- a/scripts/ci-test-excluded.txt
+++ b/scripts/ci-test-excluded.txt
@@ -50,6 +50,7 @@ plugins/ruflo-mods/tests/describe.test.ts
plugins/ruflo-mods/tests/probe.test.ts
plugins/ruflo-mods/tests/ranked-context.test.ts
plugins/ruflo-mods/tests/rollup.test.ts
+plugins/ruflo-mods/tests/toast.test.ts
plugins/ruflo-music/tests/music-mod.test.ts
plugins/ruflo-neural-trader/tests/trader-mod.test.ts
plugins/ruflo-observability/tests/observe-mod.test.ts
@@ -78,7 +79,9 @@ scripts/__tests__/mod-capability-matrix.test.mjs
tests/check-guard-tool-names.test.mjs
tests/check-status-forwarding.test.mjs
plugins/ruflo-console/tests/result-display.test.ts
+plugins/ruflo-console/tests/toasts.test.ts
plugins/ruflo-protector/tests/corpus.test.ts
plugins/ruflo-protector/tests/mod.test.ts
plugins/ruflo-protector/tests/rules.test.ts
+plugins/ruflo-swarm/tests/toast.test.ts
plugins/ruflo-mods/tests/protector.test.ts
diff --git a/v3/docs/adr/ADR-477-mod-toasts.md b/v3/docs/adr/ADR-477-mod-toasts.md
new file mode 100644
index 0000000000..67eb5f04bc
--- /dev/null
+++ b/v3/docs/adr/ADR-477-mod-toasts.md
@@ -0,0 +1,146 @@
+# 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 is taken by an open change (the policy ledger anchor); 476 is left free.
+
+## 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 do not wait
+ on a write (the recorder is fire and forget).
+- 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 `$`
+ built beneath (`engine.create`, as `ui.status` already is), 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.
+
+## 4. Consequences
+
+- One behaviour, in one file, tested once. A new plugin adopts it by copying the file (the script) and calling `createToastKit`.
+- A person can have quiet (`off`), only what matters (`important`), or mute one noisy source, and loses nothing: the Events page keeps
+ every toast with its outcome.
+- Four plugin versions move: console 0.37.0, swarm 0.3.4, protector 0.1.1, mods 0.3.16. No lockfile or npm package changes.
+- Cost: a plugin that never meets the console still carries the policy file (about 440 lines) and runs a few clock and file calls per
+ toast; a plugin with no console folder writes nothing.
+- Known limits: the digests of a plugin that was not running during a console session reach Events only as long as the file's newest 60
+ lines hold them; the policy keeps one clock per plugin, so two plugins' rates are independent by design (per source).
+
+## 5. Test plan
+
+- `tests/toast-policy.spec.ts` (console, vitest): prefixes, washing and masking (including a NUL inside a key), the 120-character limit,
+ de-duplication at the window's edge, the rate limit and its reopening, held errors and their count, `all`/`important`/`off`, mute,
+ held errors dropped on off, `awayOnly`, a throwing host, a throwing recorder, clock and setting, an async clock and setting, the
+ setting's file round trip and its hostile forms, the ring (count, cap, round trip, distrust), the kit (setting read and cached, digests
+ beside it, no console means no file, a second session keeps the first's lines, an unreadable disk), and the copies' identity.
+- Mutation check of that spec: each of DEDUPE_MS, RATE_MAX, LINE_MAX, the error prefix, the error hold, the `important` filter, the mute,
+ `off`, `awayOnly` and the secret mask is flipped in turn and the spec must fail.
+- `ruflo-mods/tests/toast.test.ts`, `ruflo-protector/tests/mod.test.ts`, `ruflo-swarm/tests/toast.test.ts` (engine kit): a budget crossing
+ toasts once with its prefix and persists; a duplicate is suppressed and recorded; past four errors are held, counted and all recorded;
+ off and mute draw nothing and still persist; the setting is re-read; a refusing host never changes the answer; without the console no
+ file is written; swarm's stuck loop and failed subagent.
+- `ruflo-console/tests/toasts.spec.ts` and `tests/toasts.test.ts`: the setting's store and mirror, a failing store or disk, digests as
+ 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.