pennyrouter 0.1.21 → 0.2.1

package/README.md

@@ -10,7 +10,7 @@ status checks, and uninstall metadata.
 
 ```bash
 npx pennyrouter install
-npx pennyrouter install --existing-account
+npx pennyrouter install --make-default
 npx pennyrouter auth anthropic
 npx pennyrouter install --harness claude-code,cline,opencode,codex,windsurf,zed,codegpt,aider
 npx pennyrouter disable
@@ -19,6 +19,9 @@ npx pennyrouter uninstall
 npx pennyrouter status
 ```
 
+Installation opens a browser and requires login to the PennyRouter account that should own
+the new machine key. CLI installs no longer create anonymous ghost accounts.
+
 With no `--harness` flag, the interactive installer shows a checkbox list. Tools with
 detected configs start checked; press Enter to accept or type tool IDs to toggle them.
 
@@ -26,6 +29,33 @@ When Claude Code is selected, the installer also offers an optional Claude Pro/M
 subscription-auth step. Users can skip it during install and enable it later with
 `@penny auth` or `npx pennyrouter auth anthropic`.
 
+## Explicit Penny Commands
+
+On macOS and Linux, a normal install adds a small `penny` launcher under `~/.local/bin`:
+
+```bash
+penny claude
+penny codex
+```
+
+Arguments are passed through to the native harness, so commands such as `penny claude --resume`
+and `penny codex resume --last` work normally. By default, bare `claude` and `codex` remain
+completely native; their normal configuration files are not redirected. Choose the installer's
+"make PennyRouter the default" option, or pass `--make-default`, to retain the original global
+routing behavior.
+
+Existing PennyRouter installs preserve their current bare-command behavior during upgrade unless
+the user explicitly changes it. Close running Claude Code or Codex sessions only when adding or
+removing global bare-command routing. A Penny-only install does not require closing native sessions.
+
+The launcher uses a private config at `~/.config/pennyrouter/config.json`, a Claude settings overlay,
+and a secret-free Codex profile. The installer adds one marked PATH block to zsh or bash startup
+files when needed; `--no-path-update` skips that edit.
+
+In Claude Code sessions launched with `penny claude`, `/penny help` is an alias for the existing
+`@penny help` syntax. Both forms remain supported. Codex continues to use `@penny` because Codex
+does not currently expose equivalent project-independent custom slash commands.
+
 When Codex is already signed in with ChatGPT, the installer preserves that Codex-managed
 login and configures PennyRouter as an OpenAI-authenticated Responses proxy. Codex continues
 to own and refresh the OpenAI credentials; PennyRouter stores only its existing `pr-` account
@@ -40,6 +70,12 @@ npx pennyrouter@latest install --harness codex --local
 Restart Codex after installation. Without `--local`, browser authorization supplies the normal
 hosted gateway URL.
 
+Before configuring Claude Code, the installer sends a small compatibility request exercising the
+modern beta/context-management request shape. If that check fails, Claude routing is not enabled;
+the gateway must be redeployed or fixed before retrying. This check is about PennyRouter's gateway
+compatibility, not a demand that the user upgrade a Claude Code version that already emits a
+supported request shape.
+
 ## Supported Tools
 
 - Claude Code
@@ -124,8 +160,9 @@ directly.
 
 ## What It Changes
 
-The CLI writes only selected local tool configuration files, saves backups under the local
-PennyRouter state directory, and records an uninstall manifest.
+The CLI installs its managed launcher under `~/.local`, writes only selected local tool
+configuration or per-command overlay files, saves backups under the local PennyRouter state
+directory, and records an uninstall manifest.
 
 `disable` temporarily removes PennyRouter from selected tools while retaining a local
 PennyRouter-managed snapshot for `enable`.

package/bin/penny.js

@@ -0,0 +1,9 @@
+#!/usr/bin/env node
+import { runPenny } from "../src/launch.js";
+
+runPenny().then((code) => {
+  process.exitCode = code;
+}).catch((error) => {
+  console.error(error?.message || String(error));
+  process.exitCode = 1;
+});

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "pennyrouter",
-  "version": "0.1.21",
+  "version": "0.2.1",
   "description": "Install and manage PennyRouter local coding-agent integrations.",
   "homepage": "https://pennyrouter.com",
   "bugs": {
@@ -24,7 +24,7 @@
   ],
   "scripts": {
     "start": "node ./bin/pennyrouter.js",
-    "check": "node --check ./bin/pennyrouter.js && find src -name '*.js' -print0 | xargs -0 -n1 node --check && node src/session.test.js && node src/statusline.test.js && node src/harnesses/claude-code.test.js && node src/harnesses/codex.test.js"
+    "check": "node --check ./bin/pennyrouter.js && node --check ./bin/penny.js && find src -name '*.js' -print0 | xargs -0 -n1 node --check && node src/session.test.js && node src/statusline.test.js && node src/harnesses/claude-code.test.js && node src/harnesses/codex.test.js && node src/launch.test.js"
   },
   "license": "MIT"
 }

package/src/cli.js

@@ -4,13 +4,14 @@ import { createInterface } from "node:readline/promises";
 import { stdin as input, stdout as output } from "node:process";
 import { aiderHarness } from "./harnesses/aider.js";
 import {
+  CLAUDE_CODE_MODELS,
   claudeCodeHarness,
   readClaudeCodeGatewayAuth,
   readClaudeCodePennyRouterKey,
 } from "./harnesses/claude-code.js";
 import { clineHarness } from "./harnesses/cline.js";
 import { codeGptHarness } from "./harnesses/codegpt.js";
-import { codexHarness } from "./harnesses/codex.js";
+import { codexHarness, detectCodexChatgptAuth } from "./harnesses/codex.js";
 import { opencodeHarness } from "./harnesses/opencode.js";
 import { windsurfHarness } from "./harnesses/windsurf.js";
 import { zedHarness } from "./harnesses/zed.js";
@@ -32,6 +33,19 @@ import {
   saveManifest,
   statePath,
 } from "./state.js";
+import {
+  claudeLaunchSettingsPath,
+  codexLaunchProfilePath,
+  configurePennyHarness,
+  hasConfiguredPennyHarnesses,
+  installPennyRuntime,
+  loadPennyConfig,
+  pennyConfigPath,
+  removePennyHarness,
+  removePennyRuntime,
+  savePennyConfig,
+  setPennyHarnessEnabled,
+} from "./launch.js";
 
 const HARNESS_BY_ID = {
   "claude-code": claudeCodeHarness,
@@ -100,6 +114,10 @@ function parseArgs(argv) {
     else if (arg === "--all") flags.all = true;
     else if (arg === "--dry-run") flags.dryRun = true;
     else if (arg === "--allow-running-claude") flags.allowRunningClaude = true;
+    else if (arg === "--allow-running-harnesses") flags.allowRunningHarnesses = true;
+    else if (arg === "--make-default") flags.makeDefault = true;
+    else if (arg === "--penny-only") flags.pennyOnly = true;
+    else if (arg === "--no-path-update") flags.noPathUpdate = true;
     else if (arg === "--no-browser") flags.noBrowser = true;
     else if (arg === "--existing-account") flags.existingAccount = true;
     else if (arg === "--anthropic-auth") flags.anthropicAuth = true;
@@ -138,7 +156,8 @@ async function authProvider(flags) {
   }
 
   if (flags.forget) {
-    const pennyKey = flags.pennyKey || await readClaudeCodePennyRouterKey();
+    const launchConfig = await loadPennyConfig();
+    const pennyKey = flags.pennyKey || launchConfig.api_key || await readClaudeCodePennyRouterKey();
     if (!pennyKey) {
       throw new Error(
         "No PennyRouter key found in Claude Code settings. Pass `--penny-key pr-...`.",
@@ -167,6 +186,10 @@ async function authProvider(flags) {
     if (updated) {
       await saveManifest(manifest);
     }
+    if (launchConfig.harnesses?.claude) {
+      launchConfig.harnesses.claude.subscription_auth = false;
+      await savePennyConfig(launchConfig);
+    }
     return;
   }
 
@@ -176,24 +199,8 @@ async function authProvider(flags) {
     return;
   }
 
-  // Claude Code's env settings are user-global and may be reloaded by already-open
-  // processes. Switching the base URL underneath an in-flight agent can transplant a
-  // multi-hundred-thousand-token tool loop into PennyRouter without a fresh human action.
-  // Make that blast radius opt-in instead of surprising every new installer.
-  if (selected.some((harness) => harness.id === "claude-code")
-      && !flags.allowRunningClaude) {
-    const running = runningClaudeCodeProcesses();
-    if (running.length > 0) {
-      throw new Error(
-        "Claude Code is currently running. Close all Claude Code sessions, then run install again. "
-        + "PennyRouter changes Claude's user-global API routing, so continuing could redirect "
-        + "an open session's full transcript. If you intentionally accept that risk, pass "
-        + "--allow-running-claude.\nDetected:\n  " + running.slice(0, 5).join("\n  "),
-      );
-    }
-  }
-
-  const pennyKey = flags.pennyKey || await readClaudeCodePennyRouterKey();
+  const launchConfig = await loadPennyConfig();
+  const pennyKey = flags.pennyKey || launchConfig.api_key || await readClaudeCodePennyRouterKey();
   if (!pennyKey) {
     throw new Error(
       "No PennyRouter key found in Claude Code settings. Run `pennyrouter install --harness claude-code` first, or pass `--penny-key pr-...`.",
@@ -209,29 +216,58 @@ async function authProvider(flags) {
   }
 
   const gatewayBaseUrl = flags.gatewayBaseUrl || process.env.PENNYROUTER_GATEWAY_BASE_URL || "https://api.pennyrouter.com";
-  // Store the token encrypted server-side, then write a pr-key-only config.
-  await storeAnthropicToken({ gatewayBaseUrl, apiKey: pennyKey, token });
   const manifest = await loadManifest();
   const existingRecord = (manifest.installations || []).find(
     (candidate) => candidate.harness === "claude-code",
   );
-  const plan = await claudeCodeHarness.planInstall();
-  const record = await claudeCodeHarness.installStoredToken({
-    apiKey: pennyKey, gatewayBaseUrl, plan, existingRecord,
+  const ownsGlobalRouting = existingRecord
+    ? existingRecord.default_routing !== false
+    : Boolean(await readClaudeCodePennyRouterKey());
+  if (ownsGlobalRouting) assertNoRunningHarness("claude-code", flags);
+  await storeAnthropicToken({ gatewayBaseUrl, apiKey: pennyKey, token });
+  await probeClaudeCodeGateway({ gatewayBaseUrl, apiKey: pennyKey });
+  if (process.platform !== "win32") {
+    await installPennyRuntime({ updatePath: !flags.noPathUpdate });
+  }
+  await configurePennyHarness("claude-code", {
+    apiKey: pennyKey,
+    gatewayBaseUrl,
+    subscriptionAuth: true,
+    models: CLAUDE_CODE_MODELS,
   });
+  let record = existingRecord || {
+    harness: "claude-code",
+    config_path: compactHome((await claudeCodeHarness.planInstall()).configPath),
+    installed_at: new Date().toISOString(),
+    launch_available: true,
+    launch_config_path: compactHome(claudeLaunchSettingsPath()),
+    default_routing: ownsGlobalRouting,
+  };
+  if (ownsGlobalRouting) {
+    const plan = await claudeCodeHarness.planInstall();
+    record = {
+      ...record,
+      ...(await claudeCodeHarness.installStoredToken({
+        apiKey: pennyKey, gatewayBaseUrl, plan, existingRecord,
+      })),
+    };
+  }
 
   upsertManifestRecord(manifest, {
     ...record,
+    launch_available: true,
+    launch_config_path: compactHome(claudeLaunchSettingsPath()),
+    default_routing: ownsGlobalRouting,
     anthropic_oauth: true,
     anthropic_token_stored: true,
     token_source: tokenResult.source,
   });
   await saveManifest(manifest);
 
-  console.log("Configured Claude Code for PennyRouter + your Claude subscription.");
+  console.log("Configured `penny claude` for PennyRouter + your Claude subscription.");
   console.log("Your Claude token is stored encrypted; Claude Code holds only your PennyRouter key.");
   console.log("If Claude auth expires, refresh the token source and run `pennyrouter auth anthropic` again.");
-  console.log(`Config: ${record.config_path}`);
+  console.log(`Penny config: ${pennyConfigPath()}`);
 }
 
 function readAnthropicOAuthToken(flags = {}) {
@@ -326,6 +362,9 @@ function normalizeAnthropicToken(value) {
 }
 
 async function install(flags) {
+  if (flags.makeDefault && flags.pennyOnly) {
+    throw new Error("--make-default and --penny-only cannot be used together.");
+  }
   const selected = await selectHarnesses(flags);
   if (selected.length === 0) {
     console.log("No supported harnesses selected.");
@@ -335,9 +374,17 @@ async function install(flags) {
   console.log("PennyRouter install");
   console.log("");
 
+  const manifest = await loadManifest();
+
   if (flags.dryRun) {
+    const defaultRouting = await chooseDefaultRouting(flags, selected, manifest);
     for (const harness of selected) {
-      console.log(`Will install on ${harness.name}${installNoteForHarness(harness.id)}.`);
+      const explicit = ["claude-code", "codex"].includes(harness.id) && process.platform !== "win32";
+      const command = harness.id === "claude-code" ? "penny claude" : "penny codex";
+      console.log(`Will install on ${harness.name}${explicit ? ` via ${command}` : installNoteForHarness(harness.id)}.`);
+      if (defaultRouting.get(harness.id)) {
+        console.log(`Will also route bare ${harness.id === "claude-code" ? "claude" : harness.id} through PennyRouter.`);
+      }
     }
     if (flags.gatewayBaseUrl) console.log(`Serving gateway: ${flags.gatewayBaseUrl}`);
     if (selected.some((harness) => harness.id === "claude-code")) {
@@ -350,14 +397,10 @@ async function install(flags) {
   const session = await createCliSession({
     appUrl: flags.appUrl || APP_URL,
     harnesses: selected.map((harness) => harness.id),
-    accountMode: flags.existingAccount ? "existing" : "seed",
+    accountMode: "existing",
   });
 
-  console.log(
-    flags.existingAccount
-      ? "Opening your browser to authorize this machine with your existing PennyRouter account..."
-      : "Opening your browser to authorize this machine...",
-  );
+  console.log("Opening your browser to log in and authorize this machine with your PennyRouter account...");
   console.log(`If your browser did not open, visit:\n${session.authorize_url}`);
   if (!flags.noBrowser) openBrowser(session.authorize_url);
   console.log("");
@@ -368,49 +411,98 @@ async function install(flags) {
   console.log("");
 
   const claudeAnthropicAuth = await maybeConfigureClaudeAnthropicAuth(flags, selected);
+  const gatewayBaseUrl = flags.gatewayBaseUrl || claim.gateway_base_url;
+
+  if (selected.some((harness) => harness.id === "claude-code")) {
+    if (claudeAnthropicAuth) {
+      await storeAnthropicToken({
+        gatewayBaseUrl,
+        apiKey: claim.api_key,
+        token: claudeAnthropicAuth.token,
+      });
+    }
+    console.log("Verifying modern Claude Code compatibility before changing local settings...");
+    await probeClaudeCodeGateway({ gatewayBaseUrl, apiKey: claim.api_key });
+    console.log("");
+  }
+
+  // Keep this as the final interactive choice: users first authorize their account,
+  // optionally connect their subscription, and pass compatibility checks. Then they
+  // choose the visible command behavior with all relevant context in front of them.
+  const defaultRouting = await chooseDefaultRouting(flags, selected, manifest);
+
+  const launchable = selected.filter((harness) => ["claude-code", "codex"].includes(harness.id));
+  let runtimeResult = null;
+  if (launchable.length > 0 && process.platform !== "win32") {
+    runtimeResult = await installPennyRuntime({ updatePath: !flags.noPathUpdate });
+  }
 
-  const manifest = await loadManifest();
   const records = [];
   const failures = [];
   for (const harness of selected) {
     await runHarnessJob(failures, harness.id, "install", async () => {
       const plan = await harness.planInstall();
-      const gatewayBaseUrl = flags.gatewayBaseUrl || claim.gateway_base_url;
       const existingRecord = (manifest.installations || []).find(
         (candidate) => candidate.harness === harness.id,
       );
-      let record;
-      if (harness.id === "claude-code" && claudeAnthropicAuth) {
-        // Store the Claude setup-token encrypted server-side, then write a config
-        // that carries ONLY the pr- key. Nothing Anthropic-flavored on disk, and no
-        // dual-credential warnings from Claude Code.
-        await storeAnthropicToken({
-          gatewayBaseUrl,
+      const supportsPennyCommand = ["claude-code", "codex"].includes(harness.id)
+        && process.platform !== "win32";
+      const makeDefault = defaultRouting.get(harness.id) ?? true;
+      const hadGlobalRouting = Boolean(existingRecord && existingRecord.default_routing !== false);
+      if (["claude-code", "codex"].includes(harness.id) && (makeDefault || hadGlobalRouting)) {
+        assertNoRunningHarness(harness.id, flags);
+      }
+
+      const codexSubscriptionAuth = harness.id === "codex"
+        ? await detectCodexChatgptAuth()
+        : false;
+      const claudeSubscriptionAuth = harness.id === "claude-code"
+        && Boolean(claudeAnthropicAuth || existingRecord?.anthropic_token_stored);
+
+      if (supportsPennyCommand) {
+        await configurePennyHarness(harness.id, {
           apiKey: claim.api_key,
-          token: claudeAnthropicAuth.token,
-        });
-        console.log("Verifying modern Claude Code compatibility before changing global settings...");
-        await probeClaudeCodeGateway({ gatewayBaseUrl, apiKey: claim.api_key });
-        record = await harness.installStoredToken({
-          apiKey: claim.api_key, gatewayBaseUrl, plan, existingRecord,
+          gatewayBaseUrl,
+          subscriptionAuth: harness.id === "claude-code"
+            ? claudeSubscriptionAuth
+            : codexSubscriptionAuth,
+          models: harness.id === "claude-code" ? CLAUDE_CODE_MODELS : null,
         });
-        record.anthropic_oauth = true;
-        record.anthropic_token_stored = true;
-        record.token_source = claudeAnthropicAuth.source;
+      }
+
+      let record;
+      if (!supportsPennyCommand || makeDefault) {
+        record = harness.id === "claude-code" && claudeSubscriptionAuth
+          ? await harness.installStoredToken({
+              apiKey: claim.api_key, gatewayBaseUrl, plan, existingRecord,
+            })
+          : await harness.install({
+              apiKey: claim.api_key, gatewayBaseUrl, plan, existingRecord,
+            });
       } else {
-        if (harness.id === "claude-code") {
-          console.log("Verifying modern Claude Code compatibility before changing global settings...");
-          await probeClaudeCodeGateway({ gatewayBaseUrl, apiKey: claim.api_key });
+        if (hadGlobalRouting) {
+          await harness.uninstall(existingRecord);
         }
-        record = await harness.install({
-          apiKey: claim.api_key,
-          // An explicit --local / --gateway-base-url overrides the URL the server hands back
-          // (which points at prod) — so a --local install serves through the local gateway.
-          gatewayBaseUrl,
-          plan,
-          existingRecord,
-        });
+        record = {
+          harness: harness.id,
+          config_path: compactHome(plan.configPath),
+          backup_path: existingRecord?.backup_path || null,
+          installed_at: new Date().toISOString(),
+        };
+      }
+      if (supportsPennyCommand) {
+        record.launch_available = true;
+        record.launch_config_path = compactHome(
+          harness.id === "claude-code" ? claudeLaunchSettingsPath() : codexLaunchProfilePath(),
+        );
+        record.default_routing = Boolean(makeDefault);
+      }
+      if (harness.id === "claude-code" && claudeSubscriptionAuth) {
+        record.anthropic_oauth = true;
+        record.anthropic_token_stored = true;
+        record.token_source = claudeAnthropicAuth?.source || existingRecord?.token_source || "stored";
       }
+      if (harness.id === "codex") record.openai_subscription_auth = codexSubscriptionAuth;
       records.push(record);
       upsertManifestRecord(manifest, record);
       await saveManifest(manifest);
@@ -419,15 +511,92 @@ async function install(flags) {
 
   await saveManifest(manifest);
   console.log("");
-  console.log("Installed PennyRouter.");
+  console.log(records.length > 0
+    ? "PennyRouter installation complete."
+    : "PennyRouter was not installed on any selected tool.");
+  console.log(`Manifest: ${statePath("installations.json")}`);
   for (const record of records) {
     const harness = HARNESS_BY_ID[record.harness];
-    console.log(`Installed on ${harness?.name || record.harness}${installNoteForRecord(record)}.`);
+    if (record.launch_available) {
+      const command = record.harness === "claude-code" ? "penny claude" : "penny codex";
+      const native = record.harness === "claude-code" ? "claude" : "codex";
+      const harnessName = record.harness === "claude-code" ? "Claude Code" : "Codex";
+      const commandWidth = Math.max(command.length, native.length) + 2;
+      console.log("");
+      console.log(color(`How to Run ${harnessName}`, "bold"));
+      console.log("");
+      console.log(`  ${color(command.padEnd(commandWidth), "bold")}→ ${harnessName} with PennyRouter`);
+      console.log(`  ${color(native.padEnd(commandWidth), "bold")}→ ${record.default_routing ? `${harnessName} with PennyRouter (default routing enabled)` : `${harnessName} native`}`);
+    } else {
+      console.log(`Installed on ${harness?.name || record.harness}${installNoteForRecord(record)}.`);
+    }
   }
-  console.log(`Manifest: ${statePath("installations.json")}`);
+  if (runtimeResult && !runtimeResult.available) {
+    console.log("Add ~/.local/bin to PATH before using the `penny` command.");
+  } else if (runtimeResult?.changed) {
+    console.log("Open a new terminal (or reload your shell) before using the `penny` command.");
+  }
+  console.log("");
   reportFailures(failures);
 }
 
+async function chooseDefaultRouting(flags, selected, manifest) {
+  const out = new Map();
+  const launchable = selected.filter((harness) => ["claude-code", "codex"].includes(harness.id));
+  if (process.platform === "win32") {
+    for (const harness of launchable) out.set(harness.id, true);
+    return out;
+  }
+  let newInstallChoice = null;
+  for (const harness of launchable) {
+    if (flags.makeDefault) {
+      out.set(harness.id, true);
+      continue;
+    }
+    if (flags.pennyOnly) {
+      out.set(harness.id, false);
+      continue;
+    }
+    const existing = (manifest.installations || []).find((item) => item.harness === harness.id);
+    if (existing) {
+      const currentlyDefault = existing.default_routing !== false;
+      if (flags.dryRun || !currentlyDefault || flags.yes || !input.isTTY || !output.isTTY) {
+        out.set(harness.id, currentlyDefault);
+        continue;
+      }
+      const native = harness.id === "claude-code" ? "claude" : "codex";
+      const change = await confirm(
+        `PennyRouter currently runs when you type ${color(native, "bold")}. Change it to run only with ${color(`penny ${native}`, "bold")}?`,
+      );
+      out.set(harness.id, !change);
+      continue;
+    }
+    if (newInstallChoice === null) {
+      if (flags.dryRun || flags.yes || !input.isTTY || !output.isTTY) {
+        newInstallChoice = false;
+      } else {
+        for (const item of launchable) {
+          const native = item.id === "claude-code" ? "claude" : "codex";
+          const harnessName = item.id === "claude-code" ? "Claude Code" : "Codex";
+          const command = `penny ${native}`;
+          const commandWidth = Math.max(command.length, native.length) + 2;
+          console.log("");
+          console.log(color(`How to Run ${harnessName}`, "bold"));
+          console.log("");
+          console.log(`  ${color(command.padEnd(commandWidth), "bold")}→ ${harnessName} with PennyRouter`);
+          console.log(`  ${color(native.padEnd(commandWidth), "bold")}→ ${harnessName} native (recommended)`);
+        }
+        console.log("");
+        const bare = launchable.map((item) => item.id === "claude-code" ? "claude" : "codex");
+        const label = bare.length === 1 ? bare[0] : `${bare.slice(0, -1).join(", ")} and ${bare.at(-1)}`;
+        newInstallChoice = await confirm(`Also route ${color(label, "bold")} through PennyRouter by default?`);
+      }
+    }
+    out.set(harness.id, newInstallChoice);
+  }
+  return out;
+}
+
 async function maybeConfigureClaudeAnthropicAuth(flags, selected) {
   if (!selected.some((harness) => harness.id === "claude-code")) return null;
   if (flags.noAnthropicAuth) return null;
@@ -526,13 +695,17 @@ async function disable(flags) {
     }
 
     await runHarnessJob(failures, record.harness, "disable", async () => {
-      if (record.config_path) {
+      const ownsGlobalRouting = !record.launch_available || record.default_routing;
+      if (record.config_path && ownsGlobalRouting) {
         const snapshotPath = await backupFile(record.config_path, `${record.harness}-disabled`);
         record.disabled_snapshot_path = snapshotPath;
       }
 
-      if (typeof harness.disable === "function") await harness.disable(record);
-      else await harness.uninstall(record);
+      if (record.launch_available) await setPennyHarnessEnabled(record.harness, false);
+      if (ownsGlobalRouting) {
+        if (typeof harness.disable === "function") await harness.disable(record);
+        else await harness.uninstall(record);
+      }
 
       record.disabled = true;
       record.disabled_at = new Date().toISOString();
@@ -584,13 +757,17 @@ async function enable(flags) {
     }
 
     await runHarnessJob(failures, record.harness, "enable", async () => {
-      if (typeof harness.enable === "function") await harness.enable(record);
-      else if (record.config_path && record.disabled_snapshot_path) {
-        await restoreFile(record.disabled_snapshot_path, record.config_path);
-      } else if (record.manual_required) {
-        console.log(`${record.harness}: re-enable manually in the tool UI using the status details.`);
-      } else {
-        throw new Error("no disabled snapshot found; run install again");
+      const ownsGlobalRouting = !record.launch_available || record.default_routing;
+      if (record.launch_available) await setPennyHarnessEnabled(record.harness, true);
+      if (ownsGlobalRouting) {
+        if (typeof harness.enable === "function") await harness.enable(record);
+        else if (record.config_path && record.disabled_snapshot_path) {
+          await restoreFile(record.disabled_snapshot_path, record.config_path);
+        } else if (record.manual_required) {
+          console.log(`${record.harness}: re-enable manually in the tool UI using the status details.`);
+        } else {
+          throw new Error("no disabled snapshot found; run install again");
+        }
       }
 
       delete record.disabled;
@@ -650,7 +827,8 @@ async function uninstall(flags) {
       } else if (record.anthropic_token_stored) {
         anthropicTokenNotice = true;
       }
-      await harness.uninstall(record);
+      if (record.launch_available) await removePennyHarness(record.harness);
+      if (!record.launch_available || record.default_routing) await harness.uninstall(record);
       console.log(`Removed ${record.harness}.`);
     });
     if (!ok) kept.push(record);
@@ -669,7 +847,8 @@ async function uninstall(flags) {
       } else if (record.anthropic_token_stored) {
         anthropicTokenNotice = true;
       }
-      await harness.uninstall(record);
+      if (record.launch_available) await removePennyHarness(record.harness);
+      if (!record.launch_available || record.default_routing) await harness.uninstall(record);
       console.log(`Removed ${record.harness}.`);
     });
   }
@@ -682,6 +861,7 @@ async function uninstall(flags) {
 
   manifest.installations = kept;
   await saveManifest(manifest);
+  if (!(await hasConfiguredPennyHarnesses())) await removePennyRuntime();
   reportFailures(failures);
 }
 
@@ -754,6 +934,11 @@ async function status() {
     if (record.disabled_at) console.log(`  disabled: ${record.disabled_at}`);
     if (record.anthropic_oauth) console.log(`  Claude subscription auth: enabled (${record.token_source || "unknown"} token)`);
     if (record.openai_subscription_auth) console.log("  OpenAI subscription auth: enabled (Codex-managed login)");
+    if (record.launch_available) {
+      const command = record.harness === "claude-code" ? "penny claude" : "penny codex";
+      console.log(`  command: ${command}`);
+      console.log(`  bare command: ${record.default_routing ? "PennyRouter" : "native"}`);
+    }
     if (record.manual_required) console.log("  note: finish or remove this integration in the tool UI");
   }
 }
@@ -994,7 +1179,10 @@ function formatError(error) {
 async function forgetStoredAnthropicToken(record) {
   if (record.harness !== "claude-code" || !record.anthropic_token_stored) return;
   try {
-    const { gatewayBaseUrl, apiKey } = await readClaudeCodeGatewayAuth();
+    const launchConfig = await loadPennyConfig();
+    const globalAuth = await readClaudeCodeGatewayAuth();
+    const gatewayBaseUrl = launchConfig.gateway_base_url || globalAuth.gatewayBaseUrl;
+    const apiKey = launchConfig.api_key || globalAuth.apiKey;
     if (!gatewayBaseUrl || !apiKey) return;
     await forgetAnthropicToken({ gatewayBaseUrl, apiKey });
   } catch {
@@ -1098,11 +1286,37 @@ function runningClaudeCodeProcesses() {
     .filter((line) => /(^|[\/\s])claude(?:\s|$)/.test(line));
 }
 
+function runningCodexProcesses() {
+  if (process.platform === "win32") return [];
+  const result = spawnSync("ps", ["-ax", "-o", "pid=,command="], { encoding: "utf8" });
+  if (result.status !== 0) return [];
+  return String(result.stdout || "").split(/\r?\n/)
+    .map((line) => line.trim())
+    .filter((line) => /(^|[\/\s])codex(?:\s|$)/.test(line));
+}
+
+function assertNoRunningHarness(harnessId, flags) {
+  if (flags.allowRunningHarnesses || (harnessId === "claude-code" && flags.allowRunningClaude)) {
+    return;
+  }
+  const running = harnessId === "claude-code"
+    ? runningClaudeCodeProcesses()
+    : runningCodexProcesses();
+  if (running.length === 0) return;
+  const name = harnessId === "claude-code" ? "Claude Code" : "Codex";
+  throw new Error(
+    `${name} is currently running. Close all ${name} sessions before changing its global routing. `
+    + "Installing only the explicit `penny` command does not require this. If you intentionally "
+    + "accept the risk, pass --allow-running-harnesses.\nDetected:\n  "
+    + running.slice(0, 5).join("\n  "),
+  );
+}
+
 function printHelp() {
   console.log(`PennyRouter CLI
 
 Usage:
-  pennyrouter install [--harness ${SUPPORTED_HARNESS_IDS}] [--all] [--yes] [--dry-run] [--existing-account] [--anthropic-auth|--no-anthropic-auth] [--local[=URL]] [--allow-running-claude]
+  pennyrouter install [--harness ${SUPPORTED_HARNESS_IDS}] [--all] [--yes] [--dry-run] [--make-default|--penny-only] [--no-path-update] [--anthropic-auth|--no-anthropic-auth] [--local[=URL]] [--allow-running-harnesses]
   pennyrouter auth anthropic [--penny-key pr-...] [--token oauth-token] [--token-command CMD] [--gateway-base-url URL] [--forget]
   pennyrouter disable [--harness ${SUPPORTED_HARNESS_IDS}] [--all] [--yes]
   pennyrouter enable [--harness ${SUPPORTED_HARNESS_IDS}] [--all] [--yes]
@@ -1111,7 +1325,8 @@ Usage:
 
 Examples:
   npx pennyrouter install
-  npx pennyrouter install --existing-account
+  npx pennyrouter install --make-default
+  npx pennyrouter install --penny-only
   npx pennyrouter install --harness claude-code --anthropic-auth --token <token>
   npx pennyrouter auth anthropic
   npx pennyrouter install --all

package/src/harnesses/claude-code.js

@@ -13,7 +13,7 @@ const CONNECTOR_SETTING = "disableClaudeAiConnectors";
 // pinned to Fable; the DYNAMIC "Penny Custom" option lets PennyRouter cost-route. Legacy
 // "Penny Speed/Core/Power"
 // installs (dynamic bundles) are still recognized for uninstall (see isPennyRouterModelValue).
-const CLAUDE_CODE_MODELS = {
+export const CLAUDE_CODE_MODELS = {
   haiku: "Penny Haiku",     // -> pinned anthropic/claude-haiku-4-5-20251001
   sonnet: "Penny Sonnet",   // -> pinned anthropic/claude-sonnet-4-6
   opus: "Penny Opus",       // -> pinned anthropic/claude-opus-4-8

package/src/harnesses/codex.js

@@ -27,10 +27,11 @@ export const codexHarness = {
     };
   },
 
-  async install({ apiKey, gatewayBaseUrl, plan }) {
+  async install({ apiKey, gatewayBaseUrl, plan, existingRecord }) {
     const current = await readText(CONFIG_PATH, "");
     const subscriptionAuth = await detectCodexChatgptAuth();
-    const previousModelProvider = rootAssignment(removeManagedCodexConfig(current), "model_provider");
+    const previousModelProvider = existingRecord?.previous_model_provider
+      || rootAssignment(removeManagedCodexConfig(current), "model_provider");
     const backupPath = await backupFile(CONFIG_PATH, "codex");
     const next = renderCodexConfig(current, {
       apiKey,
@@ -75,7 +76,7 @@ export function codexUsesChatgptAuth(auth) {
   return Boolean(auth.tokens && typeof auth.tokens === "object" && auth.tokens.account_id);
 }
 
-async function detectCodexChatgptAuth() {
+export async function detectCodexChatgptAuth() {
   const auth = await readJsonFile(AUTH_PATH, null);
   if (codexUsesChatgptAuth(auth)) return true;
   // auth.json may be absent when Codex uses the OS keyring. `codex login status` reports

package/src/harnesses/codex.test.js

@@ -1,6 +1,10 @@
 import assert from "node:assert/strict";
+import fs from "node:fs";
+import os from "node:os";
+import path from "node:path";
 
 import {
+  codexHarness,
   codexUsesChatgptAuth,
   removeManagedCodexConfig,
   renderCodexConfig,
@@ -74,9 +78,42 @@ function testUninstallLeavesUserConfig() {
   assert.ok(!removed.includes("pr-test"));
 }
 
+async function testReinstallPreservesRecordedProvider() {
+  const root = fs.mkdtempSync(path.join(os.tmpdir(), "pr-codex-reinstall-"));
+  const previousHome = process.env.HOME;
+  const previousState = process.env.XDG_STATE_HOME;
+  process.env.HOME = root;
+  process.env.XDG_STATE_HOME = path.join(root, ".state");
+  fs.mkdirSync(path.join(root, ".codex"), { recursive: true });
+  fs.writeFileSync(path.join(root, ".codex", "auth.json"), '{"auth_mode":"apikey"}\n');
+  fs.writeFileSync(path.join(root, ".codex", "config.toml"), renderCodexConfig("", {
+    apiKey: "pr-old", gatewayBaseUrl: "https://old.example", subscriptionAuth: false,
+  }));
+  try {
+    const plan = await codexHarness.planInstall();
+    const record = await codexHarness.install({
+      apiKey: "pr-new",
+      gatewayBaseUrl: "https://new.example",
+      plan,
+      existingRecord: { previous_model_provider: 'model_provider = "native"' },
+    });
+    assert.equal(record.previous_model_provider, 'model_provider = "native"');
+    await codexHarness.uninstall(record);
+    assert.ok(fs.readFileSync(path.join(root, ".codex", "config.toml"), "utf8")
+      .includes('model_provider = "native"'));
+  } finally {
+    if (previousHome === undefined) delete process.env.HOME;
+    else process.env.HOME = previousHome;
+    if (previousState === undefined) delete process.env.XDG_STATE_HOME;
+    else process.env.XDG_STATE_HOME = previousState;
+    fs.rmSync(root, { recursive: true, force: true });
+  }
+}
+
 testAuthDetection();
 testSubscriptionProviderIsRootSafe();
 testLegacyMigrationAndIdempotence();
 testProviderCollisionFailsClosed();
 testUninstallLeavesUserConfig();
+await testReinstallPreservesRecordedProvider();
 console.log("codex.test.js: all checks passed");

package/src/launch.js

@@ -0,0 +1,375 @@
+import { spawn } from "node:child_process";
+import {
+  chmod,
+  cp,
+  mkdir,
+  rm,
+  stat,
+  unlink,
+  writeFile,
+} from "node:fs/promises";
+import { constants as osConstants } from "node:os";
+import { fileURLToPath } from "node:url";
+import { basename, dirname, join, resolve } from "node:path";
+
+import { configureClaudeCodeStatusline } from "./statusline.js";
+import { atomicWrite, homeDir, readJsonFile, readText } from "./state.js";
+
+const CONFIG_VERSION = 1;
+const PATH_START = "# >>> pennyrouter PATH >>>";
+const PATH_END = "# <<< pennyrouter PATH <<<";
+const CODEX_PROFILE_MARKER = "# PennyRouter per-command profile (managed; no secrets)";
+const CLAUDE_COMMAND_MARKER = "<!-- PennyRouter managed Claude command -->";
+
+export function pennyConfigDir() {
+  return join(process.env.XDG_CONFIG_HOME || join(homeDir(), ".config"), "pennyrouter");
+}
+
+export function pennyConfigPath() {
+  return join(pennyConfigDir(), "config.json");
+}
+
+export function pennyDataDir() {
+  return join(process.env.XDG_DATA_HOME || join(homeDir(), ".local", "share"), "pennyrouter");
+}
+
+export function pennyRuntimeDir() {
+  return join(pennyDataDir(), "runtime");
+}
+
+export function pennyBinDir() {
+  return join(homeDir(), ".local", "bin");
+}
+
+export function pennyShimPath() {
+  return join(pennyBinDir(), "penny");
+}
+
+export function claudeLaunchSettingsPath() {
+  return join(pennyConfigDir(), "claude-settings.json");
+}
+
+export function codexLaunchProfilePath() {
+  const codexHome = process.env.CODEX_HOME || join(homeDir(), ".codex");
+  return join(codexHome, "pennyrouter.config.toml");
+}
+
+export function claudeUserCommandPath() {
+  return join(homeDir(), ".claude", "commands", "penny.md");
+}
+
+async function privateWrite(path, text) {
+  await mkdir(dirname(path), { recursive: true, mode: 0o700 });
+  await atomicWrite(path, text);
+  await chmod(path, 0o600);
+}
+
+export async function loadPennyConfig() {
+  return (await readJsonFile(pennyConfigPath(), null)) || {
+    version: CONFIG_VERSION,
+    harnesses: {},
+  };
+}
+
+export async function savePennyConfig(config) {
+  const next = { version: CONFIG_VERSION, ...config };
+  await privateWrite(pennyConfigPath(), `${JSON.stringify(next, null, 2)}\n`);
+  return next;
+}
+
+function packageRoot() {
+  return resolve(dirname(fileURLToPath(import.meta.url)), "..");
+}
+
+async function copyRuntime() {
+  const source = packageRoot();
+  const destination = pennyRuntimeDir();
+  await mkdir(destination, { recursive: true, mode: 0o700 });
+  for (const entry of ["bin", "src"]) {
+    // Runtime upgrades must not merge with the previous package. In particular,
+    // 0.2.1 moved /penny from a skill to a command; leaving the old skill behind
+    // makes Claude discover two incompatible definitions.
+    await rm(join(destination, entry), { recursive: true, force: true });
+    await cp(join(source, entry), join(destination, entry), {
+      recursive: true,
+      force: true,
+    });
+  }
+  // Remove plugin assets used by 0.2.0/0.2.1. /penny is now a managed personal
+  // command so it can use the exact unnamespaced name in every Claude session.
+  await rm(join(destination, "claude-plugin"), { recursive: true, force: true });
+  await cp(join(source, "package.json"), join(destination, "package.json"), { force: true });
+}
+
+async function writeShim() {
+  await mkdir(pennyBinDir(), { recursive: true, mode: 0o755 });
+  const entry = join(pennyRuntimeDir(), "bin", "penny.js").replaceAll('"', '\\"');
+  await writeFile(pennyShimPath(), `#!/bin/sh\nexec node "${entry}" "$@"\n`, {
+    encoding: "utf8",
+    mode: 0o755,
+  });
+  await chmod(pennyShimPath(), 0o755);
+}
+
+function pathContains(dir) {
+  return String(process.env.PATH || "").split(":").some((candidate) => resolve(candidate) === resolve(dir));
+}
+
+function shellRcPath() {
+  const shell = basename(process.env.SHELL || "");
+  if (shell === "zsh") return join(homeDir(), ".zshrc");
+  if (shell === "bash") return join(homeDir(), ".bashrc");
+  return null;
+}
+
+export async function ensurePennyOnPath({ updatePath = true } = {}) {
+  if (pathContains(pennyBinDir())) return { available: true, changed: false, rc_path: null };
+  if (!updatePath) return { available: false, changed: false, rc_path: null };
+  const rcPath = shellRcPath();
+  if (!rcPath) return { available: false, changed: false, rc_path: null };
+  const current = await readText(rcPath, "");
+  if (!current.includes(PATH_START)) {
+    const block = `${PATH_START}\nexport PATH="$HOME/.local/bin:$PATH"\n${PATH_END}`;
+    const prefix = current && !current.endsWith("\n") ? "\n" : "";
+    await atomicWrite(rcPath, `${current}${prefix}${block}\n`);
+  }
+  return { available: true, changed: !current.includes(PATH_START), rc_path: rcPath };
+}
+
+export async function installPennyRuntime({ updatePath = true } = {}) {
+  if (!(["darwin", "linux"].includes(process.platform))) {
+    return { supported: false, available: false, changed: false, rc_path: null };
+  }
+  await copyRuntime();
+  await writeShim();
+  const path = await ensurePennyOnPath({ updatePath });
+  const config = await loadPennyConfig();
+  if (path.rc_path) {
+    config.path_rc = path.rc_path;
+    await savePennyConfig(config);
+  }
+  return { supported: true, ...path, shim_path: pennyShimPath() };
+}
+
+export function renderCodexLaunchProfile({ gatewayBaseUrl, subscriptionAuth }) {
+  const authLines = subscriptionAuth
+    ? [
+        "requires_openai_auth = true",
+        'env_http_headers = { "x-pennyrouter-key" = "PENNYROUTER_API_KEY" }',
+      ]
+    : ['env_key = "PENNYROUTER_API_KEY"'];
+  return [
+    CODEX_PROFILE_MARKER,
+    'model_provider = "pennyrouter"',
+    "",
+    "[model_providers.pennyrouter]",
+    'name = "PennyRouter"',
+    `base_url = ${JSON.stringify(`${String(gatewayBaseUrl).replace(/\/+$/, "")}/v1`)}`,
+    'wire_api = "responses"',
+    "supports_websockets = false",
+    ...authLines,
+    "",
+  ].join("\n");
+}
+
+async function writeClaudeLaunchSettings() {
+  const native = (await readJsonFile(join(homeDir(), ".claude", "settings.json"), null)) || {};
+  const overlay = { disableClaudeAiConnectors: true };
+  if (native.statusLine) overlay.statusLine = native.statusLine;
+  await configureClaudeCodeStatusline(overlay);
+  await privateWrite(claudeLaunchSettingsPath(), `${JSON.stringify(overlay, null, 2)}\n`);
+}
+
+async function writeClaudeUserCommand() {
+  const path = claudeUserCommandPath();
+  const existing = await readText(path, "");
+  if (existing.trim() && !existing.includes(CLAUDE_COMMAND_MARKER)) {
+    throw new Error(
+      `${path} already exists and is not managed by PennyRouter. Rename it before installing.`,
+    );
+  }
+  await mkdir(dirname(path), { recursive: true });
+  await atomicWrite(path, [
+    "---",
+    "description: PennyRouter commands and help.",
+    "argument-hint: <command and arguments>",
+    "---",
+    CLAUDE_COMMAND_MARKER,
+    "",
+    "@penny $ARGUMENTS",
+    "",
+  ].join("\n"));
+}
+
+async function writeCodexLaunchProfile({ gatewayBaseUrl, subscriptionAuth }) {
+  const path = codexLaunchProfilePath();
+  const existing = await readText(path, "");
+  if (existing.trim() && !existing.startsWith(CODEX_PROFILE_MARKER)) {
+    throw new Error(
+      `${path} already exists and is not managed by PennyRouter. Rename it before installing.`,
+    );
+  }
+  await privateWrite(path, renderCodexLaunchProfile({ gatewayBaseUrl, subscriptionAuth }));
+}
+
+export async function configurePennyHarness(harness, {
+  apiKey,
+  gatewayBaseUrl,
+  subscriptionAuth = false,
+  models = null,
+}) {
+  const config = await loadPennyConfig();
+  config.gateway_base_url = gatewayBaseUrl;
+  config.api_key = apiKey;
+  config.harnesses ||= {};
+  if (harness === "claude-code") {
+    await writeClaudeUserCommand();
+    await writeClaudeLaunchSettings();
+    config.harnesses.claude = {
+      enabled: true,
+      subscription_auth: Boolean(subscriptionAuth),
+      models: models || {},
+    };
+  } else if (harness === "codex") {
+    await writeCodexLaunchProfile({ gatewayBaseUrl, subscriptionAuth });
+    config.harnesses.codex = {
+      enabled: true,
+      subscription_auth: Boolean(subscriptionAuth),
+    };
+  } else {
+    throw new Error(`The penny command does not support ${harness}.`);
+  }
+  await savePennyConfig(config);
+}
+
+export async function setPennyHarnessEnabled(harness, enabled) {
+  const config = await loadPennyConfig();
+  const key = harness === "claude-code" ? "claude" : harness;
+  if (config.harnesses?.[key]) {
+    config.harnesses[key].enabled = Boolean(enabled);
+    await savePennyConfig(config);
+  }
+}
+
+export async function removePennyHarness(harness) {
+  const config = await loadPennyConfig();
+  const key = harness === "claude-code" ? "claude" : harness;
+  if (harness === "claude-code") {
+    await unlink(claudeLaunchSettingsPath()).catch((error) => {
+      if (error.code !== "ENOENT") throw error;
+    });
+    const command = await readText(claudeUserCommandPath(), "");
+    if (command.includes(CLAUDE_COMMAND_MARKER)) {
+      await unlink(claudeUserCommandPath()).catch((error) => {
+        if (error.code !== "ENOENT") throw error;
+      });
+    }
+  } else if (harness === "codex") {
+    const existing = await readText(codexLaunchProfilePath(), "");
+    if (existing.startsWith(CODEX_PROFILE_MARKER)) {
+      await unlink(codexLaunchProfilePath()).catch((error) => {
+        if (error.code !== "ENOENT") throw error;
+      });
+    }
+  }
+  if (config.harnesses) delete config.harnesses[key];
+  await savePennyConfig(config);
+}
+
+export async function hasConfiguredPennyHarnesses() {
+  const config = await loadPennyConfig();
+  return Object.keys(config.harnesses || {}).length > 0;
+}
+
+async function removeManagedPathBlock(rcPath) {
+  if (!rcPath) return;
+  const current = await readText(rcPath, "");
+  if (!current.includes(PATH_START)) return;
+  const escapedStart = PATH_START.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+  const escapedEnd = PATH_END.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+  const next = current
+    .replace(new RegExp(`(?:^|\\n)${escapedStart}\\n[\\s\\S]*?\\n${escapedEnd}\\n?`, "m"), "\n")
+    .replace(/^\n+/, "");
+  await atomicWrite(rcPath, next);
+}
+
+export async function removePennyRuntime() {
+  const config = await loadPennyConfig();
+  await removeManagedPathBlock(config.path_rc);
+  await unlink(pennyShimPath()).catch((error) => {
+    if (error.code !== "ENOENT") throw error;
+  });
+  await rm(pennyRuntimeDir(), { recursive: true, force: true });
+  await unlink(pennyConfigPath()).catch((error) => {
+    if (error.code !== "ENOENT") throw error;
+  });
+}
+
+function assertNoConflictingArgs(harness, args) {
+  if (harness === "claude" && args.some((arg) => arg === "--settings" || arg.startsWith("--settings="))) {
+    throw new Error("penny claude manages --settings; remove that flag or run native claude.");
+  }
+  if (harness === "codex" && args.some((arg) => arg === "--profile" || arg === "-p" || arg.startsWith("--profile="))) {
+    throw new Error("penny codex manages --profile; remove that flag or run native codex.");
+  }
+}
+
+export function buildPennyInvocation(harness, args, config) {
+  const item = config.harnesses?.[harness];
+  if (!item || !item.enabled) {
+    throw new Error(`PennyRouter is not enabled for ${harness}. Run npx pennyrouter install.`);
+  }
+  assertNoConflictingArgs(harness, args);
+  const env = { ...process.env, PENNYROUTER_API_KEY: config.api_key };
+  if (harness === "claude") {
+    const models = item.models || {};
+    env.ANTHROPIC_BASE_URL = config.gateway_base_url;
+    env.ANTHROPIC_AUTH_TOKEN = config.api_key;
+    delete env.ANTHROPIC_API_KEY;
+    if (models.haiku) env.ANTHROPIC_DEFAULT_HAIKU_MODEL = models.haiku;
+    if (models.sonnet) env.ANTHROPIC_DEFAULT_SONNET_MODEL = models.sonnet;
+    if (models.opus) env.ANTHROPIC_DEFAULT_OPUS_MODEL = models.opus;
+    if (models.fable) env.ANTHROPIC_DEFAULT_FABLE_MODEL = models.fable;
+    return {
+      command: "claude",
+      args: ["--settings", claudeLaunchSettingsPath(), ...args],
+      env,
+    };
+  }
+  if (harness === "codex") {
+    return { command: "codex", args: ["--profile", "pennyrouter", ...args], env };
+  }
+  throw new Error(`Unknown Penny harness "${harness}". Try penny claude or penny codex.`);
+}
+
+async function waitForChild(child) {
+  return new Promise((resolvePromise, reject) => {
+    child.once("error", reject);
+    child.once("exit", (code, signal) => resolvePromise({ code, signal }));
+  });
+}
+
+export async function runPenny(argv = process.argv.slice(2)) {
+  const harness = argv[0];
+  if (!harness || harness === "help" || harness === "--help" || harness === "-h") {
+    console.log("Usage: penny <claude|codex> [native arguments...]");
+    return 0;
+  }
+  if (!(["claude", "codex"].includes(harness))) {
+    throw new Error(`Unknown harness "${harness}". Try penny claude or penny codex.`);
+  }
+  const config = await loadPennyConfig();
+  const invocation = buildPennyInvocation(harness, argv.slice(1), config);
+  const child = spawn(invocation.command, invocation.args, {
+    cwd: process.cwd(),
+    env: invocation.env,
+    stdio: "inherit",
+  });
+  const result = await waitForChild(child);
+  if (result.signal) return 128 + (osConstants.signals[result.signal] || 0);
+  return result.code ?? 1;
+}
+
+export async function fileMode(path) {
+  return (await stat(path)).mode & 0o777;
+}

package/src/launch.test.js

@@ -0,0 +1,152 @@
+import assert from "node:assert/strict";
+import fs from "node:fs";
+import os from "node:os";
+import path from "node:path";
+
+import {
+  buildPennyInvocation,
+  claudeLaunchSettingsPath,
+  claudeUserCommandPath,
+  codexLaunchProfilePath,
+  configurePennyHarness,
+  fileMode,
+  installPennyRuntime,
+  loadPennyConfig,
+  pennyConfigPath,
+  pennyRuntimeDir,
+  pennyShimPath,
+  removePennyHarness,
+  removePennyRuntime,
+  renderCodexLaunchProfile,
+} from "./launch.js";
+
+const ENV_KEYS = [
+  "HOME", "XDG_CONFIG_HOME", "XDG_DATA_HOME", "XDG_STATE_HOME", "CODEX_HOME", "PATH", "SHELL",
+];
+
+async function main() {
+  if (!(["darwin", "linux"].includes(process.platform))) {
+    console.log("launch.test.js: skipped on unsupported platform");
+    return;
+  }
+
+  const root = fs.mkdtempSync(path.join(os.tmpdir(), "pr-launch-test-"));
+  const previous = Object.fromEntries(ENV_KEYS.map((key) => [key, process.env[key]]));
+  const home = path.join(root, "home");
+  fs.mkdirSync(path.join(home, ".claude"), { recursive: true });
+  fs.mkdirSync(path.join(home, ".codex"), { recursive: true });
+  const nativeClaude = `${JSON.stringify({
+    permissions: { allow: ["Read"] },
+    statusLine: { type: "command", command: "native-status" },
+  }, null, 2)}\n`;
+  const nativeCodex = 'model = "native-model"\n';
+  fs.writeFileSync(path.join(home, ".claude", "settings.json"), nativeClaude);
+  fs.writeFileSync(path.join(home, ".codex", "config.toml"), nativeCodex);
+  fs.writeFileSync(path.join(home, ".zshrc"), "# user setting\n");
+
+  Object.assign(process.env, {
+    HOME: home,
+    XDG_CONFIG_HOME: path.join(home, ".config"),
+    XDG_DATA_HOME: path.join(home, ".local", "share"),
+    XDG_STATE_HOME: path.join(home, ".local", "state"),
+    CODEX_HOME: path.join(home, ".codex"),
+    PATH: "/usr/bin:/bin",
+    SHELL: "/bin/zsh",
+  });
+
+  try {
+    const first = await installPennyRuntime();
+    const staleSkill = path.join(pennyRuntimeDir(), "claude-plugin", "skills", "penny", "SKILL.md");
+    fs.mkdirSync(path.dirname(staleSkill), { recursive: true });
+    fs.writeFileSync(staleSkill, "stale plugin file");
+    const second = await installPennyRuntime();
+    assert.equal(first.supported, true);
+    assert.equal(first.changed, true);
+    assert.equal(second.changed, false);
+    assert.equal(await fileMode(pennyShimPath()), 0o755);
+    assert.ok(fs.existsSync(path.join(pennyRuntimeDir(), "bin", "penny.js")));
+    assert.ok(!fs.existsSync(staleSkill), "runtime upgrade removes stale plugin files");
+    const rc = fs.readFileSync(path.join(home, ".zshrc"), "utf8");
+    assert.equal((rc.match(/>>> pennyrouter PATH >>>/g) || []).length, 1);
+
+    await configurePennyHarness("claude-code", {
+      apiKey: "pr-super-secret",
+      gatewayBaseUrl: "https://gateway.example/",
+      subscriptionAuth: true,
+      models: { haiku: "Penny Haiku", sonnet: "Penny Sonnet", opus: "Penny Opus" },
+    });
+    await configurePennyHarness("codex", {
+      apiKey: "pr-super-secret",
+      gatewayBaseUrl: "https://gateway.example/",
+      subscriptionAuth: true,
+    });
+
+    assert.equal(fs.readFileSync(path.join(home, ".claude", "settings.json"), "utf8"), nativeClaude);
+    assert.equal(fs.readFileSync(path.join(home, ".codex", "config.toml"), "utf8"), nativeCodex);
+    assert.equal(await fileMode(pennyConfigPath()), 0o600);
+    assert.equal(await fileMode(claudeLaunchSettingsPath()), 0o600);
+    assert.equal(await fileMode(codexLaunchProfilePath()), 0o600);
+
+    const config = await loadPennyConfig();
+    assert.equal(config.api_key, "pr-super-secret");
+    const codexProfile = fs.readFileSync(codexLaunchProfilePath(), "utf8");
+    assert.ok(codexProfile.includes('env_http_headers = { "x-pennyrouter-key" = "PENNYROUTER_API_KEY" }'));
+    assert.ok(!codexProfile.includes("pr-super-secret"));
+    assert.ok(!rc.includes("pr-super-secret"));
+
+    const claude = buildPennyInvocation("claude", ["--resume", "abc"], config);
+    assert.equal(claude.command, "claude");
+    assert.deepEqual(claude.args.slice(-2), ["--resume", "abc"]);
+    assert.ok(!claude.args.includes("--plugin-dir"));
+    assert.equal(claude.env.ANTHROPIC_AUTH_TOKEN, "pr-super-secret");
+    assert.equal(claude.env.ANTHROPIC_BASE_URL, "https://gateway.example/");
+    assert.equal(claude.env.ANTHROPIC_DEFAULT_OPUS_MODEL, "Penny Opus");
+
+    const codex = buildPennyInvocation("codex", ["resume", "--last"], config);
+    assert.deepEqual(codex.args, ["--profile", "pennyrouter", "resume", "--last"]);
+    assert.equal(codex.env.PENNYROUTER_API_KEY, "pr-super-secret");
+    assert.throws(() => buildPennyInvocation("claude", ["--settings=x"], config), /manages --settings/);
+    assert.throws(() => buildPennyInvocation("codex", ["-p", "other"], config), /manages --profile/);
+
+    const command = fs.readFileSync(claudeUserCommandPath(), "utf8");
+    assert.ok(command.includes("@penny $ARGUMENTS"));
+
+    await removePennyHarness("claude-code");
+    assert.ok(!fs.existsSync(claudeUserCommandPath()));
+    fs.mkdirSync(path.dirname(claudeUserCommandPath()), { recursive: true });
+    fs.writeFileSync(claudeUserCommandPath(), "user-owned command\n");
+    await assert.rejects(configurePennyHarness("claude-code", {
+      apiKey: "pr-super-secret",
+      gatewayBaseUrl: "https://gateway.example/",
+      models: {},
+    }), /not managed by PennyRouter/);
+    assert.equal(fs.readFileSync(claudeUserCommandPath(), "utf8"), "user-owned command\n");
+    assert.ok(fs.existsSync(codexLaunchProfilePath()));
+    assert.ok(fs.existsSync(pennyShimPath()));
+    await removePennyHarness("codex");
+    await removePennyRuntime();
+    assert.ok(!fs.existsSync(pennyShimPath()));
+    assert.ok(!fs.existsSync(pennyRuntimeDir()));
+    assert.ok(!fs.existsSync(pennyConfigPath()));
+    assert.equal(fs.readFileSync(path.join(home, ".zshrc"), "utf8"), "# user setting\n");
+
+    const paid = renderCodexLaunchProfile({
+      gatewayBaseUrl: "https://gateway.example/", subscriptionAuth: false,
+    });
+    assert.ok(paid.includes('env_key = "PENNYROUTER_API_KEY"'));
+    assert.ok(!paid.includes("requires_openai_auth"));
+  } finally {
+    for (const key of ENV_KEYS) {
+      if (previous[key] === undefined) delete process.env[key];
+      else process.env[key] = previous[key];
+    }
+    fs.rmSync(root, { recursive: true, force: true });
+  }
+
+  console.log("launch.test.js: all checks passed");
+}
+
+main().catch((error) => {
+  console.error(error);
+  process.exit(1);
+});

package/src/session.js

@@ -5,7 +5,7 @@ export function maskKey(key) {
   return `${key.slice(0, 3)}...${key.slice(-4)}`;
 }
 
-export async function createCliSession({ appUrl = APP_URL, harnesses, accountMode = "seed" }) {
+export async function createCliSession({ appUrl = APP_URL, harnesses, accountMode = "existing" }) {
   const label = `${platformName()} / ${harnesses.join(",") || "PennyRouter"}`;
   const response = await fetch(`${appUrl}/api/cli/session`, {
     method: "POST",
@@ -118,7 +118,9 @@ export async function probeClaudeCodeGateway({ gatewayBaseUrl, apiKey }) {
       // Status alone is enough for a safe failure.
     }
     throw new Error(
-      `Gateway compatibility check failed: HTTP ${response.status}${detail ? ` — ${detail}` : ""}. No Claude Code settings were changed.`,
+      `Gateway compatibility check failed: HTTP ${response.status}${detail ? ` — ${detail}` : ""}. `
+      + "The PennyRouter gateway rejected a modern Claude Code request; deploy/fix the gateway "
+      + "before retrying. No Claude Code settings were changed.",
     );
   }
   return true;

package/src/session.test.js

@@ -1,9 +1,21 @@
 import assert from "node:assert/strict";
-import { probeClaudeCodeGateway } from "./session.js";
+import { createCliSession, probeClaudeCodeGateway } from "./session.js";
 
 const originalFetch = globalThis.fetch;
 
 try {
+  let sessionRequest;
+  globalThis.fetch = async (url, options) => {
+    sessionRequest = { url, options };
+    return {
+      ok: true,
+      json: async () => ({ session_id: "session-test" }),
+    };
+  };
+  await createCliSession({ appUrl: "https://app.example", harnesses: ["claude-code"] });
+  assert.equal(sessionRequest.url, "https://app.example/api/cli/session");
+  assert.equal(JSON.parse(sessionRequest.options.body).account_mode, "existing");
+
   let seen;
   globalThis.fetch = async (url, options) => {
     seen = { url, options };
@@ -29,4 +41,3 @@ try {
 } finally {
   globalThis.fetch = originalFetch;
 }
-