@agfpd/iapeer 0.4.77 → 0.4.79

package/docs/16-tray.md

@@ -34,24 +34,28 @@ activation that also installs SwiftBar.app when it is absent.
     a human is attached, `🔒` launchd-managed (H4 read-only), `🛡` the peer runs in **gated**
     human-approval mode (docs/17; `yolo` is the fleet default and carries no badge — a bare
     row reads as yolo), `⏳N` an ephemeral peer's queue depth.
-  - **Click an agent peer → Terminal.app running `iapeer attach <peer>`.** The row itself is
-    the attach action (no submenu, so a click attaches rather than merely expanding). The
-    handoff goes through `iapeer tray attach-term`, which writes a per-peer `.command`
-    launcher and `open`s it — `open <file>.command` hands the file to Terminal.app with
-    **no Automation/Accessibility permission prompt**. This deliberately avoids SwiftBar's
-    own `terminal=true`, whose Terminal launch drives a `Cmd-T` System-Events keystroke that
-    silently no-ops unless SwiftBar holds Accessibility permission. **Launchd-managed infra
-    peers (telegram / notifier, `🔒`) are not pty-attachable** — their rows are plain status
-    lines. Lifecycle actions (Stop / Start / New / Interrupt / Refresh / Compact) live
-    in the **Manage** submenu, each a `POST /fleet/v1/peers/<peer>/<cmd>` via `iapeer tray cmd`.
-    (No Wake item — a peer-row click already wakes a sleeping peer before it attaches, so
-    it was redundant.) For an agentic peer the Manage submenu also carries an
-    **approval-mode toggle** (docs/17): it reads the current mode and flips it via the local
-    `iapeer approval-mode <peer> <mode>` verb, applied on the peer's **next fresh session**
-    (a click never respawns a live session). The friction is asymmetric to the security
-    weight: `yolo → gated` (adds human approval) is one safe tap; `gated → yolo` (REMOVES the
-    approval perimeter) sits behind the submenu as an explicit red ⚠ confirm, so it is never
-    dropped by a stray click.
+  - **Each peer is a SUBMENU** — one unified list (no separate Manage section; the peer rows
+    and a parallel Manage list of every peer used to be a visible dupe). Clicking a peer
+    EXPANDS it; its actions are the children, in order:
+    - **Attach** (agent peers only) — the FIRST child. Runs `iapeer tray attach-term <peer>`,
+      which writes a per-peer `.command` launcher and `open`s it — `open <file>.command` hands
+      the file to Terminal.app with **no Automation/Accessibility permission prompt** (this
+      deliberately avoids SwiftBar's own `terminal=true`, whose Terminal launch drives a `Cmd-T`
+      System-Events keystroke that silently no-ops unless SwiftBar holds Accessibility). Attach
+      is now expand-then-Attach (two clicks) — the trade for a single dupe-free list.
+    - **Lifecycle** — Stop / Start / New / Interrupt / Refresh / Compact, each a
+      `POST /fleet/v1/peers/<peer>/<cmd>` via `iapeer tray cmd`. (No Wake item — a peer-row
+      click path already wakes a sleeping peer before it attaches, so it was redundant.)
+    - **Approval-mode toggle** (agent peers only, docs/17): reads the current mode and flips it
+      via the local `iapeer approval-mode <peer> <mode>` verb, applied on the peer's **next fresh
+      session** (a click never respawns a live session). The friction is asymmetric to the
+      security weight: `yolo → gated` (adds human approval) is one safe tap; `gated → yolo`
+      (REMOVES the approval perimeter) sits one level deeper behind an explicit red ⚠ confirm, so
+      it is never dropped by a stray click.
+
+    **Launchd-managed infra peers (telegram / notifier, `🔒`)** are not pty-attachable, so their
+    submenu carries **no Attach** and **no approval toggle** (always yolo) — just the lifecycle
+    commands (service Stop / Start etc.).
 - **Pending approvals (docs/17):** when the queue is non-empty, the **top of the dropdown** shows
   each pending request **expanded, with no extra clicks** — a header (`<peer> · <tool>`), the
   **verbatim action content** (the command / diff / plan, monospace, capped for the menu; the FULL

package/docs/17-approval.md

@@ -4,7 +4,7 @@ A peer can run in one of two **approval modes**. In `yolo` (the default — ever
 
 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.
 
-`gated` means **«ask before acting»**, not «sandboxed». It removes the bypass so blocking questions surface; it does **not** add an OS sandbox (a separate axis, not in v1). On codex, gated is explicitly `approvals ON + sandbox OFF` (see the toggle table).
+`gated` means **«ask before acting»** — blocking questions surface instead of being bypassed. On **claude**, gated stays sandbox-free (the `PermissionRequest` hook is the interceptor). On **codex**, gated is the EXEMPLAR (reframe 07.07): it runs `approvals ON + a workspace-write sandbox` so codex shows its **OWN native approval modal** in the TUI on a risky action — an attached human answers it right there — while the supervisor proxies that same modal to the bar. iapeer installs **no broker hook** on gated codex (a `PreToolUse` hook would silence the native modal). The shared memory vault (outside every peer cwd) is granted writable so routine memory writes never prompt. See the codex toggle table.
 
 ## The approval-mode toggle
 
@@ -37,17 +37,17 @@ The bypass is a **launch argument**, different per runtime, and the mode is a co
 
 **Why matcher-free `PermissionRequest`, not `PreToolUse`.** `PermissionRequest` fires **only when the runtime's permission config decided to prompt** — a call not covered by an allow/deny rule. So the policy of *what to ask* stays 100% at the runtime: a user tunes it with ordinary permission rules (a tool in `permissions.allow` is never asked → the hook never fires → auto-allowed). No class matcher to drift, no new tool slipping through, no hang. iapeer only seeds the hook + the one allow-rule for the peer's own MCP tool.
 
-**codex** (`PreToolUse` hook — verified live, codex-cli 0.142.5):
+**codex** (native modal + supervisor proxy — codex-cli 0.142.5):
 
 | # | Surface | yolo | gated |
 |---|---|---|---|
 | X1 | argv `--dangerously-bypass-approvals-and-sandbox` | present | **removed** |
-| X2 | argv approval/sandbox | (bypass) | `-c approval_policy=on-request -c sandbox_mode=danger-full-access` — approvals **ON**, sandbox **OFF** (so loopback-MCP `send_to_peer` + writes to the memory vault outside cwd still work; `workspace-write` would cut the network and external paths). Session-scoped via `-c`, not host config. |
-| X3 | `PreToolUse` hook `<cwd>/.codex/hooks.json` + trust pre-seed in `~/.codex/config.toml [hooks.state]` | **absent** | **installed + trusted** (`preSeedCodexHooksTrust`; an untrusted codex hook is silently skipped) |
+| X2 | argv approval/sandbox | (bypass) | `-c approval_policy=on-request -c sandbox_mode=workspace-write -c sandbox_workspace_write.network_access=false` (+ `-c sandbox_workspace_write.writable_roots=[…]` when the host has a memory vault). approvals **ON**, an OS sandbox that makes cwd/`/tmp`/`$TMPDIR` + the vault silent and a risky write (outside those) or outbound network pop codex's **native modal**. The old `danger-full-access` was disproven by the live sandbox matrix (07.07): `send_to_peer` (MCP) is unaffected by the sandbox because Seatbelt wraps the shell CHILDREN codex spawns, not the codex process, so the loopback MCP call is never sandboxed; and the vault is restored via `writable_roots`. Session-scoped via `-c`, not host config. |
+| X3 | `PreToolUse` broker hook | **absent** | **absent** — gated codex relies on its NATIVE modal + the supervisor proxy, so iapeer installs no broker hook (it would silence the native modal). A prior (pre-reframe) hook is removed on the next gated toggle. |
 | X4 | codex cwd-trust `[projects."<cwd>"] trust_level="trusted"` | pre-trusted (both modes) | pre-trusted (matters more with approvals active) |
 | X5 | ready-gate `isInputReady` (`›` composer) | mode-independent | unchanged |
 
-The codex hook is matched by tool-name regex `^(Bash|Shell|shell|local_shell|exec|apply_patch|ApplyPatch)$` — the coarse class matcher lives on the runtime's own `hooks.json` (the user tunes it as ordinary runtime config).
+The gated↔yolo difference for codex is thus ONLY the launch config + the profile field (no hooks.json either way), so the round-trip is byte-identical by construction. (The `iapeer approval-hook` binary + its codex `allow`→abstain shaping stay in the tree — still correct for any deny-by-rule hook an operator adds, and for claude — they are simply not installed by the codex gated toggle.)
 
 ### Idempotency and the application moment
 
@@ -62,7 +62,7 @@ All surfaces are read/applied **at session start**. A **live session keeps its l
 Both runtimes carry a Claude-compatible **hook** system that intercepts an approval programmatically and returns `allow`/`deny` + a reason + the structured action content. That is the primary mechanism. **pty screen-scrape is a backstop for one class only** — claude's `dangerous-rm` circuit-breaker, which sits *above* the permission layer and no hook can see.
 
 - **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.
+- **codex** — gated codex is NOT hook-gated (reframe): it runs `approval_policy=on-request` + a `workspace-write` sandbox and shows its **own native modal**, which the supervisor pty-scrape catches and routes (see below). The `iapeer approval-hook` binary still exists and its codex path is correct (verified live 0.142.5: codex fires `PreToolUse` with `tool_name:"Bash"`; a `deny` hard-blocks the tool and the reason reaches the model; a codex `allow` is unsupported by codex's `PreToolUse` so the hook **abstains** on allow rather than emitting a rejected decision) — but the codex gated toggle does not install it. It remains available for a deny-by-rule hook an operator wires by hand.
 - **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.
@@ -81,6 +81,8 @@ The supervisor nag-watcher classifies every mid-session blocking TUI modal it ob
 - **`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).
 
+> **This is exactly the path that surfaces gated codex's native approval modal** (the reframe). Verified live (codex-cli 0.142.5): a write outside the workspace/writable roots yields `Would you like to run the following command? … › 1. Yes, proceed (y) / 2. … / 3. No, and tell Codex what to do differently (esc) — Press enter to confirm or esc to cancel`. The footer matches the select-footer signature, so `detectNumberedModal('›')` catches it; **Allow = option 1** ("Yes, proceed") and **Deny = Esc** (which is codex's own "No" option here), so the generic binary injection is exactly right for it. So gated codex needs no bespoke breaker — it rides this same generic path, and an attached human can equally answer the modal in the TUI.
+
 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»)

package/docs/ru/16-tray.md

@@ -32,22 +32,28 @@ SwiftBar.app, если его нет.
     `👤` подключён человек, `🔒` под launchd (H4 read-only), `🛡` пир в режиме **gated**
     human-approval (docs/17; `yolo` — дефолт флота, без бейджа: голая строка читается как yolo),
     `⏳N` глубина очереди эфемерного пира.
-  - **Клик по агент-пиру → Terminal.app с `iapeer attach <peer>`.** Строка сама и есть действие
-    attach (без подменю — клик аттачит, а не раскрывает). Передача идёт через `iapeer tray
-    attach-term`: пишет per-peer `.command`-лаунчер и `open`'ит его — `open <файл>.command`
-    отдаёт файл Terminal.app **без запроса Automation/Accessibility**. Это намеренно обходит
-    родной `terminal=true` SwiftBar, чей запуск Terminal бьёт `Cmd-T` кейстроком через System
-    Events и молча не срабатывает без права Accessibility у SwiftBar. **Launchd-инфра-пиры
-    (telegram / notifier, `🔒`) не pty-аттачатся** — их строки просто статус. Lifecycle-действия
-    (Stop / Start / New / Interrupt / Refresh / Compact) — в подменю **Manage**, каждое —
-    `POST /fleet/v1/peers/<peer>/<cmd>` через `iapeer tray cmd`. (Пункта Wake нет — клик по строке
-    пира и так будит спящего перед аттачем, отдельный Wake был избыточен.) Для агентного пира
-    подменю Manage несёт ещё **переключатель approval-режима** (docs/17): читает текущий режим и
-    флипает его локальным verb'ом `iapeer approval-mode <peer> <mode>`, применяется на **следующей
-    свежей сессии** пира (клик никогда не респавнит живую сессию). Трение асимметрично весу
-    безопасности: `yolo → gated` (добавляет human-approval) — один безопасный тап; `gated → yolo`
-    (СНИМАЕТ периметр approval) спрятан в подменю как явный красный ⚠ confirm, чтобы его не сбросить
-    случайным кликом.
+  - **Каждый пир — ПОДМЕНЮ** — один единый список (без отдельной секции Manage; строки пиров и
+    параллельный Manage-список всех пиров раньше были видимым дублем). Клик по пиру РАСКРЫВАЕТ
+    его; действия — дочерние пункты, по порядку:
+    - **Attach** (только агент-пиры) — ПЕРВЫЙ пункт. Запускает `iapeer tray attach-term <peer>`:
+      пишет per-peer `.command`-лаунчер и `open`'ит его — `open <файл>.command` отдаёт файл
+      Terminal.app **без запроса Automation/Accessibility** (намеренно обходит родной
+      `terminal=true` SwiftBar, чей запуск Terminal бьёт `Cmd-T` кейстроком через System Events и
+      молча не срабатывает без права Accessibility). Attach теперь = раскрыть-и-Attach (два клика) —
+      плата за единый список без дубля.
+    - **Lifecycle** — Stop / Start / New / Interrupt / Refresh / Compact, каждое —
+      `POST /fleet/v1/peers/<peer>/<cmd>` через `iapeer tray cmd`. (Пункта Wake нет — путь клика по
+      пиру и так будит спящего перед аттачем, отдельный Wake избыточен.)
+    - **Переключатель approval-режима** (только агент-пиры, docs/17): читает текущий режим и флипает
+      локальным verb'ом `iapeer approval-mode <peer> <mode>`, применяется на **следующей свежей
+      сессии** пира (клик никогда не респавнит живую сессию). Трение асимметрично весу безопасности:
+      `yolo → gated` (добавляет human-approval) — один безопасный тап; `gated → yolo` (СНИМАЕТ
+      периметр approval) на уровень глубже за явным красным ⚠ confirm, чтобы не сбросить случайным
+      кликом.
+
+    **Launchd-инфра-пиры (telegram / notifier, `🔒`)** не pty-аттачатся — их подменю несёт **без
+    Attach** и **без approval-переключателя** (всегда yolo), только lifecycle-команды (Stop / Start
+    сервиса и т.д.).
 - **Ожидающие подтверждения (docs/17):** когда очередь непуста, **вверху выпадашки** каждый
   ожидающий запрос показан **раскрытым, без доп. кликов** — заголовок (`<peer> · <tool>`),
   **дословное содержимое действия** (команда / диф / план, моноширинно, усечено для меню; ПОЛНОЕ

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@agfpd/iapeer",
-  "version": "0.4.77",
+  "version": "0.4.79",
   "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/install.ts

@@ -188,12 +188,21 @@ export function setApprovalMode(cwd: string, mode: ApprovalMode, env: NodeJS.Pro
       if (mode === 'gated') surfaces.push(`claude: ${installClaudeApproval(cwd, env) ? 'PermissionRequest hook + MCP allow-rule installed' : 'settings write SKIPPED (non-object)'}`)
       else surfaces.push(`claude: ${removeClaudeApproval(cwd) ? 'hook + allow-rule removed' : 'nothing to remove'}`)
     } else if (rt === 'codex') {
-      if (mode === 'gated') {
-        const r = installCodexApproval(cwd, env)
-        surfaces.push(`codex: ${r ? `hooks.json installed + trust ${r.trust?.state ?? '?'}` : 'hooks.json write SKIPPED'}`)
-      } else {
-        surfaces.push(`codex: ${removeCodexApproval(cwd, env) ? 'hooks.json + trust removed' : 'trust cleared (no hooks.json)'}`)
-      }
+      // Gated codex is the EXEMPLAR (docs/17 reframe, 07.07): it shows its OWN native approval modal
+      // (from the on-request / workspace-write launch config in codex buildArgv) and the SUPERVISOR
+      // proxies that modal to the bar (unknownBlockingModal → routeCircuitBreaker). So iapeer installs
+      // NO broker PreToolUse hook on gated codex — the hook would SILENCE the native modal (its whole
+      // pre-reframe purpose). We still REMOVE any hook a prior (pre-reframe) gated toggle left behind, so
+      // an existing peer migrates cleanly to the native-modal model. yolo is identical (no hook). The
+      // gated↔yolo difference for codex is now ONLY the launch config + the profile field, not hooks.json
+      // — so the round-trip stays byte-identical. (claude keeps its PermissionRequest broker hook — its
+      // native prompt is what that hook cleanly intercepts; only codex switched to the native-modal model.)
+      const removed = removeCodexApproval(cwd, env)
+      surfaces.push(
+        mode === 'gated'
+          ? `codex: native modal + supervisor proxy, no broker hook${removed ? ' (cleared prior hook)' : ''}`
+          : `codex: ${removed ? 'hooks.json + trust removed' : 'trust cleared (no hooks.json)'}`,
+      )
     }
   }
   return { mode, surfaces }

package/src/launch/adapters/codex.ts

@@ -209,13 +209,32 @@ 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.
+    // Human-approval mode (docs/17). yolo (default) = the YOLO bypass flag (current fleet behavior).
+    //
+    // gated = codex as the EXEMPLAR (docs/17 reframe, 07.07): the peer shows its OWN NATIVE approval
+    // modal in the TUI on a risky action — an attached human approves right there — while the supervisor
+    // proxies that same modal to the bar (unknownBlockingModal → routeCircuitBreaker → broker card). So
+    // gated launches WITHOUT the bypass and WITHOUT a broker PreToolUse hook (the hook would SILENCE the
+    // native modal — that was the pre-reframe design; setApprovalMode no longer installs it on gated
+    // codex). The config, session-scoped `-c` (never a host-config edit):
+    //   - `approval_policy=on-request` — the model asks before a non-auto-approved action → native modal.
+    //   - `sandbox_mode=workspace-write` — writes to the peer cwd (+ /tmp, $TMPDIR) are SILENT; a write
+    //     OUTSIDE those is blocked → native modal. This SUPERSEDES the old `danger-full-access` (whose
+    //     comment claimed ws-write would sever MCP + vault writes — DISPROVEN by the live sandbox matrix
+    //     07.07): send_to_peer (MCP) goes THROUGH regardless of network_access because Seatbelt wraps the
+    //     shell CHILDREN codex spawns, not the codex process itself, so the loopback MCP call is never
+    //     sandboxed; and the vault is restored to writable via writable_roots just below.
+    //   - `sandbox_workspace_write.writable_roots=[…]` — the extra roots (the shared memory vault, which
+    //     lives OUTSIDE every peer cwd) so ROUTINE memory writes stay silent instead of popping the modal.
+    //     Omitted when spec.writableRoots is empty (no memory provider). The value is a TOML inline array
+    //     of strings — JSON.stringify yields exactly that (paths quoted, `"`/`\` escaped); launch shell-
+    //     quotes the whole `-c` element once, so spaces/`~` in the path arrive intact. Array `-c` form
+    //     verified live (codex-cli 0.142.5).
+    //   - `sandbox_workspace_write.network_access=false` — pin outbound network OFF (the ws-write default,
+    //     set explicitly so a codex default change can't silently open it). Real outbound stays a risk →
+    //     native modal; MCP send_to_peer is unaffected (see above).
     const gated = spec.approvalMode === 'gated'
+    const roots = spec.writableRoots ?? []
     return [
       cfg.codexBin,
       ...(spec.resume ? ['resume', '--last'] : []),
@@ -226,7 +245,15 @@ export const codexAdapter: RuntimeAdapter = {
         ? ['-c', `model_instructions_file=${spec.systemPromptFile}`]
         : []),
       ...(gated
-        ? ['-c', 'approval_policy=on-request', '-c', 'sandbox_mode=danger-full-access']
+        ? [
+            '-c',
+            'approval_policy=on-request',
+            '-c',
+            'sandbox_mode=workspace-write',
+            ...(roots.length > 0 ? ['-c', `sandbox_workspace_write.writable_roots=${JSON.stringify(roots)}`] : []),
+            '-c',
+            'sandbox_workspace_write.network_access=false',
+          ]
         : ['--dangerously-bypass-approvals-and-sandbox']),
       ...(spec.extraArgs ?? []),
     ]
@@ -259,13 +286,16 @@ export const codexAdapter: RuntimeAdapter = {
   },
 
   /**
-   * 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.
+   * GENERIC unknown blocking-modal detector (docs/17 — yolo-robustness) — AND, since the gated reframe
+   * (07.07), the catcher for codex's OWN NATIVE approval modal. codex declares no blockingConfirm: under
+   * yolo the bypass flag means no modal ever shows; under gated codex shows its native `approval_policy=
+   * on-request` / sandbox modal, which is a numbered `›` select — so THIS structural detector (bottom-most
+   * `›` is a numbered option + ≥2 options; see modalDetect.ts) is what surfaces it to the human, exactly
+   * like a truly-unforeseen modal. The daemon routes it to the human (bar card) with explicit button
+   * semantics + the timing stuck-gate on top; an ATTACHED human can equally answer it in the TUI directly.
+   * Known boot dialogs (owned by the boot-driver) are excluded first. NB modalDetect keys on a SELECT
+   * FOOTER (isSelectFooter) — that the codex approval modal's footer matches it is a LIVE-verified
+   * invariant (docs/17 §gated-codex); a codex footer that ever diverges would need its own signature here.
    */
   unknownBlockingModal(pane: string): { content: string; option1: string } | null {
     if (isKnownCodexBlockingSignature(pane)) return null

package/src/launch/types.ts

@@ -175,6 +175,13 @@ export interface LaunchSpec {
    *  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
+  /** Extra sandbox-writable roots BEYOND the peer cwd, for a gated codex peer launched under
+   *  `sandbox_mode=workspace-write` (docs/17). Consumed ONLY by codex's gated buildArgv (emitted as
+   *  `-c sandbox_workspace_write.writable_roots=[…]`) — claude/router/yolo ignore it, the same
+   *  codex-only shape as `disallowedTools` is claude-only. Resolved at spec-build from the host's
+   *  memory provider (the shared vault lives OUTSIDE every peer cwd, so a memory write would otherwise
+   *  hit codex's native modal); empty/omitted → no extra roots. */
+  writableRoots?: string[]
 }
 
 // ─────────────────────────────────────────────────────────────────────────────

package/src/lifecycle/index.ts

@@ -28,6 +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 { resolveMemoryWritableRoots } from '../status/index.ts'
 import { approvalModeOf, readPeerProfile, resolveIdentity, type ApprovalMode } from '../identity/index.ts'
 import {
   ephemeralQueueDepth,
@@ -1109,6 +1110,17 @@ export async function wakeOrSpawn(args: WakeArgs, deps: WakeDeps = {}): Promise<
       ? composePeerPrompt(peer, cwd, identity, cfg, env, peersIndex.peers.map(publicPeerSummary))
       : undefined
 
+    // Human-approval mode from the LOCAL profile (docs/17): drives the runtime bypass flag +
+    // gated permission/approval config in buildArgv. Default yolo. Resolved ONCE — also gates the
+    // writable-roots resolution below.
+    const approvalMode = peerApprovalMode(cwd)
+    // Extra sandbox-writable roots for a GATED CODEX peer (docs/17): under sandbox_mode=workspace-write
+    // a write outside the peer cwd (a memory note into the shared vault) is BLOCKED and pops codex's
+    // native modal, so the vault is granted at launch. Resolved from the host's memory provider ONLY when
+    // it can matter (codex + gated) — a yolo/claude wake never reads it. codex's gated buildArgv consumes
+    // it; every other path ignores the field. Fail-open (empty when no memory provider).
+    const writableRoots = runtime === 'codex' && approvalMode === 'gated' ? resolveMemoryWritableRoots(env) : undefined
+
     // Hand the fully-resolved spec to the launch primitive (HOW). lifecycle has
     // made every WHEN/HOW-MANY decision (lock, registry, H4, runtime, resume).
     const spec: LaunchSpec = {
@@ -1124,9 +1136,8 @@ 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),
+      approvalMode,
+      ...(writableRoots && writableRoots.length > 0 ? { writableRoots } : {}),
     }
     const launchCfg: LaunchConfig = {
       claudeBin: cfg.claudeBin,

package/src/status/index.ts

@@ -13,7 +13,7 @@
 import { closeSync, openSync, readFileSync, statSync } from 'fs'
 import { join } from 'path'
 import { IAPEER_VERSION } from '../core/version.ts'
-import { resolveGlobalRoot } from '../storage/index.ts'
+import { resolveGlobalRoot, pluginInstallDir } from '../storage/index.ts'
 import { daemonDiscoveryPath } from '../daemon/index.ts'
 import { waitForDaemonHealthy } from '../update/index.ts'
 import { iapeerBinPath } from '../install/index.ts'
@@ -112,6 +112,67 @@ export function heartbeatAgeSecs(provider: { heartbeat?: string }, nowMs: number
   }
 }
 
+// ─────────────────────────────────────────────────────────────────────────────
+// Sandbox writable roots for a gated codex peer (docs/17). A gated codex session
+// launches under `sandbox_mode=workspace-write`: writes to its own cwd (+ /tmp,
+// $TMPDIR) are silent, but a write OUTSIDE those — a memory note into the shared
+// vault, which lives in iCloud OUTSIDE every peer cwd — is BLOCKED and pops codex's
+// native approval modal. Routine memory writes must not prompt, so the vault is added
+// to `sandbox_workspace_write.writable_roots` at launch. This resolves those extra
+// writable root(s) for the host (empty when the host has no memory provider).
+// ─────────────────────────────────────────────────────────────────────────────
+
+/** config.env key the memory provider records its vault path under. */
+const MEMORY_VAULT_ENV_KEY = 'IAPEER_MEMORY_VAULT_PATH'
+
+/**
+ * Extra sandbox-writable roots a gated codex peer needs beyond its cwd — the memory vault
+ * on a host that has a memory provider, else empty.
+ *
+ * INTERIM TECHDEBT (v1 — a durable, tracked debt, NOT a permanent design): the vault path is
+ * read from the provider's OPERATOR-OWNED `config.env` (`IAPEER_MEMORY_VAULT_PATH`), located via
+ * the provider name the memory SLOT declares. This deliberately BYPASSES the slot contract — the
+ * slot (`memory-provider.json`) is the ONLY declarative foundation↔provider boundary; `config.env`
+ * is the provider's PRIVATE surface. It is read-only and fail-open, but it IS a side-coupling that a
+ * future change to the slot contract must be aware of. Why the bypass: the slot is single-writer
+ * (the provider), so foundation cannot populate a vault field itself, and adding one is a cross-repo
+ * change to `@agfpd/iapeer-memory` + its release — a disproportionate cost that would block delivery
+ * on a foreign deploy. FOLLOW-UP (the way out of the debt): promote the data root INTO the slot (a
+ * `MemoryProvider.dataRoots` field the provider writes) so foundation reads it from the declared
+ * contract and this `config.env` read is retired.
+ *
+ * Fail-open at every step: no memory slot / no config.env / no key / a non-absolute value → `[]`. A
+ * gated codex peer still works with an empty result — only a cross-vault write would then prompt (a
+ * safe degraded state, never a break). Uses the injected `env` for path resolution (IAPEER_ROOT-aware
+ * → sandbox-isolated in tests, exactly like the rest of the storage layer).
+ */
+export function resolveMemoryWritableRoots(env: NodeJS.ProcessEnv = process.env): string[] {
+  const slot = readMemoryProvider(env)
+  if (!slot) return [] // no memory provider on this host → no vault to grant
+  try {
+    const cfgPath = join(pluginInstallDir(slot.provider, { env }), 'config.env')
+    const text = readFileSync(cfgPath, 'utf8')
+    for (const rawLine of text.split(/\r?\n/)) {
+      const line = rawLine.trim()
+      if (!line || line.startsWith('#')) continue
+      const m = /^(?:export\s+)?([A-Za-z_][A-Za-z0-9_]*)=(.*)$/.exec(line)
+      if (!m || m[1] !== MEMORY_VAULT_ENV_KEY) continue
+      let value = m[2].trim()
+      if (
+        value.length >= 2 &&
+        ((value.startsWith('"') && value.endsWith('"')) || (value.startsWith("'") && value.endsWith("'")))
+      ) {
+        value = value.slice(1, -1)
+      }
+      // Absolute path only — a relative writable_root is meaningless to codex's sandbox.
+      return value.startsWith('/') ? [value] : []
+    }
+    return [] // key absent from config.env
+  } catch {
+    return [] // unreadable config.env — fail-open to bare
+  }
+}
+
 // ─────────────────────────────────────────────────────────────────────────────
 // VOICE slot — the voice-connect provider declaration (the same declarative
 // contract as memory, two differences by design: NO provision/unprovision (voice

package/src/tray/render.ts

@@ -198,19 +198,17 @@ export function renderSwiftBar(snapshot: TraySnapshot, opts: RenderOptions): str
   if (providers) lines.push(line(0, providers, { color: COLOR.meta }))
   lines.push('---')
 
-  // ── peers (each row is a DIRECT attach action — click → Terminal) ──
+  // ── peers — each peer is a SUBMENU: expand → Attach (first) + its actions. ONE list
+  //    (no separate Manage section): the peer rows and their lifecycle used to be two
+  //    parallel lists of every peer (a click-attach list + a Manage list) — a visible
+  //    dupe. Folded here (owner decision — 2 clicks to attach: expand peer → Attach). ──
   if (peers.length === 0) {
     lines.push(line(0, 'no peers registered', { color: COLOR.meta }))
   }
   for (const p of peers) {
-    lines.push(renderPeerRow(p, bin, now, pendingByPeer.get(p.personality) ?? 0))
+    lines.push(...renderPeerSubmenu(p, bin, now, pendingByPeer.get(p.personality) ?? 0))
   }
 
-  // ── Manage submenu (lifecycle commands per peer; kept off the rows so a row click
-  //    attaches instead of just expanding a submenu) ──
-  lines.push('---')
-  lines.push(...renderManage(peers, bin))
-
   // ── footer ──
   // No explicit "Refresh" item: the plugin is streamable + SSE-driven, so the menu is
   // always current on open — a manual refresh gives the user nothing and (being a
@@ -243,64 +241,52 @@ function attachable(p: TrayPeer): boolean {
   return !p.launchd_managed
 }
 
-/**
- * One peer row. For an ATTACHABLE peer the row IS a DIRECT attach action (no submenu,
- * so a click attaches instead of merely expanding): clicking runs `iapeer tray
- * attach-term <peer>` in the BACKGROUND (terminal=false), which opens a `.command` via
- * `open` — a system-Terminal handoff that needs NO Accessibility/Automation TCC. This
- * deliberately AVOIDS SwiftBar's own `terminal=true`, whose Terminal.app launch drives a
- * `Cmd-T` System-Events keystroke that silently no-ops without Accessibility permission.
- * Infra (launchd) rows are plain status lines. Lifecycle lives in the Manage submenu.
- */
-function renderPeerRow(p: TrayPeer, bin: string, now: number, pendingCount = 0): string {
-  const agg = aggregate(p)
+/** The status label for a peer's submenu-parent row: `<peer>  <rt><glyph> … <badges> <age>`.
+ *  Badges: 👤 attached · 🔒 launchd · 🛡 gated approval (docs/17; yolo=fleet default=no badge) ·
+ *  ⏳N ephemeral queue. A pending approval prepends ⚠ + a 🔴N count so the owner sees WHICH peer
+ *  waits (the Allow/Deny itself lives in the top approvals section, not here). */
+function peerLabel(p: TrayPeer, now: number, pendingCount: number): string {
   const detail = p.runtimes.map(r => `${r.runtime}${GLYPH[r.status]}`).join(' ')
-  // approval mode (docs/17): the whole fleet defaults to `yolo`, so showing it on every row is
-  // noise — mark ONLY the exception, `gated` (this peer's blocking approvals go to a human), with a
-  // 🛡 shield. No badge ⇒ yolo (the default; also how a pre-approval snapshot with the field absent
-  // renders). So the row reads the mode: 🛡 = gated, bare = yolo.
   const badges =
     (p.attached ? ' 👤' : '') +
     (p.launchd_managed ? ' 🔒' : '') +
     (p.approval_mode === 'gated' ? ' 🛡' : '') +
     (p.wake_policy === 'ephemeral' && (p.queue_depth ?? 0) > 0 ? ` ⏳${p.queue_depth}` : '')
   const ageStr = p.last_active_ms ? `  ${fmtAge(p.last_active_ms, now)}` : ''
-  // HIGHLIGHT a peer with a pending approval: a ⚠ prefix + a red count badge + the row painted red
-  // so the owner sees WHICH peer is waiting (owner criterion — the static-menu equivalent of a pulse;
-  // SwiftBar cannot animate). The highlight wins over the live/meta color.
   const prefix = pendingCount > 0 ? '⚠ ' : ''
   const pendingBadge = pendingCount > 0 ? ` 🔴${pendingCount}` : ''
-  const label = `${prefix}${p.personality}  ${detail}${badges}${pendingBadge}${ageStr}`
-  const rowColor = pendingCount > 0 ? COLOR.down : agg === 'live' ? COLOR.live : COLOR.meta
-  if (!attachable(p)) return line(0, label, { color: rowColor })
-  return line(0, label, { color: rowColor, bash: bin, param1: 'tray', param2: 'attach-term', param3: p.personality, terminal: false })
+  return `${prefix}${p.personality}  ${detail}${badges}${pendingBadge}${ageStr}`
 }
 
-/** The Manage submenu: one sub-submenu per peer with its lifecycle commands, each a
- *  `iapeer tray cmd <c> <peer>` → POST /fleet/v1/peers/<peer>/<c> (terminal=false,
- *  refresh to reflect the outcome). Kept OFF the peer rows so a row click attaches. */
-function renderManage(peers: TrayPeer[], bin: string): string[] {
-  const out: string[] = [line(0, 'Manage', { sfimage: 'slider.horizontal.3' })]
-  for (const p of peers) {
-    out.push(line(1, p.personality))
-    for (const c of MANAGE_COMMANDS) {
-      // No refresh=true: the SSE stream reflects the command's lifecycle event on its
-      // own (streamable is always fresh); a refresh would only restart the stream.
-      out.push(
-        line(2, c.label, {
-          bash: bin,
-          param1: 'tray',
-          param2: 'cmd',
-          param3: c.cmd,
-          param4: p.personality,
-          terminal: false,
-        }),
-      )
-    }
-    // approval-mode toggle — only for agentic (attachable) peers; meaningless for the
-    // human channel / notifier infra (arthur/timer/watcher), which are always yolo.
-    if (attachable(p)) out.push(...renderApprovalToggle(p, bin))
+/**
+ * One peer as a SUBMENU (single unified list — no separate Manage). The parent row is the
+ * status label (no direct action — clicking EXPANDS); the children are, in order:
+ *   1. **Attach** (agentic peers only) — the terminal handoff, unchanged (0.4.67): `iapeer tray
+ *      attach-term <peer>` in the BACKGROUND (terminal=false) opens a `.command` via `open`, needing
+ *      NO Accessibility/Automation TCC (avoids SwiftBar's `terminal=true` Cmd-T keystroke). This is
+ *      the ONE trade Arthur accepted: attach is now expand-then-Attach (2 clicks) for a dupe-free list.
+ *   2. lifecycle commands (Stop/Start/New/Interrupt/Refresh/Compact) — `iapeer tray cmd <c> <peer>`.
+ *   3. approval-mode toggle (agentic peers only — docs/17).
+ *
+ * Launchd-managed peers (arthur/timer/watcher, 🔒): NO Attach (no pty session) and NO approval toggle
+ * (always yolo); they keep the lifecycle submenu (service Stop/Start etc — the SAME set the old Manage
+ * already offered them, just relocated under the peer). Per-infra-type trimming (e.g. dropping
+ * Interrupt/Compact for the human peer) is a separate call, out of scope for a de-dupe render change.
+ */
+function renderPeerSubmenu(p: TrayPeer, bin: string, now: number, pendingCount = 0): string[] {
+  const rowColor = pendingCount > 0 ? COLOR.down : aggregate(p) === 'live' ? COLOR.live : COLOR.meta
+  const out: string[] = [line(0, peerLabel(p, now, pendingCount), { color: rowColor })]
+  // 1) Attach FIRST (agentic only — launchd infra/human peers have no pty session to attach)
+  if (attachable(p)) {
+    out.push(line(1, 'Attach', { bash: bin, param1: 'tray', param2: 'attach-term', param3: p.personality, terminal: false }))
+  }
+  // 2) lifecycle commands — each `iapeer tray cmd <c> <peer>` → POST /fleet/v1/peers/<peer>/<c>.
+  //    No refresh=true: the SSE stream reflects the outcome (streamable is always fresh).
+  for (const c of MANAGE_COMMANDS) {
+    out.push(line(1, c.label, { bash: bin, param1: 'tray', param2: 'cmd', param3: c.cmd, param4: p.personality, terminal: false }))
   }
+  // 3) approval-mode toggle (agentic only)
+  if (attachable(p)) out.push(...renderApprovalToggle(p, bin, 1))
   return out
 }
 
@@ -325,7 +311,7 @@ function renderManage(peers: TrayPeer[], bin: string): string[] {
  * stray click. SwiftBar has no native confirm dialog — the nested explicit item IS the
  * confirm.
  */
-function renderApprovalToggle(p: TrayPeer, bin: string): string[] {
+function renderApprovalToggle(p: TrayPeer, bin: string, depth: number): string[] {
   const flip = (target: 'gated' | 'yolo'): Record<string, string | boolean> => ({
     bash: bin,
     param1: 'approval-mode',
@@ -337,12 +323,12 @@ function renderApprovalToggle(p: TrayPeer, bin: string): string[] {
   if (p.approval_mode === 'gated') {
     // WEAKEN — current on the parent (no action); the flip is an explicit red confirm child.
     return [
-      line(2, 'Approval: gated 🛡', { color: COLOR.warn }),
-      line(3, '⚠ Switch to yolo — removes human approval (next session)', { color: COLOR.down, ...flip('yolo') }),
+      line(depth, 'Approval: gated 🛡', { color: COLOR.warn }),
+      line(depth + 1, '⚠ Switch to yolo — removes human approval (next session)', { color: COLOR.down, ...flip('yolo') }),
     ]
   }
   // STRENGTHEN (yolo → gated) — safe, one tap.
-  return [line(2, 'Approval: yolo → gated 🛡 (next session)', flip('gated'))]
+  return [line(depth, 'Approval: yolo → gated 🛡 (next session)', flip('gated'))]
 }
 
 // ── approval renderers (docs/17 — the always-on approval channel in the bar) ─────