claude-codex-pair 0.3.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,7 +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                    # 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.

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();
@@ -1092,7 +1093,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 +1110,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}`);
+        }
+        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 [
-            `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)`}`,
-        ];
+        return lines.join("\n");
     })
-        .join("\n");
+        .join("\n\n");
 }
 function readBody(source) {
     if (!source) {
@@ -1163,12 +1243,12 @@ const USAGE = `usage:
   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();
@@ -1220,7 +1300,7 @@ async function main(argv) {
             await serveMcp();
             return 0;
         case "ps":
-            console.log(ps());
+            console.log(ps(values.verbose ?? false));
             return 0;
         default:
             console.error(USAGE);

package/package.json

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