@agfpd/iapeer 0.4.68 → 0.4.70

package/src/launch/adapters/claude.ts

@@ -23,7 +23,7 @@
 import { homedir } from 'os'
 import { join } from 'path'
 import { readdirSync, realpathSync, statSync } from 'fs'
-import type { ControlCommand, ControlPlan, LaunchAdapterConfig, LaunchSpec, RuntimeAdapter } from '../types.ts'
+import type { ApprovalMode, ControlCommand, ControlPlan, LaunchAdapterConfig, LaunchSpec, RuntimeAdapter } from '../types.ts'
 import { lastTimestampedEntryMs } from './transcriptTail.ts'
 
 // ─────────────────────────────────────────────────────────────────────────────
@@ -129,6 +129,46 @@ function dangerousRmDetail(pane: string): string {
   return [cmd && `cmd=${JSON.stringify(cmd)}`, target && `target=${JSON.stringify(target)}`].filter(Boolean).join(' ') || '(unparsed)'
 }
 
+// Standard command-approval prompt (claude 2.1.201 — the NO-RULE-MATCH passthrough / file-access "ask")
+// needles. This is the prompt a peer sees when it is NOT in bypass — i.e. GATED mode, OR a yolo peer
+// whose bypass the runtime disabled mid-session (the `tengu_disable_bypass_permissions_mode` feature
+// gate / `disableBypassPermissionsMode` setting). Under GENUINE bypass this prompt never surfaces (only
+// the dangerous-rm breaker does — verified from the 2.1.201 permission-gate: bypass auto-allows every
+// `ask` except "Dangerous rm/rmdir operation"). The live render (captured via a nested pty, default
+// mode) is a THREE-option select — "❯ 1. Yes / 2. Yes, and <don't ask again | always allow …> / 3. No"
+// under "Do you want to proceed?" — which is what distinguishes it from the dangerous-rm breaker's
+// TWO-option "1. Yes / 2. No". Split-literal (В40): a peer reviewing this adapter must not self-trigger.
+const ORG_POLICY_APPROVAL = 'organization requires ' + 'approval' // MCP org-restriction — NEVER auto-pressed
+const BASH_CMD_HEADER = 'Bash' + ' command'
+/** FULL-signature + position match for the LIVE standard command-approval prompt. Returns true ONLY for
+ *  the 3-option layout with the bottom-most `❯` cursor on "1. Yes" — so a mere QUOTE of the prompt (ready
+ *  composer `❯` below) never matches. Two hard exclusions satisfy the owner's NARROW-matcher rule:
+ *    · org-policy ("Your organization requires approval for this tool", an MCP restriction) → excluded,
+ *      the owner's org rule is HUMAN-only and must never be auto-pressed;
+ *    · the dangerous-rm breaker → handled by its own taxonomy (checked first in blockingConfirm), and
+ *      structurally excluded here anyway (it is a 2-option "2. No", never "2. Yes," + "3. No"). */
+function isCommandApprovalPrompt(pane: string): boolean {
+  if (!pane.includes(RM_PROCEED)) return false // shares "Do you want to proceed?" with the rm breaker
+  if (pane.includes(ORG_POLICY_APPROVAL)) return false // org-policy → never auto-Yes
+  if (isDangerousRmPrompt(pane)) return false // its own taxonomy owns this pane
+  // 3-option standard layout: option 2 is a "Yes," variant + option 3 is "No" (the rm breaker is
+  // 2-option "1. Yes / 2. No", so it fails BOTH tests — no overlap).
+  if (!/(^|\n)\s*2\.\s*Yes/.test(pane)) return false
+  if (!/(^|\n)\s*3\.\s*No\b/.test(pane)) return false
+  // live-modal position gate: the bottom-most `❯` row must sit on "1. Yes".
+  let lastCursorRow = ''
+  for (const line of pane.split(/\r?\n/)) if (line.includes('❯')) lastCursorRow = line
+  return /❯\s*1\.\s*Yes\b/.test(lastCursorRow)
+}
+/** Best-effort trace of the command the approval prompt guarded — the first non-blank line under the
+ *  "Bash command" block header. Mirrors dangerousRmDetail's post-hoc audit purpose. */
+function commandApprovalDetail(pane: string): string {
+  const lines = pane.split(/\r?\n/)
+  const hi = lines.findIndex(l => l.trim() === BASH_CMD_HEADER)
+  if (hi >= 0) for (let j = hi + 1; j < lines.length; j++) { const t = lines[j].trim(); if (t) return `cmd=${JSON.stringify(t)}` }
+  return '(unparsed)'
+}
+
 // ─────────────────────────────────────────────────────────────────────────────
 // Transcript activity proxy + resume uuid (lifecycle port, claude slug fix)
 // ─────────────────────────────────────────────────────────────────────────────
@@ -228,9 +268,16 @@ export const claudeAdapter: RuntimeAdapter = {
    * NO currency — no marketplace/install/update on this path.
    */
   buildArgv(spec: LaunchSpec, cfg: LaunchAdapterConfig): string[] {
+    // Human-approval mode (docs/17). yolo (default) = '--dangerously-skip-permissions'
+    // (headless bypass, current fleet behavior). gated = NO bypass + an EXPLICIT
+    // '--permission-mode default' so the base is deterministic (never inherits an
+    // acceptEdits/bypass defaultMode from settings): the runtime's permission layer is
+    // active as a fail-SAFE backstop, and the separately-installed PreToolUse hook is
+    // the primary interceptor (it fires regardless of mode — verified live 2.1.201).
+    const gated = spec.approvalMode === 'gated'
     return [
       cfg.claudeBin,
-      '--dangerously-skip-permissions',
+      ...(gated ? ['--permission-mode', 'default'] : ['--dangerously-skip-permissions']),
       '--disallowedTools',
       'AskUserQuestion',
       '--add-dir',
@@ -329,18 +376,30 @@ export const claudeAdapter: RuntimeAdapter = {
   },
 
   /**
-   * Dangerous-rm/rmdir circuit-breaker (RuntimeAdapter.blockingConfirm). Unlike the fullscreen nag
-   * (benign upsell → DECLINE), this guard sits ABOVE `--dangerously-skip-permissions` and hangs a
-   * headless peer forever with no human to answer. Owner decision (Артур, 04.07): auto-press YES —
-   * peers run on bypass, so this only restores the pre-2.1.x status quo, and a hang is real recurring
-   * harm. The default cursor is already on "1. Yes" (verified live), so ['1','Enter'] is the explicit,
-   * position-robust affirmative. Returns the class tag + a one-line command/target trace so the
-   * supervisor logs a post-hoc audit line. NB deliberately NOT a "smart" safe-decline/escalation — that
-   * lands later on the vault idea "Human-approval подтверждения действий пира через Telegram-кнопки".
+   * Blocking-confirm circuit-breaker (RuntimeAdapter.blockingConfirm). Unlike the fullscreen nag
+   * (benign upsell → DECLINE), these guards hang a headless peer forever with no human to answer.
+   * Owner decision (Артур, 04.07): auto-press YES — peers run on bypass, so this only restores the
+   * pre-2.1.x status quo, and a hang is real recurring harm. Two signatures are matched, most-specific
+   * first, each with its own taxonomy so the supervisor's audit log and (later) the human-approval
+   * broker can tell them apart:
+   *   1. 'dangerous-rm' — the rm/rmdir breaker that sits ABOVE `--dangerously-skip-permissions` (the
+   *      ONLY prompt that surfaces under genuine bypass). Default cursor on "1. Yes" (verified live).
+   *   2. 'command-approval' — the STANDARD 3-option approval prompt, surfaced when the peer is NOT in
+   *      bypass: gated mode, or a yolo peer whose bypass the runtime disabled mid-session (feature gate
+   *      / setting). Auto-Yes keeps a yolo peer alive; a gated peer is routed to the human broker by the
+   *      supervisor (Unit 4, mode-aware). Org-policy ("Your organization requires approval for this
+   *      tool") is EXCLUDED by the matcher — the owner's org rule is never auto-pressed.
+   * Both AFFIRM with ['1','Enter'] (the position-robust affirmative — cursor already on "1. Yes"); the
+   * DECLINE keys differ by layout: dangerous-rm is a 2-option "1.Yes/2.No" → ['2','Enter']; command-
+   * approval is a 3-option "1.Yes/2.Yes,…/3.No" → ['3','Enter']. The supervisor presses `keys` (yolo
+   * auto-Yes / gated-approved) or `denyKeys` (gated-denied / broker fail-safe). Each carries a one-line
+   * 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[]; taxonomy: string; detail: string } | null {
-    if (!isDangerousRmPrompt(pane)) return null
-    return { keys: ['1', 'Enter'], taxonomy: 'dangerous-rm', detail: dangerousRmDetail(pane) }
+  blockingConfirm(pane: string): { keys: string[]; denyKeys: string[]; taxonomy: string; detail: string } | 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) }
+    return null
   },
 
   /**
@@ -350,12 +409,20 @@ export const claudeAdapter: RuntimeAdapter = {
    *   - '❯' (U+276F) — the TUI input-prompt glyph, present only at the ready
    *     input row, never in the splash art (claude-start.sh:357-360).
    *   - 'bypass permissions on' — the banner --dangerously-skip-permissions
-   *     emits once booted past the splash.
+   *     emits once booted past the splash (YOLO mode only).
    *   - none of the boot dialogs present (a dialog row can also carry '❯').
+   *
+   * GATED (docs/17): the peer launches WITHOUT --dangerously-skip-permissions, so the
+   * 'bypass permissions on' banner is ABSENT (verified live 2.1.201 — the no-bypass
+   * ready pane is '❯ Try "edit <filepath> to…"', no banner). The ready signal is then
+   * the composer '❯' with every boot dialog cleared. This branch is evaluated ONLY at
+   * BOOT (waitHostReady / the boot-driver), before any tool runs — so a mid-session
+   * '❯'-bearing modal (dangerous-rm / nag) cannot false-positive it.
    */
-  isInputReady(pane: string): boolean {
+  isInputReady(pane: string, mode?: ApprovalMode): boolean {
     if (anyBootDialog(pane)) return false
-    return pane.includes('❯') && pane.includes('bypass permissions on')
+    if (!pane.includes('❯')) return false
+    return mode === 'gated' ? true : pane.includes('bypass permissions on')
   },
 
   /**

package/src/launch/adapters/codex.ts

@@ -43,7 +43,7 @@ import { homedir } from 'os'
 import { join } from 'path'
 import { readdirSync, realpathSync, statSync } from 'fs'
 import { codexSessionCwd, lastTimestampedEntryMs } from './transcriptTail.ts'
-import type { ControlCommand, ControlPlan, LaunchAdapterConfig, LaunchSpec, RuntimeAdapter } from '../types.ts'
+import type { ApprovalMode, ControlCommand, ControlPlan, LaunchAdapterConfig, LaunchSpec, RuntimeAdapter } from '../types.ts'
 
 // ─────────────────────────────────────────────────────────────────────────────
 // Boot dialog markers (watcher.codexUpdate/DirTrust/HooksReview, 253-261)
@@ -199,6 +199,13 @@ export const codexAdapter: RuntimeAdapter = {
    * NO currency — no marketplace/install/update on this path.
    */
   buildArgv(spec: LaunchSpec, cfg: LaunchAdapterConfig): string[] {
+    // Human-approval mode (docs/17). yolo (default) = the YOLO bypass flag (current
+    // fleet behavior). gated = NO bypass + `-c approval_policy=on-request` (the model
+    // asks before acting → the PreToolUse/PermissionRequest hook intercepts) with
+    // `-c sandbox_mode=danger-full-access` — gated gates APPROVALS, it does NOT add a
+    // sandbox (workspace-write would sever the loopback-MCP send_to_peer + vault writes;
+    // sandboxing is a separate axis, not v1). Session-scoped `-c`, never a host-config edit.
+    const gated = spec.approvalMode === 'gated'
     return [
       cfg.codexBin,
       ...(spec.resume ? ['resume', '--last'] : []),
@@ -208,7 +215,9 @@ export const codexAdapter: RuntimeAdapter = {
       ...(spec.systemPromptFile
         ? ['-c', `model_instructions_file=${spec.systemPromptFile}`]
         : []),
-      '--dangerously-bypass-approvals-and-sandbox',
+      ...(gated
+        ? ['-c', 'approval_policy=on-request', '-c', 'sandbox_mode=danger-full-access']
+        : ['--dangerously-bypass-approvals-and-sandbox']),
       ...(spec.extraArgs ?? []),
     ]
   },
@@ -261,7 +270,9 @@ export const codexAdapter: RuntimeAdapter = {
    * composer, and the ready-gate still verifies a real model turn (activity
    * mtime advance) before declaring READY.
    */
-  isInputReady(pane: string): boolean {
+  // mode is accepted for interface parity but ignored: codex's ready marker (the '› '
+  // composer arrow) is the same whether or not it launched with the YOLO bypass flag.
+  isInputReady(pane: string, _mode?: ApprovalMode): boolean {
     if (pane.includes('Press enter to continue')) return false
     return pane.split(/\r?\n/).some(line => line.trimStart().startsWith('› '))
   },

package/src/launch/index.ts

@@ -202,7 +202,7 @@ export const launch: LaunchFn = async (
       // the SAME shape as the tmux boot/deliver/ready-gate below, with host equivalents.
       const baselineMtime = adapter.newestActivityMtime(cwd) ?? 0
       const isReady = await waitHostReady(
-        { identity, logDir: cfg.logDir, adapter, bootDeadlineSecs: cfg.bootDeadlineSecs, paneLogStartByte, env },
+        { identity, logDir: cfg.logDir, adapter, bootDeadlineSecs: cfg.bootDeadlineSecs, paneLogStartByte, approvalMode: spec.approvalMode, env },
         sleep,
       )
       if (!isReady) return fail(identity, 'never-became-ready (hosted: supervisor input surface not ready)')

package/src/launch/ptyHost.ts

@@ -19,7 +19,7 @@ import { parseSessionName } from '../core/socket.ts'
 import type { TmuxRuntime } from '../core/constants.ts'
 import { paneLogViewport } from './readyGateModel.ts'
 import type { LaunchInvocation } from './invocation.ts'
-import type { RuntimeAdapter } from './types.ts'
+import type { ApprovalMode, RuntimeAdapter } from './types.ts'
 
 /** Match the tmux launch geometry (index.ts new-session -x 220 -y 50) so the served child + the
  *  pane-log model render at the same size launch reads readiness at. */
@@ -154,7 +154,7 @@ export async function startPtyHost(b: {
  * 2 s cadence + bootDeadline.
  */
 export async function waitHostReady(
-  b: { identity: string; logDir: string; adapter: RuntimeAdapter; bootDeadlineSecs: number; paneLogStartByte?: number; env?: NodeJS.ProcessEnv },
+  b: { identity: string; logDir: string; adapter: RuntimeAdapter; bootDeadlineSecs: number; paneLogStartByte?: number; approvalMode?: ApprovalMode; env?: NodeJS.ProcessEnv },
   sleep: (ms: number) => Promise<void>,
 ): Promise<boolean> {
   const log = `${b.logDir}/${b.identity}.log`
@@ -168,7 +168,7 @@ export async function waitHostReady(
     await sleep(2000)
     if (!hostSessionAlive(b.identity, b.env)) return false
     const view = await paneLogViewport(log, HOST_COLS, HOST_ROWS, b.paneLogStartByte ?? 0)
-    if (view && b.adapter.isInputReady(view)) return true
+    if (view && b.adapter.isInputReady(view, b.approvalMode)) return true
   }
   return false
 }

package/src/launch/types.ts

@@ -14,8 +14,13 @@
 // be implemented independently against a known contract.
 
 import type { Intelligence, Runtime } from '../core/constants.ts'
+import type { ApprovalMode } from '../identity/index.ts'
 import type { PublicPeerSummary } from '../registry/index.ts'
 
+// Re-export so the adapters (which already import their contract types from here) get
+// ApprovalMode from ONE place rather than reaching into identity directly.
+export type { ApprovalMode }
+
 export type { PublicPeerSummary } from '../registry/index.ts'
 
 // ─────────────────────────────────────────────────────────────────────────────
@@ -159,6 +164,12 @@ export interface LaunchSpec {
    *  less throwaway may omit it, but an adapter that declares requiresIntelligence
    *  then refuses (cannot confirm the required nature). */
   intelligence?: Intelligence
+  /** Human-approval mode (docs/17): `yolo` (default/omitted) launches with the
+   *  runtime bypass flag (current fleet behavior); `gated` launches WITHOUT bypass
+   *  and swaps in the gated permission/approval config, so the runtime's blocking
+   *  requests route to a human via the daemon broker (a PreToolUse hook, installed
+   *  separately at toggle time, is the interceptor). buildArgv reads it. */
+  approvalMode?: ApprovalMode
 }
 
 // ─────────────────────────────────────────────────────────────────────────────
@@ -307,17 +318,25 @@ export interface RuntimeAdapter {
    * settings, or flag disables it). A headless peer has no human to press 1/2, so it HANGS forever
    * (live-observed on a verification session). Owner decision (Артур, 04.07): auto-press YES — peers
    * already run on bypass, so this only restores the pre-2.1.x status quo; a hang is real recurring
-   * harm. Return `{keys, taxonomy, detail}` (the affirmative keys + a class tag + a one-line trace of
-   * WHAT was approved) so the supervisor can press it AND leave a post-hoc log; else null. Match the
-   * FULL signature + cursor position so ordinary content mentioning the phrase never fires. Optional
-   * (codex/router omit it). tui only. FUTURE: replace blind-YES with human approval via Telegram —
-   * see the vault idea "Human-approval подтверждения действий пира через Telegram-кнопки".
+   * harm. Return `{keys, denyKeys, taxonomy, detail}` (the AFFIRMATIVE keys + the taxonomy-specific
+   * DECLINE keys + a class tag + a one-line trace of WHAT was approved) so the supervisor can press
+   * YES on a yolo peer AND leave a post-hoc log, OR route the confirm to the human broker on a gated
+   * peer and press the decision (Unit 4 — allow→keys, deny→denyKeys). `denyKeys` differs by taxonomy
+   * because the modal layouts differ (dangerous-rm is a 2-option "1.Yes/2.No" → `['2','Enter']`;
+   * command-approval is a 3-option "1.Yes/2.Yes,…/3.No" → `['3','Enter']`) — the adapter owns that
+   * layout knowledge, not the supervisor. Match the FULL signature + cursor position so ordinary
+   * 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-кнопки".
    */
-  blockingConfirm?(pane: string): { keys: string[]; taxonomy: string; detail: string } | null
+  blockingConfirm?(pane: string): { keys: string[]; denyKeys: string[]; taxonomy: string; detail: 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). */
-  isInputReady(pane: string): boolean
+   *  AND startup dialogs gone). Router runtimes return true (no input surface).
+   *  `mode` (default yolo) lets a runtime whose READY marker differs by approval mode
+   *  pick the right one — claude's yolo ready banner ('bypass permissions on') is
+   *  absent under gated (launched WITHOUT --dangerously-skip-permissions). */
+  isInputReady(pane: string, mode?: ApprovalMode): boolean
 
   /** Newest activity-proxy FILE mtime — used by the READY-GATE (it waits for ANY transcript write past
    *  baseline = "the model produced its first turn"). NOT for idle accounting: a live session re-saves

package/src/lifecycle/index.ts

@@ -28,7 +28,7 @@ import { buildProcessAddress, buildSocketPath, parseSessionName } from '../core/
 import { err, ok, type Result } from '../core/errors.ts'
 import { capPaneLogs } from '../launch/cmdlog.ts'
 import { resolveGlobalRoot } from '../storage/index.ts'
-import { readPeerProfile, resolveIdentity } from '../identity/index.ts'
+import { approvalModeOf, readPeerProfile, resolveIdentity, type ApprovalMode } from '../identity/index.ts'
 import {
   ephemeralQueueDepth,
   listQueuedIdentities,
@@ -600,6 +600,18 @@ export function isEphemeralPeer(cwd: string): boolean {
   }
 }
 
+/** The effective human-approval mode of the peer at `cwd` — `gated` iff its profile
+ *  persists it, else the default `yolo`. A profile read hiccup → `yolo` (safe default:
+ *  the current-fleet behavior; never gates a peer we cannot read). The single cwd-level
+ *  reader the launch/supervisor/fleet paths call (default lives in approvalModeOf). */
+export function peerApprovalMode(cwd: string): ApprovalMode {
+  try {
+    return approvalModeOf(readPeerProfile(cwd))
+  } catch {
+    return 'yolo'
+  }
+}
+
 /**
  * Decide resume vs fresh on a wake (TARGET redesign). Branch order:
  *   1. argsResume === false (folder-launch `iapeer <runtime>`) → FRESH.
@@ -1112,6 +1124,9 @@ export async function wakeOrSpawn(args: WakeArgs, deps: WakeDeps = {}): Promise<
       // Carry the peer's nature so the launch primitive can enforce an adapter's
       // intelligence gate (telegram requires natural). From the registry record.
       intelligence: peer.intelligence,
+      // Human-approval mode from the LOCAL profile (docs/17): drives the runtime
+      // bypass flag + gated permission/approval config in buildArgv. Default yolo.
+      approvalMode: peerApprovalMode(cwd),
     }
     const launchCfg: LaunchConfig = {
       claudeBin: cfg.claudeBin,

package/src/supervisor/approvalRoute.ts

@@ -0,0 +1,76 @@
+// Supervisor circuit-breaker → human-approval routing (Unit 4, docs/17). The GATED half of the
+// nag-watcher's 'approve' branch: instead of auto-pressing YES (the yolo status-quo), POST the breaker
+// to the daemon approval broker, block on a human's allow/deny, and inject the decided keys into the
+// pty — the AFFIRMATIVE keys on allow, the taxonomy-specific DECLINE keys on deny.
+//
+// FAIL-SAFE by construction: ANY broker failure (daemon unreachable, abort/timeout, non-200) resolves
+// to DENY (inject the decline keys), NEVER auto-Yes — this is the engineering basis of gated=fail-safe
+// (a gated peer under a supervision fault falls back to the safe answer, not the permissive one). The
+// breaker still sits ABOVE the permission layer, so this is the ONLY interceptor for the prompts the
+// runtime hook cannot see (dangerous-rm; an rm from a subprocess/script).
+//
+// IO is injected (fetch, the pty-write, the log, the clock), so the routing + fail-safe + key selection
+// are unit-testable without a live daemon or a real pty.
+
+import { requestApproval, resolveFleetBase, type ApprovalDecision } from '../approval/brokerClient.ts'
+
+export interface BreakerApprovalInput {
+  /** Class tag — 'dangerous-rm' | 'command-approval'. Sent as the broker `tool` + `summary`. */
+  taxonomy: string
+  /** Best-effort one-line command/target trace parsed off the pane. Sent as the broker `content`. */
+  detail: 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). */
+  denyBytes: Buffer
+}
+
+export interface BreakerRouteDeps {
+  personality: string
+  runtime: string
+  env: NodeJS.ProcessEnv
+  /** Inject keys into the pty (child.terminal.write). */
+  write: (bytes: Buffer) => void
+  /** Injectable fetch (tests). */
+  fetch?: typeof fetch
+  /** Injectable client timeout (tests). */
+  timeoutMs?: number
+  /** Post-hoc audit line (console.warn in prod; a spy in tests). */
+  log?: (line: string) => void
+  /** Injectable clock (tests). Default Date.now. */
+  now?: () => number
+}
+
+/**
+ * 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.
+ */
+export async function routeCircuitBreaker(input: BreakerApprovalInput, deps: BreakerRouteDeps): Promise<ApprovalDecision> {
+  const now = deps.now ?? Date.now
+  let decision: ApprovalDecision
+  try {
+    decision = await requestApproval(
+      resolveFleetBase(deps.env),
+      {
+        personality: deps.personality,
+        runtime: deps.runtime,
+        kind: 'circuit-breaker',
+        tool: input.taxonomy,
+        content: input.detail,
+        summary: input.taxonomy,
+      },
+      { env: deps.env, fetch: deps.fetch, timeoutMs: deps.timeoutMs },
+    )
+  } catch (e) {
+    // Broker unreachable / abort / non-200 → DENY (never auto-Yes). gated = fail-safe.
+    decision = { decision: 'deny', reason: `iapeer approval unavailable (${e instanceof Error ? e.message : String(e)}) — denied fail-safe` }
+  }
+  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
+}

package/src/supervisor/boot.ts

@@ -38,12 +38,14 @@ export function nextBootAction(adapter: BootPredicates, viewport: string, enc: K
  *  claudeAdapter satisfies both; codex/router omit them → no action. */
 export interface NagPredicate {
   nagDismissKeys?(pane: string): string[] | null
-  blockingConfirm?(pane: string): { keys: string[]; taxonomy: string; detail: string } | null
+  blockingConfirm?(pane: string): { keys: string[]; denyKeys: string[]; taxonomy: string; detail: string } | null
 }
 
 export type NagAction =
   | { kind: 'dismiss'; keys: string[]; bytes: Buffer } // benign upsell — press keys silently
-  | { kind: 'approve'; keys: string[]; bytes: Buffer; taxonomy: string; detail: string } // circuit-breaker — press keys + LOG
+  // 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 }
   | { kind: 'none' }
 
 /**
@@ -59,7 +61,15 @@ export type NagAction =
 export function nextNagAction(adapter: NagPredicate, viewport: string, enc: KeyEncoding = {}): NagAction {
   const confirm = adapter.blockingConfirm?.(viewport)
   if (confirm && confirm.keys.length)
-    return { kind: 'approve', keys: confirm.keys, bytes: keysToBytes(confirm.keys, enc), taxonomy: confirm.taxonomy, detail: confirm.detail }
+    return {
+      kind: 'approve',
+      keys: confirm.keys,
+      bytes: keysToBytes(confirm.keys, enc),
+      denyKeys: confirm.denyKeys,
+      denyBytes: keysToBytes(confirm.denyKeys, enc),
+      taxonomy: confirm.taxonomy,
+      detail: confirm.detail,
+    }
   const keys = adapter.nagDismissKeys?.(viewport)
   if (keys && keys.length) return { kind: 'dismiss', keys, bytes: keysToBytes(keys, enc) }
   return { kind: 'none' }

package/src/supervisor/daemon.ts

@@ -31,6 +31,8 @@ import { newStuckGate, nextBootAction, nextNagAction, paneIsStuck, type BootPred
 import { modelToPlainText } from './render.ts'
 import { codexAdapter } from '../launch/adapters/codex.ts'
 import { claudeAdapter } from '../launch/adapters/claude.ts'
+import { approvalModeOf, readPeerProfile, type ApprovalMode } from '../identity/index.ts'
+import { routeCircuitBreaker } from './approvalRoute.ts'
 
 /** Resolve a runtime launcher from the host AT CALL TIME — env override (IAPEER_<RT>_BIN, the same
  *  knob the rest of the foundation uses) → PATH lookup — never a baked machine-specific path. Returns
@@ -688,6 +690,30 @@ export function runSupervisorDaemon(opts: SupervisorDaemonOptions): void {
   // 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) {
+    // ── 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
+    // (default) → the breaker AUTO-presses YES as before (restores the pre-2.1.x bypass status quo,
+    // owner decision). gated → the breaker ROUTES the confirm to the human-approval broker (blocking
+    // POST, inject the human's Yes/No). approvalModeOf is the ONE "absent⇒yolo" default — never
+    // re-derived here; an unreadable/malformed profile → yolo (approvalModeOf(null)), the safe backstop
+    // (a gated peer only launched WITHOUT bypass because the SAME profile read gated moments earlier).
+    let approvalMode: ApprovalMode = 'yolo'
+    try {
+      approvalMode = approvalModeOf(readPeerProfile(opts.cwd ?? runDir))
+    } catch {
+      /* unreadable / malformed profile → yolo default */
+    }
+    // Broker identity: prefer the composed child-env ABI (PEER_PERSONALITY/RUNTIME, invocation.ts), else
+    // derive from the session name (`<runtime>-<personality>`) by STRIPPING the runtime prefix — the
+    // personality itself may carry a '-', so never split on the first dash.
+    const brokerEnv = opts.env ?? process.env
+    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,
+    // the pane stays stuck), so gate to EXACTLY ONE broker request per wedged modal.
+    let brokerInFlight = false
     let nagFiredMs = 0
     // В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
@@ -712,12 +738,42 @@ 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) — press the affirmative so a headless peer never
-        // hangs on it (owner decision: auto-YES restores the pre-2.1.x bypass status quo). Leave a
-        // post-hoc AUDIT line in the supervisor's own log (console → logPath): WHICH peer (session),
-        // WHAT (taxonomy + the parsed command/target), WHEN (ts). A rare bad rm is then at least visible
-        // after the fact — the interim before human-approval (Telegram) lands. Best-effort log, never
-        // gates the keypress.
+        // 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
+          brokerInFlight = true
+          void routeCircuitBreaker(
+            { taxonomy: action.taxonomy, detail: action.detail, approveBytes: action.bytes, denyBytes: action.denyBytes },
+            {
+              personality: brokerPersonality,
+              runtime: brokerRuntime,
+              env: brokerEnv,
+              write: b => child.terminal.write(b),
+              log: line => {
+                try {
+                  console.warn(line)
+                } catch {
+                  /* logging must never break the conduit */
+                }
+              },
+            },
+          ).finally(() => {
+            brokerInFlight = false
+            nagFiredMs = Date.now() // just answered → let the (now-clearing) modal repaint away before re-check
+          })
+          return
+        }
+        // YOLO (default) — 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.
         child.terminal.write(action.bytes)
         nagFiredMs = Date.now()
         try {

package/src/tray/index.ts

@@ -150,3 +150,28 @@ export async function trayCmd(
   const { status, body } = await fleetPostJson(addr, path, runtime ? { runtime } : {}, env)
   return { ok: status < 400, status, body }
 }
+
+export type ApprovalVerb = 'approve' | 'deny'
+
+/**
+ * Resolve a pending human-approval from the tray: POST /fleet/v1/approvals/<id>/(approve|deny) over
+ * the SAME unix-first fleet client trayCmd uses — the proxy-safe transport (the absolute-form-misroute
+ * grabli: a peer's Happ proxy would otherwise mangle a loopback POST). Tags `via:'tray'` for the audit
+ * trail; the single-queue invariant means this resolution is seen by every channel (CLI/telegram). A
+ * 404 (already resolved / expired) surfaces as ok=false with the daemon's message — the caller reports
+ * it (the request the user saw was answered elsewhere first).
+ */
+export async function trayResolveApproval(
+  env: NodeJS.ProcessEnv,
+  decision: ApprovalVerb,
+  id: string,
+  reason?: string,
+): Promise<TrayCmdResult> {
+  const addr = resolveFleetAddress({ env })
+  if (addr.fleet !== 1 || (!addr.sock && !addr.tcp)) {
+    return { ok: false, status: 0, body: { error: 'fleet daemon unreachable (no fleet:1 in router.json)' } }
+  }
+  const path = `/fleet/v1/approvals/${encodeURIComponent(id)}/${decision}`
+  const { status, body } = await fleetPostJson(addr, path, { via: 'tray', ...(reason ? { reason } : {}) }, env)
+  return { ok: status < 400, status, body }
+}