@agfpd/iapeer 0.4.78 → 0.4.79

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/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@agfpd/iapeer",
-  "version": "0.4.78",
+  "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