claude-codex-pair 0.4.0 → 0.5.1

package/DESIGN.md

@@ -7,7 +7,7 @@ and they talk through a shared directory that works like a chat channel.
 
 | Topic | Choice |
 |---|---|
-| Topology | Two live sessions. No headless spawning. |
+| Topology | Manual mode uses two live sessions. Opt-in `pair start --as <author>` owns an interactive author and starts a headless reviewer for each round. |
 | 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 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. |
@@ -86,7 +86,9 @@ at most once a day, cache the answer under the state directory, and stay quiet o
 to stderr after the command's own output, so `pair wait`'s first line is still the delivery or
 timeout line agents read. `pair upgrade` installs with npm, then runs the `init` of the package it
 just installed (found with `npm root --global`), not the first `pair` on PATH, because both this
-process and an older copy on PATH would write the old templates.
+process and an older copy on PATH would write the old templates. It asks `npm view` first, so it uses
+the same registry as the install. Already on the latest version, it only runs the in-process
+refresh. If the check fails, it goes ahead with the install, which reports the actual npm error.
 
 Channel operations report `EACCES` and `EPERM` with the affected path and the sandbox
 configuration printed by `init`. Either ordinary permissions or sandbox restrictions can
@@ -144,6 +146,76 @@ A note already accepted by the daemon still runs either way, so the prompt tells
 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.
 
+## Auto sessions
+
+`pair start` runs in the user's terminal outside agent sandboxes. It resolves both CLI executables
+once, binds a private Unix control socket for this worktree/channel/state-directory combination,
+and forks an IPC guardian. A second launcher cannot bind that socket. `pair status` and `pair stop`
+contact the live owner; persisted PIDs are diagnostic only. State and rotating reviewer logs are
+kept beside the existing listener state. The short socket path is under a private
+`/tmp/pair-auto-<uid>/` directory (or `PAIR_AUTO_SOCKET_DIR`) because macOS limits Unix socket path
+length. The path is canonicalized, and a Claude author receives an exact, per-session
+`sandbox.network.allowUnixSockets` entry through `--settings`. No global settings file is edited.
+
+The guardian owns the interactive author and each bounded reviewer in separate Unix process groups.
+The author inherits the terminal streams; the guardian forwards resize signals. Since `setsid`
+removes its controlling terminal, `/dev/tty` consumers and Ctrl+Z job control are unsupported.
+The launcher saves tty state and restores it during cleanup, and the guardian does so if the
+launcher dies. Reviewers stream
+JSON events into the launcher, which records their session IDs. Each request/response from the auto
+author asks the owner to run one review round and waits for its result over the control socket.
+The owner validates that the message is pending in its author's lane. Duplicate requests for the
+same running message share the job. A saved session is resumed only within the same review thread;
+no `--last` session lookup is used.
+
+Optional `--reviewer-model` and `--reviewer-effort` overrides are applied on every reviewer launch,
+including resume. Codex receives `--model` and `--config model_reasoning_effort="LEVEL"`; Claude
+receives `--model` and `--effort`. Overrides never enter the interactive author's arguments or
+persist to either CLI's config. The live state reports these requested overrides and labels
+omitted values as `CLI default`, since the launcher does not resolve inherited provider settings.
+Known effort names are checked for the reviewer backend before startup; each CLI/model validates
+whether it supports the selected combination.
+
+The reviewer receives instructions to read one message, send one verdict, and exit. Its CLI role
+and expected message are also checked by `pair send`/`wait`, avoiding an unrelated pending author
+duty in the opposite lane. Reviewer exits are checked against the on-disk verdict, not just the
+process exit code. Successful verdicts are returned through the author's original `send`, using
+the existing message formatting and archive behavior. This replaces idle model waits and MCP
+notifications in auto mode. An explicit author `wait` retries a failed pending round. Interactive
+Claude runs these blocking review commands as background Bash tasks and reads their completion
+output, avoiding the foreground tool timeout. Its author instructions are appended to the system
+prompt; generated instructions also tell agents to check their role after clear/compaction.
+
+Every termination path stops accepting jobs, terminates owned groups, escalates to SIGKILL after
+the configured grace period, and observes the CLI exit and stream closure. Even a successful CLI
+exit triggers cleanup of remaining group members. A private IPC disconnect cleans up if the
+launcher dies; a monotonic heartbeat deadline covers a hung launcher without counting wall-clock
+jumps or suspended wall-clock time. The guardian itself exits after its
+jobs are collected. The launcher also tracks live child identities for emergency cleanup if the
+guardian fails. No cleanup loads a PID from disk and signals it, and no command kills by agent name.
+
+This is process-group supervision on macOS/Linux, not OS containment: descendants that create their
+own sessions/groups can escape it, and killing both supervisors can leave a stale control socket.
+Stale sockets are reported for manual inspection, never silently replaced. Windows auto mode is
+not yet supported. Manual mode and its notification lifecycle remain unchanged.
+
+## Manual reset
+
+`pair reset` moves whole pending lanes into `resets/<reset-id>/` in the current channel, leaving
+source files, archived history, and session registrations untouched. `--as` selects the lane's
+author; omitting it resets both, independent of `PAIR_AGENT`. Moving whole lanes also handles
+legacy flat files, malformed messages, partial writes, and older thread directories without
+requiring successful protocol parsing. A small `reset.json` records the time, worktree and planned
+lanes. Reset backups are deliberately outside archive retention and `pair history`.
+Both preview and reset output show best-effort lane states. Unread closed threads still in their
+lanes are included in the backup; only already-archived history is left in `pair history`.
+
+Each lane rename is atomic. If a later rename fails, the command reports which lanes moved and
+where their backup is; it never deletes or rolls back over new data. Manual agents must be stopped
+before reset. On macOS/Linux, reset exclusively binds the auto-mode control socket until it finishes,
+so it refuses live or stale ownership and serializes with `pair start`. `--dry-run` only inspects
+the pending lanes and creates neither backups nor an ownership socket, even while auto mode runs.
+
 ## Usage
 
 ```
@@ -161,6 +233,7 @@ pair wait --as <agent> [--timeout s]
 pair status
 pair history [thread-id]
 pair clean --keep N
+pair reset [--as <agent>] [--dry-run]
 pair init
 pair uninit
 pair register | unregister
@@ -169,7 +242,7 @@ pair mcp
 
 ## 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.
+- A lane still in the old flat layout (before 1c588ed) isn't migrated. Commands fail with a recovery hint; `pair reset` can back up and clear it without parsing the old files.
 - 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.
 - 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:

package/README.md

@@ -18,6 +18,9 @@ terminal A: claude                         terminal B: codex ("be my reviewer")
 
 Roles are symmetric: Codex can ask Claude for a review the same way.
 
+Pair also has an opt-in auto mode: open one interactive agent, and pair starts its partner for
+each review round. The existing two-terminal workflow remains available.
+
 ## Install
 
 ```sh
@@ -114,11 +117,138 @@ pending. The note never contains message text. Codex reads the message itself wi
 
 ### Start the agents
 
+For auto mode, see below. For the manual workflow, start both agents yourself:
+
 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.
 
+### Auto mode (macOS and Linux)
+
+Install and sign in to both Claude Code and Codex first. After `pair init`, run either command in
+your own terminal, outside an agent session:
+
+```sh
+pair start --as claude    # interactive Claude, automatic Codex reviewer
+pair start --as codex     # interactive Codex, automatic Claude reviewer
+```
+
+Give the interactive agent a task as usual. When it sends a review request, pair starts the partner
+in non-interactive mode in the same worktree. Each reviewer handles one round and exits. Follow-up
+rounds resume that reviewer's saved session; new threads start fresh sessions. Requests and responses
+return the review inline, so auto mode does not require pair's Codex MCP notification server or a
+second terminal. The author still verifies findings and fixes or rejects them. The existing round
+cap and escalation rules apply.
+
+Auto mode uses a CLI wrapper belonging to this run. Agents receive its absolute path as `PAIR_BIN`,
+so a login shell cannot accidentally use an older pair installation. The launcher passes the role
+instructions at startup; the generated instructions from `pair init` also describe auto mode.
+Claude receives them through `--append-system-prompt` so they survive a clear. Interactive Claude
+runs managed `send` and retry commands in the Bash tool's background mode, then reads their output
+on completion; a review can take longer than the foreground tool timeout.
+
+For a Claude author, the launcher passes `sandbox.network.allowUnixSockets` through `--settings`,
+allowing only this worktree's exact control socket for that session. It prints the path at startup,
+uses the canonical `/private/tmp` path on macOS, and leaves your settings files unchanged. Existing
+allowlist entries merge with this one. If managed policy still denies the connection, the failed
+request names the required setting and stays on disk. See [Claude's sandbox documentation](https://code.claude.com/docs/en/sandboxing).
+
+Use another terminal in this worktree to inspect or stop the session:
+
+```sh
+pair status
+pair ps -v
+pair stop                # stops the author and all managed reviewers/tools
+```
+
+Exiting the author also stops its managed workers. Pair uses separate process groups, a guardian
+with a private parent connection and heartbeat, and termination followed by forced termination
+after a grace period. The guardian cleans up if the launcher is force-killed. Cleanup covers
+ordinary descendants that remain in their process group; deliberately detached descendants or
+simultaneously killing both the launcher and guardian require OS-level supervision for stronger
+guarantees. Pair never signals a process based on a saved PID or its executable name.
+The heartbeat uses monotonic time so clock corrections and suspended wall-clock time do not expire
+the session. Pair saves and restores terminal settings on exit, including after forced author
+termination. Process-group isolation gives the author inherited terminal streams but no controlling
+terminal: programs that require `/dev/tty` (such as some password prompts) and Ctrl+Z job control are
+not supported in this mode. Run those operations from your own terminal.
+
+Only one auto launcher can own a worktree at a time. Stop a manual reviewer before switching to
+auto mode; an existing Codex registration blocks automatic Codex reviewer startup until you run
+`pair unregister`. If all supervising processes are forcibly killed, a stale socket may remain.
+`pair status` names it; inspect it before removing it and restarting. Pair does not automatically
+take over stale sockets or kill the PIDs in old state files.
+
+Reviewers use saved CLI authentication. Codex runs with its workspace-write sandbox and explicit
+channel access. Its worktree is writable, for example for test artifacts; source edits are prohibited
+by its instructions rather than an OS read-only boundary. Claude runs with `dontAsk`, its configured tool permissions, and additional allow
+rules for reading/searching and the pair CLI; commands requiring other permission approval are
+denied. Auto mode does not enable either CLI's permission-bypass flags. Keep the sandbox paths from
+`pair init` configured for the author. A failed launch, missing verdict, or timeout preserves the
+request. The author can run `pair wait --as <author>` inside the same auto session to retry that
+round. `pair status` reports the last failure and the bounded log location.
+
+Optional launch settings:
+
+```sh
+pair start --as claude --reviewer-model CODEX_MODEL_ID --reviewer-effort high
+pair start --as codex --reviewer-model opus --reviewer-effort high
+pair start --as claude --timeout 900 --grace 2
+pair start --as codex --claude /absolute/path/to/claude --codex /absolute/path/to/codex
+```
+
+`--timeout` limits each reviewer round (default 900 seconds, maximum 86400); `--grace` is the wait
+between termination and forced termination (default 2 seconds, maximum 30). Executables are
+resolved once at startup. The interactive author is not subject to the reviewer timeout.
+
+`--reviewer-model` accepts the partner CLI's model ID or alias. `--reviewer-effort` sets the
+reviewer's reasoning effort. These overrides apply to every review round, including resumed
+sessions, and leave the interactive author's settings alone. Either flag can be omitted; each
+omitted setting inherits the reviewer CLI's normal defaults. No CLI configuration files are edited.
+
+For Codex, effort is passed as `--config model_reasoning_effort="LEVEL"`; recognized levels are
+`none`, `minimal`, `low`, `medium`, `high`, `xhigh`, `max`, and `ultra`. For Claude, it is passed as
+`--effort LEVEL`; recognized levels are `low`, `medium`, `high`, `xhigh`, `max`, and `ultracode`.
+The installed CLI and selected model must support the requested combination; an unsupported
+combination fails the review round and keeps the request available for recovery.
+
+`pair status` and `pair ps` display the requested model and effort overrides. An omitted override
+is shown as `CLI default`; pair does not claim to resolve the provider's inherited settings.
+
+## Reset stale requests
+
+Run `pair reset` manually from the affected worktree to clear outdated pending requests:
+
+```sh
+pair reset --dry-run          # preview the affected lanes without changing files
+pair reset                    # reset both directions in this worktree
+pair reset --as claude        # only requests authored by Claude (claude-to-codex)
+pair reset --as codex         # only requests authored by Codex (codex-to-claude)
+```
+
+`--dry-run` is only supported by `reset`; other commands reject it before making changes.
+
+Stop manual author/reviewer sessions first. If an auto session owns the worktree, reset refuses
+to change it; run `pair stop` before resetting. Preview remains available while auto mode runs.
+Reset also holds the auto-mode ownership socket while moving requests, so another auto launcher
+cannot start during the operation. If a stale socket is left after all supervising processes were
+killed, inspect the path reported by `pair status` before removing that socket and retrying.
+
+Reset moves each selected lane into `~/.pair/<repo>-<hash>/resets/<reset-id>/` (under `PAIR_HOME`
+when configured) and prints the backup path. It preserves every file, including malformed requests,
+legacy layouts, older threads, and partial writes. New requests start with fresh lanes. Source
+files, finished history in `archive/`, and Codex notification registrations are unchanged.
+`--as` selects the request's author; without it both lanes are reset, regardless of `PAIR_AGENT`.
+Unread approvals and escalations still in a lane are backed up too, so their verdicts will no
+longer be delivered. Preview and reset output show each lane's state, including `closed`, or
+`unparseable` if the requests cannot be read by the protocol.
+
+Backups include `reset.json` with the worktree, time, and selected lanes. They are separate from
+finished review history, so `pair history`, automatic archive retention, and `pair clean` leave
+them alone. Delete a backup manually when you no longer need it. A reset that fails partway names
+the backup holding already-moved requests; the remaining lane is left available for a retry.
+
 ## Upgrading from 0.1.x
 
 Codex no longer keeps a long `pair wait` running. To keep automatic pickup after upgrading, install
@@ -162,16 +292,20 @@ 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 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 launcher and its managed agents
 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 reset [--as <claude|codex>] [--dry-run]  # back up stale pending lanes (default: both)
 pair init
 pair upgrade               # install the latest pair from npm, then refresh this worktree's instructions
 pair uninit                # undo pair init in this worktree (keeps history; see "Uninstall")
 pair register | unregister # run by Codex in its shell: let pair_listen notify this session
 pair mcp                   # stdio MCP server for Codex (see "Let pair wake Codex")
-pair ps [-v]               # running pair mcp and pair wait processes by worktree, with each worktree's Codex registration (-v: full commands)
+pair ps [-v]               # pair processes by worktree, including auto launchers/guardians (-v: full commands)
 ```
 
 `pair status` shows the channel, worktree root, installed package version, and each lane's turn.
@@ -203,8 +337,10 @@ offline or sandboxed.
 ## Upgrading
 
 Run `pair upgrade` in your own terminal, not through an agent: agent sandboxes block the network and
-global installs. It runs `npm install -g claude-codex-pair@latest`, then the new `pair init` in the
-current worktree if pair is set up there. Other worktrees refresh their instructions on the next
+global installs. If npm has a newer version, it runs `npm install -g claude-codex-pair@latest`, then
+the new `pair init` in the current worktree if pair is set up there, and prints only the files that
+`init` wrote or kept. Already on the latest version, it installs nothing and only refreshes this
+worktree's stale instructions. Other worktrees refresh their instructions on the next
 `pair send`, `wait`, `history` or `clean`. pair owns these files, so edits inside them are
 overwritten. pair, including `pair init`, never rewrites instructions that a newer pair wrote, so
 worktrees shared by different versions don't flip back and forth. To downgrade, delete them first. Restart Claude Code and Codex afterwards. Running
@@ -223,6 +359,7 @@ so a cleanup problem doesn't prevent delivering a review or starting the next th
 | `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 |
 | `PAIR_NO_UPDATE_CHECK` | (none) | Any value turns off the daily npm version check |
+| `PAIR_AUTO_SOCKET_DIR` | `/tmp/pair-auto-<uid>` | Optional absolute private directory for auto-mode sockets; keep it short for Unix socket path limits |
 
 ## Uninstall