claude-codex-pair 0.2.0 → 0.3.1

package/DESIGN.md

@@ -168,5 +168,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
@@ -167,6 +170,7 @@ pair init
 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 [-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.
@@ -175,7 +179,7 @@ It also checks the generated instructions on disk:
 ```
 channel: /Users/you/.pair/your-repo-12345678
 worktree: /Users/you/your-repo
-version: claude-codex-pair 0.1.0
+version: claude-codex-pair 0.2.0
 claude-to-codex: idle
 codex-to-claude: idle
 instructions on disk (does not verify what running agents loaded):

package/dist/pair.js

@@ -117,9 +117,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();
@@ -1059,6 +1060,160 @@ function uninit(channel, root) {
     const summary = removed.length > 0 ? removed.map((item) => `removed: ${item}`) : [`nothing from pair init found in ${root}`];
     return [...summary, ...notes].join("\n");
 }
+const PS_LINE = /^\s*(\d+)\s+(\d+)\s+(\w{3} \w{3}\s+\d+ [\d:]+ \d{4})\s+(.*)$/; // lstart is always 5 fields
+// node itself runs the script, so a wrapper whose command line mentions it (`zsh -c "… pair.js wait"`) doesn't match
+const PAIR_PROCESS = /^(?:\S*\/)?node(?: -\S+)* \S*\/(?:bin\/pair|dist\/pair\.js) ((?:mcp|wait)\b.*)$/;
+const SHELL = /^(?:\S*\/)?(?:zsh|bash|sh|dash|fish)(?: |$)/;
+function listProcesses() {
+    let out;
+    try {
+        out = execFileSync("ps", ["-axo", "pid=,ppid=,lstart=,command="], { encoding: "utf8", env: { ...process.env, LC_ALL: "C" } });
+    }
+    catch (error) {
+        throw new PairError(`can't list processes (${error instanceof Error ? error.message : String(error)}); agent sandboxes often block ps, so run pair ps in your own terminal`);
+    }
+    return out.split("\n").flatMap((line) => {
+        const match = PS_LINE.exec(line);
+        return match ? [{ pid: Number(match[1]), ppid: Number(match[2]), started: match[3], command: match[4] }] : [];
+    });
+}
+/** Working directories by pid: /proc on Linux, lsof elsewhere. Unknown ones are left out. */
+function workingDirs(pids) {
+    const dirs = new Map();
+    if (existsSync("/proc/self/cwd")) {
+        for (const pid of pids) {
+            try {
+                dirs.set(pid, realpathSync(`/proc/${pid}/cwd`));
+            }
+            catch {
+                // gone, or not ours
+            }
+        }
+        return dirs;
+    }
+    let out = "";
+    try {
+        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
+        out = error instanceof Error && "stdout" in error ? String(error.stdout) : "";
+    }
+    let pid = 0;
+    for (const line of out.split("\n")) {
+        if (line.startsWith("p")) {
+            pid = Number(line.slice(1));
+        }
+        else if (line.startsWith("n")) {
+            dirs.set(pid, line.slice(1));
+        }
+    }
+    return dirs;
+}
+/** 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);
+        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));
+    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}`);
+        }
+        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\n");
+}
 function readBody(source) {
     if (!source) {
         throw new PairError("send needs a message file, or - for stdin");
@@ -1087,12 +1242,13 @@ const USAGE = `usage:
   pair init
   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 mcp                                            (stdio MCP server for Codex, providing pair_listen)
+  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();
@@ -1143,6 +1299,9 @@ async function main(argv) {
         case "mcp":
             await serveMcp();
             return 0;
+        case "ps":
+            console.log(ps(values.verbose ?? false));
+            return 0;
         default:
             console.error(USAGE);
             return 1;

package/package.json

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