@agfpd/iapeer 0.4.92 → 0.4.94

package/docs/15-fleet-api.md

@@ -63,6 +63,13 @@ The full fleet state. The peer rows are produced by the **same in-process functi
     { "id": "a1", "personality": "boris", "runtime": "claude", "kind": "circuit-breaker",
       "tool": "dangerous-rm", "summary": "rm -rf /tmp/x",
       "content": "cmd=\"rm -rf /tmp/x\" target=\"/tmp/x\"", "createdMs": 1751731100000, "expiresMs": 1751731400000 }
+  ],
+  "notices": [
+    { "id": "n1", "personality": "boris", "runtime": "claude", "kind": "peer-mute",
+      "errorType": "rate_limit", "model": "Fable 5", "summary": "boris · claude — rate_limit (Fable 5)",
+      "content": "You've reached your Fable 5 limit. Run /usage-credits to continue or switch models with /model.",
+      "sessionId": "85ea79c9-…", "createdMs": 1751731100000, "lastMs": 1751731160000,
+      "expiresMs": 1751734700000, "count": 3 }
   ]
 }
 ```
@@ -81,6 +88,7 @@ Field notes:
 - The daemon answering **is** the health signal: there is no `healthy` boolean. A dashboard that cannot reach any advertised address should render the daemon as down (this is also why a purely API-fed dashboard is insufficient when the daemon itself is broken — the built-in TUI keeps its direct in-process read path for exactly that case).
 - The peer's **LLM model is deliberately absent**: the effective model of a live session is not an observable registry fact (static launch pins exist, but reporting a pin as «the model» would lie under runtime auto-switching). If it ever becomes observable, it will appear as an additive field.
 - `approvals` (top-level, docs/17-approval) — the pending human-approval queue, the SAME items `GET /fleet/v1/approvals` returns, carried in the snapshot so a client that already re-fetches `/snapshot` on every event renders the queue with no extra call. **ADDITIVE + OMITTED when the queue is empty** — a client MUST treat its absence as an empty queue (the same rule as `approval_mode`). Each item: `id` (broker id, the target of `POST /fleet/v1/approvals/<id>/(approve|deny)`), `personality` + `runtime` (whose action), `kind` (`tool`|`plan`|`question`|`circuit-breaker`), `tool` (the tool / breaker name), `summary` (a one-line badge string), `content` (the FULL verbatim action — command / diff / plan; criterion #7), `createdMs` / `expiresMs`. The broker's item is a superset — unknown extra fields (`title`, `approvers`) MUST be ignored (obligation 2).
+- `notices` (top-level, docs/19-notices) — live OWNER-facing notices: things the daemon noticed that the peer itself could not report, the v1 case being a structural API error that left it MUTE (`kind: peer-mute`). The SAME items `GET /fleet/v1/notices` returns. **ADDITIVE + OMITTED when the board is empty** — absence ⇒ empty board (the same rule as `approvals`). **READ-ONLY**: a notice is one-way, there is nothing to approve or deny. Each item: `id`, `personality` + `runtime` (who went mute), `kind` (`peer-mute`; treat unknown kinds as renderable), `errorType` (the RUNTIME's own value — `rate_limit`, `overloaded`, `rate_limit_reached`, … — free-form, do not switch exhaustively), `model?`, `resetsAtMs?`, `summary`, `content` (verbatim for claude), `sessionId?`, `createdMs` / `lastMs` / `expiresMs`, `count` (detections folded in — render as `×N`). **`model` and `resetsAtMs` are ABSENT when the runtime did not state them** — absence means *the runtime did not say*, NOT *there is no limit*; a client MUST render unknown and MUST NOT substitute the 5h/7d reset, which belongs to a different limit (docs/19 §3).
 
 ## GET /fleet/v1/peers/&lt;personality&gt;
 
@@ -95,7 +103,7 @@ One peer's card: the same object as the snapshot row, plus its recent history.
 
 ## GET /fleet/v1/events — SSE stream
 
-`text/event-stream` of fleet events, sourced by tail-following the daemon's **durable logs** (`lifecycle.log`, `delivery.log`, `exits.log`). Those files are written by *every* participating process — the daemon, CLI verbs (attach/stop/wake), the pty supervisors — so the stream covers events an in-daemon bus would miss.
+`text/event-stream` of fleet events, sourced by tail-following the daemon's **durable logs** (`lifecycle.log`, `delivery.log`, `exits.log`, `approvals.log`, `notices.log`). Those files are written by *every* participating process — the daemon, CLI verbs (attach/stop/wake), the pty supervisors — so the stream covers events an in-daemon bus would miss.
 
 ```
 GET /fleet/v1/events?replay=50
@@ -110,11 +118,11 @@ GET /fleet/v1/events?replay=50
   data: {"src":"lifecycle","ev":"wake","ts":"2026-07-05T18:00:00.123Z","personality":"boris","mode":"resume"}
   ```
 
-  `data` is the full parsed log line: `src` (`lifecycle` | `delivery` | `exits`) + `ev` + every logfmt field with quoted values decoded. `id` = epoch-ms of the event.
+  `data` is the full parsed log line: `src` (`lifecycle` | `delivery` | `exits` | `approvals` | `notices`) + `ev` + every logfmt field with quoted values decoded. `id` = epoch-ms of the event.
 - A comment `: connected` marks the transition from replay to live; `: hb` comments every ~15 s keep the connection alive.
 - Latency: live events surface within ~0.5 s (log-tail poll).
 
-Current `ev` vocabulary (grows over time — see obligation 1): `wake`, `supervise` (with `action`: `reaped-idle` = parked, `reaped-ephemeral`, `dead`→fresh/resume classification, `eager-orphan-fresh`, `skipped-error`…), `stopped` / `started` (the stop/start verbs — an operator changed a peer's ✕/○ state; `action` is `stopped`/`started` for warm runtimes, `bootout`/`bootstrap` for always-on, with `reason` on failure), `delivery`, `topic-note`, `ephemeral-drain`, `attach` / `attach-end`, `hosted-deliver`, `pty-host-failed`, `supervise-error`, `composer-queue-failed-notify`, `memory-provision`, `session-exit` (from `exits.log`: `cause=child-exit` with `dead_status`/`dead_signal` when the session's process died on its own, `cause=shutdown-sigterm`/`shutdown-sigint` when the supervisor was torn down — reap/stop/new), `supervisor-uncaught` (a survivable supervisor fault left as forensics; the session keeps serving).
+Current `ev` vocabulary (grows over time — see obligation 1): `wake`, `supervise` (with `action`: `reaped-idle` = parked, `reaped-ephemeral`, `dead`→fresh/resume classification, `eager-orphan-fresh`, `skipped-error`…), `stopped` / `started` (the stop/start verbs — an operator changed a peer's ✕/○ state; `action` is `stopped`/`started` for warm runtimes, `bootout`/`bootstrap` for always-on, with `reason` on failure), `delivery`, `topic-note`, `ephemeral-drain`, `attach` / `attach-end`, `hosted-deliver`, `pty-host-failed`, `supervise-error`, `composer-queue-failed-notify`, `memory-provision`, `session-exit` (from `exits.log`: `cause=child-exit` with `dead_status`/`dead_signal` when the session's process died on its own, `cause=shutdown-sigterm`/`shutdown-sigint` when the supervisor was torn down — reap/stop/new), `supervisor-uncaught` (a survivable supervisor fault left as forensics; the session keeps serving), `notice-raised` (docs/19 — the daemon told the OWNER something a peer could not tell him itself: a structural API error left it mute. One line per condition, not per occurrence — repeats fold into the live notice silently).
 
 What the headline states look like on the stream: a peer **waking** is `ev=wake`; a peer **parked to sleep** is `ev=supervise action=reaped-idle`; an operator **stop/start** is `ev=stopped` / `ev=started`; a **death** is `ev=session-exit` (immediately, from the supervisor) followed by the daemon's classification on its next pass.
 
@@ -140,7 +148,7 @@ What the headline states look like on the stream: a peer **waking** is `ev=wake`
 
 `from` is optional: a full `<runtime>-<personality>`, or a bare personality (its default runtime). Default: the **single natural-intelligence peer** of the registry — a GUI-originated message is the human's. With zero or several natural peers the request is refused (`400`) with an instruction to pass `from`.
 
-Not part of the *command* API, deliberately: **attach** (a terminal handoff — a client opens the system terminal with `iapeer attach <peer>`), registry/host **admin verbs** (`create`/`remove`/`update`/`uninstall` — will be added when a client actually needs them). The **human-approval broker** now lives under `/fleet/v1/approvals*` (`GET` the queue / one item, `POST /<id>/(approve|deny)`) with the `approval-request` / `approval-resolved` SSE `ev` kinds and the `approvals` snapshot field above — the full contract is **docs/17-approval**.
+Not part of the *command* API, deliberately: **attach** (a terminal handoff — a client opens the system terminal with `iapeer attach <peer>`), registry/host **admin verbs** (`create`/`remove`/`update`/`uninstall` — will be added when a client actually needs them). The **human-approval broker** now lives under `/fleet/v1/approvals*` (`GET` the queue / one item, `POST /<id>/(approve|deny)`) with the `approval-request` / `approval-resolved` SSE `ev` kinds and the `approvals` snapshot field above — the full contract is **docs/17-approval**. The **notice board** lives under `/fleet/v1/notices*` (`GET` the board / one item — **read-only**: a notice is one-way and has nothing to resolve) with the `notice-raised` SSE `ev` kind and the `notices` snapshot field above — the full contract is **docs/19-notices**.
 
 Errors are always `{"error": "…"}` with an honest status: `400` malformed request, `401` bearer required, `404` unknown peer/endpoint, `405` wrong method, `502` the verb itself failed, `500` internal.
 

package/docs/19-notices.md

@@ -0,0 +1,201 @@
+# 19 — Notices: telling the owner a peer went mute
+
+A peer can fail in a way that leaves it **alive, healthy by every signal the daemon has, and
+unable to say a word**. Nobody inside that session can report it — that is precisely what
+broke. So the daemon reports it, on the owner's own surfaces, by the same principle an
+approval request travels.
+
+This note is the normative contract for the daemon side and for any face that renders
+notices. Client obligations are in §4.
+
+## 1. Why a notice is not an approval
+
+The approval broker (docs/17) and the notice board look alike and are not.
+
+| | Approval | Notice |
+|---|---|---|
+| Direction | request → decision → unblock | one-way |
+| Someone waits | yes — a hook long-polls, a tool is blocked | no |
+| A human must act | yes, or a timeout default-denies | no — it is information |
+| Faces can write | `POST …/approve` \| `…/deny` | nothing to write; **read-only** |
+| Lifetime | until answered or timed out | until TTL |
+
+Reusing the broker would drag a promise/timeout/fail-safe-deny machine into a problem with
+none of those, and would invite a face to "resolve" something that has no resolution.
+
+What the two DO share is the **surface**: a durable log tailed into the fleet SSE stream, an
+additive snapshot field, and a GET endpoint for the verbatim content. A face that already
+renders approvals renders notices with the same plumbing.
+
+## 2. The signal: `peer-mute`
+
+The v1 notice kind. It means: *a structural API error left this peer unable to answer.*
+
+The daemon does not infer this from silence — silence is unfalsifiable. It reads the fact
+**structurally** out of the runtime's own session file. Neither runtime is scraped from the
+pane: the refusal there is prose that line-wraps, while both runtimes write the fact as data.
+
+### claude — the transcript
+
+`~/.claude/projects/<slug>/<sessionId>.jsonl`, on the line the runtime wrote when it refused:
+
+```json
+{ "isApiErrorMessage": true, "error": "rate_limit", "apiErrorStatus": 429,
+  "message": { "model": "<synthetic>", "content": [{ "type": "text",
+    "text": "You've reached your Fable 5 limit. Run /usage-credits to continue or switch models with /model." }] } }
+```
+
+The detector keys on **`isApiErrorMessage: true`** — the CLASS — and reports `error`
+verbatim as `errorType`. `rate_limit` is one value; `overloaded`, an expired auth and any
+future member arrive on the same field and take the same path. `error` is a locale-stable
+enum, so no prose is matched.
+
+### codex — the rollout
+
+`~/.codex/sessions/YYYY/MM/DD/rollout-*.jsonl`, in an `event_msg` / `token_count` payload:
+
+```json
+{ "rate_limits": { "limit_id": "codex", "plan_type": "plus",
+    "primary":   { "used_percent": 1.0,  "window_minutes": 300,   "resets_at": 1783114795 },
+    "secondary": { "used_percent": 17.0, "window_minutes": 10080, "resets_at": 1783412915 },
+    "rate_limit_reached_type": null } }
+```
+
+`rate_limit_reached_type` is `null` while healthy and non-null once a wall is hit. The
+detector keys on **non-null**, never on the variant strings (`rate_limit_reached`,
+`workspace_owner_usage_limit_reached`, `workspace_member_credits_depleted`, … — read out of
+the 0.144.1 binary), so a variant we have never seen still detects and reports itself.
+
+## 3. What the owner is told — and what is deliberately withheld
+
+A notice states who, which runtime, which error type, which model, and when the wall lifts.
+Two of those are **absent by design rather than guessed**:
+
+- **`resetsAtMs` on claude.** Claude does not say when a per-model bucket lifts. Its
+  `errorDetails` is a raw 429 reading *"Please try again later"* — no stamp. The 5h/7d
+  `resets_at` in the statusline blob belongs to a **different limit** and must never be
+  substituted: measured live on 15.07.2026, the 5h bucket sat at **11 %** and the 7d at
+  **66 %** while fable was fully exhausted. Codex does state its reset, so its notices carry
+  one. The asymmetry is real and stays visible.
+- **`model` on codex.** The rollout snapshot names no model. Claude names it only in prose,
+  so it is lifted from the runtime's own sentence when no real model reply precedes the
+  error; a miss omits the field.
+
+Absent field ⇒ *the runtime did not say*. Never ⇒ *there is no limit*.
+
+`content` is the runtime's **verbatim** refusal for claude. For codex the rollout carries no
+prose, so `content` is rendered from its typed fields (both windows, their percentages and
+resets, the plan) — data, never our interpretation of the cause.
+
+## 4. Fleet API
+
+### `GET /fleet/v1/notices`
+
+```json
+{ "api": 1, "version": "0.4.93", "ts": "2026-07-15T21:10:00.000Z", "notices": [ { … } ] }
+```
+
+### `GET /fleet/v1/notices/<id>`
+
+```json
+{ "api": 1, "version": "0.4.93", "ts": "…", "notice": { … } }
+```
+
+404 when the id is unknown or its TTL has passed. There is **no** POST on either route — see §1.
+
+### The notice object
+
+| field | type | notes |
+|---|---|---|
+| `id` | string | `n1`, `n2`, … Unique while live; **not** stable across a daemon restart. |
+| `personality` | string | the mute peer |
+| `runtime` | string | `claude` \| `codex` |
+| `kind` | string | `peer-mute` in v1. **Treat unknown kinds as renderable** — new kinds ride this surface. |
+| `errorType` | string | the runtime's OWN value (`rate_limit`, `overloaded`, `rate_limit_reached`, …). Free-form: do not switch exhaustively. |
+| `model` | string? | **absent** when the runtime did not name it |
+| `resetsAtMs` | number? | epoch-ms; **absent** when the runtime did not state it → render "unknown", never substitute |
+| `summary` | string | one line, e.g. `boris · claude — rate_limit (Fable 5)` |
+| `content` | string | verbatim (claude) / rendered from typed fields (codex) |
+| `sessionId` | string? | correlates with the on-disk transcript |
+| `createdMs` | number | first occurrence |
+| `lastMs` | number | latest OCCURRENCE (not the latest sweep that re-read it) |
+| `expiresMs` | number | TTL boundary |
+| `count` | number | distinct OCCURRENCES folded in (≥1) — how many times the peer actually hit the wall. Render as `×N`. The sweep window overlaps on purpose, so the same runtime event is re-read across passes; the board discriminates on the event's own timestamp, and a re-read never bumps this. |
+
+### Snapshot
+
+`GET /fleet/v1/snapshot` carries `notices?: FleetNotice[]` — the same items, so a client that
+already fetches the snapshot on every event needs no extra call. **ADDITIVE and omitted when
+the board is empty**: absence ⇒ empty board (the same rule as `approvals`).
+
+### Events (SSE)
+
+`notices.log` is one of the tailed durable logs, so `GET /fleet/v1/events` pushes:
+
+```
+ev=notice-raised id=n1 personality=boris runtime=claude kind=peer-mute error_type=rate_limit
+  model="Fable 5" session=… summary="…" created=… expires=…
+```
+
+`resets_at` + `resets_at_iso` appear **only** when the runtime stated a reset. At-least-once;
+ignore unknown `ev` kinds as always.
+
+### Client obligations
+
+1. **Render, never resolve.** No approve/deny.
+2. **Absent `resetsAtMs` ⇒ unknown.** Never substitute the 5h/7d reset — different limit.
+3. **Absent `notices` ⇒ empty board.**
+4. **Unknown `kind` / `errorType` ⇒ still render.** Both are growth seams.
+5. **Do not key on `id` across daemon restarts** — the board is in-memory; a restart
+   re-detects from the on-disk evidence and issues new ids.
+
+## 5. Dedup and TTL — one mechanism
+
+A mute peer re-emits its error on **every** attempted turn. So a notice carries a dedup key —
+`personality | runtime | kind | errorType | model` — and while a notice with that key is live,
+a repeat detection only bumps `count` and `lastMs`: **no new id, no new log line, no new SSE
+event**. The owner sees one card saying `×7`, not seven cards.
+
+`count` means **occurrences, not sweeps**. The sweep window deliberately overlaps (so an event
+landing between two passes is never missed), which means the same transcript line is re-read on
+the next pass. The board therefore discriminates on the runtime event's OWN timestamp: a re-read
+of an already-counted event folds silently and bumps nothing. Without that, two real refusals
+would render as `×3` — a number the owner cannot check and that we would have made up.
+
+When the TTL passes (`IAPEER_NOTICE_TTL_MS`, default 1 h) the notice expires silently. If the
+peer is still broken, the next detection raises a **fresh** notice — a deliberate periodic
+reminder rather than one card that scrolls away forever. Expiry is not an event: either the
+peer recovered (nothing to say) or it is still broken and will re-raise.
+
+The board is in-memory; `notices.log` is the audit trace, not a recovery store. A restart
+re-detects from the transcript evidence still on disk.
+
+## 6. Detection, and why paths are not derived from `cwd`
+
+The daemon sweeps on its own timer (`DEFAULT_MUTEWATCH_INTERVAL_MS`, 20 s — detection latency
+is the product here, and the 60 s supervise tick would put the worst case at the budget with
+nothing to spare). A sweep only opens files whose mtime moved since the last pass.
+
+The obvious route — slugify the peer's registry `cwd` into `~/.claude/projects/<slug>` — is a
+**trap**. The slug mirrors the cwd *string as the process was launched*, not the real path.
+This host carries BOTH `-Users-macmini-Projects-IAPeer` and `-Users-macmini-Projects-iapeer`
+for one case-insensitive directory. So attribution runs the other way: read the cwd each file
+states **about itself** (claude: the `cwd` field on every line; codex: `session_meta.payload.cwd`)
+and match it against the registry, case-insensitively. A file whose cwd belongs to no peer is
+ignored — a human's own session never notifies.
+
+## 7. What is proven, and what is not
+
+- **claude — proven live.** The transcript signal, the missing reset, the whole path
+  (detector → board → fleet surface) were exercised against a genuinely exhausted fable
+  bucket on 15.07.2026. Tests replay the captured line byte-for-byte.
+- **codex — proven by replay, not live.** The rollout structure, windows, resets and the
+  healthy (`null`) path are real bytes from this host. Codex's quota never ran out here, so
+  **no real reached-bytes exist**: the tests flip that one field to a variant read out of the
+  binary. The detector keys on non-null precisely so this synthesis cannot flatter it. A real
+  codex reach should be captured opportunistically and folded in.
+- **The blocking-window heuristic is unverified.** Codex does not say WHICH window blocked;
+  the notice reports the **fullest** one. Both windows ride in `content`, so a human sees the
+  raw fact even if the heuristic picks wrong.
+
+Forensic evidence for all of the above: `docs/internals/forensics/model-limit-2026-07-15/`.

package/docs/README.md

@@ -80,6 +80,7 @@ The sections are layered: from "install and use" to "understand the architecture
 - [16 — Tray](16-tray.md) — the macOS menu-bar fleet dashboard (SwiftBar plugin), the first external Fleet API client
 - [17 — Human approval](17-approval.md) — per-peer gated/yolo mode: routing a runtime's blocking approvals to a human through the daemon broker (hook interception, the broker, Fleet API + CLI)
 - [18 — Origin guard](18-origin-guard.md) — an agent's reply to a human must target the channel the human wrote from: the armed-pair model, the hold, `confirm-send`
+- [19 — Notices](19-notices.md) — telling the owner a peer went mute: detecting the structural API error that leaves a session alive, green and speechless, and routing it to the owner's surfaces one-way (not an approval)
 
 ## Status
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@agfpd/iapeer",
-  "version": "0.4.92",
+  "version": "0.4.94",
   "description": "Run Claude Code and Codex CLI as local background agents that message each other, wake on demand, and share one memory.",
   "license": "Apache-2.0",
   "author": "agfpd",

package/src/daemon/fleet.ts

@@ -62,6 +62,8 @@ import { heartbeatAgeSecs, probeFullDiskAccess, readMemoryProvider, readVoicePro
 import { deliveryLogPath } from './deliverylog.ts'
 import { approvalsLogPath } from './approvalslog.ts'
 import { ApprovalBroker } from './approvals.ts'
+import { noticesLogPath } from './noticeslog.ts'
+import { NoticeBoard } from './notices.ts'
 import { callTool, type CallToolDeps } from './index.ts'
 
 /** The API generation baked into every snapshot (additive evolution within v1 —
@@ -128,6 +130,35 @@ export interface FleetApproval {
   expiresMs: number
 }
 
+/** A live owner-facing notice as the snapshot exposes it (docs/19). The SAME items
+ *  `GET /fleet/v1/notices` returns (board.list()) — carried in the snapshot so a client that
+ *  already fetches `/snapshot` on every event renders the board with no extra call.
+ *
+ *  ONE-WAY: there is nothing to answer. A face RENDERS a notice; it never resolves one (no
+ *  approve/deny sibling exists on purpose — see docs/19 §1).
+ *
+ *  `resetsAtMs` is present ONLY when the runtime itself stated when the wall lifts (codex
+ *  does; claude does not for a per-model bucket). Its ABSENCE means "the runtime did not
+ *  say" — a client MUST render that as unknown and MUST NOT substitute the 5h/7d reset,
+ *  which belongs to a different limit. */
+export interface FleetNotice {
+  id: string
+  personality: string
+  runtime: string
+  kind: string
+  errorType: string
+  model?: string
+  resetsAtMs?: number
+  summary: string
+  content: string
+  sessionId?: string
+  createdMs: number
+  lastMs: number
+  expiresMs: number
+  /** Detections folded into this notice while it stayed live (≥1) — render as "×N". */
+  count: number
+}
+
 export interface FleetSnapshot {
   api: typeof FLEET_API_VERSION
   version: string
@@ -137,6 +168,9 @@ export interface FleetSnapshot {
   /** Pending human-approval requests (docs/17). ADDITIVE + omitted when the queue is empty —
    *  a client MUST treat its absence as an empty queue (same rule as `approval_mode`). */
   approvals?: FleetApproval[]
+  /** Live owner-facing notices (docs/19). ADDITIVE + omitted when the board is empty — a
+   *  client MUST treat its absence as an empty board (same rule as `approvals`). */
+  notices?: FleetNotice[]
 }
 
 // The CLI op functions, injectable for tests. Defaults LAZY-load cli/index.ts at
@@ -173,6 +207,7 @@ export function buildFleetSnapshot(
   startedAtMs: number,
   nowMs: number = Date.now(),
   approvals: FleetApproval[] = [],
+  notices: FleetNotice[] = [],
 ): FleetSnapshot {
   const peers: FleetPeer[] = ops.listPeers({ env }).map(r => {
     const runtimes: FleetRuntimeStatus[] = r.runtimes.map(s => {
@@ -233,6 +268,8 @@ export function buildFleetSnapshot(
     // superset of FleetApproval — the named fields are the contract; extras ride along and
     // clients ignore them (obligation 2).
     ...(approvals.length ? { approvals } : {}),
+    // Same rule for the notice board (docs/19).
+    ...(notices.length ? { notices } : {}),
   }
 }
 
@@ -255,6 +292,10 @@ export function fleetEventFiles(cfg: LifecycleConfig): Array<{ path: string; src
     // Human-approval broker events (docs/17): approval-request / approval-resolved.
     // A pre-approval daemon simply never writes this file (readLogTail tolerates absence).
     { path: approvalsLogPath(cfg.eventLogDir), src: 'approvals' },
+    // Notice-board events (docs/19): notice-raised. Tailing it here is the WHOLE push
+    // path — a face subscribed to /fleet/v1/events receives owner notices with no
+    // further wiring, exactly as it already receives approvals.
+    { path: noticesLogPath(cfg.eventLogDir), src: 'notices' },
   ]
 }
 
@@ -472,6 +513,10 @@ export interface FleetHandlerOptions {
   pollMs?: number
   /** Injectable approval broker (tests — e.g. a short timeout). Default: a fresh one. */
   broker?: ApprovalBroker
+  /** The notice board (docs/19). The composition point passes the SAME instance the
+   *  mute-watch raises into — that shared instance IS the wiring: the watch writes, this
+   *  handler reads. Default: a fresh one (a handler with no watch simply stays empty). */
+  board?: NoticeBoard
 }
 
 export type FleetHandler = (
@@ -494,6 +539,9 @@ export function buildFleetHandler(opts: FleetHandlerOptions = {}): FleetHandler
   // The approval broker — one per daemon; the ASK side (POST /approvals long-poll) and
   // the ANSWER side (GET/POST /approvals/*) are all interfaces to this one queue.
   const broker = opts.broker ?? new ApprovalBroker({ logDir: cfg.eventLogDir, env })
+  // The notice board — one per daemon; the mute-watch RAISES into it and the /notices reads
+  // below serve it. Same shape as the broker above: one in-memory store, many interfaces.
+  const board = opts.board ?? new NoticeBoard({ logDir: cfg.eventLogDir, env })
   let opsPromise: Promise<FleetOps> | undefined
   const getOps = (): Promise<FleetOps> => {
     if (opts.ops) return Promise.resolve(opts.ops)
@@ -511,7 +559,13 @@ export function buildFleetHandler(opts: FleetHandlerOptions = {}): FleetHandler
         if (method !== 'GET') return sendJson(res, 405, { error: 'method not allowed — GET /fleet/v1/snapshot' })
         // broker.list() is PendingApproval[] — structurally a superset of FleetApproval, so it
         // satisfies the snapshot contract (extra fields serialize + are ignored by clients).
-        return sendJson(res, 200, buildFleetSnapshot(env, cfg, await getOps(), startedAtMs, undefined, broker.list()))
+        // broker.list()/board.list() are supersets of FleetApproval/FleetNotice — the named
+        // fields are the contract; extras serialize and clients ignore them (obligation 2).
+        return sendJson(
+          res,
+          200,
+          buildFleetSnapshot(env, cfg, await getOps(), startedAtMs, undefined, broker.list(), board.list()),
+        )
       }
       if (path === '/fleet/v1/events') {
         if (method !== 'GET') return sendJson(res, 405, { error: 'method not allowed — GET /fleet/v1/events' })
@@ -647,6 +701,26 @@ export function buildFleetHandler(opts: FleetHandlerOptions = {}): FleetHandler
         if (!ok) return sendJson(res, 404, { error: `no pending approval "${id}" (already resolved, expired, or unknown)` })
         return sendJson(res, 200, { id, action, ok: true })
       }
+
+      // ── notices (docs/19) — READ-ONLY BY DESIGN ───────────────────────────
+      // No approve/deny sibling: a notice is one-way. Nothing is blocked on it and there
+      // is no decision to make, so there is nothing for a face to POST back.
+      if (path === '/fleet/v1/notices') {
+        if (method !== 'GET') return sendJson(res, 405, { error: 'method not allowed — GET /fleet/v1/notices' })
+        return sendJson(res, 200, {
+          api: FLEET_API_VERSION,
+          version: IAPEER_VERSION,
+          ts: new Date().toISOString(),
+          notices: board.list(),
+        })
+      }
+      const noticeMatch = /^\/fleet\/v1\/notices\/([^/]+)$/.exec(path)
+      if (noticeMatch) {
+        if (method !== 'GET') return sendJson(res, 405, { error: 'method not allowed — GET /fleet/v1/notices/<id>' })
+        const item = board.get(noticeMatch[1]!)
+        if (!item) return sendJson(res, 404, { error: `no live notice "${noticeMatch[1]}" (expired or unknown)` })
+        return sendJson(res, 200, { api: FLEET_API_VERSION, version: IAPEER_VERSION, ts: new Date().toISOString(), notice: item })
+      }
       return sendJson(res, 404, {
         error: `unknown fleet endpoint ${method} ${path}`,
         endpoints: [
@@ -659,6 +733,8 @@ export function buildFleetHandler(opts: FleetHandlerOptions = {}): FleetHandler
           'POST /fleet/v1/approvals (hook long-poll)',
           'GET /fleet/v1/approvals/<id>',
           'POST /fleet/v1/approvals/<id>/(approve|deny)',
+          'GET /fleet/v1/notices',
+          'GET /fleet/v1/notices/<id>',
         ],
       })
     } catch (e) {

package/src/daemon/main.ts

@@ -67,6 +67,8 @@ import {
 import { iapeerBinPath } from '../install/index.ts'
 import { appendDeliveryEvent } from './deliverylog.ts'
 import { buildFleetHandler } from './fleet.ts'
+import { NoticeBoard } from './notices.ts'
+import { startMuteWatch } from './mutewatch.ts'
 import { defaultDaemonSocketPath, startDaemon, type DaemonHandle } from './index.ts'
 
 /** Default TCP loopback port for the always-on router. Real http MCP clients
@@ -91,6 +93,13 @@ export function parseDaemonPort(raw: string | undefined, dflt: number = DEFAULT_
  *  is the reap threshold; this is just how often the timer checks. */
 export const DEFAULT_SUPERVISE_INTERVAL_MS = 60_000
 
+/** Mute-watch cadence (docs/19) — how often the daemon sweeps the runtimes' session files
+ *  for a structural API error that left a peer unable to answer. Its OWN timer rather than a
+ *  ride on the 60 s supervise tick: detection latency IS the product here (the owner must
+ *  learn within a minute), and a 60 s sweep puts the worst case AT the budget with nothing
+ *  to spare. The sweep is cheap — it stats only files that CHANGED since the last pass. */
+export const DEFAULT_MUTEWATCH_INTERVAL_MS = 20_000
+
 // This module's own path — the launchd plist runs `bun <this>` as the daemon.
 const DAEMON_MAIN_PATH = fileURLToPath(import.meta.url)
 
@@ -319,6 +328,8 @@ export interface ConfiguredDaemonOptions {
   /** H8 bearer token; falls back to env.IAPEER_BEARER_TOKEN. Off when neither set. */
   bearerToken?: string
   superviseIntervalMs?: number
+  /** Mute-watch sweep cadence (default DEFAULT_MUTEWATCH_INTERVAL_MS). */
+  muteWatchIntervalMs?: number
   /** Write the router.json discovery file (default true for production). */
   discovery?: boolean
   rootDir?: string
@@ -341,7 +352,24 @@ export async function startConfiguredDaemon(opts: ConfiguredDaemonOptions = {}):
   const armEphemeralOnDelivered = makeArmEphemeralOnDelivered(cfg)
   const ephemeral = makeEphemeralRouteDeps(cfg, env)
   const composerQueue = makeComposerQueueRouteDeps(cfg, env)
-  return startDaemon({
+  // Notice board (docs/19) — ONE instance shared by the mute-watch (raises) and the
+  // fleet handler (serves /notices + the snapshot field). Constructed HERE, at the
+  // composition point, because that sharing is the whole wiring.
+  const board = new NoticeBoard({ logDir: cfg.eventLogDir, env })
+  const stopMuteWatch = startMuteWatch(cfg, board, {
+    env,
+    intervalMs: opts.muteWatchIntervalMs ?? DEFAULT_MUTEWATCH_INTERVAL_MS,
+    // Same stance as the supervise tick's onError: a detector throw must be VISIBLE, not
+    // swallowed into a silently-dead watch — the exact failure mode this feature exists to
+    // end. Best-effort; a reporter must never fail the daemon.
+    onError: (err: unknown) => {
+      try {
+        const detail = err instanceof Error ? (err.stack ?? err.message) : String(err)
+        appendLifecycleEvent(cfg.eventLogDir, { ev: 'mutewatch-error', error: detail.replace(/\s+/g, ' ').slice(0, 600) }, { env })
+      } catch { /* best-effort */ }
+    },
+  })
+  const handle = await startDaemon({
     wake: makeWakeFn(cfg, env),
     // M2 arm-on-outbound (see makeArmEphemeralOnDelivered): ephemeral caller's ok
     // send ⇒ armed for the supervise quiet-reap. No-op for every other caller.
@@ -367,7 +395,7 @@ export async function startConfiguredDaemon(opts: ConfiguredDaemonOptions = {}):
     // (the same listPeers truth as `iapeer list`), SSE events (tail of the durable
     // logs), commands over the existing verb functions. Same listeners, same bearer
     // gate; advertised in router.json as fleet:1. Contract: docs/15-fleet-api.md.
-    fleet: buildFleetHandler({ env }),
+    fleet: buildFleetHandler({ env, board }),
     supervise: {
       intervalMs: opts.superviseIntervalMs ?? DEFAULT_SUPERVISE_INTERVAL_MS,
       // idle-reap / zombie-sweep, THEN the eager fresh re-launch for any peer whose
@@ -412,6 +440,10 @@ export async function startConfiguredDaemon(opts: ConfiguredDaemonOptions = {}):
     env,
     rootDir: opts.rootDir,
   })
+  // The mute-watch timer is OURS, not startDaemon's — so its teardown must hang off the
+  // handle we return, or a closed daemon would leave a live timer sweeping the disk (and
+  // every test that starts a daemon would hang on exit).
+  return { ...handle, close: async () => { stopMuteWatch(); await handle.close() } }
 }
 
 // ─────────────────────────────────────────────────────────────────────────────

package/src/daemon/mutewatch.ts

@@ -0,0 +1,441 @@
+// Mute-watch — the daemon's detector for the ONE class of failure that is invisible to
+// every health signal it has: a structural API error left a peer unable to answer (docs/19).
+//
+// WHY THIS EXISTS. When a model's limit is exhausted the peer's session does NOT die. Proven
+// live (15.07.2026, exhausted fable bucket): the banner paints, the composer paints, the
+// ready-gate would flip READY, the delivered turn is CONSUMED, the runtime paints its refusal,
+// and the session returns to the composer and lives on. The process is alive, there is no exit
+// code, and the statusline keeps re-rendering — which advances the pane-log mtime, so the
+// activity proxy reports the delivery CONFIRMED. Every daemon health signal is green and the
+// peer is mute. The owner writes and gets silence, with nothing anywhere saying why.
+// The exit code is no help either: `-p` (headless) exits 1 on a limit, but live peers are
+// never launched that way — an interactive session just sits there.
+//
+// WHERE THE TRUTH IS. Not the pane: the refusal is prose that line-wraps, and matching wrapped
+// ANSI is a losing game. Both runtimes write the fact STRUCTURALLY to their own session JSONL:
+//
+//   • claude → the transcript (~/.claude/projects/<slug>/<sessionId>.jsonl):
+//       isApiErrorMessage: true, error: "rate_limit", apiErrorStatus: 429,
+//       message.model: "<synthetic>" (a fabricated message, not a model reply).
+//     `error` is a locale-stable enum and the WHOLE CLASS rides it — rate_limit is one value;
+//     overloaded / expired auth arrive on the same field, which is why this detector keys on
+//     isApiErrorMessage and reports `error` verbatim instead of hunting one string.
+//     Claude does NOT state when a per-model bucket lifts ("Please try again later") → the
+//     notice omits the reset rather than extrapolating from the 5h/7d buckets (a DIFFERENT
+//     limit: measured live at 5h 11% / 7d 66% while fable was fully exhausted).
+//
+//   • codex → the rollout (~/.codex/sessions/YYYY/MM/DD/rollout-*.jsonl): an `event_msg` /
+//     `token_count` payload carries RateLimitSnapshot.rate_limit_reached_type — null while
+//     healthy, non-null once a wall is hit. We key on NON-NULL, never on the variant strings
+//     (`rate_limit_reached`, `workspace_owner_usage_limit_reached`, … — read out of the 0.144.1
+//     binary but never observed live here), so an unknown future variant still detects.
+//     Codex DOES carry resets_at per window → its notice states the reset time.
+//
+// PATHS ARE NEVER DERIVED FROM cwd. The obvious route — slugify the peer's registry cwd into
+// ~/.claude/projects/<slug> — is a trap: the slug mirrors the cwd STRING as the process was
+// launched, not the real path. This host carries BOTH `-Users-macmini-Projects-IAPeer` and
+// `-Users-macmini-Projects-iapeer` for ONE case-insensitive directory. So we go the other way:
+// scan the session files that CHANGED, read the cwd each file states about ITSELF (claude: the
+// `cwd` field on every line; codex: session_meta.payload.cwd), and match that against the
+// registry. A file whose cwd is no peer's is ignored — a human's own session never notifies.
+
+import { existsSync, openSync, closeSync, fstatSync, readSync, readdirSync, statSync } from 'node:fs'
+import { join } from 'node:path'
+import type { LifecycleConfig } from '../lifecycle/index.ts'
+import type { NoticeBoard } from './notices.ts'
+
+/** How much of a session file's tail is parsed. The evidence is always at the end. */
+const TAIL_BYTES = 256 * 1024
+/** Overlap added to the since-boundary so an event landing between two sweeps is never
+ *  missed. Re-detections are free: the board's dedup folds them into the live notice. */
+const SCAN_OVERLAP_MS = 15_000
+/** Walk depth for the codex YYYY/MM/DD tree (3 levels + the file). */
+const CODEX_WALK_DEPTH = 3
+
+export interface MuteDetection {
+  personality: string
+  runtime: 'claude' | 'codex'
+  /** The runtime's OWN taxonomy value — claude's `error`, codex's rate_limit_reached_type. */
+  errorType: string
+  model?: string
+  resetsAtMs?: number
+  /** Claude: the runtime's VERBATIM refusal. Codex: a line rendered from its typed fields
+   *  (the rollout carries no prose). Either way, never our interpretation of the cause. */
+  content: string
+  sessionId?: string
+  atMs: number
+  cwd: string
+}
+
+type RawDetection = Omit<MuteDetection, 'personality' | 'runtime'>
+
+// ─────────────────────────────────────────────────────────────────────────────
+// Pure parsers — string in, detection out (fs-free: tests need no temp tree)
+// ─────────────────────────────────────────────────────────────────────────────
+
+function toMs(ts: unknown): number | null {
+  if (typeof ts !== 'string') return null
+  const ms = Date.parse(ts)
+  return Number.isFinite(ms) ? ms : null
+}
+
+/** The model out of the runtime's own prose ("You've reached your Fable 5 limit"). Used ONLY
+ *  when the transcript carries no real model reply to read it from — a session that hits the
+ *  wall on its FIRST turn has no such line. Bounded and anchored; a miss → undefined (omit). */
+export function modelFromClaudeText(text: string): string | undefined {
+  const m = /reached your\s+(.{1,40}?)\s+limit/i.exec(text)
+  return m?.[1]?.trim() || undefined
+}
+
+/**
+ * The NEWEST structural API-error line in a claude transcript newer than `sinceMs`, or null.
+ * Keys on `isApiErrorMessage` — the class, not the `rate_limit` instance.
+ */
+export function parseClaudeTranscript(text: string, sinceMs: number): RawDetection | null {
+  let lastRealModel: string | undefined
+  let found: RawDetection | null = null
+  for (const line of text.split('\n')) {
+    const s = line.trim()
+    if (!s.startsWith('{')) continue // a partial first line from the tail cut — skip
+    let d: Record<string, unknown>
+    try {
+      d = JSON.parse(s) as Record<string, unknown>
+    } catch {
+      continue // truncated/garbled line — never fail the sweep over one bad line
+    }
+    const msg = d.message as { model?: unknown; content?: unknown } | undefined
+    // Track the last REAL model reply: the error line itself is "<synthetic>" and names no model.
+    if (msg && typeof msg.model === 'string' && msg.model && msg.model !== '<synthetic>') lastRealModel = msg.model
+    if (d.isApiErrorMessage !== true) continue
+    const atMs = toMs(d.timestamp)
+    if (atMs === null || atMs <= sinceMs) continue
+    const cwd = typeof d.cwd === 'string' ? d.cwd : ''
+    if (!cwd) continue // no cwd → unattributable to a peer; ignore rather than guess
+    const errorType = typeof d.error === 'string' && d.error.trim() ? d.error.trim() : 'api-error'
+    let content = ''
+    if (Array.isArray(msg?.content)) {
+      content = (msg.content as Array<{ type?: string; text?: string }>)
+        .filter(c => c?.type === 'text' && typeof c.text === 'string')
+        .map(c => c.text as string)
+        .join('\n')
+        .trim()
+    }
+    if (!content) content = `${errorType} (api error ${String(d.apiErrorStatus ?? '')})`.trim()
+    found = {
+      errorType,
+      model: lastRealModel ?? modelFromClaudeText(content),
+      content,
+      sessionId: typeof d.sessionId === 'string' ? d.sessionId : undefined,
+      atMs,
+      cwd,
+      // Claude states no reset for a per-model bucket → resetsAtMs deliberately absent.
+    }
+  }
+  return found
+}
+
+interface CodexWindow {
+  used_percent?: unknown
+  window_minutes?: unknown
+  resets_at?: unknown
+}
+
+/** Describe a codex window for the human-readable content line. */
+function describeWindow(name: string, w: CodexWindow): string | null {
+  if (!w || typeof w.used_percent !== 'number') return null
+  const win = typeof w.window_minutes === 'number' ? `${w.window_minutes}m window` : 'window'
+  const reset =
+    typeof w.resets_at === 'number' ? `, resets ${new Date(w.resets_at * 1000).toISOString()}` : ''
+  return `${name} ${w.used_percent}% (${win}${reset})`
+}
+
+/**
+ * The codex rollout's newest limit-reached snapshot newer than `sinceMs`, or null.
+ * Keys on `rate_limit_reached_type` being NON-NULL — never on its variant strings.
+ * `cwd` comes from session_meta, which is the file's FIRST line — pass the file HEAD in
+ * `head` when the tail alone may have cut it away.
+ */
+export function parseCodexRollout(text: string, sinceMs: number, head = ''): RawDetection | null {
+  let cwd = ''
+  let sessionId: string | undefined
+  const scanMeta = (src: string): void => {
+    for (const line of src.split('\n')) {
+      const s = line.trim()
+      if (!s.startsWith('{') || !s.includes('session_meta')) continue
+      try {
+        const d = JSON.parse(s) as { type?: string; payload?: { cwd?: unknown; session_id?: unknown } }
+        if (d.type !== 'session_meta' || !d.payload) continue
+        if (typeof d.payload.cwd === 'string') cwd = d.payload.cwd
+        if (typeof d.payload.session_id === 'string') sessionId = d.payload.session_id
+      } catch {
+        /* ignore */
+      }
+    }
+  }
+  scanMeta(head)
+  if (!cwd) scanMeta(text)
+  if (!cwd) return null // unattributable to a peer
+
+  let found: RawDetection | null = null
+  for (const line of text.split('\n')) {
+    const s = line.trim()
+    if (!s.startsWith('{') || !s.includes('rate_limits')) continue
+    let d: { timestamp?: unknown; type?: unknown; payload?: { type?: unknown; rate_limits?: Record<string, unknown> } }
+    try {
+      d = JSON.parse(s)
+    } catch {
+      continue
+    }
+    const rl = d.payload?.rate_limits
+    if (!rl) continue
+    const reached = rl.rate_limit_reached_type
+    // NON-NULL is the signal. An unknown future variant must still detect, so we never
+    // compare against the variant strings read out of the binary.
+    if (reached === null || reached === undefined || reached === '') continue
+    const atMs = toMs(d.timestamp)
+    if (atMs === null || atMs <= sinceMs) continue
+    const primary = (rl.primary ?? {}) as CodexWindow
+    const secondary = (rl.secondary ?? {}) as CodexWindow
+    // Which window is blocking? Codex does not say — reported for the FULLEST one, the
+    // only defensible read. This mapping is a HEURISTIC: it could not be verified against
+    // a real reached-snapshot (the quota never ran out on this host). Both windows ride in
+    // `content`, so the human sees the raw fact even if the heuristic picked wrong.
+    const pu = typeof primary.used_percent === 'number' ? primary.used_percent : -1
+    const su = typeof secondary.used_percent === 'number' ? secondary.used_percent : -1
+    const blocking = su > pu ? secondary : primary
+    const resetsAtMs = typeof blocking.resets_at === 'number' ? blocking.resets_at * 1000 : undefined
+    const parts = [describeWindow('primary', primary), describeWindow('secondary', secondary)].filter(Boolean)
+    const plan = typeof rl.plan_type === 'string' ? ` plan=${rl.plan_type}` : ''
+    found = {
+      errorType: String(reached),
+      content: `Codex usage limit reached (${String(reached)})${plan}${parts.length ? ` — ${parts.join('; ')}` : ''}`,
+      resetsAtMs,
+      sessionId,
+      atMs,
+      cwd,
+      // Codex names no model in the snapshot → model omitted rather than guessed.
+    }
+  }
+  return found
+}
+
+// ─────────────────────────────────────────────────────────────────────────────
+// The sweep — find changed session files, attribute them, raise notices
+// ─────────────────────────────────────────────────────────────────────────────
+
+function readTail(path: string, maxBytes = TAIL_BYTES): { tail: string; head: string } | null {
+  try {
+    const fd = openSync(path, 'r')
+    try {
+      const size = fstatSync(fd).size
+      if (size <= 0) return null
+      const off = Math.max(0, size - maxBytes)
+      const buf = Buffer.alloc(size - off)
+      readSync(fd, buf, 0, buf.length, off)
+      let head = ''
+      if (off > 0) {
+        // The tail cut away the file's start — read a HEAD slice too (codex session_meta
+        // is line 1, and a long session pushes it far out of the tail).
+        const hb = Buffer.alloc(Math.min(64 * 1024, off))
+        readSync(fd, hb, 0, hb.length, 0)
+        head = hb.toString('utf8')
+      }
+      return { tail: buf.toString('utf8'), head }
+    } finally {
+      closeSync(fd)
+    }
+  } catch {
+    return null
+  }
+}
+
+function safeReaddir(dir: string): string[] {
+  try {
+    return readdirSync(dir)
+  } catch {
+    return []
+  }
+}
+
+function mtimeMs(path: string): number | null {
+  try {
+    return statSync(path).mtimeMs
+  } catch {
+    return null
+  }
+}
+
+/** *.jsonl files under `root` (depth-bounded) whose mtime is at/after `sinceMs`. */
+function changedJsonl(root: string, sinceMs: number, depth: number): string[] {
+  if (!existsSync(root)) return []
+  const out: string[] = []
+  const walk = (dir: string, left: number): void => {
+    for (const name of safeReaddir(dir)) {
+      const p = join(dir, name)
+      if (name.endsWith('.jsonl')) {
+        const m = mtimeMs(p)
+        if (m !== null && m >= sinceMs) out.push(p)
+        continue
+      }
+      if (left <= 0 || name.startsWith('.')) continue
+      let isDir = false
+      try {
+        isDir = statSync(p).isDirectory()
+      } catch {
+        continue
+      }
+      if (isDir) walk(p, left - 1)
+    }
+  }
+  walk(root, depth)
+  return out
+}
+
+export interface MuteWatchPaths {
+  /** ~/.claude/projects — INJECTED, never re-resolved from env inside the sweep. */
+  claudeProjectsDir: string
+  /** ~/.codex/sessions — same rule. */
+  codexSessionsDir: string
+}
+
+export interface ScanDeps extends MuteWatchPaths {
+  /** personality ← cwd. Built from the registry by the composition point. */
+  peerByCwd: (cwd: string) => string | undefined
+}
+
+/**
+ * The runtime session-file roots. These are the RUNTIMES' own trees, not iapeer's, so they
+ * are not LifecycleConfig fields; the composition point resolves them ONCE and injects them
+ * (a sweep never re-resolves a path mid-run). The env overrides exist so a test points the
+ * sweep at a temp tree instead of the real ~/.claude — the sweep is READ-ONLY, and its only
+ * write (notices.log) goes through cfg.eventLogDir like every other daemon log.
+ */
+export function resolveMuteWatchPaths(env: NodeJS.ProcessEnv): MuteWatchPaths {
+  const home = env.HOME?.trim() || ''
+  return {
+    claudeProjectsDir: env.IAPEER_CLAUDE_PROJECTS_DIR?.trim() || join(home, '.claude', 'projects'),
+    codexSessionsDir: env.IAPEER_CODEX_SESSIONS_DIR?.trim() || join(home, '.codex', 'sessions'),
+  }
+}
+
+/** One sweep: every peer-attributable structural API error newer than `sinceMs`. */
+export function scanMuteEvents(deps: ScanDeps, sinceMs: number): MuteDetection[] {
+  const floor = sinceMs - SCAN_OVERLAP_MS
+  const out: MuteDetection[] = []
+  const push = (raw: RawDetection | null, runtime: 'claude' | 'codex'): void => {
+    if (!raw) return
+    const personality = deps.peerByCwd(raw.cwd)
+    if (!personality) return // not a peer's session (a human's own shell) — never notify
+    out.push({ ...raw, personality, runtime })
+  }
+  // claude: ~/.claude/projects/<slug>/<sessionId>.jsonl — one level of slug dirs.
+  for (const file of changedJsonl(deps.claudeProjectsDir, floor, 1)) {
+    const t = readTail(file)
+    if (t) push(parseClaudeTranscript(t.tail, floor), 'claude')
+  }
+  // codex: ~/.codex/sessions/YYYY/MM/DD/rollout-*.jsonl
+  for (const file of changedJsonl(deps.codexSessionsDir, floor, CODEX_WALK_DEPTH)) {
+    const t = readTail(file)
+    if (t) push(parseCodexRollout(t.tail, floor, t.head), 'codex')
+  }
+  return out
+}
+
+export interface MuteWatchDeps extends ScanDeps {
+  board: NoticeBoard
+  now?: () => number
+  /** Reported, never thrown — a detector must never take the daemon down. */
+  onError?: (err: unknown) => void
+}
+
+/**
+ * Run one watch tick: sweep, raise. Returns the notices actually RAISED (deduped repeats
+ * are folded by the board and not returned) plus the new since-boundary.
+ */
+export function muteWatchTick(deps: MuteWatchDeps, sinceMs: number): { raised: number; sinceMs: number } {
+  const now = deps.now ?? Date.now
+  const startedMs = now()
+  let raised = 0
+  try {
+    for (const d of scanMuteEvents(deps, sinceMs)) {
+      const { deduped } = deps.board.raise({
+        personality: d.personality,
+        runtime: d.runtime,
+        kind: 'peer-mute',
+        errorType: d.errorType,
+        model: d.model,
+        resetsAtMs: d.resetsAtMs,
+        content: d.content,
+        sessionId: d.sessionId,
+        // The runtime event's OWN timestamp — lets the board tell a new occurrence from the
+        // same line re-read by the deliberately-overlapping sweep window.
+        eventAtMs: d.atMs,
+        summary: `${d.personality} · ${d.runtime} — ${d.errorType}${d.model ? ` (${d.model})` : ''}`,
+      })
+      if (!deduped) raised += 1
+    }
+  } catch (e) {
+    deps.onError?.(e)
+  }
+  return { raised, sinceMs: startedMs }
+}
+
+export interface StartMuteWatchOptions {
+  env?: NodeJS.ProcessEnv
+  intervalMs?: number
+  /** Override the runtime session roots (tests). Default: resolveMuteWatchPaths(env). */
+  paths?: MuteWatchPaths
+  /** Override the registry read (tests). Default: a lazy import of the CLI's listPeers. */
+  listPeers?: () => Array<{ personality: string; cwd: string }>
+  now?: () => number
+  onError?: (err: unknown) => void
+}
+
+/**
+ * Start the mute-watch timer. Returns its stop function — the caller OWNS teardown.
+ *
+ * The registry is re-read every sweep (a peer created since daemon start must be watched
+ * without a restart), and `listPeers` is imported LAZILY at first use, mirroring fleet.ts:
+ * daemon → cli is not a load-time dependency in this codebase.
+ */
+export function startMuteWatch(cfg: LifecycleConfig, board: NoticeBoard, opts: StartMuteWatchOptions = {}): () => void {
+  const env = opts.env ?? process.env
+  const paths = opts.paths ?? resolveMuteWatchPaths(env)
+  const now = opts.now ?? Date.now
+  let listPeers = opts.listPeers
+  let since = now()
+  let running = false
+
+  const sweep = async (): Promise<void> => {
+    if (running) return // a slow sweep must never overlap itself into a stampede
+    running = true
+    try {
+      if (!listPeers) {
+        const cli = await import('../cli/index.ts')
+        listPeers = () => cli.listPeers({ env }).map(p => ({ personality: p.personality, cwd: p.cwd }))
+      }
+      const rows = listPeers()
+      // cwd → personality. Compared case-insensitively: macOS paths are case-insensitive and
+      // the runtimes record the cwd STRING as launched, which is not always the registry's
+      // capitalization (the same trap that rules out deriving the transcript dir from cwd).
+      const byCwd = new Map<string, string>()
+      for (const r of rows) if (r.cwd) byCwd.set(r.cwd.replace(/\/+$/, '').toLowerCase(), r.personality)
+      const deps: MuteWatchDeps = {
+        ...paths,
+        board,
+        now,
+        onError: opts.onError,
+        peerByCwd: (cwd: string) => byCwd.get(cwd.replace(/\/+$/, '').toLowerCase()),
+      }
+      since = muteWatchTick(deps, since).sinceMs
+    } catch (e) {
+      opts.onError?.(e)
+    } finally {
+      running = false
+    }
+  }
+
+  const timer = setInterval(() => void sweep(), opts.intervalMs ?? 20_000)
+  ;(timer as { unref?: () => void }).unref?.()
+  return () => clearInterval(timer)
+}

package/src/daemon/notices.ts

@@ -0,0 +1,208 @@
+// Notice board — the in-daemon store of OWNER-FACING notices (docs/19). The daemon
+// noticed something the owner must know about a peer, and no one else can tell him: the
+// canonical case is a peer left MUTE by a structural API error (rate limit, overload,
+// expired auth) — such a peer cannot report its own failure, and an Implementer peer has
+// no telegram face of its own. So the notice travels the daemon's OWN surface, exactly as
+// an approval request does.
+//
+// DELIBERATELY NOT AN APPROVAL. An approval is request → decision → unblock: a caller
+// long-polls and something is BLOCKED until a human answers. A notice is one-way: nobody
+// waits, nothing unblocks, there is no decision to make. Reusing the approval broker here
+// would drag a promise/timeout/fail-safe-deny machine into a problem that has none of
+// those. What IS shared is the SURFACE: a durable log tailed into the fleet SSE stream, an
+// additive snapshot field, and a GET endpoint for the verbatim content.
+//
+// TTL + DEDUP, and the two are ONE mechanism. A mute peer re-emits its error on EVERY
+// attempted turn — a naive board would raise a card per attempt and bury the owner. So a
+// notice carries a `dedupKey` (peer + runtime + kind + errorType + model): while a notice
+// with that key is LIVE, a repeat detection only bumps `count`/`lastMs` — no new id, no new
+// log line, no new SSE event. The owner sees one card that says "×7", not seven cards.
+// When it expires (TTL) and the peer is STILL broken, the next detection raises a fresh
+// notice — a deliberate periodic reminder rather than one card that scrolls away forever.
+//
+// In-memory + ephemeral: notices do NOT survive a daemon restart (a restart re-detects
+// within one watch tick — the transcript evidence is on disk and is re-read). The durable
+// notices.log is the audit/observability trace, not a recovery store.
+
+import { appendNoticeEvent } from './noticeslog.ts'
+
+/** v1 taxonomy of notices. `peer-mute` = a structural API error left the peer unable to
+ *  answer. Free-form-tolerant — new kinds ride the same surface without a client change. */
+export type NoticeKind = 'peer-mute' | string
+
+export interface NoticeInput {
+  personality: string
+  runtime: string
+  /** Taxonomy tag (peer-mute | …). */
+  kind: NoticeKind
+  /** The runtime's OWN error taxonomy value — `rate_limit`, `overloaded`, … Never
+   *  invented by us: it is the structural field the runtime wrote (docs/19 §2). */
+  errorType: string
+  /** The model that hit the wall, when the runtime says which (claude names it only in
+   *  prose; codex does not name it at all). ABSENT rather than guessed. */
+  model?: string
+  /** When the limit lifts, epoch-ms — ONLY when the runtime states it. Claude does not
+   *  for a per-model bucket ("try again later"), so this is absent there: an honest
+   *  omission, never an extrapolation from the 5h/7d buckets (a DIFFERENT limit). */
+  resetsAtMs?: number
+  /** One-line summary for the SSE event / badge. */
+  summary?: string
+  /** The runtime's VERBATIM message — shown to the human in every face. */
+  content: string
+  /** The session that hit it (correlation with the transcript on disk). */
+  sessionId?: string
+  /** When the underlying runtime event happened (the transcript line's own timestamp) —
+   *  NOT when we swept. This is what makes `count` mean OCCURRENCES rather than sweeps:
+   *  the sweep window deliberately overlaps, so the same line is re-read across passes.
+   *  Absent → every raise counts (the caller has no event clock to dedup against). */
+  eventAtMs?: number
+}
+
+export interface Notice extends NoticeInput {
+  id: string
+  summary: string
+  dedupKey: string
+  /** First occurrence. */
+  createdMs: number
+  /** Latest OCCURRENCE (not the latest sweep that re-read it). */
+  lastMs: number
+  expiresMs: number
+  /** Distinct occurrences folded into this notice (≥1) — how many times the peer actually
+   *  hit the wall, which is what "×N" claims to the owner. */
+  count: number
+  /** The newest event timestamp already counted — the overlap discriminator. */
+  lastEventMs?: number
+}
+
+export interface NoticeBoardOptions {
+  /** cfg.eventLogDir — notices.log lives here (falsy → no durable log, hermetic). */
+  logDir?: string
+  env?: NodeJS.ProcessEnv
+  /** How long a notice stays live, and therefore how long the same condition is deduped.
+   *  Default IAPEER_NOTICE_TTL_MS or 1 h. */
+  ttlMs?: number
+  /** Injectable clock (tests). Default Date.now. */
+  now?: () => number
+}
+
+const DEFAULT_TTL_MS = 3_600_000
+
+function envPosInt(raw: string | undefined, dflt: number): number {
+  const n = parseInt(raw ?? '', 10)
+  return Number.isFinite(n) && n > 0 ? n : dflt
+}
+
+function firstLine(s: string): string {
+  const nl = s.indexOf('\n')
+  return (nl >= 0 ? s.slice(0, nl) : s).trim()
+}
+
+/** The dedup identity of a condition: the same peer hitting the same wall on the same
+ *  runtime with the same model. Model is part of the key on purpose — a peer that falls
+ *  back from one model to another and hits ITS limit too is a NEW fact for the owner. */
+export function noticeDedupKey(input: Pick<NoticeInput, 'personality' | 'runtime' | 'kind' | 'errorType' | 'model'>): string {
+  return [input.personality, input.runtime, input.kind, input.errorType, input.model ?? ''].join('|')
+}
+
+export class NoticeBoard {
+  private readonly live = new Map<string, Notice>()
+  private counter = 0
+  private readonly logDir?: string
+  private readonly env: NodeJS.ProcessEnv
+  private readonly ttlMs: number
+  private readonly now: () => number
+
+  constructor(opts: NoticeBoardOptions = {}) {
+    this.logDir = opts.logDir
+    this.env = opts.env ?? process.env
+    this.ttlMs = opts.ttlMs ?? envPosInt(this.env.IAPEER_NOTICE_TTL_MS, DEFAULT_TTL_MS)
+    this.now = opts.now ?? Date.now
+  }
+
+  /**
+   * Raise a notice, or fold it into the live one with the same dedupKey.
+   * Returns the notice and whether this call DEDUPED (folded) rather than raised. A
+   * folded call is deliberately silent: no id, no log line, no SSE event — only
+   * `count`/`lastMs` move (see the dedup note in the module header).
+   */
+  raise(input: NoticeInput): { notice: Notice; deduped: boolean } {
+    const nowMs = this.now()
+    this.prune(nowMs)
+    const dedupKey = noticeDedupKey(input)
+    const existing = this.live.get(dedupKey)
+    if (existing) {
+      // Same condition. Is this a NEW occurrence, or the same runtime event re-read by an
+      // overlapping sweep? Counting the latter would inflate "×N" into a claim the owner
+      // cannot check — 2 real refusals rendering as ×3. Only a strictly newer event counts.
+      const at = input.eventAtMs
+      const isNewOccurrence = at === undefined || existing.lastEventMs === undefined || at > existing.lastEventMs
+      if (isNewOccurrence) {
+        existing.count += 1
+        existing.lastMs = nowMs
+        if (at !== undefined) existing.lastEventMs = at
+      }
+      return { notice: existing, deduped: true }
+    }
+    const id = `n${++this.counter}`
+    const summary = (input.summary?.trim() || firstLine(input.content) || input.errorType).slice(0, 240)
+    const notice: Notice = {
+      ...input,
+      id,
+      summary,
+      dedupKey,
+      createdMs: nowMs,
+      lastMs: nowMs,
+      expiresMs: nowMs + this.ttlMs,
+      count: 1,
+      lastEventMs: input.eventAtMs,
+    }
+    this.live.set(dedupKey, notice)
+    appendNoticeEvent(
+      this.logDir,
+      {
+        ev: 'notice-raised',
+        id,
+        personality: input.personality,
+        runtime: input.runtime,
+        kind: input.kind,
+        error_type: input.errorType,
+        model: input.model,
+        // Emit the reset as BOTH epoch-ms and a readable stamp, or omit entirely.
+        // A reader must never have to guess whether "unknown" means "no limit" or
+        // "we didn't look" — an absent field means the runtime did not state it.
+        resets_at: input.resetsAtMs,
+        resets_at_iso: input.resetsAtMs ? new Date(input.resetsAtMs).toISOString() : undefined,
+        session: input.sessionId,
+        summary,
+        created: nowMs,
+        expires: notice.expiresMs,
+      },
+      { env: this.env, nowMs },
+    )
+    return { notice, deduped: false }
+  }
+
+  /** All live notices, oldest first (GET /fleet/v1/notices + the snapshot field). */
+  list(nowMs: number = this.now()): Notice[] {
+    this.prune(nowMs)
+    return [...this.live.values()].sort((a, b) => a.createdMs - b.createdMs)
+  }
+
+  /** One live notice by id (GET /fleet/v1/notices/<id> — full verbatim content). */
+  get(id: string, nowMs: number = this.now()): Notice | undefined {
+    this.prune(nowMs)
+    return [...this.live.values()].find(n => n.id === id)
+  }
+
+  /** Live count (badge/metrics). */
+  size(nowMs: number = this.now()): number {
+    this.prune(nowMs)
+    return this.live.size
+  }
+
+  /** Drop expired notices. Silent by design: an expiry is not news — either the peer
+   *  recovered (nothing to say) or it is still broken and the next detection re-raises. */
+  prune(nowMs: number = this.now()): void {
+    for (const [key, n] of this.live) if (n.expiresMs <= nowMs) this.live.delete(key)
+  }
+}

package/src/daemon/noticeslog.ts

@@ -0,0 +1,54 @@
+// Notice-board durable log — the daemon's DURABLE trace of every owner-facing notice it
+// raises (docs/19). Sibling to lifecycle.log / delivery.log / exits.log / approvals.log
+// under cfg.eventLogDir; tailed by the fleet-API SSE stream (fleetEventFiles), so the
+// `notice-raised` event reaches every operator client (tray, telegram, web) with
+// at-least-once semantics — and a postmortem can reconstruct which peer went mute, why,
+// and when, after the in-memory board is gone.
+//
+// What is logged: notice METADATA + a one-line `summary` — NOT the full verbatim runtime
+// message (`content`), which can be multi-line. The full content lives in the in-memory
+// board and is served by GET /fleet/v1/notices/<id>; the log carries enough to correlate
+// + render a badge/line.
+//
+// Same rotation class as its siblings: written by OUR code → self-rotates via the shared
+// storage/rotatelog primitive. The dir is passed IN by the composition point, never
+// re-resolved from env — a falsy dir → no-op (library/test daemons stay hermetic).
+
+import { join } from 'path'
+import { DEFAULT_LOG_KEEP, DEFAULT_LOG_MAX_BYTES, appendRotatedEvent } from '../storage/rotatelog.ts'
+
+/** The notice-board log inside `logDir` (sibling to approvals.log). */
+export function noticesLogPath(logDir: string): string {
+  return join(logDir, 'notices.log')
+}
+
+function envPosInt(raw: string | undefined, dflt: number): number {
+  const n = parseInt(raw ?? '', 10)
+  return Number.isFinite(n) && n > 0 ? n : dflt
+}
+
+export interface AppendNoticeOptions {
+  /** Reads the rotation knobs IAPEER_NOTICES_LOG_MAX_BYTES / _KEEP. */
+  env?: NodeJS.ProcessEnv
+  /** Stamp the line with this epoch-ms. Default Date.now(). */
+  nowMs?: number
+}
+
+/**
+ * Append one notice event line into `logDir`/notices.log. A falsy `logDir` is a no-op
+ * (the default for library/test daemons). Fully best-effort — never throws; logging must
+ * never fail a detection sweep.
+ */
+export function appendNoticeEvent(
+  logDir: string | undefined,
+  fields: Record<string, string | number | undefined>,
+  opts: AppendNoticeOptions = {},
+): void {
+  if (!logDir) return
+  const env = opts.env ?? process.env
+  appendRotatedEvent(noticesLogPath(logDir), fields, {
+    nowMs: opts.nowMs,
+    maxBytes: envPosInt(env.IAPEER_NOTICES_LOG_MAX_BYTES, DEFAULT_LOG_MAX_BYTES),
+    keep: envPosInt(env.IAPEER_NOTICES_LOG_KEEP, DEFAULT_LOG_KEEP),
+  })
+}