subs-pool 0.1.0__py3-none-any.whl

subs_pool/__init__.py

@@ -0,0 +1,3 @@
+"""General-purpose subscription pool with explicit built-in modules."""
+
+__version__ = "0.1.0"

subs_pool/__main__.py

@@ -0,0 +1,4 @@
+from .cli import main
+
+if __name__ == "__main__":
+    raise SystemExit(main())

subs_pool/agent_cli.py

@@ -0,0 +1,69 @@
+"""Machine-only ``subspool-cli`` entry point."""
+
+from __future__ import annotations
+
+import json
+import sys
+from typing import Any
+
+from . import __version__
+from .output import envelope, error_object
+from .registry import BUILTIN_MODULES
+
+
+def _emit(command: str, rc: int, data: Any = None, *, error: dict[str, Any] | None = None) -> int:
+    if rc != 0 and error is None:
+        refresh_error = data.get("refresh", {}).get("error") if isinstance(data, dict) else None
+        if isinstance(refresh_error, dict):
+            error = error_object(
+                str(refresh_error.get("code", "operation_unavailable")),
+                str(refresh_error.get("message", "operation did not complete")),
+            )
+        else:
+            error = error_object("operation_unavailable", "operation did not complete")
+    print(json.dumps(envelope(command, ok=rc == 0, data=data, error=error), ensure_ascii=False, separators=(",", ":"), allow_nan=False))
+    return rc
+
+
+def main(argv: list[str] | None = None) -> int:
+    args = list(argv) if argv is not None else sys.argv[1:]
+    if not args:
+        return _emit("help", 0, {"usage": "subspool-cli [--help|--version] codex COMMAND"})
+    if args == ["--help"]:
+        return _emit("help", 0, {"usage": "subspool-cli codex account|status|quota"})
+    if args == ["--version"]:
+        return _emit("version", 0, {"version": __version__})
+    if args[0] == "modules":
+        if args[1:] == ["--help"]:
+            return _emit("modules", 0, {"usage": "subspool-cli modules [list]"})
+        if args[1:] not in ([], ["list"]):
+            return _emit("modules", 2, None, error=error_object("invalid_syntax", "usage: subspool-cli modules [list]"))
+        return _emit("modules", 0, {"modules": [{"id": m.id, "display_name": m.display_name} for m in BUILTIN_MODULES]})
+    if args[0] == "tui":
+        return _emit("tui", 2, None, error=error_object("unsupported_command", "the machine executable never opens the TUI"))
+    if args[0] != "codex":
+        return _emit("help", 2, None, error=error_object("unknown_module", "unknown subscription module"))
+    command = "codex"
+    if len(args) > 1:
+        if args[1] != "--help":
+            command = "codex." + args[1]
+        if args[1] == "account" and len(args) > 2 and args[2] != "--help":
+            command += "." + args[2]
+    try:
+        from .modules.codex.cli import machine_operation
+
+        rc, data = machine_operation(args)
+        if isinstance(data, dict) and isinstance(data.get("error"), dict):
+            return _emit(command, rc, None, error=data["error"])
+        return _emit(command, rc, data)
+    except KeyboardInterrupt:
+        return _emit(command, 130, None, error=error_object("interrupted", "operation interrupted"))
+    except Exception:
+        return _emit(command, 5, None, error=error_object("internal_error", "unexpected internal failure"))
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())
+
+
+__all__ = ["main"]

subs_pool/cli.py

@@ -0,0 +1,77 @@
+"""Human ``subspool`` dispatcher."""
+
+from __future__ import annotations
+
+import sys
+
+from . import __version__
+from .registry import BUILTIN_MODULES, DEFAULT_MODULE_ID, UnknownModuleError, get_module
+
+_USAGE = """usage: subspool [tui | modules [list] | codex COMMAND ...]
+
+With no arguments, open the Codex account TUI.
+  tui                 open the TUI
+  modules [list]      list static built-in modules
+  codex COMMAND       run a human Codex operation
+  --version           print the version
+"""
+
+
+def _error(message: str, code: int = 2) -> int:
+    print(f"error: {message}", file=sys.stderr)
+    return code
+
+
+def _run_tui(module_id: str) -> int:
+    try:
+        module = get_module(module_id)
+    except UnknownModuleError as exc:
+        return _error(str(exc))
+    from .tui import run_tui
+
+    run_tui(module.id)
+    return 0
+
+
+def _list_modules() -> int:
+    for module in BUILTIN_MODULES:
+        marker = " (default)" if module.id == DEFAULT_MODULE_ID else ""
+        print(f"{module.id:<16} {module.display_name}{marker}")
+    return 0
+
+
+def main(argv: list[str] | None = None) -> int:
+    args = list(argv) if argv is not None else sys.argv[1:]
+    if not args:
+        return _run_tui(DEFAULT_MODULE_ID)
+    if args == ["--help"] or args == ["-h"]:
+        print(_USAGE, end="")
+        return 0
+    if args == ["--version"]:
+        print(f"subspool {__version__}")
+        return 0
+    if args[0] == "modules":
+        rest = args[1:]
+        if rest in ([], ["list"]):
+            return _list_modules()
+        return _error("usage: subspool modules [list]")
+    if args[0] == "tui":
+        if args[1:] in ([], ["codex"]):
+            return _run_tui(DEFAULT_MODULE_ID)
+        if args[1:] in (["--help"], ["-h"]):
+            print("usage: subspool tui [codex]")
+            return 0
+        return _error("usage: subspool tui [codex]")
+    try:
+        module = get_module(args[0])
+    except UnknownModuleError as exc:
+        print(f"error: {exc}", file=sys.stderr)
+        return 2
+    return module.command_main(args[1:])
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())
+
+
+__all__ = ["main"]

subs_pool/cli_client.py

@@ -0,0 +1,365 @@
+"""Thin async subprocess wrapper around a subs-pool module CLI contract.
+
+This module owns no account/token/auth state and makes no provider HTTP calls.
+Machine-safe operations use the JSON-only ``subspool-cli`` module entrypoint;
+the human TUI's device-login stream uses the human dispatcher with a private
+JSONL adapter. The subprocess spawn function is injectable so tests can supply
+a fake process without starting a real one.
+"""
+
+from __future__ import annotations
+
+import asyncio
+import json
+import re
+import sys
+from collections.abc import Awaitable, Callable, Sequence
+from typing import Any, Protocol
+
+
+class CLIError(Exception):
+    """Raised when a subs-pool module CLI exits non-zero or emits bad output."""
+
+    def __init__(self, message: str, *, returncode: int | None = None, data: dict | None = None) -> None:
+        super().__init__(message)
+        self.message = message
+        self.returncode = returncode
+        self.data = data
+
+
+class Process(Protocol):
+    """The minimal subset of :class:`asyncio.subprocess.Process` used here."""
+
+    returncode: int | None
+    stdout: Any
+    stderr: Any
+
+    async def communicate(self) -> tuple[bytes, bytes]: ...
+
+    async def wait(self) -> int: ...
+
+    def terminate(self) -> None: ...
+
+    def kill(self) -> None: ...
+
+
+Spawner = Callable[[Sequence[str]], Awaitable[Process]]
+
+
+async def _default_spawn(args: Sequence[str]) -> Process:
+    return await asyncio.create_subprocess_exec(
+        sys.executable,
+        "-m",
+        "subs_pool.agent_cli",
+        *args,
+        stdout=asyncio.subprocess.PIPE,
+        stderr=asyncio.subprocess.PIPE,
+    )
+
+
+async def _default_human_spawn(args: Sequence[str]) -> Process:
+    """Run the human dispatcher for the TUI-only login event stream."""
+    return await asyncio.create_subprocess_exec(
+        sys.executable,
+        "-m",
+        "subs_pool.cli",
+        *args,
+        stdout=asyncio.subprocess.PIPE,
+        stderr=asyncio.subprocess.PIPE,
+    )
+
+
+_MAX_RAW_ERROR_CHARS = 2000
+_LOGIN_EXIT_TIMEOUT_SECONDS = 5.0
+_SENSITIVE_ASSIGNMENT = re.compile(
+    r"(?i)\b(access[_-]?token|refresh[_-]?token|id[_-]?token|password|secret|api[_-]?key|authorization)"
+    r"(\s*[:=]\s*)([\"']?)([^\"'\s,}]+)"
+)
+_SENSITIVE_BEARER = re.compile(r"(?i)\bBearer\s+[^\s,}]+")
+_SENSITIVE_SECRET_PREFIX = re.compile(r"\b(?:sk|sess|rt|at)-[A-Za-z0-9_-]{8,}\b")
+
+
+def _safe_text(text: str) -> str:
+    """Bound and redact common credential forms in fallback diagnostics."""
+    text = _SENSITIVE_ASSIGNMENT.sub(r"\1\2<redacted>", text)
+    text = _SENSITIVE_BEARER.sub("Bearer <redacted>", text)
+    text = _SENSITIVE_SECRET_PREFIX.sub("<redacted>", text)
+    return text if len(text) <= _MAX_RAW_ERROR_CHARS else text[:_MAX_RAW_ERROR_CHARS] + "… (truncated)"
+
+
+def _parse_error(stderr: bytes) -> str:
+    text = stderr.decode(errors="replace").strip()
+    if not text:
+        return "subs-pool module CLI exited with an error (no message)"
+    # Contract errors are one JSON object on the last non-empty stderr line.
+    # A broken installation may instead produce a traceback; retain a bounded,
+    # redacted diagnostic rather than dumping unbounded/provider-tainted text.
+    try:
+        payload = json.loads(text.splitlines()[-1])
+    except json.JSONDecodeError:
+        return _safe_text(text)
+    if isinstance(payload, dict):
+        if isinstance(payload.get("error"), str):
+            return _safe_text(payload["error"])
+        if isinstance(payload.get("error"), dict):
+            return _safe_text(str(payload["error"].get("message", "module CLI failed")))
+        return "subs-pool module CLI returned a malformed error response"
+    return _safe_text(text)
+
+
+def _safe_login_event(event: dict) -> dict:
+    """Project JSONL events onto the small non-secret frontend contract."""
+    kind = event.get("event")
+    if kind == "authorization_required":
+        return {
+            "event": "authorization_required",
+            "verification_uri": event.get("verification_uri", ""),
+            "user_code": event.get("user_code", ""),
+            "expires_in": event.get("expires_in"),
+            "interval": event.get("interval"),
+        }
+    if kind == "completed":
+        account = event.get("account")
+        if not isinstance(account, dict):
+            raise CLIError("malformed login event: completed event lacks account")
+        return {
+            "event": "completed",
+            "account": {
+                key: account[key]
+                for key in ("ref", "enabled", "weight", "auth_present", "quota")
+                if key in account
+            },
+        }
+    # Unknown events are not part of the contract. Preserve only their type so
+    # a broken child cannot smuggle arbitrary provider payloads into the UI.
+    return {"event": str(kind) if kind is not None else "unknown"}
+
+
+async def _spawn_or_raise(spawn: Spawner, args: Sequence[str]) -> Process:
+    try:
+        return await spawn(args)
+    except FileNotFoundError as exc:
+        raise CLIError(
+            "subs-pool CLI not found: is subs-pool installed for this interpreter?"
+        ) from exc
+
+
+async def _terminate_process(proc: Process) -> None:
+    """Best-effort terminate and reap a local child process this wrapper owns.
+
+    This only touches our local CLI subprocess; it never claims to cancel a
+    request already submitted upstream to a provider.
+    """
+    if proc.returncode is not None:
+        return
+    try:
+        proc.terminate()
+    except (OSError, ProcessLookupError):
+        return
+    try:
+        await asyncio.wait_for(proc.wait(), timeout=5)
+    except asyncio.TimeoutError:
+        try:
+            proc.kill()
+        except (OSError, ProcessLookupError):
+            return
+        await proc.wait()
+
+
+class LoginStream:
+    """One in-flight device-login event stream for the human frontend.
+
+    Async-iterate this to receive parsed JSONL events as they arrive. A
+    ``completed`` line is held until the child has drained its pipes and exited
+    with code zero; a line alone is never treated as success. :meth:`cancel`
+    stops only the local CLI subprocess.
+    """
+
+    def __init__(self, spawn: Spawner, args: Sequence[str]) -> None:
+        self._spawn = spawn
+        self._args = list(args)
+        self._proc: Process | None = None
+        self._done = False
+        self._cancel_requested = False
+
+    def __aiter__(self) -> "LoginStream":
+        return self
+
+    async def __anext__(self) -> dict:
+        if self._done:
+            raise StopAsyncIteration
+        if self._proc is None:
+            proc = await _spawn_or_raise(self._spawn, self._args)
+            self._proc = proc
+            if self._cancel_requested:
+                await _terminate_process(proc)
+                raise StopAsyncIteration
+        assert self._proc.stdout is not None
+        raw = await self._proc.stdout.readline()
+        if not raw:
+            try:
+                returncode = await asyncio.wait_for(self._proc.wait(), timeout=_LOGIN_EXIT_TIMEOUT_SECONDS)
+            except asyncio.TimeoutError:
+                await _terminate_process(self._proc)
+                self._done = True
+                raise CLIError("login CLI did not exit after closing stdout")
+            self._done = True
+            if returncode != 0:
+                stderr = await self._proc.stderr.read() if self._proc.stderr is not None else b""
+                raise CLIError(_parse_error(stderr), returncode=returncode)
+            raise StopAsyncIteration
+
+        line = raw.decode(errors="replace").strip()
+        if not line:
+            return await self.__anext__()
+        try:
+            event = json.loads(line)
+        except json.JSONDecodeError as exc:
+            self._done = True
+            await _terminate_process(self._proc)
+            raise CLIError("malformed login event: could not parse JSON") from exc
+        if not isinstance(event, dict):
+            self._done = True
+            await _terminate_process(self._proc)
+            raise CLIError(
+                f"malformed login event: expected a JSON object, got {type(event).__name__}"
+            )
+        if event.get("event") == "completed":
+            try:
+                safe_event = _safe_login_event(event)
+            except CLIError:
+                self._done = True
+                await _terminate_process(self._proc)
+                raise
+            return await self._finish_completed(safe_event)
+        return _safe_login_event(event)
+
+    async def _finish_completed(self, event: dict) -> dict:
+        """Trust ``completed`` only after clean child termination.
+
+        ``communicate`` drains both pipes while waiting. The bounded wait also
+        handles a provider-poll process that emits a completion line and then
+        hangs, without leaving a child behind or claiming successful login.
+        """
+        assert self._proc is not None
+        try:
+            _stdout, stderr = await asyncio.wait_for(
+                self._proc.communicate(), timeout=_LOGIN_EXIT_TIMEOUT_SECONDS
+            )
+        except asyncio.TimeoutError as exc:
+            await _terminate_process(self._proc)
+            self._done = True
+            raise CLIError("login CLI did not exit cleanly after completion") from exc
+        except asyncio.CancelledError:
+            await _terminate_process(self._proc)
+            self._done = True
+            raise
+        self._done = True
+        returncode = self._proc.returncode
+        if returncode is None:
+            returncode = await self._proc.wait()
+        if returncode != 0:
+            raise CLIError(_parse_error(stderr), returncode=returncode)
+        return event
+
+    async def cancel(self) -> None:
+        """Terminate the in-flight login subprocess, if any (idempotent)."""
+        if self._done:
+            return
+        self._done = True
+        proc = self._proc
+        if proc is None:
+            self._cancel_requested = True
+            return
+        await _terminate_process(proc)
+
+
+class CLIClient:
+    """Async wrapper for one module's machine command surface."""
+
+    def __init__(
+        self,
+        module_id: str,
+        spawn: Spawner | None = None,
+        *,
+        timeout: float = 30.0,
+    ) -> None:
+        self.module_id = module_id
+        self._spawn = spawn or _default_spawn
+        # Bounds one-shot commands (status/quota/pool/import/etc.), not the
+        # device-login provider poll window owned by the CLI subprocess.
+        self._timeout = timeout
+
+    async def _run_json(self, args: Sequence[str]) -> dict:
+        proc = await _spawn_or_raise(
+            self._spawn, [self.module_id, *args]
+        )
+        try:
+            stdout, stderr = await asyncio.wait_for(proc.communicate(), timeout=self._timeout)
+        except asyncio.TimeoutError as exc:
+            await _terminate_process(proc)
+            raise CLIError(f"subs-pool module CLI timed out after {self._timeout:g}s") from exc
+        except asyncio.CancelledError:
+            await _terminate_process(proc)
+            raise
+        if proc.returncode != 0:
+            try:
+                payload = json.loads(stdout.decode(errors="replace"))
+                error = payload.get("error") if isinstance(payload, dict) else None
+                if isinstance(error, dict):
+                    raise CLIError(str(error.get("message", "module CLI failed")), returncode=proc.returncode, data=payload.get("data") if isinstance(payload.get("data"), dict) else None)
+            except json.JSONDecodeError:
+                pass
+            raise CLIError(_parse_error(stderr), returncode=proc.returncode)
+        try:
+            payload = json.loads(stdout.decode(errors="replace"))
+        except json.JSONDecodeError as exc:
+            raise CLIError(f"malformed CLI output: could not parse JSON ({len(stdout)} bytes)") from exc
+        if not isinstance(payload, dict):
+            raise CLIError(
+                f"malformed CLI output: expected a JSON object, got {type(payload).__name__}"
+            )
+        if payload.get("schema_version") == 1 and "ok" in payload:
+            if not payload.get("ok"):
+                if isinstance(payload.get("data"), dict):
+                    return payload["data"]
+                error = payload.get("error")
+                message = error.get("message", "module CLI failed") if isinstance(error, dict) else "module CLI failed"
+                raise CLIError(str(message), returncode=proc.returncode)
+            data = payload.get("data")
+            return data if isinstance(data, dict) else {}
+        return payload
+
+    async def accounts_list(self) -> dict:
+        return await self._run_json(["account", "list"])
+
+    async def accounts_import(self, ref: str, path: str, *, weight: int = 1) -> dict:
+        return await self._run_json(
+            ["account", "import", ref, "--path", path, "--weight", str(weight)]
+        )
+
+    async def pool_enable(self, ref: str) -> dict:
+        return await self._run_json(["account", "enable", ref])
+
+    async def pool_disable(self, ref: str) -> dict:
+        return await self._run_json(["account", "disable", ref])
+
+    async def pool_weight(self, ref: str, weight: int) -> dict:
+        return await self._run_json(["account", "weight", ref, str(weight)])
+
+    async def status(self) -> dict:
+        return await self._run_json(["status"])
+
+    async def quota(self) -> dict:
+        return await self._run_json(["quota"])
+
+    def login(self, ref: str) -> LoginStream:
+        """Start login lazily, on first iteration."""
+        spawn = _default_human_spawn if self._spawn is _default_spawn else self._spawn
+        return LoginStream(
+            spawn,
+            [self.module_id, "account", "login", ref, "--device", "--events-jsonl"],
+        )
+
+
+__all__ = ["CLIClient", "CLIError", "LoginStream", "Process", "Spawner"]

subs_pool/home.py

@@ -0,0 +1,41 @@
+"""Canonical data-root resolution owned by the subscription-pool core."""
+
+from __future__ import annotations
+
+import os
+from pathlib import Path
+
+DEFAULT_HOME = "~/.subs-pool"
+
+
+class HomeError(ValueError):
+    """The selected subscription-pool root is not usable."""
+
+
+def _resolve_env_path(name: str, default: str) -> Path:
+    value = os.environ.get(name, default)
+    if value == "":
+        raise HomeError(f"{name} must not be empty")
+    path = Path(value).expanduser()
+    if not path.is_absolute():
+        path = Path.cwd() / path
+    return path.resolve()
+
+
+def data_home(*, create: bool = True) -> Path:
+    """Return the canonical generic root.
+
+    The core never searches for old roots.  Creation is explicit so machine
+    help/version paths can remain state-free while stateful operations create
+    only their selected root.
+    """
+    home = _resolve_env_path("SUBS_POOL_HOME", DEFAULT_HOME)
+    if create:
+        existed = home.exists()
+        home.mkdir(parents=True, exist_ok=True)
+        if not existed and os.name != "nt":
+            home.chmod(0o700)
+    return home
+
+
+__all__ = ["DEFAULT_HOME", "HomeError", "data_home"]

subs_pool/modules/__init__.py

@@ -0,0 +1 @@
+"""Built-in subscription modules."""

subs_pool/modules/codex/CLI_CONTRACT.md

@@ -0,0 +1,44 @@
+# Codex CLI contract
+
+Human operations are selected by `subspool codex`. Agent operations are
+selected by `subspool-cli codex` and are wrapped by the root JSON envelope.
+
+```text
+account import ID --path AUTH.json [--weight N]
+account list
+account login ID --device       # human only
+account enable ID
+account disable ID
+account weight ID N
+status
+quota
+serve --listen 127.0.0.1:8765  # human only
+```
+
+Account list is metadata-only and never reports quota readiness. Account IDs
+are any non-empty path-safe strings; `/`, `\`, `.`, and `..` are rejected,
+with no additional ASCII or length restriction. Existing IDs remain readable.
+Auth paths are explicit references; credentials
+are not copied into a generic home. There is no logout/remove command in this
+release.
+
+`quota` always requests the shared bounded pool-wide refresh, whether or not a
+proxy is running. Its data includes `module`, resolved `codex_root`,
+`generated_at`, committed `snapshot_revision`, refresh outcome, account rows,
+current sample, historical `last_success`, timestamps, freshness/age,
+eligibility, exclusion reason, and sanitized error. Missing/failed/checking or
+stale samples are not current values. A failed required refresh returns exit
+3 while retaining the readable partial snapshot in Agent `data`.
+
+The WHAM adapter makes one direct request per account, retains the baseline
+nullable secondary-window parsing, calculates remaining as `100 - used` only
+for valid finite percentages, and never fabricates zero for unknown. Provider
+bodies, auth headers, tokens, device codes, and credential paths never enter
+machine output or errors.
+
+Agent `login` and `serve` return stable `prompt_required`/`unsupported_command`
+errors; they never prompt, open a browser, bind a port, or write human text.
+Agent parser/usage errors likewise produce one JSON object plus newline. Exit
+codes are 0 success, 2 syntax/unsupported, 3 unavailable/incomplete quota or
+auth/network work, 4 local state/configuration, 5 unexpected internal failure,
+and 130 interruption.

subs_pool/modules/codex/CONTRACT.md

@@ -0,0 +1,52 @@
+# Codex module contract
+
+Codex is the only built-in provider module. It owns auth, account
+configuration, WHAM parsing, quota sidecar/freshness/refresh, eligibility,
+routing, affinity, upstream wire behavior, SSE, and the local Responses
+server. Generic `subs_pool` code does not inspect any of these facts.
+
+The module keeps the baseline two-rule scheduler: a full input-prefix and
+effective-config match stays on its current in-memory chain account; a miss is
+a weighted choice. Full-prefix hashing, UUID session labels, chain capacity,
+successful-only commits, and response normalization remain in the relocated
+baseline files. A failed, partial, cancelled, or incomplete generation never
+commits and is never retried or replayed.
+
+Before selection, the module reads account configuration and
+`quota-v1.json` together under `state.lock`. A candidate must be enabled,
+locally authenticated, on the current quota
+epoch, `status=ok`, fresh under the fixed 60-second source-time policy, and
+have known positive remaining capacity. A nullable secondary window remains
+nullable according to the baseline WHAM parser; if it is present and
+exhausted it excludes the account. Unknown quota is never turned into zero or
+green capacity. No candidate means a local HTTP 503 with code
+`quota_unavailable`, before any upstream generation request.
+
+The sidecar is the sole quota authority. Its top-level schema is version 1,
+module `codex`, monotonic revision, replacement timestamp, and account-keyed
+records containing epoch, status (`never`/`checking`/`ok`/`failed`), attempt
+metadata, refresh marker, last successful sample, and sanitized error. It
+contains no tokens or raw provider bodies. Failed refreshes preserve the
+historical `last_success` but never expose it as current.
+
+Sidecar writes use same-directory exclusive temporary files, flush/fsync,
+atomic replace, directory fsync where supported, and mode 0600 state files.
+`filelock` backs the persistent `state.lock` and
+`quota-v1.refresh.lock` inodes. State locking is short; network work never
+holds it. One pool-wide owner performs at most two account checks concurrently
+and foreground coordination is bounded. Followers join completed overlapping
+waves or fail closed; they do not steal a live kernel lock.
+
+The direct Codex root is explicit `CODEX_POOL_HOME`, otherwise
+`${SUBS_POOL_HOME:-~/.subs-pool}/codex`. The root itself contains `pool.json`,
+`quota-v1.json`, `state.lock`, and `quota-v1.refresh.lock`; there is no
+`accounts/` relocation or hidden migration. Existing `pool.json` entries
+without `quota_epoch` mean `legacy-v1` for compatibility. Mutations that
+change enablement, auth, or identity advance the epoch and remove its quota
+record.
+
+The foreground server remains `--listen 127.0.0.1:8765`, loopback-only, and
+user-managed. It refreshes on startup, at the 30-second target while running,
+and just-in-time when no current candidate exists. It does not install a
+service, auto-start from the TUI, persist affinity, or perform generation
+failover.

subs_pool/modules/codex/__init__.py

@@ -0,0 +1 @@
+"""Codex subscription module: accounts, auth, quota, routing, and protocol."""