feat(messaging): add explicit enrolled Codex SSH peers

devlog/_plan/261004_codex_remote_messaging/000_scope_and_boundary.md

@@ -0,0 +1,63 @@
+# 000 — remote Codex messaging: second contribution
+
+Status: implemented locally; bounded contribution qualification recorded. No publication,
+deployment or maintainer acceptance of the remote boundary is implied.
+
+## Baseline and direction
+
+The contribution branch is rebuilt on upstream `dev`
+`0dd7451976e40f1e80e023e3c604e38d1966a68e`, containing integrated local messaging
+[PR #6544](https://github.com/lidge-jun/opencodex/pull/6544).
+It does not carry the superseded local PR commits.
+The broader deployed experiment remains separate.
+
+[Proposal #6478](https://github.com/lidge-jun/opencodex/issues/6478) and
+[scoped lifecycle feedback](https://github.com/lidge-jun/opencodex/issues/6478#issuecomment-5975718099)
+require a bounded optional owner, aggregate cross-peer limits, idempotent owned
+cleanup and no replay. Foreground ownership is a revisable proposal, not accepted
+remote architecture. Enrollment/authentication/SSH require independent review.
+
+## Included scope
+
+- CLI-only Codex-to-Codex delivery to exact loaded recipients on individually
+  enrolled SSH peers, selected by exact alias or machine UUID.
+- Explicit enable, fingerprint probe/confirmation, enrollment, list, removal,
+  status and foreground `ocx message serve`.
+- Stable per-configuration-home machine identity and protected directional
+  capabilities, with versioned SSH-stdio enrollment and retained transactions
+  for unknown enrollment outcomes.
+- IPv4-loopback gateway: mutual capability-derived proofs on the actual data
+  connection before attaching to the existing native Unix daemon. No capability
+  in URLs, argv, upgrade headers, ordinary receipts or logs.
+- Initialization, loaded discovery, projected metadata and direct experimental
+  `thread/queue/add`; no generic RPC, lifecycle, turns or approval/config writes.
+- An owned -L/-R pair and bounded return lease support replies without a second
+  SSH login. Live owner proof, not persisted ports, establishes route readiness.
+- Initiating enrollment grants outbound delivery and correlated replies only.
+  Broader local inbound delivery requires explicit per-peer consent; return transport
+  and capability possession do not substitute for that consent.
+- Discovery, final recipient revalidation and queue submission share one
+  authenticated connection; exact receipt correlation, queued/not_sent/unknown,
+  and no automatic resend.
+- Shared owner-wide capacities, cancellation, shutdown, focused regressions,
+  isolated real-SSH and stock-native qualification, docs and ownership records.
+
+## Deliberate exclusions
+
+No mesh/coordinator, dashboard/API, caches, isolation policy, Claude, managed
+skills, prompt/delegation policy, idle triggers or session creation/resume.
+No proxy startup hook, daemon start/restart/install, remote installation or
+automatic tunnel recovery. Unrelated local extensions are not carried.
+
+The gateway is a protected OpenCodex wrapper protocol, not a native WebSocket
+endpoint: raw `codex queue --remote` does not perform its mutual proof handshake.
+Native daemon auth/configuration is unchanged. SSH provides network encryption;
+capability proof is endpoint identity/admission, not transport encryption or a
+same-UID isolation boundary.
+
+## Publication boundary
+
+Prepare a local PR description and exact-head evidence. Do not push or open the
+next PR without user direction. Reference #6478 rather than closing the broader
+proposal. Linux qualification does not establish macOS interoperability; required
+current-head hosted CI and maintainer/security acceptance remain separate gates.

devlog/_plan/261004_codex_remote_messaging/010_extraction_and_ownership.md

@@ -0,0 +1,44 @@
+# 010 — extraction and source ownership
+
+## Source identities
+
+Destination: upstream `dev` `0dd7451976e40f1e80e023e3c604e38d1966a68e`.
+Source reference: local `feat/claude-messaging`, including completed direct-RPC
+hardening at `a665128c3`. This is responsibility-based extraction and narrow
+rewriting, not a whole-commit cherry-pick or a copy of the deployed subsystem.
+
+## Extraction decisions
+
+| Responsibility | Contribution |
+| --- | --- |
+| Enrollment | Strict JSON state and SSH stdio control; explicit enable on both nodes, directional capabilities, recoverable transaction and local-first revocation. No mesh or auto-enable. |
+| SSH | Reuse unchanged Remote Link argv/fingerprint/environment policy; messaging owns separate known_hosts and -L/-R children. |
+| Bridge | Codex-only mutual-proof gateway, small RPC whitelist, projected metadata, bounded aggregate admission. No cross-harness/runtime feature imports. |
+| Runtime | New explicit foreground owner with shared cancellation and accounting; no supervisor, proxy startup activation or automatic retries. |
+| Send | Extend integrated same-connection direct queue RPC through a narrow authenticated socket attachment seam. Preserve the Unix-only local factory. |
+| Envelope | Optional machine metadata and exact remote reply host; descriptive sender identity does not grant authority. |
+| Fixtures | Standalone isolated native/SSH fixtures, not the broader experiment's fixtures. |
+
+## Current ownership and paths
+
+- `structure/remote-messaging.md` owns remote modules and CLI lifecycle/contracts.
+- `structure/local-messaging.md` preserves local-only default and queue semantics.
+- `structure/cli-management.md` accounts for explicit remote command dispatch.
+- `structure/decisions/ADR-6480-remote-messaging-owner.md` records provisional
+  foreground ownership. The manifest and generated structure index register it.
+- `src/link/ssh-argv.ts`, `fingerprint.ts` and SSH environment policy remain
+  unchanged and shared; messaging does not enroll Remote Link or reuse provider keys.
+- `src/messaging/remote-process.ts` adds cancellation/join behavior the existing
+  link runner does not expose. It does not silently change Remote Link behavior.
+- `src/messaging/rpc.ts` accepts a caller-authenticated connected socket only
+  through `attach`. Its local `connect` still refuses network URLs.
+- `src/cli/message-command.ts` imports remote runtime only after pure syntax
+  validation. Local commands without a host do not read remote state.
+- English public CLI reference, registry, capabilities, help and generated
+  operating surface describe implemented commands, not proposed HTTP routes.
+- New tests are registered in both layout manifests. The contained test-temp
+  directory now explicitly uses 0700 to honor private socket/store fixtures.
+
+No source dependency/process graph or exhaustive downstream audit is claimed.
+Callbacks, subprocesses, source-oracle guards and native contracts require explicit
+regression coverage rather than import-graph coverage alone.

devlog/_plan/261004_codex_remote_messaging/020_contract_and_test_matrix.md

@@ -0,0 +1,79 @@
+# 020 — contracts and qualification ledger
+
+Status: implemented contracts with focused evidence; final qualification is tracked
+in 030 and the local PR verification packet, not inferred from historical help.
+
+## Native contract
+
+The gateway uses the integrated experimental `thread/queue/add` RPC, with one
+connection for discovery, revalidation and submission. Validated native IDs and
+text echo establish queued; a correlated rejection establishes not_sent.
+Post-write cancellation, malformed/lost receipts and route loss remain unknown.
+Nothing retries a possibly submitted message.
+
+Stock `codex-cli 0.160.1` was exercised in a separate credential-free home with
+a synthetic local provider. Executable SHA-256:
+`f34a4d2301892ae96c90097786bfe5dc269f187b6f69faf42a7b357b8c081e35`.
+The real daemon accepted the gateway request, completed a synthetic turn and sent
+a return response through the authenticated route. This is Linux evidence,
+not macOS or production-node qualification.
+
+Separately, a disposable loopback OpenSSH server with generated keys proved
+fingerprint confirmation, private enrollment, separate -L/-R routes, request and
+response and complete owned cleanup. Native endpoints in that SSH fixture are
+strict offline Unix fixtures. These two receipts are complementary, not a claim
+that the combined real-SSH/real-native matrix ran.
+
+## Fixed aggregate contracts
+
+One foreground owner covers at most four peers, 16 admitted connections, 32 active
+requests, ten helpers (eight persistent tunnel children plus two transient control
+or inspection children) and 2 MiB accounted input/output. Connections admit at
+most four pending requests, frames at most 1 MiB, state at most 128 KiB and helper
+stdout/stderr at most 64 KiB each. There is no waiting queue. Full capacity refuses
+before allocation, and release is idempotent.
+
+Setup uses one 30-second budget across peers and stages. Authentication is bounded
+to five seconds, route refresh to ten seconds, leases to 25 seconds. Connections
+last at most 30 seconds. Owned cleanup has a three-second ceiling with TERM then
+KILL; concurrent shutdown joins the same flight. Escaped process groups are not
+claimed to be terminated; retained pipes are canceled. Logical helper operations
+settle after bounded cleanup; unresolved physical children retain their reservation.
+Withdrawn published routes remain part of the owner's final cleanup join.
+
+## Regression mapping
+
+| File in tests/codex-integration | Evidence covered |
+| --- | --- |
+| messaging-remote-contract.test.ts | Direction/nonce/identity proofs; exact RPC admission; metadata projection; no native attachment before auth; replacement listener gets no client proof/body; upgrade and capacity refusal; revocation. |
+| messaging-remote-store.test.ts | Absent reads stay absent, strict bounded schema, private ownership/mode/symlink/file guards, locking, secret omission. |
+| messaging-remote-enrollment.test.ts | Explicit receiver enable, immutable transaction, fingerprint mismatch, lost-reply reconciliation, generation-bound journal ownership, concurrent completion, removal and journal-failure ordering, full registry refusal. |
+| messaging-remote-send.test.ts | Same connection, machine-aware replies, return-only receiver, strict receipts, unload, source admission revalidation after awaits, lost/malformed receipts, no replay. |
+| messaging-remote-lifecycle.test.ts | Inert imports and pure parser, owned cancellation, shared cleanup/output limits; published and unpublished tunnel cleanup joins both helpers, including failure. |
+| messaging-remote-process.test.ts | Bounded logical settlement for unresolved exit and failed stdin, retained physical reservations, persistent/transient caps and injected Darwin listener inspection. |
+| messaging-remote-interop.test.ts | Opt-in generated-key loopback SSH enrollment, duplex delivery and zero owned reservations after cleanup. |
+| messaging-remote-native.test.ts | Opt-in explicit stock binary, real queue/turn contract in isolated home, synthetic provider and return delivery. |
+
+Existing local messaging and shared SSH policy regressions are part of integrated
+validation. Import-graph selection alone cannot cover source-oracle, subprocess or
+golden-file guards; run those explicitly.
+
+## Remaining gates
+
+Full-suite qualification remains incomplete: the existing runner stopped its
+parallel lane after 900 seconds, exit 124; serial lanes were not reached. The
+local PR packet records the resource exception, observed failures, focused
+coverage and commands instead of claiming a passing full suite. No ratchet,
+timeout or required check was relaxed.
+
+A later bounded `test:changed` attempt selected 979 of 2,222 files and exceeded its
+explicit 180-second runner ceiling, exit 124, without a final count receipt. It is
+also incomplete, not passing; final focused regressions cover subsequent changes.
+
+Required exact-head hosted CI once publication is authorized and macOS
+interoperability remain outstanding. Local checks and independent source review
+are recorded separately from maintainer acceptance and operational qualification.
+No receipt from an unrun or skipped tier is described as passing.
+
+Unreleased security assessment material belongs in ignored scratch or managed
+scan artifacts, never in this public planning ledger.

devlog/_plan/261004_codex_remote_messaging/030_implementation_sequence.md

@@ -0,0 +1,56 @@
+# 030 — implementation and handover
+
+Status: the agreed remote slice is implemented locally on
+`feat/codex-remote-contribution`; bounded qualification and source review are
+recorded in the local PR packet. Publication is user-authorized; deployment and
+maintainer acceptance remain separate.
+
+## Completed implementation sequence
+
+1. Reconstructed the contribution on current upstream dev containing merged
+   #6544, preserving the old prep worktree and deployed experiment.
+2. Pinned narrow gateway/native contracts, mutual connection proofs, strict
+   receipt semantics and numeric aggregate capacities.
+3. Added explicit private state/enrollment and recoverable private-stdio
+   transactions; no implicit remote enable or lifecycle changes.
+4. Reused shared SSH policy with messaging-owned -L/-R children and live return
+   leases. Added cancellation/join behavior without changing Remote Link.
+5. Added an explicit foreground owner and dynamically selected remote CLI path.
+   No listener, helper, timer or state creation occurs from imports/default startup.
+6. Added one-connection remote sends and machine-aware return replies, preserving
+   local-only Unix trust and queued/not_sent/unknown/no-replay behavior.
+7. Added registered isolated regressions, generated surfaces, public CLI docs,
+   source ownership and a foreground decision record.
+8. Qualified disposable loopback SSH and stock Codex 0.160.1 separately. Joined
+   unpublished tunnel cleanup has dedicated regressions and a narrow independent
+   review. The rebase carried the implementation unchanged, verified by range-diff.
+9. Recorded the full-suite 900-second timeout as incomplete evidence with a
+   proportionate resource exception. Hosted CI, macOS qualification and maintainer
+   acceptance remain outstanding; no unrun tier is reported as passing.
+10. Refined transaction ownership, source admission and published cleanup joins;
+    qualified bounded helper settlement and persistent/transient helper slots.
+    Final focused validation passed 283 tests with six skips and no failures;
+    broader changed-test selection remains incomplete at its bounded ceiling.
+11. Rebased onto upstream `dev` `0dd7451976e40f1e80e023e3c604e38d1966a68e`
+    before publication. All five contribution patches carried unchanged, verified
+    by range-diff. Rebased qualification is recorded separately in the PR packet.
+
+## Maintainer adjustment points
+
+Foreground lifetime is provisional. The individual-peer schema is intentionally
+independent of any future mesh. The protected gateway protocol is not a native
+WebSocket listener and does not claim raw queue CLI compatibility. Linux evidence
+must not be generalized to macOS. If the owner requests smaller contributions,
+split along enrollment/transport/delivery while retaining the tested contracts.
+
+## Safe handover
+
+Keep source and exact-head receipts together. Preserve the deployed local branch;
+do not install, restart, enroll production hosts or migrate skills from this PR
+preparation. Do not push or raise a PR without the user's go. Reference the broader
+proposal rather than auto-closing it.
+
+The local PR draft must distinguish implementation, tests actually run, remaining
+platform/CI/maintainer gates and security review. Any unrun suite or skipped opt-in
+fixture stays explicitly unqualified. Never include secrets, personal host paths,
+internal product names or unpublished security notes in public commits.