@agfpd/iapeer 0.4.90 → 0.4.92

package/docs/17-approval.md

@@ -1,6 +1,6 @@
 # 17 — Human approval
 
-A peer can run in one of two **approval modes**. In `yolo` (the default — every peer today) the agent acts autonomously: the runtime is launched with its bypass flag and nothing asks a human before a tool runs. In `gated` the peer is launched **without** bypass, and every blocking approval the runtime would raise is routed to a **human** through the daemon's approval broker — a Telegram button, a tray click, or `iapeer approve` on the CLI. The human's `allow`/`deny` (with a reason) flows back into the runtime and the tool proceeds or is refused.
+A peer can run in one of two **approval modes**. In `yolo` (the default — every peer today) the agent acts autonomously: the runtime is launched with its bypass flag and nothing asks a human before a tool runs. In `gated` the peer is launched **without** bypass, and every blocking approval the runtime would raise is routed to a **human** through the daemon's approval broker — a Telegram button, a tray click, `iapeer approve` on the CLI, or the web console's approvals panel. The human's `allow`/`deny` (with a reason) flows back into the runtime and the tool proceeds or is refused.
 
 This is a **normative contract**. The approval broker is the daemon's, the fleet endpoints and `ev` kinds below are the surface that operator faces (CLI, tray, the Telegram runtime) are written against — not the daemon source. The interception facts (which runtime event fires, in which shape) are pinned to **Claude Code 2.1.201** and **codex-cli 0.142.5**, taken from the live binaries + current runtime docs.
 
@@ -103,7 +103,7 @@ An unknown tool falls back to a pretty-printed `tool_input`, so nothing is opaqu
 
 ## The broker (single source of truth)
 
-The approval queue lives **in the daemon** (the always-on process). Every channel that asks (the runtime hook, the supervisor breaker) and every channel that answers (CLI, tray, the Telegram runtime) is an interface to this one queue: a decision from any face resolves the request everywhere. In-memory + ephemeral — pending requests do **not** survive a daemon restart (the blocking hook connection breaks → the hook fails safe to deny); the durable `approvals.log` is the audit trace, not a recovery store.
+The approval queue lives **in the daemon** (the always-on process). Every channel that asks (the runtime hook, the supervisor breaker) and every channel that answers (CLI, tray, the Telegram runtime, the web console) is an interface to this one queue: a decision from any face resolves the request everywhere. In-memory + ephemeral — pending requests do **not** survive a daemon restart (the blocking hook connection breaks → the hook fails safe to deny); the durable `approvals.log` is the audit trace, not a recovery store.
 
 Flow: the gated peer's hook (or the supervisor breaker) blocks on `POST /fleet/v1/approvals` → the broker enqueues, emits `approval-request` (to `approvals.log` → SSE), and holds the connection → a face answers via `POST /fleet/v1/approvals/<id>/(approve|deny)` → the promise resolves, the daemon writes the runtime hook JSON back, the tool proceeds or is blocked with the reason.
 
@@ -118,7 +118,7 @@ The approval surface is served on both daemon listeners under `/fleet/v1`, same
 **Events** (compact logfmt line → SSE JSON; the full content is *not* in the event — read the queue for it):
 
 - `approval-request` — `id, personality, runtime, kind, tool, summary, created, expires, approvers`.
-- `approval-resolved` — `id, personality, runtime, decision (allow|deny), reason, by (approver), via (cli|tray|telegram|timeout|disconnect), latencyMs`.
+- `approval-resolved` — `id, personality, runtime, decision (allow|deny), reason, by (approver), via (cli|tray|telegram|web|timeout|disconnect), latencyMs`. `via` is the surface the decision came from, **self-declared by the answering face** in its `POST` body (free-form-tolerant, like `kind`; `timeout`/`disconnect` are broker-internal). A face that did not self-identify gets the field **omitted** — the audit line never guesses a surface.
 
 **Endpoints:**
 
@@ -126,12 +126,14 @@ The approval surface is served on both daemon listeners under `/fleet/v1`, same
 |---|---|
 | `GET /fleet/v1/approvals` | list pending requests (full items) |
 | `GET /fleet/v1/approvals/<id>` | one pending request, full `content` (the multi-line diff / plan / command) |
-| `POST /fleet/v1/approvals/<id>/approve` | `{approver?}` → allow |
-| `POST /fleet/v1/approvals/<id>/deny` | `{reason?, approver?}` → deny (reason to the model) |
+| `POST /fleet/v1/approvals/<id>/approve` | `{approver?, via?}` → allow |
+| `POST /fleet/v1/approvals/<id>/deny` | `{reason?, approver?, via?}` → deny (reason to the model) |
 | `POST /fleet/v1/approvals` | the **blocking long-poll** the asking hook/breaker holds: `{personality, runtime, kind, tool, content, summary?}` → `{id, decision, reason?}` |
 
 `kind` is the taxonomy tag (`tool` | `plan` | `question` | `circuit-breaker`; free-form-tolerant). So the SSE/badge stays light while the full content is available in every channel through the two `GET`s.
 
+`via` on approve/deny is the answering face's **self-identification of its surface** for the audit trail: the CLI sends `cli`, the tray `tray`, the Telegram runtime `telegram`, the web console `web`. A face MUST send it (the log omits `via` otherwise); the broker passes it through verbatim into `approvals.log`.
+
 ## CLI
 
 - `iapeer approvals [--json]` — the pending queue: personality · runtime · kind · **the verbatim command/content** · age · id.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@agfpd/iapeer",
-  "version": "0.4.90",
+  "version": "0.4.92",
   "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/approvals.ts

@@ -1,6 +1,6 @@
 // Approval broker — the in-daemon queue that is the SINGLE SOURCE OF TRUTH for
 // human-approval requests (docs/17). Every channel (the runtime hook that ASKS, and
-// the CLI / tray / telegram faces that ANSWER) is an interface to THIS one queue: a
+// the CLI / tray / telegram / web-console faces that ANSWER) is an interface to THIS one queue: a
 // decision from any face resolves the request everywhere (the owner's invariant).
 //
 // Flow: a gated peer's PreToolUse hook blocks and POSTs /fleet/v1/approvals → the fleet
@@ -56,7 +56,9 @@ export interface ApprovalDecision {
 export interface ResolveMeta {
   /** The approver who answered (a nature-peer personality). */
   by?: string
-  /** The channel that answered: cli | tray | telegram | timeout | disconnect. */
+  /** The surface that answered: cli | tray | telegram | web | timeout | disconnect.
+   *  Self-declared by the answering face (free-form-tolerant); absent when the face
+   *  did not self-identify — the audit line then omits `via` rather than guessing. */
   via?: string
 }
 

package/src/daemon/fleet.ts

@@ -636,7 +636,10 @@ export function buildFleetHandler(opts: FleetHandlerOptions = {}): FleetHandler
           /* empty/invalid body is fine — approve/deny carry only optional fields */
         }
         const by = typeof body.approver === 'string' ? body.approver : undefined
-        const via = typeof body.via === 'string' ? body.via : 'cli'
+        // The answering face self-identifies its surface in `via` (cli | tray | telegram | web | …;
+        // free-form-tolerant like `kind`). NO default — an audit line must never claim a surface the
+        // caller did not state; a face that sent nothing is logged with the field omitted.
+        const via = typeof body.via === 'string' ? body.via : undefined
         const ok =
           action === 'approve'
             ? broker.resolve(id, { decision: 'allow', reason: typeof body.reason === 'string' ? body.reason : undefined }, { by, via })

package/src/supervisor/approvalRoute.ts

@@ -74,6 +74,19 @@ export interface BreakerRouteDeps {
   env: NodeJS.ProcessEnv
   /** Inject keys into the pty (child.terminal.write). */
   write: (bytes: Buffer) => void
+  /**
+   * STALE-PROOF (15.07 incident, codex-zapret2-oneclick): return true iff the SAME modal this request
+   * was raised for is on screen RIGHT NOW (the caller compares the live pane's nagSignature against
+   * the fingerprint captured at request time). Consulted (a) periodically while the long-poll is
+   * outstanding — a vanished modal ABORTS the request at the broker (the card clears from every face)
+   * — and (b) synchronously immediately before ANY key injection. Without this, a late allow/deny
+   * lands its keys in whatever the pty shows NOW (a NEWER live turn — a bare Escape aborted it).
+   * REQUIRED by design: keys must never be injected without proof the target modal is still up.
+   * A throw is treated as `false` (fail-closed: cannot prove the modal → do not touch the pty).
+   */
+  stillActive: () => boolean
+  /** Cadence of the stale re-check while the long-poll is outstanding. Default 2000 ms. */
+  staleCheckMs?: number
   /** Injectable fetch (tests). */
   fetch?: typeof fetch
   /** Injectable client timeout (tests). */
@@ -84,16 +97,57 @@ export interface BreakerRouteDeps {
   now?: () => number
 }
 
+/** routeCircuitBreaker outcome: the decision (human / fail-safe / stale-deny) + whether keys were
+ *  actually injected into the pty. `stale: true` = the target modal was gone, so the request was
+ *  closed WITHOUT touching the pty — the caller must not treat it as an answered modal. */
+export interface BreakerRouteResult extends ApprovalDecision {
+  /** True iff approve/deny keys were written to the pty. */
+  injected: boolean
+  /** True iff the request was closed because the target modal disappeared (no keys injected). */
+  stale?: boolean
+}
+
 /**
  * POST the circuit-breaker to the human-approval broker, await the decision, and inject the decided
- * keys into the pty. Returns the decision for the caller's cooldown/in-flight bookkeeping. NEVER
- * throws — a broker failure fails safe to deny (decline keys injected). Every path leaves one audit
- * line: BREAKER-ALLOW / BREAKER-DENY with the taxonomy, the parsed detail, and (on deny) the reason.
+ * keys into the pty — IF AND ONLY IF the modal the request was raised for is still on screen. Returns
+ * the decision + whether keys were injected. NEVER throws — a broker failure fails safe to deny
+ * (decline keys injected, modal permitting).
+ *
+ * STALE-PROOF invariant (15.07 incident): pty bytes are written ONLY under a live re-proof of the
+ * target modal (`deps.stillActive`). Two checkpoints:
+ *   1. While the long-poll is outstanding, a poller re-proves the modal every `staleCheckMs`; the
+ *      moment it is gone the request is ABORTED (the daemon's requester-disconnect cancel settles it
+ *      and clears the card from every face) — the peer moved on, nobody should keep being asked.
+ *   2. Immediately before ANY injection (human decision, fail-safe deny alike) the modal is re-proved
+ *      one final time — synchronously, with no yield between proof and write, so a pane update cannot
+ *      interleave. A vanished modal → BREAKER-STALE audit line, NO pty bytes, `stale: true`.
+ * Every path leaves one audit line: BREAKER-ALLOW / BREAKER-DENY (keys injected) or BREAKER-STALE
+ * (request closed, pty untouched), each with the taxonomy, the parsed detail, and the reason/decision.
  */
-export async function routeCircuitBreaker(input: BreakerApprovalInput, deps: BreakerRouteDeps): Promise<ApprovalDecision> {
+export async function routeCircuitBreaker(input: BreakerApprovalInput, deps: BreakerRouteDeps): Promise<BreakerRouteResult> {
   const now = deps.now ?? Date.now
   const { content, summary } = composeApprovalContent(input)
+  // Fail-closed re-proof: an unreadable pane model is NOT proof the modal is up → never inject on it.
+  const stillActive = (): boolean => {
+    try {
+      return deps.stillActive()
+    } catch {
+      return false
+    }
+  }
+  // Checkpoint 1 — poll the modal while the long-poll is outstanding; a vanished modal aborts the
+  // request at the broker (requester-disconnect → cancel → the card clears from every face).
+  let stale = false
+  const controller = new AbortController()
+  const stalePoll = setInterval(() => {
+    if (!stillActive()) {
+      stale = true
+      controller.abort()
+    }
+  }, deps.staleCheckMs ?? 2000)
+  ;(stalePoll as { unref?: () => void }).unref?.()
   let decision: ApprovalDecision
+  let lateDecision: string | undefined // a human decision that arrived for an already-gone modal
   try {
     decision = await requestApproval(
       resolveFleetBase(deps.env),
@@ -105,16 +159,30 @@ export async function routeCircuitBreaker(input: BreakerApprovalInput, deps: Bre
         content,
         summary,
       },
-      { env: deps.env, fetch: deps.fetch, timeoutMs: deps.timeoutMs },
+      { env: deps.env, fetch: deps.fetch, timeoutMs: deps.timeoutMs, signal: controller.signal },
     )
+    lateDecision = decision.decision
   } catch (e) {
-    // Broker unreachable / abort / non-200 → DENY (never auto-Yes). gated = fail-safe.
+    // Broker unreachable / abort / non-200 → DENY (never auto-Yes). gated = fail-safe. Whether the
+    // deny KEYS may be pressed is still gated on the modal being up (checkpoint 2 below).
     decision = { decision: 'deny', reason: `iapeer approval unavailable (${e instanceof Error ? e.message : String(e)}) — denied fail-safe` }
+  } finally {
+    clearInterval(stalePoll)
+  }
+  // Checkpoint 2 — final synchronous re-proof immediately before the injection. No yield between this
+  // check and the write below, so the pane model cannot change in between (single-threaded).
+  if (!stale && !stillActive()) stale = true
+  if (stale) {
+    deps.log?.(
+      `[supervisor] BREAKER-STALE ${input.taxonomy} ts=${new Date(now()).toISOString()} ${input.detail}` +
+        ` — modal gone before resolution${lateDecision ? ` (late human ${lateDecision} NOT injected)` : ''}; request closed, NO pty bytes`,
+    )
+    return { decision: 'deny', reason: 'stale — modal cleared before the decision; no keys injected', injected: false, stale: true }
   }
   deps.write(decision.decision === 'allow' ? input.approveBytes : input.denyBytes)
   deps.log?.(
     `[supervisor] BREAKER-${decision.decision.toUpperCase()} ${input.taxonomy} ts=${new Date(now()).toISOString()} ${input.detail}` +
       (decision.reason ? ` reason=${JSON.stringify(decision.reason)}` : ''),
   )
-  return decision
+  return { ...decision, injected: true }
 }

package/src/supervisor/daemon.ts

@@ -795,6 +795,16 @@ export function runSupervisorDaemon(opts: SupervisorDaemonOptions): void {
           // safe to DENY on any broker fault. For unknown-modal the broker content carries EXPLICIT button
           // semantics (Allow presses option 1 "<label>"; Deny cancels via Esc) so the human decides informed.
           brokerInFlight = true
+          // STALE-PROOF (15.07 incident): pin THIS modal's content signature at request time; the route
+          // re-proves it against the LIVE pane model before any key injection. Modal gone / replaced by a
+          // different one → signature mismatch → the request closes WITHOUT touching the pty (a late
+          // allow/deny must never land in a newer live turn). A transient model-read throw propagates —
+          // routeCircuitBreaker treats it as fail-closed false (cannot prove the modal → no bytes).
+          const requestSig = sig
+          const stillActive = (): boolean => {
+            const encNow = { appCursorKeys: xterm.modes.applicationCursorKeysMode }
+            return nagSignature(nextNagAction(nagAdapter, modelToPlainText(xterm, cols, rows), encNow)) === requestSig
+          }
           void routeCircuitBreaker(
             {
               taxonomy: action.taxonomy,
@@ -809,6 +819,7 @@ export function runSupervisorDaemon(opts: SupervisorDaemonOptions): void {
               runtime: brokerRuntime,
               env: brokerEnv,
               write: b => child.terminal.write(b),
+              stillActive,
               log: line => {
                 try {
                   console.warn(line)