optio-codex 0.1.0__py3-none-any.whl

optio_codex/conversation_listener.py

@@ -0,0 +1,322 @@
+"""Per-task conversation listener — the opt-in dashboard gate for optio-codex.
+
+Exposes one running CodexConversation over HTTP, reached through the optio-api
+widget proxy (which injects the basic-auth credential):
+
+  GET  /events     — SSE: replay buffer first, then live tail. SSE id: is a
+                     monotonic seq; Last-Event-ID resumes without dupes.
+  POST /send       — {text}                 -> conversation.send
+  POST /interrupt  — {}                     -> conversation.interrupt
+  POST /model      — {model}                -> conversation.request_model_change
+                     (INLINE: pins the next turn/start's model — no restart)
+  POST /upload     — multipart {file} parts -> upload_writer; returns
+                     {ok, files:[{filename, path}]}
+  GET  /download   — ?path=<relpath>        -> download_reader; returns the
+                     bytes with Content-Disposition: attachment
+  POST /permission — {request_id, behavior, updated_input?, message?}
+                     resolves the pending requestApproval future.
+
+Structurally mirrors optio-grok's ConversationListener (itself from
+optio-claudecode's). Permissions are correlated by the JSON-RPC ``id`` of the
+``item/commandExecution/requestApproval`` / ``item/fileChange/requestApproval``
+server request — CodexConversation hands the whole JSON-RPC object to the
+handler as ``PermissionRequest.raw``.
+
+Projection principle: this listener only observes and forwards; attaching or
+detaching viewers never influences task state.
+"""
+from __future__ import annotations
+
+import asyncio
+import base64
+import json
+import logging
+from collections import deque
+from typing import Awaitable, Callable
+
+from aiohttp import web
+
+from optio_agents.conversation import ConversationClosed, PermissionDecision
+
+_LOG = logging.getLogger(__name__)
+
+BUFFER_MAXLEN = 1000
+PING_INTERVAL_S = 15.0
+# Bound aiohttp's graceful-shutdown wait so the long-lived /events SSE loop
+# cannot stall the session's cooperative-cancel teardown past its grace period.
+SHUTDOWN_TIMEOUT_S = 2.0
+# Sentinel pushed into each subscriber queue on stop() so the SSE handler loop
+# returns immediately instead of parking until the next ping timeout.
+_STOP = object()
+
+
+class ConversationListener:
+    def __init__(
+        self, conversation, *, password: str,
+        upload_writer: "Callable[[str, bytes], Awaitable[str]] | None" = None,
+        max_upload_bytes: int = 10_000_000,
+        download_reader: "Callable[[str], Awaitable[tuple[bytes, str]]] | None" = None,
+        max_download_bytes: int = 10_000_000,
+    ) -> None:
+        self._conversation = conversation
+        self._password = password
+        self._upload_writer = upload_writer
+        self._max_upload_bytes = max_upload_bytes
+        self._download_reader = download_reader
+        self._max_download_bytes = max_download_bytes
+        self._buffer: deque[tuple[int, dict]] = deque(maxlen=BUFFER_MAXLEN)
+        self._seq = 0
+        self._subscribers: set[asyncio.Queue] = set()
+        self._pending_permissions: dict[str, asyncio.Future] = {}
+        self._runner: web.AppRunner | None = None
+        self._unsubscribe = conversation.on_event(self._on_event)
+        conversation.on_permission_request(self._on_permission_request)
+
+    # -- event intake --------------------------------------------------------
+
+    def _broadcast(self, event: dict) -> None:
+        self._seq += 1
+        item = (self._seq, event)
+        self._buffer.append(item)
+        for q in list(self._subscribers):
+            q.put_nowait(item)
+
+    def _on_event(self, event: dict) -> None:
+        self._broadcast(event)
+
+    # -- permission gate -----------------------------------------------------
+
+    async def _on_permission_request(self, request) -> PermissionDecision:
+        # The raw requestApproval request already reached viewers via _on_event;
+        # here we only park until some operator POSTs /permission with its
+        # JSON-RPC id. CodexConversation stores the whole JSON-RPC request object
+        # as PermissionRequest.raw, so `id` is the correlation key.
+        request_id = str(request.raw.get("id"))
+        fut: asyncio.Future = asyncio.get_running_loop().create_future()
+        self._pending_permissions[request_id] = fut
+        try:
+            decision: PermissionDecision = await fut
+        finally:
+            self._pending_permissions.pop(request_id, None)
+        self._broadcast({
+            "type": "x-optio-permission-answered",
+            "request_id": request_id,
+            "behavior": decision.behavior,
+        })
+        return decision
+
+    # -- HTTP handlers -------------------------------------------------------
+
+    def _authorized(self, request: web.Request) -> bool:
+        # The widget proxy injects BasicAuth(username="optio", password=...).
+        auth = request.headers.get("Authorization", "")
+        if not auth.startswith("Basic "):
+            return False
+        try:
+            userpass = base64.b64decode(auth[6:]).decode("utf-8")
+        except Exception:  # noqa: BLE001
+            return False
+        return userpass == f"optio:{self._password}"
+
+    async def _handle_events(self, request: web.Request) -> web.StreamResponse:
+        if not self._authorized(request):
+            return web.json_response({"ok": False}, status=401)
+        resp = web.StreamResponse(headers={
+            "Content-Type": "text/event-stream",
+            "Cache-Control": "no-cache",
+            "X-Accel-Buffering": "no",
+        })
+        await resp.prepare(request)
+
+        async def send_item(seq: int, event: dict) -> None:
+            payload = json.dumps(event)
+            await resp.write(f"id: {seq}\ndata: {payload}\n\n".encode("utf-8"))
+
+        last_id = 0
+        raw_last = request.headers.get("Last-Event-ID", "")
+        if raw_last.isdigit():
+            last_id = int(raw_last)
+
+        queue: asyncio.Queue = asyncio.Queue()
+        # Subscribe BEFORE replay so no event falls between replay and tail;
+        # the seq check below dedupes any overlap.
+        self._subscribers.add(queue)
+        try:
+            sent_through = last_id
+            for seq, event in list(self._buffer):
+                if seq > sent_through:
+                    await send_item(seq, event)
+                    sent_through = seq
+            while True:
+                try:
+                    item = await asyncio.wait_for(
+                        queue.get(), timeout=PING_INTERVAL_S,
+                    )
+                except asyncio.TimeoutError:
+                    await resp.write(b": ping\n\n")
+                    continue
+                if item is _STOP:
+                    break  # stop() asked us to close so teardown can proceed
+                seq, event = item
+                if seq > sent_through:
+                    await send_item(seq, event)
+                    sent_through = seq
+        except (ConnectionResetError, asyncio.CancelledError):
+            pass
+        finally:
+            self._subscribers.discard(queue)
+        return resp
+
+    async def _handle_send(self, request: web.Request) -> web.Response:
+        if not self._authorized(request):
+            return web.json_response({"ok": False}, status=401)
+        try:
+            payload = await request.json()
+        except Exception:  # noqa: BLE001
+            return web.json_response({"ok": False, "reason": "bad-json"}, status=400)
+        text = payload.get("text")
+        if not isinstance(text, str) or not text:
+            return web.json_response({"ok": False, "reason": "bad-text"}, status=400)
+        try:
+            await self._conversation.send(text)
+        except ConversationClosed:
+            return web.json_response({"ok": False, "reason": "closed"}, status=409)
+        return web.json_response({"ok": True})
+
+    async def _handle_interrupt(self, request: web.Request) -> web.Response:
+        if not self._authorized(request):
+            return web.json_response({"ok": False}, status=401)
+        try:
+            await self._conversation.interrupt()
+        except ConversationClosed:
+            return web.json_response({"ok": False, "reason": "closed"}, status=409)
+        return web.json_response({"ok": True})
+
+    async def _handle_upload(self, request: web.Request) -> web.Response:
+        if not self._authorized(request):
+            return web.json_response({"ok": False}, status=401)
+        if self._upload_writer is None:
+            return web.json_response({"ok": False, "reason": "no-writer"}, status=409)
+        stored: list[dict] = []
+        try:
+            reader = await request.multipart()
+        except Exception:  # noqa: BLE001
+            return web.json_response({"ok": False, "reason": "bad-multipart"}, status=400)
+        while True:
+            part = await reader.next()
+            if part is None:
+                break
+            if part.name != "file":
+                continue
+            filename = part.filename or "file"
+            buf = bytearray()
+            while True:
+                chunk = await part.read_chunk()
+                if not chunk:
+                    break
+                buf.extend(chunk)
+                if len(buf) > self._max_upload_bytes:
+                    return web.json_response({"ok": False, "reason": "too-large"}, status=413)
+            path = await self._upload_writer(filename, bytes(buf))
+            stored.append({"filename": filename, "path": path})
+        return web.json_response({"ok": True, "files": stored})
+
+    async def _handle_download(self, request: web.Request) -> web.Response:
+        if not self._authorized(request):
+            return web.json_response({"ok": False}, status=401)
+        if self._download_reader is None:
+            return web.json_response({"ok": False, "reason": "no-reader"}, status=409)
+        path = request.query.get("path")
+        if not path:
+            return web.json_response({"ok": False, "reason": "bad-path"}, status=400)
+        try:
+            data, mime = await self._download_reader(path)
+        except FileNotFoundError:
+            return web.json_response({"ok": False, "reason": "not-found"}, status=404)
+        except ValueError as e:
+            reason = str(e)
+            status = 413 if reason == "too-large" else 403
+            return web.json_response({"ok": False, "reason": reason}, status=status)
+        base = path.split("/")[-1] or "file"
+        return web.Response(
+            body=data,
+            headers={
+                "Content-Type": mime,
+                "Content-Disposition": f'attachment; filename="{base}"',
+            },
+        )
+
+    async def _handle_model(self, request: web.Request) -> web.Response:
+        if not self._authorized(request):
+            return web.json_response({"ok": False}, status=401)
+        try:
+            payload = await request.json()
+        except Exception:  # noqa: BLE001
+            return web.json_response({"ok": False, "reason": "bad-json"}, status=400)
+        model = payload.get("model")
+        if not isinstance(model, str) or not model:
+            return web.json_response({"ok": False, "reason": "bad-model"}, status=400)
+        try:
+            self._conversation.request_model_change(model)
+        except ConversationClosed:
+            return web.json_response({"ok": False, "reason": "closed"}, status=409)
+        return web.json_response({"ok": True})
+
+    async def _handle_permission(self, request: web.Request) -> web.Response:
+        if not self._authorized(request):
+            return web.json_response({"ok": False}, status=401)
+        try:
+            payload = await request.json()
+        except Exception:  # noqa: BLE001
+            return web.json_response({"ok": False, "reason": "bad-json"}, status=400)
+        request_id = str(payload.get("request_id", ""))
+        behavior = payload.get("behavior")
+        if behavior not in ("allow", "deny"):
+            return web.json_response({"ok": False, "reason": "bad-behavior"}, status=400)
+        fut = self._pending_permissions.get(request_id)
+        if fut is None or fut.done():
+            return web.json_response({"ok": False, "reason": "unknown-request"}, status=404)
+        fut.set_result(PermissionDecision(
+            behavior=behavior,
+            updated_input=payload.get("updated_input"),
+            message=payload.get("message"),
+        ))
+        return web.json_response({"ok": True})
+
+    # -- lifecycle -----------------------------------------------------------
+
+    async def start(self, bind_iface: str) -> int:
+        app = web.Application()
+        app.router.add_get("/events", self._handle_events)
+        app.router.add_post("/send", self._handle_send)
+        app.router.add_post("/interrupt", self._handle_interrupt)
+        app.router.add_post("/model", self._handle_model)
+        app.router.add_post("/upload", self._handle_upload)
+        app.router.add_get("/download", self._handle_download)
+        app.router.add_post("/permission", self._handle_permission)
+        self._runner = web.AppRunner(app, shutdown_timeout=SHUTDOWN_TIMEOUT_S)
+        await self._runner.setup()
+        site = web.TCPSite(self._runner, bind_iface, 0)
+        await site.start()
+        # Read the OS-assigned port back from the bound server socket.
+        server = site._server  # aiohttp exposes the asyncio.Server here
+        return server.sockets[0].getsockname()[1]
+
+    async def stop(self) -> None:
+        # Idempotent: teardown paths may call stop() more than once. Make the
+        # unsubscribe one-shot so a second call can't double-remove the handler.
+        unsubscribe = self._unsubscribe
+        self._unsubscribe = lambda: None
+        unsubscribe()
+        for fut in self._pending_permissions.values():
+            if not fut.done():
+                fut.set_result(PermissionDecision(
+                    behavior="deny", message="optio harness: session ending",
+                ))
+        # Wake every open /events handler so it returns now, instead of letting
+        # runner.cleanup() wait for the long-lived SSE loops.
+        for queue in list(self._subscribers):
+            queue.put_nowait(_STOP)
+        if self._runner is not None:
+            await self._runner.cleanup()
+            self._runner = None

optio_codex/cred_watcher.py

@@ -0,0 +1,138 @@
+"""In-session credential save-back for codex seeds.
+
+Codex's ChatGPT-mode ``auth.json`` holds a **single-use rotating refresh
+token** (``tokens.refresh_token``): the manager proactively refreshes after
+8 days (``TOKEN_REFRESH_INTERVAL``, manager.rs) and on any 401, rewriting
+auth.json in place — and a used refresh token invalidates every other copy
+(openai/codex#15410, by design). That is the exact failure mode
+optio-opencode's watcher was built for and optio-grok ported; this module
+is the codex adaptation (credential path ``<workdir>/home/.codex/auth.json``).
+OpenAI's own CI/CD guidance is the same restore -> run -> persist pattern.
+
+The watcher keeps the seed current by writing the changed in-session
+auth.json back into the existing seed, plus a final backstop at teardown.
+It also renews the seed's pool lease each tick and aborts the session on
+lease loss (a new holder must never rotate the same token concurrently).
+The seed is the single source of truth for credentials.
+"""
+
+from __future__ import annotations
+
+import asyncio
+import hashlib
+import json
+import logging
+from typing import Callable
+
+from optio_host.host import Host
+
+from optio_agents import seeds
+from optio_codex.seed_manifest import CODEX_CRED_MANIFEST, CODEX_SEED_SUFFIX
+
+_LOG = logging.getLogger(__name__)
+
+CRED_WATCH_INTERVAL_S = 10.0
+_CRED_RELPATH = "home/.codex/auth.json"
+
+
+def _auth_valid(data: object) -> bool:
+    """True iff ``data`` is one of codex's two live auth shapes: ChatGPT
+    mode (``tokens`` non-null) or API-key mode (``OPENAI_API_KEY``
+    non-null). A logged-out ``{}``/null-tokens file is invalid — saving it
+    back would clobber a good seed."""
+    if not isinstance(data, dict) or not data:
+        return False
+    return data.get("tokens") is not None or data.get("OPENAI_API_KEY") is not None
+
+
+async def cred_fingerprint(host: Host) -> str | None:
+    """SHA-256 of the live ``home/.codex/auth.json``, or None when it is
+    missing, unparseable, or logged-out (nothing worth saving back).
+
+    Guards against corrupting a seed with a half-written / logged-out file —
+    the codex analog of opencode's provider-entry gate, tightened to codex's
+    two documented auth shapes (tokens / OPENAI_API_KEY).
+    """
+    path = f"{host.workdir.rstrip('/')}/{_CRED_RELPATH}"
+    try:
+        raw = await host.fetch_bytes_from_host(path)
+    except FileNotFoundError:
+        return None
+    try:
+        data = json.loads(raw.decode("utf-8"))
+    except (ValueError, UnicodeDecodeError):
+        return None
+    if not _auth_valid(data):
+        return None
+    return hashlib.sha256(raw).hexdigest()
+
+
+async def capture_gate_ok(host: Host) -> bool:
+    """Gate for seed CAPTURE: a valid ``auth.json`` is present.
+
+    Codex, like grok, has no separate model requirement (the model lives in
+    ``config.toml`` and is optional), so a valid credential is the whole
+    gate. Save-back uses ``cred_fingerprint`` directly; this is the terminal
+    capture gate."""
+    return await cred_fingerprint(host) is not None
+
+
+async def save_back_if_changed(
+    ctx,
+    host: Host,
+    *,
+    seed_id: str,
+    baseline: str | None,
+    encrypt: "Callable[[bytes], bytes] | None",
+    decrypt: "Callable[[bytes], bytes] | None",
+) -> str | None:
+    """If the live auth.json differs from ``baseline`` and is valid, save it
+    back into the seed and return the new fingerprint. Otherwise return
+    ``baseline`` unchanged. Never raises — save-back is best-effort."""
+    fp = await cred_fingerprint(host)
+    if fp is None or fp == baseline:
+        return baseline
+    try:
+        await seeds.refresh_seed(
+            ctx, host, seed_id=seed_id, manifest=CODEX_CRED_MANIFEST,
+            suffix=CODEX_SEED_SUFFIX, encrypt=encrypt, decrypt=decrypt,
+        )
+        _LOG.info("seed %s: auth.json saved back", seed_id)
+        return fp
+    except Exception:
+        _LOG.exception("seed %s: auth.json save-back failed", seed_id)
+        return baseline
+
+
+async def run_credential_watcher(
+    ctx,
+    host: Host,
+    *,
+    seed_id: str,
+    baseline: str | None,
+    encrypt: "Callable[[bytes], bytes] | None",
+    decrypt: "Callable[[bytes], bytes] | None",
+    lease_holder: str | None = None,
+) -> None:
+    """Poll every ``CRED_WATCH_INTERVAL_S``: save back the rotated auth.json,
+    and (when ``lease_holder`` is set) renew the seed's lease. If the lease
+    is lost, signal the session to stop (set the cancellation flag) and exit
+    — continuing would mean a token-rotation collision with the new holder.
+
+    Runs until cancelled. Best-effort save-back; lease-loss is decisive."""
+    current = baseline
+    while True:
+        await asyncio.sleep(CRED_WATCH_INTERVAL_S)
+        current = await save_back_if_changed(
+            ctx, host, seed_id=seed_id, baseline=current,
+            encrypt=encrypt, decrypt=decrypt,
+        )
+        if lease_holder is not None:
+            ok = await seeds.renew_lease(
+                ctx._db, prefix=ctx._prefix, suffix=CODEX_SEED_SUFFIX,
+                seed_id=seed_id, holder=lease_holder,
+            )
+            if not ok:
+                _LOG.warning("seed %s: lease lost; aborting session", seed_id)
+                ctx.cancellation_flag.set()
+                return

optio_codex/fs_allowlist.py

@@ -0,0 +1,149 @@
+"""Settings SSOT for codex's NATIVE sandbox (Stage 8 filesystem isolation).
+
+optio-codex confines the agent's TOOL SUBPROCESSES using codex's own
+kernel-level sandbox (bundled bubblewrap primary, Landlock+seccomp fallback
+on Linux; helper bins materialize to ``$CODEX_HOME/tmp/arg0/``) rather than
+porting optio-claudecode's claustrum. Unlike grok there is no planted
+profile file: one resolved :class:`SandboxSettings` renders to
+
+* CLI surfaces (interactive TUI + ``codex exec``): ``--sandbox <mode>`` plus
+  ``-c sandbox_workspace_write.writable_roots=[…]`` /
+  ``-c sandbox_workspace_write.network_access=true`` overrides
+  (:func:`build_sandbox_cli_args`); and
+* the ``codex app-server`` launch (conversation mode): the mode travels
+  out-of-band via ``thread/start``'s ``sandbox`` field (a kebab-case
+  ``SandboxMode`` enum — the app-server has NO ``--sandbox`` flag), while
+  writable_roots/network_access ride the SAME ``-c sandbox_workspace_write.*``
+  overrides on the ``codex app-server`` command line
+  (:func:`build_sandbox_config_overrides`).
+
+  Schema note (probed, codex-cli 0.142.5 ``codex app-server
+  generate-json-schema``): ``ThreadStartParams`` exposes only ``sandbox``
+  (SandboxMode enum) + a generic ``config`` object — there is NO
+  ``sandboxPolicy`` object on ``thread/start``. A structured ``SandboxPolicy``
+  (a ``type``-tagged union: ``workspaceWrite``/``readOnly``/
+  ``dangerFullAccess``, camelCase ``writableRoots``/``networkAccess``) exists
+  only on ``turn/start``, which optio does not use to carry the sandbox — the
+  mode+``-c`` pair at launch defines the whole app-server process's posture.
+
+Probed divergences vs grok/claudecode (codex-cli 0.142.5, 2026-07-02):
+
+* ``workspace-write`` restricts WRITES only — the READ side is open, so
+  ``AllowedDir(mode="ro")`` grants are a documented no-op here (additive
+  grant, trivially satisfied). Only ``rw`` grants change behavior.
+* Network is OFF by default in workspace-write (``[sandbox_workspace_write]
+  network_access``) — stricter than the other wrappers' fs-only sandboxes;
+  ``CodexTaskConfig.network_access=True`` relaxes it.
+* ``.git/`` and ``.codex/`` under a writable root stay read-only for
+  sandboxed commands — the agent's shell cannot rewrite the per-task
+  ``auth.json`` even though ``CODEX_HOME`` lives inside the workdir.
+* Failure mode with NO mechanism available: **FAIL-CLOSED** (Task-0 probe
+  verdict, codex-cli 0.142.5). codex never runs the model's shell command
+  unconfined as a result of a sandbox-setup failure — it errors/panics
+  (bwrap "Creating new namespace failed" rc=1, or bare-binary "bubblewrap is
+  unavailable" panic rc=101) and the command does not run. The only
+  unconfined path is the explicit ``--dangerously-bypass-approvals-and-
+  sandbox`` opt-out, which optio-codex never emits. Consequence: no
+  launch-time enforcement guard is required (Task 5B, evidence-only).
+"""
+
+from __future__ import annotations
+
+import json
+from dataclasses import dataclass
+from typing import TYPE_CHECKING
+
+if TYPE_CHECKING:
+    from optio_codex.types import CodexTaskConfig, SandboxMode
+
+
+def _expand_home(path: str, host_home: str) -> str:
+    """Expand a leading ``~/`` against the REAL host home.
+
+    The codex process runs under an isolated ``$HOME`` (``<workdir>/home``),
+    so a ``~/`` grant cannot rely on shell expansion — it is resolved against
+    the operator's real home here, at settings-resolution time.
+    """
+    home = host_home.rstrip("/")
+    if path == "~":
+        return home
+    if path.startswith("~/"):
+        return f"{home}/{path[2:]}"
+    return path
+
+
+@dataclass(frozen=True)
+class SandboxSettings:
+    """One task's resolved sandbox posture — the SSOT every launch surface
+    (iframe/exec ``--sandbox`` argv, and the app-server's thread/start
+    ``sandbox`` mode + ``-c`` config overrides) renders from."""
+
+    mode: "SandboxMode"
+    writable_roots: tuple[str, ...] = ()
+    network_access: bool = False
+
+
+def resolve_sandbox_settings(
+    config: "CodexTaskConfig", *, host_home: str,
+) -> SandboxSettings:
+    """Resolve ``fs_isolation``/``sandbox``/``extra_allowed_dirs``/
+    ``network_access`` into one :class:`SandboxSettings`.
+
+    ``ro`` grants are skipped (codex never restricts reads — see module
+    docstring); ``rw`` grants become ``writable_roots`` with ``~/`` expanded
+    against ``host_home``. Roots/network only apply to workspace-write
+    (validated in CodexTaskConfig.__post_init__).
+    """
+    mode = config.effective_sandbox_mode
+    roots: list[str] = []
+    if mode == "workspace-write":
+        for ad in config.extra_allowed_dirs or []:
+            if ad.mode == "rw":
+                roots.append(_expand_home(ad.path, host_home).rstrip("/"))
+    return SandboxSettings(
+        mode=mode,
+        writable_roots=tuple(roots),
+        network_access=bool(config.network_access) and mode == "workspace-write",
+    )
+
+
+def _toml_str_array(paths: tuple[str, ...]) -> str:
+    # json.dumps output is valid TOML for basic strings.
+    return "[" + ", ".join(json.dumps(p) for p in paths) + "]"
+
+
+def build_sandbox_config_overrides(settings: SandboxSettings) -> list[str]:
+    """Render the ``-c sandbox_workspace_write.*`` overrides ONLY (no
+    ``--sandbox`` flag).
+
+    Used by the ``codex app-server`` launch, which selects the mode
+    out-of-band via ``thread/start``'s ``sandbox`` field and has no
+    ``--sandbox`` flag; the writable_roots/network_access still need to reach
+    the process, and ``codex app-server`` accepts ``-c`` config overrides.
+    :func:`build_sandbox_cli_args` composes on top of this — one SSOT, two
+    launch surfaces. ``-c`` values are parsed as TOML, so the roots array is
+    emitted in TOML syntax. Empty outside workspace-write (and for a
+    workspace-write posture with no extras).
+    """
+    if settings.mode != "workspace-write":
+        return []
+    out: list[str] = []
+    if settings.writable_roots:
+        out += [
+            "-c",
+            "sandbox_workspace_write.writable_roots="
+            + _toml_str_array(settings.writable_roots),
+        ]
+    if settings.network_access:
+        out += ["-c", "sandbox_workspace_write.network_access=true"]
+    return out
+
+
+def build_sandbox_cli_args(settings: SandboxSettings) -> list[str]:
+    """Render settings as codex CLI args (interactive TUI and ``exec``).
+
+    ``--sandbox`` is accepted by both surfaces; the ``-c`` overrides are the
+    same ones :func:`build_sandbox_config_overrides` produces for the
+    app-server (one SSOT). No overrides are emitted outside workspace-write.
+    """
+    return ["--sandbox", settings.mode, *build_sandbox_config_overrides(settings)]