antiphon 0.1.0 → 0.3.0

package/BACKLOG.md

@@ -0,0 +1,329 @@
+# Antiphon product backlog
+
+Last reviewed: 2026-08-30
+
+Priorities here describe product risk, not release promises. The bridge keeps
+two invariants across every item: it preserves who said something, and it
+refuses ambiguity rather than guessing or broadcasting.
+
+## P0 — Lossless, paged context transfer
+
+This item is now a phase ledger rather than one open problem: the delivery and
+paging mechanics shipped, and what remains open is named below instead of
+hiding under a general "lossless" claim.
+
+### Shipped before the paging plan
+
+Provenance-safe parsers (a user message beginning with `<` is no longer
+mistaken for bridge metadata), the byte-offset reader and per-source cursor
+with generation fingerprints, the delivery lock beside each peer cursor, and
+the write-and-flush-before-advance transaction.
+
+### Completed by the paging plan
+
+- Oldest-first atomic pages of completed source records: an ordinary full page
+  targets 8,000 UTF-8 bytes and at most 40 records, and a record is never
+  split across pages.
+- The non-tool 420-character cut and the 2,600-character summary trim are
+  gone; whitespace, indentation and line structure are preserved exactly.
+- `has_more` is visible on every page, explicitly scoped to the currently
+  discovered sources.
+- An oversized record is handed whole to the automatic hooks, whose hosts
+  were measured (2026-08-30, Claude Code 2.1.251 and Codex CLI 0.151.0) to
+  spill above 10,000 characters and expose a path; both 400,251-character
+  probes matched their spill files by SHA-256. Codex's MCP tool result did
+  **not** meet that assumption — the transport kept the bytes but the model
+  could identify neither content nor a saved path — so `antiphon_read`
+  refuses an oversized record without advancing, and the next automatic hook
+  delivers it. That is a measured host behaviour, not an inference about its
+  internal truncation.
+- A rolling-upgrade-safe v3 page key: the legacy v2 value is preserved
+  byte-for-byte for still-running old processes and is never trusted as a
+  delivered frontier. Any present legacy key, and any malformed or unreadable
+  existing cursor, conservatively replays the currently discovered sources
+  from byte zero — measured at 69 Claude-source and 53 Codex-source pages on
+  the reviewed snapshots — with a fixed replay reason visible on every page
+  until the final persisted one clears it.
+
+### Still open, by name
+
+- Stable event ids and full tool-call retrieval: tool calls remain compressed
+  one-line summaries with no `antiphon_read(id)` route.
+- The durable source catalog and the degraded-discovery marker: discovery
+  still reads the newest 3 transcripts per side, and `has_more: false` cannot
+  distinguish complete discovery from that window.
+- Backward paging into history an older version already marked seen.
+- The last-record content anchor (an in-place rewrite that keeps inode,
+  length and first line still resumes silently).
+- Descriptor-safe reading of registry-supplied transcript paths.
+- Direct-channel spill for the 128 KiB `antiphon_send` cap.
+- Retirement of the preserved v2 sibling key once pre-v3 processes and
+  rollback support are no longer needed.
+
+## P1 — Source-aware multi-peer pull context
+
+Live push is explicitly addressed and never broadcast. Passive pull context is
+project-wide awareness, which is useful, but today it merges transcripts under
+generic `Claude`/`Codex` labels. With several terminals that can look like one
+agent said another agent's words.
+
+- Record and validate the source peer for every transcript used by pull.
+- Label each event with the source alias (or honestly `unnamed`) and stable
+  session identity.
+- Keep project-wide awareness separate from task dispatch: an event addressed
+  to `api` may be visible to `ui`, but must remain visibly addressed to `api`.
+- Add an explicit filtering policy only if users ask for it; do not silently
+  infer Claude↔Codex pairs from matching aliases.
+
+## P1 — Relayed human words are not the reader's own user
+
+`build_summary` labels the other side's human as `YOU`. The block header says
+which side it came from, but the line itself reads `[11:04] YOU: rewrite the
+migration`, and nothing tells the reading agent that this is a person talking
+to *somebody else*. An agent that treats it as its own user's instruction has
+been handed authority nobody gave it — in a bridge whose whole invariant is
+preserving who said something.
+
+Provenance and authority are different questions, and this label answers only
+the first. The fix is to say both: relay the words under a label that names them
+as relayed, and state once, where the reader cannot miss it, that they are
+context rather than a direct instruction. The existing header and footer already
+carry that tone; the per-line label is the part that lies.
+
+Worth settling with it: whether the relayed label should also carry the speaking
+peer's alias when one is set, and whether an agent should ever act on a relayed
+instruction without its own user confirming.
+
+## P1 — Large direct-message attachments
+
+The direct channel has a separate, honest 128 KiB byte cap. Keep it until an
+oversized message has a recoverable path:
+
+- atomically write mode-0600 content under `.antiphon/messages/`;
+- send a size, SHA-256 hash and local reference instead of truncating;
+- validate every reference beneath the project state directory;
+- define acknowledgement, retry, TTL and total-quota behavior;
+- show pending storage in `antiphon status` and clean it without deleting an
+  unread message silently.
+
+This is separate from passive pull, whose old 2,600-character trim is retired
+— pull now pages complete records. Ordinary long SQL and code already fit
+under 128 KiB when sent through a channel tool.
+
+## P1 — A marker in anything but the turn's last message is dropped
+
+`push` reads the other side's newest assistant text through `last_claude_reply`
+or `last_codex_reply`, and both keep only the most recent assistant record —
+`chunks = texts` overwrites on each one, with the Claude side even documenting
+it: "each new assistant message supersedes the last". One turn is not one
+record. An agent that writes a progress message containing `@claude do this`
+and then a closing message without markers has its instruction silently
+dropped, because only the closing message is ever examined.
+
+Observed, not theorised: it happened in this project during development. One
+side reported sending a marker line, the other side received nothing, and later
+messages arrived normally — the marker had been in an intermediate message of a
+multi-part turn.
+
+The obvious repair is wrong. Joining every assistant record in the tail window
+would sweep up markers from previous turns and resend them: the dedupe
+fingerprint compares the joined text, so a window that grows by one record each
+turn produces a different fingerprint every time and pushes again. The fix needs
+a boundary for "this turn" rather than a wider join.
+
+### What has to be decided
+
+- What delimits a turn on each side. Claude records carry a `promptId`; Codex
+  rollouts bracket turns with `task_started` / `task_complete` `event_msg`
+  records. Neither is verified as reliable for this purpose yet.
+- Whether a marker in an intermediate message should be sent when it appears or
+  held until the turn ends. Sending immediately is what the author meant; it
+  also means a turn can push several times, which the fingerprint must handle
+  per marker rather than per joined blob.
+- Whether the same boundary belongs in the pull path, which has its own reasons
+  to group records and now has an atomic-record model to group them with.
+
+Until then the workaround is the one people find by accident: put the marker in
+the last thing the turn says.
+
+## P2 — A refused active send does not say the message will still arrive
+
+When the direct channel refuses a send, the tools report the host's error and
+stop there. Observed twice in one session: the Codex host answered
+`direct app-server input is not allowed for unloaded spawned sub-agents`, so
+`reply_to_codex` failed. `antiphon status` then showed the same text waiting in
+the other side's pull queue — the passive path had it, and it was delivered on
+the peer's next prompt.
+
+The sender could not know that from the error. The reasonable reading of a
+failed send is that the message was lost, which invites repeating it, or
+proceeding as though the peer was never told. Both are worse than waiting.
+
+The bridge already knows the answer: passive pull carries everything either
+side wrote, and a refused *active* send changes only the timing. Say so in the
+failure — name the fallback and what it costs, which is a delay until the peer's
+next turn rather than a loss. Worth checking first whether any refusal exists
+that the pull path genuinely cannot cover; if one does, it needs a different
+message from the ones that merely arrive late.
+
+## P1 — `antiphon doctor`
+
+Add one read-only command that explains the common “bridge is quiet” cases:
+
+- command/package version and which executable `PATH` resolves;
+- Node/Python compatibility;
+- hook, MCP and environment-forwarding configuration;
+- current alias validity, live peers, readiness and stale records;
+- channel socket reachability and Codex queue availability;
+- actionable repair text. A future `--fix` may call the existing idempotent
+  setup path, but the default command must not edit anything.
+
+## P2 — Reply correlation
+
+Explicit `to` remains the safe default when several peers are live. Automatic
+reply routing needs a durable design before implementation:
+
+- correlate only after a successful delivery acknowledgement;
+- scope pending messages to the receiving peer;
+- validate the original sender is still the same live session;
+- let explicit `to` override correlation;
+- fail closed when several unanswered senders remain;
+- define expiry and cleanup without losing a late reply.
+
+## P2 — Automatic peer identity
+
+Aliases are intentionally explicit in the first multi-peer release. A later
+release may make unnamed peers visible, but only after both writers derive the
+same identity on every supported host. There must be no user-settable owner-key
+override, no short-id collision, and no “newest session” fallback once more than
+one candidate is known.
+
+There is a concrete Claude-side lead, not yet a contract. On Claude Code
+2.1.251, `claude agents --json --cwd <project>` locally returned the active
+interactive session with `pid`, exact `cwd`, `sessionId` and a generated `name`,
+and the channel server's ancestor chain reached that pid. Before using it:
+
+- feature-detect the command and schema; help text calls this background-agent
+  management even though JSON currently includes interactive sessions;
+- measure the MCP startup race and use a bounded wait, never “newest” as a
+  fallback while the session has not appeared yet;
+- fail anonymous when the server is orphaned or its ancestry cannot be joined
+  to exactly one entry;
+- treat `sessionId` as the identity candidate and the generated `name` only as
+  untrusted display metadata until uniqueness and lifetime are documented;
+- prove the equivalent Codex MCP/hook join before changing the product rule —
+  a Claude-only automatic name would restore the asymmetry this release removed;
+- keep an explicit `ANTIPHON_NAME` as the deliberate override and test upgrade,
+  collision and mixed-version behaviour.
+
+## P2 — Cross-vendor managed workers
+
+A user should be able to tell a live Claude session “have Codex do this”, or a
+live Codex session “have Claude review this”, without manually opening another
+terminal and without making the foreign agent look like a native subagent. The
+right abstraction is an **Antiphon-managed foreign worker**: the parent agent
+can delegate to it and follow its lifecycle, but every event and result still
+names the actual Claude or Codex session that produced it. This preserves the
+bridge's identity invariant; an absent or ambiguous worker is refused rather
+than guessed.
+
+The first safe shape is:
+
+- expose a small `delegate`, `status`, `result` and `cancel` lifecycle, with a
+  stable task id and explicit worker session id;
+- return immediately after acceptance by default, so the parent can continue
+  working and collect the result later;
+- label every update and artifact as coming from the foreign worker, never as
+  the parent agent's own reasoning or work;
+- give every write-capable task its own Git worktree; a worker must not edit in
+  the parent session's checkout or race another worker over the same files;
+- never give the worker a broader permission class than the delegating session
+  or an explicit human grant, and never let a worker approve the parent's
+  permission requests, merge its own work, or silently widen its sandbox;
+- default the cross-agent hop budget to one. Nested delegation is refused unless
+  the user explicitly opts into a higher bounded value, so
+  Claude → Codex → Claude cannot become an invisible recursive loop;
+- make `blocked`, `completed`, `failed`, `cancelled` and timeout outcomes
+  explicit, and return reviewable evidence such as the diff and test results
+  with a completed write task.
+
+This must be implemented as an Antiphon lifecycle over host adapters, not by
+pretending that either host natively spawned the other vendor's model. Each host
+already has its own same-vendor nesting story, and neither is a cross-vendor
+contract: Claude Code documents that a subagent inherits the main conversation's
+MCP tools and may itself spawn subagents up to a configurable depth
+(`CLAUDE_CODE_MAX_SUBAGENT_SPAWN_DEPTH`, set to `1` to turn nesting off), and on
+this machine Codex CLI 0.151.0 advertises `multi_agent` as a stable feature while
+the generated App Server schema mentioning `spawnAgent` is still experimental.
+Neither establishes a stable way for one vendor to spawn the other's model, and
+this feature must not depend on one without version detection and a tested
+fallback. The bounded-depth precedent is worth copying rather than reinventing:
+a documented, configurable limit is exactly the shape the hop budget above takes.
+
+### Decisions still required
+
+- Whether `delegate` may target an already-running named peer, always creates a
+  fresh managed worker, or exposes both modes explicitly.
+- Whether managed workers are one-task ephemeral sessions or can be resumed,
+  and what expiry, cleanup and storage quotas apply.
+- Which host adapters are supported first, and whether an unavailable native
+  worker API may fall back to a documented CLI/SDK subprocess.
+- Which task classes may run without another user confirmation, and who may
+  accept a worker's patch or merge it after deterministic checks pass.
+- Whether a synchronous wait mode is worth exposing in addition to the safer
+  asynchronous default.
+
+No claim is made yet that a Claude worker can appear in Codex's native agent UI,
+or that a Codex worker can appear in Claude Code's native subagent UI. That UX
+would be optional integration work; the portable contract is Antiphon's own
+named worker, task lifecycle and evidence trail.
+
+## Observed, not adopted — Claude Code's per-session messaging socket
+
+Measured on one macOS machine, 2026-08-30: a Claude Code session exports
+`CLAUDE_CODE_MESSAGING_SOCKET`, `CLAUDE_CODE_MESSAGING_TOKEN` and
+`CLAUDE_CODE_SESSION_ID` into the processes it starts, including hooks and
+stdio MCP servers. The socket path pointed at a real Unix domain socket under a
+temporary directory, the token was a 32-character string, and the session id was
+a UUID. Nothing was connected to and no token value was read.
+
+This is recorded because it is easy to find and tempting to use, and because the
+temptation should be answered once rather than every time somebody notices it.
+It is not documented, its path is named after a process id, and it exists on one
+side of a bridge whose entire purpose is the asymmetry between two hosts —
+Codex CLI has no equivalent. A published package that made an undocumented
+internal interface its transport would break silently on the first release that
+moved it, and the failure would look like the bridge going quiet.
+
+If a first-party, documented agent-to-agent transport ever ships on both sides,
+this is the entry to revisit. Until then Antiphon owns its own sockets.
+
+## P2 — Multi-line Stop markers
+
+Stop markers currently carry one line. Channel tools preserve multi-line text
+and are the recommended route for long content. If users need natural-language
+Stop blocks, add an explicit delimited syntax with tests for fenced code,
+embedded marker text, empty blocks and deduplication; never guess continuation
+from arbitrary following prose.
+
+## P1 — Re-run the host wrapper census before release
+
+`CLAUDE_HOST_WRAPPERS` and `CODEX_HOST_WRAPPERS` in `lib/antiphon.py` hold
+exactly what a census measured (2026-08-30), and nothing else. They will go
+stale as each host adds, renames or drops its own wrapper tags, and the
+obligation to re-measure must not live only in a planning document that ships
+nowhere. Re-run it before every release:
+
+- count every `role: user` text record whose text opens with `<`, split by
+  side, each one carrying its `promptSource` value (or its absence);
+- for every opening tag that turns up, decide host bookkeeping or a person's
+  own words before touching either set — a tag seen on only one side stays out
+  of the other's, the way `local-command-caveat` did until it was measured;
+- update the sets, the measurement comment above `CLAUDE_HOST_WRAPPERS`, and
+  this entry's date together, so none of the three can drift from the other
+  two.
+
+The asymmetry that governs a doubtful case: a tag missing from a set lets one
+stray host line leak into a summary — visible, and cheap to fix by adding it.
+A tag wrongly present deletes a person's message — silently, with nothing left
+behind to notice it happened. When the evidence is thin, leave the tag out.

package/README.md

@@ -1,14 +1,16 @@
 # Antiphon
 
-**Two terminals, two separate agents, an open-identity bridge.** While Claude Code and Codex CLI work in the same project, each sees the other's context and can wake the other when it needs to, without ever faking who the message is from.
+**Two agents in one project, an open-identity bridge.** Claude Code and Codex CLI work side by side — one terminal each, or several on each side — and each sees the other's context and can wake the other when it needs to, without ever faking who the message is from.
 
-Antiphon doesn't dispatch work. It only carries messages between the two sides while preserving whether they came from the human user, from Claude, or from Codex.
+Antiphon doesn't dispatch work. It only carries messages between the sides while preserving whether they came from the human user, from Claude, or from Codex.
+
+With one terminal per side there is nothing to configure beyond `antiphon setup`: peers go unnamed, messages have only one place to go, and the rest of this page is background. Naming becomes necessary the moment a second session opens on either side — see [Many peers](#many-peers).
 
 ## How it works
 
-No shared log is kept. Both CLIs already write their own transcripts; Antiphon reads and derives from them, marking in `.antiphon/cursor.json` which messages each side has already seen.
+No shared log is kept. Both CLIs already write their own transcripts; Antiphon reads and derives from them, recording which messages each peer has already seen. An unnamed peer keeps its cursor at `.antiphon/cursor.json`; a named one owns `.antiphon/peers/<side>-<name>/cursor.json`, so two sessions on the same side never advance each other's place.
 
-### Pull — context, no wake
+### Pull — shared context, no wake
 
 | Direction | Mechanism |
 |---|---|
@@ -18,32 +20,118 @@ No shared log is kept. Both CLIs already write their own transcripts; Antiphon r
 The other side's recent messages enter your turn's context when you type
 something. Nobody is woken up.
 
-### Push — live wake
+This path is project-wide awareness, not delivery. It is not addressed to
+anyone, and today it can merge activity from several project transcripts under
+one generic `Claude` or `Codex` label — so with several terminals open, one
+agent's words can arrive looking like another's. Source-aware labelling is a
+tracked P1 item in [BACKLOG.md](BACKLOG.md). Until it lands, do not read pull
+context as a private line between two particular peers.
 
-| Direction | Mechanism |
-|---|---|
-| Claude → Codex | Claude `Stop` hook + `codex queue` |
-| Codex → Claude | Codex `Stop` hook + MCP Channel |
+### Push — addressed, live wake
+
+| Direction | At the end of a turn | Mid-turn |
+|---|---|---|
+| Claude → Codex | `Stop` hook + `codex queue` | `reply_to_codex` tool |
+| Codex → Claude | `Stop` hook + MCP Channel | `antiphon_send` tool |
 
 A line starting with `@codex` or `@claude` in a reply reaches the other
 agent immediately, even if nobody is typing.
 
+Every push is addressed to exactly one peer and is never broadcast. When the
+recipient cannot be shown to be the only candidate, the send is refused rather
+than guessed.
+
+Neither side has to wait for its turn to end. Either agent can hand work
+over mid-turn and keep going, so the other starts on it in parallel; the
+answer is collected later from the same turn with `antiphon_read` (Codex)
+or the channel event (Claude). Nothing blocks, and a message delivered by
+a tool is recorded, so ending the turn with the same `@claude` / `@codex`
+line does not send it twice.
+
 ### How identity is preserved
 
 A Claude → Codex message reaches Codex tagged either `[Antiphon bridge] Claude:` (pushed from Claude's Stop hook) or `[Antiphon channel] Claude:` (a direct reply sent through the channel, via the `reply_to_codex` tool) — either way, Codex sees these as Claude's words, not the human user's.
 
+The tag is followed by `[from=<alias> id=<uuid>]`, naming which Claude peer spoke so a reply can be addressed back to it. A session started without `ANTIPHON_NAME` shows `from=<unnamed>`: it has no name to be addressed by, and the angle brackets keep that apart from a peer actually called `unnamed`. The id names one delivery attempt — it is not a correlation id, and nothing routes replies by it.
+
 A Codex → Claude message never pastes text into the terminal and never impersonates user input. The local MCP server sends Claude Code a `notifications/claude/channel` event. Its metadata looks like:
 
 ```xml
-<channel source="antiphon" sender="codex" sender_kind="agent" message_id="...">
+<channel source="antiphon" sender="codex" sender_kind="agent" sender_alias="build" message_id="...">
+```
+
+Claude Code's interface shows this as an incoming channel event, and Claude treats the message as the words of the Codex agent, not of the human user. It sends its reply back with the `reply_to_codex` MCP tool, passing `sender_alias` as `to` whenever it is non-null. A bare reply is refused as soon as any named Codex peer is registered: an unnamed Codex session leaves no registry record, so one visible peer cannot be shown to be the only one running. A `null` `sender_alias` is a peer with no name — it cannot be addressed by name, and a bare reply reaches it only in a project where nothing is registered.
+
+Nothing pairs peers up. There is no automatic Claude↔Codex partnership, and no reply correlation: a message is routed only by the name written on it.
+
+## Many peers
+
+A name is an environment variable read at startup, so it goes in front of the
+command:
+
+    ANTIPHON_NAME=ui claude --dangerously-load-development-channels server:antiphon
+    ANTIPHON_NAME=api claude --dangerously-load-development-channels server:antiphon
+    ANTIPHON_NAME=build codex
+    ANTIPHON_NAME=review codex
+
+Once named, a peer is addressed explicitly — by marker at the start of a line,
+or by the `to` argument of the tool that sends without ending the turn:
+
+| From | Marker | Tool |
+|---|---|---|
+| Codex → Claude | `@claude:ui` | `antiphon_send(to="ui", text=…)` |
+| Claude → Codex | `@codex:build` | `reply_to_codex(to="build", text=…)` |
+
+There is no way to reach several peers at once. A send is delivered to the one
+peer named on it, and to nobody else.
+
+### When a bare message is refused
+
+The two sides fail closed on different rules, because they leave different
+traces:
+
+- **To Claude.** A bare `@claude` works while exactly one Claude peer is live.
+  From the second one on, it is refused and you must name one.
+- **To Codex.** A bare `@codex` is refused as soon as *any* named Codex peer is
+  registered — even if it is the only one you can see. A Codex session started
+  without a name leaves no registry record at all, so a second, unnamed one
+  cannot be ruled out, and the bridge will not guess between a peer it can see
+  and one it cannot.
+
+That asymmetry is why **every terminal in a multi-peer project must be named,
+Codex terminals above all**. Mixing named and unnamed sessions is the one
+configuration that can leave a message impossible to answer: the unnamed peer
+is live, it can send, and there is no name to send a reply back to.
+
+### Seeing who is live
+
+    antiphon status
+
+Beyond transcripts and cursors, `status` lists every registered peer with the
+side it runs on, the name it took, and its state — `ready` once it has an
+address to receive on, or `waiting for first turn` before that. Under the list
+it prints the addressing rule that currently applies:
+
+```
+Peers:
+  Claude ui — ready
+  Claude api — ready
+  Codex build — ready
+  Codex review — waiting for first turn
+  → a bare @claude line is refused; address one: @claude:ui, @claude:api
+  → a bare @codex line is refused, because unnamed Codex sessions leave no record; address one: @codex:build, @codex:review
 ```
 
-Claude Code's interface shows this as an incoming channel event, and Claude treats the message as the words of the Codex agent, not of the human user. It sends its reply back with the `reply_to_codex` MCP tool.
+A peer that is `waiting for first turn` is still a candidate: readiness never
+decides who a message goes to, so it cannot silently hand routing to whichever
+session happened to start first. With nothing registered — the unnamed single
+pair — the block is empty, because there is nobody to choose between.
 
 ## Install
 
-Requires Node 18+ and Python 3. The Claude Code channel is a research
-preview and needs Claude Code 2.1.80 or newer.
+Requires Node 20+ and Python 3.9+. The Claude Code channel is a research
+preview and needs Claude Code 2.1.80 or newer; recent Claude Code releases
+set their own, higher, Node floor, so check theirs as well.
 
 Install the command, either straight from the repository:
 
@@ -51,7 +139,7 @@ Install the command, either straight from the repository:
 
 or from npm:
 
-    npm i -g @serkancangokalp/antiphon
+    npm i -g antiphon
 
 Either way the command is `antiphon` — the package name only decides
 where it comes from. Then, in the project the two agents share:
@@ -73,7 +161,7 @@ Codex hooks once when Codex first shows them.
 ## Update
 
     npm i -g github:serkancangokalp/antiphon      # from the repository
-    npm i -g @serkancangokalp/antiphon@latest     # from npm
+    npm i -g antiphon@latest                      # from npm
 
     cd /your/project && antiphon setup
 
@@ -83,21 +171,23 @@ versions in place; it never creates duplicates.
 ## Commands
 
 ```bash
-antiphon status            # transcript, cursor and channel status
+antiphon status            # transcripts, cursors, live peers and channel status
 antiphon summary [side]    # show the context that would be injected
 antiphon setup             # (re)install the project setup
 npm test                   # Python unit tests + real MCP protocol test
 ```
 
-`setup` registers the `antiphon_read` MCP tool for Codex in this project's
-`.codex/config.toml`, so there is nothing to add by hand. Note the entry
+`setup` registers Codex's MCP tools — `antiphon_read` and `antiphon_send`
+— in this project's `.codex/config.toml`, so there is nothing to add by
+hand. Note the entry
 names `args = ["mcp"]`: the `channel` server is Claude's side and hands out
 `reply_to_codex`. Aiming Codex at it would let Codex publish messages
 labelled as Claude's — exactly what this bridge exists to prevent — so
 `setup` rewrites that table whenever it is wrong, leaving the rest of the
-file alone.
+file alone. The same table forwards `ANTIPHON_NAME` into the tool process,
+because Codex does not pass the parent environment through on its own.
 
-The bridge works without this entry; it only lets Codex query the bridge by hand when it suspects the pull hook has gone quiet.
+Without this entry the pull hook still delivers Claude's context at the start of each Codex turn, but Codex loses both tools: it can no longer check the bridge by hand, nor reach Claude before its turn ends.
 
 ## Limits
 
@@ -106,8 +196,68 @@ The bridge works without this entry; it only lets Codex query the bridge by hand
 - Channels is currently a research preview; it requires a claude.ai login or a Console API key. It isn't supported on the Bedrock, Vertex, or Foundry providers. A Team/Enterprise admin may need to enable the feature.
 - The Codex hook asks for re-approval the first time it's used and whenever the hook file changes.
 - Matching is done on the same project's absolute directory.
-- Once a message has been seen, the cursor advances and the same content is never injected twice.
-- Context transfer has a budget of roughly 2600 characters; the newest messages are kept.
 - Unix sockets only — there is no Windows support.
 
+### Passive pull pages, and what it still cannot promise
+
+The pull path delivers the other side's transcript as pages of completed
+records, oldest first. An ordinary full page targets 8,000 UTF-8 bytes and at
+most 40 completed source records — the byte number is measured against the
+installed hosts' injection limits, not a permanent host guarantee. Non-tool
+records are no longer cut or flattened: line structure, indentation, code and
+SQL formatting travel intact, and a record is never split across pages.
+
+A page that leaves work behind says so with a visible `has_more: true` line;
+calling `antiphon_read` again (or simply letting later turns run) drains the
+rest. Either `has_more` value describes only the transcripts discovery can
+currently see — discovery still reads only the newest 3 transcript files per
+side, so `has_more: false` is not an inventory of all project history.
+
+One record larger than an ordinary page is handled asymmetrically, from
+measurement rather than preference. Both hosts' automatic prompt hooks save an
+oversized injection to a host-managed file and show the model a preview and the
+path, so the hook hands such a record over whole — which means host-written
+spill files may contain verbatim transcript text, under the host's own
+lifecycle. Codex's MCP tool-result surface showed no such verified path, so
+`antiphon_read` refuses that one record instead: nothing is read or marked
+seen, and the next automatic prompt hook delivers it.
+
+Page positions live under an isolated v3 cursor key, `<side>_pages`
+(`claude_pages`, `codex_pages`). The old `<side>_seen` value is
+preserved untouched beside it for still-running pre-upgrade processes and
+rollback — it is never trusted or overwritten by paging code, and it is
+scheduled for
+retirement once pre-v3 processes no longer need it, not a template for
+accumulating keys. Any present legacy value, and equally a malformed or
+unreadable existing cursor file, starts a conservative replay of the currently
+discovered sources from byte zero; only a genuinely missing cursor means a new
+side and keeps the normal six-hour lookback. The old promise that a timestamp
+cursor migrates at its exact boundary is gone: that boundary cannot be trusted
+while an old process may still move it. The replay is bounded but it is not
+small — on the reviewed snapshots it took 69 Claude-source pages and 53
+Codex-source pages, up to that many automatic prompt turns — and every replay
+page carries one of exactly two fixed explanation lines, one for the legacy
+upgrade and one for cursor recovery, until the final successfully persisted
+page clears it, so duplicated history is visible as recovery rather than
+mistaken for a malfunction. A failed delivery leaves the cursor bytes exactly
+as they were.
+
+What still loses, by name: tool calls remain compressed one-line summaries
+with no stable-id retrieval yet, discovery has no catalog (the newest-3 window
+above), and there is no backward paging into history an older version already
+marked seen. Those are tracked in [BACKLOG.md](BACKLOG.md).
+
+### The Codex-to-Claude channel refuses rather than truncates
+
+A message sent from Codex to Claude with `antiphon_send` or `@claude` uses the
+Unix-socket channel. Its serialized payload has a separate 128 KiB byte cap,
+checked by the sender before transport and by the server on arrival. Over that,
+the send fails with an error you can see; it is never silently shortened, so
+ordinary long code and SQL within the cap travel intact.
+
+The reverse Claude-to-Codex path uses `codex queue` and does not share that
+explicit Antiphon byte cap. It also has no oversized-message attachment
+protocol yet, so extremely large direct transfers in either direction remain a
+P1 item in [BACKLOG.md](BACKLOG.md).
+
 MIT.

package/bin/antiphon.mjs

@@ -12,6 +12,17 @@ const target = subcommand === "channel"
   : { cmd: "python3", args: [join(here, "..", "lib", "antiphon.py"), ...(subcommand ? [subcommand] : []), ...rest] };
 
 const child = spawn(target.cmd, target.args, { stdio: "inherit" });
+
+// Forward signals rather than dying under them. Without this the wrapper exits
+// first and leaves the channel server orphaned under PPID 1, still holding its
+// socket — and the server never learns it was supposed to stop. Exit is left to
+// the child's own exit handler below, so it gets to clean up first.
+for (const signal of ["SIGINT", "SIGTERM", "SIGHUP"]) {
+  process.on(signal, () => {
+    if (!child.killed) child.kill(signal);
+  });
+}
+
 child.on("exit", (code, signal) => process.exit(signal ? 1 : code ?? 0));
 child.on("error", (error) => {
   process.stderr.write(`antiphon: ${error.message}\n`);