optio-codex 0.4.0__tar.gz → 0.4.2__tar.gz

{optio_codex-0.4.0 → optio_codex-0.4.2}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: optio-codex
-Version: 0.4.0
+Version: 0.4.2
 Summary: Run OpenAI Codex as an optio task; local subprocess; ttyd-served TUI iframe.
 Author-email: Kristof Csillag <kristof.csillag@deai-labs.com>
 License-Expression: Apache-2.0

{optio_codex-0.4.0 → optio_codex-0.4.2}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "optio-codex"
-version = "0.4.0"
+version = "0.4.2"
 description = "Run OpenAI Codex as an optio task; local subprocess; ttyd-served TUI iframe."
 readme = "README.md"
 license = "Apache-2.0"

{optio_codex-0.4.0 → optio_codex-0.4.2}/src/optio_codex/conversation.py

@@ -496,7 +496,9 @@ class CodexConversation:
 
     # -- Conversation protocol surface --------------------------------------
 
-    async def send(self, text: str) -> None:
+    async def send(self, text: str, *, uuid: str | None = None) -> None:
+        """``uuid`` is an advisory message id (Fix 13a/Fix 23): this backend
+        has no message identity of its own, so it is accepted and ignored."""
         if self._closed.is_set():
             raise ConversationClosed(self._close_reason or "conversation closed")
         if self.thread_id is None:

{optio_codex-0.4.0 → optio_codex-0.4.2}/src/optio_codex/host_actions.py

@@ -63,6 +63,24 @@ _CODEX_RELEASE_BASE = (
     f"https://github.com/openai/codex/releases/download/rust-v{_CODEX_VERSION}"
 )
 
+# Version stamp recording which codex version the cache holds, written by
+# BOTH install tiers (pinned download stamps _CODEX_VERSION; host-copy
+# stamps the copied binary's probed version). The cache-hit path compares
+# it against _CODEX_VERSION so a pin bump actually reaches warm caches —
+# the cache is claustrum-``--rox`` to sessions, so freshness is owned
+# entirely by this unconfined provisioning path (agent-binary-freshness
+# plan, 2026-08-13).
+_CODEX_VERSION_STAMP_NAME = "codex.version"
+
+# ``codex --version`` output shape, verified against the REAL binary
+# (2026-08-13, ~/.cache/optio-codex/bin/codex, v0.142.5):
+#   $ env HOME=<empty-dir> ~/.cache/optio-codex/bin/codex --version
+#   stdout: ``codex-cli 0.142.5``   (exactly; version only on stdout)
+#   stderr: PATH-alias WARNING when $HOME/.codex is absent (harmless)
+#   exit 0; no files written under HOME.
+# Parse by regex, never by line position — stderr noise must not matter.
+_CODEX_VERSION_OUTPUT_RE = re.compile(r"codex-cli\s+(\S+)")
+
 
 async def _expand_user_path(host: "Host", path: str) -> str:
     """Expand a leading ``~``/``~/`` against the HOST's home directory.
@@ -207,6 +225,73 @@ async def claustrum_newer_tag() -> str | None:
     return newest if key(newest) > key(claustrum.CLAUSTRUM_PINNED_TAG) else None
 
 
+async def _probe_codex_version(host: "Host", codex_path: str) -> str | None:
+    """Best-effort: the version string a codex binary reports, or ``None``.
+
+    Runs ``<codex_path> --version`` with ``HOME`` pointed at the cache ROOT
+    (grok's ``_grok_update_target`` pattern) so the probe can never touch
+    the operator's ``~/.codex``. Real-binary evidence (2026-08-13, v0.142.5):
+    the probe writes nothing under HOME and prints ``codex-cli <semver>`` on
+    stdout (stderr may carry a PATH-alias warning) — parsed via
+    :data:`_CODEX_VERSION_OUTPUT_RE`. Non-zero exit / unmatched output →
+    ``None`` (never raises; a stamp-less cache just refreshes to the pin on
+    the next launch).
+    """
+    # HOME = the parent of the cache dir (…/optio-codex for …/optio-codex/bin).
+    cache_root = os.path.dirname(os.path.dirname(codex_path.rstrip("/"))) or "/"
+    r = await host.run_command(
+        f"env HOME={shlex.quote(cache_root)} {shlex.quote(codex_path)} --version"
+    )
+    if r.exit_code != 0:
+        _LOG.warning(
+            "codex --version probe failed (exit %s): %s",
+            r.exit_code, (r.stderr or "").strip()[:200],
+        )
+        return None
+    m = _CODEX_VERSION_OUTPUT_RE.search(r.stdout or "")
+    if m is None:
+        _LOG.warning(
+            "codex --version output unparseable; no version stamp: %r",
+            (r.stdout or "")[:200],
+        )
+        return None
+    return m.group(1)
+
+
+async def _read_version_stamp(host: "Host", *, cache_dir: str) -> str | None:
+    """The cache's ``codex.version`` stamp content, or ``None`` when absent
+    (legacy warm cache filled before stamping existed)."""
+    stamp = f"{cache_dir}/{_CODEX_VERSION_STAMP_NAME}"
+    r = await host.run_command(f"cat {shlex.quote(stamp)} 2>/dev/null || true")
+    content = (r.stdout or "").strip()
+    return content or None
+
+
+async def _write_version_stamp(
+    host: "Host", *, cache_dir: str, version: str,
+) -> None:
+    """Record ``version`` as ``<cache>/codex.version``, atomically.
+
+    Written AFTER the binary lands, via a per-invocation temp + ``mv -f``
+    (same concurrency discipline as the binary install): a concurrent
+    launch never reads a half-written stamp, and racers writing identical
+    content are last-writer-wins. Best-effort — a failed stamp write only
+    costs a redundant pinned re-download on the next launch, never a launch.
+    """
+    stamp = f"{cache_dir}/{_CODEX_VERSION_STAMP_NAME}"
+    tmp = f"{stamp}.{os.getpid()}-{uuid.uuid4().hex}"
+    r = await host.run_command(
+        f"printf %s {shlex.quote(version)} > {shlex.quote(tmp)} "
+        f"&& mv -f {shlex.quote(tmp)} {shlex.quote(stamp)}"
+    )
+    if r.exit_code != 0:
+        _LOG.warning(
+            "writing codex version stamp %r failed (exit %s): %s",
+            stamp, r.exit_code, (r.stderr or "").strip()[:200],
+        )
+        await host.run_command(f"rm -f {shlex.quote(tmp)}")
+
+
 async def ensure_codex_installed(
     hook_ctx: "HookContextProtocol",
     *,
@@ -219,13 +304,25 @@ async def ensure_codex_installed(
     any task workdir and never the operator's autoupdating ``~/.codex`` — so
     it stays shared, evictable, and unsnapshotted. Resolution order:
 
-    - **cache hit** — ``<cache>/codex`` is already executable.
+    - **cache hit, stamp == pin** — ``<cache>/codex`` is executable and its
+      ``codex.version`` stamp matches :data:`_CODEX_VERSION`.
+    - **cache hit, stamp missing/stale** — the ``_CODEX_VERSION`` pin is
+      authoritative: re-download the pinned release into the cache (never
+      host-copy on a refresh) and stamp it. Best-effort: a failed download
+      with an executable cached binary logs and uses the cached one (a
+      stale pin beats no engine — offline workers must still launch).
+      Gated on ``install_if_missing`` (an offline/pinned worker keeps the
+      binary it has; mirrors grok's update-probe gate).
     - **cache miss** — seed the cache from the resolved host ``codex``
       (login-shell ``command -v codex`` via :func:`resolve_codex`), copying
       it into ``<cache>/codex`` (``cp -L`` deref + chmod + re-verify).
     - **no host codex** — download the pinned GitHub-release tarball
       (:func:`_download_codex_into_cache`) and install it into the cache.
 
+    Both install tiers write the ``codex.version`` stamp, so pin bumps
+    become EFFECTIVE on warm caches (the cache is claustrum-``--rox`` to
+    confined sessions; freshness is owned here, by unconfined provisioning).
+
     Whatever fills the cache, the RETURNED path is always the per-task
     ``<workdir>/home/.local/bin/codex`` symlink (via
     :func:`_provision_task_home`) so teardown's anchored pkill stays scoped
@@ -243,7 +340,38 @@ async def ensure_codex_installed(
         f"[ -x {shlex.quote(cached)} ] && echo OK || true"
     )
     if "OK" in (probe.stdout or ""):
-        _LOG.info("ensure_codex_installed: cache HIT (%s)", cached)
+        stamp = await _read_version_stamp(host, cache_dir=cache_dir)
+        if stamp == _CODEX_VERSION:
+            _LOG.info("ensure_codex_installed: cache HIT (%s, %s)", cached, stamp)
+            return await _provision_task_home(host, shared_codex_path=cached)
+        if not install_if_missing:
+            _LOG.warning(
+                "ensure_codex_installed: cache stamp %r != pin %r but "
+                "install_if_missing=False; keeping cached binary (%s)",
+                stamp, _CODEX_VERSION, cached,
+            )
+            return await _provision_task_home(host, shared_codex_path=cached)
+        # Stamp missing (legacy warm cache) or != pin: the pin is
+        # authoritative on refresh — always the pinned release, never a
+        # host-copy (an operator's codex tracks upstream, not the pin).
+        _LOG.info(
+            "ensure_codex_installed: cache stamp %r != pin %r -> "
+            "re-downloading pinned release (%s)",
+            stamp, _CODEX_VERSION, cached,
+        )
+        hook_ctx.report_progress(None, f"Updating codex to {_CODEX_VERSION}…")
+        try:
+            await _download_codex_into_cache(
+                hook_ctx, cache_dir=cache_dir, cached=cached,
+            )
+        except Exception:  # noqa: BLE001
+            # Offline fallback: the cached binary is known-executable
+            # (probe above), so a failed refresh logs and launches on it.
+            _LOG.warning(
+                "ensure_codex_installed: pinned refresh to %s failed; "
+                "keeping cached binary (%s)",
+                _CODEX_VERSION, cached, exc_info=True,
+            )
         return await _provision_task_home(host, shared_codex_path=cached)
 
     if not install_if_missing:
@@ -301,6 +429,12 @@ async def _install_into_cache_from_host(
             f"codex cache seed completed but {cached!r} is still not "
             f"executable on the host. Check the seed source {source!r}."
         )
+    # Stamp the COPIED binary's own reported version (a host codex tracks
+    # upstream, so it need not equal the pin). Unprobeable → no stamp,
+    # and the next launch refreshes the cache to the authoritative pin.
+    version = await _probe_codex_version(host, cached)
+    if version is not None:
+        await _write_version_stamp(host, cache_dir=cache_dir, version=version)
     _LOG.info("ensure_codex_installed: cache MISS -> seeded from %s", source)
 
 
@@ -411,8 +545,14 @@ async def _download_codex_into_cache(
                 f"codex download completed but {cached!r} is still not "
                 f"executable on the host."
             )
+        # Stamp AFTER the binary: a stamp must never claim a version the
+        # cached binary is not. This tier only ever installs the pin.
+        await _write_version_stamp(
+            host, cache_dir=cache_dir, version=_CODEX_VERSION,
+        )
+        # Serves both the cold-cache fill and the stale-stamp pinned refresh.
         _LOG.info(
-            "ensure_codex_installed: cache MISS -> downloaded %s", url,
+            "ensure_codex_installed: downloaded pinned release %s", url,
         )
     finally:
         await host.run_command(

optio_codex-0.4.2/src/optio_codex/prompt.py

@@ -0,0 +1,48 @@
+"""AGENTS.md composition for optio-codex: the profile, plus a thin wrapper over
+the shared composer (``optio_agents.prompt.compose_instructions_file``), which
+owns all of the text. The exclude list is resolved with the same function the
+snapshot archive uses, so the section's preservation claims never drift."""
+
+from optio_agents.prompt import AgentPromptProfile, compose_instructions_file
+
+from optio_codex.snapshots import effective_workdir_exclude
+
+__all__ = ["PROFILE", "compose_agents_md"]
+
+PROFILE = AgentPromptProfile(
+    state_dir="home/.codex/",
+    state_dir_contents=(
+        "the codex session store (rollout files under `home/.codex/sessions`, "
+        "auth, config)"
+    ),
+)
+
+
+def compose_agents_md(
+    consumer_instructions: str,
+    *,
+    workdir_exclude: list[str] | None = None,
+    documentation: str | None = None,
+    supports_resume: bool = True,
+    host_protocol: bool = True,
+    omit_task_framing: bool = False,
+    fs_isolation_dirs: list[tuple[str, str]] | None = None,
+    file_download: bool = False,
+    check_resume_log_every_message: bool = True,
+) -> str:
+    """Render <workdir>/AGENTS.md for an optio-codex task.
+
+    ``workdir_exclude=None`` means the codex defaults
+    (``snapshots.effective_workdir_exclude``), not the bare framework ones."""
+    return compose_instructions_file(
+        consumer_instructions,
+        profile=PROFILE,
+        workdir_exclude=effective_workdir_exclude(workdir_exclude),
+        documentation=documentation,
+        supports_resume=supports_resume,
+        host_protocol=host_protocol,
+        omit_task_framing=omit_task_framing,
+        fs_isolation_dirs=fs_isolation_dirs,
+        file_download=file_download,
+        check_resume_log_every_message=check_resume_log_every_message,
+    )

{optio_codex-0.4.0 → optio_codex-0.4.2}/src/optio_codex/session.py

@@ -16,6 +16,7 @@ from optio_core.models import BasicAuth, TaskInstance
 
 from optio_agents import HookContext, RESUME_NOTICE, SYSTEM_MESSAGE_PREFIX, get_protocol
 from optio_agents import seeds as _seeds
+from optio_agents.fs_grants import fs_isolation_dirs
 from optio_agents.input_listener import serialized, start_input_listener
 from optio_agents.protocol.session import _SessionFailed, run_log_protocol_session
 from optio_agents.account import EMPTY, accounts_to_metadata
@@ -303,6 +304,7 @@ async def run_codex_session(ctx: ProcessContext, config: CodexTaskConfig) -> Non
                     workdir_exclude=config.workdir_exclude,
                     supports_resume=config.supports_resume,
                     file_download=config.file_download,
+                    fs_isolation_dirs=fs_isolation_dirs(config, host.workdir),
                 ),
             )
         else:
@@ -891,6 +893,7 @@ async def _maybe_refresh_on_resume(
         workdir_exclude=new_config.workdir_exclude,
         supports_resume=new_config.supports_resume,
         file_download=new_config.file_download,
+        fs_isolation_dirs=fs_isolation_dirs(new_config, host.workdir),
     )
     try:
         existing = await hook_ctx.read_text_from_host("AGENTS.md", silent=True)

{optio_codex-0.4.0 → optio_codex-0.4.2}/src/optio_codex.egg-info/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: optio-codex
-Version: 0.4.0
+Version: 0.4.2
 Summary: Run OpenAI Codex as an optio task; local subprocess; ttyd-served TUI iframe.
 Author-email: Kristof Csillag <kristof.csillag@deai-labs.com>
 License-Expression: Apache-2.0

{optio_codex-0.4.0 → optio_codex-0.4.2}/tests/test_codex_cache.py

@@ -53,10 +53,17 @@ def _per_task_path(ctx: _FakeHookCtx) -> str:
     return f"{ctx._host.workdir}/home/.local/bin/codex"
 
 
+def _stamp(cache: pathlib.Path, version: str | None = None) -> None:
+    """Plant a ``codex.version`` stamp (defaults to the current pin)."""
+    cache.mkdir(parents=True, exist_ok=True)
+    (cache / "codex.version").write_text(version or host_actions._CODEX_VERSION)
+
+
 @pytest.mark.asyncio
 async def test_cache_hit_returns_per_task_symlink_into_cache(tmp_path, monkeypatch):
     cache = tmp_path / "cache"
     _write_exe(cache / "codex")
+    _stamp(cache)  # stamp == pin → plain hit
 
     # A cache hit must not consult the host codex at all.
     async def _boom(*a, **k):  # noqa: ANN002, ANN003
@@ -117,6 +124,7 @@ async def test_default_cache_dir_from_env(tmp_path, monkeypatch):
     cache dir — never the workdir, never the operator's ~/.codex."""
     cache = tmp_path / "oai-cache" / "bin"
     _write_exe(cache / "codex")
+    _stamp(cache)
     monkeypatch.setenv("OPTIO_CODEX_CACHE_DIR", str(cache))
     ctx = await _local_ctx(tmp_path)
 
@@ -181,10 +189,15 @@ async def test_cache_miss_no_host_codex_downloads_release(tmp_path, monkeypatch)
     assert (cache / "codex").is_file()
     assert os.access(cache / "codex", os.X_OK)
     assert (cache / "codex").read_bytes().startswith(b"#!/bin/bash")
+    # …the pinned version was stamped alongside it…
+    assert (cache / "codex.version").read_text() == host_actions._CODEX_VERSION
     # …behind the per-task launch symlink, and no temp litter remains.
     assert result == _per_task_path(ctx)
     assert os.path.realpath(result) == os.path.realpath(str(cache / "codex"))
-    leftovers = [p.name for p in cache.iterdir() if p.name != "codex"]
+    leftovers = [
+        p.name for p in cache.iterdir()
+        if p.name not in {"codex", "codex.version"}
+    ]
     assert leftovers == [], leftovers
 
 
@@ -258,7 +271,11 @@ async def test_concurrent_cold_cache_downloads_do_not_corrupt(
     assert (cache / "codex").is_file()
     assert os.access(cache / "codex", os.X_OK)
     assert (cache / "codex").read_bytes().startswith(b"#!/bin/bash")
-    leftovers = [p.name for p in cache.iterdir() if p.name != "codex"]
+    assert (cache / "codex.version").read_text() == host_actions._CODEX_VERSION
+    leftovers = [
+        p.name for p in cache.iterdir()
+        if p.name not in {"codex", "codex.version"}
+    ]
     assert leftovers == [], leftovers
 
 
@@ -322,3 +339,209 @@ async def test_download_multi_member_tarball_rejected(tmp_path, monkeypatch):
 
     with pytest.raises(RuntimeError, match="exactly one"):
         await host_actions.ensure_codex_installed(ctx, install_dir=str(cache))
+
+
+# --- pin-stamp freshness (agent-binary-freshness plan Task 4) ---------------
+#
+# The cache is claustrum---rox to confined sessions, so freshness is owned by
+# this unconfined provisioning path: both install tiers stamp
+# <cache>/codex.version, and a cache hit compares the stamp against the
+# _CODEX_VERSION pin — a pin bump becomes effective on warm caches.
+
+
+class _NoDownloadCtx(_FakeHookCtx):
+    """Fake hook_ctx that must never be asked to download."""
+
+    async def download_file(self, url: str, dest: str) -> None:
+        raise AssertionError(f"download_file must not be called (url={url})")
+
+
+class _FailingDownloadCtx(_FakeHookCtx):
+    """Fake hook_ctx whose download always fails (offline worker)."""
+
+    def __init__(self, host) -> None:  # noqa: ANN001
+        super().__init__(host)
+        self.attempts = 0
+
+    async def download_file(self, url: str, dest: str) -> None:
+        self.attempts += 1
+        raise RuntimeError("network down")
+
+
+@pytest.mark.asyncio
+async def test_cache_hit_matching_stamp_skips_download(tmp_path, monkeypatch):
+    """Warm cache whose stamp equals the pin → no download, no host-copy."""
+    cache = tmp_path / "cache"
+    _write_exe(cache / "codex")
+    _stamp(cache)
+
+    async def _boom(*a, **k):  # noqa: ANN002, ANN003
+        raise AssertionError("resolve_codex must not be called on a stamped hit")
+
+    monkeypatch.setattr(host_actions, "resolve_codex", _boom)
+    host = LocalHost(taskdir=str(tmp_path / "task"))
+    await host.setup_workdir()
+    ctx = _NoDownloadCtx(host)
+
+    result = await host_actions.ensure_codex_installed(ctx, install_dir=str(cache))
+    assert result == _per_task_path(ctx)
+    assert os.path.realpath(result) == os.path.realpath(str(cache / "codex"))
+
+
+@pytest.mark.asyncio
+@pytest.mark.parametrize("stale_stamp", [None, "0.1.0"])
+async def test_cache_hit_stale_or_missing_stamp_redownloads_pin(
+    tmp_path, monkeypatch, stale_stamp,
+):
+    """Stamp missing (legacy warm cache) or != pin → the pinned release is
+    re-downloaded into the cache (never host-copied: the pin is
+    authoritative on refresh) and the stamp is rewritten to the pin."""
+    cache = tmp_path / "cache"
+    _write_exe(cache / "codex", body="#!/bin/bash\necho stale-codex\n")
+    if stale_stamp is not None:
+        _stamp(cache, stale_stamp)
+
+    async def _boom(*a, **k):  # noqa: ANN002, ANN003
+        raise AssertionError("refresh must never host-copy; pin is authoritative")
+
+    monkeypatch.setattr(host_actions, "resolve_codex", _boom)
+    host = LocalHost(taskdir=str(tmp_path / "task"))
+    await host.setup_workdir()
+    ctx = _DownloadingHookCtx(host, _fake_release_tarball())
+
+    result = await host_actions.ensure_codex_installed(ctx, install_dir=str(cache))
+
+    # The pinned release was fetched and installed over the stale binary…
+    assert len(ctx.urls) == 1
+    assert host_actions._CODEX_VERSION in ctx.urls[0]
+    assert (cache / "codex").read_bytes().startswith(b"#!/bin/bash")
+    assert b"downloaded-codex" in (cache / "codex").read_bytes()
+    # …the stamp now records the pin…
+    assert (cache / "codex.version").read_text() == host_actions._CODEX_VERSION
+    # …and the per-task symlink resolves into the refreshed cache.
+    assert result == _per_task_path(ctx)
+    assert os.path.realpath(result) == os.path.realpath(str(cache / "codex"))
+
+
+@pytest.mark.asyncio
+async def test_cache_hit_refresh_download_failure_falls_back_to_cached(
+    tmp_path, monkeypatch,
+):
+    """Offline fallback: a failed pinned refresh with an executable cached
+    binary logs and launches on the cached one (stale pin beats no engine)."""
+    cache = tmp_path / "cache"
+    _write_exe(cache / "codex", body="#!/bin/bash\necho stale-codex\n")
+    _stamp(cache, "0.1.0")
+
+    async def _boom(*a, **k):  # noqa: ANN002, ANN003
+        raise AssertionError("refresh must never host-copy")
+
+    monkeypatch.setattr(host_actions, "resolve_codex", _boom)
+    host = LocalHost(taskdir=str(tmp_path / "task"))
+    await host.setup_workdir()
+    ctx = _FailingDownloadCtx(host)
+
+    result = await host_actions.ensure_codex_installed(ctx, install_dir=str(cache))
+
+    assert ctx.attempts == 1  # the refresh WAS attempted…
+    # …but the launch proceeds on the untouched cached binary,
+    assert result == _per_task_path(ctx)
+    assert b"stale-codex" in (cache / "codex").read_bytes()
+    # and the stamp stays stale so the NEXT launch retries the refresh.
+    assert (cache / "codex.version").read_text() == "0.1.0"
+
+
+@pytest.mark.asyncio
+async def test_cache_hit_stale_stamp_install_if_missing_false_keeps_cached(
+    tmp_path, monkeypatch,
+):
+    """install_if_missing=False means no network ever: a stale stamp keeps
+    the cached binary without attempting the pinned refresh (mirrors grok's
+    install_if_missing gate on its update probe)."""
+    cache = tmp_path / "cache"
+    _write_exe(cache / "codex", body="#!/bin/bash\necho stale-codex\n")
+    _stamp(cache, "0.1.0")
+
+    async def _boom(*a, **k):  # noqa: ANN002, ANN003
+        raise AssertionError("must not resolve host codex")
+
+    monkeypatch.setattr(host_actions, "resolve_codex", _boom)
+    host = LocalHost(taskdir=str(tmp_path / "task"))
+    await host.setup_workdir()
+    ctx = _NoDownloadCtx(host)
+
+    result = await host_actions.ensure_codex_installed(
+        ctx, install_dir=str(cache), install_if_missing=False,
+    )
+    assert result == _per_task_path(ctx)
+    assert b"stale-codex" in (cache / "codex").read_bytes()
+    assert (cache / "codex.version").read_text() == "0.1.0"
+
+
+# A fake host codex whose --version mimics the REAL binary's output shape
+# (verified 2026-08-13 against ~/.cache/optio-codex/bin/codex: stdout is
+# exactly ``codex-cli <semver>``; stderr may carry a PATH-alias warning).
+_VERSIONED_FAKE = (
+    "#!/bin/bash\n"
+    'if [ "$1" = "--version" ]; then\n'
+    '  echo "WARNING: could not create PATH aliases" >&2\n'
+    '  echo "codex-cli 9.9.9"\n'
+    "  exit 0\n"
+    "fi\n"
+    "echo fake-codex\n"
+)
+
+
+@pytest.mark.asyncio
+async def test_host_copy_seed_stamps_probed_version(tmp_path, monkeypatch):
+    """The host-copy tier stamps the COPIED binary's own reported version
+    (which need not equal the pin — a host codex tracks upstream)."""
+    cache = tmp_path / "cache"
+    cache.mkdir()  # empty → miss
+    source = _write_exe(tmp_path / "hostbin" / "codex", body=_VERSIONED_FAKE)
+
+    async def _resolve(host, *, install_dir=None, install_if_missing=True):  # noqa: ANN001
+        return str(source)
+
+    monkeypatch.setattr(host_actions, "resolve_codex", _resolve)
+    ctx = await _local_ctx(tmp_path)
+
+    result = await host_actions.ensure_codex_installed(ctx, install_dir=str(cache))
+    assert result == _per_task_path(ctx)
+    assert (cache / "codex.version").read_text() == "9.9.9"
+
+
+@pytest.mark.asyncio
+async def test_host_copy_unprobeable_version_writes_no_stamp(
+    tmp_path, monkeypatch,
+):
+    """A copied binary whose --version output does not parse gets NO stamp —
+    the next launch then refreshes the cache to the authoritative pin."""
+    cache = tmp_path / "cache"
+    cache.mkdir()
+    source = _write_exe(tmp_path / "hostbin" / "codex")  # echoes fake-codex
+
+    async def _resolve(host, *, install_dir=None, install_if_missing=True):  # noqa: ANN001
+        return str(source)
+
+    monkeypatch.setattr(host_actions, "resolve_codex", _resolve)
+    ctx = await _local_ctx(tmp_path)
+
+    result = await host_actions.ensure_codex_installed(ctx, install_dir=str(cache))
+    assert result == _per_task_path(ctx)
+    assert not (cache / "codex.version").exists()
+
+
+def test_version_output_regex_matches_real_binary_shape():
+    """Anchor the parse to the REAL ``codex --version`` stdout (v0.142.5)."""
+    m = host_actions._CODEX_VERSION_OUTPUT_RE.search("codex-cli 0.142.5\n")
+    assert m is not None and m.group(1) == "0.142.5"
+    assert host_actions._CODEX_VERSION_OUTPUT_RE.search("fake-codex\n") is None
+
+
+def test_sshd_mount_stamp_tracks_pin():
+    """tests/codex.version is compose-mounted beside the remote shim as its
+    cache stamp; it must track the _CODEX_VERSION pin, or the remote suite
+    would attempt a real pinned re-download. Update it on every pin bump."""
+    stamp = pathlib.Path(__file__).parent / "codex.version"
+    assert stamp.read_text().strip() == host_actions._CODEX_VERSION

{optio_codex-0.4.0 → optio_codex-0.4.2}/tests/test_config_hooks.py

@@ -16,6 +16,7 @@ from unittest.mock import AsyncMock, MagicMock
 import pytest
 
 from optio_agents import get_protocol
+from optio_agents.fs_grants import fs_isolation_dirs
 from optio_codex.prompt import compose_agents_md
 from optio_codex.types import CodexTaskConfig
 
@@ -239,7 +240,7 @@ async def test_restore_workdir_blob_decrypts(monkeypatch):
 # --- P2 unit: _maybe_refresh_on_resume -------------------------------------
 
 
-def _resume_fakes(existing_agents_md: str):
+def _resume_fakes(existing_agents_md: str, workdir: str = "/workdir"):
     """Build (host, hook_ctx) fakes whose read returns ``existing_agents_md``
     and whose write records the rewritten body."""
     written: dict[str, str] = {}
@@ -249,6 +250,7 @@ def _resume_fakes(existing_agents_md: str):
 
     fake_host = MagicMock()
     fake_host.write_text = _write_text
+    fake_host.workdir = workdir
 
     fake_hook = MagicMock()
     fake_hook.read_text_from_host = AsyncMock(return_value=existing_agents_md)
@@ -260,6 +262,7 @@ async def test_maybe_refresh_identity_unchanged_is_noop():
 
     protocol = get_protocol(browser="redirect")
     cfg = _cfg(consumer_instructions="orig")
+    workdir = "/workdir"
     existing = compose_agents_md(
         cfg.consumer_instructions,
         documentation=protocol.documentation if cfg.host_protocol else None,
@@ -267,8 +270,9 @@ async def test_maybe_refresh_identity_unchanged_is_noop():
         workdir_exclude=cfg.workdir_exclude,
         supports_resume=cfg.supports_resume,
         file_download=cfg.file_download,
+        fs_isolation_dirs=fs_isolation_dirs(cfg, workdir),
     )
-    host, hook, written = _resume_fakes(existing)
+    host, hook, written = _resume_fakes(existing, workdir=workdir)
 
     refreshed = await _maybe_refresh_on_resume(host, hook, cfg, protocol)
     assert refreshed == []
@@ -285,12 +289,14 @@ async def test_maybe_refresh_mutating_hook_rewrites_agents_md():
         return dataclasses.replace(c, consumer_instructions="UPDATED INSTRUCTIONS")
 
     cfg = _cfg(consumer_instructions="orig", on_resume_refresh=_bump)
+    workdir = "/workdir"
     stale = compose_agents_md(
         "orig",
         documentation=protocol.documentation,
         host_protocol=True,
+        fs_isolation_dirs=fs_isolation_dirs(cfg, workdir),
     )
-    host, hook, written = _resume_fakes(stale)
+    host, hook, written = _resume_fakes(stale, workdir=workdir)
 
     refreshed = await _maybe_refresh_on_resume(host, hook, cfg, protocol)
     assert refreshed == ["AGENTS.md"]

{optio_codex-0.4.0 → optio_codex-0.4.2}/tests/test_prompt.py

@@ -84,3 +84,13 @@ def test_host_protocol_false_keeps_resume_section_and_explainer():
     # passing; same caveat as test_host_protocol_false_adds_system_explainer.)
     assert get_protocol(browser="redirect").documentation not in md
     assert "## Log channel" not in md
+
+
+def test_sandbox_note_and_no_prompt_text_of_its_own():
+    import inspect
+    import optio_codex.prompt as m
+    out = compose_agents_md("x", fs_isolation_dirs=[("/wd", "rwx")])
+    assert "**Filesystem access:**" in out
+    src = inspect.getsource(m)
+    assert "This harness may pause your session" not in src
+    assert "originate from the harness" not in src

optio_codex-0.4.0/src/optio_codex/prompt.py

@@ -1,184 +0,0 @@
-"""AGENTS.md composition for optio-codex.
-
-Codex reads an ``AGENTS.md`` file in its workdir. The shared framing and
-the keyword-protocol documentation are owned by ``optio-agents`` (the
-prompt SSOT); this module threads codex's protocol mode through and owns
-the codex-specific resume-awareness section (Stage 2), rendered from the
-EFFECTIVE snapshot exclude list so its preservation claims never drift
-from what the snapshot actually keeps.
-"""
-
-from optio_agents.prompt import compose_agents_md as _compose_agents_md_host
-from optio_agents.prompt import downloadables_block
-from optio_agents.protocol import ProtocolFeatures, build_log_channel_prompt
-
-from optio_codex.snapshots import effective_workdir_exclude
-
-
-# Self-contained System: explainer for sessions without the keyword-protocol
-# docs (which normally explain the convention). Per-wrapper copy is the
-# established pattern (claudecode/opencode/grok each carry their own).
-_SYSTEM_PREFIX_EXPLAINER = """\
-(Messages prefixed `System:` on your input channel originate from the
-harness coordinating this session, not from the human user.)
-"""
-
-
-RESUME_SECTION_TEMPLATE = """## Resumes
-
-This harness may pause your session, save your context to a database,
-terminate the underlying process, and later rehydrate it. From your
-point of view the conversation is fully continuous — you keep your
-prior context and will not "notice" the resume.
-
-**A resume can happen at any point, not only at the start.** The host
-environment may have changed across a resume — different host,
-different running processes, files outside this workdir gone — even
-though your context remembers everything as alive and well.
-
-**The workdir (this directory) is preserved across resumes, with two
-caveats:**
-
-- {excludes_clause}
-- **Anything outside the workdir is not preserved.**
-
-- **Your `home/.codex/` directory — the codex session store (rollout
-  files under `home/.codex/sessions`, auth, config) — IS preserved
-  across resumes** (minus the excluded paths above), so your history
-  travels with you even when the underlying process and host change.
-
-{outside_clause}
-
-### Detecting a resume: `resume.log`
-
-Each session start (fresh or resumed) appends one line to
-`./resume.log`. Line format:
-
-```
-<ISO 8601 UTC timestamp>[ REFRESHED:<comma-separated filenames>]
-```
-
-The very first line is the original launch timestamp; each subsequent
-line is a resume. The optional `REFRESHED:` suffix signals that the
-harness rewrote the listed files on that resume (e.g.
-`2026-05-28T13:15:42Z REFRESHED:AGENTS.md`) — your in-memory copy of
-those files is stale and must be re-read before continuing.
-
-**At the start of every new incoming user message, read
-`./resume.log` first.** Compare the latest line to the value you
-remembered last time you checked. If a new line has appeared, treat
-the situation as a resume:
-
-- Verify any tools, processes, or files you previously gathered
-  outside the workdir are still where you left them.
-- Re-establish anything that's gone (re-launch a server, re-fetch a
-  file, etc.) before continuing.
-- **If the latest line carries a `REFRESHED:` suffix, re-read each
-  listed file** (e.g. `cat ./AGENTS.md`) — the harness updated it
-  since your last context snapshot and the version you remember is
-  out of date.
-- Then resume the work you were doing.
-
-If a resume slips past unnoticed, a failing tool call is the
-next-best signal — re-check `./resume.log` then.
-
-You may also be notified of a resume by a `System:` message on your input
-channel; when you see one, follow the `resume.log` procedure above.
-"""
-
-
-def _render_resume_section(workdir_exclude: list[str] | None) -> str:
-    """Render RESUME_SECTION_TEMPLATE with the EFFECTIVE exclude list.
-
-    ``effective_workdir_exclude`` is the same resolver the snapshot archive
-    uses (``None`` → the codex defaults), so what this section claims is
-    preserved is exactly what the snapshot preserves.
-    """
-    effective = effective_workdir_exclude(workdir_exclude)
-    if not effective:
-        excludes_clause = (
-            "**No paths are excluded** — every file in the workdir is preserved."
-        )
-        outside_clause = (
-            "If you need to stash large data, place it outside the workdir "
-            "(e.g. `/tmp/`) — but remember it may be missing when you next look."
-        )
-    else:
-        excludes_str = ", ".join(f"`{p}`" for p in effective)
-        excludes_clause = (
-            f"**Paths matching the snapshot exclude list are NOT preserved**, "
-            f"even inside the workdir. The current exclude list is: {excludes_str}."
-        )
-        outside_clause = (
-            "If you need to stash large data, place it outside the workdir "
-            "(e.g. `/tmp/`) or inside an excluded subdirectory — but remember "
-            "any such location may be missing when you next look."
-        )
-    return RESUME_SECTION_TEMPLATE.format(
-        excludes_clause=excludes_clause,
-        outside_clause=outside_clause,
-    )
-
-
-def compose_agents_md(
-    consumer_instructions: str,
-    *,
-    documentation: str | None = None,
-    host_protocol: bool = True,
-    workdir_exclude: list[str] | None = None,
-    supports_resume: bool = True,
-    file_download: bool = False,
-) -> str:
-    """Build the full AGENTS.md body.
-
-    ``documentation`` is the keyword-protocol block; the session passes
-    ``get_protocol(browser="redirect").documentation``. Defaults (for unit
-    tests / standalone callers) to codex's ``redirect`` docs. It must
-    always come from the session's ``Protocol`` where one exists — never
-    rebuild features at a second site.
-
-    ``host_protocol=False`` omits the keyword-protocol documentation and
-    instead includes a self-contained ``System:`` message explainer
-    (guide Part 2D); iframe mode always runs with ``host_protocol=True``
-    (validated in ``CodexTaskConfig``), the False branch serves
-    conversation mode in a later stage.
-
-    ``supports_resume=True`` (default) appends the resume-awareness section
-    so the agent watches ``resume.log`` and knows ``home/.codex`` (minus
-    ``workdir_exclude``) survives across resumes. ``workdir_exclude`` is
-    this task's snapshot exclude list (None → the codex defaults), used to
-    keep the section's claims in sync with what is actually preserved.
-
-    ``file_download=True`` appends the downloadables instruction block so
-    codex offers files to the human via the ``optio-file:`` sentinel link
-    (conversation_ui file-download feature); the wording is comparative when
-    the keyword protocol is active (``host_protocol``).
-    """
-    if file_download:
-        consumer_instructions = (
-            consumer_instructions.rstrip()
-            + downloadables_block(comparative=host_protocol)
-        )
-    if host_protocol:
-        if documentation is None:
-            documentation = build_log_channel_prompt(
-                ProtocolFeatures(browser="redirect")
-            )
-    else:
-        documentation = None
-    resume_section: str | None = (
-        _render_resume_section(workdir_exclude) if supports_resume else None
-    )
-    if not host_protocol:
-        # The protocol docs normally explain the `System:` convention;
-        # without them the composed prompt carries its own explainer.
-        resume_section = (
-            resume_section + _SYSTEM_PREFIX_EXPLAINER
-            if resume_section
-            else _SYSTEM_PREFIX_EXPLAINER
-        )
-    return _compose_agents_md_host(
-        consumer_instructions,
-        documentation=documentation,
-        resume_section=resume_section,
-    )