@agfpd/iapeer 0.4.71 → 0.4.72

package/docs/17-approval.md

@@ -63,10 +63,26 @@ Both runtimes carry a Claude-compatible **hook** system that intercepts an appro
 
 - **claude `PermissionRequest`** — stdin carries `{tool_name, tool_input, …}`; the hook prints `{"hookSpecificOutput":{"hookEventName":"PermissionRequest","decision":{"behavior":"allow|deny","message":"…"}}}`. A `deny` carries `message` to the model. Fires only on prompt-worthy calls.
 - **codex `PreToolUse`** — same stdin shape; prints `{"hookSpecificOutput":{"hookEventName":"PreToolUse","permissionDecision":"allow|deny","permissionDecisionReason":"…"}}`. `exit 2` (+ stderr) also denies. Verified live (0.142.5): codex fires `PreToolUse` (not `PermissionRequest`) for tool calls with `tool_name:"Bash"` for shell; a `deny` hard-blocks the tool and the reason reaches the model even under `sandbox_mode=danger-full-access` — so under the gated config (danger-full-access + on-request → `permission_mode=bypassPermissions`) the hook is the SOLE gate.
-- **supervisor circuit-breaker** — claude's `dangerous-rm`/`rmdir` guard (and the standard command-approval prompt a no-bypass session shows) is a TUI select the hook never sees. The pty supervisor reads it off its authoritative model and, under gated, POSTs it to the broker (below); under yolo it auto-presses YES with an audit line.
+- **supervisor circuit-breaker** — claude's `dangerous-rm`/`rmdir` guard (and the standard command-approval prompt a no-bypass session shows) is a TUI select the hook never sees. The pty supervisor reads it off its authoritative model and routes by class (see *Supervisor pty-scrape classification* below): the known auto-Yes classes are pressed under yolo (with an audit line) / brokered under gated, while `org-policy` and any unrecognized `unknown-modal` always go to the human.
 
 The hook binary is the `iapeer approval-hook` subcommand: it reads the runtime's hook JSON on stdin, resolves `PEER_PERSONALITY`/`PEER_RUNTIME` from its session env and the daemon URL from `router.json`, POSTs a blocking request to the broker, and prints the runtime-appropriate decision JSON.
 
+### Supervisor pty-scrape classification (yolo-robustness)
+
+The supervisor nag-watcher classifies every mid-session blocking TUI modal it observes off its authoritative model. It fires only when the pane has been **completely static** for a threshold (the timing stuck-gate: a real blocked modal freezes the pty; a peer merely streaming or rendering the modal text keeps writing) **and** the modal is a live numbered-select that **replaced the composer** (the bottom-most cursor-glyph row is a numbered option, not the composer — the same idle→composer / modal→option invariant the known matchers rest on). Owner rule: **yolo presses what it KNOWS (maximum known rights); anything new or above the peer, the human must SEE and confirm** — never a blind auto-Yes (a modal a runtime raised on purpose must not be swallowed), never a hang.
+
+| Class | Detection | yolo | gated |
+|---|---|---|---|
+| `dangerous-rm` | known needle (2-option `1.Yes/2.No`) | auto-Yes + audit | broker (Allow=1 / Deny=2) |
+| `command-approval` | known needle (3-option `1.Yes/2.Yes,…/3.No`) | auto-Yes + audit | broker (Allow=1 / Deny=3) |
+| `org-policy` | known needle ("organization requires approval") | **broker — never auto-Yes** | broker (Allow=1 / Deny=3) |
+| `unknown-modal` | **generic** — numbered select (≥2 options) matching NO known signature | **broker — never auto-Yes** | **broker** |
+
+- **`org-policy`** is a barrier ABOVE the peer (an MCP org-restriction). It is recognized but **always routed to the human** on both modes (the owner's org rule is human-only), with the precise 3-option keys. Previously it was excluded from the matcher and a yolo peer HUNG on it — now closed.
+- **`unknown-modal`** is the generic residue: a numbered-select modal (a new one Anthropic/OpenAI shipped) matching none of the known signatures. It is **always routed to the human** on both modes. Because the option layout is unknown, the injection is **binary** (v1): **Allow presses option 1** (the proceed/primary position in every known select; the position-robust affirmative) and **Deny presses `Escape`** (the universal modal cancel — it commits no numbered choice, so it can never accidentally affirm). The broker `content` carries **explicit button semantics** — the verbatim modal block plus a header stating exactly what Allow presses (`option 1: "<verbatim label>"`) and that Deny cancels via Esc — so the human decides informed, not on an abstract Allow/Deny. A **>2-way** choice on an unknown modal is a v2 extension (most approvals are binary). If a modal ignores the injected keys (Esc not honored), the daemon **bounds re-enqueue** (a few rounds) then **logs once and safe-parks** — the peer stays blocked (safe), never an infinite ask loop nor a blind Yes. Both claude (`❯`) and codex (`›`) are covered; codex's known boot dialogs are excluded (owned by the boot-driver).
+
+The supervisor scrape is the ONLY interceptor for prompts the runtime hook cannot see (dangerous-rm above the permission layer; a non-hookable modal such as codex MCP-elicitation). A blocking prompt that is NOT a numbered select (a free-form text-input prompt) is out of v1 scope — the numbered-select family is the approval/confirm class in practice.
+
 ## Nomenclature v1 and content per action (criterion «what is being approved»)
 
 In every channel a human sees the **concrete content** of the action, not just the tool name.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@agfpd/iapeer",
-  "version": "0.4.71",
+  "version": "0.4.72",
   "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/launch/adapters/claude.ts

@@ -25,6 +25,7 @@ import { join } from 'path'
 import { readdirSync, realpathSync, statSync } from 'fs'
 import type { ApprovalMode, ControlCommand, ControlPlan, LaunchAdapterConfig, LaunchSpec, RuntimeAdapter } from '../types.ts'
 import { lastTimestampedEntryMs } from './transcriptTail.ts'
+import { detectNumberedModal } from './modalDetect.ts'
 
 // ─────────────────────────────────────────────────────────────────────────────
 // Boot dialog + ready markers (lifecycle claudeBootDialog / claudeInputReady)
@@ -169,6 +170,44 @@ function commandApprovalDetail(pane: string): string {
   return '(unparsed)'
 }
 
+// ORG-POLICY approval prompt (docs/17 — yolo-robustness). "Your organization requires approval for this
+// tool" is an MCP org-restriction: a barrier ABOVE the peer that the owner's rule says is HUMAN-only —
+// NEVER auto-pressed on ANY peer (yolo included). It was previously EXCLUDED from isCommandApprovalPrompt
+// (→ fell through to 'none' → a yolo peer HUNG on it). Now it is its OWN recognized-but-always-human tier
+// (blockingConfirm alwaysHuman:true) so it routes to the broker under BOTH modes with the SAME 3-option
+// command-approval layout keys (Allow=1.Yes, Deny=3.No). If a future org-policy render is NOT this
+// 3-option layout, isOrgPolicyPrompt returns false and the GENERIC unknownBlockingModal catches it
+// instead (→ human with Esc-deny) — either way it reaches a human, never auto-Yes.
+/** FULL-signature + position match for the org-policy approval prompt: the org needle + the 3-option
+ *  "proceed?" select with the bottom-most `❯` cursor on "1. Yes" (a live modal, not a quote). */
+function isOrgPolicyPrompt(pane: string): boolean {
+  if (!pane.includes(RM_PROCEED)) return false
+  if (!pane.includes(ORG_POLICY_APPROVAL)) return false
+  if (isDangerousRmPrompt(pane)) return false // 2-option breaker owns its pane
+  if (!/(^|\n)\s*2\.\s*Yes/.test(pane)) return false
+  if (!/(^|\n)\s*3\.\s*No\b/.test(pane)) return false
+  let lastCursorRow = ''
+  for (const line of pane.split(/\r?\n/)) if (line.includes('❯')) lastCursorRow = line
+  return /❯\s*1\.\s*Yes\b/.test(lastCursorRow)
+}
+
+// claude's select-modal cursor glyph (U+276F) — the same glyph isInputReady / the nag matcher key on.
+const CLAUDE_SELECT_GLYPH = '❯'
+/** Does the pane carry a KNOWN claude blocking signature (dangerous-rm / command-approval / org-policy /
+ *  fullscreen-nag)? unknownBlockingModal returns null for these so it fires ONLY for the unrecognized
+ *  residue — the daemon also checks them first, but this keeps the detector self-contained + testable. */
+function isKnownClaudeBlockingSignature(pane: string): boolean {
+  // anyBootDialog: the numbered boot selects (resume-picker / bypass-accept / theme / MCP-approval) are
+  // owned by the boot-driver (nextBootAction) — never treat them as an "unknown" mid-session modal.
+  return (
+    anyBootDialog(pane) ||
+    isDangerousRmPrompt(pane) ||
+    isCommandApprovalPrompt(pane) ||
+    isOrgPolicyPrompt(pane) ||
+    isFullscreenNagText(pane)
+  )
+}
+
 // ─────────────────────────────────────────────────────────────────────────────
 // Transcript activity proxy + resume uuid (lifecycle port, claude slug fix)
 // ─────────────────────────────────────────────────────────────────────────────
@@ -396,12 +435,28 @@ export const claudeAdapter: RuntimeAdapter = {
    * command/target trace for the audit + broker content. NB deliberately NOT a "smart" safe-decline —
    * the gated human-approval path lands via the daemon broker (docs/17, Unit 4).
    */
-  blockingConfirm(pane: string): { keys: string[]; denyKeys: string[]; taxonomy: string; detail: string } | null {
+  blockingConfirm(pane: string): { keys: string[]; denyKeys: string[]; taxonomy: string; detail: string; alwaysHuman?: boolean } | null {
     if (isDangerousRmPrompt(pane)) return { keys: ['1', 'Enter'], denyKeys: ['2', 'Enter'], taxonomy: 'dangerous-rm', detail: dangerousRmDetail(pane) }
     if (isCommandApprovalPrompt(pane)) return { keys: ['1', 'Enter'], denyKeys: ['3', 'Enter'], taxonomy: 'command-approval', detail: commandApprovalDetail(pane) }
+    // Org-policy: recognized, but NEVER auto-Yes — always to the human (both modes). Same 3-option keys.
+    if (isOrgPolicyPrompt(pane)) return { keys: ['1', 'Enter'], denyKeys: ['3', 'Enter'], taxonomy: 'org-policy', detail: commandApprovalDetail(pane), alwaysHuman: true }
     return null
   },
 
+  /**
+   * GENERIC unknown blocking-modal detector (docs/17 — yolo-robustness). Fires for a numbered-select
+   * modal that halts the pty but matches NONE of the known signatures above (a new modal we did not
+   * foresee — the class that hung a live yolo peer). Returns null for the known signatures (checked by
+   * isKnownClaudeBlockingSignature) so the daemon routes those through their own tiers. The verbatim
+   * block + option-1 label let the daemon give the human EXPLICIT button semantics (Allow presses
+   * option 1 = "<option1>", Deny cancels via Esc). Detection is structural (bottom-most `❯` is a
+   * numbered option + ≥2 options) — see modalDetect.ts; the daemon's timing stuck-gate composes on top.
+   */
+  unknownBlockingModal(pane: string): { content: string; option1: string } | null {
+    if (isKnownClaudeBlockingSignature(pane)) return null
+    return detectNumberedModal(pane, CLAUDE_SELECT_GLYPH)
+  },
+
   /**
    * Ready for the first message iff the input surface is rendered AND no startup
    * dialog is still up (lifecycle.claudeInputReady, index.ts:272-279;

package/src/launch/adapters/codex.ts

@@ -43,6 +43,7 @@ import { homedir } from 'os'
 import { join } from 'path'
 import { readdirSync, realpathSync, statSync } from 'fs'
 import { codexSessionCwd, lastTimestampedEntryMs } from './transcriptTail.ts'
+import { detectNumberedModal } from './modalDetect.ts'
 import type { ApprovalMode, ControlCommand, ControlPlan, LaunchAdapterConfig, LaunchSpec, RuntimeAdapter } from '../types.ts'
 
 // ─────────────────────────────────────────────────────────────────────────────
@@ -75,6 +76,15 @@ function codexHooksReviewActive(pane: string): boolean {
   return pane.includes('Hooks need review')
 }
 
+// codex's select-modal glyph (U+203A) — the same arrow isInputReady keys on (a numbered option row is
+// `› 1. …`; the composer is `› <text>`, no leading digit-dot).
+const CODEX_SELECT_GLYPH = '›'
+/** Does the pane carry a KNOWN codex boot dialog (update / dir-trust / hooks-review)? unknownBlockingModal
+ *  returns null for these so they stay owned by the boot-driver and are never re-routed to a human. */
+function isKnownCodexBlockingSignature(pane: string): boolean {
+  return codexUpdatePromptActive(pane) || codexDirTrustActive(pane) || codexHooksReviewActive(pane)
+}
+
 // ─────────────────────────────────────────────────────────────────────────────
 // Session activity proxy + resume preflight (watcher / spawner port)
 // ─────────────────────────────────────────────────────────────────────────────
@@ -248,6 +258,20 @@ export const codexAdapter: RuntimeAdapter = {
     return null
   },
 
+  /**
+   * GENERIC unknown blocking-modal detector (docs/17 — yolo-robustness). codex carries no known
+   * mid-session circuit-breaker (its tool approvals ride the PreToolUse hook under gated, and yolo
+   * bypasses them), so it declares no blockingConfirm/nagDismissKeys — but a NON-hookable modal
+   * (MCP-elicitation, a future codex prompt) can still surface on screen and hang the pty. This catches
+   * that residue structurally (bottom-most `›` is a numbered option + ≥2 options; see modalDetect.ts),
+   * excluding the known boot dialogs (owned by the boot-driver). The daemon routes it to the human with
+   * explicit button semantics + the timing stuck-gate on top.
+   */
+  unknownBlockingModal(pane: string): { content: string; option1: string } | null {
+    if (isKnownCodexBlockingSignature(pane)) return null
+    return detectNumberedModal(pane, CODEX_SELECT_GLYPH)
+  },
+
   /**
    * Ready for the first message iff the codex TUI composer is rendered and no
    * startup screen is still up:

package/src/launch/adapters/modalDetect.ts

@@ -0,0 +1,102 @@
+// GENERIC numbered-SELECT modal detector (docs/17 — yolo-robustness / unknown-modal). Shared by the
+// claude (`❯`) and codex (`›`) adapters' unknownBlockingModal: a modal that halts the pty on a keypress
+// but matches NONE of the adapter's KNOWN signatures — a new modal Anthropic/OpenAI shipped that we did
+// not foresee (the class that hung a live yolo peer). It is detected STRUCTURALLY, not by phrase, on the
+// SAME invariant the known matchers rest on (an idle-ready TUI shows the composer at the bottom; a live
+// modal REPLACES it with a numbered select), minus the phrase gate:
+//
+//   - the BOTTOM-MOST cursor-glyph row is a numbered option (`glyph … N. …`), not the composer
+//     (`glyph <placeholder/text>` carries no leading digit-dot), and
+//   - the contiguous non-blank block ending there carries ≥2 distinct numbered options (a real select,
+//     not a lone printed `N.` line).
+//
+// A peer merely RENDERING/quoting a modal in its output fails this: the READY composer glyph renders
+// BELOW the quote, so the bottom-most glyph row is the composer, not an option (the В40 class the known
+// matchers already survive). The daemon's timing STUCK-gate composes on top (fires only on a frozen
+// pane), so a working/streaming peer is excluded there.
+
+/** Verbatim modal block (shown to the human) + the option-1 label (what an ALLOW presses). */
+export interface NumberedModal {
+  content: string
+  option1: string
+}
+
+const CAP_LINES = 24
+const CAP_BYTES = 8192
+// Unicode box-drawing block (U+2500–U+257F) — modal borders/separators; stripped for PARSING only
+// (the verbatim `content` keeps them).
+const BOX_DRAWING = /[─-╿]/g
+
+function escapeForRegex(s: string): string {
+  return s.replace(/[.*+?^${}()|[\]\\]/g, '\\$&')
+}
+
+/** Parse a numbered option row (`❯ 1. Yes` / `│  2. No │`) → {num, label}, else null. Box glyphs and a
+ *  leading select glyph are stripped before matching so a boxed/selected row parses the same. */
+function parseOption(raw: string, glyph: string): { num: number; label: string } | null {
+  const s = raw.replace(BOX_DRAWING, ' ').split(glyph).join(' ').trim()
+  const m = /^(\d+)[.)]\s+(\S.*)$/.exec(s)
+  if (!m) return null
+  return { num: parseInt(m[1], 10), label: m[2].replace(/\s+$/, '').trim() }
+}
+
+/** Cap the verbatim block: keep the LAST CAP_LINES rows (the options sit at the bottom, most load-
+ *  bearing), each right-trimmed, then a hard byte ceiling. A leading marker notes any drop. */
+function capBlock(block: string[]): string {
+  let rows = block.map(l => l.replace(/\s+$/, ''))
+  let dropped = false
+  if (rows.length > CAP_LINES) {
+    rows = rows.slice(rows.length - CAP_LINES)
+    dropped = true
+  }
+  let out = rows.join('\n')
+  if (Buffer.byteLength(out, 'utf8') > CAP_BYTES) {
+    out = out.slice(-CAP_BYTES)
+    dropped = true
+  }
+  return dropped ? `…\n${out}` : out
+}
+
+/**
+ * Detect a generic numbered-select modal that has replaced the composer. `glyph` is the runtime's
+ * cursor/select glyph (`❯` claude, `›` codex). Returns the verbatim block + option-1 label, or null.
+ * The CALLER must first exclude its OWN known signatures (so this fires only for the unrecognized
+ * residue) — this function is signature-agnostic by design.
+ */
+export function detectNumberedModal(pane: string, glyph: string): NumberedModal | null {
+  const lines = pane.split(/\r?\n/)
+  // bottom-most row carrying the select glyph.
+  let selected = -1
+  for (let i = 0; i < lines.length; i++) if (lines[i].includes(glyph)) selected = i
+  if (selected < 0) return null
+  // it must be a SELECTED numbered option (`glyph … N. …`) — the composer (`glyph <text>`) carries no
+  // leading digit-dot, so an idle/ready pane and a mere quote-with-composer-below both fail here.
+  const selectedRe = new RegExp(`${escapeForRegex(glyph)}\\s*\\d+[.)]\\s`)
+  if (!selectedRe.test(lines[selected])) return null
+  // The select glyph sits only on the SELECTED option; siblings render WITHOUT it (above and below). Grow
+  // the contiguous OPTION RUN in BOTH directions from the selected row while each line parses as a
+  // numbered option (an interleaved blank / non-option line ends the run). This captures every option,
+  // not just the ones above the cursor.
+  let optTop = selected
+  let optBottom = selected
+  while (optTop - 1 >= 0 && parseOption(lines[optTop - 1], glyph)) optTop--
+  while (optBottom + 1 < lines.length && parseOption(lines[optBottom + 1], glyph)) optBottom++
+  // need ≥2 DISTINCT numbered options (a real select, not a lone printed `N.` line).
+  const nums = new Set<number>()
+  let option1 = ''
+  for (let i = optTop; i <= optBottom; i++) {
+    const opt = parseOption(lines[i], glyph)
+    if (!opt) continue
+    nums.add(opt.num)
+    if (opt.num === 1 && !option1) option1 = opt.label
+  }
+  if (nums.size < 2) return null
+  // Verbatim block shown to the human: the option run + a little context (the question above / a footer
+  // below), then leading/trailing blank lines trimmed. Bounded by the caps.
+  const start = Math.max(0, optTop - 3)
+  const end = Math.min(lines.length - 1, optBottom + 2)
+  const block = lines.slice(start, end + 1)
+  while (block.length && block[0].trim() === '') block.shift()
+  while (block.length && block[block.length - 1].trim() === '') block.pop()
+  return { content: capBlock(block), option1: option1 || '(option 1)' }
+}

package/src/launch/types.ts

@@ -329,8 +329,33 @@ export interface RuntimeAdapter {
    * content mentioning the phrase never fires; else null. Optional (codex/router omit it). tui only.
    * Human-approval lands via the daemon broker (docs/17); the vault idea is "Human-approval
    * подтверждения действий пира через Telegram-кнопки".
+   *
+   * `alwaysHuman` (default false) marks a KNOWN class that must NEVER be auto-pressed on ANY peer —
+   * it always routes to the human broker regardless of approval mode (the owner's org-policy rule:
+   * "a barrier ABOVE us is never auto-answered"). yolo auto-Yes applies only to alwaysHuman=false
+   * classes (dangerous-rm / command-approval — the "yolo presses what it KNOWS" set).
    */
-  blockingConfirm?(pane: string): { keys: string[]; denyKeys: string[]; taxonomy: string; detail: string } | null
+  blockingConfirm?(pane: string): { keys: string[]; denyKeys: string[]; taxonomy: string; detail: string; alwaysHuman?: boolean } | null
+
+  /**
+   * GENERIC blocking-modal detector (docs/17 — yolo-robustness / unknown-modal). The residual sibling
+   * of blockingConfirm: a numbered-SELECT modal that halts the pty on a keypress but matches NONE of
+   * the adapter's KNOWN signatures (a new modal Anthropic/OpenAI shipped that we did not foresee — the
+   * class that hung a live yolo peer). Detected STRUCTURALLY, not by phrase: the bottom-most cursor-glyph
+   * row (`❯`/`›`) is a numbered option (`N.`) AND the contiguous block ending there carries ≥2 numbered
+   * options — i.e. a live select REPLACED the composer (the same idle→composer / modal→option invariant
+   * the known matchers rest on, minus the phrase gate). The adapter returns null for its OWN known
+   * signatures (checked first by the caller), so this fires ONLY for the unrecognized residue.
+   *
+   * Returns `{ content, option1 }`: `content` = the VERBATIM modal block (question + all option rows,
+   * CR-stripped, capped) shown to the human; `option1` = the verbatim label of option 1 (what an ALLOW
+   * will press — the supervisor injects ['1','Enter'] on allow, ['Escape'] to cancel on deny). The human
+   * sees the exact options and what Allow selects, so the decision is INFORMED (owner's "new I must SEE
+   * and confirm" — предметно). v1 is BINARY (option-1-or-cancel); a >2-way choice on an unknown modal is
+   * a v2 extension (most approvals are binary). The timing STUCK-gate (daemon) composes on top — this
+   * fires only on a genuinely frozen pane. Optional (router omits it). tui only.
+   */
+  unknownBlockingModal?(pane: string): { content: string; option1: string } | null
 
   /** Is the input surface ready for the first message? (tui: ready marker present
    *  AND startup dialogs gone). Router runtimes return true (no input surface).

package/src/supervisor/approvalRoute.ts

@@ -15,16 +15,59 @@
 import { requestApproval, resolveFleetBase, type ApprovalDecision } from '../approval/brokerClient.ts'
 
 export interface BreakerApprovalInput {
-  /** Class tag — 'dangerous-rm' | 'command-approval'. Sent as the broker `tool` + `summary`. */
+  /** Class tag — 'dangerous-rm' | 'command-approval' | 'org-policy' | 'unknown-modal'. Sent as the
+   *  broker `tool`. */
   taxonomy: string
-  /** Best-effort one-line command/target trace parsed off the pane. Sent as the broker `content`. */
+  /** Broker taxonomy `kind` (docs/17): 'circuit-breaker' for the known breakers + org-policy, or
+   *  'unknown-modal' for the generic residue. Default 'circuit-breaker'. */
+  brokerKind?: string
+  /** Known breakers: a one-line command/target trace. unknown-modal: the VERBATIM modal block. */
   detail: string
+  /** unknown-modal only: the verbatim label of option 1 — what an ALLOW presses. Powers the explicit
+   *  button semantics the human sees (owner's "new I must SEE and confirm — предметно"). */
+  option1?: string
   /** Keys to inject on ALLOW — the position-robust affirmative ('1'+Enter). */
   approveBytes: Buffer
-  /** Keys to inject on DENY — the taxonomy-specific decline (2.No | 3.No). */
+  /** Keys to inject on DENY — known: the taxonomy decline (2.No | 3.No); unknown-modal: Escape (cancel). */
   denyBytes: Buffer
 }
 
+/**
+ * Compose the human-facing broker `content` + `summary`. KNOWN breakers (dangerous-rm / command-approval)
+ * keep the Ф1 format verbatim (content = the parsed trace) — no regression. The new always-human classes
+ * get an EXPLICIT button-semantics header so a human answering Allow/Deny knows precisely what each does
+ * (boris's mandatory refinement): for an unknown modal, Allow presses option 1 (whose verbatim text is
+ * shown) and Deny cancels via Esc; for org-policy, the known 1.Yes / 3.No mapping is stated. Pure —
+ * unit-testable.
+ */
+export function composeApprovalContent(input: BreakerApprovalInput): { content: string; summary: string } {
+  const kind = input.brokerKind ?? 'circuit-breaker'
+  if (kind === 'unknown-modal') {
+    const opt1 = input.option1?.trim() || '(option 1)'
+    const content = [
+      '⚠ Unrecognized blocking modal — iapeer could not classify it, so it is asking you.',
+      `Allow → presses option 1: ${JSON.stringify(opt1)}`,
+      "Deny  → cancels the modal (Esc); the peer's action is declined and it continues.",
+      '',
+      '─── modal (verbatim) ───',
+      input.detail,
+    ].join('\n')
+    return { content, summary: `unrecognized blocking modal — Allow presses option 1: ${opt1}`.slice(0, 240) }
+  }
+  if (input.taxonomy === 'org-policy') {
+    const content = [
+      '⚠ Organization policy requires approval for this action (a barrier above the peer).',
+      'Allow → presses "1. Yes" (proceed).',
+      'Deny  → presses "3. No" (refuse); the reason goes to the model.',
+      '',
+      input.detail,
+    ].join('\n')
+    return { content, summary: `org-policy approval required — ${input.detail}`.slice(0, 240) }
+  }
+  // Known circuit-breaker (dangerous-rm / command-approval) — Ф1 format, unchanged.
+  return { content: input.detail, summary: input.taxonomy }
+}
+
 export interface BreakerRouteDeps {
   personality: string
   runtime: string
@@ -49,6 +92,7 @@ export interface BreakerRouteDeps {
  */
 export async function routeCircuitBreaker(input: BreakerApprovalInput, deps: BreakerRouteDeps): Promise<ApprovalDecision> {
   const now = deps.now ?? Date.now
+  const { content, summary } = composeApprovalContent(input)
   let decision: ApprovalDecision
   try {
     decision = await requestApproval(
@@ -56,10 +100,10 @@ export async function routeCircuitBreaker(input: BreakerApprovalInput, deps: Bre
       {
         personality: deps.personality,
         runtime: deps.runtime,
-        kind: 'circuit-breaker',
+        kind: input.brokerKind ?? 'circuit-breaker',
         tool: input.taxonomy,
-        content: input.detail,
-        summary: input.taxonomy,
+        content,
+        summary,
       },
       { env: deps.env, fetch: deps.fetch, timeoutMs: deps.timeoutMs },
     )

package/src/supervisor/boot.ts

@@ -34,29 +34,58 @@ export function nextBootAction(adapter: BootPredicates, viewport: string, enc: K
 }
 
 /** The slice of a RuntimeAdapter the MID-SESSION nag-watcher consumes — the optional nagDismissKeys
- *  (benign upsell → silent decline) + blockingConfirm (circuit-breaker → affirmative + audit log).
- *  claudeAdapter satisfies both; codex/router omit them → no action. */
+ *  (benign upsell → silent decline) + blockingConfirm (known circuit-breaker → affirmative/decision) +
+ *  unknownBlockingModal (docs/17 yolo-robustness — a numbered-select modal matching NO known signature →
+ *  always to the human). claudeAdapter satisfies all three; codex declares unknownBlockingModal only;
+ *  router omits all → no action. */
 export interface NagPredicate {
   nagDismissKeys?(pane: string): string[] | null
-  blockingConfirm?(pane: string): { keys: string[]; denyKeys: string[]; taxonomy: string; detail: string } | null
+  blockingConfirm?(pane: string): { keys: string[]; denyKeys: string[]; taxonomy: string; detail: string; alwaysHuman?: boolean } | null
+  unknownBlockingModal?(pane: string): { content: string; option1: string } | null
 }
 
+// Fixed keys for a GENERIC unknown modal whose option layout we do NOT know (docs/17 fork 3): ALLOW
+// presses option 1 (the proceed/primary position in every known claude/codex select; the human is told
+// exactly what option 1 is), DENY presses Escape (the universal modal cancel — commits no numbered
+// choice, so it can never accidentally affirm; if a modal ignores Esc the daemon bounds re-enqueue and
+// safe-parks). v1 is BINARY (option-1-or-cancel); a >2-way choice on an unknown modal is a v2 extension.
+export const UNKNOWN_MODAL_ALLOW_KEYS = ['1', 'Enter']
+export const UNKNOWN_MODAL_DENY_KEYS = ['Escape']
+
 export type NagAction =
   | { kind: 'dismiss'; keys: string[]; bytes: Buffer } // benign upsell — press keys silently
-  // circuit-breaker — press `bytes` to AFFIRM (yolo auto-Yes / gated-approved) or `denyBytes` to DECLINE
-  // (gated-denied / broker fail-safe); LOG the taxonomy + detail either way.
-  | { kind: 'approve'; keys: string[]; bytes: Buffer; denyKeys: string[]; denyBytes: Buffer; taxonomy: string; detail: string }
+  // A blocking confirm/modal needing a Yes/No decision. Press `bytes` to AFFIRM or `denyBytes` to DECLINE.
+  //   - alwaysHuman=false (dangerous-rm / command-approval): yolo auto-Yes, gated → broker.
+  //   - alwaysHuman=true  (org-policy / unknown-modal): ALWAYS → broker (both modes; never auto-Yes).
+  // `brokerKind` is the broker taxonomy tag (docs/17); `option1` (unknown-modal only) is the verbatim
+  // label of option 1, so the human is shown EXACTLY what an Allow will press. `detail` is the audit
+  // trace (known) or the verbatim modal block (unknown-modal).
+  | {
+      kind: 'approve'
+      keys: string[]
+      bytes: Buffer
+      denyKeys: string[]
+      denyBytes: Buffer
+      taxonomy: string
+      detail: string
+      alwaysHuman: boolean
+      brokerKind: string
+      option1?: string
+    }
   | { kind: 'none' }
 
 /**
  * MID-SESSION nag/confirm step (livability) — the persistent sibling of nextBootAction. Unlike the
- * boot-driver (which STOPS at ready), the daemon loops this for the WHOLE session for TWO classes of
- * mid-session blocking prompt no headless peer can answer:
- *   1. a CIRCUIT-BREAKER confirm (blockingConfirm — e.g. the dangerous-rm guard above the permission
- *      layer) → press the affirmative AND surface a `detail`/`taxonomy` the caller logs (owner audit);
- *   2. a benign UPSELL modal (nagDismissKeys — e.g. "Try the new fullscreen-renderer?") → decline silently.
- * The circuit-breaker is checked FIRST (safety-relevant). The caller writes `action.bytes` (cooldown- +
- * stuck-gate-guarded so a cleared prompt is never double-answered). An adapter with neither → 'none'.
+ * boot-driver (which STOPS at ready), the daemon loops this for the WHOLE session over THREE classes of
+ * mid-session blocking prompt no headless peer can answer, checked most-specific FIRST:
+ *   1. a KNOWN circuit-breaker (blockingConfirm — dangerous-rm / command-approval / org-policy) → press
+ *      the affirmative/decision AND surface a `detail`/`taxonomy` the caller logs; `alwaysHuman` decides
+ *      whether a yolo peer auto-Yeses (false) or always routes to the human (true, org-policy);
+ *   2. a benign UPSELL modal (nagDismissKeys — e.g. "Try the new fullscreen-renderer?") → decline silently;
+ *   3. a GENERIC unknown modal (unknownBlockingModal — a numbered select matching no known signature) →
+ *      ALWAYS to the human with fixed option-1-or-cancel keys + the verbatim block (docs/17 yolo-robustness).
+ * The caller writes `action.bytes` (cooldown- + stuck-gate-guarded so a cleared prompt is never double-
+ * answered). An adapter with none of the three → 'none'.
  */
 export function nextNagAction(adapter: NagPredicate, viewport: string, enc: KeyEncoding = {}): NagAction {
   const confirm = adapter.blockingConfirm?.(viewport)
@@ -69,9 +98,26 @@ export function nextNagAction(adapter: NagPredicate, viewport: string, enc: KeyE
       denyBytes: keysToBytes(confirm.denyKeys, enc),
       taxonomy: confirm.taxonomy,
       detail: confirm.detail,
+      alwaysHuman: confirm.alwaysHuman ?? false,
+      brokerKind: 'circuit-breaker',
     }
   const keys = adapter.nagDismissKeys?.(viewport)
   if (keys && keys.length) return { kind: 'dismiss', keys, bytes: keysToBytes(keys, enc) }
+  // GENERIC residue — checked LAST so a known signature always wins its precise keys.
+  const unknown = adapter.unknownBlockingModal?.(viewport)
+  if (unknown)
+    return {
+      kind: 'approve',
+      keys: UNKNOWN_MODAL_ALLOW_KEYS,
+      bytes: keysToBytes(UNKNOWN_MODAL_ALLOW_KEYS, enc),
+      denyKeys: UNKNOWN_MODAL_DENY_KEYS,
+      denyBytes: keysToBytes(UNKNOWN_MODAL_DENY_KEYS, enc),
+      taxonomy: 'unknown-modal',
+      detail: unknown.content,
+      alwaysHuman: true,
+      brokerKind: 'unknown-modal',
+      option1: unknown.option1,
+    }
   return { kind: 'none' }
 }
 

package/src/supervisor/daemon.ts

@@ -94,6 +94,11 @@ const NAG_COOLDOWN_MS = 4000
  *  fire. A genuinely blocked modal freezes the session forever, so a ~10 s delay costs nothing;
  *  a live peer rendering the modal text keeps writing (stream/spinner) and never crosses this. */
 const NAG_STUCK_MS = 10_000
+// docs/17 fork 3 — bound how many times the daemon re-asks a human about a GENERIC unknown modal whose
+// injected keys did NOT clear it (a modal ignoring both option-1 and Esc). After this many answered-but-
+// still-static rounds it logs once and safe-PARKS (the peer stays blocked = safe) instead of looping
+// forever. The counter resets the moment the pane makes progress (writeSeq advances → the modal cleared).
+const MAX_UNKNOWN_MODAL_ATTEMPTS = 3
 // В25 — cap the attach-snapshot stabilization wait: under saturating output the model never goes quiet,
 // so without a budget firstAttach would never complete (frozen attach). On timeout we snapshot the
 // current model; live-forward delivers the rest once the gate lifts.
@@ -689,7 +694,7 @@ export function runSupervisorDaemon(opts: SupervisorDaemonOptions): void {
   // NAG_COOLDOWN_MS so a just-dismissed modal is never double-answered (a stray keystroke would land in
   // the now-visible composer). Only runs for a runtime whose adapter declares nagDismissKeys.
   const nagAdapter = BOOT_ADAPTERS[runtime] as NagPredicate | undefined
-  if (nagAdapter?.nagDismissKeys || nagAdapter?.blockingConfirm) {
+  if (nagAdapter?.nagDismissKeys || nagAdapter?.blockingConfirm || nagAdapter?.unknownBlockingModal) {
     // ── Unit 4 — approval-mode routing for the circuit-breaker ──────────────────────
     // Resolve the peer's approval mode ONCE at watcher setup: the profile is stable for the session (a
     // mid-session flip needs a fresh launch), and re-reading it every tick would hammer the fs. yolo
@@ -711,10 +716,16 @@ export function runSupervisorDaemon(opts: SupervisorDaemonOptions): void {
     const brokerPersonality =
       brokerEnv.PEER_PERSONALITY?.trim() || (session.startsWith(`${runtime}-`) ? session.slice(runtime.length + 1) : session)
     const brokerRuntime = brokerEnv.PEER_RUNTIME?.trim() || runtime
-    // In-flight guard: the setInterval keeps firing while a gated POST is outstanding (the modal stays up,
+    // In-flight guard: the setInterval keeps firing while a broker POST is outstanding (the modal stays up,
     // the pane stays stuck), so gate to EXACTLY ONE broker request per wedged modal.
     let brokerInFlight = false
     let nagFiredMs = 0
+    // docs/17 fork 3 — bounded re-enqueue state for a GENERIC unknown modal. `attempts` counts answered-
+    // but-still-static rounds; `parked` latches after MAX to stop asking. Both reset on pane progress
+    // (writeSeq advance) so a later, DIFFERENT modal is handled fresh.
+    let unknownModalAttempts = 0
+    let unknownModalParked = false
+    let lastNagSeq = -1
     // В60 — stuck-gate: a REAL blocked modal freezes the pty entirely, while a live peer merely
     // RENDERING the modal text (code review / quoted report — the В40 false-fire class) keeps
     // writing. Fire the dismiss ONLY when the pane has been completely static (writeSeq unchanged)
@@ -725,6 +736,13 @@ export function runSupervisorDaemon(opts: SupervisorDaemonOptions): void {
         clearInterval(nagWatch)
         return
       }
+      // Pane made PROGRESS since last tick → the modal (if any) cleared / the peer moved on: reset the
+      // unknown-modal re-enqueue counters so a subsequent, different modal starts a fresh budget.
+      if (writeSeq !== lastNagSeq) {
+        lastNagSeq = writeSeq
+        unknownModalAttempts = 0
+        unknownModalParked = false
+      }
       if (!paneIsStuck(stuckGate, writeSeq, Date.now(), NAG_STUCK_MS)) return // progressing → not a wedged modal
       if (Date.now() - nagFiredMs < NAG_COOLDOWN_MS) return // let a just-answered modal repaint away first
       let action
@@ -738,19 +756,51 @@ export function runSupervisorDaemon(opts: SupervisorDaemonOptions): void {
         child.terminal.write(action.bytes)
         nagFiredMs = Date.now()
       } else if (action.kind === 'approve') {
-        // CIRCUIT-BREAKER confirm (e.g. dangerous-rm) — a headless peer has no human to press it, so it
-        // hangs forever. What we press depends on the peer's approval MODE (resolved once above):
-        if (approvalMode === 'gated') {
-          // GATED — route the confirm to the human-approval broker (docs/17, Unit 4). A blocking POST
-          // awaits a human's allow/deny (≤ broker 300s); routeCircuitBreaker injects the affirmative on
-          // allow, the taxonomy-specific decline on deny (dangerous-rm=2.No / command-approval=3.No), and
-          // fails safe to DENY on any broker fault. The breaker sits ABOVE the permission layer, so this
-          // is the ONLY interceptor for prompts the runtime hook cannot see (dangerous-rm; rm from a
-          // subprocess). Guarded by brokerInFlight so a re-firing tick never opens a second request.
-          if (brokerInFlight) return
+        // A blocking confirm/modal a headless peer can't answer → it hangs forever. WHERE it goes depends
+        // on the class + the peer's approval MODE (resolved once above):
+        //   - alwaysHuman (org-policy / unknown-modal, docs/17 yolo-robustness) → ALWAYS to the human
+        //     broker in EITHER mode. Owner's rule: yolo presses what it KNOWS (max known rights); a modal
+        //     ABOVE us (org-policy) or one we could NOT classify (unknown) I must SEE and confirm — never
+        //     a blind auto-Yes (an unknown modal Anthropic put up on purpose must not be swallowed).
+        //   - known auto-Yes class (dangerous-rm / command-approval): gated → broker, yolo → auto-Yes.
+        const routeToHuman = action.alwaysHuman || approvalMode === 'gated'
+        if (routeToHuman) {
+          if (brokerInFlight) return // one broker request per wedged modal (the tick keeps firing)
+          // BOUNDED re-enqueue for a GENERIC unknown modal whose injected keys may not dismiss it (fork 3):
+          // after MAX_UNKNOWN_MODAL_ATTEMPTS answered rounds that leave the pane STILL static, stop asking —
+          // log once and safe-PARK (the peer stays blocked = safe; never an infinite ask loop nor a blind
+          // Yes). Counters reset on pane progress (loop top). Known classes (org-policy) have precise keys
+          // that DO dismiss, so this bound applies only to the heuristic unknown-modal path.
+          if (action.brokerKind === 'unknown-modal') {
+            if (unknownModalParked) return
+            if (unknownModalAttempts >= MAX_UNKNOWN_MODAL_ATTEMPTS) {
+              unknownModalParked = true
+              try {
+                console.warn(
+                  `[supervisor] UNKNOWN-MODAL PARKED identity=${session} ts=${new Date().toISOString()} attempts=${unknownModalAttempts} — injected keys did not clear it; manual attention needed`,
+                )
+              } catch {
+                /* logging must never break the conduit */
+              }
+              return
+            }
+            unknownModalAttempts++
+          }
+          // Route to the human-approval broker (docs/17). A blocking POST awaits a human's allow/deny (≤
+          // broker 300s); routeCircuitBreaker injects the affirmative on allow, the class-specific decline
+          // on deny (dangerous-rm=2.No / command-approval|org-policy=3.No / unknown-modal=Esc), and fails
+          // 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
           void routeCircuitBreaker(
-            { taxonomy: action.taxonomy, detail: action.detail, approveBytes: action.bytes, denyBytes: action.denyBytes },
+            {
+              taxonomy: action.taxonomy,
+              brokerKind: action.brokerKind,
+              detail: action.detail,
+              option1: action.option1,
+              approveBytes: action.bytes,
+              denyBytes: action.denyBytes,
+            },
             {
               personality: brokerPersonality,
               runtime: brokerRuntime,
@@ -770,7 +820,7 @@ export function runSupervisorDaemon(opts: SupervisorDaemonOptions): void {
           })
           return
         }
-        // YOLO (default) — auto-press YES so a headless peer never hangs (owner decision: restores the
+        // YOLO + known class — auto-press YES so a headless peer never hangs (owner decision: restores the
         // pre-2.1.x bypass status quo). Leave a post-hoc AUDIT line (WHICH peer, WHAT taxonomy + parsed
         // command/target, WHEN) so a rare bad rm is at least visible after the fact. Best-effort log,
         // never gates the keypress.