ccx-native 0.0.1 → 0.2.0

package/ccx/controllers/live_vars_runner.py

@@ -0,0 +1,216 @@
+"""Execution helpers for CCX worker variables.
+
+This module intentionally depends only on the Python standard library. The
+standalone durable path executes this file with the worker-selected Python,
+which may not have the ccx package importable.
+"""
+
+from __future__ import annotations
+
+import argparse
+import json
+import linecache
+import os
+from pathlib import Path
+import runpy
+import sys
+import traceback
+from typing import Any
+
+
+SCHEMA_VERSION = 1
+STATE_FILE_LIMIT = 4 * 1024 * 1024
+
+
+def strict_json(value: Any) -> str:
+    return json.dumps(
+        value,
+        separators=(",", ":"),
+        ensure_ascii=False,
+        allow_nan=False,
+    )
+
+
+def _system_exit_code(error: SystemExit) -> int:
+    if error.code is None:
+        return 0
+    if isinstance(error.code, int):
+        return error.code
+    if error.code:
+        print(error.code, file=sys.stderr)
+    return 1
+
+
+def execute_target(args: list[str], globals_seed: dict[str, Any]) -> tuple[int, dict[str, Any]]:
+    """Execute one supported Python invocation against a fresh globals mapping."""
+    ns = dict(globals_seed)
+    ns.setdefault("__name__", "__main__")
+    try:
+        if not args or args[0] == "-":
+            if sys.path:
+                sys.path[0] = ""
+            sys.argv = ["-", *args[1:]]
+            ns["__file__"] = "<stdin>"
+            source = sys.stdin.read()
+            exec(compile(source, "<stdin>", "exec"), ns, ns)
+            return 0, ns
+
+        if args[0] == "-c":
+            if sys.path:
+                sys.path[0] = ""
+            if len(args) < 2:
+                print("argument expected for -c", file=sys.stderr)
+                return 2, ns
+            sys.argv = ["-c", *args[2:]]
+            ns["__file__"] = "<string>"
+            # The bootstrap itself ran as -c; give traceback the user's source.
+            linecache.cache["<string>"] = (
+                len(args[1]), None, args[1].splitlines(keepends=True), "<string>"
+            )
+            exec(compile(args[1], "<string>", "exec"), ns, ns)
+            return 0, ns
+
+        if args[0] == "-m":
+            if sys.path:
+                sys.path[0] = ""
+            if len(args) < 2:
+                print("argument expected for -m", file=sys.stderr)
+                return 2, ns
+            sys.argv = [args[1], *args[2:]]
+            # Resolve packages through runpy, but retain the executing globals
+            # even when the module exits or raises before runpy can return them.
+            _, spec, code = runpy._get_module_details(args[1])
+            with runpy._TempModule("__main__") as temporary, runpy._ModifiedArgv0(spec.origin):
+                ns = temporary.module.__dict__
+                ns.update(globals_seed)
+                runpy._run_code(code, ns, mod_name="__main__", mod_spec=spec)
+            return 0, ns
+
+        if args[0].startswith("-"):
+            print(
+                f"ccx shared python: unsupported interpreter option {args[0]!r}; "
+                "use an explicit interpreter path for native Python",
+                file=sys.stderr,
+            )
+            return 2, ns
+
+        script = Path(args[0]).resolve()
+        if sys.path:
+            sys.path[0] = str(script.parent)
+        sys.argv = [str(script), *args[1:]]
+        ns["__file__"] = str(script)
+        source = script.read_bytes()
+        exec(compile(source, str(script), "exec"), ns, ns)
+        return 0, ns
+    except SystemExit as error:
+        return _system_exit_code(error), ns
+    except KeyboardInterrupt as error:
+        tb = error.__traceback__
+        traceback.print_exception(type(error), error, tb.tb_next if tb else None)
+        return 130, ns
+    except BaseException as error:
+        tb = error.__traceback__
+        traceback.print_exception(type(error), error, tb.tb_next if tb else None)
+        return 1, ns
+
+
+def _atomic_write(path: Path, text: str) -> None:
+    tmp = path.with_name(f".{path.name}.{os.getpid()}.tmp")
+    tmp.write_text(text, encoding="utf-8")
+    try:
+        os.chmod(tmp, 0o600)
+    except OSError:
+        pass
+    os.replace(tmp, path)
+
+
+def _parse_runner_args(argv: list[str] | None = None):
+    parser = argparse.ArgumentParser(add_help=False)
+    parser.add_argument("--state", required=True)
+    parser.add_argument("--lock", required=True)
+    parser.add_argument("--cwd", required=True)
+    parser.add_argument("--real-python", required=True)
+    parser.add_argument("target_args", nargs=argparse.REMAINDER)
+    value = parser.parse_args(argv)
+    if value.target_args and value.target_args[0] == "--":
+        value.target_args = value.target_args[1:]
+    return value
+
+
+def durable_main(argv: list[str] | None = None) -> int:
+    """Run one durable invocation under a whole-invocation file lock."""
+    import fcntl
+
+    args = _parse_runner_args(argv)
+    state_path = Path(args.state)
+    lock_path = Path(args.lock)
+    lock_path.parent.mkdir(parents=True, exist_ok=True)
+    with lock_path.open("a+") as lock_file:
+        fcntl.flock(lock_file, fcntl.LOCK_EX)
+        try:
+            document = json.loads(state_path.read_text(encoding="utf-8"))
+        except FileNotFoundError:
+            print("ccx: worker variable state is no longer available", file=sys.stderr)
+            return 69
+
+        if not isinstance(document.get("stateId"), str):
+            print("ccx: durable variable state is malformed", file=sys.stderr)
+            return 69
+
+        names = {
+            str(name)
+            for name in document.get("names", [])
+            if isinstance(name, str)
+        }
+        variables = document.get("variables")
+        if not isinstance(variables, dict):
+            variables = {}
+
+        seed = {name: variables[name] for name in names if name in variables}
+        old_cwd = os.getcwd()
+        old_argv = sys.argv[:]
+        try:
+            os.chdir(args.cwd)
+            exit_code, final_ns = execute_target(args.target_args, seed)
+        finally:
+            sys.argv = old_argv
+            os.chdir(old_cwd)
+
+        if exit_code != 0:
+            return exit_code
+
+        final_names = sorted(name for name in names if name in final_ns)
+        final_variables = {name: final_ns[name] for name in final_names}
+        try:
+            encoded_variables = strict_json(final_variables)
+        except (TypeError, ValueError) as error:
+            bad_name = "<unknown>"
+            for name, value in final_variables.items():
+                try:
+                    strict_json(value)
+                except (TypeError, ValueError):
+                    bad_name = name
+                    break
+            print(
+                f"CcxStateValueUnsupported: variable {bad_name!r} can't be saved: "
+                f"{error}; use JSON dicts, lists, strings, numbers, booleans or null",
+                file=sys.stderr,
+            )
+            return 1
+
+        updated = dict(document)
+        updated["schemaVersion"] = SCHEMA_VERSION
+        updated["names"] = final_names
+        updated["variables"] = json.loads(encoded_variables)
+        text = strict_json(updated)
+        if len(text.encode("utf-8")) > STATE_FILE_LIMIT:
+            print("CcxStateTooLarge: worker variables exceed the 4 MiB state limit; "
+                  "shrink a bound variable and retry", file=sys.stderr)
+            return 1
+        _atomic_write(state_path, text)
+        return 0
+
+
+
+if __name__ == "__main__":
+    raise SystemExit(durable_main())

package/ccx/controllers/notify.py

@@ -0,0 +1,213 @@
+"""Controller-attempt observations for the shared parent notification daemon."""
+
+from __future__ import annotations
+
+from pathlib import Path
+from typing import Any
+
+from ccx.controllers import store as store
+from ccx.errors import ControllerError
+
+
+def _attempt_for_registration(
+    record: dict[str, Any], reg: dict[str, Any]
+) -> dict[str, Any] | None:
+    operation = reg.get("operation") if isinstance(reg.get("operation"), dict) else {}
+    number = operation.get("attempt")
+    token = operation.get("attemptToken")
+    if not isinstance(token, str) or not token:
+        return None
+    for attempt in record.get("attempts") or []:
+        if not isinstance(attempt, dict) or attempt.get("number") != number:
+            continue
+        if attempt.get("attemptToken") != token:
+            continue
+        return attempt
+    return None
+
+
+def _startup_deadline(
+    reg: dict[str, Any],
+    attempt: dict[str, Any] | None = None,
+) -> int:
+    operation = (
+        reg.get("operation")
+        if isinstance(reg.get("operation"), dict)
+        else {}
+    )
+    deadline = int(operation.get("startupDeadlineMs") or 0)
+    if isinstance(attempt, dict):
+        deadline = max(
+            deadline,
+            int(attempt.get("startedAt") or 0) + 45_000,
+        )
+    return deadline
+
+
+def _record(reg: dict[str, Any]) -> dict[str, Any] | None:
+    run_id = reg["worker"]["workerId"]
+    try:
+        bootstrap = store.bootstrap_root() / run_id
+        run_dir = (bootstrap if bootstrap.is_dir() else next(
+            (path for path in store._all_run_dirs() if path.name == run_id), None
+        ))
+        if run_dir is None:
+            raise ControllerError("original controller run is unavailable")
+        record = store.read_json(store.run_record_path(run_dir))
+        if record.get("runId") != run_id:
+            raise ControllerError("controller run identity differs from notification")
+        attempt = _attempt_for_registration(record, reg)
+        if (
+            isinstance(attempt, dict)
+            and attempt.get("lifecycle") in store.TERMINAL_LIFECYCLES
+        ):
+            return record
+
+        # A registration can deliberately precede attempt publication. While
+        # that bounded startup window is open, missing attempt state is pending.
+        # After the window, settlement/progress will turn a missing or token-
+        # mismatched attempt into a structural unavailable result. Never inspect
+        # a later attempt's liveness on behalf of this registration.
+        if attempt is None:
+            return record
+
+        # An earlier unfinished attempt must never sample a newer host's PID.
+        if (record.get("attempts") or [])[-1] is not attempt:
+            return record
+
+        lifecycle = record.get("lifecycle") or {}
+        deadline = _startup_deadline(reg, attempt)
+        if (
+            lifecycle.get("state") == "starting"
+            and not lifecycle.get("pid")
+            and store.now_ms() < deadline
+        ):
+            return record
+        return store.refresh_liveness(run_dir)
+    except (ControllerError, OSError):
+        # Bootstrap publication can temporarily hide the directory. After the
+        # already recorded deadline, keep this event visible as unavailable.
+        if store.now_ms() < _startup_deadline(reg):
+            return None
+        return {"runId": run_id, "controller": reg["worker"].get("name"),
+                "attempts": [], "reports": []}
+
+
+def settlement(reg: dict[str, Any]) -> dict[str, Any] | None:
+    record = _record(reg)
+    if record is None:
+        return None
+    number = reg["operation"]["attempt"]
+    store.snapshot_attempt_outcome(record)
+    attempt = _attempt_for_registration(record, reg)
+    if attempt is None:
+        if store.now_ms() < _startup_deadline(reg):
+            return None
+        token = reg.get("operation", {}).get("attemptToken")
+        return {
+            "status": "unavailable",
+            "workerState": "unavailable",
+            "operationType": "controller-attempt",
+            "operationId": f"{record['runId']}:{number}",
+            "controller": record.get("controller"),
+            "runId": record["runId"],
+            "attempt": number,
+            "controllerStatus": None,
+            "checkpoint": None,
+            "summary": None,
+            "report": None,
+            "reportTruncated": False,
+            "reportPath": None,
+            "error": {
+                "type": "ControllerAttemptUnavailable",
+                "message": (
+                    "controller attempt was not durably published"
+                    if token
+                    else "controller attempt is unavailable"
+                ),
+            },
+        }
+    if attempt.get("lifecycle") not in store.TERMINAL_LIFECYCLES:
+        return None
+    outcome = attempt.get("outcome") or {}
+    metadata = outcome.get("report") or {}
+    report = None
+    path = metadata.get("path")
+    error = outcome.get("error")
+    if path:
+        try:
+            report = Path(path).read_text(encoding="utf-8")
+        except OSError as exc:
+            error = error or {"type": "ControllerReportUnavailable", "message": str(exc)}
+    from ccx.notify.settle import _truncate_report
+    report, truncated = _truncate_report(report)
+    return {
+        "status": attempt["lifecycle"],
+        "workerState": attempt["lifecycle"],
+        "operationType": "controller-attempt",
+        "operationId": f"{record['runId']}:{number}",
+        "controller": record.get("controller"),
+        "runId": record["runId"],
+        "attempt": number,
+        "controllerStatus": outcome.get("status"),
+        "checkpoint": outcome.get("checkpoint"),
+        "summary": outcome.get("summary"),
+        "report": report,
+        "reportTruncated": truncated,
+        "reportPath": path,
+        "error": error,
+    }
+
+
+def progress(reg: dict[str, Any]) -> dict[str, Any]:
+    record = _record(reg)
+    result: dict[str, Any] = {
+        "elapsedSeconds": max(0, int((store.now_ms() - reg["createdAtMs"]) / 1000)),
+        "attempt": reg["operation"]["attempt"],
+    }
+    if record is None:
+        return {**result, "workerState": "unknown", "health": "record-unavailable"}
+    store.snapshot_attempt_outcome(record)
+    attempt = _attempt_for_registration(record, reg)
+    if attempt is None:
+        if store.now_ms() >= _startup_deadline(reg):
+            return {
+                **result,
+                "workerState": "unavailable",
+                "health": "attempt-unavailable",
+                "controller": record.get("controller"),
+                "runId": record["runId"],
+            }
+        return {
+            **result,
+            "workerState": "starting",
+            "health": "attempt-pending-publication",
+            "controller": record.get("controller"),
+            "runId": record["runId"],
+        }
+    if attempt.get("outcome") is not None:
+        outcome = attempt["outcome"]
+        return {
+            **result, "workerState": attempt["lifecycle"],
+            "controller": record.get("controller"), "runId": record["runId"],
+            "controllerStatus": outcome.get("status"),
+            "checkpoint": outcome.get("checkpoint"),
+        }
+    if (record.get("attempts") or [])[-1] is not attempt:
+        return {
+            **result, "workerState": attempt.get("lifecycle") or "unavailable",
+            "controller": record.get("controller"), "runId": record["runId"],
+        }
+    reports = (record.get("reports") or [])[int(attempt.get("reportStartIndex", 0)):]
+    latest = reports[-1] if reports else {}
+    tasks = list((record.get("tasks") or {}).values())
+    return {
+        **result,
+        "workerState": (record.get("lifecycle") or {}).get("state"),
+        "controller": record.get("controller"),
+        "runId": record["runId"],
+        "controllerStatus": latest.get("status"),
+        "checkpoint": latest.get("checkpoint"),
+        "taskCount": len(tasks),
+        "activeTasks": [t.get("name") or t.get("id") for t in tasks if t.get("state") == "running"][:4],
+    }

package/ccx/controllers/orchestrator.py

@@ -0,0 +1,193 @@
+"""Identify the harness currently driving the CCX CLI.
+
+This is deliberately about the *caller*, not the worker engine. A Codex turn can
+launch either a Claude or Codex worker, and the continuation policy follows the
+parent harness that invoked CCX.
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+import os
+from typing import Any
+
+from ccx.errors import InvalidRequest
+
+
+def _external_codex_unavailable(thread_id: str) -> str | None:
+    """Check the *owning* app-server, not merely a thread saved on disk.
+
+    A plain Codex TUI has its own in-process app-server. A separately running
+    daemon can read that TUI's rollout, but cannot deliver into the TUI turn.
+    Only server-local loaded-thread membership permits an external return arm.
+    """
+    from ccx.codex import control as codex_control
+
+    path = codex_control.control_socket_path()
+    try:
+        is_socket = path.is_socket()
+    except OSError as error:  # e.g. a sandbox denying access to ~/.codex
+        return f"Codex app-server control socket at {path} is not accessible: {error}"
+    if not is_socket:
+        return f"no Codex app-server control socket at {path} (plain Codex TUI runs in-process)"
+    client = None
+    try:
+        client = codex_control.CodexControlClient(handshake_timeout=2)
+        client.initialize(timeout=2)
+        result = client.request("thread/loaded/list", {}, timeout=2)
+    except Exception as error:
+        return f"Codex app-server control socket at {path} is unreachable: {error}"
+    finally:
+        if client is not None:
+            client.close()
+    loaded = result.get("data")
+    if not isinstance(loaded, list) or not all(isinstance(item, str) for item in loaded):
+        return f"Codex app-server at {path} did not confirm its loaded threads"
+    if thread_id not in loaded:
+        return (f"Codex parent thread {thread_id} is not loaded in the app-server at {path}; "
+                "a separate TUI process cannot receive its notifications there")
+    return None
+
+
+def _owned_codex_thread(store, thread_id: str):
+    """Complete read-only native return-address census, never a worker alias."""
+    from ccx.errors import SessionUnavailable
+
+    if not isinstance(thread_id, str) or not thread_id:
+        raise InvalidRequest("Notification needs a Codex recipient; call it from Codex")
+    matched = None
+    for row in store.list_workers(engine="codex", limit=None):
+        native = store.record(row["worker"]).get("native")
+        if not isinstance(native, dict):
+            raise SessionUnavailable("Codex worker list is unavailable; check CCX_ROOT")
+        if native.get("threadId") == thread_id:
+            if matched is not None:
+                raise SessionUnavailable("Cannot identify the Codex caller; use a worker handle")
+            matched = row["worker"]
+    store.revalidate()
+    return store.resolve(matched) if matched is not None else None
+
+
+@dataclass(frozen=True)
+class CallerContext:
+    """Full-UUID owned caller or explicitly unverified native origin."""
+    kind: str  # codex | claude | unknown
+    native_id: str | None = None
+    worker_id: str | None = None
+    managed: bool = False
+
+    def parent_notify_unavailable(self) -> str | None:
+        """The single capability rule for wait policy and notification arms."""
+        if (self.kind != "codex" or not self.native_id
+                or (not self.worker_id if self.managed else self.worker_id is not None)):
+            return ("parent notification needs a managed Codex caller or its own "
+                    "CODEX_THREAD_ID; Claude and mixed origins are not supported")
+        if self.managed:
+            return None  # CCX-owned parents keep their original codexd path.
+        return _external_codex_unavailable(self.native_id)
+
+    @property
+    def supports_parent_notify(self) -> bool:
+        return self.parent_notify_unavailable() is None
+
+    def parent_ref(self) -> dict[str, Any]:
+        unavailable = self.parent_notify_unavailable()
+        if unavailable is not None:
+            raise InvalidRequest(f"{unavailable}; use --wait / ccx wait TARGET instead")
+        from ccx.constants import CCX_ROOT
+        from ccx.errors import SessionUnavailable
+        from ccx.store.root import GenerationError, require_ccx_active
+        from ccx.store.identity import IdentityError
+
+        if not self.managed:
+            # The caller's own CODEX_THREAD_ID is a return address, not a
+            # worker target. A missing managed stamp must never cause the
+            # interactive app-server to dual-subscribe a CCX-owned rollout.
+            try:
+                store = require_ccx_active(CCX_ROOT)
+                if _owned_codex_thread(store, self.native_id) is not None:
+                    raise InvalidRequest(
+                        "Notification recipient is already a CCX worker; use that handle"
+                    )
+            except (GenerationError, IdentityError, OSError) as exc:
+                raise SessionUnavailable(
+                    f"Cannot list Codex workers; check CCX_ROOT: {exc}"
+                ) from exc
+            return {"kind": "codex-native-thread", "threadId": self.native_id}
+
+        try:
+            store = require_ccx_active(CCX_ROOT)
+            owner = store.resolve(f"codex:{self.worker_id}")
+            store.authorize_native_action(owner.worker, "send")
+            native = store.record(owner.worker).get("native")
+            if not isinstance(native, dict):
+                raise SessionUnavailable("Codex worker record is missing; inspect its handle")
+            if (native.get("threadId") != self.native_id
+                    or native.get("threadSource")
+                    != store.codex_source(owner.worker)):
+                raise SessionUnavailable(
+                    "Codex caller does not match the worker; verify the handle"
+                )
+            store.revalidate()
+        except (GenerationError, IdentityError, OSError) as exc:
+            raise SessionUnavailable(
+                f"Cannot verify the Codex parent worker; inspect status: {exc}"
+            ) from exc
+        return {"kind": "ccx-codex", "workerId": owner.worker_id,
+                "threadId": native["threadId"], "generation": store.generation}
+
+
+def current_caller() -> CallerContext:
+    """Classify owner with full-ID engine stamp; never infer from old short.
+
+    The managed full-ID stamp is independently checked against current
+    ACTIVE global owner record and provider-native thread/session identity.
+    A native-only stamp is NOT a CCX worker association.
+    """
+    from ccx.store.records import spawned_by_from_env
+    from ccx.constants import CCX_ROOT
+    from ccx.store.root import GenerationError, require_ccx_active
+    from ccx.errors import SessionUnavailable
+
+    origin = spawned_by_from_env()
+    if origin is None:
+        return CallerContext("unknown")
+    if origin.get("kind") == "ccx-worker":
+        wid, engine = origin["workerId"], origin["engine"]
+        try:
+            rec = require_ccx_active(CCX_ROOT).record(f"{engine}:{wid}")
+        except (GenerationError, OSError) as exc:
+            raise SessionUnavailable(
+                f"Caller worker changed; retry the notification: {exc}"
+            ) from exc
+        native = rec.get("native") if isinstance(rec.get("native"), dict) else {}
+        key = "sessionId" if engine == "claude" else "threadId"
+        env_key = ("CLAUDE_CODE_SESSION_ID" if engine == "claude"
+                   else "CODEX_THREAD_ID")
+        supplied = os.environ.get(env_key, "").strip()
+        if supplied and supplied != native.get(key):
+            raise SessionUnavailable(
+                "Codex caller does not match this worker; verify the handle"
+            )
+        return CallerContext(
+            engine, native_id=supplied or native.get(key),
+            worker_id=wid, managed=True,
+        )
+    if origin.get("kind") == "provider-native-unknown":
+        engine = origin.get("engine")
+        if engine in ("codex", "claude"):
+            return CallerContext(engine, native_id=origin.get("nativeId"))
+        return CallerContext("unknown")
+    raise SessionUnavailable("Notification caller could not be identified; use a CCX Codex worker")
+
+
+def require_notify_parent() -> dict[str, Any]:
+    """Return the machine-continuation parent reference or raise before effects."""
+    return current_caller().parent_ref()
+
+
+def codex_blocking_override_enabled() -> bool:
+    """Hidden developer escape hatch; intentionally absent from the public CLI."""
+    return os.environ.get("CCX_ALLOW_CODEX_BLOCKING_WAIT", "").strip().lower() in {
+        "1", "true", "yes", "on"
+    }

package/ccx/controllers/policy.py

@@ -0,0 +1,57 @@
+"""Harness-specific CLI policy for blocking versus continuation modes."""
+
+from __future__ import annotations
+
+import sys
+
+from ccx.constants import EXIT_ERROR
+from ccx.controllers.orchestrator import codex_blocking_override_enabled, current_caller
+
+
+def blocking_turn_family(argv: list[str]) -> str | None:
+    """Classify calls whose blocking completion has a durable continuation sibling.
+
+    This includes model turns and native compaction. Operational waits such as
+    kill confirmation and report reads stay synchronous because notification is
+    not a semantic replacement for them.
+    """
+    if not argv or "--help" in argv or "-h" in argv:
+        return None
+    command, flags = argv[0], argv[1:]
+    if command in {"new", "fork"} and "--wait" in flags:
+        return command
+    # Every managed root send is a strict new turn and waits by default,
+    # regardless of the child engine. No target/native probe is needed here.
+    if command == "send" and "--no-wait" not in flags and "--notify-parent" not in flags:
+        return "send"
+    if command == "wait":
+        return "wait.next-turn" if "--next-turn" in flags else "wait"
+    if command in {"answer", "approve", "reject", "respond"} and "--wait" in flags:
+        return command
+    if command == "compact" and "--no-wait" not in flags and "--notify-parent" not in flags:
+        return "compact"
+    return None
+
+
+def _guidance(family: str) -> str:
+    if family == "wait.next-turn":
+        return "use `ccx notify TARGET --next-turn` to arm a durable future-turn continuation"
+    if family in {"wait"}:
+        return "use `ccx notify TARGET` to arm a durable parent continuation"
+    if family == "compact":
+        return "use `--notify-parent` so Codex is resumed when the exact compact operation settles"
+    return "use `--notify-parent` instead of blocking for the worker turn"
+
+
+def reject_codex_blocking_call(argv: list[str]) -> None:
+    family = blocking_turn_family(argv)
+    if family is None or codex_blocking_override_enabled():
+        return
+    if not current_caller().supports_parent_notify:
+        return
+    sys.stderr.write(
+        "[ccx] blocking CCX waits are disabled for Codex orchestrators when a durable continuation exists; "
+        + _guidance(family)
+        + ". The notification returns immediately and resumes Codex when the awaited operation settles.\n"
+    )
+    raise SystemExit(EXIT_ERROR)