pennyrouter 0.2.10 → 0.2.12

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "pennyrouter",
-  "version": "0.2.10",
+  "version": "0.2.12",
   "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 && 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 && node src/thread-session.test.js && node src/mcp.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 && node src/thread-session.test.js && node src/thread-session-codex.test.js && node src/mcp-register.test.js && node src/mcp.test.js"
   },
   "license": "MIT"
 }

package/src/cli.js

@@ -4,6 +4,10 @@ import { createInterface } from "node:readline/promises";
 import { stdin as input, stdout as output } from "node:process";
 import { aiderHarness } from "./harnesses/aider.js";
 import { runMcpServer } from "./mcp.js";
+import { mcpStatus, registerMcp } from "./mcp-register.js";
+
+/** The harnesses that can run an MCP server. The other supported harnesses cannot. */
+const MCP_HARNESS_IDS = ["claude-code", "codex"];
 import {
   CLAUDE_CODE_MODELS,
   claudeCodeHarness,
@@ -117,7 +121,13 @@ export async function main(argv = process.argv.slice(2)) {
   }
 
   if (command === "mcp") {
-    await serveMcp(flags);
+    // Bare `mcp` is the server itself, started by a harness over stdio. The subcommands are for
+    // a person: registering after --no-mcp, retrying after a name conflict, or checking state.
+    const sub = (flags.args[0] || "").toLowerCase();
+    if (sub === "install" || sub === "add") await installMcp(flags);
+    else if (sub === "uninstall" || sub === "remove") await uninstallMcp(flags);
+    else if (sub === "status" || sub === "list") await statusMcp();
+    else await serveMcp(flags);
     return;
   }
 
@@ -141,6 +151,7 @@ function parseArgs(argv) {
     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-mcp") flags.noMcp = 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;
@@ -578,6 +589,24 @@ export async function install(flags = {}) {
   } else if (runtimeResult?.changed) {
     console.log("Open a new terminal (or reload your shell) before using the `penny` command.");
   }
+
+  // Registered after routing, which is the primary job: a naming conflict here reports itself
+  // and leaves a working install rather than failing the whole run.
+  if (!flags.noMcp && !flags.dryRun) {
+    const mcp = await registerMcp(records.map((r) => r.harness));
+    const registered = mcp.filter((r) => r.changed).map((r) => HARNESS_BY_ID[r.harness]?.name);
+    if (registered.length) {
+      console.log("");
+      console.log(color("Threads MCP", "bold"));
+      console.log(`  Registered on ${registered.join(" and ")}.`);
+      console.log("  Ask your agent to read or resume an AI share link:");
+      console.log('    "code based on this chat: <paste a ChatGPT/Claude/Gemini/Perplexity link>"');
+    }
+    for (const result of mcp.filter((r) => r.error)) {
+      console.log(`  MCP registration skipped for ${result.harness}: ${result.error}`);
+    }
+  }
+
   console.log("");
   reportFailures(failures);
 }
@@ -596,6 +625,59 @@ export async function getSetupPreflight() {
   };
 }
 
+/* The `mcp install|uninstall|status` subcommands.
+
+   Install already registers the server, so these exist for the states install cannot reach:
+   someone who passed --no-mcp and changed their mind, someone who hit a name conflict and has
+   now renamed the other server, and anyone who just wants to know whether it is wired up. */
+
+function mcpTargets(flags) {
+  const requested = parseHarnessList(flags.harness).filter((id) => MCP_HARNESS_IDS.includes(id));
+  return requested.length ? requested : MCP_HARNESS_IDS;
+}
+
+async function installMcp(flags) {
+  const results = await registerMcp(mcpTargets(flags));
+  console.log("PennyRouter Threads MCP");
+  console.log("");
+  for (const result of results) {
+    const name = HARNESS_BY_ID[result.harness]?.name || result.harness;
+    if (result.error) console.log(`  ${name}: ${result.error}`);
+    else if (result.changed) console.log(`  ${name}: registered`);
+    else if (result.reason) console.log(`  ${name}: skipped — ${result.reason}`);
+    else console.log(`  ${name}: already registered`);
+  }
+  console.log("");
+  console.log("Restart any running session, then ask your agent to read or resume a share link.");
+}
+
+async function uninstallMcp(flags) {
+  const results = await registerMcp(mcpTargets(flags), { remove: true });
+  console.log("PennyRouter Threads MCP");
+  console.log("");
+  for (const result of results) {
+    const name = HARNESS_BY_ID[result.harness]?.name || result.harness;
+    console.log(`  ${name}: ${result.changed ? "removed" : "nothing to remove"}`);
+  }
+}
+
+async function statusMcp() {
+  const rows = await mcpStatus(MCP_HARNESS_IDS);
+  console.log("PennyRouter Threads MCP");
+  console.log("");
+  for (const row of rows) {
+    const name = HARNESS_BY_ID[row.harness]?.name || row.harness;
+    if (!row.configFound) console.log(`  ${name}: not installed on this machine`);
+    else if (row.conflict) {
+      console.log(`  ${name}: a different server is already named "pennyrouter"`);
+    } else console.log(`  ${name}: ${row.registered ? "registered" : "not registered"}`);
+  }
+  if (rows.some((row) => row.configFound && !row.registered)) {
+    console.log("");
+    console.log("Register with: pennyrouter mcp install");
+  }
+}
+
 /* Serve the Threads MCP tools over stdio. Started by the harness, not by a person: stdout is the
    JSON-RPC channel, so nothing may be printed to it. Diagnostics go to stderr. */
 async function serveMcp(flags) {
@@ -736,6 +818,24 @@ async function update(flags) {
   }
 
   await saveManifest(manifest);
+
+  // Pick up MCP registration for installs that predate it, which is every existing user: the
+  // server ships with the package but nothing registers it retroactively.
+  //
+  // Update always registers rather than honoring a stored opt-out. Registration is what makes
+  // the Threads tools exist at all, and a preference remembered across version bumps would
+  // mostly serve to leave people silently without them. `--no-mcp` still skips a single run,
+  // and `pennyrouter mcp uninstall` removes it for good.
+  if (!flags.dryRun && !flags.noMcp) {
+    const wanted = targets.filter((record) => MCP_HARNESS_IDS.includes(record.harness));
+    const results = await registerMcp(wanted.map((record) => record.harness));
+    const added = results.filter((r) => r.changed).map((r) => HARNESS_BY_ID[r.harness]?.name);
+    if (added.length) console.log(`Registered the Threads MCP server on ${added.join(" and ")}.`);
+    for (const result of results.filter((r) => r.error)) {
+      console.log(`MCP registration skipped for ${result.harness}: ${result.error}`);
+    }
+  }
+
   console.log("");
   if (runtimeResult && !runtimeResult.available) {
     console.log("Add the PennyRouter launcher directory to PATH before using the `penny` command.");
@@ -1203,6 +1303,10 @@ async function uninstall(flags) {
     });
   }
 
+  // Only entries PennyRouter wrote are removed, so a server the user re-pointed at their own
+  // build survives an uninstall.
+  await registerMcp(selectedRecords.map((record) => record.harness), { remove: true });
+
   if (anthropicTokenNotice) {
     console.log("");
     console.log("Note: Your stored Anthropic token remains on the server for other machines.");
@@ -1733,22 +1837,26 @@ function printHelp() {
   console.log(`PennyRouter CLI
 
 Usage:
-  pennyrouter install [--harness ${SUPPORTED_HARNESS_IDS}] [--all] [--yes] [--dry-run] [--make-default|--penny-only] [--no-path-update] [--anthropic-auth|--no-anthropic-auth] [--anthropic-api-key KEY] [--openai-api-key KEY] [--openrouter-api-key KEY] [--local[=URL]] [--allow-running-harnesses]
-  pennyrouter update [--harness ${SUPPORTED_HARNESS_IDS}] [--all] [--dry-run] [--penny-key pr-...] [--gateway-base-url URL] [--allow-running-harnesses]
+  pennyrouter install [--harness ${SUPPORTED_HARNESS_IDS}] [--all] [--yes] [--dry-run] [--make-default|--penny-only] [--no-path-update] [--no-mcp] [--anthropic-auth|--no-anthropic-auth] [--anthropic-api-key KEY] [--openai-api-key KEY] [--openrouter-api-key KEY] [--local[=URL]] [--allow-running-harnesses]
+  pennyrouter update [--harness ${SUPPORTED_HARNESS_IDS}] [--all] [--dry-run] [--penny-key pr-...] [--gateway-base-url URL] [--no-mcp] [--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]
   pennyrouter uninstall [--harness ${SUPPORTED_HARNESS_IDS}] [--all] [--yes] [--forget-token]
   pennyrouter status
-  pennyrouter mcp [--penny-key pr-...] [--gateway-base-url URL]
+  pennyrouter mcp install|uninstall|status [--harness claude-code,codex]
 
-The mcp command runs the Threads MCP server on stdio. It is started by your agent, not by hand —
-register it once and then ask the agent to read or resume a share link:
+Install and update both register the Threads MCP server with Claude Code and Codex (--no-mcp to
+skip a run). Run "pennyrouter mcp install" if you skipped it or had to rename a conflicting
+server, "pennyrouter mcp status" to see whether it is wired up, and "pennyrouter mcp uninstall"
+to remove it. Bare "pennyrouter mcp" is the server itself, run by those harnesses over stdio —
+you never invoke it by hand.
 
-  claude mcp add pennyrouter -- npx -y pennyrouter mcp
+Once registered, ask your agent to read or resume an AI share link:
 
   thread_read <url>    pull a ChatGPT/Claude/Gemini/Perplexity conversation into the chat
-  thread_resume <url>  write it as a resumable Claude Code session and print the resume command
+  thread_resume <url>  write it as a resumable session and print the resume command
+                       (harness: claude-code by default, or codex)
 
 Update refreshes the managed local config and the penny runtime to this package version.
 It reuses your existing key and never re-asks for subscription or API credentials.

package/src/harnesses/claude-code.js

@@ -4,13 +4,10 @@ import { configureClaudeCodeStatusline, restoreClaudeCodeStatusline } from "../s
 const CONFIG_PATH = "~/.claude/settings.json";
 const LEGACY_MODEL_LABEL = "PennyRouter Bundle";
 const CONNECTOR_SETTING = "disableClaudeAiConnectors";
-// Values written into Claude Code's four model slots. CC displays a slot's VALUE verbatim in
-// its /model menu AND sends it as the request `model`, so use genuine Anthropic ids here.
-// That lets Claude Code apply its own per-model context limits: Haiku gets its 200K window;
-// the 1M-capable slots get 1M. The gateway recognizes and pins these native ids, so the user's
-// pick still runs on that exact model (background/utility calls remain cheap). "Penny Custom"
-// remains the dynamic PennyRouter option. Friendly pinned labels from earlier installs remain
-// recognized for uninstall and backwards compatibility (see isPennyRouterModelValue).
+// The slot values remain genuine Anthropic ids so Claude Code recognizes their actual context
+// windows (Haiku 200K; the 1M-capable models 1M) and sends the native id on the wire. Claude
+// Code separately supports *_MODEL_NAME and *_MODEL_DESCRIPTION for the picker, so Penny can
+// present a friendly alias without sacrificing model recognition.
 export const CLAUDE_CODE_MODELS = {
   haiku: "claude-haiku-4-5-20251001",
   sonnet: "claude-sonnet-5",
@@ -18,6 +15,12 @@ export const CLAUDE_CODE_MODELS = {
   fable: "claude-fable-5",
   custom: "Penny Custom",             // -> dynamic (PennyRouter cost-routing)
 };
+const CLAUDE_CODE_MODEL_PRESENTATION = {
+  haiku: { name: "Haiku 4.5 (PennyRouter)", description: "Fast, economical Claude model · 200K context" },
+  sonnet: { name: "Sonnet 5 (PennyRouter)", description: "Balanced Claude model · 1M context" },
+  opus: { name: "Opus 5 (PennyRouter)", description: "Most capable Claude model · 1M context" },
+  fable: { name: "Fable 5 (PennyRouter)", description: "Claude model · 1M context" },
+};
 const LEGACY_PINNED_MODEL_IDS = {
   "Haiku 4.5 (PennyRouter)": CLAUDE_CODE_MODELS.haiku,
   "Sonnet 5 (PennyRouter)": CLAUDE_CODE_MODELS.sonnet,
@@ -33,6 +36,22 @@ const LEGACY_PENNY_LABELS = [
   "Penny Opus", "Penny Sonnet", "Penny Haiku", "Penny Fable",
 ];
 
+// Used both for globally-installed Claude Code and `penny claude`, whose isolated
+// launch environment otherwise bypasses ~/.claude/settings.json entirely.
+export function writeClaudeCodeModelPresentation(env) {
+  for (const [slot, { name, description }] of Object.entries(CLAUDE_CODE_MODEL_PRESENTATION)) {
+    const prefix = `ANTHROPIC_DEFAULT_${slot.toUpperCase()}_MODEL`;
+    env[`${prefix}_NAME`] = name;
+    env[`${prefix}_DESCRIPTION`] = description;
+  }
+}
+
+const CLAUDE_CODE_MODEL_PRESENTATION_KEYS = Object.keys(CLAUDE_CODE_MODEL_PRESENTATION)
+  .flatMap((slot) => {
+    const prefix = `ANTHROPIC_DEFAULT_${slot.toUpperCase()}_MODEL`;
+    return [`${prefix}_NAME`, `${prefix}_DESCRIPTION`];
+  });
+
 export const claudeCodeHarness = {
   id: "claude-code",
   name: "Claude Code",
@@ -69,6 +88,7 @@ export const claudeCodeHarness = {
     current.env.ANTHROPIC_DEFAULT_SONNET_MODEL = CLAUDE_CODE_MODELS.sonnet;
     current.env.ANTHROPIC_DEFAULT_HAIKU_MODEL = CLAUDE_CODE_MODELS.haiku;
     current.env.ANTHROPIC_DEFAULT_FABLE_MODEL = CLAUDE_CODE_MODELS.fable;
+    writeClaudeCodeModelPresentation(current.env);
     // This is global, not per-model. Leave it unset so Claude Code uses each native id's
     // real context limit instead of incorrectly giving Haiku a 1M window.
     delete current.env.CLAUDE_CODE_MAX_CONTEXT_TOKENS;
@@ -94,6 +114,7 @@ export const claudeCodeHarness = {
           "ANTHROPIC_DEFAULT_SONNET_MODEL",
           "ANTHROPIC_DEFAULT_HAIKU_MODEL",
           "ANTHROPIC_DEFAULT_FABLE_MODEL",
+          ...CLAUDE_CODE_MODEL_PRESENTATION_KEYS,
         ],
       },
     };
@@ -117,6 +138,7 @@ export const claudeCodeHarness = {
     current.env.ANTHROPIC_DEFAULT_SONNET_MODEL = CLAUDE_CODE_MODELS.sonnet;
     current.env.ANTHROPIC_DEFAULT_HAIKU_MODEL = CLAUDE_CODE_MODELS.haiku;
     current.env.ANTHROPIC_DEFAULT_FABLE_MODEL = CLAUDE_CODE_MODELS.fable;
+    writeClaudeCodeModelPresentation(current.env);
     // This is global, not per-model. Leave it unset so Claude Code uses each native id's
     // real context limit instead of incorrectly giving Haiku a 1M window.
     delete current.env.CLAUDE_CODE_MAX_CONTEXT_TOKENS;
@@ -142,6 +164,7 @@ export const claudeCodeHarness = {
           "ANTHROPIC_DEFAULT_SONNET_MODEL",
           "ANTHROPIC_DEFAULT_HAIKU_MODEL",
           "ANTHROPIC_DEFAULT_FABLE_MODEL",
+          ...CLAUDE_CODE_MODEL_PRESENTATION_KEYS,
         ],
       },
     };
@@ -161,6 +184,7 @@ export const claudeCodeHarness = {
     current.env.ANTHROPIC_DEFAULT_SONNET_MODEL = CLAUDE_CODE_MODELS.sonnet;
     current.env.ANTHROPIC_DEFAULT_HAIKU_MODEL = CLAUDE_CODE_MODELS.haiku;
     current.env.ANTHROPIC_DEFAULT_FABLE_MODEL = CLAUDE_CODE_MODELS.fable;
+    writeClaudeCodeModelPresentation(current.env);
     // This is global, not per-model. Leave it unset so Claude Code uses each native id's
     // real context limit instead of incorrectly giving Haiku a 1M window.
     delete current.env.CLAUDE_CODE_MAX_CONTEXT_TOKENS;
@@ -186,6 +210,7 @@ export const claudeCodeHarness = {
           "ANTHROPIC_DEFAULT_SONNET_MODEL",
           "ANTHROPIC_DEFAULT_HAIKU_MODEL",
           "ANTHROPIC_DEFAULT_FABLE_MODEL",
+          ...CLAUDE_CODE_MODEL_PRESENTATION_KEYS,
         ],
       },
     };
@@ -220,6 +245,7 @@ export const claudeCodeHarness = {
       ]) {
         if (current.env[k] === LEGACY_MODEL_LABEL || isPennyRouterModelValue(current.env[k])) delete current.env[k];
       }
+      for (const k of CLAUDE_CODE_MODEL_PRESENTATION_KEYS) delete current.env[k];
       delete current.env.CLAUDE_CODE_MAX_CONTEXT_TOKENS;
     }
     restoreClaudeAiConnectors(current, record);

package/src/launch.js

@@ -13,7 +13,7 @@ import { fileURLToPath } from "node:url";
 import { basename, dirname, join, resolve } from "node:path";
 
 import { configureClaudeCodeStatusline } from "./statusline.js";
-import { upgradeClaudeCodeModelValue } from "./harnesses/claude-code.js";
+import { upgradeClaudeCodeModelValue, writeClaudeCodeModelPresentation } from "./harnesses/claude-code.js";
 import { atomicWrite, homeDir, readJsonFile, readText } from "./state.js";
 
 const CONFIG_VERSION = 1;
@@ -438,6 +438,7 @@ export function buildPennyInvocation(harness, args, config) {
     if (models.sonnet) env.ANTHROPIC_DEFAULT_SONNET_MODEL = upgradeClaudeCodeModelValue(models.sonnet);
     if (models.opus) env.ANTHROPIC_DEFAULT_OPUS_MODEL = upgradeClaudeCodeModelValue(models.opus);
     if (models.fable) env.ANTHROPIC_DEFAULT_FABLE_MODEL = upgradeClaudeCodeModelValue(models.fable);
+    writeClaudeCodeModelPresentation(env);
     // Per-model limits must come from Claude Code's recognized native model ids. This
     // global override would incorrectly give Haiku the 1M window.
     delete env.CLAUDE_CODE_MAX_CONTEXT_TOKENS;

package/src/launch.test.js

@@ -105,6 +105,8 @@ async function main() {
     assert.equal(claude.env.ANTHROPIC_BASE_URL, "https://gateway.example/");
     assert.equal(claude.env.ANTHROPIC_DEFAULT_OPUS_MODEL, "claude-opus-5");
     assert.equal(claude.env.ANTHROPIC_DEFAULT_HAIKU_MODEL, "claude-haiku-4-5-20251001");
+    assert.equal(claude.env.ANTHROPIC_DEFAULT_HAIKU_MODEL_NAME, "Haiku 4.5 (PennyRouter)");
+    assert.equal(claude.env.ANTHROPIC_DEFAULT_HAIKU_MODEL_DESCRIPTION, "Fast, economical Claude model · 200K context");
     assert.equal(claude.env.CLAUDE_CODE_MAX_CONTEXT_TOKENS, undefined);
 
     const codex = buildPennyInvocation("codex", ["resume", "--last"], config);

package/src/mcp-register.js

@@ -0,0 +1,193 @@
+/* Register the Threads MCP server with the harnesses that can run it.
+
+   Without this, `pennyrouter install` gives a user routing and nothing else: the MCP server
+   exists as a command they would have to discover and register by hand, which almost nobody
+   does. Registration is what makes thread_read/thread_resume simply be there.
+
+   Two harnesses, two config files, neither of them the one the installer already manages:
+
+     Claude Code  ~/.claude.json          -> mcpServers.pennyrouter   (JSON)
+     Codex        ~/.codex/config.toml    -> [mcp_servers.pennyrouter] (TOML)
+
+   NOTE the file for Claude Code. Its MCP registry is `~/.claude.json`, NOT the
+   `~/.claude/settings.json` that harnesses/claude-code.js writes — different file, different
+   shape. Writing the entry into settings.json looks right and does nothing.
+
+   The command is `npx -y pennyrouter mcp`, deliberately unpinned. An absolute path to the
+   current bin breaks the moment the user switches node versions or reinstalls, and the server
+   then silently stops appearing rather than failing loudly. A pinned version would freeze the
+   session writers, which is wrong for a feature whose whole risk is that Claude Code and Codex
+   change their undocumented formats — the writers need to be updatable. */
+
+import { atomicWrite, backupFile, exists, expandHome, readJsonFile } from "./state.js";
+import { readFile } from "node:fs/promises";
+
+export const SERVER_NAME = "pennyrouter";
+const CLAUDE_REGISTRY = "~/.claude.json";
+const CODEX_CONFIG = "~/.codex/config.toml";
+
+const MANAGED_START = "# --- PennyRouter managed MCP server ---";
+const MANAGED_END = "# --- end PennyRouter managed MCP server ---";
+
+/** What we register. Shared by both harnesses so the two configs cannot drift apart. */
+export function serverEntry() {
+  return { command: "npx", args: ["-y", "pennyrouter", "mcp"] };
+}
+
+/** True when an entry is one of ours, so re-installing updates rather than duplicating and
+    uninstalling never removes a server the user registered themselves. */
+export function isManagedEntry(entry) {
+  if (!entry || typeof entry !== "object") return false;
+  const args = Array.isArray(entry.args) ? entry.args.join(" ") : "";
+  return /\bpennyrouter\b/.test(`${entry.command || ""} ${args}`);
+}
+
+// -- Claude Code ----------------------------------------------------------
+
+export function applyClaudeRegistry(config, { remove = false } = {}) {
+  const next = { ...(config || {}) };
+  const servers = { ...(next.mcpServers || {}) };
+
+  if (remove) {
+    // Only remove what we wrote. A user who pointed the name at their own build keeps it.
+    if (isManagedEntry(servers[SERVER_NAME])) delete servers[SERVER_NAME];
+  } else {
+    const existing = servers[SERVER_NAME];
+    if (existing && !isManagedEntry(existing)) {
+      throw new Error(
+        `Claude Code already has an MCP server named "${SERVER_NAME}" that PennyRouter did not ` +
+          "write. Rename it before installing so your configuration is not overwritten.",
+      );
+    }
+    servers[SERVER_NAME] = serverEntry();
+  }
+
+  if (Object.keys(servers).length) next.mcpServers = servers;
+  else delete next.mcpServers;
+  return next;
+}
+
+async function writeClaude({ remove }) {
+  if (!(await exists(CLAUDE_REGISTRY))) {
+    // Claude Code writes this on first run. Creating it ourselves risks clobbering a shape we
+    // do not own, so skip rather than guess.
+    return { changed: false, reason: "Claude Code config not found" };
+  }
+  const current = (await readJsonFile(CLAUDE_REGISTRY, null)) || {};
+  const next = applyClaudeRegistry(current, { remove });
+  if (JSON.stringify(next) === JSON.stringify(current)) return { changed: false };
+
+  await backupFile(CLAUDE_REGISTRY, "mcp");
+  await atomicWrite(CLAUDE_REGISTRY, `${JSON.stringify(next, null, 2)}\n`);
+  return { changed: true, path: expandHome(CLAUDE_REGISTRY) };
+}
+
+// -- Codex ----------------------------------------------------------------
+
+export function renderCodexMcp(text, { remove = false } = {}) {
+  const clean = removeManagedCodexMcp(text).trimEnd();
+  if (remove) return clean ? `${clean}\n` : "";
+
+  const pattern = new RegExp(`^\\s*\\[mcp_servers\\.${SERVER_NAME}\\]\\s*$`, "m");
+  if (pattern.test(clean)) {
+    throw new Error(
+      `Codex already defines [mcp_servers.${SERVER_NAME}] outside PennyRouter's managed block. ` +
+        "Rename that server before installing so PennyRouter does not overwrite it.",
+    );
+  }
+
+  const entry = serverEntry();
+  const block = [
+    MANAGED_START,
+    `[mcp_servers.${SERVER_NAME}]`,
+    `command = "${entry.command}"`,
+    `args = [${entry.args.map((a) => `"${a}"`).join(", ")}]`,
+    MANAGED_END,
+  ].join("\n");
+
+  // Appended rather than spliced at the first table: a TOML table header captures every key
+  // that follows it, so inserting this block above existing tables would silently reparent
+  // their keys into ours.
+  return `${clean ? `${clean}\n\n` : ""}${block}\n`;
+}
+
+export function removeManagedCodexMcp(text) {
+  return String(text || "").replace(
+    new RegExp(
+      `${escapeRegex(MANAGED_START)}[\\s\\S]*?${escapeRegex(MANAGED_END)}\\n?`,
+      "g",
+    ),
+    "",
+  );
+}
+
+function escapeRegex(value) {
+  return value.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+}
+
+async function writeCodex({ remove }) {
+  if (!(await exists(CODEX_CONFIG))) return { changed: false, reason: "Codex config not found" };
+  const current = await readFile(expandHome(CODEX_CONFIG), "utf8").catch(() => "");
+  const next = renderCodexMcp(current, { remove });
+  if (next === current) return { changed: false };
+
+  await backupFile(CODEX_CONFIG, "mcp");
+  await atomicWrite(CODEX_CONFIG, next);
+  return { changed: true, path: expandHome(CODEX_CONFIG) };
+}
+
+// -- entry points ---------------------------------------------------------
+
+const WRITERS = { "claude-code": writeClaude, codex: writeCodex };
+
+/** Whether each harness currently has our server registered, and whether it could. */
+export async function mcpStatus(harnessIds = Object.keys(WRITERS)) {
+  const out = [];
+  for (const id of harnessIds) {
+    if (id === "claude-code") {
+      const present = await exists(CLAUDE_REGISTRY);
+      const config = present ? (await readJsonFile(CLAUDE_REGISTRY, null)) || {} : {};
+      out.push({
+        harness: id,
+        configFound: present,
+        registered: isManagedEntry((config.mcpServers || {})[SERVER_NAME]),
+        conflict: Boolean(
+          (config.mcpServers || {})[SERVER_NAME] &&
+            !isManagedEntry((config.mcpServers || {})[SERVER_NAME]),
+        ),
+      });
+    } else if (id === "codex") {
+      const present = await exists(CODEX_CONFIG);
+      const text = present ? await readFile(expandHome(CODEX_CONFIG), "utf8").catch(() => "") : "";
+      const managed = text.includes(MANAGED_START);
+      out.push({
+        harness: id,
+        configFound: present,
+        registered: managed,
+        conflict:
+          !managed && new RegExp(`^\\s*\\[mcp_servers\\.${SERVER_NAME}\\]`, "m").test(text),
+      });
+    }
+  }
+  return out;
+}
+
+/**
+ * Register (or with `remove`, unregister) the MCP server for `harnessIds`.
+ * Returns one result per harness; a harness whose config is absent is skipped, not an error.
+ */
+export async function registerMcp(harnessIds, { remove = false } = {}) {
+  const results = [];
+  for (const id of harnessIds) {
+    const writer = WRITERS[id];
+    if (!writer) continue;
+    try {
+      results.push({ harness: id, ...(await writer({ remove })) });
+    } catch (error) {
+      // A conflict must not fail the whole install: routing is the primary job and is already
+      // done by this point. Report it and let the user resolve the name.
+      results.push({ harness: id, changed: false, error: error?.message || String(error) });
+    }
+  }
+  return results;
+}

package/src/mcp-register.test.js

@@ -0,0 +1,171 @@
+import assert from "node:assert/strict";
+
+import {
+  SERVER_NAME,
+  applyClaudeRegistry,
+  isManagedEntry,
+  removeManagedCodexMcp,
+  renderCodexMcp,
+  serverEntry,
+} from "./mcp-register.js";
+
+// -- what gets written ----------------------------------------------------
+// Unpinned on purpose: an absolute path breaks on a node/nvm switch and the server then stops
+// appearing silently, and a pinned version would freeze the session writers — wrong for a
+// feature whose risk is that the harnesses change their undocumented formats.
+{
+  const entry = serverEntry();
+  assert.equal(entry.command, "npx");
+  assert.deepEqual(entry.args, ["-y", "pennyrouter", "mcp"]);
+  assert.ok(!JSON.stringify(entry).includes("/"), "no absolute paths");
+  assert.ok(!/pennyrouter@/.test(JSON.stringify(entry)), "not version-pinned");
+}
+
+// -- Claude Code registry -------------------------------------------------
+{
+  // Registering into an empty config.
+  const fresh = applyClaudeRegistry({});
+  assert.deepEqual(fresh.mcpServers[SERVER_NAME], serverEntry());
+
+  // Existing unrelated servers are preserved.
+  const withOthers = applyClaudeRegistry({
+    mcpServers: { railway: { command: "railway" } },
+    projects: { "/x": {} },
+  });
+  assert.ok(withOthers.mcpServers.railway, "other servers survive");
+  assert.ok(withOthers.projects, "unrelated top-level keys survive");
+
+  // Re-installing updates in place rather than duplicating.
+  const twice = applyClaudeRegistry(applyClaudeRegistry({}));
+  assert.equal(Object.keys(twice.mcpServers).length, 1);
+
+  // A same-named server we did not write is a hard stop, not a silent overwrite.
+  assert.throws(
+    () => applyClaudeRegistry({ mcpServers: { [SERVER_NAME]: { command: "/my/own/build" } } }),
+    /did not write/,
+  );
+
+  // Removal takes ours and leaves everything else.
+  const removed = applyClaudeRegistry(
+    { mcpServers: { railway: { command: "railway" }, [SERVER_NAME]: serverEntry() } },
+    { remove: true },
+  );
+  assert.ok(!removed.mcpServers[SERVER_NAME]);
+  assert.ok(removed.mcpServers.railway);
+
+  // A user who re-pointed the name at their own build keeps it through an uninstall.
+  const custom = { mcpServers: { [SERVER_NAME]: { command: "/my/own/build" } } };
+  assert.deepEqual(applyClaudeRegistry(custom, { remove: true }), custom);
+
+  // Removing the last server drops the key entirely rather than leaving `{}`.
+  const emptied = applyClaudeRegistry(
+    { mcpServers: { [SERVER_NAME]: serverEntry() } },
+    { remove: true },
+  );
+  assert.ok(!("mcpServers" in emptied));
+}
+
+// -- managed-entry detection ----------------------------------------------
+assert.equal(isManagedEntry(serverEntry()), true);
+assert.equal(isManagedEntry({ command: "npx", args: ["-y", "pennyrouter@1.2.3", "mcp"] }), true);
+assert.equal(isManagedEntry({ command: "/my/own/build" }), false);
+assert.equal(isManagedEntry(null), false);
+assert.equal(isManagedEntry({}), false);
+
+// -- Codex TOML -----------------------------------------------------------
+{
+  const existing = [
+    'model_provider = "pennyrouter"',
+    "",
+    "[mcp_servers.node_repl]",
+    'command = "/Applications/Codex.app/node_repl"',
+  ].join("\n");
+
+  const written = renderCodexMcp(existing);
+  assert.ok(written.includes(`[mcp_servers.${SERVER_NAME}]`));
+  assert.ok(written.includes('command = "npx"'));
+  assert.ok(written.includes('args = ["-y", "pennyrouter", "mcp"]'));
+  assert.ok(written.includes("[mcp_servers.node_repl]"), "existing servers survive");
+
+  // A TOML table header captures every key after it, so our block must be appended — splicing
+  // it above an existing table would reparent that table's keys into ours.
+  const ourIndex = written.indexOf(`[mcp_servers.${SERVER_NAME}]`);
+  assert.ok(ourIndex > written.indexOf("[mcp_servers.node_repl]"), "appended, not spliced");
+  assert.ok(
+    written.indexOf('model_provider = "pennyrouter"') < written.indexOf("[mcp_servers."),
+    "root keys stay above every table",
+  );
+
+  // Re-installing is idempotent: the managed block is replaced, not stacked.
+  const again = renderCodexMcp(written);
+  assert.equal(again.match(new RegExp(`\\[mcp_servers\\.${SERVER_NAME}\\]`, "g")).length, 1);
+
+  // Removal restores the original.
+  assert.equal(renderCodexMcp(written, { remove: true }).trim(), existing.trim());
+  assert.equal(removeManagedCodexMcp(written).trim(), existing.trim());
+
+  // An unmanaged server of the same name is a hard stop.
+  assert.throws(
+    () => renderCodexMcp(`[mcp_servers.${SERVER_NAME}]\ncommand = "mine"`),
+    /outside PennyRouter's managed block/,
+  );
+
+  // Empty config in, valid config out.
+  assert.ok(renderCodexMcp("").includes(`[mcp_servers.${SERVER_NAME}]`));
+  assert.equal(renderCodexMcp("", { remove: true }), "");
+}
+
+// -- status reporting -----------------------------------------------------
+// `mcp status` is how someone finds out they are in the state install cannot reach: opted out
+// with --no-mcp, or blocked by a name conflict. Both must be distinguishable from "not set up".
+{
+  const { mkdtempSync, writeFileSync, mkdirSync } = await import("node:fs");
+  const { tmpdir } = await import("node:os");
+  const { join } = await import("node:path");
+  const { mcpStatus } = await import("./mcp-register.js");
+
+  const home = mkdtempSync(join(tmpdir(), "pr-mcp-status-"));
+  const originalHome = process.env.HOME;
+  process.env.HOME = home;
+  try {
+    // No configs at all: reported as absent, not as "not registered".
+    let rows = await mcpStatus(["claude-code", "codex"]);
+    assert.deepEqual(rows.map((r) => r.configFound), [false, false]);
+
+    // Present but not registered — the --no-mcp state.
+    writeFileSync(join(home, ".claude.json"), JSON.stringify({ mcpServers: {} }));
+    mkdirSync(join(home, ".codex"), { recursive: true });
+    writeFileSync(join(home, ".codex", "config.toml"), 'model = "gpt-5"\n');
+    rows = await mcpStatus(["claude-code", "codex"]);
+    assert.deepEqual(rows.map((r) => r.registered), [false, false]);
+    assert.deepEqual(rows.map((r) => r.conflict), [false, false]);
+    assert.deepEqual(rows.map((r) => r.configFound), [true, true]);
+
+    // Someone else's server under our name.
+    writeFileSync(
+      join(home, ".claude.json"),
+      JSON.stringify({ mcpServers: { [SERVER_NAME]: { command: "/my/own/build" } } }),
+    );
+    writeFileSync(
+      join(home, ".codex", "config.toml"),
+      `[mcp_servers.${SERVER_NAME}]\ncommand = "mine"\n`,
+    );
+    rows = await mcpStatus(["claude-code", "codex"]);
+    assert.deepEqual(rows.map((r) => r.conflict), [true, true]);
+    assert.deepEqual(rows.map((r) => r.registered), [false, false]);
+
+    // Ours.
+    writeFileSync(
+      join(home, ".claude.json"),
+      JSON.stringify(applyClaudeRegistry({})),
+    );
+    writeFileSync(join(home, ".codex", "config.toml"), renderCodexMcp(""));
+    rows = await mcpStatus(["claude-code", "codex"]);
+    assert.deepEqual(rows.map((r) => r.registered), [true, true]);
+    assert.deepEqual(rows.map((r) => r.conflict), [false, false]);
+  } finally {
+    process.env.HOME = originalHome;
+  }
+}
+
+console.log("mcp-register tests passed");

package/src/mcp.js

@@ -5,10 +5,15 @@
 
      thread_read    fetch + parse, return the transcript to the model. For "what did we decide
                     in this chat?" — the body lands in the caller's context, which is the point.
-     thread_resume  fetch + parse, write a resumable Claude Code session, return only a path and
-                    a one-line summary. For "let's continue coding from this chat" — the
-                    transcript never enters the caller's context, so moving a 200-turn thread
-                    costs the caller nothing. That asymmetry is the whole reason for two tools.
+     thread_resume  fetch + parse, write a resumable session for Claude Code OR Codex, return
+                    only a path and a resume command. For "let's continue coding from this chat"
+                    — the transcript never enters the caller's context, so moving a 200-turn
+                    thread costs the caller nothing. That asymmetry is the whole reason for two
+                    tools rather than one with a flag.
+
+   Because the destination is a parameter, "resume this Perplexity thread in Codex" and "…in
+   Claude Code" are the same call with a different `harness`. Each harness has its own writer:
+   the two on-disk formats share nothing structurally (see thread-session-codex.js).
 
    ALL SCRAPING STAYS SERVER-SIDE. This process holds no adapters, no fetcher credentials and no
    provider knowledge; it POSTs a URL to the gateway and gets a canonical thread back. What ships
@@ -22,6 +27,7 @@ import { createInterface } from "node:readline";
 import { execFileSync } from "node:child_process";
 
 import { writeSession, VERIFIED_MIN, VERIFIED_MAX } from "./thread-session.js";
+import { writeSession as writeCodexSession } from "./thread-session-codex.js";
 
 const PROTOCOL_VERSION = "2024-11-05";
 
@@ -44,10 +50,10 @@ const TOOLS = [
   {
     name: "thread_resume",
     description:
-      "Fetch an AI conversation from a share link and write it as a resumable Claude Code " +
-      "session in a workspace, so the user can `claude --resume` into it and continue coding " +
-      "with that conversation as history. Use when the user wants to CONTINUE or BUILD FROM a " +
-      "past chat rather than talk about it. Returns a session id and path; the transcript is " +
+      "Fetch an AI conversation from a share link and write it as a resumable coding-agent " +
+      "session (Claude Code or Codex), so the user can resume into it and continue coding with " +
+      "that conversation as history. Use when the user wants to CONTINUE or BUILD FROM a past " +
+      "chat rather than talk about it. Returns a session id and path; the transcript is " +
       "deliberately NOT returned, so importing a long thread costs you no context.",
     inputSchema: {
       type: "object",
@@ -59,15 +65,24 @@ const TOOLS = [
             "Absolute path to the workspace the session should resume in. Defaults to the " +
             "current working directory.",
         },
+        harness: {
+          type: "string",
+          enum: ["claude-code", "codex"],
+          description:
+            "Which agent should be able to resume it. Defaults to claude-code. Use codex when " +
+            "the user asks to continue the conversation in Codex.",
+        },
       },
       required: ["url"],
     },
   },
 ];
 
-function claudeVersion() {
+/** `<tool> --version`, or null when the tool is not installed. The writers version-gate on this
+    and refuse rather than write a session file that only fails at resume time. */
+function toolVersion(binary) {
   try {
-    return execFileSync("claude", ["--version"], { encoding: "utf8" }).trim();
+    return execFileSync(binary, ["--version"], { encoding: "utf8", stdio: ["ignore", "pipe", "ignore"] }).trim();
   } catch {
     return null;
   }
@@ -130,21 +145,34 @@ async function callTool(name, args, context) {
 
   if (name === "thread_resume") {
     const cwd = String(args?.directory || process.cwd());
-    const version = claudeVersion();
+    const harness = String(args?.harness || "claude-code").toLowerCase();
+    if (harness !== "claude-code" && harness !== "codex") {
+      throw new Error(`unknown harness "${harness}"; expected claude-code or codex`);
+    }
+
+    const codex = harness === "codex";
+    const version = codex ? toolVersion("codex") : toolVersion("claude");
     const thread = await fetchCanonical(url, context);
-    const { sessionId, path, messageCount } = writeSession(thread, { cwd, version });
+    const write = codex ? writeCodexSession : writeSession;
+    const { sessionId, path, messageCount } = write(thread, { cwd, version });
+
     return [
       `Imported "${thread.title}" (${thread.messages?.length || 0} messages, ` +
         `~${thread.token_estimate || 0} tokens) from ${thread.origin_app || thread.source}.`,
       "",
-      `Wrote a resumable session: ${messageCount} records`,
+      `Wrote a resumable ${codex ? "Codex" : "Claude Code"} session: ${messageCount} records`,
       `  ${path}`,
       "",
       "Resume it with:",
-      `  cd ${cwd} && claude --resume ${sessionId}`,
+      codex
+        ? `  cd ${cwd} && codex resume ${sessionId}`
+        : `  cd ${cwd} && claude --resume ${sessionId}`,
       "",
-      "The transcript was written to disk and deliberately not returned here, so it did not " +
-        "consume this session's context.",
+      codex
+        ? "Tool calls were rendered as prose: Codex and the source harness do not share a tool " +
+          "format, so this is a readable continuation rather than a replay."
+        : "The transcript was written to disk and deliberately not returned here, so it did not " +
+          "consume this session's context.",
     ].join("\n");
   }
 

package/src/mcp.test.js

@@ -133,6 +133,61 @@ const workspace = mkdtempSync(join(tmpdir(), "pr-mcp-ws-"));
   assert.equal(byId.get(4).result.isError, undefined);
 }
 
+// -- harness routing ------------------------------------------------------
+// "Resume this in Codex" is the same call with a different `harness`, so the tool must dispatch
+// to the right writer and print the right resume command. Skipped when codex is not installed:
+// the writer version-gates on `codex --version` and correctly refuses without it.
+{
+  const { server, port } = await stubGateway((req, body, res) => {
+    res.setHeader("content-type", "application/json");
+    res.end(JSON.stringify(thread));
+  });
+
+  const { messages } = await rpc(
+    [
+      { jsonrpc: "2.0", id: 1, method: "tools/list" },
+      {
+        jsonrpc: "2.0",
+        id: 2,
+        method: "tools/call",
+        params: {
+          name: "thread_resume",
+          arguments: { url: "https://x/y", directory: workspace, harness: "codex" },
+        },
+      },
+      {
+        jsonrpc: "2.0",
+        id: 3,
+        method: "tools/call",
+        params: {
+          name: "thread_resume",
+          arguments: { url: "https://x/y", directory: workspace, harness: "nonsense" },
+        },
+      },
+    ],
+    { port, home },
+  );
+  server.close();
+
+  const byId = new Map(messages.map((m) => [m.id, m]));
+
+  const schema = byId.get(1).result.tools.find((t) => t.name === "thread_resume").inputSchema;
+  assert.deepEqual(schema.properties.harness.enum, ["claude-code", "codex"]);
+
+  const codex = byId.get(2).result;
+  if (codex.isError) {
+    assert.match(codex.content[0].text, /Codex .*outside the range|ENOENT|not.*install/i);
+  } else {
+    assert.ok(codex.content[0].text.includes("codex resume"), "prints the codex resume command");
+    assert.ok(!codex.content[0].text.includes("claude --resume"));
+    assert.ok(!codex.content[0].text.includes("UNIQUE-QUESTION"), "still returns no transcript");
+  }
+
+  // An unknown harness is refused rather than silently defaulting to the wrong format.
+  assert.equal(byId.get(3).result.isError, true);
+  assert.match(byId.get(3).result.content[0].text, /unknown harness/);
+}
+
 // -- gateway failures reach the model as readable text --------------------
 {
   const { server, port } = await stubGateway((req, body, res) => {

package/src/thread-session-codex.js

@@ -0,0 +1,152 @@
+/* Write a canonical thread into a Codex rollout it will resume from.
+
+   `codex resume <session-id>` reads ~/.codex/sessions/YYYY/MM/DD/rollout-<stamp>-<uuid>.jsonl,
+   so a synthesized rollout in that tree resumes like any other session. Verified end-to-end on
+   codex-cli 0.146.0: a file written by this shape resumed and the model answered from history it
+   never lived.
+
+   The format differs from Claude Code's in every structural respect, which is why this is a
+   separate writer rather than a flag on the other one:
+
+     - Records are a {timestamp, type, payload} envelope, not flat message objects.
+     - There is no parentUuid chain. Order in the file IS the order; nothing to link.
+     - The first record is a `session_meta` header carrying cwd, cli_version and the id.
+     - User content is `input_text`; assistant content is `output_text`. Using the wrong key
+       for a role is the one mistake that produces a file which loads but renders empty.
+     - Ids are UUIDv7 (time-ordered), and both the filename stamp and the id encode when the
+       session began. Codex sorts its picker by these, so a random v4 sorts to 1970.
+
+   THE FORMAT IS UNDOCUMENTED, exactly as with Claude Code, and the same three rules apply:
+   never overwrite, version-gate, and fail loudly rather than write something that only reveals
+   itself as broken at resume time. */
+
+import { randomBytes } from "node:crypto";
+import { mkdirSync, existsSync, writeFileSync } from "node:fs";
+import { homedir } from "node:os";
+import { join } from "node:path";
+
+import { orientation, renderMessage } from "./thread-session.js";
+
+/** Versions this writer has been verified against. */
+export const VERIFIED_MIN = "0.100.0";
+export const VERIFIED_MAX = "0.999.999";
+
+/** UUIDv7: 48-bit big-endian millisecond timestamp, then version/variant bits, then random.
+    Codex orders sessions by this, so a v4 would sort as if it began in 1970. */
+export function uuidv7(now = Date.now()) {
+  const bytes = randomBytes(16);
+  const ms = BigInt(now);
+  for (let i = 0; i < 6; i += 1) {
+    bytes[i] = Number((ms >> BigInt(8 * (5 - i))) & 0xffn);
+  }
+  bytes[6] = (bytes[6] & 0x0f) | 0x70;
+  bytes[8] = (bytes[8] & 0x3f) | 0x80;
+  const hex = bytes.toString("hex");
+  return [
+    hex.slice(0, 8),
+    hex.slice(8, 12),
+    hex.slice(12, 16),
+    hex.slice(16, 20),
+    hex.slice(20),
+  ].join("-");
+}
+
+function compare(a, b) {
+  const pa = String(a).split(".").map((n) => parseInt(n, 10) || 0);
+  const pb = String(b).split(".").map((n) => parseInt(n, 10) || 0);
+  for (let i = 0; i < 3; i += 1) {
+    if ((pa[i] || 0) !== (pb[i] || 0)) return (pa[i] || 0) < (pb[i] || 0) ? -1 : 1;
+  }
+  return 0;
+}
+
+export function versionSupported(version) {
+  if (!version) return false;
+  // `codex --version` prints "codex-cli 0.146.0"; take the numeric field wherever it sits.
+  const match = String(version).match(/(\d+\.\d+\.\d+)/);
+  if (!match) return false;
+  return compare(match[1], VERIFIED_MIN) >= 0 && compare(match[1], VERIFIED_MAX) <= 0;
+}
+
+/** ~/.codex/sessions/YYYY/MM/DD — Codex partitions rollouts by date. */
+export function sessionDirFor(date = new Date()) {
+  const yyyy = String(date.getUTCFullYear());
+  const mm = String(date.getUTCMonth() + 1).padStart(2, "0");
+  const dd = String(date.getUTCDate()).padStart(2, "0");
+  return join(homedir(), ".codex", "sessions", yyyy, mm, dd);
+}
+
+/** The stamp embedded in a rollout filename: 2026-08-09T22-15-30. */
+export function fileStamp(date = new Date()) {
+  return date.toISOString().replace(/\.\d+Z$/, "").replace(/:/g, "-");
+}
+
+export function buildRecords(thread, { cwd, sessionId, version, timestamp = new Date() }) {
+  const ts = timestamp.toISOString();
+  const envelope = (type, payload) => ({ timestamp: ts, type, payload });
+
+  const message = (role, text) =>
+    envelope("response_item", {
+      type: "message",
+      id: `msg_${uuidv7(timestamp.getTime())}`,
+      role,
+      // The content key is role-dependent. Swapping them yields a file that loads and shows
+      // nothing, which is the worst failure mode available here.
+      content: [{ type: role === "assistant" ? "output_text" : "input_text", text }],
+    });
+
+  const records = [
+    envelope("session_meta", {
+      session_id: sessionId,
+      id: sessionId,
+      timestamp: ts,
+      cwd,
+      originator: "pennyrouter",
+      cli_version: String(version || "").match(/(\d+\.\d+\.\d+)/)?.[1] || "0.0.0",
+      source: "cli",
+      thread_source: "user",
+      model_provider: "openai",
+      history_mode: "legacy",
+    }),
+    message("user", orientation(thread)),
+    message("assistant", "Understood — I have the imported conversation and will continue from it."),
+  ];
+
+  for (const entry of thread.messages || []) {
+    const text = renderMessage(entry);
+    if (!text) continue;
+    if (entry.role === "assistant") records.push(message("assistant", text));
+    else if (entry.role === "user") records.push(message("user", text));
+  }
+
+  return records;
+}
+
+/**
+ * Write `thread` as a resumable Codex rollout.
+ * Returns { sessionId, path, messageCount }.
+ */
+export function writeSession(thread, { cwd, version, timestamp = new Date() }) {
+  if (!versionSupported(version)) {
+    throw new Error(
+      `Codex ${version || "(unknown version)"} is outside the range this importer has been ` +
+        `verified against (${VERIFIED_MIN}–${VERIFIED_MAX}). Refusing to write a rollout that ` +
+        `may not resume.`,
+    );
+  }
+
+  const dir = sessionDirFor(timestamp);
+  mkdirSync(dir, { recursive: true });
+
+  const sessionId = uuidv7(timestamp.getTime());
+  const path = join(dir, `rollout-${fileStamp(timestamp)}-${sessionId}.jsonl`);
+  if (existsSync(path)) throw new Error("session id collision; try again");
+
+  const records = buildRecords(thread, { cwd, sessionId, version, timestamp });
+  writeFileSync(path, records.map((r) => JSON.stringify(r)).join("\n") + "\n", {
+    encoding: "utf8",
+    flag: "wx", // fail rather than clobber, even against a race
+  });
+
+  return { sessionId, path, messageCount: records.length };
+}

package/src/thread-session-codex.test.js

@@ -0,0 +1,136 @@
+import assert from "node:assert/strict";
+import { mkdtempSync, readFileSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+
+import {
+  buildRecords,
+  fileStamp,
+  sessionDirFor,
+  uuidv7,
+  versionSupported,
+  writeSession,
+} from "./thread-session-codex.js";
+
+const thread = {
+  title: "Kickplate removal",
+  source: "perplexity_share",
+  origin_app: "Perplexity",
+  source_url: "https://www.perplexity.ai/search/x",
+  messages: [
+    { role: "user", blocks: [{ type: "text", text: "USER-TURN" }] },
+    {
+      role: "assistant",
+      blocks: [
+        { type: "thinking", text: "REASONING-TRACE" },
+        { type: "text", text: "ASSISTANT-TURN" },
+      ],
+    },
+    { role: "system", blocks: [{ type: "text", text: "SYSTEM-PREAMBLE" }] },
+  ],
+};
+
+// -- uuidv7 ---------------------------------------------------------------
+// Codex sorts its session picker by these ids. A random v4 would sort as if the session began
+// in 1970, so the timestamp prefix is not cosmetic.
+{
+  const when = Date.UTC(2026, 7, 9, 22, 15, 30);
+  const id = uuidv7(when);
+  assert.match(id, /^[0-9a-f]{8}-[0-9a-f]{4}-7[0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$/);
+  assert.equal(parseInt(id.slice(0, 8) + id.slice(9, 13), 16), when, "ms timestamp is encoded");
+  assert.notEqual(uuidv7(when), uuidv7(when), "the random tail still varies");
+  // Time-ordering is the property Codex depends on.
+  assert.ok(uuidv7(when) < uuidv7(when + 1000));
+}
+
+// -- paths ----------------------------------------------------------------
+{
+  const date = new Date(Date.UTC(2026, 7, 9, 22, 15, 30));
+  assert.ok(sessionDirFor(date).endsWith(join(".codex", "sessions", "2026", "08", "09")));
+  assert.equal(fileStamp(date), "2026-08-09T22-15-30");
+}
+
+// -- version gate ---------------------------------------------------------
+// `codex --version` prints "codex-cli 0.146.0", so the number has to be found, not assumed.
+assert.equal(versionSupported("codex-cli 0.146.0"), true);
+assert.equal(versionSupported("0.100.0"), true);
+assert.equal(versionSupported("0.99.0"), false);
+assert.equal(versionSupported("1.0.0"), false);
+assert.equal(versionSupported("not-a-version"), false);
+assert.equal(versionSupported(null), false);
+
+// -- record construction --------------------------------------------------
+{
+  const records = buildRecords(thread, {
+    cwd: "/tmp/ws",
+    sessionId: "sid-1",
+    version: "codex-cli 0.146.0",
+  });
+
+  // Every record is the {timestamp, type, payload} envelope.
+  for (const record of records) {
+    assert.deepEqual(Object.keys(record).sort(), ["payload", "timestamp", "type"]);
+  }
+
+  const [meta, ...rest] = records;
+  assert.equal(meta.type, "session_meta");
+  assert.equal(meta.payload.session_id, "sid-1");
+  assert.equal(meta.payload.cwd, "/tmp/ws");
+  assert.equal(meta.payload.cli_version, "0.146.0", "the bare number, not the whole string");
+
+  // Content key is role-dependent. Getting this wrong yields a rollout that loads and renders
+  // empty, which is the failure mode least likely to be noticed before a user hits it.
+  for (const record of rest) {
+    assert.equal(record.type, "response_item");
+    assert.equal(record.payload.type, "message");
+    const key = record.payload.content[0].type;
+    assert.equal(key, record.payload.role === "assistant" ? "output_text" : "input_text");
+    assert.match(record.payload.id, /^msg_/);
+  }
+
+  assert.deepEqual(
+    rest.map((r) => r.payload.role),
+    ["user", "assistant", "user", "assistant"],
+  );
+
+  const serialized = JSON.stringify(records);
+  assert.ok(!serialized.includes("REASONING-TRACE"), "thinking must never reach a handoff");
+  assert.ok(!serialized.includes("SYSTEM-PREAMBLE"), "system turns are not replayed");
+  assert.ok(serialized.includes("USER-TURN") && serialized.includes("ASSISTANT-TURN"));
+  assert.ok(rest[0].payload.content[0].text.includes("Perplexity"), "orientation names origin");
+}
+
+// -- writing --------------------------------------------------------------
+{
+  const home = mkdtempSync(join(tmpdir(), "pr-codex-home-"));
+  const originalHome = process.env.HOME;
+  process.env.HOME = home;
+  try {
+    const result = writeSession(thread, { cwd: "/tmp/ws", version: "codex-cli 0.146.0" });
+
+    // The filename carries both the stamp and the id; Codex's picker reads both.
+    assert.match(result.path, /rollout-\d{4}-\d{2}-\d{2}T\d{2}-\d{2}-\d{2}-[0-9a-f-]{36}\.jsonl$/);
+    assert.ok(result.path.includes(result.sessionId));
+
+    const lines = readFileSync(result.path, "utf8").trim().split("\n");
+    assert.equal(lines.length, result.messageCount);
+    const parsed = lines.map((l) => JSON.parse(l));
+    assert.equal(parsed[0].type, "session_meta");
+    assert.equal(parsed[0].payload.id, result.sessionId);
+
+    // Never overwrite an existing session.
+    const again = writeSession(thread, { cwd: "/tmp/ws", version: "codex-cli 0.146.0" });
+    assert.notEqual(again.sessionId, result.sessionId);
+    assert.notEqual(again.path, result.path);
+
+    assert.throws(
+      () => writeSession(thread, { cwd: "/tmp/ws", version: "codex-cli 2.0.0" }),
+      /outside the range/,
+    );
+    assert.throws(() => writeSession(thread, { cwd: "/tmp/ws", version: null }), /outside the range/);
+  } finally {
+    process.env.HOME = originalHome;
+  }
+}
+
+console.log("thread-session-codex tests passed");