claude-codex-pair 0.4.0 → 0.5.1

package/dist/pair.js

@@ -8,6 +8,7 @@ import { createInterface } from "node:readline";
 import { setTimeout as sleep } from "node:timers/promises";
 import { fileURLToPath } from "node:url";
 import { parseArgs } from "node:util";
+import { autoCall, autoSocketPath, autoStatus, runGuardian, startAuto, stopAuto, withAutoStopped } from "./auto.js";
 const AGENTS = ["claude", "codex"];
 const MESSAGE_TYPES = ["request", "review", "response"];
 const VERDICTS = ["approve", "changes"];
@@ -111,7 +112,7 @@ 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.`);
+        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 stop the agents and run pair reset --as ${thread.author} to back it up and clear the lane.`);
     }
     const latest = entries
         .filter((entry) => entry.isDirectory() && !entry.name.startsWith("."))
@@ -296,7 +297,7 @@ function send(channel, me, type, body, verdict) {
     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`);
+            throw new PairError(`a review thread to ${thread.reviewer} is already open (${state.kind}); finish it first, or stop the agents and manually run pair reset --as ${me} to back up and clear this lane`);
         }
         if (state.kind === "closed") {
             archive(channel, state.last);
@@ -319,6 +320,9 @@ function sendReview(channel, me, body, verdict) {
     if (state.kind !== "awaiting-review") {
         throw new PairError(`cannot send review: nothing from ${thread.author} is waiting for review (thread is ${state.kind})`);
     }
+    if (process.env.PAIR_AUTO_ROLE === "reviewer" && state.last.file !== process.env.PAIR_AUTO_MESSAGE) {
+        throw new PairError("managed reviewer cannot reply to a different message");
+    }
     const round = state.last.round;
     const status = verdict === "approve" ? "approved" : round >= maxRounds() ? "escalated" : "open";
     const review = { from: me, type: "review", round, verdict, status };
@@ -329,6 +333,13 @@ function escalationNotice() {
     return `ESCALATED: round cap (${maxRounds()}) reached with open findings. STOP and ask the user how to proceed.`;
 }
 function pendingFor(channel, me) {
+    if (process.env.PAIR_AUTO_ROLE === "reviewer") {
+        const thread = threadFor(channel, partnerOf(me));
+        const messages = listMessages(thread);
+        const state = stateOf(messages);
+        return state.kind === "awaiting-review" && state.last.file === process.env.PAIR_AUTO_MESSAGE
+            ? { thread, state, earlier: messages.slice(0, -1) } : undefined;
+    }
     const asAuthor = threadFor(channel, me);
     const authorMessages = listMessages(asAuthor);
     const authorState = stateOf(authorMessages);
@@ -892,24 +903,31 @@ function status(channel, root) {
  * Returns a note for after the command's output: agents read `pair wait`'s first line, with stderr merged.
  */
 function refreshInstructions(root) {
-    const skillPath = join(root, ".claude", "skills", "pair", "SKILL.md");
-    const agentsPath = join(root, "AGENTS.md");
-    const refreshed = [];
     try {
-        if (instructionState(skillPath, claudeSkill()) === "stale") {
-            writeFileSync(skillPath, claudeSkill());
-            refreshed.push(skillPath);
-        }
-        if (instructionState(agentsPath, codexSection(), true) === "stale") {
-            writeFileSync(agentsPath, readFileSync(agentsPath, "utf8").replace(PAIR_SECTION, () => codexSection()));
-            refreshed.push(`${agentsPath} (pair section)`);
-        }
+        return refreshedNote(refreshStale(root));
     }
     catch (error) {
         // A read-only sandbox: message delivery must still work, so report and go on.
         const reason = error instanceof Error ? error.message : String(error);
         return `pair: couldn't refresh instructions (${reason}); run \`pair init\` in your own terminal`;
     }
+}
+/** The stale instruction files it rewrote. A write failure throws. */
+function refreshStale(root) {
+    const skillPath = join(root, ".claude", "skills", "pair", "SKILL.md");
+    const agentsPath = join(root, "AGENTS.md");
+    const refreshed = [];
+    if (instructionState(skillPath, claudeSkill()) === "stale") {
+        writeFileSync(skillPath, claudeSkill());
+        refreshed.push(skillPath);
+    }
+    if (instructionState(agentsPath, codexSection(), true) === "stale") {
+        writeFileSync(agentsPath, readFileSync(agentsPath, "utf8").replace(PAIR_SECTION, () => codexSection()));
+        refreshed.push(`${agentsPath} (pair section)`);
+    }
+    return refreshed;
+}
+function refreshedNote(refreshed) {
     return refreshed.length > 0
         ? `pair: refreshed ${refreshed.join(", ")} to pair ${PACKAGE.version}; reload agent sessions to load them`
         : undefined;
@@ -964,6 +982,21 @@ async function updateNotice() {
 }
 /** Installs the latest pair, then lets the new version refresh this worktree's instructions. */
 function upgrade(root) {
+    // npm's own answer, from the registry it installs from; if it fails, the install reports why.
+    const view = spawnSync("npm", ["view", PACKAGE.name, "version"], { encoding: "utf8" });
+    const latest = view.status === 0 ? view.stdout.trim() : undefined;
+    if (latest && !isNewer(latest, PACKAGE.version)) {
+        let note;
+        try {
+            note = refreshedNote(refreshStale(root)); // refreshing is all that is left to do, so a failure fails upgrade
+        }
+        catch (error) {
+            const reason = error instanceof Error ? error.message : String(error);
+            throw new PairError(`already up to date, but couldn't refresh instructions (${reason})`);
+        }
+        console.log(`already up to date: ${PACKAGE.name} ${PACKAGE.version}${note ? `\n${note}` : ""}`);
+        return 0;
+    }
     const install = spawnSync("npm", ["install", "--global", `${PACKAGE.name}@latest`], { stdio: "inherit" });
     if (install.error) {
         throw new PairError(`couldn't run npm: ${install.error.message}`);
@@ -982,12 +1015,14 @@ function upgrade(root) {
             throw new PairError("installed, but `npm root --global` failed; run `pair init` yourself");
         }
         const installed = join(globalRoot.stdout.trim(), PACKAGE.name, "dist", "pair.js");
-        const init = spawnSync(process.execPath, [installed, "init"], { cwd: root, stdio: "inherit" });
+        const init = spawnSync(process.execPath, [installed, "init"], { cwd: root, encoding: "utf8", stdio: ["ignore", "pipe", "inherit"] });
         if (init.error || init.status !== 0) {
             throw new PairError(`installed, but the new \`pair init\` failed${init.error ? `: ${init.error.message}` : ""}; run it yourself`);
         }
+        // Only what it did to the files: the sandbox and `codex mcp add` setup it also prints is already done.
+        console.log(init.stdout.split("\n").filter((line) => /^(?:wrote|kept): /.test(line)).join("\n"));
     }
-    console.log("Restart Claude Code and Codex sessions to load the new version. Other worktrees refresh on their next pair send or wait.");
+    console.log(`upgraded: ${PACKAGE.name} ${PACKAGE.version} → ${latest ?? "latest"}. Restart Claude Code and Codex sessions to load it; other worktrees refresh on their next pair send or wait.`);
     return 0;
 }
 /** Finished threads, most recently finished first. Entries that aren't archived threads are ignored. */
@@ -1064,6 +1099,55 @@ function clean(channel, keepValue) {
     const keep = parseKeep(keepValue, "--keep");
     return `removed ${prune(channel, keep)} finished thread(s), kept up to ${keep}`;
 }
+/** Back up whole lanes so reset also repairs legacy, corrupt, and partially written requests. */
+function reset(channel, root, author, dryRun) {
+    const lanes = (author ? [author] : AGENTS)
+        .flatMap((agent) => {
+        const lane = threadFor(channel, agent).lane;
+        const stat = lstatSync(lane, { throwIfNoEntry: false });
+        if (!stat || (stat.isDirectory() && readdirSync(lane).length === 0))
+            return [];
+        let label = `${basename(lane)}: ${stat.isSymbolicLink() ? "symlink" : "unparseable"}`;
+        if (stat.isDirectory()) {
+            try {
+                label = describe(channel, agent);
+            }
+            catch { /* backup must still work for malformed requests */ }
+        }
+        return [{ lane, label }];
+    });
+    if (lanes.length === 0)
+        return `nothing to reset in ${root}`;
+    if (dryRun)
+        return [
+            `would reset in ${root}:`,
+            ...lanes.map(({ label }) => `  ${label}`),
+            `would preserve their contents under ${join(channel, "resets")}; no files changed`,
+        ].join("\n");
+    const resetRoot = join(channel, "resets");
+    const stat = lstatSync(resetRoot, { throwIfNoEntry: false });
+    if (stat && !stat.isDirectory())
+        throw new PairError(`refusing to write reset backups through a non-directory or symlink: ${resetRoot}`);
+    const backup = join(resetRoot, newThreadId());
+    mkdirSync(backup, { recursive: true });
+    const moved = [];
+    try {
+        writeFileSync(join(backup, "reset.json"), `${JSON.stringify({ resetAt: new Date().toISOString(), worktree: root, plannedLanes: lanes.map(({ lane }) => basename(lane)) }, null, 2)}\n`);
+        for (const { lane } of lanes) {
+            renameSync(lane, join(backup, basename(lane)));
+            moved.push(basename(lane));
+        }
+    }
+    catch (error) {
+        const failure = channelError(channel, error);
+        throw new PairError(`reset failed${moved.length ? ` after moving ${moved.join(", ")}` : ""}; any moved requests are preserved at ${backup}: ${failure instanceof Error ? failure.message : String(failure)}`);
+    }
+    return [
+        ...lanes.map(({ label }) => `reset: ${label}`),
+        `saved pending requests: ${backup}`,
+        "Archived history and source files are unchanged. Restart manual agents before sending a fresh request.",
+    ].join("\n");
+}
 function renderPrompt(agent) {
     const template = readFileSync(join(PACKAGE_ROOT, "prompts", "pair.md"), "utf8");
     return template.replaceAll("{{AGENT}}", agent).replaceAll("{{PARTNER}}", partnerOf(agent));
@@ -1109,6 +1193,7 @@ function init(channel, root) {
         "",
         sandboxConfig(channel),
         "",
+        ...(process.platform !== "win32" ? [`Auto mode: pair start --as claude adds sandbox.network.allowUnixSockets for ${autoSocketPath(stateDir(channel))} to that Claude session only. No persistent socket setting is needed.`, ""] : []),
         "To let pair wake Codex when a message arrives, instead of Codex polling, register pair's MCP server once:",
         `  ${mcpAddCommand(root)}`,
     ].join("\n");
@@ -1196,7 +1281,7 @@ function uninit(channel, root) {
 }
 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 PAIR_PROCESS = /^(?:\S*\/)?node(?: -\S+)* \S*\/(?:bin\/pair|dist\/pair\.js) ((?:mcp|wait|start|_auto-guardian)\b.*)$/;
 const SHELL = /^(?:\S*\/)?(?:zsh|bash|sh|dash|fish)(?: |$)/;
 function listProcesses() {
     let out;
@@ -1298,8 +1383,8 @@ function codexLine(root) {
         return error instanceof Error ? error.message : String(error);
     }
 }
-/** Every running `pair mcp` and `pair wait` on this machine, grouped by worktree. */
-function ps(verbose) {
+/** Pair listeners, waits, auto launchers and guardians on this machine, grouped by worktree. */
+async function ps(verbose) {
     const all = listProcesses();
     const byPid = new Map(all.map((proc) => [proc.pid, proc]));
     const ours = all.flatMap((proc) => {
@@ -1311,10 +1396,12 @@ function ps(verbose) {
         while (host && SHELL.test(host.command)) {
             host = byPid.get(host.ppid); // an agent runs pair wait through a shell; show the agent
         }
-        return [{ ...proc, kind: match[1].startsWith("mcp") ? "mcp" : "wait", host }];
+        const command = match[1].split(" ")[0];
+        const kind = command === "_auto-guardian" ? "guardian" : command;
+        return [{ ...proc, kind, host }];
     });
     if (ours.length === 0) {
-        return "no pair mcp or pair wait is running";
+        return "no pair mcp, wait, start or guardian is running";
     }
     const dirs = workingDirs(ours.map((proc) => proc.pid));
     const groups = new Map();
@@ -1328,14 +1415,17 @@ function ps(verbose) {
         groups.set(key, group);
     }
     const blocks = [...groups].sort(([a, x], [b, y]) => Number(!x.root) - Number(!y.root) || a.localeCompare(b));
-    return blocks
-        .map(([path, { root, procs }]) => {
+    return (await Promise.all(blocks
+        .map(async ([path, { root, procs }]) => {
         const name = root ? basename(root) : path !== "?" && !existsSync(path) ? "(deleted)" : "(no worktree)";
         const lines = [`${name}  ${shortPath(path)}`];
         const codex = root ? codexLine(root) : undefined;
         if (codex) {
             lines.push(`  codex   ${codex}`);
         }
+        if (root && procs.some((proc) => proc.kind === "start" || proc.kind === "guardian")) {
+            lines.push(...(await autoStatus(stateDir(channelDir(root)))).map((line) => `  ${line}`));
+        }
         procs.sort((a, b) => a.kind.localeCompare(b.kind) || a.pid - b.pid);
         for (const proc of procs) {
             const host = proc.host ? hostName(proc.host.command) : `⚠ parent gone (${proc.ppid})`;
@@ -1345,7 +1435,7 @@ function ps(verbose) {
             }
         }
         return lines.join("\n");
-    })
+    })))
         .join("\n\n");
 }
 function readBody(source) {
@@ -1368,43 +1458,125 @@ function oneOf(value, allowed, what) {
     return value;
 }
 const USAGE = `usage:
+  pair start --as <claude|codex> [--reviewer-model MODEL] [--reviewer-effort LEVEL]
+             [--claude /path] [--codex /path] [--timeout seconds] [--grace seconds]
+  pair stop                                           (stop this worktree's auto session and its managed agents)
   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)
   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 reset [--as <claude|codex>] [--dry-run]        (back up pending lanes; --as selects their author, default: both)
   pair init
   pair upgrade                                        (install the latest pair from npm, then refresh this worktree)
   pair uninit                                         (remove what pair init wrote in this worktree; keeps history)
   pair register | unregister                          (in Codex's shell: let pair_listen notify this session)
   pair mcp                                            (stdio MCP server for Codex, providing pair_listen)
-  pair ps [-v]                                        (running pair mcp and pair wait processes, by worktree; -v: full commands)`;
+  pair ps [-v]                                        (running pair processes, including auto owners, by worktree; -v: full commands)`;
 async function main(argv) {
     const { values, positionals } = parseArgs({
         args: argv,
         allowPositionals: true,
-        options: { as: { type: "string" }, verdict: { type: "string" }, timeout: { type: "string" }, keep: { type: "string" }, verbose: { type: "boolean", short: "v" } },
+        options: { as: { type: "string" }, verdict: { type: "string" }, timeout: { type: "string" }, keep: { type: "string" }, verbose: { type: "boolean", short: "v" }, claude: { type: "string" }, codex: { type: "string" }, grace: { type: "string" }, help: { type: "boolean", short: "h" }, "reviewer-model": { type: "string" }, "reviewer-effort": { type: "string" }, "dry-run": { type: "boolean" } },
     });
     const [command, ...rest] = positionals;
+    if (values.help || command === "help") {
+        console.log(USAGE);
+        return 0;
+    }
+    if (values["dry-run"] && command !== "reset")
+        throw new PairError("--dry-run is only supported by pair reset");
     const root = worktreeRoot();
     const channel = channelDir(root);
     const agent = () => oneOf(values.as ?? process.env.PAIR_AGENT, AGENTS, "--as (or PAIR_AGENT)");
     const refreshNote = REFRESHING_COMMANDS.includes(command) ? refreshInstructions(root) : undefined;
+    const managedReview = async (me) => {
+        if (process.env.PAIR_AUTO_ROLE !== "author" || !process.env.PAIR_AUTO_RUN)
+            return false;
+        const thread = threadFor(channel, me);
+        const state = channelAccess(channel, () => stateOf(listMessages(thread)));
+        if (state.kind !== "awaiting-review")
+            return false;
+        try {
+            await autoCall(stateDir(channel), { action: "review", run: process.env.PAIR_AUTO_RUN, file: state.last.file }, 24 * 60 * 60 * 1000);
+        }
+        catch (error) {
+            if (hasCode(error, "EPERM") || hasCode(error, "EACCES")) {
+                throw new PairError(`managed review cannot connect to ${autoSocketPath(stateDir(channel))}. Claude needs sandbox.network.allowUnixSockets for this exact socket. pair start --as claude supplies it through --settings; check managed sandbox policy if access is still denied. The request remains on disk.`);
+            }
+            throw new PairError(`managed review failed: ${error instanceof Error ? error.message : String(error)}. The request remains on disk.`);
+        }
+        return true;
+    };
     try {
         switch (command) {
+            case "_auto-guardian":
+                await runGuardian();
+                return 0;
+            case "start": {
+                const me = agent();
+                try {
+                    if (process.env.CODEX_THREAD_ID || process.env.CLAUDECODE)
+                        throw new PairError("run pair start in your own terminal, outside Claude or Codex");
+                    if (me === "claude" && readRegistration(channel)) {
+                        throw new PairError("a manual Codex reviewer is registered here; stop it and run pair unregister before starting auto mode");
+                    }
+                    const timeout = positiveNumber(values.timeout ?? "900", "--timeout");
+                    const grace = positiveNumber(values.grace ?? "2", "--grace");
+                    if (timeout > 86400 || grace > 30)
+                        throw new PairError("--timeout must be at most 86400 seconds and --grace at most 30 seconds");
+                    return await startAuto({
+                        author: me, root, channel, stateDir: stateDir(channel), entry: fileURLToPath(import.meta.url),
+                        claude: values.claude, codex: values.codex,
+                        reviewerModel: values["reviewer-model"], reviewerEffort: values["reviewer-effort"],
+                        timeoutMs: timeout * 1000,
+                        graceMs: grace * 1000,
+                        target: () => {
+                            const state = stateOf(listMessages(threadFor(channel, me)));
+                            return state.kind === "awaiting-review" ? { file: state.last.file, thread: basename(dirname(state.last.file)) } : undefined;
+                        },
+                        reviewed: (file) => {
+                            const messages = listMessages(threadFor(channel, me));
+                            const index = messages.findIndex((message) => message.file === file);
+                            return index >= 0 && messages[index + 1]?.type === "review";
+                        },
+                    });
+                }
+                catch (error) {
+                    throw new PairError(error instanceof Error ? error.message : String(error));
+                }
+            }
+            case "stop":
+                try {
+                    console.log(await stopAuto(stateDir(channel)));
+                }
+                catch (error) {
+                    throw new PairError(error instanceof Error ? error.message : String(error));
+                }
+                return 0;
             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();
+                if (process.env.PAIR_AUTO_ROLE && me !== process.env.PAIR_AGENT)
+                    throw new PairError("auto mode agent identity does not match --as");
+                if (process.env.PAIR_AUTO_ROLE === "reviewer" && (me !== process.env.PAIR_AGENT || type !== "review")) {
+                    throw new PairError("a managed reviewer may only send its own review verdict");
+                }
                 const body = readBody(rest[1]);
                 console.log(`sent: ${channelAccess(channel, () => send(channel, me, type, body, verdict))}`);
+                if (type !== "review" && await managedReview(me))
+                    await wait(channel, me, 1);
                 return 0;
             }
             case "wait": {
                 autoKeep(); // reject a bad PAIR_KEEP before touching any thread
                 const me = agent();
+                if (process.env.PAIR_AUTO_ROLE && me !== process.env.PAIR_AGENT)
+                    throw new PairError("auto mode agent identity does not match --as");
                 const timeout = positiveNumber(values.timeout ?? String(DEFAULT_WAIT_SECONDS), "--timeout");
+                await managedReview(me); // explicit retry after a failed managed round
                 if (!(await wait(channel, me, timeout))) {
                     // Exit 0: a timeout is routine, and agent UIs show any non-zero exit as a failure. No "run it
                     // again" here: whether to wait again differs by agent (Codex must not poll), so the prompt says.
@@ -1413,7 +1585,7 @@ async function main(argv) {
                 return 0;
             }
             case "status":
-                console.log([status(channel, root), ...(await updateNotice())].join("\n"));
+                console.log([status(channel, root), ...(await autoStatus(stateDir(channel))), ...(await updateNotice())].join("\n"));
                 return 0;
             case "history":
                 console.log(channelAccess(channel, () => history(channel, rest[0])));
@@ -1421,6 +1593,19 @@ async function main(argv) {
             case "clean":
                 console.log(channelAccess(channel, () => clean(channel, values.keep)));
                 return 0;
+            case "reset": {
+                if (rest.length)
+                    throw new PairError("reset accepts no positional arguments; use --as claude|codex to select an author lane");
+                const author = values.as === undefined ? undefined : oneOf(values.as, AGENTS, "--as");
+                const operation = () => channelAccess(channel, () => reset(channel, root, author, values["dry-run"] ?? false));
+                try {
+                    console.log(values["dry-run"] ? operation() : await withAutoStopped(stateDir(channel), operation));
+                }
+                catch (error) {
+                    throw new PairError(error instanceof Error ? error.message : String(error));
+                }
+                return 0;
+            }
             case "init":
                 console.log([init(channel, root), ...(await updateNotice())].join("\n"));
                 return 0;
@@ -1430,6 +1615,8 @@ async function main(argv) {
                 console.log(uninit(channel, root));
                 return 0;
             case "register":
+                if (process.env.PAIR_AUTO_ROLE)
+                    throw new PairError("auto mode delivers reviews inline; session registration is unnecessary");
                 console.log(channelAccess(channel, () => register(channel, root)));
                 return 0;
             case "unregister":
@@ -1439,7 +1626,7 @@ async function main(argv) {
                 await serveMcp();
                 return 0;
             case "ps":
-                console.log(ps(values.verbose ?? false));
+                console.log(await ps(values.verbose ?? false));
                 return 0;
             default:
                 console.error(USAGE);

package/package.json

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

package/prompts/pair.md

@@ -5,6 +5,27 @@ These instructions are for `{{AGENT}}` only. If you are not `{{AGENT}}`, ignore
 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}}`.
 
+## Auto mode
+
+At session start and after a clear or compaction, check `PAIR_AUTO_ROLE` in your shell before
+choosing the pair workflow below.
+
+In auto mode the launcher sets `PAIR_BIN` to its own CLI. Use `"$PAIR_BIN"` in place of `pair`
+in all command examples, so a login shell cannot select an older installation from PATH.
+
+If `PAIR_AUTO_ROLE=author`, pair owns the reviewer. After finishing a task, send your request as
+usual. `pair send request` and `pair send response` return the review inline: read it and continue
+the fix/reject loop until approval or escalation. In interactive Claude Code, run these commands
+and managed retry waits with Bash's `run_in_background: true`, end your turn, and read their output
+when the completion notification arrives. Reviews can exceed the foreground Bash timeout. This
+background command is active review work, not an idle wait loop. Do not register, call `pair_listen`,
+or run idle waits. If a managed review fails, `pair wait --as {{AGENT}}` explicitly retries the round.
+
+If `PAIR_AUTO_ROLE=reviewer`, handle exactly one pending review round. Read it with
+`pair wait --as {{AGENT}} --timeout 1`, review, send your verdict, and exit. Do not modify source,
+register, call `pair_listen`, request your own review, or wait again after sending the verdict.
+These auto-mode rules replace the waiting instructions below.
+
 ## How to wait
 
 `pair wait` returns as soon as a message for you arrives. Wait in whichever way costs the fewest