fix(glpi): accept HTTP 206 in list wrappers (#807) (#810)

docs/scratchpads/807-glpi-partial-content.md

@@ -0,0 +1,64 @@
+# Issue #807 — GLPI list wrappers accept HTTP 206
+
+- **Branch:** `fix/807-glpi-206`
+- **Task:** Gitea issue #807
+- **Role:** Author-only worker reporting to `mosaic-100`; no self-review or merge
+- **Started:** 2026-07-16
+
+## Objective
+
+Fix the shipped GLPI ticket, computer, and user list wrappers so ranged responses with HTTP 206 Partial Content render successfully while genuine HTTP failures remain non-zero errors.
+
+## Scope
+
+- Modify only the three affected list wrappers and a focused shell regression test.
+- Do not touch `session-init.sh`, `ticket-create.sh`, or `docs/TASKS.md`.
+- Add task-local delivery evidence here as required by the mission protocol.
+
+## Plan
+
+1. Add a deterministic shell harness that copies each wrapper beside stubbed `session-init.sh`, credentials, and `curl` boundaries.
+2. Prove RED against the current 200-only gates: 206 must fail before the implementation change.
+3. Update all three status gates to accept exactly 200 or 206.
+4. Prove GREEN for 206 rendering and genuine 401/500 failures, then run repository quality gates.
+5. Commit with co-author attribution, run the push queue guard, push, and open a PR for independent review and merge by the team lead.
+
+## Budget
+
+- No explicit token cap supplied.
+- Soft estimate: 8K tokens; narrow single-worker execution with no exploratory scope.
+
+## Progress
+
+- [x] Mission, task, PRD, QA, documentation, and code-review guidance loaded.
+- [x] RED regression evidence captured: `test-list-http-status.sh` exited 1; all three wrappers rejected 206 while retaining 401 failures.
+- [x] Implementation complete.
+- [x] Relevant tests and repository gates green.
+- [ ] Commit pushed and PR opened.
+
+## Tests and evidence
+
+- RED (before source fix): `packages/mosaic/framework/tools/glpi/test-list-http-status.sh` → exit 1; ticket/computer/user 206 assertions failed, all 401 assertions passed.
+- GREEN: `bash -n packages/mosaic/framework/tools/glpi/{ticket-list.sh,computer-list.sh,user-list.sh,test-list-http-status.sh}` → pass.
+- GREEN: `shellcheck packages/mosaic/framework/tools/glpi/test-list-http-status.sh` → pass.
+- GREEN: `packages/mosaic/framework/tools/glpi/test-list-http-status.sh` → 6 assertions pass (206 renders and 401 errors for all three wrappers).
+- GREEN: `pnpm typecheck` → 42/42 tasks pass.
+- GREEN: `pnpm lint` → 23/23 tasks pass.
+- GREEN: `pnpm format:check` → all matched files pass.
+- Setup note: initial gate attempts could not start because the fresh worktree lacked dependencies; `pnpm install --frozen-lockfile --store-dir /home/hermes/.local/share/pnpm/store` restored the locked workspace dependencies without lockfile changes.
+
+## Acceptance criteria mapping
+
+| Criterion | Evidence |
+| --- | --- |
+| HTTP 206 succeeds and renders each ranged list | Focused test's three 206 render assertions pass |
+| Genuine HTTP failures remain non-zero with existing diagnostics | Focused test's three HTTP 401 assertions pass |
+| Only affected list wrappers change | Diff contains the three status predicates plus focused test/evidence; session and create wrappers untouched |
+
+## Documentation decision
+
+No operator/API documentation change is needed: this restores documented list behavior for a healthy GLPI response without changing command syntax, output, configuration, or public contracts. This task scratchpad records delivery evidence.
+
+## Risks / blockers
+
+- Existing dirty `.mosaic/orchestrator/mission.json` and `.mosaic/orchestrator/session.lock` are runtime-owned and will not be edited or committed.

docs/scratchpads/808-agent-send-sender-identity.md

@@ -0,0 +1,37 @@
+# Issue #808 — agent-send sender identity
+
+## Objective
+
+Fix cross-socket `agent-send.sh` preambles so replies route to the real sender rather than a destination-socket holder session.
+
+## Scope and acceptance criteria
+
+- Prefer exported `MOSAIC_AGENT_NAME` as the authoritative sender session name.
+- If it is unset, query the sender's local/default tmux socket for `#S` without destination `-L` arguments.
+- Preserve `?` when sender identity cannot be determined.
+- Do not alter destination socket dispatch.
+- Add red-first regressions for all three identity paths.
+
+## Plan
+
+1. Extend `agent-send.test.sh` with deterministic fake-tmux coverage.
+2. Run the test against the unpatched implementation and record RED evidence.
+3. Apply the minimal sender lookup fix only.
+4. Run the focused suite and repository quality gates.
+5. Commit, queue-guard, push, and open an author-only PR for independent review.
+
+## Constraints and risks
+
+- Worker lane is author-only: no self-review or merge.
+- `docs/TASKS.md` and mission state are orchestrator-owned and will not be modified.
+- Pre-existing runtime changes under `.mosaic/orchestrator/` are excluded from this work.
+- Budget: no explicit token cap; keep changes limited to the shell tool, sibling regression test, and this scratchpad.
+
+## Evidence
+
+- RED: `bash packages/mosaic/framework/tools/tmux/agent-send.test.sh` failed on the unpatched implementation with `PASS=12 FAIL=3`; it selected `destination-holder` instead of both `MOSAIC_AGENT_NAME=authoritative-agent` and local session `local-agent`. The genuinely unavailable sender case already exercised and preserved `?`.
+- GREEN: `bash packages/mosaic/framework/tools/tmux/agent-send.test.sh` passed with `PASS=15 FAIL=0`; coverage includes env authority, local/default tmux fallback across a destination `-L`, explicit rejection of the destination holder, and `?` fallback.
+- Syntax: `bash -n packages/mosaic/framework/tools/tmux/agent-send.sh packages/mosaic/framework/tools/tmux/agent-send.test.sh` passed.
+- Quality gates: `pnpm typecheck` (42/42 tasks), `pnpm lint` (23/23 tasks), and `pnpm format:check` all passed after installing the frozen lockfile dependencies. The first install attempt failed because pnpm's configured store pointed at `/root`; retrying with the existing user-owned store (`--store-dir /home/hermes/.local/share/pnpm/store`) succeeded without changing tracked dependency files.
+- Documentation: no public API or operator workflow changed; the source comment, regression-test contract, and this implementation record cover the internal bug fix.
+- Independent review: intentionally pending for the reviewer assigned by `mosaic-100`; this author-only lane will not self-review or merge.

packages/mosaic/README.md

@@ -47,6 +47,61 @@ export MOSAIC_ADMIN_PASSWORD="securepass123"
 mosaic gateway install
 ```
 
+## Runtime launchers
+
+```bash
+mosaic claude            # Launch Claude Code with Mosaic injection
+mosaic yolo claude       # …with --dangerously-skip-permissions
+mosaic codex | opencode | pi
+```
+
+### `mosaic claudex` (EXPERIMENTAL)
+
+Runs GPT models **inside the Claude Code harness** by pointing Claude Code at a
+local [`claude-code-proxy`](https://github.com/raine/claude-code-proxy) that
+translates the Anthropic Messages API to a ChatGPT-subscription (Codex OAuth)
+backend. This is **not Anthropic Claude** — model behavior, tool use, and output
+quality may differ. Intended for evaluation, not production delivery.
+
+```bash
+mosaic claudex           # launch (prompts through the proxy readiness gate)
+mosaic yolo claudex      # …with --dangerously-skip-permissions
+mosaic claudex --print "hello"   # trailing args are forwarded to Claude Code
+```
+
+**Prerequisite:** the `claude-code-proxy` binary must be installed and
+authenticated (`claude-code-proxy codex auth …`). `mosaic claudex` runs a
+preflight that verifies the binary, the OAuth state (triggering a device re-auth
+if needed), and a trusted local listener before launching; it **fails closed**
+if the proxy cannot be brought up with a verified identity.
+
+**Isolation (never touches your real Claude state).** claudex always launches
+against an isolated `CLAUDE_CONFIG_DIR` (default `~/.config/mosaic/claudex/home`).
+The ambient `CLAUDE_CONFIG_DIR` is deliberately ignored, and a guard proves the
+resolved dir can never be — or live under — the real `~/.claude`. A claudex
+session therefore cannot mutate your normal Claude Code config.
+
+**No token leakage.** claudex never reads the proxy's credential file. Claude
+Code is handed only `ANTHROPIC_AUTH_TOKEN=unused` pointed at the loopback proxy;
+the entire credential-bearing env family (`ANTHROPIC_*`, `AWS_*`, `GOOGLE_CLOUD_*`,
+`GOOGLE_APPLICATION_CREDENTIALS`, `*_TOKEN`, `*_KEY`, `*_SECRET`, …) is stripped
+from the composed environment. The Bedrock/Vertex routing switches
+(`CLAUDE_CODE_USE_BEDROCK`, `CLAUDE_CODE_USE_VERTEX`, and the `_SKIP_*_AUTH`
+pair) are force-removed regardless of value — otherwise their mere presence
+would route Claude Code to the real Anthropic API via AWS/GCP and bypass the
+proxy. The proxy holds the real OAuth credential.
+
+**Model tiers (override via env).**
+
+| Tier                  | Env var                      | Default        |
+| --------------------- | ---------------------------- | -------------- |
+| primary (opus/sonnet) | `ANTHROPIC_MODEL`            | `gpt-5.6-sol`  |
+| small/fast (haiku)    | `ANTHROPIC_SMALL_FAST_MODEL` | `gpt-5.6-luna` |
+
+Operator-provided values win over the defaults. Additional overrides:
+`MOSAIC_CLAUDEX_CONFIG_DIR` (isolated config dir), `ANTHROPIC_BASE_URL` (proxy
+endpoint).
+
 ## Hooks management
 
 After running `mosaic wizard`, Claude hooks are installed in `~/.claude/hooks-config.json`.

packages/mosaic/framework/tools/glpi/computer-list.sh

@@ -37,7 +37,7 @@ response=$(curl -sk -w "\n%{http_code}" \
 http_code=$(echo "$response" | tail -n1)
 body=$(echo "$response" | sed '$d')
 
-if [[ "$http_code" != "200" ]]; then
+if [[ "$http_code" != "200" && "$http_code" != "206" ]]; then
   echo "Error: Failed to list computers (HTTP $http_code)" >&2
   exit 1
 fi

packages/mosaic/framework/tools/glpi/test-list-http-status.sh

@@ -0,0 +1,84 @@
+#!/usr/bin/env bash
+# Regression harness for #807: ranged GLPI list requests may return HTTP 206.
+#
+# Each shipped list wrapper must render a healthy 206 response and must retain
+# its non-zero error behavior for a genuine HTTP failure.
+
+set -euo pipefail
+
+SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+WORK_DIR="${MOSAIC_TEST_WORK_DIR:-$PWD/.mosaic-test-work/glpi-list-http-status}"
+TOOL_DIR="$WORK_DIR/tools/glpi"
+BIN_DIR="$WORK_DIR/bin"
+
+rm -rf "$WORK_DIR"
+mkdir -p "$TOOL_DIR" "$BIN_DIR" "$WORK_DIR/tools/_lib"
+trap 'rm -rf "$WORK_DIR"' EXIT
+
+for wrapper in ticket-list.sh computer-list.sh user-list.sh; do
+  cp "$SCRIPT_DIR/$wrapper" "$TOOL_DIR/$wrapper"
+done
+
+cat > "$WORK_DIR/tools/_lib/credentials.sh" <<'SH'
+load_credentials() {
+  export GLPI_URL="https://glpi.test/apirest.php"
+  export GLPI_APP_TOKEN="test-app-token"
+}
+SH
+
+cat > "$TOOL_DIR/session-init.sh" <<'SH'
+#!/usr/bin/env bash
+printf '%s\n' 'test-session-token'
+SH
+chmod +x "$TOOL_DIR/session-init.sh"
+
+cat > "$BIN_DIR/curl" <<'SH'
+#!/usr/bin/env bash
+set -euo pipefail
+printf '%s\n' '[{"id":42,"priority":3,"status":1,"name":"Regression fixture","date_mod":"2026-07-16 10:00:00","serial":"SER-42","states_id":1,"realname":"Fixture","firstname":"GLPI","is_active":1}]'
+printf '%s\n' "${GLPI_TEST_HTTP_CODE:?GLPI_TEST_HTTP_CODE is required}"
+SH
+chmod +x "$BIN_DIR/curl"
+
+export MOSAIC_HOME="$WORK_DIR"
+export PATH="$BIN_DIR:$PATH"
+
+wrappers=(ticket-list.sh computer-list.sh user-list.sh)
+resources=(tickets computers users)
+headings=(PRIORITY SERIAL USERNAME)
+fail=0
+
+for index in "${!wrappers[@]}"; do
+  wrapper="${wrappers[$index]}"
+  resource="${resources[$index]}"
+  heading="${headings[$index]}"
+  path="$TOOL_DIR/$wrapper"
+
+  if ! output=$(GLPI_TEST_HTTP_CODE=206 bash "$path" 2>&1); then
+    echo "FAIL: $wrapper rejected healthy HTTP 206" >&2
+    fail=1
+  elif [[ "$output" != *"$heading"* || "$output" != *"Regression fixture"* ]]; then
+    echo "FAIL: $wrapper did not render the HTTP 206 list response" >&2
+    fail=1
+  else
+    echo "PASS: $wrapper renders HTTP 206"
+  fi
+
+  rc=0
+  output=$(GLPI_TEST_HTTP_CODE=401 bash "$path" 2>&1) || rc=$?
+  if [[ "$rc" -eq 0 ]]; then
+    echo "FAIL: $wrapper accepted HTTP 401" >&2
+    fail=1
+  elif [[ "$output" != *"Error: Failed to list $resource (HTTP 401)"* ]]; then
+    echo "FAIL: $wrapper changed the HTTP failure diagnostic" >&2
+    fail=1
+  else
+    echo "PASS: $wrapper rejects HTTP 401"
+  fi
+done
+
+if [[ "$fail" -eq 0 ]]; then
+  echo "ALL PASS: test-list-http-status.sh"
+fi
+
+exit "$fail"

packages/mosaic/framework/tools/glpi/ticket-list.sh

@@ -55,7 +55,7 @@ response=$(curl -sk -w "\n%{http_code}" \
 http_code=$(echo "$response" | tail -n1)
 body=$(echo "$response" | sed '$d')
 
-if [[ "$http_code" != "200" ]]; then
+if [[ "$http_code" != "200" && "$http_code" != "206" ]]; then
   echo "Error: Failed to list tickets (HTTP $http_code)" >&2
   exit 1
 fi

packages/mosaic/framework/tools/glpi/user-list.sh

@@ -37,7 +37,7 @@ response=$(curl -sk -w "\n%{http_code}" \
 http_code=$(echo "$response" | tail -n1)
 body=$(echo "$response" | sed '$d')
 
-if [[ "$http_code" != "200" ]]; then
+if [[ "$http_code" != "200" && "$http_code" != "206" ]]; then
   echo "Error: Failed to list users (HTTP $http_code)" >&2
   exit 1
 fi

packages/mosaic/framework/tools/tmux/agent-send.sh

@@ -122,12 +122,11 @@ fi
 
 # Source label: this agent's host:session (auto-detected, overridable).
 if [ -z "$SRC_LABEL" ]; then
-  tmux_cmd=(tmux)
-  if [ -n "$SOCKET_NAME" ]; then
-    tmux_cmd+=(-L "$SOCKET_NAME")
-  fi
   src_host=$(hostname -s 2>/dev/null || echo "?")
-  src_sess=$("${tmux_cmd[@]}" display-message -p '#S' 2>/dev/null || echo "?")
+  src_sess=${MOSAIC_AGENT_NAME:-}
+  if [ -z "$src_sess" ]; then
+    src_sess=$(tmux display-message -p '#S' 2>/dev/null || echo "?")
+  fi
   SRC_LABEL="${src_host}:${src_sess}"
 fi
 

packages/mosaic/framework/tools/tmux/agent-send.test.sh

@@ -14,6 +14,9 @@
 #   5. invalid class => exit 3, nothing sent.
 #   6. --class with no value => exit 3.
 #   7. the documented consumer regex parses producer output for every class.
+#   8. MOSAIC_AGENT_NAME is authoritative for sender identity.
+#   9. sender fallback queries local tmux, never the destination -L socket.
+#  10. an undeterminable sender is stamped as "?".
 set -uo pipefail
 
 HERE=$(cd -- "$(dirname -- "$0")" && pwd)
@@ -21,22 +24,45 @@ TOOL="$HERE/agent-send.sh"
 
 # Capture stub: stands in for send-message.sh. Decodes -b and prints the payload.
 STUB=$(mktemp)
-trap 'rm -f "$STUB"' EXIT
+FAKE_BIN=$(mktemp -d)
+trap 'rm -f "$STUB"; rm -rf "$FAKE_BIN"' EXIT
 cat >"$STUB" <<'STUB_EOF'
 #!/usr/bin/env bash
 set -uo pipefail
 b64=""
-while getopts "t:b:r:v" o; do case "$o" in b) b64=$OPTARG ;; *) : ;; esac; done
+while getopts "L:t:b:r:v" o; do case "$o" in b) b64=$OPTARG ;; *) : ;; esac; done
 printf '%s' "$b64" | base64 -d
 STUB_EOF
 chmod +x "$STUB"
 
+# Fake tmux distinguishes the sender's default socket from a destination socket.
+cat >"$FAKE_BIN/tmux" <<'TMUX_EOF'
+#!/usr/bin/env bash
+set -uo pipefail
+case "${FAKE_TMUX_MODE:-sessions}" in
+  unavailable) exit 1 ;;
+  sessions)
+    if [ "${1:-}" = "-L" ]; then
+      printf '%s\n' 'destination-holder'
+    else
+      printf '%s\n' 'local-agent'
+    fi
+    ;;
+esac
+TMUX_EOF
+chmod +x "$FAKE_BIN/tmux"
+
 PASS=0; FAIL=0
 ok()   { PASS=$((PASS+1)); printf 'ok   %s\n' "$1"; }
 no()   { FAIL=$((FAIL+1)); printf 'FAIL %s\n   %s\n' "$1" "$2"; }
 
 # Run the tool with the stub injected; echoes captured payload on stdout.
 run() { AGENT_SEND_SENDER="$STUB" bash "$TOOL" -S a:src -n dsthost "$@"; }
+run_auto() {
+  env -u MOSAIC_AGENT_NAME \
+    AGENT_SEND_SENDER="$STUB" PATH="$FAKE_BIN:$PATH" \
+    bash "$TOOL" -n dsthost "$@"
+}
 
 # Documented consumer grammar — the daemon will mirror exactly this.
 GRAMMAR='^\[(\S+) -> (\S+) class=(terminal-log|actionable|human|reaction)\] (.*)$'
@@ -92,6 +118,30 @@ classic=$(run -s mos -m "plain body")
 [[ "$classic" =~ $GRAMMAR_NOCLASS ]] && [ "${BASH_REMATCH[3]}" = "plain body" ] \
   && ok "grammar (no-class) parses classic line" || no "grammar (no-class) parses classic line" "line=[$classic]"
 
+# 8. Exported pane identity wins even when dispatch targets another tmux socket.
+src_host=$(hostname -s)
+got=$(MOSAIC_AGENT_NAME=authoritative-agent FAKE_TMUX_MODE=sessions \
+  AGENT_SEND_SENDER="$STUB" PATH="$FAKE_BIN:$PATH" \
+  bash "$TOOL" -L destination-socket -n dsthost -s mos -m "env identity")
+want="[$src_host:authoritative-agent -> dsthost:mos] env identity"
+[ "$got" = "$want" ] && ok "MOSAIC_AGENT_NAME is authoritative across sockets" \
+  || no "MOSAIC_AGENT_NAME is authoritative across sockets" "got=[$got] want=[$want]"
+
+# 9. Without the env identity, self-lookup uses local tmux, not destination -L.
+got=$(FAKE_TMUX_MODE=sessions run_auto -L destination-socket -s mos -m "local fallback")
+want="[$src_host:local-agent -> dsthost:mos] local fallback"
+[ "$got" = "$want" ] && ok "cross-socket fallback uses local sender session" \
+  || no "cross-socket fallback uses local sender session" "got=[$got] want=[$want]"
+[[ "$got" != *":destination-holder ->"* ]] \
+  && ok "cross-socket fallback rejects destination holder identity" \
+  || no "cross-socket fallback rejects destination holder identity" "got=[$got]"
+
+# 10. If neither env nor local tmux identifies the sender, preserve '?'.
+got=$(FAKE_TMUX_MODE=unavailable run_auto -L destination-socket -s mos -m "unknown fallback")
+want="[$src_host:? -> dsthost:mos] unknown fallback"
+[ "$got" = "$want" ] && ok "unknown sender falls back to ?" \
+  || no "unknown sender falls back to ?" "got=[$got] want=[$want]"
+
 echo "---"
 echo "PASS=$PASS FAIL=$FAIL"
 [ "$FAIL" -eq 0 ]

packages/mosaic/src/commands/claudex-proxy.spec.ts

@@ -0,0 +1,862 @@
+import { describe, it, expect, vi } from 'vitest';
+import { mkdtempSync, readFileSync, rmSync } from 'node:fs';
+import { tmpdir } from 'node:os';
+import { join } from 'node:path';
+import {
+  CLAUDEX_PROXY_HOST,
+  CLAUDEX_PROXY_PORT,
+  CLAUDEX_PROXY_URL,
+  CLAUDEX_PROXY_BINARY,
+  CLAUDEX_HEALTH_PATH,
+  CLAUDEX_HEALTH_URL,
+  buildAuthStatusArgs,
+  buildDeviceAuthArgs,
+  buildServeArgs,
+  parseAuthStatus,
+  checkProxyBinary,
+  checkAuthStatus,
+  runDeviceReauth,
+  probeLiveness,
+  buildSystemdUnitContent,
+  systemdUnitPath,
+  installSystemdUnit,
+  startNohupProxy,
+  verifyListenerIdentity,
+  runProxyPreflight,
+  ensureProxyRunning,
+  type AuthStatus,
+  type ProxyRunResult,
+  type SpawnedChild,
+  type ListenerIdentity,
+} from './claudex-proxy.js';
+
+/**
+ * P1 — Proxy preflight + lifecycle helpers for `mosaic yolo claudex`.
+ *
+ * Security-relevant invariants exercised here:
+ *  - Liveness probe hits the proxy's dedicated `GET /healthz` and treats only a
+ *    2xx as "alive" — a *proxy-specific* health contract, not arbitrary HTTP on
+ *    the port (CWE-345: a local port-squatter must not be trusted as the proxy).
+ *    This also honors spec gotcha #1 (never `curl -f` the root, which returns
+ *    non-2xx): `/healthz` returns 2xx when the proxy is up, so a healthy proxy is
+ *    never mistaken for dead and no duplicate proxy is spawned.
+ *  - Auth-status parsing NEVER surfaces OAuth token material — only a coarse
+ *    state + optional expiry — even if a token-shaped string appears in output.
+ *  - The systemd unit's ExecStart never interpolates an unvalidated path
+ *    (CWE-74: a CR/LF in the path could inject arbitrary systemd directives).
+ *  - The nohup fallback captures spawn's *async* error event instead of crashing.
+ */
+
+describe('claudex-proxy constants', () => {
+  it('pins the proxy endpoint to loopback :18765 (spec table)', () => {
+    expect(CLAUDEX_PROXY_HOST).toBe('127.0.0.1');
+    expect(CLAUDEX_PROXY_PORT).toBe(18765);
+    expect(CLAUDEX_PROXY_URL).toBe('http://127.0.0.1:18765');
+    expect(CLAUDEX_PROXY_BINARY).toBe('claude-code-proxy');
+  });
+
+  it('exposes the dedicated /healthz liveness endpoint (not the root path)', () => {
+    expect(CLAUDEX_HEALTH_PATH).toBe('/healthz');
+    expect(CLAUDEX_HEALTH_URL).toBe('http://127.0.0.1:18765/healthz');
+  });
+
+  it('builds the documented codex subcommand argv', () => {
+    expect(buildAuthStatusArgs()).toEqual(['codex', 'auth', 'status']);
+    expect(buildDeviceAuthArgs()).toEqual(['codex', 'auth', 'device']);
+    expect(buildServeArgs()).toEqual(['serve', '--no-monitor']);
+  });
+});
+
+describe('parseAuthStatus', () => {
+  it('reports valid on exit 0 with an authenticated marker', () => {
+    const s = parseAuthStatus({
+      status: 0,
+      stdout: 'Authenticated as user; token valid',
+      stderr: '',
+    });
+    expect(s.state).toBe('valid');
+  });
+
+  it('reports expired when output mentions expiry', () => {
+    const s = parseAuthStatus({ status: 0, stdout: 'Token expired 2 days ago', stderr: '' });
+    expect(s.state).toBe('expired');
+  });
+
+  it('reports unauthenticated when output says not logged in', () => {
+    const s = parseAuthStatus({
+      status: 1,
+      stdout: '',
+      stderr: 'not authenticated: run codex auth device',
+    });
+    expect(s.state).toBe('unauthenticated');
+  });
+
+  it('reports unknown on an unrecognized non-zero exit', () => {
+    const s = parseAuthStatus({ status: 2, stdout: 'weird', stderr: '' });
+    expect(s.state).toBe('unknown');
+  });
+
+  it('does NOT trust a signal-terminated check (status null) even with an auth-looking line', () => {
+    // status: null means the process was killed by a signal — an INCOMPLETE
+    // check. An auth-looking line that happened to be flushed must not be read
+    // as valid, or preflight passes on a check that never finished.
+    const s = parseAuthStatus({ status: null, stdout: 'Authenticated', stderr: '' });
+    expect(s.state).toBe('unknown');
+  });
+
+  it('extracts a best-effort expiry in days when present', () => {
+    const s = parseAuthStatus({
+      status: 0,
+      stdout: 'Authenticated; expires in 9 days',
+      stderr: '',
+    });
+    expect(s.state).toBe('valid');
+    expect(s.expiresInDays).toBe(9);
+  });
+
+  it('treats a clean exit 0 with no explicit markers as valid', () => {
+    const s = parseAuthStatus({ status: 0, stdout: 'Session active for account foo', stderr: '' });
+    expect(s.state).toBe('valid');
+    expect(s.expiresInDays).toBeUndefined();
+  });
+
+  it('NEVER retains token-shaped material from output', () => {
+    const leaky = 'Authenticated. access_token=sk-abc123SECRETdeadbeef refresh_token=rt-9999';
+    const s: AuthStatus = parseAuthStatus({ status: 0, stdout: leaky, stderr: '' });
+    const serialized = JSON.stringify(s);
+    expect(serialized).not.toContain('sk-abc123SECRETdeadbeef');
+    expect(serialized).not.toContain('rt-9999');
+    expect(serialized).not.toContain('access_token');
+    expect(serialized).not.toContain('refresh_token');
+  });
+});
+
+describe('checkAuthStatus', () => {
+  it('runs the status subcommand and parses the result', () => {
+    const run = vi.fn(
+      (_cmd: string, _args: string[]): ProxyRunResult => ({
+        status: 0,
+        stdout: 'Authenticated; expires in 7 days',
+        stderr: '',
+      }),
+    );
+    const s = checkAuthStatus(run);
+    expect(run).toHaveBeenCalledWith(CLAUDEX_PROXY_BINARY, ['codex', 'auth', 'status']);
+    expect(s.state).toBe('valid');
+    expect(s.expiresInDays).toBe(7);
+  });
+
+  it('surfaces unknown when the default runner cannot find the binary', () => {
+    // Exercises the default spawnSync path against an absent binary: no throw,
+    // status is non-zero/null → unknown. Deterministic on a box without the proxy.
+    const s = checkAuthStatus();
+    expect(['unknown', 'unauthenticated', 'valid', 'expired']).toContain(s.state);
+  });
+});
+
+describe('runDeviceReauth', () => {
+  it('spawns the device flow with inherited stdio (never captures the code/token)', () => {
+    const calls: Array<{ cmd: string; args: string[]; opts: { stdio: string } }> = [];
+    const status = runDeviceReauth((cmd, args, opts) => {
+      calls.push({ cmd, args, opts });
+      return { status: 0 };
+    });
+    expect(status).toBe(0);
+    expect(calls).toHaveLength(1);
+    expect(calls[0]!.cmd).toBe(CLAUDEX_PROXY_BINARY);
+    expect(calls[0]!.args).toEqual(['codex', 'auth', 'device']);
+    // stdio 'inherit' is the security-critical bit: the device code streams to
+    // the user's TTY; the launcher never pipes/captures it.
+    expect(calls[0]!.opts.stdio).toBe('inherit');
+  });
+
+  it('returns 1 when the child yields no status (absent binary)', () => {
+    const status = runDeviceReauth(() => ({ status: null }));
+    expect(status).toBe(1);
+  });
+});
+
+describe('checkProxyBinary', () => {
+  it('resolves via the default `which` path (proxy absent → null)', () => {
+    // Covers the default resolver; on CI/dev the proxy is not installed.
+    const r = checkProxyBinary();
+    expect(typeof r.present).toBe('boolean');
+    if (!r.present) expect(r.path).toBeNull();
+  });
+
+  it('reports present with the resolved path', () => {
+    const r = checkProxyBinary(() => '/home/u/.local/bin/claude-code-proxy');
+    expect(r.present).toBe(true);
+    expect(r.path).toBe('/home/u/.local/bin/claude-code-proxy');
+  });
+
+  it('reports absent when the resolver finds nothing', () => {
+    const r = checkProxyBinary(() => null);
+    expect(r.present).toBe(false);
+    expect(r.path).toBeNull();
+  });
+});
+
+describe('probeLiveness (proxy-specific /healthz, not arbitrary HTTP)', () => {
+  it('defaults to probing the /healthz endpoint, never the root path', async () => {
+    const seen: string[] = [];
+    await probeLiveness(undefined, async (u) => {
+      seen.push(u);
+      return { status: 200 };
+    });
+    expect(seen[0]).toBe(CLAUDEX_HEALTH_URL);
+    expect(seen[0]).toContain('/healthz');
+  });
+
+  it('treats a 200 on /healthz as alive', async () => {
+    const live = await probeLiveness(CLAUDEX_HEALTH_URL, async () => ({ status: 200 }));
+    expect(live).toBe(true);
+  });
+
+  it('treats a 204 on /healthz as alive', async () => {
+    const live = await probeLiveness(CLAUDEX_HEALTH_URL, async () => ({ status: 204 }));
+    expect(live).toBe(true);
+  });
+
+  it('treats a 404 as DEAD — does not trust an arbitrary responder on the port (CWE-345)', async () => {
+    // The whole point: a random local process squatting :18765 will not honor the
+    // proxy's /healthz contract, so a non-2xx there must not be mistaken for the proxy.
+    const live = await probeLiveness(CLAUDEX_HEALTH_URL, async () => ({ status: 404 }));
+    expect(live).toBe(false);
+  });
+
+  it('treats a 500 as DEAD (unhealthy / not the proxy health contract)', async () => {
+    const live = await probeLiveness(CLAUDEX_HEALTH_URL, async () => ({ status: 500 }));
+    expect(live).toBe(false);
+  });
+
+  it('treats a missing status as dead', async () => {
+    const live = await probeLiveness(CLAUDEX_HEALTH_URL, async () => ({}));
+    expect(live).toBe(false);
+  });
+
+  it('treats a connection failure (reject) as dead', async () => {
+    const live = await probeLiveness(CLAUDEX_HEALTH_URL, async () => {
+      throw new Error('ECONNREFUSED');
+    });
+    expect(live).toBe(false);
+  });
+
+  it('treats a timeout as dead', async () => {
+    const never = () => new Promise<{ status?: number }>(() => {});
+    const live = await probeLiveness(CLAUDEX_HEALTH_URL, never, 20);
+    expect(live).toBe(false);
+  });
+});
+
+describe('buildSystemdUnitContent', () => {
+  it('emits a user unit that execs the given binary with serve args', () => {
+    const unit = buildSystemdUnitContent('/home/u/.local/bin/claude-code-proxy');
+    expect(unit).toContain('[Unit]');
+    expect(unit).toContain('[Service]');
+    expect(unit).toContain('[Install]');
+    expect(unit).toContain('/home/u/.local/bin/claude-code-proxy serve --no-monitor');
+    expect(unit).toContain('WantedBy=default.target');
+  });
+
+  it('never embeds credential material', () => {
+    const unit = buildSystemdUnitContent('/home/u/.local/bin/claude-code-proxy');
+    expect(unit).not.toMatch(/token/i);
+    expect(unit).not.toMatch(/auth\.json/i);
+  });
+
+  it('rejects a path containing a newline (CWE-74 systemd directive injection)', () => {
+    // A raw newline in ExecStart would let an attacker append arbitrary unit
+    // directives — e.g. `ExecStartPost=curl evil`. Must be rejected outright.
+    expect(() =>
+      buildSystemdUnitContent('/bin/claude-code-proxy\nExecStartPost=/bin/rm -rf /'),
+    ).toThrow();
+  });
+
+  it('rejects a path containing a carriage return', () => {
+    expect(() => buildSystemdUnitContent('/bin/claude-code-proxy\rmalicious')).toThrow();
+  });
+
+  it('rejects a path with other control characters', () => {
+    expect(() => buildSystemdUnitContent('/bin/claude-code-proxy\x00nul')).toThrow();
+  });
+
+  it('rejects a non-absolute path', () => {
+    expect(() => buildSystemdUnitContent('claude-code-proxy')).toThrow();
+    expect(() => buildSystemdUnitContent('')).toThrow();
+  });
+
+  it('systemd-quotes a path that contains spaces', () => {
+    const unit = buildSystemdUnitContent('/home/u/my apps/claude-code-proxy');
+    expect(unit).toContain('ExecStart="/home/u/my apps/claude-code-proxy" serve --no-monitor');
+  });
+
+  it('escapes embedded quotes and backslashes when quoting', () => {
+    const unit = buildSystemdUnitContent('/home/u/we"ird\\dir/claude-code-proxy');
+    // No unescaped closing quote can terminate the token early.
+    expect(unit).toContain('ExecStart="/home/u/we\\"ird\\\\dir/claude-code-proxy" serve');
+  });
+
+  it('leaves a clean absolute path unquoted (no needless churn)', () => {
+    const unit = buildSystemdUnitContent('/home/u/.local/bin/claude-code-proxy');
+    expect(unit).toContain('ExecStart=/home/u/.local/bin/claude-code-proxy serve --no-monitor');
+  });
+});
+
+describe('systemdUnitPath', () => {
+  it('targets the systemd --user unit dir', () => {
+    expect(systemdUnitPath('/home/u')).toBe(
+      '/home/u/.config/systemd/user/claude-code-proxy.service',
+    );
+  });
+});
+
+describe('installSystemdUnit', () => {
+  it('writes the unit and returns true when daemon-reload succeeds', () => {
+    let written: { path: string; content: string } | null = null;
+    const ok = installSystemdUnit('/bin/claude-code-proxy', {
+      home: '/home/u',
+      writeUnit: (path, content) => {
+        written = { path, content };
+      },
+      run: () => ({ status: 0, stdout: '', stderr: '' }),
+    });
+    expect(ok).toBe(true);
+    expect(written).not.toBeNull();
+    expect(written!.path).toBe('/home/u/.config/systemd/user/claude-code-proxy.service');
+    expect(written!.content).toContain('ExecStart=/bin/claude-code-proxy serve --no-monitor');
+  });
+
+  it('returns false when daemon-reload fails (systemd --user unavailable)', () => {
+    const ok = installSystemdUnit('/bin/claude-code-proxy', {
+      home: '/home/u',
+      writeUnit: () => {},
+      run: () => ({ status: 1, stdout: '', stderr: 'Failed to connect to bus' }),
+    });
+    expect(ok).toBe(false);
+  });
+
+  it('returns false when writing the unit throws', () => {
+    const ok = installSystemdUnit('/bin/claude-code-proxy', {
+      home: '/home/u',
+      writeUnit: () => {
+        throw new Error('EACCES');
+      },
+      run: () => ({ status: 0, stdout: '', stderr: '' }),
+    });
+    expect(ok).toBe(false);
+  });
+
+  it('refuses to write a unit for an injection-bearing path (never writes a poisoned unit)', () => {
+    const writeUnit = vi.fn();
+    const ok = installSystemdUnit('/bin/claude-code-proxy\nExecStartPost=/bin/rm -rf /', {
+      home: '/home/u',
+      writeUnit,
+      run: () => ({ status: 0, stdout: '', stderr: '' }),
+    });
+    expect(ok).toBe(false);
+    // The poisoned unit content is never even produced, so nothing is written.
+    expect(writeUnit).not.toHaveBeenCalled();
+  });
+
+  it('writes to a real temp dir via the default writer', () => {
+    const home = mkdtempSync(join(tmpdir(), 'claudex-unit-'));
+    try {
+      const ok = installSystemdUnit('/bin/claude-code-proxy', {
+        home,
+        run: () => ({ status: 0, stdout: '', stderr: '' }),
+      });
+      expect(ok).toBe(true);
+      const written = readFileSync(systemdUnitPath(home), 'utf8');
+      expect(written).toContain('[Service]');
+    } finally {
+      rmSync(home, { recursive: true, force: true });
+    }
+  });
+});
+
+describe('runProxyPreflight', () => {
+  const trustedListener = () => 'ok' as const;
+
+  it('is ok when binary present, auth valid, proxy live, and listener identity-verified', async () => {
+    const report = await runProxyPreflight({
+      checkBinary: () => ({ present: true, path: '/bin/claude-code-proxy' }),
+      checkAuth: () => ({ state: 'valid' }),
+      probe: async () => true,
+      verifyListener: trustedListener,
+    });
+    expect(report.ok).toBe(true);
+    expect(report.listenerVerdict).toBe('ok');
+    expect(report.problems).toEqual([]);
+  });
+
+  it('flags a missing binary', async () => {
+    const report = await runProxyPreflight({
+      checkBinary: () => ({ present: false, path: null }),
+      checkAuth: () => ({ state: 'valid' }),
+      probe: async () => true,
+      verifyListener: trustedListener,
+    });
+    expect(report.ok).toBe(false);
+    expect(report.problems.some((p) => /binary/i.test(p))).toBe(true);
+  });
+
+  it('flags expired auth (re-auth needed)', async () => {
+    const report = await runProxyPreflight({
+      checkBinary: () => ({ present: true, path: '/bin/claude-code-proxy' }),
+      checkAuth: () => ({ state: 'expired' }),
+      probe: async () => true,
+      verifyListener: trustedListener,
+    });
+    expect(report.ok).toBe(false);
+    expect(report.needsReauth).toBe(true);
+    expect(report.problems.some((p) => /auth/i.test(p))).toBe(true);
+  });
+
+  it('flags a dead proxy', async () => {
+    const report = await runProxyPreflight({
+      checkBinary: () => ({ present: true, path: '/bin/claude-code-proxy' }),
+      checkAuth: () => ({ state: 'valid' }),
+      probe: async () => false,
+      verifyListener: trustedListener,
+    });
+    expect(report.ok).toBe(false);
+    expect(report.live).toBe(false);
+  });
+
+  it('flags an unknown auth state without marking it for re-auth', async () => {
+    const report = await runProxyPreflight({
+      checkBinary: () => ({ present: true, path: '/bin/claude-code-proxy' }),
+      checkAuth: () => ({ state: 'unknown' }),
+      probe: async () => true,
+      verifyListener: trustedListener,
+    });
+    expect(report.ok).toBe(false);
+    expect(report.needsReauth).toBe(false);
+    expect(report.problems.some((p) => /could not determine/i.test(p))).toBe(true);
+  });
+
+  it('does NOT pass preflight when the live responder fails identity verification (F2b)', async () => {
+    // A squatter answering /healthz-2xx must not yield ok:true just because the
+    // binary is installed and OAuth is valid — the identity gate holds here too.
+    for (const verdict of ['foreign-user', 'wrong-exe', 'unknown'] as const) {
+      const report = await runProxyPreflight({
+        checkBinary: () => ({ present: true, path: '/bin/claude-code-proxy' }),
+        checkAuth: () => ({ state: 'valid' }),
+        probe: async () => true,
+        verifyListener: () => verdict,
+      });
+      expect(report.ok).toBe(false);
+      expect(report.live).toBe(true);
+      expect(report.listenerVerdict).toBe(verdict);
+      expect(report.problems.some((p) => /identity could not be verified/i.test(p))).toBe(true);
+      // The identity problem is non-sensitive: port + verdict only, no token.
+      expect(JSON.stringify(report)).not.toMatch(/token|sk-|auth\.json/i);
+    }
+  });
+
+  it('does not verify listener identity when the proxy is dead (no listener to trust)', async () => {
+    const verifyListener = vi.fn(() => 'ok' as const);
+    const report = await runProxyPreflight({
+      checkBinary: () => ({ present: true, path: '/bin/claude-code-proxy' }),
+      checkAuth: () => ({ state: 'valid' }),
+      probe: async () => false,
+      verifyListener,
+    });
+    expect(verifyListener).not.toHaveBeenCalled();
+    expect(report.listenerVerdict).toBe('unknown');
+    expect(report.ok).toBe(false);
+  });
+
+  it('does not leak token material for any auth state', async () => {
+    const report = await runProxyPreflight({
+      checkBinary: () => ({ present: true, path: '/bin/claude-code-proxy' }),
+      checkAuth: () => ({ state: 'expired' }),
+      probe: async () => false,
+      verifyListener: trustedListener,
+    });
+    expect(JSON.stringify(report)).not.toMatch(/token|sk-|auth\.json/i);
+  });
+
+  it('runs end-to-end with all real defaults (no proxy installed → not ok)', async () => {
+    // Exercises the default checkBinary/checkAuth/probe closures against a box
+    // with no proxy: absent binary, spawnSync status, real loopback probe that
+    // fast-fails with ECONNREFUSED. Asserts shape only (never token material).
+    const report = await runProxyPreflight();
+    expect(typeof report.ok).toBe('boolean');
+    expect(Array.isArray(report.problems)).toBe(true);
+    expect(['valid', 'expired', 'unauthenticated', 'unknown']).toContain(report.auth.state);
+    expect(JSON.stringify(report)).not.toMatch(/access_token|refresh_token|sk-/i);
+  });
+});
+
+/**
+ * A minimal fake ChildProcess for the nohup-fallback tests: records once()
+ * handlers so a test can drive the async 'spawn'/'error' events, and tracks
+ * whether the 'error' listener was already attached at the moment unref() ran
+ * (the security-critical ordering from finding #1).
+ */
+function fakeChild() {
+  const handlers: Record<string, (arg?: unknown) => void> = {};
+  const state = { unreffed: false, errorHandlerAtUnref: false };
+  const child = {
+    once(event: string, listener: (arg?: unknown) => void) {
+      handlers[event] = listener;
+      return child;
+    },
+    unref() {
+      state.unreffed = true;
+      state.errorHandlerAtUnref = typeof handlers.error === 'function';
+    },
+    emit(event: string, arg?: unknown) {
+      handlers[event]?.(arg);
+    },
+  };
+  return {
+    child: child as unknown as SpawnedChild & { emit(e: string, a?: unknown): void },
+    state,
+  };
+}
+
+describe('startNohupProxy (finding #1 — async spawn error must not crash)', () => {
+  it('resolves status 0 only after a confirmed spawn, and unrefs the child', async () => {
+    const { child, state } = fakeChild();
+    const spawnImpl = vi.fn((_cmd: string, _args: string[]) => {
+      queueMicrotask(() => child.emit('spawn'));
+      return child;
+    });
+    const r = await startNohupProxy({ resolveBin: () => '/bin/claude-code-proxy', spawnImpl });
+    expect(r.status).toBe(0);
+    expect(state.unreffed).toBe(true);
+    // The error listener MUST be registered before unref(), so an ENOENT that
+    // arrives asynchronously can never become an unhandled 'error' crash.
+    expect(state.errorHandlerAtUnref).toBe(true);
+    expect(spawnImpl).toHaveBeenCalledWith('/bin/claude-code-proxy', ['serve', '--no-monitor'], {
+      detached: true,
+      stdio: 'ignore',
+    });
+  });
+
+  it('captures an async spawn error (ENOENT) as a failed start instead of crashing', async () => {
+    const { child, state } = fakeChild();
+    const spawnImpl = () => {
+      queueMicrotask(() => child.emit('error', new Error('spawn claude-code-proxy ENOENT')));
+      return child;
+    };
+    const r = await startNohupProxy({ resolveBin: () => '/bin/claude-code-proxy', spawnImpl });
+    expect(r.status).toBe(1);
+    expect(r.stderr).toContain('ENOENT');
+    expect(state.unreffed).toBe(false); // never unref a child that failed to start
+  });
+
+  it('captures a synchronous spawn throw as a failed start', async () => {
+    const spawnImpl = () => {
+      throw new Error('EACCES');
+    };
+    const r = await startNohupProxy({ resolveBin: () => '/bin/claude-code-proxy', spawnImpl });
+    expect(r.status).toBe(1);
+    expect(r.stderr).toContain('EACCES');
+  });
+
+  it('ignores a late error after a successful spawn (settles once)', async () => {
+    const { child } = fakeChild();
+    const spawnImpl = () => {
+      queueMicrotask(() => {
+        child.emit('spawn');
+        child.emit('error', new Error('late boom'));
+      });
+      return child;
+    };
+    const r = await startNohupProxy({ resolveBin: () => '/bin/claude-code-proxy', spawnImpl });
+    expect(r.status).toBe(0); // first settle wins; the late error cannot flip it
+  });
+});
+
+describe('verifyListenerIdentity (finding #2 — OS-level listener identity, CWE-345)', () => {
+  const me: ListenerIdentity = {
+    pid: 4242,
+    uid: 1000,
+    exePath: '/home/me/.local/bin/claude-code-proxy',
+  };
+  // Identity canonicalize for tests: fake paths don't exist on disk, so we map
+  // each path to itself and exercise symlink resolution explicitly where needed.
+  const idc = (p: string) => p;
+
+  it('accepts a listener owned by the current uid whose exe is the expected proxy path', () => {
+    const verdict = verifyListenerIdentity({
+      identify: () => me,
+      currentUid: () => 1000,
+      expectedExe: () => '/home/me/.local/bin/claude-code-proxy',
+      canonicalize: idc,
+    });
+    expect(verdict).toBe('ok');
+  });
+
+  it('resolves symlinks on BOTH sides before comparing (canonical match → ok)', () => {
+    // The listener exe and our resolved binary reach the same real file via
+    // different symlink paths — a canonical comparison must accept it.
+    const canon: Record<string, string> = {
+      '/var/run/proxy.link': '/opt/proxy/bin/claude-code-proxy',
+      '/home/me/.local/bin/claude-code-proxy': '/opt/proxy/bin/claude-code-proxy',
+    };
+    const verdict = verifyListenerIdentity({
+      identify: () => ({ ...me, exePath: '/var/run/proxy.link' }),
+      currentUid: () => 1000,
+      expectedExe: () => '/home/me/.local/bin/claude-code-proxy',
+      canonicalize: (p) => canon[p] ?? null,
+    });
+    expect(verdict).toBe('ok');
+  });
+
+  it('does NOT trust a same-uid process at the WRONG path with the right basename (F2a)', () => {
+    // The squatter vector on a shared-uid host: right basename, wrong path. The
+    // basename must NEVER be a trust signal when an expected exact path resolved.
+    const verdict = verifyListenerIdentity({
+      identify: () => ({ ...me, exePath: '/tmp/claude-code-proxy' }),
+      currentUid: () => 1000,
+      expectedExe: () => '/home/me/.local/bin/claude-code-proxy',
+      canonicalize: idc,
+    });
+    expect(verdict).toBe('wrong-exe');
+  });
+
+  it('fails closed (unknown) when our own proxy binary path cannot be resolved (F2a)', () => {
+    // No expected path → we cannot assert identity → refuse to trust (no basename
+    // acceptance). Previously this returned `ok` by basename; that was a bypass.
+    const verdict = verifyListenerIdentity({
+      identify: () => me,
+      currentUid: () => 1000,
+      expectedExe: () => null,
+      canonicalize: idc,
+    });
+    expect(verdict).toBe('unknown');
+  });
+
+  it('fails closed (unknown) when a path cannot be canonicalized (F2a)', () => {
+    const verdict = verifyListenerIdentity({
+      identify: () => me,
+      currentUid: () => 1000,
+      expectedExe: () => '/home/me/.local/bin/claude-code-proxy',
+      canonicalize: () => null, // e.g. binary deleted out from under the listener
+    });
+    expect(verdict).toBe('unknown');
+  });
+
+  it('rejects a listener owned by a DIFFERENT uid (foreign-user) — fail closed', () => {
+    const verdict = verifyListenerIdentity({
+      identify: () => ({ ...me, uid: 0 }),
+      currentUid: () => 1000,
+      expectedExe: () => '/home/me/.local/bin/claude-code-proxy',
+      canonicalize: idc,
+    });
+    expect(verdict).toBe('foreign-user');
+  });
+
+  it('rejects a same-user listener whose exe is NOT the proxy (wrong-exe)', () => {
+    const verdict = verifyListenerIdentity({
+      identify: () => ({ ...me, exePath: '/usr/bin/nc' }),
+      currentUid: () => 1000,
+      expectedExe: () => '/home/me/.local/bin/claude-code-proxy',
+      canonicalize: idc,
+    });
+    expect(verdict).toBe('wrong-exe');
+  });
+
+  it('returns unknown (fail closed) when the listener cannot be identified', () => {
+    const verdict = verifyListenerIdentity({
+      identify: () => null,
+      currentUid: () => 1000,
+      expectedExe: () => '/home/me/.local/bin/claude-code-proxy',
+      canonicalize: idc,
+    });
+    expect(verdict).toBe('unknown');
+  });
+
+  it('returns unknown when the current uid is unavailable (non-posix)', () => {
+    const verdict = verifyListenerIdentity({
+      identify: () => me,
+      currentUid: () => -1,
+      expectedExe: () => '/home/me/.local/bin/claude-code-proxy',
+      canonicalize: idc,
+    });
+    expect(verdict).toBe('unknown');
+  });
+
+  it('returns unknown when the listener exe path cannot be read', () => {
+    const verdict = verifyListenerIdentity({
+      identify: () => ({ ...me, exePath: null }),
+      currentUid: () => 1000,
+      expectedExe: () => '/home/me/.local/bin/claude-code-proxy',
+      canonicalize: idc,
+    });
+    expect(verdict).toBe('unknown');
+  });
+
+  it('runs with real defaults without throwing (identity may be unresolved → verdict)', () => {
+    const verdict = verifyListenerIdentity();
+    expect(['ok', 'foreign-user', 'wrong-exe', 'unknown']).toContain(verdict);
+  });
+});
+
+describe('ensureProxyRunning', () => {
+  const ok: ProxyRunResult = { status: 0, stdout: '', stderr: '' };
+  const nohupOk = async (): Promise<ProxyRunResult> => ok;
+  const trusted = () => 'ok' as const;
+
+  it('is a no-op when the proxy is already live AND identity-verified', async () => {
+    const startSystemd = vi.fn(() => ok);
+    const startNohup = vi.fn(nohupOk);
+    const r = await ensureProxyRunning({
+      probe: async () => true,
+      verifyListener: trusted,
+      startSystemd,
+      startNohup,
+      waitMs: async () => {},
+    });
+    expect(r.method).toBe('already');
+    expect(r.live).toBe(true);
+    expect(startSystemd).not.toHaveBeenCalled();
+    expect(startNohup).not.toHaveBeenCalled();
+  });
+
+  it('fails closed as untrusted when a responder holds :18765 but identity is NOT ours', async () => {
+    // A foreign process answers /healthz but the listener is not our proxy
+    // (foreign uid / wrong exe / unidentifiable). We must NOT trust it and must
+    // NOT start a second proxy (the port is already taken) — fail closed.
+    const startSystemd = vi.fn(() => ok);
+    const startNohup = vi.fn(nohupOk);
+    const r = await ensureProxyRunning({
+      probe: async () => true,
+      verifyListener: () => 'foreign-user',
+      startSystemd,
+      startNohup,
+      waitMs: async () => {},
+    });
+    expect(r.method).toBe('untrusted');
+    expect(r.live).toBe(false);
+    expect(startSystemd).not.toHaveBeenCalled();
+    expect(startNohup).not.toHaveBeenCalled();
+  });
+
+  it('starts via systemd when available and then becomes trusted-live', async () => {
+    let calls = 0;
+    const r = await ensureProxyRunning({
+      probe: async () => calls++ > 0, // dead first, live after start
+      verifyListener: trusted,
+      startSystemd: () => ok,
+      startNohup: async () => {
+        throw new Error('should not fall back');
+      },
+      waitMs: async () => {},
+    });
+    expect(r.method).toBe('systemd');
+    expect(r.live).toBe(true);
+  });
+
+  it('waits past a slow systemd bind before giving up (finding #2 — no duplicate proxy)', async () => {
+    // systemd `start` returns 0 (job accepted) but the socket only binds on the
+    // 4th probe — still well within the startup deadline. nohup must NOT run,
+    // or two proxies would contend for :18765.
+    let probes = 0;
+    const startNohup = vi.fn(nohupOk);
+    const r = await ensureProxyRunning({
+      probe: async () => probes++ >= 3,
+      verifyListener: trusted,
+      startSystemd: () => ok,
+      startNohup,
+      waitMs: async () => {},
+      settleMs: 10,
+      startupDeadlineMs: 200,
+    });
+    expect(r.method).toBe('systemd');
+    expect(r.live).toBe(true);
+    expect(startNohup).not.toHaveBeenCalled();
+  });
+
+  it('does NOT fall back to nohup after systemd accepts but never binds (finding #1 — dup-proxy race)', async () => {
+    // systemctl start exit 0 means the job was ACCEPTED, not bound. If it binds
+    // just after our deadline (or systemd restarts it), a nohup fallback would
+    // create a SECOND proxy contending for :18765. Once systemd has accepted the
+    // job we never spawn nohup — we report a managed-service startup failure.
+    const startNohup = vi.fn(nohupOk);
+    const r = await ensureProxyRunning({
+      probe: async () => false, // never becomes live within the deadline
+      verifyListener: trusted,
+      startSystemd: () => ok,
+      startNohup,
+      waitMs: async () => {},
+      settleMs: 10,
+      startupDeadlineMs: 30,
+    });
+    expect(startNohup).not.toHaveBeenCalled();
+    expect(r.method).toBe('failed');
+    expect(r.live).toBe(false);
+  });
+
+  it('does NOT trust a systemd-started responder whose identity cannot be verified', async () => {
+    // Dead at first (so we reach the systemd start), then the socket binds — but
+    // identity never verifies (e.g. a squatter beat systemd to the port). A live
+    // responder that fails identity must never be reported as a successful start.
+    let calls = 0;
+    const startNohup = vi.fn(nohupOk);
+    const r = await ensureProxyRunning({
+      probe: async () => calls++ > 0,
+      verifyListener: () => 'wrong-exe',
+      startSystemd: () => ok,
+      startNohup,
+      waitMs: async () => {},
+      settleMs: 10,
+      startupDeadlineMs: 30,
+    });
+    expect(startNohup).not.toHaveBeenCalled();
+    expect(r.method).toBe('failed');
+    expect(r.live).toBe(false);
+  });
+
+  it('falls back to nohup only when systemd start FAILS outright (not accepted)', async () => {
+    let calls = 0;
+    const r = await ensureProxyRunning({
+      // A failed systemd start skips its post-start poll, so probes are:
+      // #0 initial (dead), #1 after nohup (live). nohup fallback is reachable
+      // ONLY because systemd never accepted the job (status 1).
+      probe: async () => calls++ > 0,
+      verifyListener: trusted,
+      startSystemd: () => ({ status: 1, stdout: '', stderr: 'no systemd' }),
+      startNohup: nohupOk,
+      waitMs: async () => {},
+      settleMs: 10,
+      startupDeadlineMs: 30,
+    });
+    expect(r.method).toBe('nohup');
+    expect(r.live).toBe(true);
+  });
+
+  it('does NOT trust a nohup-started responder whose identity cannot be verified', async () => {
+    let calls = 0;
+    const r = await ensureProxyRunning({
+      probe: async () => calls++ > 0,
+      verifyListener: () => 'unknown',
+      startSystemd: () => ({ status: 1, stdout: '', stderr: 'no systemd' }),
+      startNohup: nohupOk,
+      waitMs: async () => {},
+      settleMs: 10,
+      startupDeadlineMs: 30,
+    });
+    expect(r.method).toBe('failed');
+    expect(r.live).toBe(false);
+  });
+
+  it('reports failed when nothing brings the proxy up', async () => {
+    const r = await ensureProxyRunning({
+      probe: async () => false,
+      verifyListener: trusted,
+      startSystemd: () => ({ status: 1, stdout: '', stderr: '' }),
+      startNohup: async () => ({ status: 1, stdout: '', stderr: '' }),
+      waitMs: async () => {},
+      settleMs: 10,
+      startupDeadlineMs: 30,
+    });
+    expect(r.method).toBe('failed');
+    expect(r.live).toBe(false);
+  });
+});

packages/mosaic/src/commands/claudex-proxy.ts

@@ -0,0 +1,700 @@
+/**
+ * Claudex proxy preflight + lifecycle (P1 of `mosaic yolo claudex`).
+ *
+ * `raine/claude-code-proxy` runs a local server on 127.0.0.1:18765 that speaks
+ * the Anthropic Messages API and translates to the ChatGPT/Codex backend using
+ * ChatGPT-subscription OAuth. This module owns the *preflight* and *lifecycle*
+ * concerns for the launcher: is the binary present, is OAuth valid, is the proxy
+ * listening, and — if not — bring it up (systemd user unit preferred, nohup
+ * fallback).
+ *
+ * Design: every function is pure or dependency-injected so the launch path is
+ * fully unit-testable without touching a real process, socket, or the OAuth
+ * token. Nothing here reads `~/.config/claude-code-proxy/codex/auth.json`; the
+ * proxy holds the real credential and Claude Code only ever sees
+ * `ANTHROPIC_AUTH_TOKEN=unused`. Parsed auth status is deliberately coarse
+ * (state + optional expiry) so no token material can be retained or surfaced.
+ */
+
+import { execFileSync, spawn, spawnSync } from 'node:child_process';
+import { mkdirSync, readFileSync, readlinkSync, realpathSync, writeFileSync } from 'node:fs';
+import { homedir } from 'node:os';
+import { dirname, join } from 'node:path';
+
+// ─── Endpoint / command constants (spec table) ──────────────────────────────
+
+export const CLAUDEX_PROXY_HOST = '127.0.0.1';
+export const CLAUDEX_PROXY_PORT = 18765;
+export const CLAUDEX_PROXY_URL = `http://${CLAUDEX_PROXY_HOST}:${CLAUDEX_PROXY_PORT}`;
+export const CLAUDEX_PROXY_BINARY = 'claude-code-proxy';
+export const CLAUDEX_SYSTEMD_UNIT = 'claude-code-proxy.service';
+
+/**
+ * The proxy's dedicated liveness endpoint. We probe this — NOT the root path —
+ * for two reasons: (1) the root returns non-2xx (spec gotcha #1), which is why
+ * the original `curl -f` check spawned duplicate proxies; `/healthz` returns 2xx
+ * when the proxy is healthy. (2) It is a *proxy-specific* contract, so a 2xx here
+ * is a much stronger signal that the responder on :18765 is actually our proxy
+ * and not some other local process squatting the port (CWE-345).
+ */
+export const CLAUDEX_HEALTH_PATH = '/healthz';
+export const CLAUDEX_HEALTH_URL = `${CLAUDEX_PROXY_URL}${CLAUDEX_HEALTH_PATH}`;
+
+/** argv for `claude-code-proxy codex auth status`. */
+export function buildAuthStatusArgs(): string[] {
+  return ['codex', 'auth', 'status'];
+}
+
+/** argv for `claude-code-proxy codex auth device` (device-code re-auth flow). */
+export function buildDeviceAuthArgs(): string[] {
+  return ['codex', 'auth', 'device'];
+}
+
+/** argv for `claude-code-proxy serve --no-monitor`. */
+export function buildServeArgs(): string[] {
+  return ['serve', '--no-monitor'];
+}
+
+// ─── Types ──────────────────────────────────────────────────────────────────
+
+export type AuthState = 'valid' | 'expired' | 'unauthenticated' | 'unknown';
+
+/**
+ * Coarse OAuth status. Intentionally carries NO token material — only a state
+ * and an optional best-effort expiry-in-days for user-facing messaging.
+ */
+export interface AuthStatus {
+  state: AuthState;
+  expiresInDays?: number;
+}
+
+export interface ProxyRunResult {
+  status: number | null;
+  stdout: string;
+  stderr: string;
+}
+
+/** Runs a command synchronously and returns its captured result. */
+export type CommandRunner = (cmd: string, args: string[]) => ProxyRunResult;
+
+/** Minimal fetch shape used for the liveness probe (any HTTP response = alive). */
+export type FetchLike = (
+  url: string,
+  init?: { signal?: AbortSignal },
+) => Promise<{ status?: number }>;
+
+// ─── Binary presence ─────────────────────────────────────────────────────────
+
+function defaultWhich(cmd: string): string | null {
+  try {
+    return execFileSync('which', [cmd], { encoding: 'utf8' }).trim() || null;
+  } catch {
+    return null;
+  }
+}
+
+export function checkProxyBinary(resolve: (cmd: string) => string | null = defaultWhich): {
+  present: boolean;
+  path: string | null;
+} {
+  const path = resolve(CLAUDEX_PROXY_BINARY);
+  return { present: path !== null && path !== '', path: path || null };
+}
+
+// ─── Auth status ─────────────────────────────────────────────────────────────
+
+/**
+ * Parse `claude-code-proxy codex auth status` output into a coarse state.
+ *
+ * The proxy's exact wording is not contractually pinned, so this matches
+ * tolerantly on well-known markers and falls back on the exit code. It never
+ * copies the raw output onto the result — only a state and an optional expiry —
+ * so token-shaped strings in the output cannot leak downstream.
+ */
+export function parseAuthStatus(result: ProxyRunResult): AuthStatus {
+  const text = `${result.stdout}\n${result.stderr}`.toLowerCase();
+
+  const expired = /\bexpired\b|token has expired|expires?d? \d+ days? ago/.test(text);
+  const unauth =
+    /not authenticated|not logged in|no (?:auth|credentials|token)|please (?:log ?in|authenticate)|run .*auth device/.test(
+      text,
+    );
+  const authed = /\bauthenticated\b|logged in|token valid|valid until|expires? in/.test(text);
+
+  let state: AuthState;
+  if (expired) {
+    state = 'expired';
+  } else if (unauth) {
+    state = 'unauthenticated';
+  } else if (authed && result.status === 0) {
+    // A `null` status means the check was killed by a signal — an INCOMPLETE
+    // run. We require a clean exit 0 for `valid`; a partially-flushed auth line
+    // from a signal-terminated check must never be trusted (finding #3).
+    state = 'valid';
+  } else if (result.status === 0) {
+    state = 'valid';
+  } else {
+    state = 'unknown';
+  }
+
+  const status: AuthStatus = { state };
+  const days = /expires? in (\d+) days?/.exec(text);
+  if (state === 'valid' && days) {
+    status.expiresInDays = Number(days[1]);
+  }
+  return status;
+}
+
+function defaultRun(cmd: string, args: string[]): ProxyRunResult {
+  const r = spawnSync(cmd, args, { encoding: 'utf8' });
+  return { status: r.status, stdout: r.stdout ?? '', stderr: r.stderr ?? '' };
+}
+
+export function checkAuthStatus(run: CommandRunner = defaultRun): AuthStatus {
+  return parseAuthStatus(run(CLAUDEX_PROXY_BINARY, buildAuthStatusArgs()));
+}
+
+/** Spawn shape for the interactive device re-auth flow. */
+export type InheritSpawn = (
+  cmd: string,
+  args: string[],
+  opts: { stdio: 'inherit' },
+) => { status: number | null };
+
+function defaultInheritSpawn(cmd: string, args: string[], opts: { stdio: 'inherit' }) {
+  return spawnSync(cmd, args, opts);
+}
+
+/**
+ * Run the device-code re-auth flow (`claude-code-proxy codex auth device`).
+ *
+ * Deliberately `stdio: 'inherit'` so the device code the proxy prints goes
+ * straight to the user's terminal — the launcher NEVER captures, stores, or logs
+ * it, and never observes the resulting OAuth token (the proxy persists that to
+ * its own config). Returns the child's exit status; 1 on an absent binary.
+ */
+export function runDeviceReauth(spawnImpl: InheritSpawn = defaultInheritSpawn): number {
+  const r = spawnImpl(CLAUDEX_PROXY_BINARY, buildDeviceAuthArgs(), { stdio: 'inherit' });
+  return r.status ?? 1;
+}
+
+// ─── Liveness (probe the proxy-specific /healthz; require 2xx) ────────────────
+
+/**
+ * Probe the proxy for liveness by hitting its dedicated `GET /healthz` endpoint
+ * and requiring a 2xx response.
+ *
+ * This is a LIVENESS check only — it answers "is a healthy proxy responding?",
+ * not "is that responder actually ours?". Requiring a 2xx on the proxy's own
+ * `/healthz` contract (rather than "any HTTP response = alive") resolves spec
+ * gotcha #1: the root path returns non-2xx, but `/healthz` returns 2xx when
+ * healthy, so a live proxy is never mistaken for dead and no duplicate proxy is
+ * spawned.
+ *
+ * Residual risk (CWE-345): the proxy binds loopback with NO client
+ * authentication, so on a shared host a local process could occupy :18765 and
+ * serve a 2xx here. A 2xx therefore does NOT by itself establish that the
+ * listener is our proxy. Identity is verified SEPARATELY and at every trust
+ * point by {@link verifyListenerIdentity} (OS-level uid + executable check),
+ * which fails closed when identity can't be established. See
+ * {@link ensureProxyRunning}. (Broader multi-user hardening — a persistent
+ * warning when a foreign listener is seen — is tracked for a later phase.)
+ */
+export async function probeLiveness(
+  url: string = CLAUDEX_HEALTH_URL,
+  fetchImpl: FetchLike = fetch as unknown as FetchLike,
+  timeoutMs = 1500,
+): Promise<boolean> {
+  const controller = new AbortController();
+  let timer: ReturnType<typeof setTimeout> | undefined;
+
+  // Bound the probe with our own timeout race rather than trusting the fetch
+  // implementation to honor the abort signal — a hung socket (or a fetch that
+  // ignores the signal) must never wedge the launcher. We still abort() so a
+  // signal-aware fetch tears the request down promptly.
+  const timeout = new Promise<boolean>((resolve) => {
+    timer = setTimeout(() => {
+      controller.abort();
+      resolve(false);
+    }, timeoutMs);
+  });
+
+  const probe = fetchImpl(url, { signal: controller.signal })
+    .then((res) => typeof res.status === 'number' && res.status >= 200 && res.status < 300)
+    .catch(() => false); // connection refused / aborted → dead
+
+  try {
+    return await Promise.race([probe, timeout]);
+  } finally {
+    if (timer) clearTimeout(timer);
+  }
+}
+
+// ─── Listener identity (OS-level, CWE-345 mitigation) ─────────────────────────
+
+/**
+ * The result of verifying who actually owns the :18765 listener.
+ *  - `ok`           — same-user process running the expected proxy binary.
+ *  - `foreign-user` — a process owned by a DIFFERENT uid holds the port.
+ *  - `wrong-exe`    — same-user, but the executable is not the proxy.
+ *  - `unknown`      — identity could not be established (fail closed).
+ */
+export type ListenerVerdict = 'ok' | 'foreign-user' | 'wrong-exe' | 'unknown';
+
+/** OS-level identity of the process bound to the proxy port. */
+export interface ListenerIdentity {
+  pid: number;
+  uid: number;
+  /** Absolute path of the process executable, or null if unreadable. */
+  exePath: string | null;
+}
+
+export interface VerifyListenerDeps {
+  /** Resolve the process bound to the proxy port (null → unidentifiable). */
+  identify?: () => ListenerIdentity | null;
+  /** The current process uid (-1 when unavailable, e.g. non-posix). */
+  currentUid?: () => number;
+  /** The expected proxy executable path (null when it can't be resolved). */
+  expectedExe?: () => string | null;
+  /** Canonicalize a path (resolve symlinks); null when it can't be resolved. */
+  canonicalize?: (p: string) => string | null;
+}
+
+/** Resolve a path through symlinks to its canonical form; null on any failure. */
+function defaultCanonicalize(p: string): string | null {
+  try {
+    return realpathSync(p);
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * Identify the process listening on the proxy port via `ss` + `/proc`. Every
+ * failure path returns null so the caller fails closed. Reads no credential
+ * material — only pid/uid/exe path of the listener.
+ */
+function defaultIdentifyListener(port: number = CLAUDEX_PROXY_PORT): ListenerIdentity | null {
+  try {
+    const out = execFileSync('ss', ['-H', '-ltnp', `sport = :${port}`], { encoding: 'utf8' });
+    const pidMatch = /pid=(\d+)/.exec(out);
+    if (!pidMatch) return null;
+    const pid = Number(pidMatch[1]);
+    if (!Number.isInteger(pid) || pid <= 0) return null;
+
+    const status = readFileSync(`/proc/${pid}/status`, 'utf8');
+    const uidLine = /^Uid:\s*(\d+)/m.exec(status);
+    if (!uidLine) return null;
+    const uid = Number(uidLine[1]);
+
+    let exePath: string | null = null;
+    try {
+      exePath = readlinkSync(`/proc/${pid}/exe`);
+    } catch {
+      exePath = null;
+    }
+    return { pid, uid, exePath };
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * Verify that the process owning :18765 is genuinely OUR proxy before trusting
+ * it. The proxy binds loopback with NO client authentication, so on a shared
+ * host any local process could squat the port and a liveness 2xx alone does not
+ * prove identity (CWE-345). We FAIL CLOSED (`unknown`) whenever identity cannot
+ * be established. This needs no upstream shared-secret/unix-socket support from
+ * `claude-code-proxy`.
+ *
+ * The executable path is the trust boundary that matters: on a shared-uid host
+ * (every agent session runs as the same operator) same-uid is NOT sufficient, so
+ * we require an EXACT canonical-path match against our resolved proxy binary and
+ * canonicalize both sides for symlinks. There is deliberately NO basename
+ * fallback — a same-uid process running `/tmp/claude-code-proxy` (right name,
+ * wrong path) must never be trusted. If our own binary path can't be resolved,
+ * or either path can't be canonicalized, we fail closed rather than downgrade to
+ * a weaker check.
+ */
+export function verifyListenerIdentity(deps: VerifyListenerDeps = {}): ListenerVerdict {
+  const identify = deps.identify ?? (() => defaultIdentifyListener());
+  const currentUid =
+    deps.currentUid ?? (() => (typeof process.getuid === 'function' ? process.getuid() : -1));
+  const expectedExe = deps.expectedExe ?? (() => checkProxyBinary().path);
+  const canonicalize = deps.canonicalize ?? defaultCanonicalize;
+
+  const id = identify();
+  if (!id) return 'unknown'; // can't see the listener → don't trust it
+  const uid = currentUid();
+  if (uid < 0) return 'unknown'; // can't establish our own identity → fail closed
+  if (id.uid !== uid) return 'foreign-user'; // someone else's process holds the port
+  if (!id.exePath) return 'unknown'; // can't confirm the executable → fail closed
+
+  const expected = expectedExe();
+  if (!expected) return 'unknown'; // can't resolve our own binary → fail closed
+  const expectedReal = canonicalize(expected);
+  const actualReal = canonicalize(id.exePath);
+  if (!expectedReal || !actualReal) return 'unknown'; // uncanonicalizable → fail closed
+  return actualReal === expectedReal ? 'ok' : 'wrong-exe';
+}
+
+// ─── systemd user unit ───────────────────────────────────────────────────────
+
+export function systemdUnitPath(home: string = homedir()): string {
+  return join(home, '.config', 'systemd', 'user', CLAUDEX_SYSTEMD_UNIT);
+}
+
+/**
+ * Validate a path destined for a systemd `ExecStart=` line. A raw newline (or
+ * other control character) in the path would let an attacker inject arbitrary
+ * unit directives (e.g. an extra `ExecStartPost=`), a CWE-74 command injection.
+ * We require a plain absolute path and reject any control character outright.
+ */
+function validateExecPath(binaryPath: string): string {
+  if (typeof binaryPath !== 'string' || binaryPath.length === 0) {
+    throw new Error('systemd ExecStart: binary path is empty');
+  }
+  if (!binaryPath.startsWith('/')) {
+    throw new Error(
+      `systemd ExecStart: binary path must be absolute: ${JSON.stringify(binaryPath)}`,
+    );
+  }
+
+  if (/[\x00-\x1f\x7f]/.test(binaryPath)) {
+    throw new Error('systemd ExecStart: binary path contains control characters');
+  }
+  return binaryPath;
+}
+
+/**
+ * Encode a validated path for a systemd `ExecStart=` token. systemd only needs
+ * quoting when the token carries whitespace or quote/backslash characters; a
+ * clean path is emitted verbatim. When quoting, we escape backslashes and double
+ * quotes per systemd's C-style rules so the token cannot be terminated early.
+ */
+function systemdQuoteExec(path: string): string {
+  if (!/[\s"'\\]/.test(path)) {
+    return path;
+  }
+  const escaped = path.replace(/\\/g, '\\\\').replace(/"/g, '\\"');
+  return `"${escaped}"`;
+}
+
+/**
+ * Render the `claude-code-proxy.service` user unit. Contains no credential
+ * material — the proxy reads its own OAuth token from its config dir at runtime.
+ * The binary path is validated (absolute, no control characters) and systemd-
+ * quoted so it cannot inject unit directives.
+ */
+export function buildSystemdUnitContent(binaryPath: string): string {
+  const exec = `${systemdQuoteExec(validateExecPath(binaryPath))} ${buildServeArgs().join(' ')}`;
+  return [
+    '[Unit]',
+    'Description=claude-code-proxy (Anthropic->Codex translation proxy for mosaic claudex)',
+    'After=network-online.target',
+    'Wants=network-online.target',
+    '',
+    '[Service]',
+    'Type=simple',
+    `ExecStart=${exec}`,
+    'Restart=on-failure',
+    'RestartSec=2',
+    '',
+    '[Install]',
+    'WantedBy=default.target',
+    '',
+  ].join('\n');
+}
+
+/**
+ * Write the user unit and reload the systemd --user daemon. Returns false when
+ * systemd --user is unavailable (the caller then falls back to nohup).
+ */
+export function installSystemdUnit(
+  binaryPath: string,
+  deps: {
+    home?: string;
+    writeUnit?: (path: string, content: string) => void;
+    run?: CommandRunner;
+  } = {},
+): boolean {
+  const home = deps.home ?? homedir();
+  const write =
+    deps.writeUnit ??
+    ((path: string, content: string) => {
+      mkdirSync(dirname(path), { recursive: true });
+      writeFileSync(path, content);
+    });
+  const run = deps.run ?? defaultRun;
+
+  try {
+    write(systemdUnitPath(home), buildSystemdUnitContent(binaryPath));
+    const reload = run('systemctl', ['--user', 'daemon-reload']);
+    return reload.status === 0;
+  } catch {
+    return false;
+  }
+}
+
+// ─── Preflight report ────────────────────────────────────────────────────────
+
+export interface PreflightReport {
+  binaryPresent: boolean;
+  binaryPath: string | null;
+  auth: AuthStatus;
+  live: boolean;
+  /** OS-level identity verdict for the :18765 listener (`unknown` when dead). */
+  listenerVerdict: ListenerVerdict;
+  needsReauth: boolean;
+  ok: boolean;
+  problems: string[];
+}
+
+export interface PreflightDeps {
+  checkBinary?: () => { present: boolean; path: string | null };
+  checkAuth?: () => AuthStatus;
+  probe?: () => Promise<boolean>;
+  verifyListener?: () => ListenerVerdict;
+}
+
+/**
+ * Compose the preflight checks into a single structured report. `ok` is true
+ * only when the binary is present, OAuth is valid, the proxy responds, AND the
+ * responding listener's OS-level identity verifies as our proxy.
+ *
+ * The identity gate lives here too, not only in {@link ensureProxyRunning}: any
+ * consumer of this report (notably the phase-2 launch path) would otherwise
+ * treat a `/healthz`-2xx squatter as healthy and route Claude traffic to it
+ * (CWE-345). A liveness 2xx is necessary but not sufficient — a live responder
+ * that fails identity fails the preflight.
+ */
+export async function runProxyPreflight(deps: PreflightDeps = {}): Promise<PreflightReport> {
+  const checkBinary = deps.checkBinary ?? (() => checkProxyBinary());
+  const checkAuth = deps.checkAuth ?? (() => checkAuthStatus());
+  const probe = deps.probe ?? (() => probeLiveness());
+  const verifyListener = deps.verifyListener ?? (() => verifyListenerIdentity());
+
+  const bin = checkBinary();
+  const auth = checkAuth();
+  const live = await probe();
+  // Only meaningful when something is actually responding; a dead port has no
+  // listener identity to establish.
+  const listenerVerdict: ListenerVerdict = live ? verifyListener() : 'unknown';
+
+  const problems: string[] = [];
+  if (!bin.present) {
+    problems.push(
+      `claude-code-proxy binary not found in PATH. Install it before launching claudex.`,
+    );
+  }
+  const needsReauth = auth.state === 'expired' || auth.state === 'unauthenticated';
+  if (needsReauth) {
+    problems.push(
+      `claude-code-proxy OAuth is ${auth.state}. Re-auth with: ${CLAUDEX_PROXY_BINARY} ${buildDeviceAuthArgs().join(' ')}`,
+    );
+  } else if (auth.state === 'unknown') {
+    problems.push('Could not determine claude-code-proxy OAuth status.');
+  }
+  if (!live) {
+    problems.push(`No proxy responding on ${CLAUDEX_PROXY_URL}.`);
+  } else if (listenerVerdict !== 'ok') {
+    // Non-sensitive: names the port and the verdict only — never any listener
+    // command line, token, or other process detail.
+    problems.push(
+      `A process is listening on ${CLAUDEX_PROXY_URL} but its identity could not be verified as ${CLAUDEX_PROXY_BINARY} (${listenerVerdict}). Refusing to trust it.`,
+    );
+  }
+
+  const ok = bin.present && auth.state === 'valid' && live && listenerVerdict === 'ok';
+  return {
+    binaryPresent: bin.present,
+    binaryPath: bin.path,
+    auth,
+    live,
+    listenerVerdict,
+    needsReauth,
+    ok,
+    problems,
+  };
+}
+
+// ─── Lifecycle: ensure the proxy is running ──────────────────────────────────
+
+export type ProxyStartMethod = 'already' | 'systemd' | 'nohup' | 'untrusted' | 'failed';
+
+export interface EnsureProxyResult {
+  live: boolean;
+  method: ProxyStartMethod;
+}
+
+/** Minimal spawned-child shape used by the nohup fallback (testable seam). */
+export interface SpawnedChild {
+  once(event: string, listener: (arg?: unknown) => void): unknown;
+  unref(): void;
+}
+
+/** Spawn shape for the detached fallback process. */
+export type SpawnLike = (
+  cmd: string,
+  args: string[],
+  opts: { detached: boolean; stdio: 'ignore' },
+) => SpawnedChild;
+
+export interface StartNohupDeps {
+  resolveBin?: () => string;
+  spawnImpl?: SpawnLike;
+}
+
+/**
+ * Start the proxy as a detached background process (the fallback when no systemd
+ * user unit is available).
+ *
+ * `spawn()` reports launch failures (ENOENT/EACCES) ASYNCHRONOUSLY via the
+ * child's `error` event, which a `try/catch` cannot see. If left unhandled that
+ * event throws and crashes the launcher. So we: (1) attach the `error` listener
+ * BEFORE `unref()`, capturing a failed launch as a non-zero result instead of a
+ * crash; and (2) resolve success only after the child's `spawn` event fires —
+ * never optimistically before the process is known to have started.
+ */
+export function startNohupProxy(deps: StartNohupDeps = {}): Promise<ProxyRunResult> {
+  const resolveBin = deps.resolveBin ?? (() => checkProxyBinary().path ?? CLAUDEX_PROXY_BINARY);
+  const spawnImpl =
+    deps.spawnImpl ?? ((cmd, args, opts) => spawn(cmd, args, opts) as unknown as SpawnedChild);
+
+  return new Promise<ProxyRunResult>((resolve) => {
+    let settled = false;
+    const finish = (r: ProxyRunResult) => {
+      if (!settled) {
+        settled = true;
+        resolve(r);
+      }
+    };
+
+    let child: SpawnedChild;
+    try {
+      child = spawnImpl(resolveBin(), buildServeArgs(), { detached: true, stdio: 'ignore' });
+    } catch (err) {
+      finish({ status: 1, stdout: '', stderr: err instanceof Error ? err.message : String(err) });
+      return;
+    }
+
+    // Register error handling BEFORE unref so an async spawn failure is caught.
+    child.once('error', (err) => {
+      finish({
+        status: 1,
+        stdout: '',
+        stderr: err instanceof Error ? err.message : String(err),
+      });
+    });
+    child.once('spawn', () => {
+      child.unref();
+      finish({ status: 0, stdout: '', stderr: '' });
+    });
+  });
+}
+
+export interface EnsureProxyDeps {
+  probe?: () => Promise<boolean>;
+  /** OS-level identity check for the process holding the proxy port. */
+  verifyListener?: () => ListenerVerdict;
+  startSystemd?: () => ProxyRunResult;
+  startNohup?: () => Promise<ProxyRunResult>;
+  waitMs?: (ms: number) => Promise<void>;
+  /** Interval between liveness polls while waiting for a start to bind. */
+  settleMs?: number;
+  /** Total budget to wait for a started proxy to bind its socket. */
+  startupDeadlineMs?: number;
+}
+
+function defaultWait(ms: number): Promise<void> {
+  return new Promise((resolve) => setTimeout(resolve, ms));
+}
+
+function defaultStartSystemd(): ProxyRunResult {
+  return defaultRun('systemctl', ['--user', 'start', CLAUDEX_SYSTEMD_UNIT]);
+}
+
+/**
+ * Poll for a TRUSTED-live proxy up to a bounded startup deadline. A start command
+ * returning 0 only means the job was ACCEPTED, not that the socket is bound — so
+ * we keep probing at `intervalMs` until either the deadline elapses or the port
+ * both responds AND passes the OS-level identity check. Liveness alone is not
+ * enough: a responder that fails identity (a squatter) must never be trusted.
+ */
+async function waitForTrusted(
+  probe: () => Promise<boolean>,
+  verifyListener: () => ListenerVerdict,
+  waitMs: (ms: number) => Promise<void>,
+  intervalMs: number,
+  deadlineMs: number,
+): Promise<boolean> {
+  let elapsed = 0;
+  while (elapsed < deadlineMs) {
+    await waitMs(intervalMs);
+    elapsed += intervalMs;
+    if ((await probe()) && verifyListener() === 'ok') {
+      return true;
+    }
+  }
+  return false;
+}
+
+/**
+ * Ensure a proxy is listening. No-op when already live. Otherwise prefer the
+ * systemd user unit, then fall back to a detached background process.
+ *
+ * Every trust point is gated on OS-level listener identity, not just liveness:
+ * the proxy has no client authentication, so on a shared host a local process
+ * could squat :18765 and a 2xx `/healthz` alone would not prove it is our proxy
+ * (CWE-345, finding #2). We only trust a responder whose owning process is the
+ * current uid running the expected proxy binary; otherwise we fail closed.
+ *
+ * If a responder is already present but its identity does NOT verify, we return
+ * `untrusted` WITHOUT starting anything — the port is taken, so spawning would
+ * only create contention, and we must never route Claude traffic through an
+ * unverified listener.
+ *
+ * After a start command is accepted we poll to a bounded startup deadline before
+ * giving up: `systemctl start` exit 0 means the job was accepted, not that the
+ * socket bound within one probe interval. Critically, once systemd ACCEPTS the
+ * job we do NOT fall back to nohup even if it never becomes trusted-live in the
+ * deadline (finding #1): the accepted unit may bind late or be restarted by
+ * systemd, and a second proxy would then contend for :18765 — the very
+ * duplicate-proxy outcome this function exists to prevent. nohup is reachable
+ * only when systemd never accepted the job at all.
+ */
+export async function ensureProxyRunning(deps: EnsureProxyDeps = {}): Promise<EnsureProxyResult> {
+  const probe = deps.probe ?? (() => probeLiveness());
+  const verifyListener = deps.verifyListener ?? (() => verifyListenerIdentity());
+  const startSystemd = deps.startSystemd ?? defaultStartSystemd;
+  const startNohup = deps.startNohup ?? (() => startNohupProxy());
+  const waitMs = deps.waitMs ?? defaultWait;
+  const settleMs = deps.settleMs ?? 500;
+  const startupDeadlineMs = deps.startupDeadlineMs ?? 5000;
+
+  if (await probe()) {
+    // Something answers on :18765 — trust it ONLY if it is provably our proxy.
+    return verifyListener() === 'ok'
+      ? { live: true, method: 'already' }
+      : { live: false, method: 'untrusted' };
+  }
+
+  const systemd = startSystemd();
+  if (systemd.status === 0) {
+    // systemd accepted the job. Wait for a trusted-live bind, but never fall
+    // back to nohup afterward — that would risk a duplicate proxy (finding #1).
+    if (await waitForTrusted(probe, verifyListener, waitMs, settleMs, startupDeadlineMs)) {
+      return { live: true, method: 'systemd' };
+    }
+    return { live: false, method: 'failed' };
+  }
+
+  const nohup = await startNohup();
+  if (nohup.status === 0) {
+    if (await waitForTrusted(probe, verifyListener, waitMs, settleMs, startupDeadlineMs)) {
+      return { live: true, method: 'nohup' };
+    }
+  }
+
+  return { live: false, method: 'failed' };
+}

packages/mosaic/src/commands/claudex.spec.ts

@@ -0,0 +1,732 @@
+import { describe, it, expect, vi } from 'vitest';
+import { mkdtempSync, mkdirSync, symlinkSync, rmSync, lstatSync, writeFileSync } from 'node:fs';
+import { tmpdir, homedir } from 'node:os';
+import { join } from 'node:path';
+import {
+  CLAUDEX_CONFIG_DIR_ENV,
+  CLAUDEX_DEFAULT_PRIMARY_MODEL,
+  CLAUDEX_DEFAULT_SMALL_FAST_MODEL,
+  CLAUDEX_CREDENTIAL_ENV_RE,
+  defaultClaudexConfigDir,
+  assertIsolatedConfigDir,
+  resolveClaudexConfigDir,
+  resolveClaudexModels,
+  buildClaudexEnv,
+  buildClaudexBanner,
+  buildClaudexContractNote,
+  runClaudexProxyGate,
+  launchClaudex,
+  type ClaudexHarnessAdapter,
+} from './claudex.js';
+import { CLAUDEX_PROXY_URL, type PreflightReport } from './claudex-proxy.js';
+
+// ─── helpers ─────────────────────────────────────────────────────────────────
+
+function makeReport(overrides: Partial<PreflightReport> = {}): PreflightReport {
+  return {
+    binaryPresent: true,
+    binaryPath: '/usr/bin/claude-code-proxy',
+    auth: { state: 'valid' },
+    live: true,
+    listenerVerdict: 'ok',
+    needsReauth: false,
+    ok: true,
+    problems: [],
+    ...overrides,
+  };
+}
+
+function okAdapter(overrides: Partial<ClaudexHarnessAdapter> = {}): ClaudexHarnessAdapter {
+  return {
+    harnessPreflight: () => {},
+    composePrompt: () => '# Composed Claude contract',
+    exec: () => {},
+    ...overrides,
+  };
+}
+
+// Identity canonicalizer + no-op FS deps so config-dir logic is tested purely.
+const idCanon = (p: string): string => p;
+const noFsDeps = { canonicalize: idCanon, mkdir: () => {}, isSymlink: () => false };
+
+// ─── isolated config dir (HARD SECURITY REQ 1 — provable isolation) ───────────
+
+describe('defaultClaudexConfigDir', () => {
+  it('is namespaced under the mosaic home, never ~/.claude', () => {
+    const dir = defaultClaudexConfigDir('/home/agent/.config/mosaic');
+    expect(dir).toBe(join('/home/agent/.config/mosaic', 'claudex', 'home'));
+    expect(dir).not.toBe(join(homedir(), '.claude'));
+  });
+});
+
+describe('assertIsolatedConfigDir — the isolation guard is provable', () => {
+  const realClaude = '/home/agent/.claude';
+
+  it('accepts a dir that does not resolve to ~/.claude', () => {
+    const safe = '/home/agent/.config/mosaic/claudex/home';
+    expect(
+      assertIsolatedConfigDir(safe, { realClaudeDir: realClaude, canonicalize: idCanon }),
+    ).toBe(safe);
+  });
+
+  it('REJECTS a candidate that is literally ~/.claude', () => {
+    expect(() =>
+      assertIsolatedConfigDir(realClaude, { realClaudeDir: realClaude, canonicalize: idCanon }),
+    ).toThrow(/refusing/i);
+  });
+
+  it('REJECTS a descendant of ~/.claude (would pollute the real tree)', () => {
+    expect(() =>
+      assertIsolatedConfigDir('/home/agent/.claude/projects/x', {
+        realClaudeDir: realClaude,
+        canonicalize: idCanon,
+      }),
+    ).toThrow(/refusing/i);
+  });
+
+  it('REJECTS a candidate that canonically resolves to ~/.claude (symlink, both sides canonicalized)', () => {
+    const canon = (p: string): string => (p === '/home/agent/link' ? realClaude : p);
+    expect(() =>
+      assertIsolatedConfigDir('/home/agent/link', {
+        realClaudeDir: realClaude,
+        canonicalize: canon,
+      }),
+    ).toThrow(/refusing/i);
+  });
+
+  it('canonicalizes the ~/.claude side too (real dir itself may be a symlink)', () => {
+    // realClaudeDir is a symlink whose canonical target equals the candidate's target.
+    const canon = (p: string): string =>
+      p === '/home/agent/.claude' || p === '/home/agent/link' ? '/canonical/claude' : p;
+    expect(() =>
+      assertIsolatedConfigDir('/home/agent/link', {
+        realClaudeDir: realClaude,
+        canonicalize: canon,
+      }),
+    ).toThrow(/refusing/i);
+  });
+
+  it('REJECTS an empty or whitespace candidate (fail closed)', () => {
+    expect(() =>
+      assertIsolatedConfigDir('', { realClaudeDir: realClaude, canonicalize: idCanon }),
+    ).toThrow();
+    expect(() =>
+      assertIsolatedConfigDir('   ', { realClaudeDir: realClaude, canonicalize: idCanon }),
+    ).toThrow();
+  });
+
+  it('REJECTS a relative candidate (must be absolute)', () => {
+    expect(() =>
+      assertIsolatedConfigDir('relative/dir', { realClaudeDir: realClaude, canonicalize: idCanon }),
+    ).toThrow(/absolute/i);
+  });
+});
+
+describe('resolveClaudexConfigDir', () => {
+  it('uses the namespaced default and never the ambient CLAUDE_CONFIG_DIR', () => {
+    // Ambient CLAUDE_CONFIG_DIR is deliberately ignored (it could be ~/.claude).
+    const env = { CLAUDE_CONFIG_DIR: join(homedir(), '.claude') };
+    const dir = resolveClaudexConfigDir(env, {
+      mosaicHome: '/home/agent/.config/mosaic',
+      realClaudeDir: '/home/agent/.claude',
+      ...noFsDeps,
+    });
+    expect(dir).toBe(join('/home/agent/.config/mosaic', 'claudex', 'home'));
+  });
+
+  it('honors the dedicated override env when it is safe', () => {
+    const env = { [CLAUDEX_CONFIG_DIR_ENV]: '/home/agent/custom-claudex' };
+    const dir = resolveClaudexConfigDir(env, {
+      mosaicHome: '/home/agent/.config/mosaic',
+      realClaudeDir: '/home/agent/.claude',
+      ...noFsDeps,
+    });
+    expect(dir).toBe('/home/agent/custom-claudex');
+  });
+
+  it('REJECTS a dedicated override that points at ~/.claude (before creating anything)', () => {
+    const mkdir = vi.fn();
+    const env = { [CLAUDEX_CONFIG_DIR_ENV]: '/home/agent/.claude' };
+    expect(() =>
+      resolveClaudexConfigDir(env, {
+        mosaicHome: '/home/agent/.config/mosaic',
+        realClaudeDir: '/home/agent/.claude',
+        canonicalize: idCanon,
+        mkdir,
+        isSymlink: () => false,
+      }),
+    ).toThrow(/refusing/i);
+    expect(mkdir).not.toHaveBeenCalled();
+  });
+
+  it('TOCTOU: REJECTS when the created target is itself a symlink (pre-created race)', () => {
+    const env = {};
+    expect(() =>
+      resolveClaudexConfigDir(env, {
+        mosaicHome: '/home/agent/.config/mosaic',
+        realClaudeDir: '/home/agent/.claude',
+        canonicalize: idCanon,
+        mkdir: () => {},
+        isSymlink: () => true, // the just-ensured dir is a symlink → fail closed
+      }),
+    ).toThrow(/refusing|symlink/i);
+  });
+
+  it('real-FS: creates the isolated dir 0700 and returns its canonical path', () => {
+    const root = mkdtempSync(join(tmpdir(), 'claudex-cfg-'));
+    try {
+      const mosaicHome = join(root, '.config', 'mosaic');
+      const dir = resolveClaudexConfigDir({}, { mosaicHome, realClaudeDir: join(root, '.claude') });
+      expect(dir).toBe(join(mosaicHome, 'claudex', 'home'));
+      const st = lstatSync(dir);
+      expect(st.isDirectory()).toBe(true);
+      // 0700 (owner-only) — mask off the type bits.
+      expect(st.mode & 0o777).toBe(0o700);
+    } finally {
+      rmSync(root, { recursive: true, force: true });
+    }
+  });
+
+  it('real-FS: catches an override whose ancestor symlinks into ~/.claude', () => {
+    const root = mkdtempSync(join(tmpdir(), 'claudex-cfg-'));
+    try {
+      const realClaudeDir = join(root, 'dot-claude');
+      mkdirSync(realClaudeDir, { recursive: true });
+      const link = join(root, 'link'); // link -> dot-claude
+      symlinkSync(realClaudeDir, link, 'dir');
+      const override = join(link, 'sub'); // resolves under ~/.claude
+      expect(() =>
+        resolveClaudexConfigDir(
+          { [CLAUDEX_CONFIG_DIR_ENV]: override },
+          { mosaicHome: join(root, '.config', 'mosaic'), realClaudeDir },
+        ),
+      ).toThrow(/refusing/i);
+    } finally {
+      rmSync(root, { recursive: true, force: true });
+    }
+  });
+
+  it('FAIL CLOSED: default canonicalizer rethrows a non-ENOENT error (ELOOP) instead of a literal fallback', () => {
+    // A symlink loop makes realpathSync throw ELOOP. The guard must NOT swallow
+    // it as "does not exist yet, keep walking up" and return a literal path —
+    // it must fail closed. (REQ 1: fails CLOSED on any uncertainty.)
+    const root = mkdtempSync(join(tmpdir(), 'claudex-loop-'));
+    try {
+      const a = join(root, 'a');
+      const b = join(root, 'b');
+      symlinkSync(b, a, 'dir'); // a -> b
+      symlinkSync(a, b, 'dir'); // b -> a  (loop)
+      const looped = join(a, 'home'); // canonicalizing this hits ELOOP
+      // No canonicalize dep → the real defaultCanonicalizeIntended runs.
+      expect(() =>
+        assertIsolatedConfigDir(looped, { realClaudeDir: join(root, '.claude') }),
+      ).toThrow();
+    } finally {
+      rmSync(root, { recursive: true, force: true });
+    }
+  });
+
+  it('FAIL CLOSED: default isSymlink rethrows a non-ENOENT error (ENOTDIR) rather than reporting "not a symlink"', () => {
+    // A candidate whose parent is a regular FILE makes lstat throw ENOTDIR.
+    // The post-create symlink check must fail closed, not treat it as safe.
+    const root = mkdtempSync(join(tmpdir(), 'claudex-notdir-'));
+    try {
+      const file = join(root, 'afile');
+      writeFileSync(file, 'x');
+      const candidate = join(file, 'child'); // parent is a file → ENOTDIR on lstat
+      expect(() =>
+        // Bypass the guard/mkdir side-effects; only the default isSymlink runs live.
+        resolveClaudexConfigDir(
+          { [CLAUDEX_CONFIG_DIR_ENV]: candidate },
+          {
+            realClaudeDir: join(root, '.claude'),
+            canonicalize: idCanon,
+            mkdir: () => {},
+            // isSymlink omitted → real defaultIsSymlink runs on the ENOTDIR path.
+          },
+        ),
+      ).toThrow();
+    } finally {
+      rmSync(root, { recursive: true, force: true });
+    }
+  });
+
+  it('FAIL CLOSED: an injected canonicalize throwing EACCES is not swallowed', () => {
+    const eacces = Object.assign(new Error('permission denied'), { code: 'EACCES' });
+    expect(() =>
+      resolveClaudexConfigDir(
+        { [CLAUDEX_CONFIG_DIR_ENV]: '/home/agent/custom-claudex' },
+        {
+          realClaudeDir: '/home/agent/.claude',
+          canonicalize: () => {
+            throw eacces;
+          },
+          mkdir: () => {},
+          isSymlink: () => false,
+        },
+      ),
+    ).toThrow(/permission denied/);
+  });
+});
+
+// ─── model-tier map (P3) ──────────────────────────────────────────────────────
+
+describe('resolveClaudexModels', () => {
+  it('defaults primary=sol / smallFast=luna', () => {
+    expect(resolveClaudexModels({})).toEqual({
+      primary: CLAUDEX_DEFAULT_PRIMARY_MODEL,
+      smallFast: CLAUDEX_DEFAULT_SMALL_FAST_MODEL,
+    });
+    expect(CLAUDEX_DEFAULT_PRIMARY_MODEL).toBe('gpt-5.6-sol');
+    expect(CLAUDEX_DEFAULT_SMALL_FAST_MODEL).toBe('gpt-5.6-luna');
+  });
+
+  it('env-provided values WIN over defaults', () => {
+    expect(
+      resolveClaudexModels({ ANTHROPIC_MODEL: 'gpt-x', ANTHROPIC_SMALL_FAST_MODEL: 'gpt-y' }),
+    ).toEqual({ primary: 'gpt-x', smallFast: 'gpt-y' });
+  });
+
+  it('ignores blank env values (falls back to defaults)', () => {
+    expect(
+      resolveClaudexModels({ ANTHROPIC_MODEL: '   ', ANTHROPIC_SMALL_FAST_MODEL: '' }),
+    ).toEqual({
+      primary: CLAUDEX_DEFAULT_PRIMARY_MODEL,
+      smallFast: CLAUDEX_DEFAULT_SMALL_FAST_MODEL,
+    });
+  });
+});
+
+// ─── env injection (HARD SECURITY REQ 2 — zero token leakage) ─────────────────
+
+describe('buildClaudexEnv — zero token leakage', () => {
+  const models = { primary: 'gpt-5.6-sol', smallFast: 'gpt-5.6-luna' };
+  const configDir = '/home/agent/.config/mosaic/claudex/home';
+
+  it('sets only ANTHROPIC_AUTH_TOKEN=unused and points at the loopback proxy', () => {
+    const env = buildClaudexEnv({}, { configDir, models });
+    expect(env.ANTHROPIC_AUTH_TOKEN).toBe('unused');
+    expect(env.ANTHROPIC_BASE_URL).toBe(CLAUDEX_PROXY_URL);
+    expect(env.CLAUDE_CONFIG_DIR).toBe(configDir);
+    expect(env.ANTHROPIC_MODEL).toBe('gpt-5.6-sol');
+    expect(env.ANTHROPIC_SMALL_FAST_MODEL).toBe('gpt-5.6-luna');
+  });
+
+  it('OVERWRITES an inherited real auth token with the literal "unused"', () => {
+    const env = buildClaudexEnv(
+      { ANTHROPIC_AUTH_TOKEN: 'sk-ant-realsecret-should-never-flow' },
+      { configDir, models },
+    );
+    expect(env.ANTHROPIC_AUTH_TOKEN).toBe('unused');
+  });
+
+  it('DELETES ANTHROPIC_API_KEY so no real Anthropic key reaches the local proxy', () => {
+    const env = buildClaudexEnv(
+      { ANTHROPIC_API_KEY: 'sk-ant-api03-realkey' },
+      { configDir, models },
+    );
+    expect('ANTHROPIC_API_KEY' in env).toBe(false);
+    expect(env.ANTHROPIC_API_KEY).toBeUndefined();
+  });
+
+  it('sweeps the WHOLE credential-bearing env family (token/api-key/secret/oauth), not just two', () => {
+    const env = buildClaudexEnv(
+      {
+        ANTHROPIC_API_KEY: 'sk-ant-api03-leak',
+        CLAUDE_CODE_OAUTH_TOKEN: 'oauth-leak',
+        SOME_SERVICE_TOKEN: 'tok-leak',
+        VENDOR_API_KEY: 'key-leak',
+        DB_SECRET: 'secret-leak',
+        HARMLESS: 'kept',
+        PATH: '/usr/bin',
+      },
+      { configDir, models },
+    );
+    expect(env.ANTHROPIC_API_KEY).toBeUndefined();
+    expect(env.CLAUDE_CODE_OAUTH_TOKEN).toBeUndefined();
+    expect(env.SOME_SERVICE_TOKEN).toBeUndefined();
+    expect(env.VENDOR_API_KEY).toBeUndefined();
+    expect(env.DB_SECRET).toBeUndefined();
+    // Non-credential vars the harness needs are preserved.
+    expect(env.HARMLESS).toBe('kept');
+    expect(env.PATH).toBe('/usr/bin');
+  });
+
+  it('neutralizes Bedrock/Vertex provider switches so Claude cannot bypass the proxy (REQ 2)', () => {
+    // CLAUDE_CODE_USE_BEDROCK / _USE_VERTEX are ROUTING switches: their mere
+    // presence makes Claude Code route to AWS Bedrock / GCP Vertex against the
+    // ambient cloud credential chain — reaching the real Anthropic API and
+    // bypassing ANTHROPIC_BASE_URL (the loopback proxy) entirely. They MUST be
+    // gone from the composed env regardless of the launching env.
+    const env = buildClaudexEnv(
+      {
+        CLAUDE_CODE_USE_BEDROCK: '1',
+        CLAUDE_CODE_USE_VERTEX: '1',
+        CLAUDE_CODE_SKIP_BEDROCK_AUTH: '1',
+        CLAUDE_CODE_SKIP_VERTEX_AUTH: '1',
+        AWS_ACCESS_KEY_ID: 'AKIAREAL',
+        AWS_SECRET_ACCESS_KEY: 'realsecret',
+        AWS_SESSION_TOKEN: 'realsession',
+        AWS_BEARER_TOKEN_BEDROCK: 'bearer-bedrock-real',
+        AWS_REGION: 'us-east-1',
+        GOOGLE_APPLICATION_CREDENTIALS: '/home/agent/gcp.json',
+        GOOGLE_CLOUD_ACCESS_TOKEN: 'gcp-token-real',
+        PATH: '/usr/bin',
+      },
+      { configDir, models },
+    );
+    // Routing switches gone by construction.
+    expect('CLAUDE_CODE_USE_BEDROCK' in env).toBe(false);
+    expect('CLAUDE_CODE_USE_VERTEX' in env).toBe(false);
+    expect('CLAUDE_CODE_SKIP_BEDROCK_AUTH' in env).toBe(false);
+    expect('CLAUDE_CODE_SKIP_VERTEX_AUTH' in env).toBe(false);
+    // Cloud credentials swept — none of the Claude-capable creds survive.
+    expect(env.AWS_ACCESS_KEY_ID).toBeUndefined();
+    expect(env.AWS_SECRET_ACCESS_KEY).toBeUndefined();
+    expect(env.AWS_SESSION_TOKEN).toBeUndefined();
+    expect(env.AWS_BEARER_TOKEN_BEDROCK).toBeUndefined();
+    expect(env.AWS_REGION).toBeUndefined();
+    expect(env.GOOGLE_APPLICATION_CREDENTIALS).toBeUndefined();
+    expect(env.GOOGLE_CLOUD_ACCESS_TOKEN).toBeUndefined();
+    // The proxy routing is still the only path.
+    expect(env.ANTHROPIC_BASE_URL).toBe(CLAUDEX_PROXY_URL);
+    expect(env.ANTHROPIC_AUTH_TOKEN).toBe('unused');
+    expect(env.PATH).toBe('/usr/bin');
+  });
+
+  it('closes the mid-string _KEY / _SECRET gap (STRIPE_SECRET_KEY, SSH_PRIVATE_KEY)', () => {
+    const env = buildClaudexEnv(
+      {
+        STRIPE_SECRET_KEY: 'sk-live-real',
+        SSH_PRIVATE_KEY: '-----BEGIN OPENSSH PRIVATE KEY-----',
+        HARMLESS: 'kept',
+      },
+      { configDir, models },
+    );
+    expect(env.STRIPE_SECRET_KEY).toBeUndefined();
+    expect(env.SSH_PRIVATE_KEY).toBeUndefined();
+    expect(env.HARMLESS).toBe('kept');
+  });
+
+  it('no credential-NAMED key in the composed env carries a real-looking value', () => {
+    const env = buildClaudexEnv(
+      {
+        ANTHROPIC_API_KEY: 'sk-ant-api03-leak',
+        ANTHROPIC_AUTH_TOKEN: 'access_token_leak',
+        SOME_JWT_TOKEN: 'eyJhbGciOiJIUzI1NiJ9.payload.sig',
+        REFRESH_SECRET: 'refresh_token_value',
+      },
+      { configDir, models },
+    );
+    for (const [name, value] of Object.entries(env)) {
+      if (CLAUDEX_CREDENTIAL_ENV_RE.test(name)) {
+        // Any surviving credential-named var must carry only a safe sentinel value.
+        expect(value).not.toMatch(/sk-(ant|proj)-/);
+        expect(value).not.toMatch(/access_token|refresh_token/);
+        expect(value).not.toMatch(/eyJ[A-Za-z0-9_-]+\./); // JWT
+      }
+    }
+  });
+
+  it('honors a caller-provided baseUrl override (loopback default otherwise)', () => {
+    const env = buildClaudexEnv({}, { configDir, models, baseUrl: 'http://127.0.0.1:9999' });
+    expect(env.ANTHROPIC_BASE_URL).toBe('http://127.0.0.1:9999');
+  });
+
+  it('returns a fresh object without mutating the base env', () => {
+    const base = { EXISTING: 'kept' };
+    const env = buildClaudexEnv(base, { configDir, models });
+    expect(env.EXISTING).toBe('kept');
+    expect(base).not.toHaveProperty('ANTHROPIC_AUTH_TOKEN');
+  });
+});
+
+// ─── EXPERIMENTAL classification (P4) ─────────────────────────────────────────
+
+describe('buildClaudexBanner / buildClaudexContractNote', () => {
+  const models = { primary: 'gpt-5.6-sol', smallFast: 'gpt-5.6-luna' };
+
+  it('banner marks EXPERIMENTAL and names the models + proxy', () => {
+    const banner = buildClaudexBanner(models);
+    expect(banner).toMatch(/EXPERIMENTAL/);
+    expect(banner).toMatch(/gpt-5\.6-sol/);
+    expect(banner).toMatch(/gpt-5\.6-luna/);
+    expect(banner).toMatch(/claude-code-proxy/);
+    expect(banner).not.toMatch(/unused/); // no token material in the banner
+  });
+
+  it('contract note classifies the runtime as EXPERIMENTAL GPT-via-proxy', () => {
+    const note = buildClaudexContractNote(models);
+    expect(note).toMatch(/EXPERIMENTAL/);
+    expect(note).toMatch(/gpt-5\.6-sol/);
+    expect(note).toMatch(/not.*Anthropic/i);
+  });
+});
+
+// ─── proxy gate ───────────────────────────────────────────────────────────────
+
+describe('runClaudexProxyGate', () => {
+  it('is ok when the first preflight already passes', async () => {
+    const preflight = vi.fn().mockResolvedValue(makeReport());
+    const ensureProxy = vi.fn();
+    const reauth = vi.fn();
+    const gate = await runClaudexProxyGate({ preflight, ensureProxy, reauth });
+    expect(gate.ok).toBe(true);
+    expect(ensureProxy).not.toHaveBeenCalled();
+    expect(reauth).not.toHaveBeenCalled();
+  });
+
+  it('fails fast when the binary is missing (no reauth, no start)', async () => {
+    const preflight = vi
+      .fn()
+      .mockResolvedValue(
+        makeReport({ binaryPresent: false, ok: false, problems: ['binary not found'] }),
+      );
+    const ensureProxy = vi.fn();
+    const reauth = vi.fn();
+    const gate = await runClaudexProxyGate({ preflight, ensureProxy, reauth });
+    expect(gate.ok).toBe(false);
+    expect(reauth).not.toHaveBeenCalled();
+    expect(ensureProxy).not.toHaveBeenCalled();
+  });
+
+  it('runs device reauth then re-preflights when OAuth needs it', async () => {
+    const preflight = vi
+      .fn()
+      .mockResolvedValueOnce(
+        makeReport({
+          auth: { state: 'expired' },
+          needsReauth: true,
+          ok: false,
+          problems: ['expired'],
+        }),
+      )
+      .mockResolvedValueOnce(makeReport());
+    const reauth = vi.fn().mockReturnValue(0);
+    const gate = await runClaudexProxyGate({ preflight, reauth, ensureProxy: vi.fn() });
+    expect(reauth).toHaveBeenCalledTimes(1);
+    expect(preflight).toHaveBeenCalledTimes(2);
+    expect(gate.ok).toBe(true);
+  });
+
+  it('does NOT reauth when auth is already valid', async () => {
+    const preflight = vi.fn().mockResolvedValue(makeReport());
+    const reauth = vi.fn();
+    await runClaudexProxyGate({ preflight, reauth, ensureProxy: vi.fn() });
+    expect(reauth).not.toHaveBeenCalled();
+  });
+
+  it('aborts when device reauth fails', async () => {
+    const preflight = vi.fn().mockResolvedValue(
+      makeReport({
+        auth: { state: 'unauthenticated' },
+        needsReauth: true,
+        ok: false,
+        problems: ['unauth'],
+      }),
+    );
+    const reauth = vi.fn().mockReturnValue(1);
+    const gate = await runClaudexProxyGate({ preflight, reauth, ensureProxy: vi.fn() });
+    expect(gate.ok).toBe(false);
+    expect(gate.problems.join(' ')).toMatch(/re-auth/i);
+  });
+
+  it('starts the proxy then re-preflights when nothing is live', async () => {
+    const preflight = vi
+      .fn()
+      .mockResolvedValueOnce(
+        makeReport({ live: false, listenerVerdict: 'unknown', ok: false, problems: ['dead'] }),
+      )
+      .mockResolvedValueOnce(makeReport());
+    const ensureProxy = vi.fn().mockResolvedValue({ live: true, method: 'systemd' });
+    const gate = await runClaudexProxyGate({ preflight, ensureProxy, reauth: vi.fn() });
+    expect(ensureProxy).toHaveBeenCalledTimes(1);
+    expect(gate.ok).toBe(true);
+  });
+
+  it('aborts (non-sensitive) when the proxy cannot come up trusted', async () => {
+    const preflight = vi
+      .fn()
+      .mockResolvedValue(
+        makeReport({ live: false, listenerVerdict: 'unknown', ok: false, problems: ['dead'] }),
+      );
+    const ensureProxy = vi.fn().mockResolvedValue({ live: false, method: 'untrusted' });
+    const gate = await runClaudexProxyGate({ preflight, ensureProxy, reauth: vi.fn() });
+    expect(gate.ok).toBe(false);
+    expect(gate.problems.join(' ')).toMatch(/untrusted/);
+    // Non-sensitive: no token material in surfaced problems.
+    expect(gate.problems.join(' ')).not.toMatch(/access_token|refresh_token|sk-/);
+  });
+});
+
+// ─── launch orchestration (fail-closed ordering) ──────────────────────────────
+
+describe('launchClaudex', () => {
+  const baseDeps = {
+    baseEnv: {},
+    proxyGate: () => Promise.resolve({ ok: true, report: makeReport(), problems: [] }),
+    resolveConfigDir: () => '/home/agent/.config/mosaic/claudex/home',
+    log: () => {},
+    errorLog: () => {},
+    fail: (() => {
+      throw new Error('exit');
+    }) as (code: number) => never,
+  };
+
+  it('yolo=true passes --dangerously-skip-permissions + injected env to claude', async () => {
+    const exec = vi.fn();
+    await launchClaudex(['--print', 'hi'], true, okAdapter({ exec }), baseDeps);
+    expect(exec).toHaveBeenCalledTimes(1);
+    const [cmd, args, env] = exec.mock.calls[0]!;
+    expect(cmd).toBe('claude');
+    expect(args[0]).toBe('--dangerously-skip-permissions');
+    expect(args).toContain('--append-system-prompt');
+    expect(args).toContain('--print');
+    expect(args).toContain('hi');
+    expect(env.ANTHROPIC_AUTH_TOKEN).toBe('unused');
+    expect(env.ANTHROPIC_BASE_URL).toBe(CLAUDEX_PROXY_URL);
+    expect(env.CLAUDE_CONFIG_DIR).toBe('/home/agent/.config/mosaic/claudex/home');
+    expect(env.ANTHROPIC_MODEL).toBe('gpt-5.6-sol');
+  });
+
+  it('non-yolo omits --dangerously-skip-permissions but still injects the proxy env', async () => {
+    const exec = vi.fn();
+    await launchClaudex([], false, okAdapter({ exec }), baseDeps);
+    const [, args, env] = exec.mock.calls[0]!;
+    expect(args).not.toContain('--dangerously-skip-permissions');
+    expect(args[0]).toBe('--append-system-prompt');
+    expect(env.ANTHROPIC_AUTH_TOKEN).toBe('unused');
+  });
+
+  it('appends the EXPERIMENTAL contract note to the composed prompt', async () => {
+    const exec = vi.fn();
+    await launchClaudex([], true, okAdapter({ exec, composePrompt: () => '# BASE' }), baseDeps);
+    const args = exec.mock.calls[0]![1] as string[];
+    const promptIdx = args.indexOf('--append-system-prompt') + 1;
+    expect(args[promptIdx]).toContain('# BASE');
+    expect(args[promptIdx]).toMatch(/EXPERIMENTAL/);
+  });
+
+  it('runs the harness preflight BEFORE the proxy gate and exec', async () => {
+    const order: string[] = [];
+    const adapter = okAdapter({
+      harnessPreflight: () => order.push('preflight'),
+      exec: () => order.push('exec'),
+    });
+    await launchClaudex([], true, adapter, {
+      ...baseDeps,
+      proxyGate: () => {
+        order.push('gate');
+        return Promise.resolve({ ok: true, report: makeReport(), problems: [] });
+      },
+    });
+    expect(order).toEqual(['preflight', 'gate', 'exec']);
+  });
+
+  it('FAIL CLOSED: exits WITHOUT exec when the proxy gate fails', async () => {
+    const exec = vi.fn();
+    const errors: string[] = [];
+    await expect(
+      launchClaudex([], true, okAdapter({ exec }), {
+        ...baseDeps,
+        proxyGate: () =>
+          Promise.resolve({ ok: false, report: makeReport({ ok: false }), problems: ['no proxy'] }),
+        errorLog: (m: string) => errors.push(m),
+      }),
+    ).rejects.toThrow('exit');
+    expect(exec).not.toHaveBeenCalled();
+    expect(errors.join('\n')).toMatch(/no proxy/);
+  });
+
+  it('FAIL CLOSED: exits WITHOUT exec when the config-dir guard throws', async () => {
+    const exec = vi.fn();
+    await expect(
+      launchClaudex([], true, okAdapter({ exec }), {
+        ...baseDeps,
+        resolveConfigDir: () => {
+          throw new Error('refusing to use ~/.claude');
+        },
+      }),
+    ).rejects.toThrow('exit');
+    expect(exec).not.toHaveBeenCalled();
+  });
+
+  it('FAIL CLOSED: reports a non-Error throw via String() and still aborts', async () => {
+    const exec = vi.fn();
+    const errors: string[] = [];
+    await expect(
+      launchClaudex([], true, okAdapter({ exec }), {
+        ...baseDeps,
+        resolveConfigDir: () => {
+          // A non-Error throw exercises the String(err) branch of the catch.
+          throw { toString: () => 'string-shaped failure' };
+        },
+        errorLog: (m: string) => errors.push(m),
+      }),
+    ).rejects.toThrow('exit');
+    expect(exec).not.toHaveBeenCalled();
+    expect(errors.join('\n')).toMatch(/string-shaped failure/);
+  });
+});
+
+// ─── production DI defaults (fallback-branch coverage; no real proxy touched) ──
+
+describe('production dependency defaults', () => {
+  it('assertIsolatedConfigDir defaults realClaudeDir to ~/.claude', () => {
+    const safe = join(tmpdir(), 'mosaic-claudex-default-real', 'home');
+    // Only canonicalize injected; realClaudeDir falls back to ~/.claude.
+    expect(assertIsolatedConfigDir(safe, { canonicalize: idCanon })).toBe(safe);
+  });
+
+  it('assertIsolatedConfigDir default canonicalizer resolves a non-existent path', () => {
+    // No canonicalize dep → exercises the real realpath-longest-ancestor walk
+    // (including the not-yet-existing tail), on a path safely outside ~/.claude.
+    const safe = join(tmpdir(), 'mosaic-claudex-canon', 'nested', 'home');
+    expect(assertIsolatedConfigDir(safe)).toContain('mosaic-claudex-canon');
+  });
+
+  it('resolveClaudexConfigDir defaults mosaicHome when not injected', () => {
+    const dir = mkdtempSync(join(tmpdir(), 'claudex-cfg-'));
+    try {
+      const target = join(dir, 'home');
+      // Override env points elsewhere; mosaicHome dep omitted → MOSAIC_HOME default path is exercised.
+      const out = resolveClaudexConfigDir(
+        { [CLAUDEX_CONFIG_DIR_ENV]: target },
+        { canonicalize: idCanon },
+      );
+      expect(out).toBe(target);
+      expect(lstatSync(target).isDirectory()).toBe(true);
+    } finally {
+      rmSync(dir, { recursive: true, force: true });
+    }
+  });
+
+  it('runClaudexProxyGate defaults ensureProxy/reauth/log without invoking them on a missing binary', async () => {
+    // Only preflight injected; binary missing → returns before the default
+    // ensureProxy/reauth thunks could ever reach the real proxy.
+    const preflight = vi
+      .fn()
+      .mockResolvedValue(makeReport({ binaryPresent: false, ok: false, problems: ['missing'] }));
+    const gate = await runClaudexProxyGate({ preflight });
+    expect(gate.ok).toBe(false);
+  });
+
+  it('launchClaudex defaults log/errorLog/fail/baseEnv/models/buildEnv on the success path', async () => {
+    const logSpy = vi.spyOn(console, 'log').mockImplementation(() => {});
+    try {
+      const exec = vi.fn();
+      // Inject only the boundaries that would touch the real proxy/FS; let the
+      // rest default. Success path never calls fail/errorLog.
+      await launchClaudex([], true, okAdapter({ exec }), {
+        proxyGate: () => Promise.resolve({ ok: true, report: makeReport(), problems: [] }),
+        resolveConfigDir: () => join(tmpdir(), 'claudex-default-launch'),
+      });
+      expect(exec).toHaveBeenCalledTimes(1);
+      const [, , env] = exec.mock.calls[0]!;
+      expect(env.ANTHROPIC_AUTH_TOKEN).toBe('unused');
+      expect(env.ANTHROPIC_MODEL).toBe(CLAUDEX_DEFAULT_PRIMARY_MODEL);
+    } finally {
+      logSpy.mockRestore();
+    }
+  });
+});

packages/mosaic/src/commands/claudex.ts

@@ -0,0 +1,464 @@
+/**
+ * Claudex launch composition (P2–P4 of `mosaic yolo claudex`).
+ *
+ * Builds the isolated launch environment for running GPT models inside the
+ * Claude Code harness via `raine/claude-code-proxy` (ChatGPT-subscription OAuth).
+ * PR-1 (`claudex-proxy.ts`) owns the proxy preflight/lifecycle; this module owns
+ * the *composition* the launcher hands to Claude Code:
+ *
+ *   P2  isolated CLAUDE_CONFIG_DIR (provably never the real ~/.claude) + env
+ *       injection that leaks ZERO token material;
+ *   P3  the model-tier map (primary → gpt-5.6-sol, small/fast → gpt-5.6-luna,
+ *       operator env values win);
+ *   P4  the EXPERIMENTAL classification banner + composed-contract note.
+ *
+ * Two hard security invariants (secrev-enforced):
+ *   REQ 1 — Provable isolation. {@link assertIsolatedConfigDir} makes the
+ *           CLAUDE_CONFIG_DIR seam incapable of resolving to `~/.claude` (or any
+ *           descendant of it); it canonicalizes both sides, rejects descendants,
+ *           and — after ensuring the dir — re-checks and rejects a symlinked
+ *           target (TOCTOU). Fails CLOSED on any uncertainty.
+ *   REQ 2 — Zero token leakage. This module never reads the proxy's
+ *           `auth.json`; {@link buildClaudexEnv} strips the ENTIRE
+ *           credential-bearing env family and hands Claude Code only
+ *           `ANTHROPIC_AUTH_TOKEN=unused`. The proxy holds the real credential.
+ *
+ * Every side-effecting boundary is dependency-injected so the launch path is
+ * unit-testable without spawning Claude Code or touching a real config dir.
+ */
+
+import { lstatSync, mkdirSync, realpathSync } from 'node:fs';
+import { homedir } from 'node:os';
+import { dirname, isAbsolute, join, relative, resolve } from 'node:path';
+import {
+  CLAUDEX_PROXY_URL,
+  ensureProxyRunning,
+  runDeviceReauth,
+  runProxyPreflight,
+  type EnsureProxyResult,
+  type PreflightReport,
+} from './claudex-proxy.js';
+
+const MOSAIC_HOME = process.env['MOSAIC_HOME'] ?? join(homedir(), '.config', 'mosaic');
+
+// ─── Isolated CLAUDE_CONFIG_DIR (HARD SECURITY REQ 1) ─────────────────────────
+
+/** Dedicated override env for the isolated config dir. The ambient
+ * `CLAUDE_CONFIG_DIR` is deliberately NOT honored — it may already point at the
+ * real `~/.claude` of the launching session. */
+export const CLAUDEX_CONFIG_DIR_ENV = 'MOSAIC_CLAUDEX_CONFIG_DIR';
+
+/** The default isolated config dir — structurally under the mosaic home, so it
+ * can never equal `~/.claude`. */
+export function defaultClaudexConfigDir(mosaicHome: string = MOSAIC_HOME): string {
+  return join(mosaicHome, 'claudex', 'home');
+}
+
+export interface ConfigDirDeps {
+  /** The real Claude state dir to protect (default `~/.claude`). */
+  realClaudeDir?: string;
+  /** Resolve a path to canonical form, resolving symlinks on the longest
+   * existing ancestor (so a not-yet-created dir still canonicalizes). */
+  canonicalize?: (p: string) => string;
+  /** Ensure the isolated dir exists (mkdir -p, owner-only 0700). */
+  mkdir?: (p: string) => void;
+  /** Whether a path is itself a symlink (lstat). */
+  isSymlink?: (p: string) => boolean;
+}
+
+/** Resolve a path to canonical form, resolving symlinks on the LONGEST EXISTING
+ * ancestor and re-appending the not-yet-existing tail. A symlinked ancestor that
+ * points into `~/.claude` is therefore caught even before the leaf exists. */
+function defaultCanonicalizeIntended(p: string): string {
+  const abs = resolve(p);
+  let existing = abs;
+  const tail: string[] = [];
+  // Walk up until we hit an existing ancestor (or the filesystem root).
+  for (;;) {
+    try {
+      const real = realpathSync(existing);
+      return tail.length > 0 ? join(real, ...tail) : real;
+    } catch (err) {
+      // ONLY a genuine "does not exist yet" (ENOENT) justifies walking up to an
+      // existing ancestor. Any other errno (ELOOP, EACCES, ENOTDIR, …) means we
+      // cannot establish the canonical form — fail CLOSED rather than fall back
+      // to a possibly-wrong literal path.
+      if ((err as NodeJS.ErrnoException).code !== 'ENOENT') throw err;
+      const parent = dirname(existing);
+      if (parent === existing) return abs; // reached root without an existing prefix
+      tail.unshift(existing.slice(parent.length + 1));
+      existing = parent;
+    }
+  }
+}
+
+function defaultMkdir(p: string): void {
+  mkdirSync(p, { recursive: true, mode: 0o700 });
+}
+
+function defaultIsSymlink(p: string): boolean {
+  try {
+    return lstatSync(p).isSymbolicLink();
+  } catch (err) {
+    // A missing path is genuinely "not a symlink"; anything else (EACCES, ELOOP,
+    // ENOTDIR, …) is uncertainty the guard must not swallow — fail CLOSED.
+    if ((err as NodeJS.ErrnoException).code === 'ENOENT') return false;
+    throw err;
+  }
+}
+
+/** True when `child` is `parent` itself or a descendant of it (path-wise). */
+function isWithin(child: string, parent: string): boolean {
+  if (child === parent) return true;
+  const rel = relative(parent, child);
+  return rel.length > 0 && !rel.startsWith('..') && !isAbsolute(rel);
+}
+
+/**
+ * Guard: prove that `candidate` is a legitimate ISOLATED config dir and can
+ * never be, resolve to, or live under the real `~/.claude`. Canonicalizes BOTH
+ * sides (either may be a symlink), rejects `~/.claude` and any descendant, and
+ * fails CLOSED (throws) on an empty/relative candidate. Returns the canonical
+ * isolated path on success.
+ */
+export function assertIsolatedConfigDir(candidate: string, deps: ConfigDirDeps = {}): string {
+  const canonicalize = deps.canonicalize ?? defaultCanonicalizeIntended;
+  const realClaudeDir = deps.realClaudeDir ?? join(homedir(), '.claude');
+
+  if (typeof candidate !== 'string' || candidate.trim() === '') {
+    throw new Error('claudex: isolated CLAUDE_CONFIG_DIR must be a non-empty path (fail closed).');
+  }
+  if (!isAbsolute(candidate)) {
+    throw new Error(
+      `claudex: isolated CLAUDE_CONFIG_DIR must be an absolute path: ${JSON.stringify(candidate)}`,
+    );
+  }
+
+  const canonCandidate = canonicalize(candidate);
+  const canonReal = canonicalize(realClaudeDir);
+
+  // Compare canonical forms AND raw resolved forms — belt and suspenders so a
+  // canonicalizer that no-ops on a nonexistent real dir still catches the literal.
+  if (isWithin(canonCandidate, canonReal) || isWithin(resolve(candidate), resolve(realClaudeDir))) {
+    throw new Error(
+      `claudex: refusing to use the real Claude config dir (or a descendant of it) as the ` +
+        `isolated CLAUDE_CONFIG_DIR. Resolved to ${JSON.stringify(canonCandidate)}.`,
+    );
+  }
+
+  return canonCandidate;
+}
+
+/**
+ * Resolve the isolated CLAUDE_CONFIG_DIR: pick the dedicated override or the
+ * namespaced default, run the pre-create guard, ensure the dir (0700), then
+ * RE-CHECK after creation — reject a symlinked target and re-run the guard on
+ * the now-existing (fully canonicalizable) path. This closes the pre-created
+ * symlink race (TOCTOU). Every failure throws (fail closed).
+ */
+export function resolveClaudexConfigDir(
+  env: NodeJS.ProcessEnv = process.env,
+  deps: ConfigDirDeps & { mosaicHome?: string } = {},
+): string {
+  const mosaicHome = deps.mosaicHome ?? MOSAIC_HOME;
+  const mkdir = deps.mkdir ?? defaultMkdir;
+  const isSymlink = deps.isSymlink ?? defaultIsSymlink;
+
+  const override = env[CLAUDEX_CONFIG_DIR_ENV]?.trim();
+  const candidate =
+    override && override.length > 0 ? override : defaultClaudexConfigDir(mosaicHome);
+
+  // Pre-create guard (before touching the filesystem).
+  assertIsolatedConfigDir(candidate, deps);
+
+  // Ensure the dir, then re-verify against the post-create reality.
+  mkdir(candidate);
+  if (isSymlink(candidate)) {
+    throw new Error(
+      'claudex: refusing to use the isolated CLAUDE_CONFIG_DIR — the target is a symlink ' +
+        '(possible pre-created race). Fail closed.',
+    );
+  }
+  // Re-run the guard now that the leaf exists so canonicalization reflects any
+  // symlinked ancestor introduced between the pre-check and mkdir.
+  return assertIsolatedConfigDir(candidate, deps);
+}
+
+// ─── Model-tier map (P3) ──────────────────────────────────────────────────────
+
+export const CLAUDEX_DEFAULT_PRIMARY_MODEL = 'gpt-5.6-sol';
+export const CLAUDEX_DEFAULT_SMALL_FAST_MODEL = 'gpt-5.6-luna';
+
+export interface ClaudexModels {
+  /** Primary tier (opus/sonnet) → ANTHROPIC_MODEL. */
+  primary: string;
+  /** Small/fast tier (haiku) → ANTHROPIC_SMALL_FAST_MODEL. */
+  smallFast: string;
+}
+
+/** Resolve the model-tier map. Operator-provided env values WIN over defaults;
+ * blank values fall back to the defaults. */
+export function resolveClaudexModels(env: NodeJS.ProcessEnv = process.env): ClaudexModels {
+  const primary = env['ANTHROPIC_MODEL']?.trim() || CLAUDEX_DEFAULT_PRIMARY_MODEL;
+  const smallFast = env['ANTHROPIC_SMALL_FAST_MODEL']?.trim() || CLAUDEX_DEFAULT_SMALL_FAST_MODEL;
+  return { primary, smallFast };
+}
+
+// ─── Env injection (HARD SECURITY REQ 2 — zero token leakage) ─────────────────
+
+/**
+ * Names of env vars considered credential-bearing. The whole family is stripped
+ * from the composed env so no real Anthropic key, OAuth token, or third-party /
+ * cloud credential can reach the local proxy or be used by Claude Code to bypass
+ * it. We then re-add ONLY the safe claudex vars (`ANTHROPIC_MODEL`,
+ * `_SMALL_FAST_MODEL`, `_BASE_URL`, `_AUTH_TOKEN=unused`). A name-pattern sweep
+ * can't miss a specific var a short denylist forgot, while still preserving the
+ * arbitrary non-credential env the harness/MCP/hooks require (PATH, HOME, XDG,
+ * terminal, proxies, …), which a strict allowlist would fragilely drop.
+ *
+ * The cloud-provider families (`AWS_*`, `GOOGLE_APPLICATION_CREDENTIALS`,
+ * `GOOGLE_CLOUD_*`, `GCP_*`) are included because Claude Code can route to the
+ * real Anthropic API via AWS Bedrock / GCP Vertex using the ambient cloud
+ * credential chain — a Claude-capable credential that must never survive into a
+ * claudex launch. `_KEY$` / `_SECRET` (not just the `_API_KEY$` tail) close the
+ * mid-string gap (`STRIPE_SECRET_KEY`, `SSH_PRIVATE_KEY`, `AWS_SECRET_ACCESS_KEY`).
+ */
+export const CLAUDEX_CREDENTIAL_ENV_RE =
+  /^ANTHROPIC_|^CLAUDE_CODE_OAUTH|^AWS_|^GOOGLE_APPLICATION_CREDENTIALS$|^GOOGLE_CLOUD_|^GCP_|_API_?KEY$|_KEY$|_TOKEN$|_SECRET/i;
+
+/**
+ * Provider ROUTING switches whose mere PRESENCE (independent of any credential)
+ * makes Claude Code bypass `ANTHROPIC_BASE_URL` (the loopback proxy) and talk to
+ * the real Anthropic API via Bedrock/Vertex. A name-pattern is the wrong model
+ * for a boolean switch, so these are force-deleted by exact name — REGARDLESS of
+ * value — after the credential sweep. (REQ 2: isolation must hold for any
+ * launching env, including a Bedrock/Vertex-configured enterprise host.)
+ */
+export const CLAUDEX_FORCED_UNSET_ENV = [
+  'CLAUDE_CODE_USE_BEDROCK',
+  'CLAUDE_CODE_USE_VERTEX',
+  'CLAUDE_CODE_SKIP_BEDROCK_AUTH',
+  'CLAUDE_CODE_SKIP_VERTEX_AUTH',
+] as const;
+
+export interface BuildClaudexEnvOptions {
+  configDir: string;
+  models: ClaudexModels;
+  /** Override the proxy base URL (defaults to the PR-1 loopback constant). */
+  baseUrl?: string;
+}
+
+/**
+ * Compose the launch env for Claude Code. Returns a FRESH object (never mutates
+ * the base env). Strips the entire credential-bearing family AND force-deletes
+ * the Bedrock/Vertex routing switches (REQ 2), then sets the isolated config dir
+ * and the proxy routing. Claude Code sees only `ANTHROPIC_AUTH_TOKEN=unused`
+ * pointed at the loopback proxy; the proxy holds the real OAuth credential, which
+ * this module never reads.
+ */
+export function buildClaudexEnv(
+  baseEnv: NodeJS.ProcessEnv,
+  opts: BuildClaudexEnvOptions,
+): NodeJS.ProcessEnv {
+  const env: NodeJS.ProcessEnv = {};
+  for (const [name, value] of Object.entries(baseEnv)) {
+    if (CLAUDEX_CREDENTIAL_ENV_RE.test(name)) continue; // drop the whole credential family
+    env[name] = value;
+  }
+
+  // Force-delete routing switches by exact name — their presence (not their
+  // value) is what would route Claude Code off the proxy to the real API.
+  for (const name of CLAUDEX_FORCED_UNSET_ENV) delete env[name];
+
+  env['CLAUDE_CONFIG_DIR'] = opts.configDir;
+  env['ANTHROPIC_BASE_URL'] = opts.baseUrl ?? CLAUDEX_PROXY_URL;
+  env['ANTHROPIC_AUTH_TOKEN'] = 'unused';
+  env['ANTHROPIC_MODEL'] = opts.models.primary;
+  env['ANTHROPIC_SMALL_FAST_MODEL'] = opts.models.smallFast;
+  return env;
+}
+
+// ─── EXPERIMENTAL classification (P4) ─────────────────────────────────────────
+
+/** Console banner shown at launch. Contains no token material by construction. */
+export function buildClaudexBanner(models: ClaudexModels): string {
+  return [
+    '',
+    '  ┌─────────────────────────────────────────────────────────────────────┐',
+    '  │  ⚠  EXPERIMENTAL — mosaic claudex                                     │',
+    '  └─────────────────────────────────────────────────────────────────────┘',
+    `  Running GPT models inside the Claude Code harness via claude-code-proxy`,
+    `  (ChatGPT-subscription OAuth). This is NOT Anthropic Claude.`,
+    `    primary    : ${models.primary}`,
+    `    small/fast : ${models.smallFast}`,
+    `  Model behavior, tool use, and output quality may differ from Claude.`,
+    '',
+  ].join('\n');
+}
+
+/** Markdown note appended to the composed runtime contract so the model itself
+ * knows it is running the EXPERIMENTAL GPT-via-proxy configuration. */
+export function buildClaudexContractNote(models: ClaudexModels): string {
+  return [
+    '# EXPERIMENTAL Runtime — claudex (GPT via claude-code-proxy)',
+    '',
+    'You are running in Mosaic **claudex** mode: the Claude Code harness is wired to',
+    'GPT models through a local `claude-code-proxy` (ChatGPT-subscription OAuth). This',
+    "runtime is NOT Anthropic's Claude API and is not Claude.",
+    '',
+    `- Primary model: \`${models.primary}\``,
+    `- Small/fast model: \`${models.smallFast}\``,
+    '',
+    'Some Claude-specific harness assumptions may not hold under GPT models — verify',
+    'tool output carefully. This classification is EXPERIMENTAL and is not intended for',
+    'production delivery without explicit operator sign-off.',
+  ].join('\n');
+}
+
+// ─── Proxy gate ───────────────────────────────────────────────────────────────
+
+export interface ProxyGateResult {
+  ok: boolean;
+  report: PreflightReport;
+  /** Non-sensitive problems suitable for surfacing to the operator. */
+  problems: string[];
+}
+
+export interface ProxyGateDeps {
+  preflight?: () => Promise<PreflightReport>;
+  ensureProxy?: () => Promise<EnsureProxyResult>;
+  reauth?: () => number;
+  log?: (message: string) => void;
+}
+
+/**
+ * Run the proxy readiness gate: preflight → (device reauth if OAuth needs it) →
+ * (start the proxy if nothing trusted is live) → re-preflight. Returns `ok` only
+ * when the final preflight passes (binary present, OAuth valid, a TRUSTED-live
+ * listener — identity verified by PR-1's `verifyListenerIdentity`). All surfaced
+ * problems are non-sensitive (port + verdict only; never a token).
+ */
+export async function runClaudexProxyGate(deps: ProxyGateDeps = {}): Promise<ProxyGateResult> {
+  const preflight = deps.preflight ?? (() => runProxyPreflight());
+  const ensureProxy = deps.ensureProxy ?? (() => ensureProxyRunning());
+  const reauth = deps.reauth ?? (() => runDeviceReauth());
+  const log = deps.log ?? (() => {});
+
+  let report = await preflight();
+
+  // A missing binary is unrecoverable here — don't attempt reauth or a start.
+  if (!report.binaryPresent) {
+    return { ok: false, report, problems: report.problems };
+  }
+
+  if (report.needsReauth) {
+    log('claudex: claude-code-proxy OAuth needs re-authentication — starting device flow…');
+    const code = reauth();
+    if (code !== 0) {
+      return {
+        ok: false,
+        report,
+        problems: [...report.problems, 'claudex: device re-authentication did not complete.'],
+      };
+    }
+    report = await preflight();
+  }
+
+  if (!report.live) {
+    log('claudex: no trusted claude-code-proxy responding — starting it…');
+    const started = await ensureProxy();
+    if (!started.live) {
+      return {
+        ok: false,
+        report,
+        problems: [
+          ...report.problems,
+          `claudex: could not bring up a trusted claude-code-proxy (${started.method}).`,
+        ],
+      };
+    }
+    report = await preflight();
+  }
+
+  return { ok: report.ok, report, problems: report.problems };
+}
+
+// ─── Launch orchestration ─────────────────────────────────────────────────────
+
+/**
+ * The launch.ts-provided seam. Keeps `claudex.ts` free of a circular import back
+ * into `launch.ts` while letting the orchestration reuse the harness preflight,
+ * the composed runtime contract, and the process-replacing exec.
+ */
+export interface ClaudexHarnessAdapter {
+  /** Runs the Claude-harness preflight (mosaic home, SOUL, `claude` on PATH,
+   * sequential-thinking). May terminate the process on a hard failure. */
+  harnessPreflight: () => void;
+  /** Compose the full Claude runtime contract (== `composeContract('claude')`). */
+  composePrompt: () => string;
+  /** Replace the current process with `claude` using the composed env. */
+  exec: (cmd: string, args: string[], env: NodeJS.ProcessEnv) => void;
+}
+
+export interface LaunchClaudexDeps {
+  baseEnv?: NodeJS.ProcessEnv;
+  proxyGate?: () => Promise<ProxyGateResult>;
+  resolveConfigDir?: () => string;
+  models?: () => ClaudexModels;
+  buildEnv?: (base: NodeJS.ProcessEnv, opts: BuildClaudexEnvOptions) => NodeJS.ProcessEnv;
+  log?: (message: string) => void;
+  errorLog?: (message: string) => void;
+  fail?: (code: number) => never;
+}
+
+/**
+ * Orchestrate a `mosaic [yolo] claudex` launch. Runs the harness preflight, the
+ * proxy gate, composes the isolated env (REQ 1 + REQ 2), appends the EXPERIMENTAL
+ * note, and exec's Claude Code. FAIL CLOSED: on any gate failure or guard throw
+ * it reports non-sensitive detail and exits WITHOUT reaching exec.
+ */
+export async function launchClaudex(
+  args: string[],
+  yolo: boolean,
+  adapter: ClaudexHarnessAdapter,
+  deps: LaunchClaudexDeps = {},
+): Promise<void> {
+  const log = deps.log ?? ((m: string) => console.log(m));
+  const errorLog = deps.errorLog ?? ((m: string) => console.error(m));
+  const fail = deps.fail ?? ((code: number) => process.exit(code));
+  const baseEnv = deps.baseEnv ?? process.env;
+  const proxyGate = deps.proxyGate ?? (() => runClaudexProxyGate({ log }));
+  const resolveConfigDir = deps.resolveConfigDir ?? (() => resolveClaudexConfigDir(baseEnv));
+  const models = deps.models ?? (() => resolveClaudexModels(baseEnv));
+  const buildEnv = deps.buildEnv ?? buildClaudexEnv;
+
+  try {
+    // Harness readiness first (claude on PATH, mosaic home, sequential-thinking).
+    adapter.harnessPreflight();
+
+    // Proxy readiness (binary, OAuth, trusted-live listener).
+    const gate = await proxyGate();
+    if (!gate.ok) {
+      errorLog('[mosaic] claudex preflight failed:');
+      for (const problem of gate.problems) errorLog(`  - ${problem}`);
+      return fail(1);
+    }
+
+    // Compose the isolated launch env (guard throws → caught below, fail closed).
+    const resolvedModels = models();
+    const configDir = resolveConfigDir();
+    const env = buildEnv(baseEnv, { configDir, models: resolvedModels });
+    const prompt = `${adapter.composePrompt()}\n\n${buildClaudexContractNote(resolvedModels)}`;
+
+    log(buildClaudexBanner(resolvedModels));
+
+    const cliArgs = yolo ? ['--dangerously-skip-permissions'] : [];
+    cliArgs.push('--append-system-prompt', prompt, ...args);
+    adapter.exec('claude', cliArgs, env);
+  } catch (err) {
+    errorLog(
+      `[mosaic] claudex launch aborted: ${err instanceof Error ? err.message : String(err)}`,
+    );
+    return fail(1);
+  }
+}

packages/mosaic/src/commands/launch.spec.ts

@@ -9,6 +9,7 @@ import {
   piForceSkillNames,
   registerRuntimeLaunchers,
   type RuntimeLaunchHandler,
+  type ClaudexLaunchHandler,
 } from './launch.js';
 
 /**
@@ -31,6 +32,16 @@ function buildProgram(handler: RuntimeLaunchHandler): Command {
   return program;
 }
 
+function buildProgramWithClaudex(
+  handler: RuntimeLaunchHandler,
+  claudexHandler: ClaudexLaunchHandler,
+): Command {
+  const program = new Command();
+  program.exitOverride();
+  registerRuntimeLaunchers(program, handler, claudexHandler);
+  return program;
+}
+
 const fakeSkills = ['--skill', '/skills/test-driven-development', '--skill', '/skills/pdf'];
 const fakeForced = ['--skill', '/skills/mosaic-tools'];
 
@@ -280,3 +291,61 @@ describe('registerRuntimeLaunchers — yolo <runtime>', () => {
     expect(mockExit).toHaveBeenCalledWith(1);
   });
 });
+
+describe('registerRuntimeLaunchers — claudex (EXPERIMENTAL overlay)', () => {
+  let mockExit: MockInstance<typeof process.exit>;
+  let mockError: MockInstance<typeof console.error>;
+
+  beforeEach(() => {
+    mockExit = vi.spyOn(process, 'exit').mockImplementation(exitThrows);
+    mockError = vi.spyOn(console, 'error').mockImplementation(() => {});
+  });
+
+  afterEach(() => {
+    mockExit.mockRestore();
+    mockError.mockRestore();
+  });
+
+  it('dispatches `claudex` to the claudex handler (yolo=false), not the runtime handler', () => {
+    const handler = vi.fn();
+    const claudex = vi.fn();
+    const program = buildProgramWithClaudex(handler, claudex);
+    program.parse(['node', 'mosaic', 'claudex']);
+
+    expect(claudex).toHaveBeenCalledTimes(1);
+    expect(claudex).toHaveBeenCalledWith([], false);
+    expect(handler).not.toHaveBeenCalled();
+  });
+
+  it('forwards excess args after `claudex`', () => {
+    const handler = vi.fn();
+    const claudex = vi.fn();
+    const program = buildProgramWithClaudex(handler, claudex);
+    program.parse(['node', 'mosaic', 'claudex', '--print', 'hi']);
+
+    expect(claudex).toHaveBeenCalledWith(['--print', 'hi'], false);
+  });
+
+  it('dispatches `yolo claudex` with yolo=true and slices off the runtime name (#454)', () => {
+    const handler = vi.fn();
+    const claudex = vi.fn();
+    const program = buildProgramWithClaudex(handler, claudex);
+    program.parse(['node', 'mosaic', 'yolo', 'claudex']);
+
+    expect(claudex).toHaveBeenCalledTimes(1);
+    // extraArgs must be empty — the positional 'claudex' must not leak through.
+    expect(claudex).toHaveBeenCalledWith([], true);
+    expect(handler).not.toHaveBeenCalled();
+    expect(mockExit).not.toHaveBeenCalled();
+  });
+
+  it('forwards true excess args after `yolo claudex`', () => {
+    const handler = vi.fn();
+    const claudex = vi.fn();
+    const program = buildProgramWithClaudex(handler, claudex);
+    program.parse(['node', 'mosaic', 'yolo', 'claudex', '--model', 'gpt-5.6-sol']);
+
+    expect(claudex).toHaveBeenCalledWith(['--model', 'gpt-5.6-sol'], true);
+    expect(mockExit).not.toHaveBeenCalled();
+  });
+});

packages/mosaic/src/commands/launch.ts

@@ -27,6 +27,7 @@ import {
 import { readRegularFileSecure } from '../fleet/secure-file.js';
 import { readPersonaContractBlock } from '../fleet/persona-contract.js';
 import { canonicalizeRoleClass } from './fleet-personas.js';
+import { launchClaudex, type ClaudexHarnessAdapter } from './claudex.js';
 
 const MOSAIC_HOME = process.env['MOSAIC_HOME'] ?? join(homedir(), '.config', 'mosaic');
 const MAX_INSTALLED_TOOLS_BYTES = 256 * 1024;
@@ -806,12 +807,12 @@ function launchRuntime(runtime: RuntimeName, args: string[], yolo: boolean): nev
 }
 
 /** exec into the runtime, replacing the current process. */
-function execRuntime(cmd: string, args: string[]): void {
+function execRuntime(cmd: string, args: string[], env: NodeJS.ProcessEnv = process.env): void {
   try {
     // Use execFileSync with inherited stdio to replace the process
     const result = spawnSync(cmd, args, {
       stdio: 'inherit',
-      env: process.env,
+      env,
     });
     process.exit(result.status ?? 0);
   } catch (err) {
@@ -820,6 +821,29 @@ function execRuntime(cmd: string, args: string[]): void {
   }
 }
 
+/**
+ * Production glue for `mosaic [yolo] claudex` (EXPERIMENTAL — GPT models inside
+ * the Claude Code harness via claude-code-proxy). Assembles the real harness
+ * adapter and delegates the security-critical composition + fail-closed
+ * orchestration to `launchClaudex` in `claudex.ts`. Kept thin so the tested
+ * logic lives in the DI module, not here.
+ */
+function launchClaudexProduction(args: string[], yolo: boolean): void {
+  writeSessionLock('claude');
+  const adapter: ClaudexHarnessAdapter = {
+    harnessPreflight: () => {
+      checkMosaicHome();
+      checkFile(join(MOSAIC_HOME, 'AGENTS.md'), 'AGENTS.md');
+      checkSoul();
+      checkRuntime('claude');
+      checkSequentialThinking('claude');
+    },
+    composePrompt: () => buildRuntimePrompt('claude'),
+    exec: (cmd, cmdArgs, env) => execRuntime(cmd, cmdArgs, env),
+  };
+  void launchClaudex(args, yolo, adapter);
+}
+
 // ─── Framework script/tool delegation ───────────────────────────────────────
 
 function delegateToScript(scriptPath: string, args: string[], env?: Record<string, string>): never {
@@ -1034,12 +1058,25 @@ export type RuntimeLaunchHandler = (
   yolo: boolean,
 ) => void;
 
+/**
+ * Handler invoked for `claudex` / `yolo claudex`. Kept separate from
+ * `RuntimeLaunchHandler` because claudex is an EXPERIMENTAL harness overlay
+ * (GPT-via-proxy), not one of the first-class runtimes. Exposed + injectable so
+ * the commander wiring can be exercised without composing a real launch.
+ */
+export type ClaudexLaunchHandler = (extraArgs: string[], yolo: boolean) => void;
+
 /**
  * Wire `<runtime>` and `yolo <runtime>` subcommands onto `program` using a
  * pluggable launch handler. Separated from `registerLaunchCommands` so tests
  * can inject a spy and verify argument forwarding.
  */
-export function registerRuntimeLaunchers(program: Command, handler: RuntimeLaunchHandler): void {
+export function registerRuntimeLaunchers(
+  program: Command,
+  handler: RuntimeLaunchHandler,
+  claudexHandler: ClaudexLaunchHandler = (extraArgs, yolo) =>
+    launchClaudexProduction(extraArgs, yolo),
+): void {
   for (const runtime of ['claude', 'codex', 'opencode', 'pi'] as const) {
     program
       .command(runtime)
@@ -1051,16 +1088,37 @@ export function registerRuntimeLaunchers(program: Command, handler: RuntimeLaunc
       });
   }
 
+  // claudex — EXPERIMENTAL: GPT models inside the Claude Code harness via
+  // claude-code-proxy (ChatGPT-subscription OAuth). Isolated CLAUDE_CONFIG_DIR
+  // + zero-token-leak env injection live in claudex.ts.
+  program
+    .command('claudex')
+    .description('EXPERIMENTAL: launch Claude Code harness against GPT via claude-code-proxy')
+    .allowUnknownOption(true)
+    .allowExcessArguments(true)
+    .action((_opts: unknown, cmd: Command) => {
+      claudexHandler(cmd.args, false);
+    });
+
   program
     .command('yolo <runtime>')
-    .description('Launch a runtime in dangerous-permissions mode (claude|codex|opencode|pi)')
+    .description(
+      'Launch a runtime in dangerous-permissions mode (claude|codex|opencode|pi|claudex)',
+    )
     .allowUnknownOption(true)
     .allowExcessArguments(true)
     .action((runtime: string, _opts: unknown, cmd: Command) => {
+      // claudex is an EXPERIMENTAL overlay, not a RuntimeName — dispatch it
+      // before the runtime allowlist check. Slice off the positional runtime
+      // name for the same reason as below (#454).
+      if (runtime === 'claudex') {
+        claudexHandler(cmd.args.slice(1), true);
+        return;
+      }
       const valid: RuntimeName[] = ['claude', 'codex', 'opencode', 'pi'];
       if (!valid.includes(runtime as RuntimeName)) {
         console.error(
-          `[mosaic] ERROR: Unsupported yolo runtime '${runtime}'. Use: ${valid.join('|')}`,
+          `[mosaic] ERROR: Unsupported yolo runtime '${runtime}'. Use: ${valid.join('|')}|claudex`,
         );
         process.exit(1);
       }