@agfpd/iapeer 0.4.94 → 0.4.96

package/docs/17-approval.md

@@ -146,3 +146,65 @@ The approval surface is served on both daemon listeners under `/fleet/v1`, same
 ## Compatibility
 
 Additive within `/fleet/v1` (docs/15): the `approval-*` endpoints and `ev` kinds grow the surface without a version bump. A pre-approval daemon simply omits `approval_mode` from the snapshot and serves no `/approvals` endpoints; a client feature-detects by the presence of the field / a `200` from `GET /fleet/v1/approvals`.
+
+## What an EMPTY broker does and does not mean
+
+Diagnosed live on 15.07.2026 after an owner-visible false alarm; recorded here because the
+misreading is natural and cost three people an incident.
+
+**An empty `/fleet/v1/approvals` is the NORMAL state of a yolo fleet, not a symptom.** In
+`yolo` the supervisor auto-presses Yes for the known classes (`dangerous-rm`,
+`command-approval`) and the broker is deliberately uninvolved — there is no human decision to
+route, so `approvals.log` correctly stays silent. Only `gated` peers ever reach the broker.
+
+**A circuit breaker fires even under `--dangerously-skip-permissions`** — that is what makes it
+a breaker. Seeing a modal on a bypassed peer is not evidence that the bypass failed. The live
+sample: `Dangerous rm operation on working directory or its ancestor: /tmp/codex-probe` on a
+peer launched with the bypass flag; the supervisor auto-confirmed 11 s later (nag-poll
+cadence) and the tool completed 180 ms after that. Nothing hung, nothing leaked.
+
+A useful narrowing when diagnosing one of these: under `bypassPermissions` the permission
+engine auto-allows **every** `ask` decision except reasons beginning `Dangerous rm operation` /
+`Dangerous rmdir operation` (established from the 2.1.201 engine). So a live modal on a
+bypassed peer is almost certainly that one class — the "the bypass broke" hypothesis can be
+dropped before investigating it.
+
+**The yolo auto-confirm IS audited, but only off-surface — and that is DECIDED, not pending.**
+The supervisor writes `[supervisor] AUTO-CONFIRM <taxonomy> identity=<id> ts=<…> <detail>` to
+its own stderr log (`~/.iapeer/state/supervisor/<identity>.log`). That line is **not** in
+`approvals.log`, **not** in the Fleet API, **not** in the SSE stream, and therefore invisible to
+tray / telegram / web. Measured frequency: 9 auto-confirms across 10 days over the whole real
+fleet (8 `dangerous-rm`, 1 `command-approval`).
+
+> **Decision (owner, 15.07.2026): auto-confirms are NOT surfaced as notices.** Proposed after a
+> destructive auto-approval proved invisible to every operator surface; considered, rejected.
+> Rationale: `yolo` **means** silent auto-confirmation — the owner chose it explicitly to stop
+> being asked, so a card per auto-confirm would be precisely the noise he opted out of. Even the
+> narrow variant (destructive class only, post-hoc, one-way) was declined. The audit stays in the
+> supervisor log.
+>
+> **The honest boundary of that decision, accepted knowingly:** observability of auto-confirms
+> lives ONLY in `~/.iapeer/state/supervisor/<identity>.log`. You must know that file exists and
+> that there is a reason to grep it. This is not a defect — it is the price of `yolo`, chosen
+> deliberately. Re-proposing "let's just show them" re-opens a settled question: the counter-
+> argument is above, and the frequency number is the reason it does not accumulate.
+
+**The runtime's OWN notifications are outside this contour.** Claude Code pushes a native
+"Claude needs your permission: Bash …" notification to the owner's phone when a modal appears —
+including modals this contour auto-resolves seconds later. It is not ours (no `Notification`
+hook exists in any settings here), we do not control it, and it is indistinguishable from a
+real approval request. An owner-visible push therefore does NOT imply the broker saw anything.
+Whether `preferredNotifChannel` (a real Claude Code setting) can silence this class is
+**unverified**.
+
+## Known unverified area: modals from a child runtime process
+
+A peer's turn can spawn its own `claude` / `codex` child process (e.g. `claude -p …` inside a
+Bash call). Such a child does **not** carry the peer's launch flags and its modal does **not**
+render in the peer's pane — so the supervisor's nag-watch, the breaker path and the broker are
+all structurally blind to it.
+
+This is **not known to be a problem and not known to be safe: it has never been tested.** It is
+recorded here so nobody later concludes the contour covers it. The scenario is real — it
+occurred on this host on 15.07 during live acceptance (`claude --model fable -p ping` fired
+from a peer's turn). Worth probing when there is a reason; not measured to date.

package/docs/19-notices.md

@@ -117,8 +117,8 @@ resets, the plan) — data, never our interpretation of the cause.
 | `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) |
+| `createdMs` | number | when the notice was raised (board clock — the TTL anchor) |
+| `lastMs` | number | when the latest occurrence was folded in (board clock). A sweep that merely re-reads an already-counted event does not move 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. |
 
@@ -148,6 +148,40 @@ ignore unknown `ev` kinds as always.
 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.
+6. **On startup, seed the board SILENTLY.** Whatever is already live when your face comes up
+   is history: mark it seen and deliver none of it. Deliver only notices raised *while you
+   were running* — i.e. whose `createdMs` is later than your own start.
+
+#### Why obligation 6 exists, and what it costs
+
+A notice is one-way: nobody is waiting on it, nothing unblocks. So a face restart is an event
+in the **face's** life, not news about the fleet — and re-announcing the live board because
+*you* redeployed tells the owner nothing he did not already know. It is your deploy, buzzing
+his phone.
+
+This is not hypothetical: on 15.07.2026 a telegram-runtime deploy re-delivered all five live
+cards; the web-runtime, from the same board and the same version of this document, seeded
+silently. Neither face was wrong — **the contract was silent, so each guessed, and they
+guessed differently.** That is what this obligation ends.
+
+**The cost, named:** a notice raised while your face was DOWN is never delivered by you.
+Accepted, because it is bounded and self-healing:
+
+- if the peer recovered during your downtime, the notice was moot — there was nothing to act on;
+- if the peer is **still** broken, the board re-raises a FRESH notice when the TTL expires
+  (§5). Its `createdMs` is then later than your start, so you deliver it. The worst case is a
+  delay of one TTL, not a permanent loss.
+
+**Approvals are the OPPOSITE — do not copy this rule across (docs/17).** A pending approval
+has a human on the other end and a ≤300 s default-deny deadline: a face that starts up and
+stays quiet about it lets the request time out into a denial. So approvals *are* delivered on
+startup. The discriminator is not which surface you are, it is **whether anything is blocked
+waiting on a human**. Notices block nothing; approvals block a peer's tool call.
+
+**Implementation:** record your start time at boot and compare `createdMs`. No persisted
+seen-set is needed, and it stays correct across a daemon restart — a restarted daemon
+re-detects from the on-disk evidence and stamps newer `createdMs`, so genuinely current
+conditions are delivered rather than suppressed.
 
 ## 5. Dedup and TTL — one mechanism
 
@@ -176,13 +210,23 @@ The daemon sweeps on its own timer (`DEFAULT_MUTEWATCH_INTERVAL_MS`, 20 s — de
 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.
+Attribution does not derive the path from `cwd`. It reads the cwd each file states **about
+itself** (claude: the `cwd` field on every line; codex: `session_meta.payload.cwd`) and matches
+it against the registry, case-insensitively. A file whose cwd belongs to no peer is ignored —
+a human's own session never notifies.
+
+The reason is that one rule must serve both runtimes: the claude slug is a naming convention we
+do not own, and a codex rollout carries no cwd in its path at all (`YYYY/MM/DD/rollout-*`), so
+there is nothing to derive from. Reading the file's own statement works for both.
+
+> **Correction (15.07.2026).** This section previously justified the choice by claiming the host
+> carries BOTH `-Users-macmini-Projects-IAPeer` and `-Users-macmini-Projects-iapeer` as two
+> directories for one case-insensitive path. **That was false.** `readdir` lists exactly one
+> (`…-IAPeer`), and both spellings `stat` to the same inode — the filesystem is case-insensitive,
+> so a slug of differing case resolves correctly, and the confirm path in `transport` derives its
+> slug this way and works. The claim came from reading a `grep -c` result of 2 whose second hit was
+> `…-Projects-iapeer-memory`: a count was trusted instead of the entries. The design choice is
+> unchanged; its stated reason is.
 
 ## 7. What is proven, and what is not
 
@@ -199,3 +243,45 @@ ignored — a human's own session never notifies.
   raw fact even if the heuristic picks wrong.
 
 Forensic evidence for all of the above: `docs/internals/forensics/model-limit-2026-07-15/`.
+
+## 8. Known hole: codex generic API errors — measured, not assumed
+
+**A codex peer left mute by anything other than a rate limit is not detected.** Its
+rate-limit path — the actual incident class — IS covered by `rate_limit_reached_type`. Mute
+from overload or an expired auth is not.
+
+This is a property of codex, not an omission here. Measured on 15.07.2026:
+
+- **A real 429 leaves no trace in the rollout.** An isolated codex (`CODEX_HOME` on a temp
+  tree, a custom `model_provider` pointed at a local endpoint — the live fleet untouched) was
+  fault-injected with a genuine HTTP 429. Codex's OWN retry and error path ran and the turn
+  died: `ERROR: exceeded retry limit, last status: 429 Too Many Requests`. Its rollout
+  contains: `session_meta`, `task_started`, three `response_item/message`, `world_state`,
+  `turn_context`, `user_message`, `task_complete`. **Zero error items.**
+- **Worse: the rollout affirmatively says the turn SUCCEEDED.** It records
+  `task_complete { last_agent_message: null }` for the turn that just died on a 429. The
+  rollout is not merely silent about the failure — for this purpose it is wrong.
+- **Corroborated across real history**: 43 real rollouts, ~6147 `token_count` events, zero
+  error events of any kind; `TurnAbortedReason`'s variants (`interrupted`, `review_ended`,
+  `budget_limited`, `other`) contain no API-error member; codex's own `logs_2.sqlite` holds
+  exactly one ERROR row, unrelated (a model-refresh timeout).
+
+So codex's only structural error surface is the `rate_limits` snapshot this detector already
+reads. The claude/codex asymmetry in §2 is that fact, not a shortcut.
+
+**Rejected, deliberately:** `task_complete` with `last_agent_message: null` is the only tell
+that the turn failed — and it is an **absence, not a signal**. A detector on it would fire on
+every turn that legitimately produced no agent message. Inferring "mute" from it would be the
+exact plausible-inference defect this whole note exists to prevent; it is not built.
+
+**Not answered:** whether `stream_error` — a real serde variant of codex's `EventMsg`, next to
+`deprecation_notice` and `patch_apply_begin` — is persisted to the rollout. Codex filters
+which `event_msg` kinds land there (`patch_apply_end` does, `patch_apply_begin` does not), and
+it has never appeared in any rollout here. A mid-stream-break probe was run; codex retries a
+broken stream with a long backoff and did not terminate inside the time box. **This is left
+unanswered rather than inferred from the 429 result.**
+
+**Caveat on the measurement:** the probe drove a custom `model_provider`. The real ChatGPT
+provider path could in principle record something this one did not.
+
+Artifacts (rollout, injector, config): `docs/internals/forensics/model-limit-2026-07-15/`.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@agfpd/iapeer",
-  "version": "0.4.94",
+  "version": "0.4.96",
   "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/mutewatch.ts

@@ -31,12 +31,18 @@
 //     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
+// PATHS ARE NOT DERIVED FROM cwd — but NOT for the reason first claimed here. The original note
+// said this host carries BOTH `-Users-macmini-Projects-IAPeer` and `-Users-macmini-Projects-iapeer`
+// as two directories. That was FALSE, and measured to be false on 15.07: readdir lists exactly one
+// (`…-IAPeer`), and both spellings stat to the SAME inode — the filesystem is case-insensitive, so
+// a slug whose case differs from the on-disk name resolves fine. (The claim came from a grep -c of
+// 2, whose second hit was `…-Projects-iapeer-memory`. The count was read instead of the entries.)
+//
+// The real reason stands on its own: the slug mirrors the cwd STRING as the process was launched,
+// which is a claude-specific naming convention we do not own, and codex has no cwd in its path at
+// all (YYYY/MM/DD/rollout-*). One attribution rule that works for both runtimes beats two derivation
+// schemes: 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'

package/src/daemon/notices.ts

@@ -62,9 +62,11 @@ export interface Notice extends NoticeInput {
   id: string
   summary: string
   dedupKey: string
-  /** First occurrence. */
+  /** When the notice was raised (board clock — the TTL anchor, hence not the event's own
+   *  timestamp: expiry must be measured from when the owner could first see it). */
   createdMs: number
-  /** Latest OCCURRENCE (not the latest sweep that re-read it). */
+  /** When the latest OCCURRENCE was folded in (board clock). A sweep that merely re-reads an
+   *  already-counted event does NOT move it — only a genuinely new occurrence does. */
   lastMs: number
   expiresMs: number
   /** Distinct occurrences folded into this notice (≥1) — how many times the peer actually

package/src/transport/index.ts

@@ -182,11 +182,40 @@ const LIVENESS_POLL_MS = 100
 // `IAP_HOST_LIVENESS_GRACE_MS` overrides (operator calibration; tests set 0 for an immediate
 // deterministic fail). Prefer a false-FAIL (sender retries) over a false-OK (silent loss, forbidden).
 const CONFIRM_GRACE_MS = 4000
-function confirmGraceMs(): number {
-  const raw = process.env.IAP_HOST_LIVENESS_GRACE_MS
+
+// ATTACHMENT grace. The "sub-second" assumption above holds only WITHOUT attachments. Measured
+// 15.07.2026 on a live att=4 delivery (1.3 MB of PNGs) into an IDLE receiver: the record was
+// stamped 19:34:59.269, the confirm polled the right file until 19:35:03.4 and did not see it,
+// and the receiver's first output came at 19:35:21.7. The receiver writes the user-record when it
+// BEGINS the turn, and loading/encoding the images pushed that start ~22 s out — so a 4 s grace
+// expired on a message that had landed. Every att>0 delivery to a claude receiver false-FAILED,
+// the sender retried on the lie, and the message duplicated in the receiver's context.
+//
+// 60 s is a CONSERVATIVE BOUND FROM THAT MEASUREMENT (≤22 s observed, ×3 headroom), not a
+// calibrated number: the exact paste→disk latency is still unmeasured (see docs/10). It costs
+// nothing on the happy path — the confirm returns the moment the record lands — and costs the
+// sender up to a minute only when an attachment message genuinely fails, which is rare.
+const CONFIRM_GRACE_ATTACHMENTS_MS = 60_000
+
+function envNonNegative(raw: string | undefined): number | null {
   const n = raw === undefined ? NaN : Number(raw)
-  if (Number.isFinite(n) && n >= 0) return n
-  return CONFIRM_GRACE_MS
+  return Number.isFinite(n) && n >= 0 ? n : null
+}
+
+/** Does this envelope carry attachments — i.e. will the receiver have to ingest files before it
+ *  records anything? Same marker `confirmNeedles` splits on, so the two cannot disagree. */
+export function envelopeHasAttachments(envelope: string): boolean {
+  return envelope.includes('<attachments>') && envelope.includes('</attachments>')
+}
+
+function confirmGraceMs(hasAttachments: boolean): number {
+  // An EXPLICIT operator/test override wins for both modes — tests set 0 for a deterministic
+  // immediate fail, and an operator calibrating one number must not be silently overridden by
+  // the attachment branch.
+  const explicit = envNonNegative(process.env.IAP_HOST_LIVENESS_GRACE_MS)
+  if (explicit !== null) return explicit
+  if (!hasAttachments) return CONFIRM_GRACE_MS
+  return envNonNegative(process.env.IAP_HOST_LIVENESS_GRACE_ATTACHMENTS_MS) ?? CONFIRM_GRACE_ATTACHMENTS_MS
 }
 
 // Launchd-revive retry — a MISS on a launchd-managed target the daemon can't wake (H4)
@@ -328,7 +357,7 @@ async function deliverViaHost(
   // false-OK (silent loss the contract forbids).
   const confirm = seam.confirmLanded ?? ((payload: string) => transcriptCarriesEnvelope(baseline, payload, { env }))
   const sleep = seam.sleep ?? ((ms: number) => new Promise<void>(r => setTimeout(r, ms)))
-  const graceMs = confirmGraceMs()
+  const graceMs = confirmGraceMs(envelopeHasAttachments(envelope))
   const graceDeadline = monotonicMs() + graceMs
   while (true) {
     if (confirm(envelope)) return ok(undefined)
@@ -574,13 +603,63 @@ export function compactTranscriptHasDone(
 
 /** Deep-search every string value of a parsed JSON record for `needle` (CR-stripped on the haystack
  *  side; the needle is pre-stripped by the caller). */
-function jsonStringValuesContain(value: unknown, needle: string): boolean {
-  if (typeof value === 'string') return value.replace(/\r/g, '').includes(needle)
-  if (Array.isArray(value)) return value.some(v => jsonStringValuesContain(v, needle))
-  if (value && typeof value === 'object') return Object.values(value).some(v => jsonStringValuesContain(v, needle))
+/** ALL needles must be present in ONE string value — not scattered across the record. Splitting
+ *  the confirm into head+tail (see confirmNeedles) only stays as forge-resistant as the whole
+ *  envelope if both halves are found in the SAME string the receiver actually stored. */
+function jsonStringValuesContainAll(value: unknown, needles: readonly string[]): boolean {
+  if (typeof value === 'string') {
+    const s = value.replace(/\r/g, '')
+    return needles.every(n => s.includes(n))
+  }
+  if (Array.isArray(value)) return value.some(v => jsonStringValuesContainAll(v, needles))
+  if (value && typeof value === 'object') return Object.values(value).some(v => jsonStringValuesContainAll(v, needles))
   return false
 }
 
+/**
+ * The substrings whose presence in ONE new record proves the receiver took THIS envelope.
+ *
+ * Normally that is the whole envelope: long, unique, and a receiver's own turn does not
+ * reproduce it verbatim, so it cannot forge a confirm.
+ *
+ * WITH ATTACHMENTS the whole envelope is the wrong needle, because the receiver REWRITES it.
+ * Measured 15.07.2026 (claude receiver, 4 PNGs). Sent:
+ *
+ *   <iap …>⏎Reply via send_to_peer.⏎<attachments>a.png⏎…⏎d.png</attachments>⏎<msg>…</msg>⏎</iap>
+ *
+ * Stored by the receiver:
+ *
+ *   [Image #108] [Image #109]<iap …>⏎Reply via send_to_peer.⏎d.png</attachments>⏎<msg>…</msg>⏎</iap>
+ *
+ * The runtime hoists the images into separate image blocks, prepends `[Image #N]` placeholders,
+ * and eats the OPENING `<attachments>` tag plus the paths it consumed. The envelope no longer
+ * contains itself → no match → a 4 s false-FAIL on a message that DID land. The sender then
+ * retries and duplicates it in the receiver's context (three times, live, before this fix).
+ *
+ * The mutation is structurally CONFINED to the attachments region: the `<iap …>` header and the
+ * whole `<msg>…</msg></iap>` tail were byte-intact in the stored record. So we match around the
+ * damage — head + tail, both required in the same string value.
+ *
+ * NOT a short unique token in the header, which is the tempting fix: a short, predictable needle
+ * is one the receiver can reproduce in its OWN turn (agents quote IAP headers when reporting),
+ * and that forges a confirm. A false-OK is silent loss — the one outcome this contract forbids —
+ * while a false-FAIL merely costs a retry. Head+tail keeps the original forge-resistance bar:
+ * to fake it the receiver must echo both the header and the entire body verbatim.
+ */
+export function confirmNeedles(envelope: string): string[] {
+  const n = envelope.replace(/\r/g, '')
+  const OPEN = '<attachments>'
+  const CLOSE = '</attachments>'
+  const open = n.indexOf(OPEN)
+  if (open < 0) return [n] // no attachments → nothing rewrites the envelope → strongest needle
+  const close = n.indexOf(CLOSE, open + OPEN.length)
+  if (close < 0) return [n] // malformed → fall back to the whole envelope rather than guess
+  const head = n.slice(0, open).trimEnd()
+  const tail = n.slice(close + CLOSE.length).trimStart()
+  const parts = [head, tail].filter(p => p.length > 0)
+  return parts.length ? parts : [n]
+}
+
 /**
  * Did a NEW transcript/session-jsonl record CARRYING `envelope` appear since `baseline` (the
  * per-runtime absolute file paths + SIZES captured immediately before delivery)? This is the
@@ -618,8 +697,8 @@ export function transcriptCarriesEnvelope(
   envelope: string,
   opts: { env?: NodeJS.ProcessEnv } = {},
 ): boolean {
-  const needle = envelope.replace(/\r/g, '')
-  if (!needle) return false
+  const needles = confirmNeedles(envelope)
+  if (!needles.length || needles.every(n => !n)) return false
   // Baseline files at their pre-deliver offset; a file NOT in the baseline (born after it) is read from 0.
   const offsets = new Map(baseline.files.map(f => [f.path, f.size]))
   for (const path of compactCandidateFiles(baseline.runtime, baseline.cwd, opts.env)) {
@@ -639,7 +718,7 @@ export function transcriptCarriesEnvelope(
       } catch {
         continue
       }
-      if (jsonStringValuesContain(obj, needle)) return true
+      if (jsonStringValuesContainAll(obj, needles)) return true
     }
   }
   return false