feat(messaging): add read-only existing-session resume preflight

docs-site/src/content/docs/reference/cli/messaging.md

@@ -47,7 +47,7 @@ Windows is explicitly refused.
   to 16 KiB; NUL and empty text are refused. There is no name guessing, model
   override, permission grant or automatic response.
 
-Each tool call starts a short-lived, explicitly selected Codex CLI app-server
+Each queue/metadata or stored-read tool call starts a short-lived, explicitly selected Codex CLI app-server
 over stdio. It uses `thread/list` or the same experimental `thread/queue/add`
 method as `codex queue`, without putting text in subprocess arguments. It issues
 no daemon-start, login, thread-resume, turn-start or steer request. Ordinary
@@ -433,3 +433,41 @@ is not controlled by it.
 
 Mesh, dashboard/cache controls, isolation, Claude messaging, managed skills and
 idle notifications remain outside this contribution.
+
+
+## Explicit existing-server resume
+
+**Execution is currently blocked pending native atomic conditional resume support.**
+This pending tool cannot safely resume an unloaded conversation with the checked
+Codex 0.166.0 API. It performs bounded preflight and returns a refusal; it does not
+run queued work. Existing queue and stored-reply tools remain available separately.
+
+To expose the preflight tool, configure all three arguments:
+
+```sh
+ocx message mcp --codex /absolute/path/to/codex --codex-home /absolute/path/to/.codex --allow-reply-read --allow-resume --resume-socket /absolute/path/to/existing.sock --resume-permissions :read-only
+```
+
+The socket must be an existing trusted local Unix App Server reporting the same
+canonical Codex home. No server is installed or started. An exact thread UUID is
+normalized before metadata-only lookup. Observed loaded idle/active targets return
+`already_loaded`; unhealthy targets refuse. For an unloaded target, managed policy,
+unsupported APIs, invalid metadata or a missing/disallowed/unobserved profile refuse.
+The profile is configured by the host, never by tool arguments or queued messages.
+The check reads one bounded catalog page of at most 50 profiles in the target cwd.
+
+Even when these checks pass, the result is `not_resumed` with
+`resume_atomicity_unsupported`. No `thread/resume` is sent. Another client could load
+and unsubscribe from the conversation between the metadata read and resume; the
+checked native server can replace that idle cache entry using supplied permissions.
+A client-side lock or second read cannot eliminate this window. Execution requires
+a native unloaded-only condition enforced atomically before changing a live thread;
+there is no supported conditional-resume API in the checked version. Do not bypass
+this refusal, infer safety from a version string or treat an acknowledgement as a
+way to undo work already started.
+
+`executionVerified` is always false. The tool starts no conversation or turn,
+changes no permission and answers no approval requests. Each call shares a
+20-second budget and the host's four-operation limit; overlapping calls for one
+UUID refuse. Disconnect closes only the bridge connection. Network/SSH endpoints
+and Windows remain outside this tool's scope.

docs-site/src/content/docs/tr/reference/cli/messaging.md

@@ -291,3 +291,26 @@ trafik onun denetiminde değildir.
 
 Mesh, pano/önbellek denetimleri, yalıtım, Claude mesajlaşması, yönetilen beceriler
 ve boşta bildirimleri bu katkının kapsamı dışındadır.
+
+
+## Mevcut sunucuda açık devam ettirme
+
+**Atomik koşullu devam ettirme desteği gelene kadar yürütme engellidir.**
+Kontrol edilen Codex 0.166.0 API'si, ön kontrolden sonra başka bir istemcinin
+yüklediği boşta oturumu farklı izinlerle değiştirebilir. İstemci tarafında ikinci
+bir okuma bu yarışı engellemez. Araç thread/resume göndermez ve kuyruktaki işi çalıştırmaz.
+
+```sh
+ocx message mcp --codex /absolute/path/to/codex --codex-home /absolute/path/to/.codex --allow-resume --resume-socket /absolute/path/to/existing.sock --resume-permissions :read-only
+```
+
+Üç seçenek birlikte yalnızca ön kontrol aracını açar. Aynı gerçek Codex home'u
+bildiren mevcut güvenilir yerel Unix sunucusu gerekir. Yüklü idle/active hedefler
+already_loaded döndürür. Yönetilen politika, desteklenmeyen API veya doğrulanamayan
+profil reddedilir. Profil ana makine ayarıdır; araç girdisi izin veremez. İzin
+kataloğunun en fazla 50 kayıtlık tek sayfası incelenir. Kontroller geçse bile
+yüklenmemiş hedef not_resumed / resume_atomicity_unsupported döndürür.
+
+executionVerified daima false'tur. Yeni sunucu, oturum, mesaj veya turn oluşturulmaz;
+izin değiştirilmez ve onay talepleri yanıtlanmaz. Bağlantı kapanınca yalnızca bu
+istemci bağlantısı kapanır. SSH/ağ uçları ve Windows bu aracın kapsamında değildir.

scripts/test-layout/layout.json

@@ -2,7 +2,7 @@
   "version": 1,
   "root": "tests",
   "explicitShards": ["layout-file-identity.json", "layout-clients.json", "layout-codex-collision.json", "layout-native-profiles.json", "layout-agent-assertion.json", "layout-chat.json", "layout-replay.json", "layout-adapters.json", "layout-jev.json", "layout-workbuddy.json", "layout-combos.json", "layout-credit-renewal.json", "layout-server-inbound.json", "layout-providers.json", "layout-responses.json", "layout-exec-boundary.json", "layout-persistent-dashboard.json", "layout-start-ownership.json", "layout-config.json", "layout-kiro-usage.json", "layout-usage.json", "layout-docs-guides.json", "layout-claude-keychain.json"],
-  "explicit": { "pr-gates-workflow.test.ts": "ci-workflows", "kimi-monthly-quota.test.ts": "providers", "sync-fanout.test.ts": "cli", "sync-command-fanout.test.ts": "cli", "link-pinned-sync-argv.test.ts": "clients", "sync-link-status.test.ts": "cli", "sync-fanout-process.test.ts": "cli", "codex-installation-acl.test.ts": "codex-integration", "codex-installation-id.test.ts": "codex-integration", "codex-installation-wire.test.ts": "codex-integration", "codex-installation-failover.test.ts": "responses", "service-desktop-recovery.test.ts": "service", "catalog-omit-disabled-native.test.ts": "codex-integration", "provider-input-modalities.test.ts": "providers", "combo-description.test.ts": "routing", "combo-description-catalog.test.ts": "codex-integration", "codex-provider-routing.test.ts": "codex-integration", "config-native-reasoning-retention.test.ts": "config", "server-native-reasoning-retention-merge.test.ts": "server", "server-native-reasoning-retention.test.ts": "server", "config-workflow-budget.test.ts": "config", "server-workflow-budget-settings.test.ts": "server", "responses-retained-reasoning-stream-recovery.test.ts": "responses", "openai-native-hosted-search-history.test.ts": "adapters/openai", "responses-native-compact-search-history.test.ts": "responses", "config-hosted-search-projection.test.ts": "config", "gcp-credential-boundary.test.ts": "adapters/google", "gcp-sa-marker.test.ts": "adapters/google", "gcp-sa-adapter.test.ts": "adapters/google", "management-gcp-credential-input.test.ts": "server", "codex-preserve-signed-in.test.ts": "codex-integration", "cli-account-preservation.test.ts": "cli", "cli-provider-list-active.test.ts": "cli", "service-state-isolation.test.ts": "service", "compaction-history-framing.test.ts": "responses", "catalog-native-max-context.test.ts": "codex-integration", "protocol-argon-thought-boundary.test.ts": "responses", "service-log.test.ts": "service", "messages-native-empty-inline.test.ts": "claude-integration", "catalog-auto-review-override.test.ts": "codex-integration", "management-auto-review-settings.test.ts": "server", "management-auto-review-auth.test.ts": "server", "prefer-model-alias-ids.test.ts": "server", "responses-mimo-envelope.test.ts": "responses", "responses-call-id-linkage.test.ts": "responses", "bridge-terminal-refusal.test.ts": "adapters", "loop-terminal-refusal.test.ts": "images", "web-search-terminal-refusal.test.ts": "web-search", "combo-terminal-refusal.test.ts": "routing", "server-terminal-refusal-wiring.test.ts": "server", "incomplete-reason-normalization.test.ts": "responses", "advisor-retention.test.ts": "advisor", "responses-native-key-cooldown.test.ts": "responses", "responses-run-turn-key-readmission.test.ts": "responses", "qoder-spawn-readmission.test.ts": "adapters", "api-key-selection-cooldown.test.ts": "providers", "api-key-auto-pause-distribution.test.ts": "providers", "explicit-key-pause-oauth-boundary.test.ts": "providers", "server-chat-native-key-selection.test.ts": "server", "compact-key-selection.test.ts": "responses", "messages-native-key-selection.test.ts": "claude-integration", "coding-agent-windows-dispatch.test.ts": "adapters", "coding-agent-native-empty-argv.test.ts": "windows",
+  "explicit": { "cli-message-mcp-resume.test.ts": "cli", "messaging-mcp-resume.test.ts": "codex-integration", "pr-gates-workflow.test.ts": "ci-workflows", "kimi-monthly-quota.test.ts": "providers", "sync-fanout.test.ts": "cli", "sync-command-fanout.test.ts": "cli", "link-pinned-sync-argv.test.ts": "clients", "sync-link-status.test.ts": "cli", "sync-fanout-process.test.ts": "cli", "codex-installation-acl.test.ts": "codex-integration", "codex-installation-id.test.ts": "codex-integration", "codex-installation-wire.test.ts": "codex-integration", "codex-installation-failover.test.ts": "responses", "service-desktop-recovery.test.ts": "service", "catalog-omit-disabled-native.test.ts": "codex-integration", "provider-input-modalities.test.ts": "providers", "combo-description.test.ts": "routing", "combo-description-catalog.test.ts": "codex-integration", "codex-provider-routing.test.ts": "codex-integration", "config-native-reasoning-retention.test.ts": "config", "server-native-reasoning-retention-merge.test.ts": "server", "server-native-reasoning-retention.test.ts": "server", "config-workflow-budget.test.ts": "config", "server-workflow-budget-settings.test.ts": "server", "responses-retained-reasoning-stream-recovery.test.ts": "responses", "openai-native-hosted-search-history.test.ts": "adapters/openai", "responses-native-compact-search-history.test.ts": "responses", "config-hosted-search-projection.test.ts": "config", "gcp-credential-boundary.test.ts": "adapters/google", "gcp-sa-marker.test.ts": "adapters/google", "gcp-sa-adapter.test.ts": "adapters/google", "management-gcp-credential-input.test.ts": "server", "codex-preserve-signed-in.test.ts": "codex-integration", "cli-account-preservation.test.ts": "cli", "cli-provider-list-active.test.ts": "cli", "service-state-isolation.test.ts": "service", "compaction-history-framing.test.ts": "responses", "catalog-native-max-context.test.ts": "codex-integration", "protocol-argon-thought-boundary.test.ts": "responses", "service-log.test.ts": "service", "messages-native-empty-inline.test.ts": "claude-integration", "catalog-auto-review-override.test.ts": "codex-integration", "management-auto-review-settings.test.ts": "server", "management-auto-review-auth.test.ts": "server", "prefer-model-alias-ids.test.ts": "server", "responses-mimo-envelope.test.ts": "responses", "responses-call-id-linkage.test.ts": "responses", "bridge-terminal-refusal.test.ts": "adapters", "loop-terminal-refusal.test.ts": "images", "web-search-terminal-refusal.test.ts": "web-search", "combo-terminal-refusal.test.ts": "routing", "server-terminal-refusal-wiring.test.ts": "server", "incomplete-reason-normalization.test.ts": "responses", "advisor-retention.test.ts": "advisor", "responses-native-key-cooldown.test.ts": "responses", "responses-run-turn-key-readmission.test.ts": "responses", "qoder-spawn-readmission.test.ts": "adapters", "api-key-selection-cooldown.test.ts": "providers", "api-key-auto-pause-distribution.test.ts": "providers", "explicit-key-pause-oauth-boundary.test.ts": "providers", "server-chat-native-key-selection.test.ts": "server", "compact-key-selection.test.ts": "responses", "messages-native-key-selection.test.ts": "claude-integration", "coding-agent-windows-dispatch.test.ts": "adapters", "coding-agent-native-empty-argv.test.ts": "windows",
     "stop-restore-history-ownership.test.ts": "service",
     "cli-stop-refusal-transport.test.ts": "cli",
     "service-proxy-env.test.ts": "service", "openai-chat-standalone-bare-block.test.ts": "adapters/openai",

skills/ocx/references/01_surface_agents-routing.md

@@ -182,9 +182,9 @@ Drives no management route.
 
 ### `ocx message mcp`
 
-Usage: `ocx message mcp --codex <absolute-cli-path> --codex-home <absolute-existing-home> [--allow-reply-read]`
+Usage: `ocx message mcp --codex <absolute-cli-path> --codex-home <absolute-existing-home> [--allow-reply-read] [--allow-resume --resume-socket <absolute-existing-unix-socket> --resume-permissions <profile-id>]`
 
-Serve MCP tools for stored Codex metadata, queued text and explicitly enabled stored-turn reply reads and bounded waits.
+Serve MCP tools for stored Codex metadata, queued text, opt-in stored-turn reply reads, bounded waits and guarded existing-server resume preflight.
 
 State-changing: yes. JSON mode: `none`.
 
@@ -195,9 +195,12 @@ Drives no management route.
 | `--codex` | string | Explicit local Codex CLI executable. |
 | `--codex-home` | string | Explicit existing Codex home; no creation or login. |
 | `--allow-reply-read` | boolean | Explicitly expose stored final-turn text through codex_read_reply and codex_wait_reply; disabled by default. |
+| `--allow-resume` | boolean | Expose existing-thread resume preflight; requires --resume-socket and --resume-permissions. Execution is blocked pending native atomic resume support. |
+| `--resume-socket` | string | Existing trusted local Unix App Server socket; requires --allow-resume, --resume-permissions and matching Codex home. |
+| `--resume-permissions` | string | Host-selected native profile for resume preflight; does not bypass the atomicity refusal or preserve saved permissions automatically. |
 
-- macOS/Linux only. No proxy/control socket required. Starts bounded stdio helpers only when a tool is called; existing sessions/send behavior stays unchanged.
-- Stored threads are not verified live sessions. queued is not processing; unknown is never replayed. --allow-reply-read exposes bounded same-turn final text, not exclusive reply ownership or goal completion. No daemon start, thread resume, steer, automatic replies or registration.
+- macOS/Linux only. Default queue/read tools need no proxy/control socket; resume uses the explicitly configured existing Unix socket. Starts bounded stdio helpers only when a tool is called; existing sessions/send behavior stays unchanged.
+- Stored threads are not verified live sessions. queued is not processing; unknown is never replayed. --allow-reply-read exposes bounded same-turn final text, not exclusive reply ownership or goal completion. No daemon start, steer, automatic replies or registration. Resume preflight is separate opt-in through a same-home existing Unix server; managed requirements and unavailable profiles refuse. The checked native API cannot enforce unloaded-only resume atomically, so execution is blocked with resume_atomicity_unsupported; no thread/resume is sent.
 
 ### `ocx advisor`
 

src/cli/capabilities-agents-routing.ts

@@ -27,14 +27,17 @@ export const AGENT_ROUTING_CAPABILITIES: readonly Capability[] = [
       "Exit 0: queued; 1: not sent; 3: unknown; 64: invalid usage. No Claude transport, native lifecycle mutation or skill installation."],
   },
   {
-    command: ["message", "mcp"], usage: "ocx message mcp --codex <absolute-cli-path> --codex-home <absolute-existing-home> [--allow-reply-read]",
-    summary: "Serve MCP tools for stored Codex metadata, queued text and explicitly enabled stored-turn reply reads and bounded waits.",
+    command: ["message", "mcp"], usage: "ocx message mcp --codex <absolute-cli-path> --codex-home <absolute-existing-home> [--allow-reply-read] [--allow-resume --resume-socket <absolute-existing-unix-socket> --resume-permissions <profile-id>]",
+    summary: "Serve MCP tools for stored Codex metadata, queued text, opt-in stored-turn reply reads, bounded waits and guarded existing-server resume preflight.",
     routes: [], mutates: true, json: "none",
     flags: [{ name: "--codex", value: "string", required: true, summary: "Explicit local Codex CLI executable." },
       { name: "--codex-home", value: "string", required: true, summary: "Explicit existing Codex home; no creation or login." },
-      { name: "--allow-reply-read", value: "boolean", summary: "Explicitly expose stored final-turn text through codex_read_reply and codex_wait_reply; disabled by default." }],
-    details: ["macOS/Linux only. No proxy/control socket required. Starts bounded stdio helpers only when a tool is called; existing sessions/send behavior stays unchanged.",
-      "Stored threads are not verified live sessions. queued is not processing; unknown is never replayed. --allow-reply-read exposes bounded same-turn final text, not exclusive reply ownership or goal completion. No daemon start, thread resume, steer, automatic replies or registration."],
+      { name: "--allow-reply-read", value: "boolean", summary: "Explicitly expose stored final-turn text through codex_read_reply and codex_wait_reply; disabled by default." },
+      { name: "--allow-resume", value: "boolean", summary: "Expose existing-thread resume preflight; requires --resume-socket and --resume-permissions. Execution is blocked pending native atomic resume support." },
+      { name: "--resume-socket", value: "string", summary: "Existing trusted local Unix App Server socket; requires --allow-resume, --resume-permissions and matching Codex home." },
+      { name: "--resume-permissions", value: "string", summary: "Host-selected native profile for resume preflight; does not bypass the atomicity refusal or preserve saved permissions automatically." }],
+    details: ["macOS/Linux only. Default queue/read tools need no proxy/control socket; resume uses the explicitly configured existing Unix socket. Starts bounded stdio helpers only when a tool is called; existing sessions/send behavior stays unchanged.",
+      "Stored threads are not verified live sessions. queued is not processing; unknown is never replayed. --allow-reply-read exposes bounded same-turn final text, not exclusive reply ownership or goal completion. No daemon start, steer, automatic replies or registration. Resume preflight is separate opt-in through a same-home existing Unix server; managed requirements and unavailable profiles refuse. The checked native API cannot enforce unloaded-only resume atomically, so execution is blocked with resume_atomicity_unsupported; no thread/resume is sent."],
   },
   {
     command: ["advisor"],

src/cli/message-command.ts

@@ -12,7 +12,7 @@ export async function runMessageCommand(argv: readonly string[], env: NodeJS.Pro
   if (remote) return (await import("./message-remote-command")).runRemoteMessageCommand(remote, env);
   const args = parseMessageArgs(argv);
   if (!args) {
-    console.error("Usage: ocx message sessions [--host <peer>] [--json] | send (--thread <uuid> | --name <exact-name>) --stdin [--host <peer>] [--kind request|response|notification] [--in-reply-to <uuid>] [--json] | mcp --codex <absolute-cli-path> --codex-home <absolute-existing-home> [--allow-reply-read] | enable [--port <port>] | disable | status | hosts <probe|add|list|remove|abandon|allow-inbound|deny-inbound> | serve [--host <peer>]...");
+    console.error("Usage: ocx message sessions [--host <peer>] [--json] | send (--thread <uuid> | --name <exact-name>) --stdin [--host <peer>] [--kind request|response|notification] [--in-reply-to <uuid>] [--json] | mcp --codex <absolute-cli-path> --codex-home <absolute-existing-home> [--allow-reply-read] [--allow-resume --resume-socket <absolute-existing-unix-socket> --resume-permissions <profile-id>] | enable [--port <port>] | disable | status | hosts <probe|add|list|remove|abandon|allow-inbound|deny-inbound> | serve [--host <peer>]...");
     return 64;
   }
   const controller = new AbortController();