# Compatibility and evidence boundaries

This is a local Python 3.11+ MVP using the pinned official Python MCP SDK `1.30.0` stdio interface. It does not implement MCP 2.0 Events. Linux and macOS/POSIX are supported execution targets. Since 0.9.30 the core, setup, the runtime bootstrap and `aot serve` also run on Windows: CI runs the test suite and a real bootstrap there, but no host (Claude Code, Codex) has been tried on a Windows machine yet; see [Windows](OPERATIONS.md#windows). Platform coverage is limited to the host and checks recorded in the implementation test report. Native scoped Codex tools were exercised live on 2026-10-19; Windows, curated-store submission and plugin UI installation remain untested. The macOS native listener checks are scoped below.

| Surface | Package support and limit |
| --- | --- |
| Python MCP client over stdio | Independent processes sharing one bot/state database with separate capabilities passed offline SDK interoperability tests. |
| Codex native scoped tools | Live checks covered same-bot broker delivery/deduplication and Alpha pause/queued intake/resume/reply/ack while Beta remained usable. |
| Codex desktop plugin UI | Normal installation declares skills and onboarding, with no plugin MCP server. UI installation, enablement and automatic skill/setup-button discovery remain untested; see the versioned validation record. |
| Runtime bootstrap | The packaged bootstrap requires local Python 3.11+ and prepares a stable private runtime from the installed plugin. uv is optional; its absence selects Python venv/ensurepip and private-environment pip, which require the corresponding Python support modules. No separately maintained source checkout is required. It does not install prerequisites, select a live account or start listening. |
| Codex marketplace CLI | The root `.agents/plugins` catalog names the marketplace and plugin `agents-over-telegram`. Native CLI registration and installation passed from the public `fourlastor/agents-over-telegram` GitHub repository in an empty Codex home, followed by runtime bootstrap and fresh fake scoped MCP checks. |
| Exact-project setup | Guided onboarding selects the bootstrap-returned executable for a new project and preserves the runtime already configured for an existing one. It prepares a private profile reference and one native project `telegram` MCP entry. Reload/reopen the project chat to load it. Only the exact directory selects that profile; all chats in the project share its identity. The user decides project trust in Codex. |
| Claude | Deferred. No Claude-specific command or integration is claimed. |
| One global plugin MCP entry across several Codex chats | The server cannot tell these chats apart. All callers using that entry share its selected client permissions. This is not a per-chat isolation mode. |
| Separate scoped stdio configurations | Supported authentication boundary: each configuration points to a different private client file. The core authorizes the resulting connection on every request. |
| ChatGPT web / Cloud | This package needs a local executable and private local state; no hosted endpoint or cloud relay is provided. |
| Recent captured context | `messages_history` / CLI `history` provide a scoped, bounded, paginated 24-hour local view including acknowledged inbound, own outbound statuses and broker metadata. Reads do not collect, send, claim, acknowledge or replay. |
| Complete preconnection Telegram history | Not provided. The view cannot retrieve updates already consumed elsewhere, prebinding omissions, or unconfigured/disallowed message bodies; no old-bridge history import exists. |
| Normal-launch desktop listener | `relay-desktop` uses the installed native Codex queue and OS wake URL for an existing local chat. Automatic Telegram collection, same-local-chat wake, native poll/reply/ack passed on normally launched Linux desktop with bundled Codex 0.163.0-alpha.10.2. Ledger confirms one sent reply and zero pending; the user also confirmed the reply is visible in Telegram. |
| Older model-mediated relay | A bounded watcher reports to a running relay chat, which calls native `send_message_to_thread`. One live idle-target wake/reply/ack check passed. This is a secondary experimental route; the plugin cannot invoke that host tool externally. |
| Experimental shared-backend dispatcher | `relay-dispatch` passed a manually launched live idle-target wake/reply/ack check using the optional bridge. Its special desktop startup is not required by the normal-launch listener and is not the default setup. The corrected bridge child-startup gate still lacks a final GUI restart check. |
| Listener lifecycle | On-demand remains the default. Explicit `relay-desktop` listening runs for a chosen duration with the normally opened desktop; it needs no relay model. Setup installs no service, autostart or scheduler. Stored messages and ordinary MCP notifications alone do not create turns. |
| MCP Events | Not implemented. The documented callback integration is a separate possible adapter, not evidence of local wakeup. |
| Several machines with the same bot | Unsupported without external receiver coordination. A local file lock cannot exclude a receiver on another host. |
| Same OS user | Trusted local processes. Private files and scoped MCP authorization do not isolate a malicious process already running as the same user. |

## Package formats

The Codex package has one manifest, `.codex-plugin/plugin.json`. It declares the skills in `skills/`, the onboarding skill and the hooks in `codex/hooks.json`. The package root contains no `plugin.json`, `mcp.json` or `.mcp.json`, and the manifest declares no `mcpServers`. [Official package documentation](https://developers.openai.com/plugins/build/plugins)

Up to version 0.8.0 the package also had a root `plugin.json` in the Agent Plugins 1.0.0 format. That file was removed because Codex uses it instead of `.codex-plugin/plugin.json` when both exist, and Codex loads no hooks for an Agent Plugins package. With Codex CLI 0.163.0, `plugin/read` reported no hooks for 0.8.0 and all four hooks once the root file was gone. Adding `hooks` to the root manifest's `extensions.com.openai` object did not help. The Codex 0.163.0 source code confirms both results. [Agent hosts](HOSTS.md#how-the-codex-plugin-hooks-were-checked) has the full check.

Guided setup writes a native project MCP configuration using a stable `aot` executable and one private client file. The setup skill invokes the packaged runtime bootstrap for a new installation; merely loading the plugin does not execute the bootstrap. Since 0.8.0 the Codex manifest also references `codex/hooks.json`. Version 0.8.0 claimed that Codex loads these as plugin hooks, but the root `plugin.json` stopped Codex from loading them (see above). Without that file, Codex lists them as plugin hooks that the human must trust; see [agent hosts](HOSTS.md#codex). The normal Codex plugin still has no MCP launcher to configure. The bootstrap copies the required source and builds a non-editable environment outside the plugin cache. The pip path pins and hash-checks runtime and build dependencies from shipped requirements, using compatible wheels. The existing uv path retains frozen runtime resolution; its isolated build dependencies do not gain the pip path's transitive hash pinning. It uses existing uv when available, otherwise Python 3.11+ venv/ensurepip and pip inside the new environment. It does not install uv or use global pip, and performs no Telegram setup or listening. Pip offline installation requires a populated compatible wheelhouse for the shipped runtime and build requirements; uv offline installation uses its cache. Existing project configurations keep their chosen executable; a plugin update alone does not migrate them. The optional advanced `plugin-render` command synthesizes a private package whose `.codex-plugin/plugin.json` points at a `.mcp.json` stdio declaration with the selected absolute runtime/state/client paths. This one-client package must stay scoped to its intended callers and must not be enabled globally. The bundled launcher is used only by explicit advanced configurations; it requires absolute `AOT_EXECUTABLE`, `AOT_STATE_DIR`, and `AOT_CLIENT_FILE` paths and fails closed if any is absent. [Official desktop-only plugin documentation](https://developers.openai.com/plugins/deploy/desktop-only)

The repository also carries a Claude Code plugin in `.claude-plugin/plugin.json`, with its marketplace in `.claude-plugin/marketplace.json`. Its MCP server, hooks (`claude/hooks.json`) and monitor (`claude/monitors.json`) start through `scripts/aot_host_launch.py`. The Claude hooks and monitor live outside the default `hooks/` and `monitors/` folders, so Codex does not load them, and there is still no root `mcp.json` or `.mcp.json`. `claude plugin validate` passes for both files. Pi and Amp integrations live in `integrations/`. See [agent hosts](HOSTS.md).

The repository's `.agents/plugins/marketplace.json` declares marketplace `agents-over-telegram` with plugin source `./`. The installed Codex CLI accepts `codex plugin marketplace add fourlastor/agents-over-telegram` followed by `codex plugin add agents-over-telegram@agents-over-telegram`. The 0.7.0 local registration and installation passed with isolated `HOME` and `CODEX_HOME`. Bootstrap ran from that installed cache and reused the same runtime on repetition. After both source-package and installed-cache directories were moved away, runtime help and imports still worked from the private virtual environment. Fresh fake Alpha/Beta setup, native MCP scope, read-only status, pause and history checks also passed. Online dependency installation and a fresh offline bootstrap under a long path containing spaces passed. That version's full suite passed **534 tests in 21.15 seconds**; package and setup-skill validation passed. The development workspace records this check in `outputs/first-run-smoke.json`. These results predate the optional-uv pip fallback; its validation is recorded separately in [implementation status](IMPLEMENTATION_STATUS.md).

The 0.7.1 online first-run check also passed without an available uv executable. With `PATH=/usr/bin:/bin`, default bootstrap selected pip from a native CLI-installed plugin cache, reused its runtime on repetition, and still worked after both source/cache copies were moved away. Runtime help, imports and `pip check` passed, followed by fresh fake Alpha/Beta pairing, scoped MCP, status, pause and history checks. The interpreter was a full CPython 3.13.7 installation with ensurepip; no interpreter download or uv dependency cache was needed during the check. The implementation workspace records this result in `outputs/uv-free-smoke.json`. A fresh offline pip install and the same scoped MCP checks also passed using a 35-wheel compatible wheelhouse with network index access disabled. The full 0.7.1 suite passed **561 tests in 21.95 seconds**, including 39 bootstrap tests. The existing uv path also passed a fresh offline bootstrap. Offline pip evidence is recorded in `outputs/uv-free-offline-smoke.json`; these checks used fake Telegram only.

The public [fourlastor/agents-over-telegram repository](https://github.com/fourlastor/agents-over-telegram) was published under Apache-2.0 at commit `7ebd567`. A genuine remote CLI install passed in empty `HOME`/`CODEX_HOME`: GitHub marketplace retrieval and plugin installation, source/metadata/lock/license verification, default pip bootstrap without uv, repeat reuse, cache-independent runtime imports and `pip check`, then fresh fake Alpha/Beta scoped MCP checks. Evidence: `outputs/github-install-smoke.json` in the implementation workspace. Desktop install UI, automatic onboarding-button invocation and fresh real-bot registration remain untested; earlier live Telegram tests cover separately recorded existing-account flows.

The optional `extensions.com.openai.onboardingSkill` in `.codex-plugin/plugin.json` points to the packaged `telegram-setup` skill. Validation checks its existence and containment, including symlink escape. With Codex CLI 0.163.0, `plugin/read` resolved it to `telegram-setup` after a local install, both before and after the root `plugin.json` was removed. This does not prove the host invoked onboarding. [Official onboarding documentation](https://developers.openai.com/plugins/build/plugins#add-an-onboarding-skill)

The vendored MCP schema in `docs/schemas/` was retrieved on 2026-10-19; `sources.json` records its source URL and SHA-256 digest. `scripts/validate_package.py` uses it offline to check the server entries of a rendered `.mcp.json`. The script also rejects a root `plugin.json` or `mcp.json` and checks the manifest identity, the marketplace and the referenced local paths, including the hooks file. It does not claim to validate all OpenAI extension semantics or prove acceptance by a desktop host. [MCP schema](https://agent-plugins.org/schemas/1.0.0/mcp.schema.json)

OpenAI documents MCP Events for Work web, desktop Work with Cloud selected, and dots. This MVP's local stdio server has no event subscription or callback implementation. Do not infer local Codex wakeup support from that documentation. [Official MCP Events documentation](https://developers.openai.com/plugins/build/mcp-events)

## Normal-launch local desktop boundary

The [desktop listener](DIRECT_DISPATCH.md) leaves ChatGPT's usual app-list launch and native backend intact. It validates the exact local thread and project, writes a fixed notice through native `codex queue`, and opens `codex://threads/wake/THREAD_UUID` through the operating system. Project scope, client capability, state directory and fake/live mode must continue to match. Telegram messages cannot authorize or change a mapping.

Version 0.7.2 replaces the exact-version gate with a read-only `codex queue --help` capability check for `--thread` and `--message`. Unknown version strings may proceed when those capabilities and the existing Linux process, schema and routing checks pass. This is an eligibility check, not a claim that every future Codex release or desktop wake implementation has been validated. The live-tested build remains **0.163.0-alpha.10.2**. macOS support is described below; Windows is not supported by this adapter.

The native queue delivers a **user-role** notice. Its text is a trusted fixed local instruction to check the scoped inbox, never Telegram text or sender-supplied instructions. This differs from the experimental app-server dispatcher's tool-output provenance. The target retrieves actual Telegram messages through its existing scoped tools and treats them as untrusted external input.

A live probe on **2026-10-19** used the normally launched Linux desktop and its bundled native Codex **0.163.0-alpha.10.2** with the existing local Alpha UUID. The desktop retained its ordinary stdio backend with no bridge or WebSocket launch override. External native queueing plus the OS wake URL started a new turn, which successfully called `telegram.connection_status` once and verified the expected identity. A repeated wake URL with the native queue empty created no extra turn over an observed interval of at least five seconds. No `send_message_to_thread` forwarding or Telegram publication was used. Evidence: `outputs/native-queue-live-probe.json`.

A subsequent live `relay-desktop` test passed the automatic Telegram round trip. Its collector captured `/test@ab_aot_tester_bot normal-idle-1` as incoming message **22**, queued the fixed notice and opened the wake URL. The same existing local Alpha UUID `01a153ec-3a02-7cb1-9168-b23584e47381` completed turn `01a154e3-9697-7f61-b4b5-92e9a854bbdb` using one native `messages_poll`, one `message_send` and acknowledgment after the outbox recorded `sent`. Telegram reply **23** references message 22 and uses idempotency key `normal-idle-1-reply`; Alpha finished with zero pending deliveries. The queue receipt is `01a154e3-941f-70f1-9c85-e166c3b6cb52`. The normal desktop retained its native direct stdio backend, with no manual wake or model forwarding after the marker arrived. The notification was accepted on attempt one and the target turn completed in **39.3 seconds**. Native tools and persisted delivery records confirm the result; the user also confirmed the reply is visible in Telegram. The development workspace records the receipts in `outputs/normal-startup-validation.json`; that external evidence file is not part of the portable package.

The 0.6.0 automated suite passed **502 tests in 20.97 seconds**; this predates the first-run bootstrap changes. Broader live busy-target, approval and lifecycle checks remain separate work. Other Linux Codex builds and Windows have not been validated for this adapter. The newer macOS checks below are distinct from this Linux result. Queue commands and desktop wake routing are installed-build capabilities rather than a claimed portable MCP feature.

The listener records the enqueue attempt before the native command and stores its returned queue ID before opening the wake URL. If enqueue success is ambiguous, it holds the handoff rather than blindly adding another notice. When the queue ID is known, recovery retries only the wake URL. A successful OS opener exit is not proof of model completion or Telegram handling. Inbox leases, acknowledgment and publication remain the target's separate operations; the listener and optional collector never perform them or flush the outbox.

The adapter checks for an existing desktop before enqueueing and opening the URL. It does not intentionally launch a closed app, but the check and OS opener are not atomic; a close/open race can let the OS launch the app normally. Stopping the listener prevents new attempts but does not remove a previously queued notice or cancel a running turn. No system service, scheduler or custom app launcher is installed.

## Earlier experimental routes

The [model-mediated relay](RELAY.md) uses the same collector, scoped binding and durable notification ledger. A running relay chat forwards fixed notices through native `send_message_to_thread`; it needs the human's authorization for that target. Its repeated bounded waits may return to the model while idle. One live idle-target wake/reply/ack test passed, but the parent chat must stay running. This is a secondary option, not the current normal-launch procedure.

`relay-dispatch` connects to an explicitly shared app-server and injects a fixed tool-output notice with empty user input. It accepts a protected local Unix WebSocket or an authenticated literal-loopback WebSocket and leaves approvals and dynamic tool handling to the desktop owner. It neither discovers a normal stdio backend nor starts another runtime over saved conversation files. An accepted notification remains separate from turn completion, inbox acknowledgment and Telegram publication.

The optional `aot-codex-bridge` test adapter exposes that shared endpoint while preserving the desktop's stdio ownership. An earlier manually launched bounded dispatcher passed a real Telegram idle-wake/reply/ack check. The corrected bridge child-startup gate has isolated coverage but lacks its final real-GUI restart check. This adapter requires a special startup command and is retained only as experimental infrastructure; it is unnecessary for `relay-desktop`.

An isolated native proxy fixture passed **15 checks**, and a native SSH-hosted desktop fixture passed visible idle wakeup with a canned model. The latter used a different remote chat, retained 31 dynamic `codex_app` tools, and did not establish separate coordination MCP, real Telegram handling or ordinary local-chat behavior. Evidence: `outputs/wrapper-free-validation.json` and `work/native-ssh/desktop-wake-result.json`.

A native local restart fixture passed **12 checks**, preserving its UUID/history and invoking its project MCP tool after switching to a native Unix listener. Static inspection found that this special startup path misses the fresh coordination MCP pipe environment and the stdio-only trusted environment for `artifact_session`. It does not establish full desktop tool parity. These launch experiments are not required for the normal-launch route. Evidence: `work/direct-probe/native-restart-persistence-result.json` and `work/wakeup-investigation/local-native-attach-audit.json`.

## Telegram limits

The routing unit is one registered bot plus numeric group ID and optional numeric topic ID. A destination binds to one logical agent. Same-bot coordination uses an explicit internal broker delivery because publication by the shared bot cannot be assumed to reappear as a `getUpdates` item. A visible logical-agent label is not a separate Telegram-authenticated identity.

Telegram's webhook and `getUpdates` receivers are mutually exclusive. Updates are retained by Telegram for at most 24 hours, and a higher offset confirms earlier updates; the core persists its received batch before advancing its local cursor. Extended offline periods can therefore leave unrecoverable upstream gaps. [Telegram getting updates](https://core.telegram.org/bots/api#getting-updates)

The 24-hour local history view and Telegram's update retention are separate limits. Snapshot pagination fixes a 24-hour event-time window with a 15-minute cursor lifetime. It reads captured local records and can include acknowledged messages; it does not query Telegram history or establish that every message from the preceding day was captured. The window does not delete older stored records.

Telegram visibility depends on destination settings and the bot's permissions. Its bot-to-bot mode and addressed/reply behavior require live verification in the selected group. This build does not change BotFather settings, webhooks, or group permissions. [Telegram bot communication](https://core.telegram.org/bots/features#bot-to-bot-communication)


## macOS native queue validation

On 2026-10-19 the adapter was exercised on macOS with the normally running ChatGPT app (bundle ID `com.openai.codex`, app version `26.1013.40934`). No wrapper launcher, Accessibility automation, copied Codex home or replacement backend was used. Read-only capability inspection found `queue --thread --message`; Darwin process inspection matched the app and its direct same-user native stdio backend with the same Codex home.

One fixed local notice was queued to the existing development chat: the native CLI returned a valid queue receipt and `/usr/bin/open -a` accepted the UUID-only wake URL for the same validated app. The target was already busy. These observations establish native queue and OS handoff acceptance, **not** idle model wake, Telegram intake, a Telegram reply, or inbox acknowledgment. The new bot was not paired during this check. The Linux `normal-idle-1` round trip above remains separate evidence.

Tests cover both macOS bundle layouts, the bundled CLI wrapper routing alias, exact UUID URLs pinned to the selected app, owner/process/start-time guards, malformed process arguments, filtering of unrelated environment fields, blocked routing overrides, duplicate/indirect backends and denied process inspection. Linux process and subprocess tests run on both hosts with disposable metadata; a Darwin-only smoke test checks the actual libproc/sysctl ABI against the test process itself.

The complete macOS suite passed with **614 tests passed, 2 skipped** using Python 3.13.16. Package/schema validation also passed. Socket-test fixture directories are canonicalized so macOS's `/var` symlink is not mistaken for an unsafe application endpoint; production socket checks remain strict. The experimental shared-backend wrapper also handles Darwin's EPERM for an already exited leader only after libproc positively reports an empty process group, with failures preserved for live, nonempty or uninspectable groups. No process-group permission error is ignored solely because the leader exited.

Follow-up observation from the same macOS probe: after the preceding busy turn completed, the exact fixed queue notice automatically appeared as a user message in a new turn of the same development chat. No relay model forwarded it. This verifies delivery to a model turn after a busy target finishes, in addition to the CLI receipt and OS URL acceptance. At that stage, a fresh arrival while the target was already idle was untested. The development project had no Telegram profile or loaded Telegram MCP tools, so no real inbox was polled and no deliveries were acknowledged. The later paired tests are recorded below.

## macOS follow-up: idle and busy tests

Follow-up live checks on 2026-10-19 used the same normally launched macOS desktop and a dedicated operator-owned bot, with the existing target's scoped Telegram MCP tools. The idle test passed: intake to model start was 1.116 seconds; intake to sent receipt was 24.72 seconds. The ledger contained one sent reply, an acknowledged input and zero pending messages. The operator confirmed the reply in Telegram. This extends the earlier busy-queue probe; it does not turn a queue receipt into proof of immediate busy-turn delivery.

A separate busy test exposed the limit: the native notice remained queued while the existing turn continued. An operator-installed `PostToolUse` hook then supplied a fixed pending-inbox notice at a tool boundary. After correcting its interpreter to use the plugin Python runtime, a fresh message produced one sent reply in **24.603 seconds**, one acknowledgment and zero pending messages. The same work turn remained active before and after handling. No manual Steer, inter-task forwarding or target restart delivered that fresh marker. The reply was independently visible in Telegram.

The hook is a **local integration, not part of this release**. The check does not prove interruption during a model request, a long-running tool, or unsupported tool paths. Hook trust was reviewed in the CLI because `/hooks` was unavailable in the tested desktop UI. See the [hook constraints](DIRECT_DISPATCH.md#busy-sessions-and-hooks).

An explicitly requested user LaunchAgent also ran the listener with `--duration 0 --collect`. Graceful termination followed by automatic launchd recovery preserved the ledger without duplicate notifications. Desktop reopen and subsequent Telegram handling passed. An OS reboot, automatic desktop startup before login, network-outage recovery, and a multi-day unattended run were **not** exercised. Existing operator power management was retained. The manual service procedure is in [continuous listening on macOS](MACOS_SERVICE.md).
