claude-codex-pair 0.3.1 → 0.4.1

package/DESIGN.md

@@ -74,7 +74,21 @@ active threads.
 freshness to the channel and lane states. Freshness compares the marked pair section in
 `AGENTS.md` and the generated Claude skill against the same templates used by `init`. It is
 read-only and describes files on disk, not instructions already loaded into a running session.
-The check runs only on `status`, not during polling or message delivery.
+The comparison ignores the `<!-- pair x.y.z -->` stamp that records which version wrote a file.
+
+`send`, `wait`, `history`, `clean`, `register` and `unregister` run the same check once at startup,
+not on each poll, and rewrite stale files. They skip files stamped by a newer pair, so worktrees
+shared by two versions don't flip back and forth. A write failure is a warning on stderr, so a
+read-only sandbox still delivers messages. `status` stays read-only, and `mcp` never refreshes:
+it runs unsandboxed and only reads. `status` and `init` also report a newer npm version. They check
+at most once a day, cache the answer under the state directory, and stay quiet on failure.
+`init` also keeps files a newer pair wrote; deleting them is the way to downgrade. The refresh note goes
+to stderr after the command's own output, so `pair wait`'s first line is still the delivery or
+timeout line agents read. `pair upgrade` installs with npm, then runs the `init` of the package it
+just installed (found with `npm root --global`), not the first `pair` on PATH, because both this
+process and an older copy on PATH would write the old templates. It asks `npm view` first, so it uses
+the same registry as the install. Already on the latest version, it only runs the in-process
+refresh. If the check fails, it goes ahead with the install, which reports the actual npm error.
 
 Channel operations report `EACCES` and `EPERM` with the affected path and the sandbox
 configuration printed by `init`. Either ordinary permissions or sandbox restrictions can

package/README.md

@@ -158,7 +158,7 @@ lines. Pair needs no extra sandbox config, because every channel lives under `~/
 
 ## Commands
 
-The agents run `send` and `wait` themselves. You'll mostly use `init`, `status`, `history` and `clean`.
+The agents run `send` and `wait` themselves. You'll mostly use `init`, `status`, `history`, `clean` and `upgrade`.
 
 ```
 pair send <request|review|response> --as <claude|codex> [--verdict approve|changes] <file|->
@@ -167,6 +167,7 @@ pair status
 pair history [thread-id]   # list finished threads (latest first), or print one (any unique part of its id)
 pair clean --keep N        # delete all but the N newest finished threads
 pair init
+pair upgrade               # install the latest pair from npm, then refresh this worktree's instructions
 pair uninit                # undo pair init in this worktree (keeps history; see "Uninstall")
 pair register | unregister # run by Codex in its shell: let pair_listen notify this session
 pair mcp                   # stdio MCP server for Codex (see "Let pair wake Codex")
@@ -189,11 +190,28 @@ codex notifications: session 01a13922-c08f-79e3-a41f-6780876fd9c5, registered 20
   last listener event: 2026-10-14T08:05:12.345Z notified 01a13922-… about /Users/you/.pair/…/001-request.md
 ```
 
-Instruction states are `current`, `stale`, `missing`, or `unreadable`. The check compares only
+Instruction states are `current`, `stale`, `newer`, `missing`, or `unreadable`. The check compares only
 the marked pair section in `AGENTS.md`, so your other instructions don't affect it. Status
 doesn't change files. Run `pair init` to refresh missing or stale instructions, then reload
 agent sessions; fix access to unreadable files first. Current files on disk don't guarantee
-that a running agent has loaded them.
+that a running agent has loaded them. `newer` means a newer pair wrote them: run `pair upgrade`.
+
+`pair status` and `pair init` also print a line when npm has a newer version. They check at most
+once a day and cache the answer in `~/.local/state/pair/latest.json`. The check stays quiet when
+offline or sandboxed.
+
+## Upgrading
+
+Run `pair upgrade` in your own terminal, not through an agent: agent sandboxes block the network and
+global installs. If npm has a newer version, it runs `npm install -g claude-codex-pair@latest`, then
+the new `pair init` in the current worktree if pair is set up there, and prints only the files that
+`init` wrote or kept. Already on the latest version, it installs nothing and only refreshes this
+worktree's stale instructions. Other worktrees refresh their instructions on the next
+`pair send`, `wait`, `history` or `clean`. pair owns these files, so edits inside them are
+overwritten. pair, including `pair init`, never rewrites instructions that a newer pair wrote, so
+worktrees shared by different versions don't flip back and forth. To downgrade, delete them first. Restart Claude Code and Codex afterwards. Running
+sessions keep the instructions they loaded at start, and Codex keeps its old `pair mcp` until
+it restarts.
 
 If a channel read or write fails with `EACCES` or `EPERM`, the command names the path and prints
 sandbox configuration snippets using your actual channel directory. Check ordinary filesystem
@@ -206,6 +224,7 @@ so a cleanup problem doesn't prevent delivering a review or starting the next th
 | `PAIR_AGENT` | (none) | Default for `--as` |
 | `PAIR_MAX_ROUNDS` | `3` | Number of review rounds before escalation |
 | `PAIR_KEEP` | `100` | Finished threads to keep, by finish time. Older ones are deleted whenever a thread finishes. `all` keeps everything, `0` keeps none |
+| `PAIR_NO_UPDATE_CHECK` | (none) | Any value turns off the daily npm version check |
 
 ## Uninstall
 

package/dist/pair.js

@@ -1,5 +1,5 @@
 #!/usr/bin/env node
-import { execFile, execFileSync } from "node:child_process";
+import { execFile, execFileSync, spawnSync } from "node:child_process";
 import { createHash, randomBytes } from "node:crypto";
 import { accessSync, closeSync, constants, existsSync, lstatSync, mkdirSync, openSync, readdirSync, readFileSync, realpathSync, renameSync, rmdirSync, rmSync, statSync, writeFileSync, writeSync } from "node:fs";
 import { homedir, tmpdir } from "node:os";
@@ -24,6 +24,12 @@ const PAIR_SECTIONS = /<!-- pair:start -->[\s\S]*?<!-- pair:end -->(?:\r?\n)?/g;
 // SKILL.md as released versions wrote it (0.1.0 and 0.1.1), so `uninit` can tell it from an edited one.
 const RELEASED_SKILL_SHA256 = ["e9afb64c53d5e90f935bcb66406601a31a91b37758467cf867713e245f8af288"];
 const PACKAGE_ROOT = join(dirname(fileURLToPath(import.meta.url)), "..");
+const PACKAGE = JSON.parse(readFileSync(join(PACKAGE_ROOT, "package.json"), "utf8"));
+// Which pair wrote an instruction file, so an older pair never rolls back what a newer one wrote.
+const STAMP = /<!-- pair (\S+) -->\n/;
+// Commands that refresh stale instructions. Not status (a read-only diagnosis) or mcp (unsandboxed, so it only reads).
+const REFRESHING_COMMANDS = ["send", "wait", "history", "clean", "register", "unregister"];
+const UPDATE_CHECK_MS = 24 * 60 * 60 * 1000;
 const SESSION_ID = /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i; // any UUID version; Codex uses v7
 const SESSION_FILE = "codex.session"; // the Codex session that pair_listen may notify, per channel
 const LISTEN_LOG = "codex.listen.log";
@@ -506,9 +512,12 @@ function rotateLog(path) {
  * any check and the write that follows, so the unsandboxed server only ever reads channels.
  */
 function stateDir(channel) {
+    return join(stateHome(), basename(channel));
+}
+function stateHome() {
     const configured = process.env.XDG_STATE_HOME;
     const root = configured && isAbsolute(configured) ? configured : join(homedir(), ".local", "state");
-    return join(resolve(root), "pair", basename(channel));
+    return join(resolve(root), "pair");
 }
 function logListen(channel, text) {
     try {
@@ -817,7 +826,11 @@ function instructionState(path, expected, sectionOnly = false) {
         if (actual === undefined) {
             return "missing"; // AGENTS.md exists but has no complete pair section
         }
-        return actual === expected ? "current" : "stale";
+        if (unstamped(actual) === unstamped(expected)) {
+            return "current";
+        }
+        const writer = STAMP.exec(actual)?.[1];
+        return writer && isNewer(writer, PACKAGE.version) ? `newer (pair ${writer})` : "stale";
     }
     catch (error) {
         if (isMissing(error)) {
@@ -855,13 +868,12 @@ function notificationStatus(channel) {
 }
 function status(channel, root) {
     const lanes = channelAccess(channel, () => AGENTS.map((agent) => describe(channel, agent)));
-    const { name, version } = JSON.parse(readFileSync(join(PACKAGE_ROOT, "package.json"), "utf8"));
     const agents = instructionState(join(root, "AGENTS.md"), codexSection(), true);
     const skill = instructionState(join(root, ".claude", "skills", "pair", "SKILL.md"), claudeSkill());
     return [
         `channel: ${channel}`,
         `worktree: ${root}`,
-        `version: ${name} ${version}`,
+        `version: ${PACKAGE.name} ${PACKAGE.version}`,
         ...lanes,
         "instructions on disk (does not verify what running agents loaded):",
         `  AGENTS.md (pair section): ${agents}`,
@@ -871,8 +883,137 @@ function status(channel, root) {
             ? ["Run `pair init` to refresh missing or stale instructions, then reload agent sessions."] : []),
         ...(agents.startsWith("unreadable") || skill.startsWith("unreadable")
             ? ["Check permissions on the unreadable instruction paths before refreshing them."] : []),
+        ...(agents.startsWith("newer") || skill.startsWith("newer")
+            ? ["A newer pair wrote these instructions: run `pair upgrade` in your own terminal."] : []),
     ].join("\n");
 }
+/**
+ * Rewrites instructions an older pair wrote; leaves missing, unreadable and newer ones for `pair status` to report.
+ * Returns a note for after the command's output: agents read `pair wait`'s first line, with stderr merged.
+ */
+function refreshInstructions(root) {
+    try {
+        return refreshedNote(refreshStale(root));
+    }
+    catch (error) {
+        // A read-only sandbox: message delivery must still work, so report and go on.
+        const reason = error instanceof Error ? error.message : String(error);
+        return `pair: couldn't refresh instructions (${reason}); run \`pair init\` in your own terminal`;
+    }
+}
+/** The stale instruction files it rewrote. A write failure throws. */
+function refreshStale(root) {
+    const skillPath = join(root, ".claude", "skills", "pair", "SKILL.md");
+    const agentsPath = join(root, "AGENTS.md");
+    const refreshed = [];
+    if (instructionState(skillPath, claudeSkill()) === "stale") {
+        writeFileSync(skillPath, claudeSkill());
+        refreshed.push(skillPath);
+    }
+    if (instructionState(agentsPath, codexSection(), true) === "stale") {
+        writeFileSync(agentsPath, readFileSync(agentsPath, "utf8").replace(PAIR_SECTION, () => codexSection()));
+        refreshed.push(`${agentsPath} (pair section)`);
+    }
+    return refreshed;
+}
+function refreshedNote(refreshed) {
+    return refreshed.length > 0
+        ? `pair: refreshed ${refreshed.join(", ")} to pair ${PACKAGE.version}; reload agent sessions to load them`
+        : undefined;
+}
+function unstamped(text) {
+    return text.replace(STAMP, "");
+}
+function isNewer(version, than) {
+    return version.localeCompare(than, "en", { numeric: true }) > 0;
+}
+/** The latest version on npm, checked at most once a day; undefined when opted out or the check fails. */
+async function latestVersion() {
+    if (process.env.PAIR_NO_UPDATE_CHECK) {
+        return undefined;
+    }
+    const cache = join(stateHome(), "latest.json");
+    try {
+        const cached = JSON.parse(readFileSync(cache, "utf8"));
+        if (Date.now() - cached.checkedAt < UPDATE_CHECK_MS && typeof cached.version === "string") {
+            return cached.version;
+        }
+    }
+    catch {
+        // no cache yet, or a corrupt one: check again
+    }
+    let version;
+    try {
+        // ponytail: the public registry, not npm's configured one; read `npm config get registry` if mirrors matter
+        const response = await fetch(`https://registry.npmjs.org/${PACKAGE.name}/latest`, { signal: AbortSignal.timeout(2000) });
+        version = (await response.json()).version;
+    }
+    catch {
+        return undefined; // offline or sandboxed: the notice is best-effort
+    }
+    if (typeof version !== "string") {
+        return undefined;
+    }
+    try {
+        mkdirSync(dirname(cache), { recursive: true });
+        writeFileSync(cache, JSON.stringify({ checkedAt: Date.now(), version }));
+    }
+    catch {
+        // a read-only state dir only means checking again next time
+    }
+    return version;
+}
+async function updateNotice() {
+    const latest = await latestVersion();
+    return latest && isNewer(latest, PACKAGE.version)
+        ? [`update available: ${PACKAGE.name} ${PACKAGE.version} → ${latest}. Run \`pair upgrade\` in your own terminal.`]
+        : [];
+}
+/** Installs the latest pair, then lets the new version refresh this worktree's instructions. */
+function upgrade(root) {
+    // npm's own answer, from the registry it installs from; if it fails, the install reports why.
+    const view = spawnSync("npm", ["view", PACKAGE.name, "version"], { encoding: "utf8" });
+    const latest = view.status === 0 ? view.stdout.trim() : undefined;
+    if (latest && !isNewer(latest, PACKAGE.version)) {
+        let note;
+        try {
+            note = refreshedNote(refreshStale(root)); // refreshing is all that is left to do, so a failure fails upgrade
+        }
+        catch (error) {
+            const reason = error instanceof Error ? error.message : String(error);
+            throw new PairError(`already up to date, but couldn't refresh instructions (${reason})`);
+        }
+        console.log(`already up to date: ${PACKAGE.name} ${PACKAGE.version}${note ? `\n${note}` : ""}`);
+        return 0;
+    }
+    const install = spawnSync("npm", ["install", "--global", `${PACKAGE.name}@latest`], { stdio: "inherit" });
+    if (install.error) {
+        throw new PairError(`couldn't run npm: ${install.error.message}`);
+    }
+    if (install.status !== 0) {
+        return install.status ?? 1;
+    }
+    const states = [
+        instructionState(join(root, ".claude", "skills", "pair", "SKILL.md"), claudeSkill()),
+        instructionState(join(root, "AGENTS.md"), codexSection(), true),
+    ];
+    if (states.some((state) => state !== "missing")) {
+        // The package just installed, not whatever `pair` comes first on PATH, which may be an older copy.
+        const globalRoot = spawnSync("npm", ["root", "--global"], { encoding: "utf8" });
+        if (globalRoot.error || globalRoot.status !== 0) {
+            throw new PairError("installed, but `npm root --global` failed; run `pair init` yourself");
+        }
+        const installed = join(globalRoot.stdout.trim(), PACKAGE.name, "dist", "pair.js");
+        const init = spawnSync(process.execPath, [installed, "init"], { cwd: root, encoding: "utf8", stdio: ["ignore", "pipe", "inherit"] });
+        if (init.error || init.status !== 0) {
+            throw new PairError(`installed, but the new \`pair init\` failed${init.error ? `: ${init.error.message}` : ""}; run it yourself`);
+        }
+        // Only what it did to the files: the sandbox and `codex mcp add` setup it also prints is already done.
+        console.log(init.stdout.split("\n").filter((line) => /^(?:wrote|kept): /.test(line)).join("\n"));
+    }
+    console.log(`upgraded: ${PACKAGE.name} ${PACKAGE.version} → ${latest ?? "latest"}. Restart Claude Code and Codex sessions to load it; other worktrees refresh on their next pair send or wait.`);
+    return 0;
+}
 /** Finished threads, most recently finished first. Entries that aren't archived threads are ignored. */
 function listArchived(channel) {
     const archiveDir = join(channel, "archive");
@@ -953,25 +1094,42 @@ function renderPrompt(agent) {
 }
 function claudeSkill() {
     const header = `---\nname: pair\ndescription: Request a code review from codex after finishing a task, or act as codex's reviewer ("be my reviewer", "listen"), via the pair CLI.\n---\n\n`;
-    return header + renderPrompt("claude");
+    return `${header}<!-- pair ${PACKAGE.version} -->\n${renderPrompt("claude")}`;
 }
 function codexSection() {
-    return `<!-- pair:start -->\n${renderPrompt("codex").trimEnd()}\n<!-- pair:end -->\n`;
+    return `<!-- pair:start -->\n<!-- pair ${PACKAGE.version} -->\n${renderPrompt("codex").trimEnd()}\n<!-- pair:end -->\n`;
 }
 function init(channel, root) {
     channelAccess(channel, () => mkdirSync(channel, { recursive: true }));
+    // Current files keep their stamp too: a newer pair may have written the same text.
+    const kept = (state) => state === "current" ? " (current)" : state.startsWith("newer") ? " (a newer pair wrote it; run `pair upgrade`, or delete it to downgrade)" : undefined;
+    const done = [];
     const skillDir = join(root, ".claude", "skills", "pair");
-    mkdirSync(skillDir, { recursive: true });
-    writeFileSync(join(skillDir, "SKILL.md"), claudeSkill());
+    const skillPath = join(skillDir, "SKILL.md");
+    const skillKept = kept(instructionState(skillPath, claudeSkill()));
+    if (skillKept) {
+        done.push(`kept: ${skillPath}${skillKept}`);
+    }
+    else {
+        mkdirSync(skillDir, { recursive: true });
+        writeFileSync(skillPath, claudeSkill());
+        done.push(`wrote: ${skillPath}`);
+    }
     const agentsPath = join(root, "AGENTS.md");
     const section = codexSection();
-    const existing = existsSync(agentsPath) ? readFileSync(agentsPath, "utf8") : "";
-    const updated = PAIR_SECTION.test(existing) ? existing.replace(PAIR_SECTION, () => section) : `${existing}${existing ? "\n" : ""}${section}`;
-    writeFileSync(agentsPath, updated);
+    const agentsKept = kept(instructionState(agentsPath, section, true));
+    if (agentsKept) {
+        done.push(`kept: ${agentsPath} (pair section)${agentsKept}`);
+    }
+    else {
+        const existing = existsSync(agentsPath) ? readFileSync(agentsPath, "utf8") : "";
+        const updated = PAIR_SECTION.test(existing) ? existing.replace(PAIR_SECTION, () => section) : `${existing}${existing ? "\n" : ""}${section}`;
+        writeFileSync(agentsPath, updated);
+        done.push(`wrote: ${agentsPath} (pair section)`);
+    }
     return [
         `channel: ${channel}`,
-        `wrote: ${join(skillDir, "SKILL.md")}`,
-        `wrote: ${agentsPath} (pair section)`,
+        ...done,
         "",
         sandboxConfig(channel),
         "",
@@ -1017,7 +1175,7 @@ function uninit(channel, root) {
     const skillPath = join(skillDir, "SKILL.md");
     if (existsSync(skillPath)) {
         const skill = readFileSync(skillPath, "utf8");
-        if (skill === claudeSkill() || RELEASED_SKILL_SHA256.includes(createHash("sha256").update(skill).digest("hex"))) {
+        if (unstamped(skill) === unstamped(claudeSkill()) || RELEASED_SKILL_SHA256.includes(createHash("sha256").update(skill).digest("hex"))) {
             rmSync(skillPath);
             removed.push(skillPath);
             // Drop the directories init created, up to the first one that holds something else.
@@ -1240,6 +1398,7 @@ const USAGE = `usage:
   pair history [thread-id]                            (list finished threads, or show one)
   pair clean --keep N                                 (delete all but the N newest finished threads)
   pair init
+  pair upgrade                                        (install the latest pair from npm, then refresh this worktree)
   pair uninit                                         (remove what pair init wrote in this worktree; keeps history)
   pair register | unregister                          (in Codex's shell: let pair_listen notify this session)
   pair mcp                                            (stdio MCP server for Codex, providing pair_listen)
@@ -1254,57 +1413,67 @@ async function main(argv) {
     const root = worktreeRoot();
     const channel = channelDir(root);
     const agent = () => oneOf(values.as ?? process.env.PAIR_AGENT, AGENTS, "--as (or PAIR_AGENT)");
-    switch (command) {
-        case "send": {
-            autoKeep(); // reject a bad PAIR_KEEP before touching any thread
-            const type = oneOf(rest[0], MESSAGE_TYPES, "message type");
-            const verdict = values.verdict === undefined ? undefined : oneOf(values.verdict, VERDICTS, "--verdict");
-            const me = agent();
-            const body = readBody(rest[1]);
-            console.log(`sent: ${channelAccess(channel, () => send(channel, me, type, body, verdict))}`);
-            return 0;
-        }
-        case "wait": {
-            autoKeep(); // reject a bad PAIR_KEEP before touching any thread
-            const me = agent();
-            const timeout = positiveNumber(values.timeout ?? String(DEFAULT_WAIT_SECONDS), "--timeout");
-            if (!(await wait(channel, me, timeout))) {
-                // Exit 0: a timeout is routine, and agent UIs show any non-zero exit as a failure. No "run it
-                // again" here: whether to wait again differs by agent (Codex must not poll), so the prompt says.
-                console.log(`pair: no message for ${me} yet.`);
+    const refreshNote = REFRESHING_COMMANDS.includes(command) ? refreshInstructions(root) : undefined;
+    try {
+        switch (command) {
+            case "send": {
+                autoKeep(); // reject a bad PAIR_KEEP before touching any thread
+                const type = oneOf(rest[0], MESSAGE_TYPES, "message type");
+                const verdict = values.verdict === undefined ? undefined : oneOf(values.verdict, VERDICTS, "--verdict");
+                const me = agent();
+                const body = readBody(rest[1]);
+                console.log(`sent: ${channelAccess(channel, () => send(channel, me, type, body, verdict))}`);
+                return 0;
             }
-            return 0;
-        }
-        case "status":
-            console.log(status(channel, root));
-            return 0;
-        case "history":
-            console.log(channelAccess(channel, () => history(channel, rest[0])));
-            return 0;
-        case "clean":
-            console.log(channelAccess(channel, () => clean(channel, values.keep)));
-            return 0;
-        case "init":
-            console.log(init(channel, root));
-            return 0;
-        case "uninit":
-            console.log(uninit(channel, root));
-            return 0;
-        case "register":
-            console.log(channelAccess(channel, () => register(channel, root)));
-            return 0;
-        case "unregister":
-            console.log(channelAccess(channel, () => unregister(channel)));
-            return 0;
-        case "mcp":
-            await serveMcp();
-            return 0;
-        case "ps":
-            console.log(ps(values.verbose ?? false));
-            return 0;
-        default:
-            console.error(USAGE);
-            return 1;
+            case "wait": {
+                autoKeep(); // reject a bad PAIR_KEEP before touching any thread
+                const me = agent();
+                const timeout = positiveNumber(values.timeout ?? String(DEFAULT_WAIT_SECONDS), "--timeout");
+                if (!(await wait(channel, me, timeout))) {
+                    // Exit 0: a timeout is routine, and agent UIs show any non-zero exit as a failure. No "run it
+                    // again" here: whether to wait again differs by agent (Codex must not poll), so the prompt says.
+                    console.log(`pair: no message for ${me} yet.`);
+                }
+                return 0;
+            }
+            case "status":
+                console.log([status(channel, root), ...(await updateNotice())].join("\n"));
+                return 0;
+            case "history":
+                console.log(channelAccess(channel, () => history(channel, rest[0])));
+                return 0;
+            case "clean":
+                console.log(channelAccess(channel, () => clean(channel, values.keep)));
+                return 0;
+            case "init":
+                console.log([init(channel, root), ...(await updateNotice())].join("\n"));
+                return 0;
+            case "upgrade":
+                return upgrade(root);
+            case "uninit":
+                console.log(uninit(channel, root));
+                return 0;
+            case "register":
+                console.log(channelAccess(channel, () => register(channel, root)));
+                return 0;
+            case "unregister":
+                console.log(channelAccess(channel, () => unregister(channel)));
+                return 0;
+            case "mcp":
+                await serveMcp();
+                return 0;
+            case "ps":
+                console.log(ps(values.verbose ?? false));
+                return 0;
+            default:
+                console.error(USAGE);
+                return 1;
+        }
+    }
+    finally {
+        if (refreshNote) {
+            console.error(refreshNote);
+        }
     }
 }
 main(process.argv.slice(2)).then((code) => {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "claude-codex-pair",
-  "version": "0.3.1",
+  "version": "0.4.1",
   "description": "Claude Code and Codex review each other's work over a file-system chat channel",
   "keywords": [
     "claude-code",