claude-codex-pair 0.3.0 → 0.4.0

package/DESIGN.md

@@ -74,7 +74,19 @@ 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.
 
 Channel operations report `EACCES` and `EPERM` with the affected path and the sandbox
 configuration printed by `init`. Either ordinary permissions or sandbox restrictions can
@@ -168,5 +180,5 @@ pair mcp
   - Two worktrees each woke only their own session.
   - With Codex as the author, a `changes` review and the final approval each woke it once, and its `pair wait` archived the approved thread.
   - Approval policy `never` makes `pair_listen` fail, and Codex reports it and stops without polling.
-- The MCP server is a child of the app-server daemon, not of the TUI. After the last TUI on a session quit, it ran 1–2 more minutes, until the daemon unloaded the session. A message in that gap still wakes the session with no TUI attached. Desktop and IDE sessions, `--no-daemon`, and `--remote` are untested.
+- The MCP server is a child of the app-server daemon, not of the TUI. After the last TUI on a session quit, it ran 1–2 more minutes, until the daemon unloaded the session. A message in that gap still wakes the session with no TUI attached. The ChatGPT desktop app runs its own app-server, which starts its own `pair mcp`; waking its sessions worked, with `PAIR_CODEX` pointing at the separately installed CLI. IDE sessions, `--no-daemon`, and `--remote` are untested.
 - Completion-driven waiting is verified only for interactive Claude Code sessions, with waits of up to a few minutes. A full hour is untested. Headless `claude -p` ends background commands after its final result, so the prompt falls back to a foreground wait. Codex was tried with one long `pair wait` that it kept checking. Its built-in instructions cap each check at about 60 seconds, so an idle Codex made a model call every minute, enough to run a workspace out of credits. A finished background command doesn't resume Codex (measured with CLI 0.162.1), which is why Codex uses `pair mcp` instead.

package/README.md

@@ -101,9 +101,12 @@ pending. The note never contains message text. Codex reads the message itself wi
   - two worktrees each woke only their own Codex;
   - with Codex as the author, a `changes` review and the final approval each woke it once, and its
     `pair wait` archived the approved thread;
-  - the `never` approval policy failed.
+  - the `never` approval policy failed;
+  - with Codex CLI 0.163.0, a session idle for about 2 hours was still woken 0.9s after the request
+    and replied 9s after it.
 
-  Desktop and IDE sessions are untested.
+  Codex in the ChatGPT desktop app works too: the app starts its own `pair mcp`, and in daily use
+  with Codex as the author, each review woke it and it replied. IDE sessions are untested.
 - `pair status` shows the registered session and the listener's last event. The full log is
   `~/.local/state/pair/<repo>-<hash>/codex.listen.log` (under `$XDG_STATE_HOME` if it is absolute).
   The server writes only there, never in the channel, which agents can write. At 256 KB it becomes
@@ -155,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|->
@@ -164,10 +167,11 @@ 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")
-pair ps                    # list running pair mcp and pair wait processes, where they run, and what started them
+pair ps [-v]               # running pair mcp and pair wait processes by worktree, with each worktree's Codex registration (-v: full commands)
 ```
 
 `pair status` shows the channel, worktree root, installed package version, and each lane's turn.
@@ -186,11 +190,26 @@ 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. It runs `npm install -g claude-codex-pair@latest`, then the new `pair init` in the
+current worktree if pair is set up there. 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
@@ -203,6 +222,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";
@@ -117,9 +123,10 @@ function currentThreadDir(thread) {
 function newThreadId() {
     return `${new Date().toISOString().replace(/[:.]/g, "-")}-${randomBytes(3).toString("hex")}`;
 }
-function gitPath(flag) {
+function gitPath(flag, cwd) {
     try {
         return execFileSync("git", ["rev-parse", "--path-format=absolute", flag], {
+            cwd,
             encoding: "utf8",
             stdio: ["ignore", "pipe", "ignore"],
         }).trim();
@@ -505,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 {
@@ -816,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)) {
@@ -854,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}`,
@@ -870,8 +883,113 @@ 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) {
+    const skillPath = join(root, ".claude", "skills", "pair", "SKILL.md");
+    const agentsPath = join(root, "AGENTS.md");
+    const refreshed = [];
+    try {
+        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)`);
+        }
+    }
+    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`;
+    }
+    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) {
+    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, stdio: "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`);
+        }
+    }
+    console.log("Restart Claude Code and Codex sessions to load the new version. 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");
@@ -952,25 +1070,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),
         "",
@@ -1016,7 +1151,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.
@@ -1092,7 +1227,7 @@ function workingDirs(pids) {
     }
     let out = "";
     try {
-        out = execFileSync("lsof", ["-a", "-d", "cwd", "-Fpn", "-p", pids.join(",")], { encoding: "utf8" });
+        out = execFileSync("lsof", ["-w", "-a", "-d", "cwd", "-Fpn", "-p", pids.join(",")], { encoding: "utf8", stdio: ["ignore", "pipe", "ignore"] });
     }
     catch (error) {
         // lsof exits 1 when one of the pids is gone, but still prints the rest
@@ -1109,30 +1244,109 @@ function workingDirs(pids) {
     }
     return dirs;
 }
-/** Every running `pair mcp` and `pair wait` on this machine, with what started it. */
-function ps() {
+/** A short name for what started a pair process; `pair ps -v` shows the full command. */
+function hostName(command) {
+    if (command.includes("/ChatGPT.app/")) {
+        return "ChatGPT app";
+    }
+    const daemon = /\/app-server-daemon\/releases\/(\d[\w.]*?)-/.exec(command);
+    if (daemon) {
+        return `Codex CLI ${daemon[1]}`;
+    }
+    const [argv0 = "", ...args] = command.split(" ");
+    const name = basename(argv0);
+    if (name === "claude") {
+        const worktree = /--worktree (\S+)/.exec(command)?.[1];
+        const session = /--resume ([0-9a-f]{8})/.exec(command)?.[1];
+        const hint = worktree ? `worktree ${worktree}` : session ? `resume ${session}` : args.includes("--resume") ? "resume" : "";
+        return hint ? `Claude Code (${hint})` : "Claude Code";
+    }
+    return name === "codex" ? "Codex CLI" : name;
+}
+function age(started) {
+    const minutes = Math.max(0, Math.floor((Date.now() - new Date(started).getTime()) / 60_000));
+    if (minutes < 60) {
+        return `${minutes}m`;
+    }
+    return minutes < 24 * 60 ? `${Math.floor(minutes / 60)}h` : `${Math.floor(minutes / (24 * 60))}d`;
+}
+/** `~` for home, and only the last four parts of a long path. */
+function shortPath(path) {
+    const home = homedir();
+    const tilde = path === home || path.startsWith(`${home}${sep}`) ? `~${path.slice(home.length)}` : path;
+    const parts = tilde.split(sep);
+    return tilde.length > 40 && parts.length > 5 ? [parts[0], "…", ...parts.slice(-4)].join(sep) : tilde;
+}
+/**
+ * The worktree's registered Codex session and when pair last woke it, or undefined. It reads with this shell's
+ * PAIR_HOME and XDG_STATE_HOME, which may not be the agents', so it only reports what it finds, never an absence.
+ */
+function codexLine(root) {
+    const channel = channelDir(root);
+    try {
+        const registration = readRegistration(channel);
+        if (!registration) {
+            return undefined;
+        }
+        const mine = ` notified ${registration.thread} about `; // not a note to an earlier session
+        const log = join(stateDir(channel), LISTEN_LOG);
+        const notified = existsSync(log) ? readChannelFile(log).trimEnd().split("\n").findLast((line) => line.includes(mine)) : undefined;
+        const id = registration.thread.slice(0, 8);
+        return notified ? `registered ${id} · last note ${age(notified.split(" ")[0])} ago` : `registered ${id}`;
+    }
+    catch (error) {
+        return error instanceof Error ? error.message : String(error);
+    }
+}
+/** Every running `pair mcp` and `pair wait` on this machine, grouped by worktree. */
+function ps(verbose) {
     const all = listProcesses();
     const byPid = new Map(all.map((proc) => [proc.pid, proc]));
     const ours = all.flatMap((proc) => {
         const match = PAIR_PROCESS.exec(proc.command);
-        return match ? [{ ...proc, args: match[1] }] : [];
+        if (!match) {
+            return [];
+        }
+        let host = byPid.get(proc.ppid);
+        while (host && SHELL.test(host.command)) {
+            host = byPid.get(host.ppid); // an agent runs pair wait through a shell; show the agent
+        }
+        return [{ ...proc, kind: match[1].startsWith("mcp") ? "mcp" : "wait", host }];
     });
     if (ours.length === 0) {
         return "no pair mcp or pair wait is running";
     }
     const dirs = workingDirs(ours.map((proc) => proc.pid));
-    return ours
-        .flatMap((proc) => {
-        let host = byPid.get(proc.ppid);
-        while (host && SHELL.test(host.command)) {
-            host = byPid.get(host.ppid); // an agent runs pair wait through a shell; show the agent
+    const groups = new Map();
+    for (const proc of ours) {
+        const dir = dirs.get(proc.pid) ?? "?";
+        const top = dir === "?" ? undefined : gitPath("--show-toplevel", dir);
+        const root = top ? realpathOrSelf(top) : undefined;
+        const key = root ?? dir;
+        const group = groups.get(key) ?? { root, procs: [] };
+        group.procs.push(proc);
+        groups.set(key, group);
+    }
+    const blocks = [...groups].sort(([a, x], [b, y]) => Number(!x.root) - Number(!y.root) || a.localeCompare(b));
+    return blocks
+        .map(([path, { root, procs }]) => {
+        const name = root ? basename(root) : path !== "?" && !existsSync(path) ? "(deleted)" : "(no worktree)";
+        const lines = [`${name}  ${shortPath(path)}`];
+        const codex = root ? codexLine(root) : undefined;
+        if (codex) {
+            lines.push(`  codex   ${codex}`);
         }
-        return [
-            `pair ${proc.args}  pid ${proc.pid}  since ${proc.started}  in ${dirs.get(proc.pid) ?? "?"}`,
-            `  started by ${host ? `${host.pid}: ${host.command.slice(0, 160)}` : `${proc.ppid} (gone)`}`,
-        ];
+        procs.sort((a, b) => a.kind.localeCompare(b.kind) || a.pid - b.pid);
+        for (const proc of procs) {
+            const host = proc.host ? hostName(proc.host.command) : `⚠ parent gone (${proc.ppid})`;
+            lines.push(`  ${proc.kind.padEnd(6)}  ${String(proc.pid).padEnd(6)} ${age(proc.started).padEnd(4)} ${host}`);
+            if (verbose && proc.host) {
+                lines.push(`          started by ${proc.host.pid}: ${proc.host.command}`);
+            }
+        }
+        return lines.join("\n");
     })
-        .join("\n");
+        .join("\n\n");
 }
 function readBody(source) {
     if (!source) {
@@ -1160,71 +1374,82 @@ 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)
-  pair ps                                             (list running pair mcp and pair wait processes)`;
+  pair ps [-v]                                        (running pair mcp and pair wait processes, by worktree; -v: full commands)`;
 async function main(argv) {
     const { values, positionals } = parseArgs({
         args: argv,
         allowPositionals: true,
-        options: { as: { type: "string" }, verdict: { type: "string" }, timeout: { type: "string" }, keep: { type: "string" } },
+        options: { as: { type: "string" }, verdict: { type: "string" }, timeout: { type: "string" }, keep: { type: "string" }, verbose: { type: "boolean", short: "v" } },
     });
     const [command, ...rest] = positionals;
     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());
-            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.0",
+  "version": "0.4.0",
   "description": "Claude Code and Codex review each other's work over a file-system chat channel",
   "keywords": [
     "claude-code",