Skip to content

feat: support WSL relay receivers targeting native Windows Codex #110

Closed

Description

@abruption

Problem

v1.0.0-alpha.1 supports paired-device receivers on Linux/macOS, while the core CLI separately supports native Windows Codex sessions. On a Windows workstation, WSL2 is therefore the supported place to run the relay receiver, but that receiver cannot submit to the workstation's native Windows Codex session without an operator-built wrapper.

A WSL receiver can read the native Codex state DB through a mounted codexHome, so policy validation and relay list succeed. Relay send then returns native_outcome_unknown because:

  1. Policy permits codexHome but not codexBin;
  2. Linux executable discovery looks for codex, while the installed native binary is codex.exe;
  3. the Windows process needs a Windows CODEX_HOME, not /mnt/c/....

The public relay, admission, pairing, inner TLS, and Codex queue all worked after adding a private test wrapper that exposed codex, converted CODEX_HOME with wslpath -w, and invoked codex.exe. That wrapper is not suitable as an undocumented user prerequisite.

This is distinct from #22: native Windows core list/send support is complete there. The gap is the relay receiver's WSL-to-native-Windows adapter boundary introduced by #69.

Reproduction

Environment:

  • Windows 10 with native Codex CLI 0.154.0 and an existing native Codex session
  • Ubuntu 24.04 on WSL2, Python 3.12
  • session-peer[relay]==1.0.0a1
  • policy target uses agent: codex, a native session target, and /mnt/c/Users/<user>/.codex

Observed:

  • local and remote relay list: succeeds;
  • relay send: receiver reports native_outcome_unknown;
  • direct local dry-run inside WSL gives Codex executable not found: 'codex';
  • a private codex wrapper plus CODEX_HOME conversion makes dry-run and real transcript ACK succeed.

No credentials, private keys, device identifiers, session identifiers, or host addresses are included here.

Proposed direction

Choose and document one explicit contract:

  • support WSL receivers targeting native Windows Codex by adding a reviewed adapter option that carries an explicit executable and converts the home path safely; or
  • reject mounted native Windows homes with a specific error and document a supported architecture that doesn't require an ad-hoc wrapper.

Avoid shell command construction. Preserve the existing policy allowlist, absolute-path validation, fixed argv invocation, and no-secret logging behavior.

Acceptance criteria

  • A WSL2 receiver can list and submit to an allowlisted native Windows Codex session without a user-authored wrapper, or fails early with a specific documented unsupported-boundary error.
  • The receiver policy has an explicit, validated executable/home contract; arbitrary command strings aren't accepted.
  • Windows and POSIX path conversion is covered by unit tests.
  • A WSL2 ↔ Linux forced-public-relay integration test covers list, real queue submission, and transcript ACK.
  • Existing Linux/macOS relay targets and native Windows core behavior remain unchanged.
  • User-facing relay setup docs explain the supported Windows topology.

Activity

  1. added this to the v1.0.0-beta milestone on Sep 20, 2026
  2. abruption commented on Sep 20, 2026

    @abruption
    OwnerAuthor

    Target release: v1.0.0-beta. This platform compatibility gap should be resolved and validated before the stable core architecture freeze.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Metadata

Metadata

Assignees

No one assigned

    Labels

    enhancementNew feature or request

    Projects

    No projects

      Milestone

      Relationships

      None yet

      Development

      No branches or pull requests

      Issue actions