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

fix(mods): a toast needs no engine.create (bind at session.start too), a throwing clock falls back to the wall clock; update the cost ladder expectation in the v3 mods contract

ruv04ff98bb327b
diff --git a/plugins/ruflo-console/hooks/toast-policy.ts b/plugins/ruflo-console/hooks/toast-policy.ts
index ce628b6d1a..4382287e82 100644
--- a/plugins/ruflo-console/hooks/toast-policy.ts
+++ b/plugins/ruflo-console/hooks/toast-policy.ts
@@ -292,7 +292,17 @@ export function createToaster(deps: ToasterDeps): Toaster {
}
/** A clock that fails (a refused `clock.now`) is the wall clock: the toast is still decided. */
- const atNow = <T>(then: (now: number) => Maybe<T>, fallback: () => T): Maybe<T> => chain(deps.now(), then, () => chain(Date.now(), then, fallback))
+ const atNow = <T>(then: (now: number) => Maybe<T>, fallback: () => T): Maybe<T> => {
+ let clock: Maybe<number>
+
+ try {
+ clock = deps.now()
+ } catch {
+ clock = Date.now()
+ }
+
+ return chain(clock, then, () => chain(Date.now(), then, fallback))
+ }
const releaseNow = (): Maybe<void> => atNow(now => withPrefs(prefs => releaseAt(now, prefs)), () => undefined)
diff --git a/plugins/ruflo-console/tests/toast-policy.spec.ts b/plugins/ruflo-console/tests/toast-policy.spec.ts
index 85b793a66b..6eb4d6abf3 100644
--- a/plugins/ruflo-console/tests/toast-policy.spec.ts
+++ b/plugins/ruflo-console/tests/toast-policy.spec.ts
@@ -214,13 +214,15 @@ describe('the toaster', () => {
const b = createToaster({ source: 'mods', now: () => 1, show: l => void drawn.push(l), persist: () => Promise.reject(new Error('disk')) })
const c = createToaster({ source: 'mods', now: () => Promise.reject(new Error('clock')), show: l => void drawn.push(l) })
const d = createToaster({ source: 'mods', now: () => 1, show: l => void drawn.push(l), prefs: () => { throw new Error('prefs') } })
+ const e = createToaster({ source: 'mods', now: () => { throw new Error('no clock on this engine') }, show: l => void drawn.push(l) })
expect(a.toast({ text: 'a' })).toBe('shown')
expect(b.toast({ text: 'b' })).toBe('shown')
expect(await c.toast({ text: 'c' })).toBe('shown')
expect(d.toast({ text: 'd' })).toBe('shown')
+ expect(e.toast({ text: 'e' })).toBe('shown')
await Promise.resolve()
- expect(drawn).toEqual(['› a', '› b', '› c', '› d'])
+ expect(drawn).toEqual(['› a', '› b', '› c', '› d', '› e'])
})
it('empty text draws and records nothing', () => {
diff --git a/plugins/ruflo-mods/hooks/session.ts b/plugins/ruflo-mods/hooks/session.ts
index 19037201b0..eec2d21def 100644
--- a/plugins/ruflo-mods/hooks/session.ts
+++ b/plugins/ruflo-mods/hooks/session.ts
@@ -6,6 +6,7 @@ import { HANDSHAKE_MARKER, ownedEvents } from './ownership'
import type { ModOptions } from './options'
import { MAX_BYTES, PROTECTOR_STATUS, protectorLine } from './protector'
import { redraw, report, under, type ModState } from './state'
+import { bindToasts } from './toast'
/** `/ruflo-mods` plus the protector row when `.claude-flow/protector-mod/status.json` is present and readable (bounded, regular file only). */
async function reportWithProtector($: EngineInterface, s: ModState): Promise<string> {
@@ -65,6 +66,14 @@ function hasClassicStatusLine(settings: unknown): boolean {
export function registerSession(on: On, state: ModState, options: ModOptions, guidance?: GuidanceHooks) {
on('session.start', async ($, e, next) => {
state.root = await $.session.root()
+ bindToasts(state, {
+ now: () => $.clock.now(),
+ show: (line, options) => $.ui.toast(line, options),
+ after: (ms, fn) => $.clock.after(ms, fn),
+ read: path => $.fs.read(`${state.root}/${path}`),
+ write: (path, text) => $.fs.write(`${state.root}/${path}`, text),
+ exists: path => $.fs.exists(`${state.root}/${path}`),
+ })
// A user-scoped install loads in every project. Existing Ruflo state is
// the opt-in boundary: a missing, unreadable or non-directory path must
// neither own project events nor be created by the display heartbeat.
diff --git a/plugins/ruflo-mods/hooks/toast/index.ts b/plugins/ruflo-mods/hooks/toast/index.ts
index 8f7eddd0b8..d4e802dd4d 100644
--- a/plugins/ruflo-mods/hooks/toast/index.ts
+++ b/plugins/ruflo-mods/hooks/toast/index.ts
@@ -3,8 +3,24 @@ import { createToastKit, type ToastInput } from './policy'
/**
* The mod's toasts (ADR-477): every `$.ui.toast` of ruflo-mods goes through the shared policy (levels, one clean line, de-duplication, a
- * rate limit, the person's Toasts setting from the console, and a digest on the console's Events page). The engine `$` cannot be passed
- * across an import, so `registerNoun` binds the calls from the `$` built beneath (as it does `ui.status`) and hands them here as functions.
+ * rate limit, the person's Toasts setting from the console, and a digest on the console's Events page). The engine `import type { ModState } from '../state'
+import { createToastKit, type ToastInput } from './policy'
+
+/**
+ * The mod's toasts (ADR-477): every `$.ui.toast` of ruflo-mods goes through the shared policy (levels, one clean line, de-duplication, a
+ * rate limit, the person's Toasts setting from the console, and a digest on the console's Events page). cannot be passed
+ * across an import, so `registerNoun` binds the calls from the `import type { ModState } from '../state'
+import { createToastKit, type ToastInput } from './policy'
+
+/**
+ * The mod's toasts (ADR-477): every `$.ui.toast` of ruflo-mods goes through the shared policy (levels, one clean line, de-duplication, a
+ * rate limit, the person's Toasts setting from the console, and a digest on the console's Events page). built beneath (as it does `ui.status`), and `session.start` from its own `import type { ModState } from '../state'
+import { createToastKit, type ToastInput } from './policy'
+
+/**
+ * The mod's toasts (ADR-477): every `$.ui.toast` of ruflo-mods goes through the shared policy (levels, one clean line, de-duplication, a
+ * rate limit, the person's Toasts setting from the console, and a digest on the console's Events page). if
+ * `engine.create` did not run first (a test harness), and each hands them here as functions.
* The result never rejects and never throws: a refused toast changes no verdict, answer or hook result.
*/
export type ToastBinding = {
@@ -16,8 +32,14 @@ export type ToastBinding = {
exists: (path: string) => Promise<boolean>
}
-export function bindToasts(state: ModState, bound: ToastBinding): void {
- const toaster = createToastKit({ source: 'mods', now: bound.now, show: bound.show, after: bound.after, io: { read: bound.read, write: bound.write, exists: bound.exists } })
+/** The states whose toasts are bound: the first binding wins (`engine.create` runs before `session.start`; either is enough on its own). */
+const bound = new WeakSet<ModState>()
+
+export function bindToasts(state: ModState, calls: ToastBinding): void {
+ if (bound.has(state)) return
+
+ bound.add(state)
+ const toaster = createToastKit({ source: 'mods', now: calls.now, show: calls.show, after: calls.after, io: { read: calls.read, write: calls.write, exists: calls.exists } })
state.say = async (input: ToastInput) => {
try {
diff --git a/plugins/ruflo-mods/hooks/toast/policy.ts b/plugins/ruflo-mods/hooks/toast/policy.ts
index ce628b6d1a..4382287e82 100644
--- a/plugins/ruflo-mods/hooks/toast/policy.ts
+++ b/plugins/ruflo-mods/hooks/toast/policy.ts
@@ -292,7 +292,17 @@ export function createToaster(deps: ToasterDeps): Toaster {
}
/** A clock that fails (a refused `clock.now`) is the wall clock: the toast is still decided. */
- const atNow = <T>(then: (now: number) => Maybe<T>, fallback: () => T): Maybe<T> => chain(deps.now(), then, () => chain(Date.now(), then, fallback))
+ const atNow = <T>(then: (now: number) => Maybe<T>, fallback: () => T): Maybe<T> => {
+ let clock: Maybe<number>
+
+ try {
+ clock = deps.now()
+ } catch {
+ clock = Date.now()
+ }
+
+ return chain(clock, then, () => chain(Date.now(), then, fallback))
+ }
const releaseNow = (): Maybe<void> => atNow(now => withPrefs(prefs => releaseAt(now, prefs)), () => undefined)
diff --git a/plugins/ruflo-protector/hooks/toast-policy.ts b/plugins/ruflo-protector/hooks/toast-policy.ts
index ce628b6d1a..4382287e82 100644
--- a/plugins/ruflo-protector/hooks/toast-policy.ts
+++ b/plugins/ruflo-protector/hooks/toast-policy.ts
@@ -292,7 +292,17 @@ export function createToaster(deps: ToasterDeps): Toaster {
}
/** A clock that fails (a refused `clock.now`) is the wall clock: the toast is still decided. */
- const atNow = <T>(then: (now: number) => Maybe<T>, fallback: () => T): Maybe<T> => chain(deps.now(), then, () => chain(Date.now(), then, fallback))
+ const atNow = <T>(then: (now: number) => Maybe<T>, fallback: () => T): Maybe<T> => {
+ let clock: Maybe<number>
+
+ try {
+ clock = deps.now()
+ } catch {
+ clock = Date.now()
+ }
+
+ return chain(clock, then, () => chain(Date.now(), then, fallback))
+ }
const releaseNow = (): Maybe<void> => atNow(now => withPrefs(prefs => releaseAt(now, prefs)), () => undefined)
diff --git a/plugins/ruflo-swarm/hooks/toast-policy.ts b/plugins/ruflo-swarm/hooks/toast-policy.ts
index ce628b6d1a..4382287e82 100644
--- a/plugins/ruflo-swarm/hooks/toast-policy.ts
+++ b/plugins/ruflo-swarm/hooks/toast-policy.ts
@@ -292,7 +292,17 @@ export function createToaster(deps: ToasterDeps): Toaster {
}
/** A clock that fails (a refused `clock.now`) is the wall clock: the toast is still decided. */
- const atNow = <T>(then: (now: number) => Maybe<T>, fallback: () => T): Maybe<T> => chain(deps.now(), then, () => chain(Date.now(), then, fallback))
+ const atNow = <T>(then: (now: number) => Maybe<T>, fallback: () => T): Maybe<T> => {
+ let clock: Maybe<number>
+
+ try {
+ clock = deps.now()
+ } catch {
+ clock = Date.now()
+ }
+
+ return chain(clock, then, () => chain(Date.now(), then, fallback))
+ }
const releaseNow = (): Maybe<void> => atNow(now => withPrefs(prefs => releaseAt(now, prefs)), () => undefined)
diff --git a/v3/@claude-flow/cli/__tests__/mods/mods-learn-cost.test.ts b/v3/@claude-flow/cli/__tests__/mods/mods-learn-cost.test.ts
index 1fab52012b..a2c6beae2f 100644
--- a/v3/@claude-flow/cli/__tests__/mods/mods-learn-cost.test.ts
+++ b/v3/@claude-flow/cli/__tests__/mods/mods-learn-cost.test.ts
@@ -115,7 +115,7 @@ describe('ADR-404 budget ladder', () => {
for (const usd of [1, 5.5, 6, 7.6, 9.2, 9.3, 12]) {
await mod.dispatch('session.measure', { context: {}, rateLimits: [], cost: { usd }, changed: ['cost'] }, (e) => ({ changed: e.changed }));
}
- expect(world.toasts.map((t) => t.split(':')[0])).toEqual(['ruflo budget INFO', 'ruflo budget WARNING', 'ruflo budget CRITICAL', 'ruflo budget HARD_STOP']);
+ expect(world.toasts.map((t) => t.split(':')[0])).toEqual(['› ruflo budget INFO', '⚠ ruflo budget WARNING', '✗ ruflo budget CRITICAL', '✗ ruflo budget HARD_STOP']);
});
it('with costHardStop, refuses new agents at HARD_STOP and only then', async () => {
diff --git a/v3/docs/adr/ADR-477-mod-toasts.md b/v3/docs/adr/ADR-477-mod-toasts.md
index 389471cdee..d8f3612836 100644
--- a/v3/docs/adr/ADR-477-mod-toasts.md
+++ b/v3/docs/adr/ADR-477-mod-toasts.md
@@ -111,8 +111,234 @@ answers it.
after the hook returned was tried and lost digests in the engine kit, so the mods await the toast, not the write.
- Muting is the person's alone and only narrows: no plugin can unmute another, and the default with no file is "all", so a deleted or
corrupt setting never silences an error for good.
-- The engine's static validation follows `$` only into a function declared in the same file: the mods bind the engine's calls from the `$`
- built beneath (`engine.create`, as `ui.status` already is), 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 `# 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 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.