pennyrouter 0.1.20 → 0.2.0

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,339 @@
+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)";
+
+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 claudePluginPath() {
+  return join(pennyRuntimeDir(), "claude-plugin");
+}
+
+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", "claude-plugin"]) {
+    await cp(join(source, entry), join(destination, entry), {
+      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 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 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;
+    });
+  } 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(), "--plugin-dir", claudePluginPath(), ...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,140 @@
+import assert from "node:assert/strict";
+import fs from "node:fs";
+import os from "node:os";
+import path from "node:path";
+
+import {
+  buildPennyInvocation,
+  claudeLaunchSettingsPath,
+  claudePluginPath,
+  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 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(path.join(claudePluginPath(), ".claude-plugin", "plugin.json")));
+    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 skill = fs.readFileSync(path.join(claudePluginPath(), "skills", "penny", "SKILL.md"), "utf8");
+    assert.ok(skill.includes("@penny $ARGUMENTS"));
+
+    await removePennyHarness("claude-code");
+    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",
@@ -71,6 +71,61 @@ export async function storeAnthropicToken({ gatewayBaseUrl, apiKey, token }) {
   return response.json();
 }
 
+// Exercise the exact modern Claude Code request feature that has historically broken at
+// proxy boundaries BEFORE changing ~/.claude/settings.json (a user-global redirect). This
+// is intentionally a real, tiny Messages call: a generic /health check cannot prove that
+// Anthropic beta headers survive the gateway's subscription/native relay.
+export async function probeClaudeCodeGateway({ gatewayBaseUrl, apiKey }) {
+  const url = `${gatewayBaseUrl.replace(/\/+$/, "")}/v1/messages?beta=true`;
+  const controller = new AbortController();
+  const timer = setTimeout(() => controller.abort(), 20_000);
+  let response;
+  try {
+    response = await fetch(url, {
+      method: "POST",
+      signal: controller.signal,
+      headers: {
+        "content-type": "application/json",
+        authorization: `Bearer ${apiKey}`,
+        "anthropic-beta": "compact-2026-01-12",
+      },
+      body: JSON.stringify({
+        model: "Penny Sonnet",
+        max_tokens: 16,
+        stream: false,
+        messages: [{ role: "user", content: "Reply OK." }],
+        tools: [{
+          name: "pennyrouter_install_probe",
+          description: "No-op compatibility probe; do not call it.",
+          input_schema: { type: "object", properties: {} },
+        }],
+        context_management: { edits: [{ type: "compact_20260112" }] },
+      }),
+    });
+  } catch (error) {
+    if (error?.name === "AbortError") {
+      throw new Error("Gateway compatibility check timed out; no Claude Code settings were changed.");
+    }
+    throw new Error(`Gateway compatibility check failed; no Claude Code settings were changed: ${error?.message || error}`);
+  } finally {
+    clearTimeout(timer);
+  }
+  if (!response.ok) {
+    let detail = "";
+    try {
+      detail = (await response.text()).slice(0, 500).replace(/\s+/g, " ").trim();
+    } catch {
+      // Status alone is enough for a safe failure.
+    }
+    throw new Error(
+      `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;
+}
+
 // Best-effort "forget my Claude token" on uninstall. Never throws — a cleanup that
 // can't reach the network shouldn't block removing the local integration.
 export async function forgetAnthropicToken({ gatewayBaseUrl, apiKey }) {

package/src/session.test.js

@@ -0,0 +1,43 @@
+import assert from "node:assert/strict";
+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 };
+    return { ok: true, status: 200 };
+  };
+  assert.equal(await probeClaudeCodeGateway({
+    gatewayBaseUrl: "https://gateway.example/", apiKey: "pr-test",
+  }), true);
+  assert.equal(seen.url, "https://gateway.example/v1/messages?beta=true");
+  assert.equal(seen.options.headers.authorization, "Bearer pr-test");
+  assert.equal(seen.options.headers["anthropic-beta"], "compact-2026-01-12");
+  const body = JSON.parse(seen.options.body);
+  assert.equal(body.context_management.edits[0].type, "compact_20260112");
+  assert.equal(body.tools[0].name, "pennyrouter_install_probe");
+
+  globalThis.fetch = async () => ({
+    ok: false, status: 502, text: async () => "context_management rejected",
+  });
+  await assert.rejects(
+    probeClaudeCodeGateway({ gatewayBaseUrl: "https://gateway.example", apiKey: "pr-test" }),
+    /HTTP 502.*No Claude Code settings were changed/,
+  );
+} finally {
+  globalThis.fetch = originalFetch;
+}

package/src/statusline.js

@@ -153,10 +153,9 @@ function authSuffix(mode) {
   return mode === "sub" || mode === "byok" ? " (" + mode + ")" : "";
 }
 
-// Teammate badges (@penny ask). Rendered from the STRUCTURED fields, not the gateway's
-// prebuilt \`label\` — this line is composed here (and may be appended to a wrap_command's
-// output), so the client owns the layout. 📨 = questions waiting on you; 📬 = an answer came
-// back to you. Both absent on an older gateway, which renders nothing.
+// Teammate badges (@penny ask): 📨 questions waiting on you, 📬 answers that came back.
+// Read from the structured fields rather than the gateway's prebuilt \`label\`, since this
+// line is composed here. Absent on an older gateway, which renders nothing.
 function askBadges(c) {
   if (!c) return "";
   let out = "";