@agfpd/iapeer 0.4.91 → 0.4.93

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,195 @@
+# 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 detection |
+| `lastMs` | number | most recent detection folded in |
+| `expiresMs` | number | TTL boundary |
+| `count` | number | detections folded into this notice (≥1) — render as `×N` |
+
+### 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.
+
+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.91",
+  "version": "0.4.93",
   "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/approval/brokerClient.ts

@@ -57,6 +57,10 @@ export interface RequestApprovalDeps {
   fetch?: typeof fetch
   /** Injectable client timeout (tests). */
   timeoutMs?: number
+  /** External cancel: aborting this signal aborts the long-poll fetch (the daemon sees the requester
+   *  transport close and settles the pending request cancel/default-deny, clearing it from every
+   *  face). The supervisor uses it to close a request whose modal disappeared before a decision. */
+  signal?: AbortSignal
 }
 
 /**
@@ -73,6 +77,11 @@ export async function requestApproval(base: string, body: ApprovalRequestBody, d
   const controller = new AbortController()
   const timer = setTimeout(() => controller.abort(), timeoutMs)
   ;(timer as { unref?: () => void }).unref?.()
+  const onExternalAbort = (): void => controller.abort()
+  if (deps.signal) {
+    if (deps.signal.aborted) controller.abort()
+    else deps.signal.addEventListener('abort', onExternalAbort, { once: true })
+  }
   try {
     const headers: Record<string, string> = { 'content-type': 'application/json' }
     const bearer = env.IAPEER_BEARER_TOKEN?.trim()
@@ -88,5 +97,6 @@ export async function requestApproval(base: string, body: ApprovalRequestBody, d
     return data.decision === 'allow' ? { decision: 'allow' } : { decision: 'deny', reason: data.reason || 'denied' }
   } finally {
     clearTimeout(timer)
+    deps.signal?.removeEventListener('abort', onExternalAbort)
   }
 }

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() } }
 }
 
 // ─────────────────────────────────────────────────────────────────────────────