claude-codex-pair 0.0.0-stage → 0.1.1

package/DESIGN.md

@@ -0,0 +1,105 @@
+# cc-pair design
+
+Claude Code and Codex review each other's work. Each runs as a live session in its own terminal,
+and they talk through a shared directory that works like a chat channel.
+
+## Decisions
+
+| Topic | Choice |
+|---|---|
+| 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"). |
+| 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. |
+| Concurrency | At most one open thread per direction. |
+| Storage | `~/.pair/<repo>-<hash>/` (or `$PAIR_HOME`). The hash comes from `git rev-parse --show-toplevel`, so each worktree gets its own channel. A reviewer reads the author's files, so both agents must run in the same worktree, and parallel pairs in different worktrees stay isolated. |
+| Format | Markdown files with flat YAML frontmatter that the CLI writes. Findings go in the body. |
+
+## Layout
+
+```
+~/.pair/<repo>-<hash>/
+  claude-to-codex/                    # lane where claude is the author
+    <iso-ts>-<rand>/                  # one directory per thread; a path is never reused
+      001-request.md
+      002-review.md                   # round 1, verdict changes
+      003-response.md                 # round 2
+      004-review.md                   # round 2, verdict approve, status approved
+  codex-to-claude/
+  archive/<iso-ts>-<rand>-<lane>-<approved|escalated>/
+```
+
+Each message has this frontmatter, written by the CLI: `from`, `type`, `round`, `verdict` (reviews only), and `status` (`open`/`approved`/`escalated`).
+The CLI writes to a dotfile first and then renames it, so readers never see a partial message.
+When the CLI reads a message, it checks every field and fails with `corrupt message <path>: …` if anything is invalid. It doesn't guess.
+
+## Protocol
+
+The thread state comes from the last message, so there is no separate state file:
+
+| Last message | State | Whose turn |
+|---|---|---|
+| none | idle | author may `send request` |
+| request / response | awaiting-review | reviewer: `send review --verdict …` |
+| review, status open | awaiting-response | author: `send response` |
+| review, approved/escalated | closed | author reads it with `wait`, then it's archived |
+
+`pair wait --as X` returns the first message where it is X's turn, in either thread. It
+prints the message and a `next:` line telling the agent what to do. Calling `wait` again before
+acting returns the same message, because X still owes a reply. If the thread already has earlier
+messages, `wait` also lists their files. An agent that lost its context, for example after a
+restart, can then read the history instead of seeing only "F1 fixed".
+
+Finished threads go to `archive/`. Whenever a thread finishes, `pair` deletes all but the `PAIR_KEEP`
+most recently finished ones (100 by default; `all` keeps everything; `0` keeps none). "Most recently
+finished" means by when the thread's last message landed, not when it started, so a thread that just
+finished always survives when `PAIR_KEEP` is at least 1. An invalid `PAIR_KEEP` makes `send` and `wait`
+fail before they touch any thread. If automatic cleanup itself fails (for example, an undeletable
+directory), `pair` prints a warning and still delivers the result or writes the request.
+`pair history` lists finished threads, most recently finished first, and
+`pair history <id>` prints one transcript. `pair clean --keep N` deletes all but the N newest right
+away. The flag is required, so a bare `clean` deletes nothing. Neither kind of cleanup touches
+active threads.
+
+`pair status` adds the canonical worktree root, installed package version, and instruction
+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.
+
+Channel operations report `EACCES` and `EPERM` with the affected path and the sandbox
+configuration printed by `init`. Either ordinary permissions or sandbox restrictions can
+cause these failures. Input message files, instruction files, and installed assets are handled
+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.
+
+## Usage
+
+```
+npm install && npm link                       # npm install builds via prepare; npm link provides `pair`
+cd <repo> && pair init                        # installs the skill and AGENTS.md section, prints sandbox config
+```
+
+Then add the printed paths to both sandboxes: Codex `writable_roots`, Claude
+`sandbox.filesystem.allowWrite`. In the reviewer terminal say "be my reviewer". In the author
+terminal, finish a task and say "ask for review".
+
+```
+pair send <request|review|response> --as <claude|codex> [--verdict approve|changes] <file|->
+pair wait --as <agent> [--timeout s]
+pair status
+pair history [thread-id]
+pair clean --keep N
+pair init
+```
+
+## Known limits
+
+- 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.

package/LICENSE

@@ -0,0 +1,24 @@
+This is free and unencumbered software released into the public domain.
+
+Anyone is free to copy, modify, publish, use, compile, sell, or
+distribute this software, either in source code form or as a compiled
+binary, for any purpose, commercial or non-commercial, and by any
+means.
+
+In jurisdictions that recognize copyright laws, the author or authors
+of this software dedicate any and all copyright interest in the
+software to the public domain. We make this dedication for the benefit
+of the public at large and to the detriment of our heirs and
+successors. We intend this dedication to be an overt act of
+relinquishment in perpetuity of all present and future rights to this
+software under copyright law.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
+EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
+MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT.
+IN NO EVENT SHALL THE AUTHORS BE LIABLE FOR ANY CLAIM, DAMAGES OR
+OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE,
+ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR
+OTHER DEALINGS IN THE SOFTWARE.
+
+For more information, please refer to <https://unlicense.org>

package/README.md

@@ -1,3 +1,156 @@
-# Temporary Holding Version
+# cc-pair
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+Claude Code and Codex review each other's work. Each runs as a live session in its own terminal,
+and they talk through a shared directory on disk.
+
+```
+terminal A: claude                         terminal B: codex ("be my reviewer")
+  finish task
+  pair send request ──▶ ~/.pair/<repo>-<hash>/claude-to-codex/<thread>/001-request.md
+  pair wait  ⏳                              pair wait ◀── picks it up
+                    002-review.md ◀── pair send review --verdict changes
+  verify findings, fix
+  pair send response ──▶ 003-response.md
+  pair wait  ⏳                              pair wait ◀── re-checks fixes
+                    004-review.md ◀── pair send review --verdict approve
+  done ✓
+```
+
+Roles are symmetric: Codex can ask Claude for a review the same way.
+
+## Install
+
+```sh
+npm install -g claude-codex-pair
+```
+
+Requires Node 22 or later. This installs the `pair` command.
+
+To install from source, clone the repo, then run `npm install && npm link` inside it.
+
+If you installed from source before the package was renamed to `claude-codex-pair`, run
+`npm uninstall -g cc-pair` first. Otherwise the install fails with `EEXIST` on `bin/pair`.
+
+## Setup (once per repo)
+
+```sh
+cd your-repo
+pair init
+```
+
+`init` writes a Claude Code skill (`.claude/skills/pair/SKILL.md`) and a section in `AGENTS.md`
+for Codex. Both explain the protocol to the agent.
+
+Claude Code 2.1.277 and later can also read `AGENTS.md`. The pair section there starts by telling
+any agent other than Codex to ignore it, so Claude keeps its own role. If you ran `pair init` with
+an earlier version of this package, run it again to refresh both files.
+
+Both agents' sandboxes must be able to write to `~/.pair`, or `$PAIR_HOME` if set. `pair init`
+prints the configuration snippets with your actual path; add them to the corresponding configs.
+For the default directory, they look like this:
+
+```toml
+# ~/.codex/config.toml
+[sandbox_workspace_write]
+writable_roots = ["/Users/you/.pair"]
+```
+
+```jsonc
+// ~/.claude/settings.json
+"sandbox": { "filesystem": { "allowWrite": ["~/.pair"] } }
+```
+
+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.
+
+## Use
+
+1. In the reviewer's terminal, say **"be my reviewer"**. The agent loops on `pair wait`.
+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.
+4. The thread ends when the reviewer approves. If findings are still open after 3 rounds, the thread
+   is **escalated** and both agents stop and ask you.
+
+## Worktrees
+
+The channel comes from the worktree root, so each git worktree gets its own. You can run one pair
+per worktree in parallel without them seeing each other's messages.
+
+```sh
+git worktree add ../your-repo-feature -b feature/x
+cd ../your-repo-feature
+pair init     # needed unless AGENTS.md and .claude/skills/pair/ are committed on this branch
+pair status   # worktree: /Users/you/your-repo-feature
+```
+
+Then start Claude Code and Codex in `../your-repo-feature`, not in the main checkout. If one agent
+never receives the other's messages, ask each agent to run `pair status` and compare the `channel:`
+lines. Pair needs no extra sandbox config, because every channel lives under `~/.pair` (or `$PAIR_HOME`).
+
+`git worktree remove` leaves the worktree's channel in `~/.pair`. To delete it too, run
+`pair status` in the worktree first to get its `channel:` path, then remove that directory.
+
+## Commands
+
+The agents run `send` and `wait` themselves. You'll mostly use `init`, `status`, `history` and `clean`.
+
+```
+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 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 status` shows the channel, worktree root, installed package version, and each lane's turn.
+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
+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
+```
+
+Instruction states are `current`, `stale`, `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.
+
+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
+permissions as well as sandbox settings. Automatic archive cleanup failures remain warnings,
+so a cleanup problem doesn't prevent delivering a review or starting the next thread.
+
+| Env var | Default | Meaning |
+|---|---|---|
+| `PAIR_HOME` | `~/.pair` | Root directory for channels |
+| `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 |
+
+## Example review
+
+These are messages from a real run, shortened. The bug in round 1 was planted on purpose.
+
+```
+== pair: review from codex · claude-to-codex · round 1 · verdict changes ==
+### F1 [medium] src/paginate.js:8: Partial last pages are omitted from the page count
+`totalPages(5, 2)` returns 2 ... Use `Math.ceil(count / pageSize)`.
+### F2 [medium] src/paginate.js:2: Invalid pagination inputs produce unrelated items
+`paginate([1, 2, 3, 4, 5], 1, -2)` returns `[1, 2, 3]` ...
+
+== pair: review from codex · claude-to-codex · round 2 · verdict approve ==
+F1 and F2 are fixed. I re-read src/paginate.js and ran 41 assertions ... All passed.
+```
+
+See [DESIGN.md](DESIGN.md) for the protocol, storage layout, and known limits.

package/dist/pair.js

@@ -0,0 +1,601 @@
+#!/usr/bin/env node
+import { 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 { setTimeout as sleep } from "node:timers/promises";
+import { fileURLToPath } from "node:url";
+import { parseArgs } from "node:util";
+const AGENTS = ["claude", "codex"];
+const MESSAGE_TYPES = ["request", "review", "response"];
+const VERDICTS = ["approve", "changes"];
+const THREAD_STATUSES = ["open", "approved", "escalated"];
+const DEFAULT_MAX_ROUNDS = 3;
+const DEFAULT_KEEP = 100; // finished threads kept by auto-pruning
+const DEFAULT_WAIT_SECONDS = 540; // stays under Claude Code's 10-minute Bash cap
+const POLL_MS = 1000;
+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 PACKAGE_ROOT = join(dirname(fileURLToPath(import.meta.url)), "..");
+class PairError extends Error {
+}
+function isMissing(error) {
+    return error instanceof Error && "code" in error && error.code === "ENOENT";
+}
+function sandboxConfig(channel) {
+    const pairHome = JSON.stringify(dirname(channel));
+    return [
+        "Both agents need read and write access to the channel. Sandbox configuration:",
+        "",
+        "  ~/.codex/config.toml",
+        "    [sandbox_workspace_write]",
+        `    writable_roots = [${pairHome}]`,
+        "",
+        "  ~/.claude/settings.json",
+        `    "sandbox": { "filesystem": { "allowWrite": [${pairHome}] } }`,
+    ].join("\n");
+}
+/** Only call this for channel operations; input files and installed assets have other remedies. */
+function channelError(channel, error) {
+    if (error instanceof Error && "code" in error && (error.code === "EACCES" || error.code === "EPERM")) {
+        const path = "path" in error ? String(error.path) : channel;
+        return new PairError(`cannot access channel path ${path} (${error.code}). Check filesystem permissions and sandbox restrictions.\n${sandboxConfig(channel)}`);
+    }
+    return error;
+}
+function channelAccess(channel, operation) {
+    try {
+        return operation();
+    }
+    catch (error) {
+        throw channelError(channel, error);
+    }
+}
+function positiveNumber(value, what) {
+    const parsed = Number(value);
+    if (!Number.isFinite(parsed) || parsed <= 0) {
+        throw new PairError(`${what} must be a positive number (got "${value}")`);
+    }
+    return parsed;
+}
+function maxRounds() {
+    return positiveNumber(process.env.PAIR_MAX_ROUNDS ?? String(DEFAULT_MAX_ROUNDS), "PAIR_MAX_ROUNDS");
+}
+function partnerOf(agent) {
+    return agent === "claude" ? "codex" : "claude";
+}
+function threadFor(channel, author) {
+    const reviewer = partnerOf(author);
+    return { lane: join(channel, `${author}-to-${reviewer}`), author, reviewer };
+}
+function readdirOrEmpty(path) {
+    try {
+        return readdirSync(path, { withFileTypes: true });
+    }
+    catch (error) {
+        // No lane dir yet means no thread has been started in it.
+        if (isMissing(error)) {
+            return [];
+        }
+        throw error;
+    }
+}
+/** Each thread gets a fresh directory, so a stale archive can never move a newer thread. */
+function currentThreadDir(thread) {
+    const entries = readdirOrEmpty(thread.lane);
+    const legacy = entries.find((entry) => entry.isFile() && MESSAGE_FILE.test(entry.name));
+    if (legacy) {
+        throw new PairError(`${thread.lane} still uses the old flat layout (${legacy.name}). Move its NNN-*.md files into a new subdirectory of it, or delete them if that thread is finished.`);
+    }
+    const latest = entries
+        .filter((entry) => entry.isDirectory() && !entry.name.startsWith("."))
+        .map((entry) => entry.name)
+        .sort()
+        .at(-1);
+    return latest === undefined ? undefined : join(thread.lane, latest);
+}
+function newThreadId() {
+    return `${new Date().toISOString().replace(/[:.]/g, "-")}-${randomBytes(3).toString("hex")}`;
+}
+function gitPath(flag) {
+    try {
+        return execFileSync("git", ["rev-parse", "--path-format=absolute", flag], {
+            encoding: "utf8",
+            stdio: ["ignore", "pipe", "ignore"],
+        }).trim();
+    }
+    catch {
+        // Not inside a git repo; callers fall back to the current directory.
+        return undefined;
+    }
+}
+function worktreeRoot() {
+    return realpathSync(gitPath("--show-toplevel") ?? process.cwd());
+}
+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}`);
+}
+function parseFrontmatter(text) {
+    const match = /^---\n([\s\S]*?)\n---\n?/.exec(text);
+    if (!match) {
+        return { fields: {}, body: text };
+    }
+    const fields = {};
+    for (const line of match[1].split("\n")) {
+        const colon = line.indexOf(":");
+        if (colon > 0) {
+            fields[line.slice(0, colon).trim()] = line.slice(colon + 1).trim();
+        }
+    }
+    return { fields, body: text.slice(match[0].length) };
+}
+/** 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 corrupt = `corrupt message ${path}:`;
+    const type = oneOf(fields.type, MESSAGE_TYPES, `${corrupt} type`);
+    if (!basename(path).endsWith(`-${type}.md`)) {
+        throw new PairError(`${corrupt} type "${type}" does not match the file name`);
+    }
+    const from = oneOf(fields.from, [type === "review" ? thread.reviewer : thread.author], `${corrupt} from`);
+    const round = Number(fields.round);
+    if (!Number.isInteger(round) || round < 1) {
+        throw new PairError(`${corrupt} round must be a positive integer (got "${fields.round}")`);
+    }
+    const status = oneOf(fields.status, THREAD_STATUSES, `${corrupt} status`);
+    const verdict = type === "review" ? oneOf(fields.verdict, VERDICTS, `${corrupt} verdict`) : undefined;
+    const consistent = verdict === "approve" ? status === "approved" : verdict === "changes" ? status !== "approved" : status === "open";
+    if (!consistent) {
+        throw new PairError(`${corrupt} status "${status}" does not fit verdict "${verdict ?? "none"}"`);
+    }
+    return { file: path, from, type, round, verdict, status, body };
+}
+function readThread(dir, thread) {
+    return readdirSync(dir)
+        .filter((name) => MESSAGE_FILE.test(name))
+        .sort()
+        .map((name) => readMessage(join(dir, name), thread));
+}
+function listMessages(thread) {
+    const dir = currentThreadDir(thread);
+    if (!dir) {
+        return [];
+    }
+    try {
+        return readThread(dir, thread);
+    }
+    catch (error) {
+        // The author's wait archived this thread mid-read, so it is closed and gone.
+        if (isMissing(error)) {
+            return [];
+        }
+        throw error;
+    }
+}
+function stateOf(messages) {
+    const last = messages.at(-1);
+    if (!last) {
+        return { kind: "idle" };
+    }
+    if (last.type !== "review") {
+        return { kind: "awaiting-review", last };
+    }
+    return last.status === "open" ? { kind: "awaiting-response", last } : { kind: "closed", last };
+}
+/** Digits only: Number("") is 0, so an empty value must never reach the conversion. */
+function parseKeep(value, what) {
+    if (!/^\d+$/.test(value)) {
+        throw new PairError(`${what} must be a whole number of finished threads to keep (got "${value}")`);
+    }
+    return Number(value);
+}
+/** How many finished threads auto-pruning keeps. Undefined means keep them all. */
+function autoKeep() {
+    const value = process.env.PAIR_KEEP;
+    if (value === undefined) {
+        return DEFAULT_KEEP;
+    }
+    return value === "all" ? undefined : parseKeep(value, "PAIR_KEEP");
+}
+/** Deletes all but the `keep` newest finished threads. Returns how many were removed. */
+function prune(channel, keep) {
+    const doomed = listArchived(channel).slice(keep);
+    for (const entry of doomed) {
+        rmSync(entry.dir, { recursive: true, force: true });
+    }
+    return doomed.length;
+}
+function archive(channel, last) {
+    const dir = dirname(last.file);
+    const archiveDir = join(channel, "archive");
+    mkdirSync(archiveDir, { recursive: true });
+    try {
+        renameSync(dir, join(archiveDir, `${basename(dir)}-${basename(dirname(dir))}-${last.status}`));
+    }
+    catch (error) {
+        // Another wait for the same agent already archived this exact thread.
+        if (!isMissing(error)) {
+            throw error;
+        }
+    }
+    const keep = autoKeep();
+    if (keep === undefined) {
+        return;
+    }
+    try {
+        prune(channel, keep);
+    }
+    catch (error) {
+        // Cleanup is housekeeping. It must never block delivering a result or starting a thread.
+        const failure = channelError(channel, error);
+        const reason = failure instanceof Error ? failure.message : String(failure);
+        console.error(`pair: warning: automatic cleanup failed: ${reason}\nFix it, then run \`pair clean --keep ${keep}\`.`);
+    }
+}
+function writeMessage(dir, seq, message, body) {
+    mkdirSync(dir, { recursive: true });
+    const name = `${String(seq).padStart(3, "0")}-${message.type}.md`;
+    const lines = [
+        "---",
+        `from: ${message.from}`,
+        `type: ${message.type}`,
+        `round: ${message.round}`,
+        ...(message.verdict ? [`verdict: ${message.verdict}`] : []),
+        `status: ${message.status}`,
+        "---",
+        body.trimEnd(),
+        "",
+    ];
+    const finalPath = join(dir, name);
+    const tmpPath = join(dir, `.${name}.tmp`);
+    writeFileSync(tmpPath, lines.join("\n"));
+    renameSync(tmpPath, finalPath); // atomic: readers never see a half-written message
+    return finalPath;
+}
+function send(channel, me, type, body, verdict) {
+    if (type === "review") {
+        return sendReview(channel, me, body, verdict);
+    }
+    const thread = threadFor(channel, me);
+    const messages = listMessages(thread);
+    const state = stateOf(messages);
+    if (type === "request") {
+        if (state.kind === "awaiting-review" || state.kind === "awaiting-response") {
+            throw new PairError(`a review thread to ${thread.reviewer} is already open (${state.kind}); finish it first`);
+        }
+        if (state.kind === "closed") {
+            archive(channel, state.last);
+        }
+        return writeMessage(join(thread.lane, newThreadId()), 1, { from: me, type, round: 1, status: "open" }, body);
+    }
+    if (state.kind !== "awaiting-response") {
+        throw new PairError(`cannot send response: no open review from ${thread.reviewer} (thread is ${state.kind})`);
+    }
+    const round = state.last.round + 1;
+    return writeMessage(dirname(state.last.file), messages.length + 1, { from: me, type, round, status: "open" }, body);
+}
+function sendReview(channel, me, body, verdict) {
+    if (!verdict) {
+        throw new PairError(`review needs --verdict ${VERDICTS.join("|")}`);
+    }
+    const thread = threadFor(channel, partnerOf(me));
+    const messages = listMessages(thread);
+    const state = stateOf(messages);
+    if (state.kind !== "awaiting-review") {
+        throw new PairError(`cannot send review: nothing from ${thread.author} is waiting for review (thread is ${state.kind})`);
+    }
+    const round = state.last.round;
+    const status = verdict === "approve" ? "approved" : round >= maxRounds() ? "escalated" : "open";
+    const review = { from: me, type: "review", round, verdict, status };
+    const path = writeMessage(dirname(state.last.file), messages.length + 1, review, body);
+    return status === "escalated" ? `${path}\n${escalationNotice()}` : path;
+}
+function escalationNotice() {
+    return `ESCALATED: round cap (${maxRounds()}) reached with open findings. STOP and ask the user how to proceed.`;
+}
+function pendingFor(channel, me) {
+    const asAuthor = threadFor(channel, me);
+    const authorMessages = listMessages(asAuthor);
+    const authorState = stateOf(authorMessages);
+    if (authorState.kind === "awaiting-response" || authorState.kind === "closed") {
+        return { thread: asAuthor, state: authorState, earlier: authorMessages.slice(0, -1) };
+    }
+    const asReviewer = threadFor(channel, partnerOf(me));
+    const reviewerMessages = listMessages(asReviewer);
+    const reviewerState = stateOf(reviewerMessages);
+    if (reviewerState.kind === "awaiting-review") {
+        return { thread: asReviewer, state: reviewerState, earlier: reviewerMessages.slice(0, -1) };
+    }
+    return undefined;
+}
+function nextStep(me, state) {
+    switch (state.kind) {
+        case "awaiting-review":
+            return `review it, then: pair send review --verdict approve|changes --as ${me} <file|->`;
+        case "awaiting-response":
+            return `verify each finding yourself, fix or reject it, then: pair send response --as ${me} <file|->`;
+        case "closed":
+            return state.last.status === "approved"
+                ? "thread approved and closed. Nothing to send."
+                : escalationNotice();
+    }
+}
+/** Points an agent that lost its context (e.g. after a restart) at the rest of the thread. */
+function historyLine({ state, earlier }) {
+    // A closed thread is archived as soon as it's read and needs no further action.
+    if (state.kind === "closed" || earlier.length === 0) {
+        return undefined;
+    }
+    const names = earlier.map((message) => basename(message.file)).join(" ");
+    return `== earlier in this thread (read them first if they're not in your context): ${dirname(state.last.file)}/ ${names} ==`;
+}
+function messageHeader(message, laneName) {
+    const verdict = message.verdict ? ` · verdict ${message.verdict}` : "";
+    return `== pair: ${message.type} from ${message.from} · ${laneName} · round ${message.round}${verdict} ==`;
+}
+function formatMessage(me, pending) {
+    const { thread, state } = pending;
+    const { last } = state;
+    const header = messageHeader(last, basename(thread.lane));
+    const history = historyLine(pending);
+    return [header, ...(history ? [history] : []), last.body.trimEnd(), `== next: ${nextStep(me, state)} ==`].join("\n");
+}
+/**
+ * Prints the message, then archives a closed thread. Archiving last keeps the `== pair:` header on
+ * the first line even when cleanup warns on stderr, since agents read stdout and stderr merged.
+ */
+async function wait(channel, me, timeoutSeconds) {
+    const deadline = Date.now() + timeoutSeconds * 1000;
+    while (true) {
+        const pending = channelAccess(channel, () => pendingFor(channel, me));
+        if (pending) {
+            console.log(formatMessage(me, pending));
+            if (pending.state.kind === "closed") {
+                channelAccess(channel, () => archive(channel, pending.state.last));
+            }
+            return true;
+        }
+        if (Date.now() >= deadline) {
+            return false;
+        }
+        await sleep(POLL_MS);
+    }
+}
+function describe(channel, author) {
+    const thread = threadFor(channel, author);
+    const state = stateOf(listMessages(thread));
+    if (state.kind === "idle") {
+        return `${basename(thread.lane)}: idle`;
+    }
+    const turn = state.kind === "awaiting-review" ? thread.reviewer : thread.author;
+    return `${basename(thread.lane)}: ${state.kind} (round ${state.last.round}, ${turn}'s turn)`;
+}
+function instructionState(path, expected, sectionOnly = false) {
+    try {
+        const text = readFileSync(path, "utf8");
+        const actual = sectionOnly ? PAIR_SECTION.exec(text)?.[0] : text;
+        if (actual === undefined) {
+            return "missing"; // AGENTS.md exists but has no complete pair section
+        }
+        return actual === expected ? "current" : "stale";
+    }
+    catch (error) {
+        if (isMissing(error)) {
+            return "missing";
+        }
+        const reason = error instanceof Error && "code" in error ? String(error.code) : String(error);
+        return `unreadable (${reason})`;
+    }
+}
+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}`,
+        ...lanes,
+        "instructions on disk (does not verify what running agents loaded):",
+        `  AGENTS.md (pair section): ${agents}`,
+        `  .claude/skills/pair/SKILL.md: ${skill}`,
+        ...(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")
+            ? ["Check permissions on the unreadable instruction paths before refreshing them."] : []),
+    ].join("\n");
+}
+/** Finished threads, most recently finished first. Entries that aren't archived threads are ignored. */
+function listArchived(channel) {
+    const archiveDir = join(channel, "archive");
+    return readdirOrEmpty(archiveDir)
+        .filter((entry) => entry.isDirectory())
+        .flatMap((entry) => {
+        const match = ARCHIVED_THREAD.exec(entry.name);
+        if (!match) {
+            return [];
+        }
+        const [, id, author, reviewer, outcome] = match;
+        const thread = threadFor(channel, author);
+        if (thread.reviewer !== reviewer) {
+            return [];
+        }
+        const dir = join(archiveDir, entry.name);
+        const stats = statSync(dir, { throwIfNoEntry: false });
+        if (!stats) {
+            return []; // removed by a concurrent clean
+        }
+        const laneName = `${author}-to-${reviewer}`;
+        return [{ id, finishedAt: stats.mtimeMs, dir, laneName, outcome: outcome, thread }];
+    })
+        .sort((a, b) => b.finishedAt - a.finishedAt || b.id.localeCompare(a.id));
+}
+/** Undefined when `pair clean` removed the thread after the archive was listed. */
+function readArchived(entry) {
+    try {
+        return readThread(entry.dir, entry.thread);
+    }
+    catch (error) {
+        if (isMissing(error)) {
+            return undefined;
+        }
+        throw error;
+    }
+}
+function requestSummary(messages) {
+    const first = messages[0]?.body.split("\n").map((line) => line.trim()).find((line) => line && !line.startsWith("#")) ?? "";
+    return first.length > 72 ? `${first.slice(0, 71)}…` : first;
+}
+function history(channel, query) {
+    const archived = listArchived(channel);
+    if (query === undefined) {
+        if (archived.length === 0) {
+            return "no finished threads yet";
+        }
+        return archived
+            .flatMap((entry) => {
+            const messages = readArchived(entry);
+            return messages ? [`${entry.id}  ${entry.laneName}  ${entry.outcome}  ${messages.length} messages  ${requestSummary(messages)}`] : [];
+        })
+            .join("\n");
+    }
+    const matches = archived.filter((entry) => entry.id.includes(query));
+    if (matches.length !== 1) {
+        const found = matches.length === 0 ? "no finished thread matches" : `${matches.length} finished threads match`;
+        throw new PairError(`${found} "${query}"${matches.map((entry) => `\n  ${entry.id}`).join("")}`);
+    }
+    const [entry] = matches;
+    const messages = readArchived(entry);
+    if (!messages) {
+        throw new PairError(`finished thread ${entry.id} was removed while reading it`);
+    }
+    const transcript = messages.map((message) => `${messageHeader(message, entry.laneName)}\n${message.body.trimEnd()}`);
+    return [`== thread ${entry.id} · ${entry.laneName} · ${entry.outcome} ==`, ...transcript].join("\n\n");
+}
+function clean(channel, keepValue) {
+    if (keepValue === undefined) {
+        throw new PairError("clean needs --keep N, the number of newest finished threads to keep");
+    }
+    const keep = parseKeep(keepValue, "--keep");
+    return `removed ${prune(channel, keep)} finished thread(s), kept up to ${keep}`;
+}
+function renderPrompt(agent) {
+    const template = readFileSync(join(PACKAGE_ROOT, "prompts", "pair.md"), "utf8");
+    return template.replaceAll("{{AGENT}}", agent).replaceAll("{{PARTNER}}", partnerOf(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");
+}
+function codexSection() {
+    return `<!-- pair:start -->\n${renderPrompt("codex").trimEnd()}\n<!-- pair:end -->\n`;
+}
+function init(channel, root) {
+    channelAccess(channel, () => mkdirSync(channel, { recursive: true }));
+    const skillDir = join(root, ".claude", "skills", "pair");
+    mkdirSync(skillDir, { recursive: true });
+    writeFileSync(join(skillDir, "SKILL.md"), claudeSkill());
+    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);
+    return [
+        `channel: ${channel}`,
+        `wrote: ${join(skillDir, "SKILL.md")}`,
+        `wrote: ${agentsPath} (pair section)`,
+        "",
+        sandboxConfig(channel),
+    ].join("\n");
+}
+function readBody(source) {
+    if (!source) {
+        throw new PairError("send needs a message file, or - for stdin");
+    }
+    if (source !== "-" && !existsSync(source)) {
+        throw new PairError(`message file not found: ${source}`);
+    }
+    const body = readFileSync(source === "-" ? 0 : source, "utf8");
+    if (!body.trim()) {
+        throw new PairError("message body is empty");
+    }
+    return body;
+}
+function oneOf(value, allowed, what) {
+    if (!value || !allowed.includes(value)) {
+        throw new PairError(`${what} must be one of: ${allowed.join(", ")}${value ? ` (got "${value}")` : ""}`);
+    }
+    return value;
+}
+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 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`;
+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" } },
+    });
+    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.
+                console.log(`pair: no message for ${me} yet. Run \`pair wait --as ${me}\` again.`);
+            }
+            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;
+        default:
+            console.error(USAGE);
+            return 1;
+    }
+}
+main(process.argv.slice(2)).then((code) => {
+    process.exitCode = code;
+}, (error) => {
+    const isUsageError = error instanceof PairError || (error instanceof Error && "code" in error && String(error.code).startsWith("ERR_PARSE_ARGS"));
+    if (isUsageError) {
+        console.error(`pair: ${error.message}`);
+        process.exitCode = 1;
+        return;
+    }
+    throw error;
+});

package/package.json

@@ -1,6 +1,41 @@
 {
   "name": "claude-codex-pair",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "0.1.1",
+  "description": "Claude Code and Codex review each other's work over a file-system chat channel",
+  "keywords": [
+    "claude-code",
+    "codex",
+    "code-review",
+    "ai-agents",
+    "cli"
+  ],
+  "license": "Unlicense",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/leonlee/cc-pair.git"
+  },
+  "homepage": "https://github.com/leonlee/cc-pair#readme",
+  "bugs": "https://github.com/leonlee/cc-pair/issues",
+  "type": "module",
+  "bin": {
+    "pair": "dist/pair.js"
+  },
+  "files": [
+    "dist",
+    "prompts",
+    "DESIGN.md"
+  ],
+  "scripts": {
+    "build": "tsc",
+    "prepare": "tsc",
+    "prepublishOnly": "npm test",
+    "test": "tsc && node --test"
+  },
+  "engines": {
+    "node": ">=22"
+  },
+  "devDependencies": {
+    "@types/node": "^22.0.0",
+    "typescript": "^5.6.0"
+  }
+}

package/prompts/pair.md

@@ -0,0 +1,87 @@
+# pair: review loop with {{PARTNER}}
+
+These instructions are for `{{AGENT}}` only. If you are not `{{AGENT}}`, ignore this section.
+
+You are `{{AGENT}}`. Your partner `{{PARTNER}}` runs in another terminal on the same repo.
+You talk only through the `pair` CLI. Always pass `--as {{AGENT}}`.
+
+## How to wait
+
+`pair wait` returns as soon as a message for you arrives. Wait in whichever way costs the fewest
+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.
+- 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.
+
+During idle waits, don't send unsolicited status updates. If your runtime requires a progress
+message, write exactly `waiting for {{PARTNER}}`, with nothing added. Answer direct user questions and
+report new messages or failures normally.
+
+`pair wait` prints only the newest message. If it lists earlier messages that aren't in your context
+(for example, after a restart), read those files before acting. To see a thread that has already
+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
+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.
+
+## Ask {{PARTNER}} for a review (you are the author)
+
+When you finish a task:
+
+1. Send a request with what changed and why, what to focus on, and the files touched.
+   ```
+   pair send request --as {{AGENT}} - <<'EOF'
+   ## Summary
+   ...
+   ## Focus
+   ...
+   ## Files
+   - src/a.ts
+   EOF
+   ```
+2. Wait for the review (see How to wait).
+3. On a review with verdict `changes`, check every finding against the code yourself. Reviewers
+   are sometimes wrong. For each one, fix it, reject it with a concrete reason, or defer it. Then reply:
+   ```
+   pair send response --as {{AGENT}} - <<'EOF'
+   ### F1 fixed: <what changed>
+   ### F2 rejected: <why it is not a defect>
+   ### F3 deferred: <why, and where it is tracked>
+   EOF
+   ```
+   Then go back to step 2.
+4. Stop when `wait` reports the thread approved. If it reports ESCALATED, stop and ask the user.
+
+## Review for {{PARTNER}} (when the user says "be my reviewer" or "listen")
+
+Loop: wait for a message (see How to wait), review, send your review, then wait again.
+
+- On a request, read the listed files in the repo and review the change.
+- On a response, re-check fixed findings and judge each rejection on its merits. Accept good
+  reasons. Re-raise only with a counter-argument. Don't add new nitpicks in later rounds.
+
+```
+pair send review --as {{AGENT}} --verdict changes - <<'EOF'
+### F1 [high] src/a.ts:42: null deref in parse()
+How it fails, and the suggested fix.
+### F2 [low] src/b.ts:7: ...
+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.
+Severity levels: `high` (bug, data loss, security), `medium` (likely bug, missing edge case),
+`low` (style, naming).