fix(claude): preserve OCX routing for spawned Claude CLIs

[OnlineChef]

Problem

ocx claude correctly wires the top-level Claude Code process to the local OpenCodex gateway. A Claude/plugin/agent workflow that starts a fresh claude CLI can lose Anthropic provider variables and open as Not logged in · Run /login, even though the parent remains on an claude-ocx-* model.

Fix

• Resolve the native Claude launcher before modifying PATH.
• Generate an OCX-owned claude shim under ~/.opencodex/claude-launcher on every ocx claude launch.
• Prepend that directory only to the launched Claude process environment.
• Route descendant claude invocations back through ocx claude, rebuilding the current gateway URL, auth mode, model slots and discovery flags.
• Pin the real Claude launcher to prevent recursive shim loops.
• Keep gateway tokens process-local; the generated shim contains executable paths only.
• Preserve normal command-not-found behavior and degrade safely when the shim cannot be written.

Platforms

• POSIX executable shim for Linux/macOS.
• .cmd shim with native npm launcher resolution and argument forwarding for Windows.

Tests

Added focused regression coverage for:

• native launcher resolution and PATH precedence;
• nested/pinned launcher reuse;
• no-token-on-disk guarantee;
• missing launcher fallback;
• read-only filesystem degradation;
• Windows .CMD resolution and forwarding.

Repository CI is the execution gate for typecheck and the Bun test suite.

---

^{Need help on this PR? Tag @codesmith-bot with what you need. Autofix is enabled.}

Summary by CodeRabbit

• New Features

  • Added support for recursive Claude launches, including nested invocations across Unix and Windows environments.
  • Preserves the configured Claude executable and forwards launch arguments automatically.
  • Provides a warning and fallback guidance when recursive launch setup cannot be completed.

• Bug Fixes

  • Improved handling of missing Claude executables and platform-specific command resolution.

Greptile Summary

This change adds recursive Claude launcher shims so descendant Claude processes re-enter OpenCodex with gateway routing restored. A shared launcher file under OPENCODEX_HOME is overwritten when another session starts with a different OpenCodex or Claude installation. Execution confirmed that descendants from the first active session then run through the second session’s launcher paths. This change is not safe to merge until the generated shim is isolated per session or no longer embeds mutable installation-specific paths.

Confidence Score: 4/5

T-Rex Logs

What T-Rex did

• Published a finding-comment-proof for a posted P1 finding and attached four artifacts that support the finding.
• Published a second finding-comment-proof for another posted P1 finding; no artifacts were attached.
• Validated the shared-home shim regression through a regression harness and test run, confirming before/after behavior across sessions and that tests pass.

_{Ran code and verified through T-Rex}

Comments Outside Diff (1)

1. General comment

   Shared recursive Claude shim redirects earlier session descendants to a later installation

   • Bug
     • Two ocx claude sessions using the same OPENCODEX_HOME/config directory install to the same claude-launcher/claude file. After the second installation, a descendant launched using the first session's PATH executes the second session's runtime and entry launcher, with the second session's pinned native Claude command.
   • Cause
     • prepareRecursiveClaudeLaunch creates a constant shim directory and filename from only deps.configDir at lines 146-147, then overwrites that file at lines 149-152 with content containing session-specific realCommand, runtimePath, and entryPath. The first session retains that shared directory at the front of its PATH.
   • Fix
     • Use a per-session or installation-specific shim path/name (and prepend that unique directory), or make the shim resolve an appropriate stable launcher without embedding mutable installation-specific paths. Add a regression test covering two distinct launch installations sharing configDir and invoking the first session descendant after the second installation.

   _{Ran code and verified through T-Rex}

Prompt To Fix All With AI

### Issue 1
src/claude/recursive-launch.ts:146-153
**Shared shim redirects active sessions**

The launcher shim location is derived only from the shared `configDir`, then rewritten with session-specific `realCommand`, runtime, and entry paths. If two `ocx claude` sessions use the same `OPENCODEX_HOME` but resolve different installations, the later session overwrites `claude-launcher/claude`. Descendants of the earlier session retain that directory in `PATH` and consequently launch through the later session's installation, or fail if those paths are unavailable. Use a per-session or installation-specific shim location, or avoid embedding mutable session-specific paths in a shared shim.

---

For each issue above, determine whether it is valid and should be fixed. If so, fix it directly.

_{Reviews (1): Last reviewed commit: 4d8036c | Re-trigger Greptile}

Greptile also left 1 inline comment on this PR.

[qodo-code-review]

ⓘ Qodo reviews are paused because your trial has ended. Ask your workspace admin to add credits to resume reviews. Manage billing

[github-actions]

✅ Target branch corrected

This pull request now targets dev.

The [WRONG BRANCH] title prefix has been removed. The pull request has been marked ready for review again.

[coderabbitai]

📝 Walkthrough

Walkthrough

Changes

Recursive Claude launch

Layer / File(s)	Summary
Native command resolution and shim rendering src/claude/recursive-launch.ts	Adds launch contracts, pinned and PATH-based native command resolution, and Unix and Windows shim rendering.
Shim installation and launch preparation src/claude/recursive-launch.ts	Writes shims atomically, prepends the shim directory to PATH, and returns fallback or warning metadata on failure.
CLI integration and launch validation src/cli/claude.ts, tests/claude-recursive-launch.test.ts	Uses prepared launch state in cmdClaude and tests Unix, nested, fallback, failure, and Windows scenarios.

Estimated code review effort: 4 (Complex) | ~45 minutes

Suggested reviewers: ingwannu, lidge-jun, wibias

Sequence Diagram(s)

sequenceDiagram
  participant cmdClaude
  participant prepareRecursiveClaudeLaunch
  participant recursiveClaudeShim
  participant nativeClaude

  cmdClaude->>prepareRecursiveClaudeLaunch: Prepare command and child environment
  prepareRecursiveClaudeLaunch->>nativeClaude: Resolve pinned or PATH-based executable
  nativeClaude-->>prepareRecursiveClaudeLaunch: Return native command
  prepareRecursiveClaudeLaunch-->>cmdClaude: Return shim command and environment
  cmdClaude->>recursiveClaudeShim: Spawn recursive Claude launch
  recursiveClaudeShim->>nativeClaude: Invoke native Claude with forwarded arguments

Loading

🚥 Pre-merge checks | ✅ 4 | ❌ 1

❌ Failed checks (1 warning)

Check name	Status	Explanation	Resolution
Docstring Coverage	⚠️ Warning	Docstring coverage is 27.27% which is insufficient. The required threshold is 80.00%.	Write docstrings for the functions missing them to satisfy the coverage threshold.

✅ Passed checks (4 passed)

Check name	Status	Explanation
Linked Issues check	✅ Passed	Check skipped because no linked issues were found for this pull request.
Out of Scope Changes check	✅ Passed	Check skipped because no linked issues were found for this pull request.
Description Check	✅ Passed	Check skipped - CodeRabbit’s high-level summary is enabled.
Title check	✅ Passed	The title clearly summarizes the main change: preserving OCX routing for spawned Claude CLI processes.

✨ Finishing Touches 💡 2

📝 Generate docstrings 💡

• Create stacked PR
• Commit on current branch

🛠️ Fix failing CI checks 💡

• Create stacked PR
• Commit on current branch

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Commit unit tests in branch fix/claude-recursive-ocx-launch

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands.}

[coderabbitai]

Actionable comments posted: 1

🤖 Prompt for all review comments with AI agents

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

Inline comments:
In `@tests/claude-recursive-launch.test.ts`:
- Around line 1-111: Add a focused regression test for cmdClaude that stubs
commandInvocation/spawn and verifies recursiveLaunch.command and
recursiveLaunch.env are forwarded to the child-process invocation. Place it
alongside the existing recursive launcher tests, and assert the resolved command
and environment are preserved through the commandInvocation wiring.

🪄 Autofix (Beta)

Fix all unresolved CodeRabbit comments on this PR:

• Push a commit to this branch (recommended)
• Create a new PR with the fixes

---

ℹ️ Review info

⚙️ Run configuration

Configuration used: Path: .coderabbit.yaml

Review profile: ASSERTIVE

Plan: Pro Plus

Run ID: 5dd47dbf-581a-4bbf-9cef-30e507156ad5

📥 Commits

Reviewing files that changed from the base of the PR and between ae6efe6 and 4d8036c.

📒 Files selected for processing (3)

• src/claude/recursive-launch.ts
• src/cli/claude.ts
• tests/claude-recursive-launch.test.ts

[OnlineChef]

P1 fixed in 0340ff9.

The recursive launcher is now isolated by a stable SHA-256 installation identity derived from platform + native Claude executable + OCX runtime + entrypoint. Concurrent ocx claude sessions sharing one OPENCODEX_HOME therefore use different shim directories and cannot overwrite or redirect each other.

Added a regression test that creates two installations in the same config directory, verifies distinct launcher paths, and proves the first launcher's contents/PATH remain unchanged after the second launch.

Current gates: React Doctor green; typecheck green on Linux, macOS and Windows; npm global/package smoke green on Linux, macOS and Windows. Full Bun test/GUI lanes are still executing.

[OnlineChef]

Reviewed current head against the reported shared-shim race. The launcher directory is now keyed by a stable hash of platform, native Claude command, runtime path, and entry path, so concurrently active installations sharing OPENCODEX_HOME no longer overwrite each other. Secrets remain process-local and shim writes remain atomic. No blocking issue remains in this lane.

[OnlineChef]

Expanded the fix for Claude Code Agent View/background sessions.

The original PATH shim only covers descendants that execute claude through PATH. Agent View uses a per-user supervisor and launches each background session as a separate Claude Code process, so those workers can lose the terminal-only ANTHROPIC_BASE_URL / ANTHROPIC_AUTH_TOKEN environment and show Not logged in · Run /login.

New head behavior:

• persists the OCX provider/model env into the official user-level Claude settings.json env surface, which Claude applies to every supervisor session;
• forces CLAUDE_CODE_PROVIDER_MANAGED_BY_HOST=0 for OCX launches, because host-managed mode strips settings-sourced provider variables;
• journals prior values under OPENCODEX_HOME and restores keys when OCX no longer supplies them, without replacing unrelated Claude settings;
• writes settings/state atomically with mode 0600 and fails closed on malformed settings;
• adds focused tests for env selection, unrelated-setting preservation, auth-mode switching, and malformed JSON.

Typecheck is already green on macOS and Ubuntu for head ab47729d; the full test/package matrix is running.

[cursor]

Pickup status (cloud agent): Stale review threads resolved (Greptile P1 installation-hash fix + CodeRabbit cmdClaude wiring test both already in tree). CI green on current head; independent of rate-limit/metrics lanes.

Merge readiness: Ready to merge after #51 (CI sharding) or in parallel. Highest user-impact of the open train (Claude nested spawn / Agent View env loss).