claude-codex-pair 0.1.1 → 0.3.0

package/DESIGN.md

@@ -10,8 +10,8 @@ and they talk through a shared directory that works like a chat channel.
 | Topology | Two live sessions. No headless spawning. |
 | Roles | Symmetric. Either agent can author or review. |
 | Interface | One `pair` CLI (Node/TS). The agents learn it from a thin prompt: a Claude skill and an AGENTS.md section for Codex. |
-| Waiting | `pair wait` checks the files every second and returns as soon as a message arrives. By default it gives up after 540s, printing `no message … yet` and exiting 0 (agent UIs show any non-zero exit as a failure), which keeps a foreground run under Claude Code's 10-minute Bash cap. Interactive Claude Code sessions run `pair wait --timeout 3600` as a background command and spend no model turns until it exits. Codex starts one `pair wait --timeout 3600` and checks on the running command. In the sessions observed so far, its instructions limit each check (a single blocking tool wait) to 60 seconds and ask for a progress update at least every minute, so an idle Codex wakes about once a minute to check. That limit applies to each check, not to how long the command runs, so Codex doesn't restart `pair wait` every minute. Headless runs wait in the foreground. |
-| Pickup | The reviewer runs `pair wait` in a loop ("be my reviewer"). |
+| Waiting | `pair wait` checks the files every second and returns as soon as a message arrives. By default it gives up after 540s, printing `no message … yet` and exiting 0 (agent UIs show any non-zero exit as a failure), which keeps a foreground run under Claude Code's 10-minute Bash cap. Interactive Claude Code sessions run `pair wait --timeout 3600` as a background command and spend no model turns until it exits. Codex can't do the same, because a finished background command doesn't resume it. Instead, pair's MCP server queues a fixed note into the Codex session when a message is pending (see Notifications), so an idle Codex makes no model calls. Codex never polls, because each check of a running command is a model call: without the MCP server it checks once and the user asks it to check again. Headless runs wait in the foreground. |
+| Pickup | The reviewer waits in a loop ("be my reviewer"): Claude on a background `pair wait`, Codex woken by `pair mcp`. |
 | Request | The author's summary plus a list of files. The reviewer reads the files from the shared repo. |
 | Review | Numbered findings with severity, and a verdict of `approve` or `changes`. Multiple rounds. |
 | Disputes | Cap of 3 rounds (`PAIR_MAX_ROUNDS`). A review that still says `changes` at the cap marks the thread `escalated`, and both agents stop to ask the user. |
@@ -31,6 +31,11 @@ and they talk through a shared directory that works like a chat channel.
       004-review.md                   # round 2, verdict approve, status approved
   codex-to-claude/
   archive/<iso-ts>-<rand>-<lane>-<approved|escalated>/
+  codex.session                       # Codex session that pair_listen may notify (pair register)
+
+${XDG_STATE_HOME:-~/.local/state}/pair/<repo>-<hash>/   # written only by pair mcp, outside agent sandboxes
+  codex.listen.log                    # what the MCP listener did, newest last; .1 holds the previous 256 KB
+  claims/<thread>.<message file>.<session id>
 ```
 
 Each message has this frontmatter, written by the CLI: `from`, `type`, `round`, `verdict` (reviews only), and `status` (`open`/`approved`/`escalated`).
@@ -77,6 +82,56 @@ cause these failures. Input message files, instruction files, and installed asse
 separately. Automatic pruning still warns and continues; its diagnostics follow the delivered
 message so `wait` keeps its protocol header first even when stdout and stderr are merged.
 
+## Notifications
+
+`codex queue --thread <id> --message <text>` starts a turn in an idle Codex session, and queues
+behind a busy one. It works only outside both sandboxes, because it opens Codex's state databases
+under `~/.codex` read-write. Claude's sandbox can't run it unless it's given write access to
+`~/.codex`, which holds Codex's own config. So `send` doesn't call it. Instead, `pair mcp` runs as
+a stdio MCP server that Codex starts outside its shell sandbox.
+
+1. Codex runs `pair register` in its shell. The CLI writes `codex.session` with `CODEX_THREAD_ID`,
+   which Codex sets in its shell environment, into the channel of that shell's worktree.
+2. Codex calls `pair_listen`, which takes no arguments. The server reads the session id from the
+   call's `_meta.threadId`, which Codex sets, and requires exactly one channel whose `codex.session`
+   names that id. The model supplies no id or path, and the server's own cwd is never used.
+3. Every second, the server reads `pendingFor(channel, "codex")`. It never calls `wait`, so it
+   never archives anything. When the newest pending message file differs from the last one it
+   announced, it runs `codex queue` with a fixed note telling Codex to run `pair wait --timeout 5`.
+   Message text never goes into the note, so the partner's words never arrive as user input. Before
+   every dispatch it checks that `codex.session` still names its session. `pair unregister` or a
+   newer `pair register` stops it.
+
+Before sending, a server creates a claim file for the message and session, using an exclusive
+create, and writes `sending` in it. Only the server that creates it sends the note, so
+two Codex processes attached to one session, or a repeated `pair_listen`, don't send it twice. After
+`codex queue` succeeds, the claim says `sent`. Other servers then treat the message as notified.
+While it says `sending`, they wait. If `codex queue` fails, the claim is removed, so the retry can
+claim it again. If a claim still says `sending` after 60s, twice the queue timeout, its sender died
+mid-send, and the next server takes it over. Two servers taking over at the same moment can both
+send, which costs one extra short turn. A queue call that accepted the note but timed out before
+exiting can also be retried and send one extra note. Claims older than 7 days are deleted when a
+session starts listening.
+
+The server runs outside both sandboxes, and agents can write the channel. An agent could replace a
+file there, or a whole directory on the path to it, with a symlink, and could do it between any
+check and the write that follows. So `pair mcp` never writes in a channel. Its log and claims live
+in `${XDG_STATE_HOME:-~/.local/state}/pair/`; relative `XDG_STATE_HOME` values are ignored. Agent
+sandboxes cannot write there by default. The server still reads the channel, opening those files
+with `O_NOFOLLOW`. It runs `PAIR_CODEX`, an absolute path set when the server is registered, never
+`codex` from `PATH`, because an agent-writable `PATH` entry would turn the fixed call into
+unsandboxed code execution.
+
+A message is announced once. A failed `codex queue` is retried with backoff up to 60s. If a message
+is still pending 10 minutes after its note, the server logs a stall warning and doesn't announce it
+again: the turn may have failed or been cancelled, may be waiting for an approval, or the review may
+just be long. Watches live in the MCP process. Codex's app-server daemon starts it and ends it when it unloads
+the session, which took 1–2 minutes after the last TUI on that session quit. Until then, a new
+message still starts a turn with no TUI attached. `pair unregister` stops notifications right away.
+A note already accepted by the daemon still runs either way, so the prompt tells Codex to ignore a
+note that arrives after the user said stop. A repeated note costs one short
+turn: `pair wait --timeout 5` prints `no message` and Codex ends its turn.
+
 ## Usage
 
 ```
@@ -95,6 +150,9 @@ pair status
 pair history [thread-id]
 pair clean --keep N
 pair init
+pair uninit
+pair register | unregister
+pair mcp
 ```
 
 ## Known limits
@@ -102,4 +160,13 @@ pair init
 - A lane still in the old flat layout (before 1c588ed) isn't migrated. Commands fail with a hint to move its files into a subdirectory, and the messages are left untouched.
 - Polling, not fs events. A 1s delay is fine for chat between agents.
 - Archiving is safe against concurrent readers and stale `wait`s. A thread disappearing mid-read counts as closed. A stale archive can only target its own, already-archived directory, so it never touches a newer thread.
-- 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's built-in instructions (observed in these sessions: no blocking sleep or wait call over 60 seconds, and a progress update at least every minute) outrank a repo prompt, so the prompt leaves the length of each check to those instructions and only fixes the command's lifetime. Two earlier versions got this wrong. One asked for a 5-minute check window, which conflicted with the cap. The next applied the cap to the command itself (`--timeout 55`), so Codex restarted `pair wait` every minute and each run showed up as a separate entry. Whether Codex resumes automatically after ending its turn is unverified.
+- Notifications are verified end to end with Codex CLI 0.162.1 on the shared app-server daemon. A registered session that had ended its turn was woken about 1s after Claude's request, then reviewed and replied in one turn. Other cases also verified:
+  - A message sent while Codex was closed was queued about 1s after `pair_listen` on resume.
+  - `pair unregister` stopped the watch.
+  - A fork's `register` stopped the original session's watch within 40ms.
+  - Two TUIs on one session share one MCP process and got one note.
+  - 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.
+- 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

@@ -60,14 +60,74 @@ writable_roots = ["/Users/you/.pair"]
 "sandbox": { "filesystem": { "allowWrite": ["~/.pair"] } }
 ```
 
+### Let pair wake Codex (needed for automatic pickup)
+
+Codex can't wait in the background the way Claude Code does: a finished background command doesn't
+resume it, and keeping a `pair wait` running costs a model call for every check. So Codex doesn't
+poll. Pair's MCP server wakes it when a message arrives. Without the server, Codex checks once, tells
+you it can't be woken, and checks again only when you ask ("check pair"). Register the server once;
+`pair init` prints this command with your actual paths:
+
+```sh
+codex mcp add --env 'PAIR_CODEX=/opt/homebrew/bin/codex' pair -- '/path/to/node_modules/claude-codex-pair/dist/pair.js' mcp
+```
+
+Codex then runs `pair register` in its shell and calls the `pair_listen` tool before it waits. The
+MCP server watches the channel and runs `codex queue` with a fixed note when a message for Codex is
+pending. The note never contains message text. Codex reads the message itself with `pair wait`.
+
+- Point the command at the installed package, not at a checkout you edit. `PAIR_CODEX` pins the
+  `codex` executable the server runs. The server runs outside Codex's sandbox, so it never looks
+  `codex` up on `PATH`. It only reads the channel and keeps its own writes in a state directory
+  (see below). `pair init` won't pin a
+  `codex` that is in, or links into, the worktree, the channel directory, or a temp directory,
+  because agents can write there.
+- Codex starts MCP servers with only a few variables from your shell, such as `HOME` and `PATH`.
+  If you set `PAIR_HOME` or `XDG_STATE_HOME`, `pair init` adds them to the command. If you change
+  them later, run `codex mcp remove pair` and add the server again.
+- `pair_listen` needs MCP tool approval, so Codex's `never` approval policy is unsupported. With
+  `on-request`, approve the first call.
+- Notifications stop when Codex runs `pair unregister` ("stop as reviewer"), or when Codex's
+  background service unloads the session, which happened 1–2 minutes after the last window on it
+  closed. A message that arrives in that gap still starts a turn with no window attached, and so does
+  a note that pair already queued. Say "stop as reviewer" before closing Codex if that matters.
+- Verified end to end with Codex CLI 0.162.1 on the shared app-server daemon. A registered session
+  that ended its turn was woken by the note about 1s after Claude's request, and it reviewed and
+  replied in one turn. These also behaved as described:
+  - a message that arrived while Codex was closed was delivered right after resume;
+  - `pair unregister` stopped notifications;
+  - a forked session took over the registration;
+  - two windows on one session got one note;
+  - 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.
+
+  Desktop and 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
+  `codex.listen.log.1`, replacing the previous one.
+
+### Start the agents
+
 After setup, start Claude Code and Codex in separate terminals in the same worktree of this repo. Each
 worktree has its own channel, so an agent started in another checkout won't see the messages
 (see [Worktrees](#worktrees)). Restart any sessions that were already open so they load the new
 instructions and sandbox settings.
 
+## Upgrading from 0.1.x
+
+Codex no longer keeps a long `pair wait` running. To keep automatic pickup after upgrading, install
+the new package with `npm install -g claude-codex-pair`, run `pair init` in each worktree, run the
+printed `codex mcp add` command once, and restart Codex with an approval policy that permits MCP
+tools (`-a on-request` worked in the live test). Without the MCP server, Codex checks once and then
+checks again only when you ask it to "check pair", whether it is the author or reviewer.
+
 ## Use
 
-1. In the reviewer's terminal, say **"be my reviewer"**. The agent loops on `pair wait`.
+1. In the reviewer's terminal, say **"be my reviewer"**. Claude waits on `pair wait` in a background
+   command. Codex registers with pair's MCP server and ends its turn until a message wakes it.
 2. In the author's terminal, finish a task and say **"ask codex for a review"** (or "ask claude").
 3. Watch them go back and forth. The author verifies each finding before fixing it, and can reject
    one with a reason.
@@ -99,11 +159,15 @@ The agents run `send` and `wait` themselves. You'll mostly use `init`, `status`,
 
 ```
 pair send <request|review|response> --as <claude|codex> [--verdict approve|changes] <file|->
-pair wait --as <claude|codex> [--timeout seconds]   # prints "no message … yet" on timeout: run again
+pair wait --as <claude|codex> [--timeout seconds]   # prints "no message … yet" on timeout
 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 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 status` shows the channel, worktree root, installed package version, and each lane's turn.
@@ -112,12 +176,14 @@ 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):
   AGENTS.md (pair section): current
   .claude/skills/pair/SKILL.md: current
+codex notifications: session 01a13922-c08f-79e3-a41f-6780876fd9c5, registered 2026-10-14T08:00:00.000Z
+  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
@@ -133,11 +199,33 @@ so a cleanup problem doesn't prevent delivering a review or starting the next th
 
 | Env var | Default | Meaning |
 |---|---|---|
-| `PAIR_HOME` | `~/.pair` | Root directory for channels |
+| `PAIR_HOME` | `~/.pair` | Root directory for channels. A relative path resolves against the worktree root; empty means the default |
 | `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 |
 
+## Uninstall
+
+In each worktree where you ran `pair init`:
+
+```sh
+pair uninit
+```
+
+This removes three things: `.claude/skills/pair/SKILL.md`, the pair section of `AGENTS.md` (or the
+whole file, if it held nothing else), and the Codex session registration. It also cleans up files
+written by older versions, and it leaves your own content alone: text outside the pair section stays
+as it was, and a `SKILL.md` you edited is kept and reported. Message history stays in
+`~/.pair/<repo>-<hash>/` and `~/.local/state/pair/<repo>-<hash>/`; `pair uninit` prints the
+`rm -rf` command to delete it. Once no repo uses pair, also run:
+
+```sh
+codex mcp remove pair
+npm uninstall -g claude-codex-pair
+```
+
+Then remove `~/.pair` from the sandbox settings you added during setup.
+
 ## Example review
 
 These are messages from a real run, shortened. The bug in round 1 was planted on purpose.

package/dist/pair.js

@@ -1,9 +1,10 @@
 #!/usr/bin/env node
-import { execFileSync } from "node:child_process";
+import { execFile, execFileSync } from "node:child_process";
 import { createHash, randomBytes } from "node:crypto";
-import { existsSync, mkdirSync, readdirSync, readFileSync, realpathSync, renameSync, rmSync, statSync, writeFileSync } from "node:fs";
-import { homedir } from "node:os";
-import { basename, dirname, join, resolve } from "node:path";
+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";
+import { basename, delimiter, dirname, isAbsolute, join, resolve, sep } from "node:path";
+import { createInterface } from "node:readline";
 import { setTimeout as sleep } from "node:timers/promises";
 import { fileURLToPath } from "node:url";
 import { parseArgs } from "node:util";
@@ -19,11 +20,27 @@ const MESSAGE_FILE = /^(\d{3})-(request|review|response)\.md$/;
 // archive/<thread id>-<author>-to-<reviewer>-<outcome>; the id starts with a timestamp
 const ARCHIVED_THREAD = /^(.+)-(claude|codex)-to-(claude|codex)-(approved|escalated)$/;
 const PAIR_SECTION = /<!-- pair:start -->[\s\S]*?<!-- pair:end -->\n?/;
+const PAIR_SECTIONS = /<!-- pair:start -->[\s\S]*?<!-- pair:end -->(?:\r?\n)?/g; // for removal, CRLF too
+// 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 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";
+const LISTEN_LOG_MAX_BYTES = 256 * 1024; // then it becomes codex.listen.log.1, replacing the previous one
+const CLAIM_MAX_AGE_MS = 7 * 24 * 60 * 60 * 1000;
+const STALL_MS = 10 * 60 * 1000;
+const QUEUE_TIMEOUT_MS = 30_000;
+const CLAIM_LEASE_MS = 2 * QUEUE_TIMEOUT_MS; // longer than any live `codex queue` call can hold a claim
+// Fixed text on purpose: nothing from the channel may reach Codex as user input.
+const NUDGE = "pair: a message is waiting for you. Run `pair wait --as codex --timeout 5`, act on what it prints as the pair instructions in AGENTS.md describe, send your reply if one is due, then end your turn. Don't start another pair wait.";
 class PairError extends Error {
 }
+function hasCode(error, code) {
+    return error instanceof Error && "code" in error && error.code === code;
+}
 function isMissing(error) {
-    return error instanceof Error && "code" in error && error.code === "ENOENT";
+    return hasCode(error, "ENOENT");
 }
 function sandboxConfig(channel) {
     const pairHome = JSON.stringify(dirname(channel));
@@ -115,11 +132,16 @@ function gitPath(flag) {
 function worktreeRoot() {
     return realpathSync(gitPath("--show-toplevel") ?? process.cwd());
 }
+/** A relative PAIR_HOME resolves against the worktree root, not cwd, so every subdirectory finds one channel. */
+function pairHome(root) {
+    const configured = process.env.PAIR_HOME;
+    return configured ? resolve(root, configured) : join(homedir(), ".pair"); // empty means unset
+}
 function channelDir(root) {
     // One channel per worktree: a reviewer reads the author's files, so both must share a checkout.
     // realpath so /tmp/x and /private/tmp/x (or any symlinked checkout) share one channel.
     const hash = createHash("sha1").update(root).digest("hex").slice(0, 8);
-    return join(resolve(process.env.PAIR_HOME ?? join(homedir(), ".pair")), `${basename(root)}-${hash}`);
+    return join(pairHome(root), `${basename(root)}-${hash}`);
 }
 function parseFrontmatter(text) {
     const match = /^---\n([\s\S]*?)\n---\n?/.exec(text);
@@ -137,7 +159,7 @@ function parseFrontmatter(text) {
 }
 /** Parses a stored message and rejects anything the CLI would not have written. */
 function readMessage(path, thread) {
-    const { fields, body } = parseFrontmatter(readFileSync(path, "utf8"));
+    const { fields, body } = parseFrontmatter(readChannelFile(path));
     const corrupt = `corrupt message ${path}:`;
     const type = oneOf(fields.type, MESSAGE_TYPES, `${corrupt} type`);
     if (!basename(path).endsWith(`-${type}.md`)) {
@@ -367,6 +389,417 @@ async function wait(channel, me, timeoutSeconds) {
         await sleep(POLL_MS);
     }
 }
+/**
+ * `pair mcp` runs outside the agents' sandboxes, but agents can write the channel. So the files it
+ * opens there must never be symlinks, or an agent could make it read or write any file.
+ */
+function openChannelFile(path, flags) {
+    try {
+        return openSync(path, flags | constants.O_NOFOLLOW, 0o600);
+    }
+    catch (error) {
+        if (hasCode(error, "ELOOP")) {
+            throw new PairError(`refusing to follow the symlink at ${path}`);
+        }
+        throw error;
+    }
+}
+function readChannelFile(path) {
+    const fd = openChannelFile(path, constants.O_RDONLY);
+    try {
+        return readFileSync(fd, "utf8");
+    }
+    finally {
+        closeSync(fd);
+    }
+}
+function writeChannelFile(path, text, flags) {
+    const fd = openChannelFile(path, constants.O_WRONLY | constants.O_CREAT | flags);
+    try {
+        writeSync(fd, text);
+    }
+    finally {
+        closeSync(fd);
+    }
+}
+function readRegistration(channel) {
+    const path = join(channel, SESSION_FILE);
+    let parsed;
+    try {
+        parsed = JSON.parse(readChannelFile(path));
+    }
+    catch (error) {
+        if (isMissing(error)) {
+            return undefined;
+        }
+        throw error instanceof SyntaxError ? new PairError(`corrupt registration ${path}: ${error.message}`) : error;
+    }
+    const { thread, worktree, registeredAt } = parsed;
+    if (typeof thread !== "string" || !SESSION_ID.test(thread) || typeof worktree !== "string" || typeof registeredAt !== "string") {
+        throw new PairError(`corrupt registration ${path}: expected thread, worktree and registeredAt`);
+    }
+    return { thread, worktree, registeredAt };
+}
+/** The calling Codex session, or undefined outside Codex. */
+function codexThreadId() {
+    const id = process.env.CODEX_THREAD_ID;
+    if (id === undefined || id === "") {
+        return undefined;
+    }
+    if (!SESSION_ID.test(id)) {
+        throw new PairError(`CODEX_THREAD_ID is not a session id (got "${id}")`);
+    }
+    return id;
+}
+/** Runs in Codex's shell, so the worktree comes from the session's real cwd, not from a tool argument. */
+function register(channel, root) {
+    const thread = codexThreadId();
+    if (!thread) {
+        throw new PairError("register must run in a Codex session's shell: CODEX_THREAD_ID is not set");
+    }
+    const previous = readRegistration(channel);
+    mkdirSync(channel, { recursive: true });
+    const registration = { thread, worktree: root, registeredAt: new Date().toISOString() };
+    const tmpPath = join(channel, `.${SESSION_FILE}.${randomBytes(3).toString("hex")}.tmp`);
+    writeFileSync(tmpPath, `${JSON.stringify(registration)}\n`);
+    renameSync(tmpPath, join(channel, SESSION_FILE));
+    const replaced = previous && previous.thread !== thread ? ` (replaced ${previous.thread})` : "";
+    return `registered codex session ${thread} for ${root}${replaced}. Now call the pair_listen tool.`;
+}
+function unregister(channel) {
+    const current = readRegistration(channel);
+    if (!current) {
+        return "no codex session is registered for this worktree";
+    }
+    const caller = codexThreadId();
+    // An old session saying "stop" must not silence a newer one. A shell outside Codex is the user.
+    if (caller !== undefined && caller !== current.thread) {
+        throw new PairError(`a different codex session (${current.thread}) is registered here; nothing changed`);
+    }
+    // ponytail: check-then-delete; a re-register in the same instant would be removed too. status shows it.
+    rmSync(join(channel, SESSION_FILE), { force: true });
+    return `unregistered codex session ${current.thread}: pair stops notifying it`;
+}
+/** Keeps the log to at most two files, so a long-lived channel doesn't grow without bound. */
+function rotateLog(path) {
+    const stats = lstatSync(path, { throwIfNoEntry: false });
+    if (stats && !stats.isFile()) {
+        rmSync(path, { force: true }); // a symlink planted here: remove the link itself, never its target
+        return;
+    }
+    if ((stats?.size ?? 0) <= LISTEN_LOG_MAX_BYTES) {
+        return;
+    }
+    try {
+        renameSync(path, `${path}.1`);
+    }
+    catch (error) {
+        if (!isMissing(error)) {
+            throw error; // ENOENT: another server rotated it first
+        }
+    }
+}
+/**
+ * Where `pair mcp` keeps its own files, the log and the claims: outside every agent's writable roots.
+ * Agents can write the channel, and could swap a directory on a channel path for a symlink between
+ * any check and the write that follows, so the unsandboxed server only ever reads channels.
+ */
+function stateDir(channel) {
+    const configured = process.env.XDG_STATE_HOME;
+    const root = configured && isAbsolute(configured) ? configured : join(homedir(), ".local", "state");
+    return join(resolve(root), "pair", basename(channel));
+}
+function logListen(channel, text) {
+    try {
+        const path = join(stateDir(channel), LISTEN_LOG);
+        mkdirSync(dirname(path), { recursive: true });
+        rotateLog(path);
+        const singleLine = JSON.stringify(text).slice(1, -1); // escape control characters in agent-chosen paths
+        writeChannelFile(path, `${new Date().toISOString()} ${singleLine}\n`, constants.O_APPEND);
+    }
+    catch (error) {
+        console.error(`pair: cannot write ${LISTEN_LOG}: ${String(error)}\n${text}`); // stderr: stdout is the MCP stream
+    }
+}
+/**
+ * The MCP server runs outside Codex's sandbox, so it must not run whatever `codex` PATH points at:
+ * an agent-writable PATH entry would turn the fixed queue call into unsandboxed code execution.
+ */
+function pinnedCodex() {
+    const path = process.env.PAIR_CODEX;
+    if (!path || !isAbsolute(path)) {
+        throw new PairError("PAIR_CODEX must be the absolute path of the codex executable. Re-add the MCP server with the command `pair init` prints.");
+    }
+    return path;
+}
+function realpathOrSelf(path) {
+    try {
+        return realpathSync(path);
+    }
+    catch {
+        return path; // doesn't exist (yet); compare it as written
+    }
+}
+/**
+ * For `init`: the codex a shell here would run, unless it is, or links to, a file in a place agents
+ * can write: the worktree, the channels, or a temporary directory.
+ */
+function findCodex(root) {
+    const untrusted = [root, pairHome(root), tmpdir(), process.env.TMPDIR, "/tmp", "/var/tmp"]
+        .filter((dir) => Boolean(dir))
+        .flatMap((dir) => [resolve(dir), realpathOrSelf(dir)]);
+    const agentWritable = (path) => untrusted.some((dir) => path === dir || path.startsWith(`${dir}${sep}`));
+    for (const dir of (process.env.PATH ?? "").split(delimiter)) {
+        if (!isAbsolute(dir)) {
+            continue;
+        }
+        const candidate = join(dir, "codex");
+        try {
+            accessSync(candidate, constants.X_OK);
+        }
+        catch {
+            continue; // not in this PATH entry
+        }
+        return agentWritable(candidate) || agentWritable(realpathSync(candidate)) ? undefined : candidate;
+    }
+    return undefined;
+}
+/** Finds the one channel where this session ran `pair register`. Thread id comes from trusted call metadata. */
+function listen(thread, watches) {
+    if (typeof thread !== "string" || !SESSION_ID.test(thread)) {
+        throw new PairError("the tool call carried no Codex session id (_meta.threadId), so pair can't notify this session");
+    }
+    const codex = pinnedCodex();
+    const home = pairHome(process.cwd()); // the server has no worktree; `pair init` passes an absolute PAIR_HOME
+    const registered = readdirOrEmpty(home)
+        .filter((entry) => entry.isDirectory())
+        .map((entry) => join(home, entry.name))
+        .filter((channel) => {
+        try {
+            return readRegistration(channel)?.thread === thread;
+        }
+        catch {
+            return false; // another channel's corrupt registration is that channel's problem; status reports it
+        }
+    });
+    if (registered.length === 0) {
+        throw new PairError("this session isn't registered: run `pair register` in your shell, then call pair_listen again");
+    }
+    if (registered.length > 1) {
+        throw new PairError(`this session is registered in ${registered.length} channels (${registered.join(", ")}); run \`pair unregister\` in the worktrees you don't want`);
+    }
+    const [channel] = registered;
+    if (watches.get(thread)?.channel !== channel) {
+        watches.set(thread, { channel, codex, notifiedAt: 0, stallReported: false, dispatching: false, failures: 0, retryAt: 0 });
+        logListen(channel, `listening for ${thread}`);
+        pruneClaims(channel);
+    }
+    return `listening: pair will queue a short "pair:" note into this session when a message for codex arrives in ${channel}. End your turn now.`;
+}
+/**
+ * One nudge per session and message, even with several MCP processes on one session. It says
+ * "sending" while a server holds the right to send, and "sent" once `codex queue` succeeded.
+ */
+function claimPath(channel, thread, pending) {
+    return join(stateDir(channel), "claims", `${basename(dirname(pending))}.${basename(pending)}.${thread}`);
+}
+/** Claims outlive their threads, so old ones are dropped. A still-pending message may get one more note. */
+function pruneClaims(channel) {
+    const dir = join(stateDir(channel), "claims");
+    try {
+        for (const entry of readdirOrEmpty(dir)) {
+            const path = join(dir, entry.name);
+            const stats = lstatSync(path, { throwIfNoEntry: false });
+            if (stats && Date.now() - stats.mtimeMs > CLAIM_MAX_AGE_MS) {
+                rmSync(path, { force: true });
+            }
+        }
+    }
+    catch (error) {
+        logListen(channel, `couldn't prune old claims: ${String(error)}`);
+    }
+}
+/** Exclusive create: true if this server now holds the claim. O_EXCL never follows a symlink. */
+function createClaim(path) {
+    mkdirSync(dirname(path), { recursive: true });
+    try {
+        writeChannelFile(path, "sending\n", constants.O_EXCL);
+        return true;
+    }
+    catch (error) {
+        if (!hasCode(error, "EEXIST")) {
+            throw error;
+        }
+        return false;
+    }
+}
+function claim(path) {
+    if (createClaim(path)) {
+        return "claimed";
+    }
+    const stats = lstatSync(path);
+    if (stats.isFile() && readChannelFile(path).trim() === "sent") {
+        return "sent";
+    }
+    if (stats.isFile() && Date.now() - stats.mtimeMs < CLAIM_LEASE_MS) {
+        return "busy"; // another server is sending; if it fails it removes the claim and we try again
+    }
+    // Its sender died mid-send, or this isn't a plain file (say, a planted symlink). Unlinking removes
+    // the entry itself, never a link's target. ponytail: two servers taking over at the same moment
+    // may both send, which costs one extra short turn; a lock for the takeover would be the upgrade.
+    rmSync(path, { force: true });
+    return createClaim(path) ? "claimed" : "busy";
+}
+/** Replaces the claim's directory entry, so a symlink put there is replaced, not written through. */
+function markSent(path) {
+    const tmpPath = `${path}.${randomBytes(3).toString("hex")}.tmp`;
+    writeChannelFile(tmpPath, "sent\n", constants.O_EXCL);
+    renameSync(tmpPath, path);
+}
+function dispatch(thread, watch, pending) {
+    watch.dispatching = true;
+    const child = execFile(watch.codex, ["queue", "--thread", thread, "--message", NUDGE], { timeout: QUEUE_TIMEOUT_MS }, (error, _stdout, stderr) => {
+        watch.dispatching = false;
+        if (error) {
+            rmSync(claimPath(watch.channel, thread, pending), { force: true }); // let the retry, here or in another process, claim it again
+            watch.failures += 1;
+            const delay = Math.min(60_000, 1000 * 2 ** watch.failures);
+            watch.retryAt = Date.now() + delay;
+            logListen(watch.channel, `codex queue failed for ${pending}, retrying in ${delay / 1000}s: ${stderr.trim() || error.message}`);
+            return;
+        }
+        Object.assign(watch, { notified: pending, notifiedAt: Date.now(), stallReported: false, failures: 0 });
+        logListen(watch.channel, `notified ${thread} about ${pending}`);
+        try {
+            markSent(claimPath(watch.channel, thread, pending));
+        }
+        catch (claimError) {
+            if (!isMissing(claimError)) {
+                logListen(watch.channel, `couldn't mark ${pending} as sent, so another server may send it again: ${String(claimError)}`);
+            }
+        }
+    });
+    child.stdin?.end();
+}
+/** One poll for one session. Never archives: reading a closed thread stays the agent's own `pair wait`. */
+function tick(thread, watch, watches) {
+    if (watch.dispatching || Date.now() < watch.retryAt) {
+        return;
+    }
+    try {
+        if (readRegistration(watch.channel)?.thread !== thread) {
+            watches.delete(thread);
+            logListen(watch.channel, `stopped notifying ${thread}: it is no longer the registered session`);
+            return;
+        }
+        const pending = pendingFor(watch.channel, "codex")?.state.last.file;
+        if (pending === undefined) {
+            return;
+        }
+        if (pending !== watch.notified) {
+            let claimed;
+            try {
+                claimed = claim(claimPath(watch.channel, thread, pending));
+            }
+            catch (error) {
+                if (isMissing(error)) {
+                    return; // another server released the claim since we looked: look again next tick
+                }
+                throw error;
+            }
+            if (claimed === "sent") {
+                // Sent by another MCP process on this session, or by an earlier run of this one.
+                Object.assign(watch, { notified: pending, notifiedAt: Date.now(), stallReported: false });
+            }
+            else if (claimed === "claimed") {
+                dispatch(thread, watch, pending);
+            }
+            return;
+        }
+        if (!watch.stallReported && Date.now() - watch.notifiedAt > STALL_MS) {
+            watch.stallReported = true;
+            logListen(watch.channel, `no reply to ${pending} after 10 minutes. The review may just be long, or the turn failed, was cancelled, or waits for an approval. Pair won't notify again; ask Codex to check pair.`);
+        }
+    }
+    catch (error) {
+        watch.retryAt = Date.now() + 60_000;
+        logListen(watch.channel, `poll failed, retrying in 60s: ${error instanceof Error ? error.message : String(error)}`);
+    }
+}
+const LISTEN_TOOL = {
+    name: "pair_listen",
+    description: "Have pair notify this Codex session when a pair message for codex arrives, so you can end your turn instead of polling. Run `pair register` in your shell first. Takes no arguments.",
+    inputSchema: { type: "object", properties: {}, additionalProperties: false },
+};
+function mcpResult(request, watches) {
+    switch (request.method) {
+        case "initialize": {
+            const { version } = JSON.parse(readFileSync(join(PACKAGE_ROOT, "package.json"), "utf8"));
+            return {
+                protocolVersion: request.params?.protocolVersion ?? "2025-06-18",
+                capabilities: { tools: {} },
+                serverInfo: { name: "pair", version },
+            };
+        }
+        case "ping":
+            return {};
+        case "tools/list":
+            return { tools: [LISTEN_TOOL] };
+        case "tools/call": {
+            if (request.params?.name !== LISTEN_TOOL.name) {
+                return { content: [{ type: "text", text: `unknown tool: ${String(request.params?.name)}` }], isError: true };
+            }
+            try {
+                return { content: [{ type: "text", text: listen(request.params._meta?.threadId, watches) }] };
+            }
+            catch (error) {
+                if (!(error instanceof PairError)) {
+                    throw error;
+                }
+                return { content: [{ type: "text", text: `pair: ${error.message}` }], isError: true };
+            }
+        }
+        default:
+            return undefined;
+    }
+}
+/** stdio MCP server. Its watches live and die with this process, which Codex ends with the session. */
+async function serveMcp() {
+    const watches = new Map();
+    const timer = setInterval(() => {
+        for (const [thread, watch] of watches) {
+            tick(thread, watch, watches);
+        }
+    }, POLL_MS);
+    const respond = (message) => {
+        process.stdout.write(`${JSON.stringify({ jsonrpc: "2.0", ...message })}\n`);
+    };
+    for await (const line of createInterface({ input: process.stdin })) {
+        if (!line.trim()) {
+            continue;
+        }
+        let request;
+        try {
+            request = JSON.parse(line);
+        }
+        catch {
+            respond({ id: null, error: { code: -32700, message: "parse error" } });
+            continue;
+        }
+        if (request.id === undefined || request.id === null) {
+            continue; // a notification, such as notifications/initialized
+        }
+        try {
+            const result = mcpResult(request, watches);
+            respond(result === undefined ? { id: request.id, error: { code: -32601, message: `method not found: ${request.method}` } } : { id: request.id, result });
+        }
+        catch (error) {
+            // Report it to Codex instead of dying: a crashed server would silently stop every watch.
+            respond({ id: request.id, error: { code: -32603, message: error instanceof Error ? error.message : String(error) } });
+        }
+    }
+    clearInterval(timer); // stdin closed: the session is gone, so stop notifying it
+}
 function describe(channel, author) {
     const thread = threadFor(channel, author);
     const state = stateOf(listMessages(thread));
@@ -393,6 +826,32 @@ function instructionState(path, expected, sectionOnly = false) {
         return `unreadable (${reason})`;
     }
 }
+function notificationStatus(channel) {
+    let registration;
+    try {
+        const current = readRegistration(channel);
+        registration = current ? `session ${current.thread}, registered ${current.registeredAt}` : "no session registered";
+    }
+    catch (error) {
+        if (!(error instanceof PairError)) {
+            throw error;
+        }
+        registration = error.message;
+    }
+    let lastEvent;
+    try {
+        lastEvent = readChannelFile(join(stateDir(channel), LISTEN_LOG)).trimEnd().split("\n").at(-1);
+    }
+    catch (error) {
+        if (error instanceof PairError) {
+            lastEvent = error.message;
+        }
+        else if (!isMissing(error)) {
+            throw error;
+        }
+    }
+    return [`codex notifications: ${registration}`, ...(lastEvent ? [`  last listener event: ${lastEvent}`] : [])];
+}
 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"));
@@ -406,6 +865,7 @@ function status(channel, root) {
         "instructions on disk (does not verify what running agents loaded):",
         `  AGENTS.md (pair section): ${agents}`,
         `  .claude/skills/pair/SKILL.md: ${skill}`,
+        ...channelAccess(channel, () => notificationStatus(channel)),
         ...(agents === "missing" || agents === "stale" || skill === "missing" || skill === "stale"
             ? ["Run `pair init` to refresh missing or stale instructions, then reload agent sessions."] : []),
         ...(agents.startsWith("unreadable") || skill.startsWith("unreadable")
@@ -513,8 +973,167 @@ function init(channel, root) {
         `wrote: ${agentsPath} (pair section)`,
         "",
         sandboxConfig(channel),
+        "",
+        "To let pair wake Codex when a message arrives, instead of Codex polling, register pair's MCP server once:",
+        `  ${mcpAddCommand(root)}`,
     ].join("\n");
 }
+/** Codex starts MCP servers with only HOME, PATH and a few more, so the command carries what `pair mcp` reads. */
+function mcpAddCommand(root) {
+    const stateHome = process.env.XDG_STATE_HOME;
+    const env = [
+        ...(process.env.PAIR_HOME ? [`PAIR_HOME=${pairHome(root)}`] : []),
+        ...(stateHome && isAbsolute(stateHome) ? [`XDG_STATE_HOME=${resolve(stateHome)}`] : []),
+        `PAIR_CODEX=${findCodex(root) ?? "<absolute path of codex>"}`,
+    ];
+    const flags = env.map((entry) => `--env ${shellQuote(entry)}`).join(" ");
+    return `codex mcp add ${flags} pair -- ${shellQuote(join(PACKAGE_ROOT, "dist", "pair.js"))} mcp`;
+}
+/**
+ * `init` appends its section after exactly one added line ending. When the last section ends the file,
+ * drop it with that one line ending, so the user's text ends exactly as before, final newline or not.
+ */
+function withoutAppendedSection(text) {
+    const end = text.lastIndexOf("<!-- pair:end -->");
+    if (end === -1 || text.slice(end + "<!-- pair:end -->".length).trim() !== "") {
+        return text;
+    }
+    const start = text.lastIndexOf("<!-- pair:start -->", end);
+    return start === -1 ? text : text.slice(0, start).replace(/\r?\n$/, "");
+}
+/** Single-quoted for sh: the channel name comes from the worktree's name, which may hold `$(…)`. */
+function shellQuote(text) {
+    return `'${text.replaceAll("'", `'\\''`)}'`;
+}
+/**
+ * Undoes `init` in this worktree. Every version so far wrote the same two paths and section markers,
+ * so this also cleans up after older versions. History and global setup are only reported.
+ */
+function uninit(channel, root) {
+    const removed = [];
+    const notes = [];
+    const skillDir = join(root, ".claude", "skills", "pair");
+    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"))) {
+            rmSync(skillPath);
+            removed.push(skillPath);
+            // Drop the directories init created, up to the first one that holds something else.
+            for (const dir of [skillDir, dirname(skillDir), dirname(dirname(skillDir))]) {
+                try {
+                    rmdirSync(dir);
+                }
+                catch {
+                    break; // not empty: someone else's files live there
+                }
+            }
+        }
+        else {
+            notes.push(`kept: ${skillPath} (it isn't a file pair init wrote, so it may hold your changes; delete it yourself if not)`);
+        }
+    }
+    const agentsPath = join(root, "AGENTS.md");
+    const agents = existsSync(agentsPath) ? readFileSync(agentsPath, "utf8") : "";
+    if (PAIR_SECTION.test(agents)) {
+        const rest = withoutAppendedSection(agents).replace(PAIR_SECTIONS, "");
+        if (rest.trim() === "") {
+            rmSync(agentsPath);
+            removed.push(`${agentsPath} (it held only the pair section)`);
+        }
+        else {
+            writeFileSync(agentsPath, rest);
+            removed.push(`the pair section of ${agentsPath}`);
+        }
+    }
+    const registration = join(channel, SESSION_FILE);
+    if (channelAccess(channel, () => lstatSync(registration, { throwIfNoEntry: false }))) {
+        channelAccess(channel, () => rmSync(registration, { force: true }));
+        removed.push("the codex session registration, so pair stops notifying it");
+    }
+    const history = [channel, stateDir(channel)].filter((dir) => existsSync(dir));
+    if (history.length > 0) {
+        notes.push(`kept: message history. To delete it: rm -rf ${history.map(shellQuote).join(" ")}`);
+    }
+    notes.push("If no repo uses pair anymore: run `codex mcp remove pair`, then `npm uninstall -g claude-codex-pair`, and remove the pair home from the sandbox settings `pair init` printed.");
+    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", ["-a", "-d", "cwd", "-Fpn", "-p", pids.join(",")], { encoding: "utf8" });
+    }
+    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;
+}
+/** Every running `pair mcp` and `pair wait` on this machine, with what started it. */
+function ps() {
+    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 (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
+        }
+        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)`}`,
+        ];
+    })
+        .join("\n");
+}
 function readBody(source) {
     if (!source) {
         throw new PairError("send needs a message file, or - for stdin");
@@ -536,11 +1155,15 @@ function oneOf(value, allowed, what) {
 }
 const USAGE = `usage:
   pair send <request|review|response> --as <claude|codex> [--verdict approve|changes] <file|->
-  pair wait --as <claude|codex> [--timeout seconds]   (prints "no message … yet" on timeout: run again)
+  pair wait --as <claude|codex> [--timeout seconds]   (prints "no message … yet" on timeout)
   pair status
   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 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 ps                                             (list running pair mcp and pair wait processes)`;
 async function main(argv) {
     const { values, positionals } = parseArgs({
         args: argv,
@@ -566,8 +1189,9 @@ async function main(argv) {
             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.
-                console.log(`pair: no message for ${me} yet. Run \`pair wait --as ${me}\` again.`);
+                // 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;
         }
@@ -583,6 +1207,21 @@ async function main(argv) {
         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;

package/package.json

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

package/prompts/pair.md

@@ -13,13 +13,17 @@ model turns:
 - If you are Claude Code in an interactive session: run `pair wait --as {{AGENT}} --timeout 3600` as
   a background command (`run_in_background: true`) and end your turn. You'll be resumed when it exits.
   Then read its output.
-- If you are Codex: start `pair wait --as {{AGENT}} --timeout 3600` once and keep it running. Check
-  on it as your tools allow, keeping each check within any wait limit in your instructions (for
-  example, 55 seconds). A limit on checks doesn't limit how long the command runs, unless your
-  instructions also limit command lifetime. Don't start another `pair wait` until the running one
-  exits, and re-run it only when it times out (see below). If a check is interrupted, the command
-  may still be running: keep checking that session, or stop it and confirm it exited before starting
-  a new one.
+- If you are Codex: run `pair register` in your shell, call the `pair_listen` tool, then end your
+  turn. Never keep a `pair wait` running or poll for messages: each check costs a model call. Do this
+  before your first wait in a session, and again after the session restarts or resumes; repeating it
+  is harmless. When a message arrives, pair queues a short note starting with `pair:` into this
+  session. Then run `pair wait --as {{AGENT}} --timeout 5`, act on what it prints, send your reply if
+  one is due, and end your turn again. If it prints `pair: no message for`, there's nothing to do:
+  end your turn.
+  If you don't have `pair_listen`, or `pair register` or `pair_listen` fails, run
+  `pair wait --as {{AGENT}} --timeout 5` once and act on any message. Then tell the user that pair
+  can't wake you, quoting the error if there was one, and that `pair init` prints the setup. End your
+  turn. When the user asks you to check pair, run `pair wait --as {{AGENT}} --timeout 5` once again.
 - Otherwise, including headless `claude -p` or when background commands are unavailable: run
   `pair wait --as {{AGENT}}` in the foreground with a shell timeout above 600 seconds. It gives up
   after 540 seconds by default.
@@ -33,7 +37,8 @@ report new messages or failures normally.
 finished, such as an approval you missed, run `pair history`, then `pair history <id>`.
 
 Read the first line of `pair wait`'s output. If it starts with `pair: no message for`, the wait timed
-out: start it again. That isn't an error. If it starts with `== pair:`, a message was delivered. Act on
+out: start it again, unless you are Codex (see above). That isn't an error. If it starts with
+`== pair:`, a message was delivered. Act on
 it, even if its body quotes timeout text. If `pair wait` ends any other way (a non-zero exit, or
 cancelled by you or the user), don't restart it. Tell the user what happened.
 
@@ -83,5 +88,10 @@ EOF
 
 Use `--verdict approve` when no high- or medium-severity finding is still open.
 If `send review` prints ESCALATED, stop the loop and ask the user how to proceed.
+When the user tells you to stop reviewing, stop waiting. If you ran `pair register`, also run
+`pair unregister` so pair stops notifying you. A `pair:` note that pair queued before that can still
+arrive, and so can one sent within a minute or two after Codex closes. If a note arrives after the
+user told you to stop, and they haven't asked you to review or check pair since, don't act on it: say
+that a pair message is waiting and end your turn.
 Severity levels: `high` (bug, data loss, security), `medium` (likely bug, missing edge case),
 `low` (style, naming).