oxtail 0.6.0 → 0.7.0

package/AGENTS.md

@@ -17,7 +17,7 @@ Scope is **project-root as the unit**. Sessions in one project root see each oth
 - **Registry (leaning):** `tmux list-sessions` filtered by project-derived names, rather than a custom JSON registry. Free dead-session detection, free naming, no daemon to maintain. Decision pending real-use signals.
 - **Project scoping:** project root inferred from session CWD at agent startup.
 
-## Status: v0.6.0 shipped, dogfooding
+## Status: v0.7.0 shipped, dogfooding
 
 Nine MCP tools live: `list_project_sessions`, `read_session`, `claim_session`, `set_my_state`, `register_my_session`, `get_my_session`, the v0.5 messaging pair `send_message` and `read_my_messages`, and the v0.6 delegate-and-wait primitive `ask_peer`. Registered both project-locally (via `.mcp.json` using `tsx ./src/server.ts` for the dev loop) and globally (in `~/.claude.json` and `~/.codex/config.toml`, pointing at `dist/server.js`).
 
@@ -29,7 +29,9 @@ Current phase remains **dogfooding**: use the tools in real parallel-agent work,
 
 The v0.5 change: two new MCP tools (`send_message`, `read_my_messages`) plus an opt-in `PreToolUse` hook installable via `npx oxtail install-hook`. Friction observed while pairing on Terminator — two agents in the same project root can see each other's state cards and transcripts but couldn't say anything to each other. Now they can. Claude Code peers see messages mid-turn (via the hook); Codex peers (or unhooked Claude Code) see them next-turn (via polling `read_my_messages`).
 
-The v0.6 change: one new MCP tool (`ask_peer`) that turns v0.5's async pings into synchronous delegate-and-wait. Friction observed while dogfooding v0.5 — `send_message` lets agents say things to each other, but the sender doesn't stay in-turn waiting for a reply, and an idle receiver doesn't get nudged. `ask_peer` blocks server-side until a reply with a matching `from_session_id` lands (or a fixed timeout elapses) and fires a `tmux send-keys` wake to rouse idle peers. The result: an agent talking to its user can delegate to a peer, exchange multiple rounds inside one of its own turns, and report back synthesized findings.
+The v0.6 change: one new MCP tool (`ask_peer`) that turns v0.5's async pings into a blocking delegate-and-wait. Friction observed while dogfooding v0.5 — `send_message` lets agents say things to each other, but the sender doesn't stay in-turn waiting for a reply. `ask_peer` blocks server-side until a reply with a matching `from_session_id` lands (or a fixed timeout elapses) and fires a `tmux send-keys` wake against the peer's pane.
+
+The v0.7 change: per-client wake routing after the v0.6 wake was found to be broken against idle TUI peers. Spike investigation (issue #3) revealed two distinct constraints, fixed differently. For **Codex**: the root cause was not `\r`-as-newline as initially suspected, but Codex's paste-burst heuristic (`codex-rs/tui/src/bottom_pane/paste_burst.rs`) suppressing Enter for ~120ms after a fast typed burst — `tmux send-keys -l text` + immediate `send-keys Enter` looked like a paste, so the trailing Enter was forcibly converted to newline. Fix: a 500ms gap between the text and the Enter. Verified live 2026-05-13 against the live `oxtail-codex` peer in this repo. For **Claude Code**: idle peers are architecturally unwakeable from outside the process — the documented Claude Code hook surface has no idle event, no polling, no external "start a turn" mechanism (`Notification` is outbound-only; `FileChanged` only fires inside an in-flight turn). v0.7 ask_peer fail-fasts for Claude Code targets with `wake_status: "skipped_unsupported"` rather than burning the 45s timeout. The outbound is still enqueued and delivered next time the peer enters a turn. Wake strategy is overridable via `OXTAIL_ASK_PEER_WAKE_STRATEGY=auto|legacy|off` as a rollback.
 
 ## How to collaborate on this project
 
@@ -45,9 +47,14 @@ The v0.6 change: one new MCP tool (`ask_peer`) that turns v0.5's async pings int
 3. **Both Claude Code and Codex CLI must work** with whatever we build. MCP is the cross-tool protocol; Skills are Claude-specific syntactic sugar that wraps MCP tools, never primary functionality.
 4. **Minimum viable first.** One MCP tool that's actually used > five speculative ones.
 
+## Invariants worth defending
+
+- **`client.session_id` is the unique agent identity.** Not `server_pid`, not `tmux_session`. One Claude/Codex client can be backed by multiple MCP server children — the documented dual-scope setup (project `.mcp.json` + user `~/.claude.json`) intentionally spawns two oxtail processes per session, and Claude Code/Codex restarts during a long session can leak ghost children. The registry stores one file per `server_pid`, so duplicates per `session_id` are the norm; `readAll()` collapses them by `session_id` (freshest `started_at` wins). Any new code that reasons about peer identity must key on `client.session_id` — adding lookups keyed on `server_pid` or `tmux_session` will reintroduce the bug class where peer reads bail with misleading scope errors (see commit history for the v0.6-era dedupe fix).
+
 ## Recently shipped
 
-- **Delegate-and-wait (v0.6).** `ask_peer({ target, body })` blocks server-side until the peer replies (filtered by `from_session_id`) or a fixed timeout elapses, with a `tmux send-keys` wake fallback for idle peers. Late replies fall back to the v0.5 hook / poll delivery path. Target must have a registered `client.session_id`.
+- **Per-client wake routing (v0.7).** `ask_peer` now routes its wake mechanism per `client_type`. Codex: paste-burst-aware send-keys (500ms gap between text and Enter) — verified to actually submit. Claude Code: fail-fast with `wake_status: "skipped_unsupported"` since the hook surface has no idle event. Response gains a `wake_status` field for caller diagnostics. Pre-wake pane re-resolution closes the stale-pane-ID race from v0.6. `OXTAIL_ASK_PEER_WAKE_STRATEGY=auto|legacy|off` env override for rollback. Issue #3 has the spike findings.
+- **Delegate-and-wait (v0.6).** `ask_peer({ target, body })` blocks server-side until the peer replies (filtered by `from_session_id`) or a fixed timeout elapses. Late replies fall back to the v0.5 hook / poll delivery path. Target must have a registered `client.session_id`.
 - **Cross-session messaging (v0.5).** `send_message({ target, body })` + `read_my_messages()`. Mailbox lives at `~/.oxtail/mailboxes/<server_pid>.jsonl`, drained under an `mkdir`-based advisory lock. Opt-in PreToolUse hook (`npx oxtail install-hook`) for mid-turn delivery to Claude Code.
 
 ## Deliberately deferred

package/README.md

@@ -1,5 +1,7 @@
 # oxtail
 
+[![test](https://github.com/d4j3y2k/oxtail/actions/workflows/test.yml/badge.svg)](https://github.com/d4j3y2k/oxtail/actions/workflows/test.yml)
+
 Run two or more coding agents in the same repo and let them see each other. oxtail is a local MCP server that gives parallel Claude Code and Codex CLI sessions peer awareness: each session can list the others running in the same project root, read their state cards, and (when needed) read their transcripts directly. No fixed cap — every oxtail-aware session in the project shows up in `list_project_sessions`.
 
 Works for any mix of clients that speak MCP — Claude Code, Codex CLI, or one of each. Scope is **project-root as the unit**: sessions in `/path/to/foo` see each other; sessions in `/path/to/bar` see each other; cross-project there is no visibility, by design.
@@ -38,14 +40,14 @@ curl -L https://raw.githubusercontent.com/d4j3y2k/oxtail/v0.6.0/.claude/commands
   -o ~/.claude/commands/oxtail-join.md
 ```
 
-**Codex skill** (`/oxtail-register`):
+**Codex skill** (`/oxtail-join`):
 
 ```sh
-mkdir -p ~/.codex/skills/oxtail-register/agents
-curl -L https://raw.githubusercontent.com/d4j3y2k/oxtail/v0.6.0/integrations/codex/oxtail-register/SKILL.md \
-  -o ~/.codex/skills/oxtail-register/SKILL.md
-curl -L https://raw.githubusercontent.com/d4j3y2k/oxtail/v0.6.0/integrations/codex/oxtail-register/agents/openai.yaml \
-  -o ~/.codex/skills/oxtail-register/agents/openai.yaml
+mkdir -p ~/.codex/skills/oxtail-join/agents
+curl -L https://raw.githubusercontent.com/d4j3y2k/oxtail/v0.6.1/integrations/codex/oxtail-join/SKILL.md \
+  -o ~/.codex/skills/oxtail-join/SKILL.md
+curl -L https://raw.githubusercontent.com/d4j3y2k/oxtail/v0.6.1/integrations/codex/oxtail-join/agents/openai.yaml \
+  -o ~/.codex/skills/oxtail-join/agents/openai.yaml
 ```
 
 Floating form (`npx -y oxtail` with no `@`) exists for trying it out; don't pin daily configs to it — it floats end users into whatever the next published version turns out to be.
@@ -63,9 +65,9 @@ Contributing? `git clone https://github.com/d4j3y2k/oxtail && cd oxtail && npm i
 - `read_session` — the recent transcript of a peer session, as clean per-turn messages when the peer is oxtail-aware (Claude Code and Codex CLI), or as raw tmux pane text otherwise. Accepts a tmux session name OR a `client_session_id` UUID; an ambiguous tmux name returns `ambiguous-target` with the candidate UUIDs.
 - `claim_session` — single-shot session registration. The routine path: `Bash echo $CLAUDE_CODE_SESSION_ID` (or `$CODEX_THREAD_ID` for Codex) → `claim_session({ session_id })`. Returns `{ ok, session_id, transcript_path }`.
 - `set_my_state` — write a small "state card" onto this session's registry entry so peers can see what we're doing without reading our transcript. v1 surfaces a single field, `purpose` (≤200 chars).
-- `send_message` — **fire-and-forget** message to a peer. **Does NOT wake an idle peer** — use `ask_peer` for that. Target is a tmux session name or a raw `client_session_id` UUID. Body ≤ 8KB. Delivery is async via the peer's mailbox file. (v0.5+)
+- `send_message` — **fire-and-forget** message to a peer. **Does NOT wake an idle peer.** Target is a tmux session name or a raw `client_session_id` UUID. Body ≤ 8KB. Delivery is async via the peer's mailbox file. (v0.5+)
 - `read_my_messages` — drain this session's mailbox and return any queued messages. Codex peers (and unhooked Claude Code) poll this; Claude Code peers with the PreToolUse hook installed see messages mid-turn instead. (v0.5+)
-- `ask_peer` — **synchronous delegate-and-wait**. Wakes the peer via `tmux send-keys` and **blocks until they reply** (or the fixed timeout elapses, default 45s, tunable via `OXTAIL_ASK_PEER_TIMEOUT_MS`). Returns the peer's reply body. Use this for delegate-and-wait dynamics; use `send_message` for fire-and-forget. (v0.6+)
+- `ask_peer` — **delegate-and-wait**. Enqueues a message and blocks server-side until the peer replies (or the fixed timeout elapses, default 45s, tunable via `OXTAIL_ASK_PEER_TIMEOUT_MS`). v0.7 routes the wake per `client_type`: Codex gets a paste-burst-aware `tmux send-keys` wake that actually submits; Claude Code targets fail-fast (no wake surface for idle Claude — see "Delegate-and-wait" below). Response includes `wake_status` so the caller can distinguish "we polled and got nothing" from "this peer can't be woken." Use `send_message` for fire-and-forget. (v0.7+; v0.6 caveats below)
 - `register_my_session` — pin this MCP server's `session_id` directly. Kept for debugging; prefer `claim_session`.
 - `get_my_session` — return this MCP server's own registry entry plus a per-strategy detection diagnosis. Useful for debugging.
 
@@ -134,28 +136,59 @@ If you have a PreToolUse hook installed that isn't from Terminator and isn't oxt
 
 oxtail trusts any process running as the **same local user** to enqueue messages. The mailbox directory is mode `0o700` (private), so other users on the host cannot read or write. **On a shared-tenancy box (containers, multi-user dev hosts, etc.), do not run oxtail-aware agents:** any local process under your user can inject `<system-reminder>` content directly into a Claude session. The threat boundary is the same as `~/.ssh/` — what your user processes do, you trust.
 
-## Delegate-and-wait (v0.6)
+## Delegate-and-wait (v0.7)
 
-`ask_peer` extends v0.5's mailbox transport into a synchronous primitive:
+`ask_peer` extends v0.5's mailbox transport into a blocking primitive:
 
 ```
 ask_peer({ target, body })
-  → { ok: true, message_id, reply: { id, body, enqueued_at, from_session_id } | null, timed_out }
+  → {
+      ok: true,
+      message_id,
+      wake_status: "fired" | "skipped_unsupported" | "skipped_no_target" | "disabled",
+      reply: { id, body, enqueued_at, from_session_id } | null,
+      timed_out,
+    }
 ```
 
-Mechanics:
+`wake_status` distinguishes the four outcomes a caller may need to handle differently. `fired` means the wake was attempted (or the reply arrived during the grace window, so no wake was needed). `skipped_unsupported` means the target's `client_type` cannot be woken externally — currently Claude Code, see "Per-client wake routing" below. `skipped_no_target` means no tmux pane/session resolved for the target. `disabled` means `OXTAIL_ASK_PEER_WAKE_STRATEGY=off` is in effect.
+
+`timed_out` is `true` only when the poll loop ran to its deadline without a reply. Fail-fast for `skipped_unsupported` returns `timed_out: false` because no polling was attempted — the message is still enqueued and will be delivered when the peer next enters a turn.
+
+### Per-client wake routing
+
+v0.7 routes the wake mechanism per `client_type`. Verified 2026-05-13 via spike investigation and falsifying experiment:
+
+- **Codex** — `tmux send-keys -l <text>` followed by `send-keys Enter` is the wake. The keystrokes are split by 500ms because Codex's TUI has a paste-burst heuristic in `codex-rs/tui/src/bottom_pane/paste_burst.rs` (`PASTE_BURST_MIN_CHARS=3`, `PASTE_ENTER_SUPPRESS_WINDOW=120ms`) that converts Enter→newline for ~120ms after a fast typed burst. Without the gap, the wake text accumulates in the composer and Enter is suppressed. With the gap, Codex submits and enters a turn. 500ms is a deliberately generous multiple of the documented window for upstream-drift safety.
+
+- **Claude Code** — fail-fast. Claude Code's hook surface (per [docs](https://code.claude.com/docs/en/hooks)) has no event that fires while the agent is idle: no polling hook, no external "start a turn" mechanism, `Notification` is outbound-only, `FileChanged` only fires inside an in-flight turn. An external process cannot rouse an idle Claude Code peer. ask_peer returns immediately with `wake_status: "skipped_unsupported"` rather than burning the timeout. The message is enqueued and delivered to the peer's PreToolUse hook on their next tool call (or via explicit `read_my_messages`).
+
+- **Unknown** — legacy v0.6 wake (text + Enter, no gap). No implied promise; if a new TUI lands, treat it as unknown until verified.
+
+### Wake strategy override
+
+`OXTAIL_ASK_PEER_WAKE_STRATEGY=auto|legacy|off` (default `auto`):
+
+- `auto` — per-client routing above.
+- `legacy` — v0.6 behavior for every client (no paste-burst gap, no per-client routing). Escape hatch if auto mode misfires.
+- `off` — wake disabled entirely; ask_peer becomes a pure blocking poll. Response surfaces `wake_status: "disabled"`. Useful as a rollback if a Codex update changes the paste-burst constants and the auto-mode delay no longer covers the window.
+
+### Mechanics
 
 1. Enqueue `body` into the target's mailbox (same as `send_message`).
 2. Wait ~500ms for a hook-delivered reply (rare path — handles the case where the peer was already mid-tool-call and replied immediately).
-3. Fire a `tmux send-keys` wake against the peer's pane: a single literal line `[oxtail] new peer message — run mcp__oxtail__read_my_messages and respond via mcp__oxtail__send_message` followed by Enter. This nudges idle peers without requiring the human at the other end to type.
+3. Route the wake via `wake_status` resolution (see above). For Claude Code, return immediately. Otherwise fire the wake.
 4. Poll the caller's mailbox at 200ms for a reply with `from_session_id == target.session_id`. Other peers' messages stay in the mailbox untouched.
-5. Return the reply on match, or `{ reply: null, timed_out: true }` after the fixed timeout. Late replies fall back to the normal v0.5 hook / `read_my_messages` path — never lost, just delivered out of band.
+5. Return the reply on match, or `{ reply: null, timed_out: true, wake_status }` after the fixed timeout. Late replies fall back to the normal v0.5 hook / `read_my_messages` path — never lost, just delivered out of band.
+
+### Pane staleness
+
+Pane targeting can go stale: `tmux_pane` is cached at server startup, but tmux can reuse pane ids after a pane is killed. v0.7 re-resolves the pane from the peer's `server_pid` at wake-time (via process-tree ancestry), preferring the live pane id over the cached one. If the peer is no longer in any tmux pane (orphaned), oxtail falls back to the registered tmux session name. If both targeting attempts fail, `wake_status` returns `skipped_no_target`.
 
-Constraints:
+### Constraints
 
 - The target peer must have a registered `client.session_id`. Codex peers must call `claim_session` / `register_my_session` first; without that, `ask_peer` returns `error: "peer-has-no-session-id"` rather than guessing.
 - Timeout defaults to 45000ms (conservative under typical MCP-client tool-call abort windows). For longer dialogues, the calling agent chains multiple `ask_peer` calls in one turn rather than configuring a longer single block.
-- The wake is best-effort. If `tmux send-keys` fails against the cached pane id (Terminator-style window churn can leave the id stale), oxtail retries against the tmux session name (which targets the currently-active pane). If both fail, the peer may still respond on its own via polling — the only loss is the immediacy of the nudge.
 
 ### Tuning the timeout
 
@@ -209,4 +242,4 @@ If `MCP_TRACE_FILE` is set in the environment, every detection run appends an ND
 
 ## Status
 
-v0.6.0. Adds `ask_peer` on top of v0.5's mailbox transport: an agent can send a message and block until the peer replies, with an automatic `tmux send-keys` wake for idle peers. Combined with the existing PreToolUse hook, two Claude Code sessions can now sustain a back-and-forth handoff inside a single turn of the delegating agent. Codex peers are supported as targets once they've claimed a session.
+v0.7.0. Replaces v0.6's wake mechanism with per-client routing after a spike investigation found the root cause was Codex's paste-burst heuristic suppressing Enter, not `\r`-as-newline. Codex idle peers now wake reliably via a 500ms-gap send-keys sequence (verified live 2026-05-13). Claude Code idle peers fail-fast with `wake_status: "skipped_unsupported"` — Claude Code's hook surface has no idle event so they're architecturally unwakeable from outside; the message is still enqueued and delivered next turn. ask_peer's response gains a `wake_status` field for caller diagnostics. Wake strategy is overridable via `OXTAIL_ASK_PEER_WAKE_STRATEGY=auto|legacy|off` as a rollback. See [issue #3](https://github.com/d4j3y2k/oxtail/issues/3) for the spike findings.

package/dist/registry.js

@@ -116,6 +116,15 @@ export function resolveTmuxPane(env = process.env, pid = process.pid) {
         return env.TMUX_PANE;
     return findTmuxPaneByAncestry(pid, listTmuxPanePids(), listAllPpids());
 }
+// Resolve the tmux pane currently hosting a given server pid by walking the
+// process tree. Unlike resolveTmuxPane(), this does NOT trust env vars — it
+// queries live tmux + ps state. Used by the ask_peer wake path to detect a
+// stale cached tmux_pane: if a peer's pane was killed and its pane_id reused
+// by an unrelated pane, the cached id no longer points at our peer. Returns
+// null if the server pid is no longer in any tmux pane's process tree.
+export function currentPaneForServerPid(serverPid) {
+    return findTmuxPaneByAncestry(serverPid, listTmuxPanePids(), listAllPpids());
+}
 export function buildEntry(client, env = process.env) {
     const tmux_pane = resolveTmuxPane(env);
     return {
@@ -134,6 +143,13 @@ export function refreshTmuxBinding(entry) {
 }
 export function register(entry) {
     ensureDir();
+    // Best-effort GC: drop stale entries from dead processes that share our
+    // session_id. Happens when oxtail is configured in multiple MCP scopes
+    // (user + project), so the same client session has spawned several MCP
+    // server children over its lifetime — survivors of crashed prior children
+    // accumulate otherwise. Leaves live siblings alone; readAll() collapses
+    // those by session_id.
+    gcDeadSiblings(entry);
     // Temp file + atomic rename. Concurrent peers running readAll() can otherwise
     // catch a torn write, fail JSON.parse, and silently drop the entry until the
     // next write completes.
@@ -153,6 +169,38 @@ export function register(entry) {
         throw err;
     }
 }
+function gcDeadSiblings(entry) {
+    const sid = entry.client.session_id;
+    if (!sid)
+        return;
+    const dir = registryDir();
+    if (!existsSync(dir))
+        return;
+    for (const file of readdirSync(dir)) {
+        if (!file.endsWith(".json"))
+            continue;
+        const full = join(dir, file);
+        let other;
+        try {
+            other = JSON.parse(readFileSync(full, "utf8"));
+        }
+        catch {
+            continue;
+        }
+        if (other.server_pid === entry.server_pid)
+            continue;
+        if (other.client.session_id !== sid)
+            continue;
+        if (isAlive(other.server_pid))
+            continue;
+        try {
+            unlinkSync(full);
+        }
+        catch {
+            // already gone, fine
+        }
+    }
+}
 export function unregister(pid = process.pid) {
     try {
         unlinkSync(entryPath(pid));
@@ -175,7 +223,7 @@ export function readAll() {
     const dir = registryDir();
     if (!existsSync(dir))
         return [];
-    const out = [];
+    const live = [];
     for (const file of readdirSync(dir)) {
         if (!file.endsWith(".json"))
             continue;
@@ -196,9 +244,35 @@ export function readAll() {
             }
             continue;
         }
-        out.push(entry);
+        live.push(entry);
+    }
+    return dedupeBySessionId(live);
+}
+// One Claude/Codex session can be backed by multiple MCP server children when
+// oxtail is declared in more than one MCP scope (e.g. user-level config +
+// project `.mcp.json`). Each child registers separately, so the registry ends
+// up with N entries that share the same client.session_id. session_id is the
+// unique agent identity downstream (resolver UUID lookup, peer messaging),
+// so collapse the duplicates here. Keep the freshest by started_at — that's
+// the most likely to have an up-to-date transcript path and tmux binding.
+// Entries with no session_id are left alone: they're either pre-claim
+// (haven't called claim_session yet) or unclaimed peers, and conflating
+// them would be wrong.
+export function dedupeBySessionId(entries) {
+    const winnerBySession = new Map();
+    const noSession = [];
+    for (const e of entries) {
+        const sid = e.client.session_id;
+        if (!sid) {
+            noSession.push(e);
+            continue;
+        }
+        const prior = winnerBySession.get(sid);
+        if (!prior || e.started_at > prior.started_at) {
+            winnerBySession.set(sid, e);
+        }
     }
-    return out;
+    return [...winnerBySession.values(), ...noSession];
 }
 export function findByTmuxSession(name) {
     return readAll().filter((e) => e.tmux_session === name);

package/dist/server.js

@@ -9,7 +9,7 @@ import { dirname, join, sep } from "node:path";
 import { clientFromHandshake, detectClient, enrichWithDiagnosis, transcriptPathFor, } from "./clients.js";
 import { isAbstain } from "./detect/index.js";
 import { trace } from "./trace.js";
-import { buildEntry, findByTmuxSession, readAll, refreshTmuxBinding, register, unregister, } from "./registry.js";
+import { buildEntry, currentPaneForServerPid, findByTmuxSession, readAll, refreshTmuxBinding, register, unregister, } from "./registry.js";
 import * as mailbox from "./mailbox.js";
 // CLI subcommand dispatch must run before any MCP setup so that
 // `npx oxtail install-hook` doesn't open an MCP transport or register a
@@ -715,7 +715,7 @@ server.registerTool("send_message", {
         "Delivery is asynchronous: the message lands in the target's mailbox and is delivered mid-turn via the oxtail PreToolUse hook (Claude Code) or next-turn via read_my_messages (Codex, or any client without the hook installed). If the peer is idle (no in-flight turn, no polling), the message waits until they next call a tool or poll explicitly — there is no nudge.",
         "Sender-side wrapping: if you want the message to appear as a system-reminder, include the <system-reminder>...</system-reminder> tags in `body`. The mailbox is a dumb transport.",
         "Cross-project targets are rejected, never silently dropped.",
-        "For a blocking send-and-wait variant that pauses your turn until the peer replies AND nudges an idle peer via tmux send-keys, use ask_peer instead.",
+        "For a blocking send-and-wait variant that pauses your turn until the peer replies, use ask_peer instead. (Note: ask_peer's idle-peer wake is best-effort in v0.6 and does not reliably rouse fully-idle TUI peers — see ask_peer's tool description.)",
     ].join(" "),
     inputSchema: {
         target: z
@@ -797,6 +797,32 @@ const ASK_PEER_TIMEOUT_MS = (() => {
 const ASK_PEER_GRACE_MS = 500;
 const ASK_PEER_POLL_MS = 200;
 const ASK_PEER_WAKE_TEXT = "[oxtail] new peer message — run mcp__oxtail__read_my_messages and respond via mcp__oxtail__send_message";
+// Codex's TUI has a paste-burst heuristic at codex-rs/tui/src/bottom_pane/
+// paste_burst.rs (PASTE_BURST_MIN_CHARS=3, PASTE_BURST_CHAR_INTERVAL=8ms,
+// PASTE_ENTER_SUPPRESS_WINDOW=120ms). When `tmux send-keys` blasts the
+// literal-text payload followed immediately by Enter, Codex detects the
+// pattern as a paste and forcibly converts Enter→newline for ~120ms,
+// suppressing the submit. Inserting a delay between the text and the Enter
+// keystrokes lets the suppression window expire so Enter is treated as a
+// real keypress. 500ms is a generous multiple of the documented window for
+// upstream-drift safety — Codex point releases may bump the constant.
+// Verified empirically 2026-05-13 against Codex (gpt-5.5 xhigh).
+const ASK_PEER_CODEX_SUBMIT_DELAY_MS = 500;
+// OXTAIL_ASK_PEER_WAKE_STRATEGY = "auto" | "legacy" | "off"
+//   auto    — per-client routing: Codex gets paste-burst-aware wake (500ms gap
+//             between text and Enter); Claude Code is skipped (no idle hook
+//             surface — verified via Claude Code hook docs); unknown clients
+//             get legacy v0.6 behavior.
+//   legacy  — v0.6 behavior for every client (text + Enter, no gap, no
+//             per-client routing). Escape hatch if auto mode misfires.
+//   off     — wake disabled entirely; ask_peer becomes a blocking poll.
+//             Caller can rely solely on the peer's natural turn cadence.
+const ASK_PEER_WAKE_STRATEGY = (() => {
+    const v = (process.env.OXTAIL_ASK_PEER_WAKE_STRATEGY ?? "auto").toLowerCase();
+    if (v === "auto" || v === "legacy" || v === "off")
+        return v;
+    return "auto";
+})();
 function askPeerDelay(ms, signal) {
     return new Promise((resolve, reject) => {
         if (signal.aborted) {
@@ -815,34 +841,58 @@ function askPeerDelay(ms, signal) {
         signal.addEventListener("abort", onAbort, { once: true });
     });
 }
-// Best-effort wake: two send-keys calls so the text is interpreted literally
-// (-l) and Enter is parsed as a key event. The -l flag neutralizes any tmux
-// keysequences a malicious peer could plant in its registry entry. Failure to
-// reach tmux is non-fatal — the peer may still poll or hook-deliver on its own.
+// Wake routing (v0.7). The wake's job is to nudge an idle peer into a turn so
+// it drains its mailbox. Mechanics differ per client:
+//
+//   Codex — `tmux send-keys -l <text>` followed by `send-keys Enter` would
+//   work, EXCEPT Codex's paste-burst heuristic suppresses Enter for 120ms
+//   after a fast typing burst (codex-rs/tui/src/bottom_pane/paste_burst.rs).
+//   We insert ASK_PEER_CODEX_SUBMIT_DELAY_MS between the text and the Enter
+//   so the suppression window expires. Verified live 2026-05-13.
+//
+//   Claude Code — has no hook event that fires while idle (verified via
+//   Claude Code's documented hook catalog at code.claude.com/docs/en/hooks;
+//   Notification is outbound-only; FileChanged cannot start a turn).
+//   No external surface can rouse an idle Claude Code peer. wakePeer()
+//   short-circuits with skipped_unsupported for this client_type.
+//
+//   Unknown — legacy v0.6 behavior (text + Enter, no gap). No implied
+//   promise; if a new TUI lands and breaks, we treat it as unknown until
+//   verified.
+//
+// Two send-keys calls: the text is interpreted literally (-l) and Enter is
+// parsed as a key event. The -l flag neutralizes any tmux keysequences a
+// malicious peer could plant in its registry entry.
 //
-// Pane targeting can go stale: tmux_pane is cached at server startup (registry
-// resolveTmuxPane), but Terminator-style window churn can move or close the
-// pane after registration. send-keys against a dead pane id errors; if pane
-// targeting fails and a sessionName is also available, retry against it
-// (targets the session's currently-active pane).
-function defaultFireWakeKeystrokes(target) {
+// Pane targeting can go stale: tmux_pane is cached at server startup
+// (registry resolveTmuxPane), but Terminator-style window churn can move or
+// close the pane after registration. send-keys against a dead pane id
+// errors; if pane targeting fails and a sessionName is also available,
+// retry against it (targets the session's currently-active pane).
+async function defaultFireWakeKeystrokes(target, clientType) {
     execFileSync("tmux", ["send-keys", "-t", target, "-l", ASK_PEER_WAKE_TEXT], {
         stdio: ["ignore", "pipe", "pipe"],
     });
+    if (clientType === "codex") {
+        await new Promise((resolve) => {
+            const timer = setTimeout(resolve, ASK_PEER_CODEX_SUBMIT_DELAY_MS);
+            timer.unref?.();
+        });
+    }
     execFileSync("tmux", ["send-keys", "-t", target, "Enter"], {
         stdio: ["ignore", "pipe", "pipe"],
     });
 }
-// Exported for unit testing the retry path; production callers use askPeerWake
-// which wires defaultFireWakeKeystrokes.
-export function askPeerWakeImpl(pane, sessionName, fire) {
+// Exported for unit testing the retry path; production callers use wakePeer
+// which wires defaultFireWakeKeystrokes via routing.
+export async function askPeerWakeImpl(pane, sessionName, fire) {
     if (!pane && !sessionName) {
         trace("ask_peer_wake_skipped", { reason: "no-pane-or-session" });
         return false;
     }
     const primary = pane ?? sessionName;
     try {
-        fire(primary);
+        await fire(primary);
         trace("ask_peer_wake_fired", { target: primary });
         return true;
     }
@@ -851,7 +901,7 @@ export function askPeerWakeImpl(pane, sessionName, fire) {
     }
     if (pane && sessionName && pane !== sessionName) {
         try {
-            fire(sessionName);
+            await fire(sessionName);
             trace("ask_peer_wake_fired_retry", { target: sessionName });
             return true;
         }
@@ -861,8 +911,55 @@ export function askPeerWakeImpl(pane, sessionName, fire) {
     }
     return false;
 }
-function askPeerWake(pane, sessionName) {
-    return askPeerWakeImpl(pane, sessionName, defaultFireWakeKeystrokes);
+// Route a wake to a peer based on OXTAIL_ASK_PEER_WAKE_STRATEGY and the
+// peer's client_type. Returns the wake_status that should surface in the
+// ask_peer response so callers can distinguish "we tried, no answer" from
+// "we didn't try because the client can't be woken."
+async function wakePeer(peer) {
+    if (ASK_PEER_WAKE_STRATEGY === "off") {
+        trace("ask_peer_wake_skipped", { reason: "strategy-off" });
+        return "disabled";
+    }
+    const clientType = peer.client.type;
+    if (ASK_PEER_WAKE_STRATEGY === "auto" && clientType === "claude-code") {
+        trace("ask_peer_wake_skipped", { reason: "client-unsupported", client_type: clientType });
+        return "skipped_unsupported";
+    }
+    if (!peer.tmux_pane && !peer.tmux_session) {
+        return "skipped_no_target";
+    }
+    // Race-fix: tmux_pane is cached at registration but pane ids can be reused
+    // by tmux after a pane is killed. If we send-keys against a reused id we
+    // wake the wrong shell. When the peer registered WITH a cached pane,
+    // re-resolve from its server_pid at wake-time and prefer the live value.
+    // If the peer registered without a pane (no TMUX_PANE in env, no ancestry
+    // match), skip the re-resolution entirely — fishing for a pane based on
+    // server_pid alone is unsafe (server_pid may not even still be alive, and
+    // in tests it can coincide with the test runner's process tree).
+    const livePane = peer.tmux_pane
+        ? currentPaneForServerPid(peer.server_pid)
+        : null;
+    if (peer.tmux_pane && livePane && livePane !== peer.tmux_pane) {
+        trace("ask_peer_wake_pane_refreshed", {
+            cached: peer.tmux_pane,
+            live: livePane,
+            server_pid: peer.server_pid,
+        });
+    }
+    else if (peer.tmux_pane && !livePane) {
+        trace("ask_peer_wake_pane_orphaned", {
+            cached: peer.tmux_pane,
+            server_pid: peer.server_pid,
+        });
+    }
+    const effectivePane = livePane ?? peer.tmux_pane;
+    // Legacy mode bypasses per-client routing: every wake is the v0.6 sequence
+    // (no inter-keystroke delay). Cast to "unknown" so defaultFireWakeKeystrokes
+    // skips the Codex delay branch.
+    const fireType = ASK_PEER_WAKE_STRATEGY === "legacy" ? "unknown" : clientType;
+    const fire = (target) => defaultFireWakeKeystrokes(target, fireType);
+    const ok = await askPeerWakeImpl(effectivePane, peer.tmux_session, fire);
+    return ok ? "fired" : "skipped_no_target";
 }
 // Poll my mailbox at ASK_PEER_POLL_MS until a matching reply lands or the
 // deadline elapses. Each tick checks mtime first and only acquires the
@@ -897,10 +994,13 @@ async function askPeerPoll(my_pid, from_session_id, deadlineMs, signal) {
 }
 server.registerTool("ask_peer", {
     description: [
-        "Synchronous delegate-and-wait. Wakes the peer via tmux send-keys and blocks until they reply (or timeout).",
-        "Use this when you want a synchronous back-and-forth with another agent in the same project root, rather than fire-and-forget like send_message.",
-        "Behavior: enqueues the body to the target's mailbox, waits ~500ms for a hook-delivered reply, then fires a tmux send-keys wake to nudge the peer if idle, then polls this session's mailbox at 200ms for a reply from the target.",
-        "Returns when the target sends a message back (via send_message) whose from_session_id matches them, or when the timeout elapses (returns reply: null, timed_out: true). Timeout defaults to 45000ms; user-tunable via OXTAIL_ASK_PEER_TIMEOUT_MS env var.",
+        "Enqueue a message to a peer and block until they reply (or timeout).",
+        "Use this when you want a back-and-forth with another agent in the same project root, rather than fire-and-forget like send_message.",
+        "Wake behavior (v0.7) varies per client_type. Codex peers are woken via paste-burst-aware tmux send-keys (literal text + 500ms gap + Enter) so the composer submits. Claude Code peers cannot be woken externally — Claude Code's hook surface has no idle event (verified against the documented hook catalog), so ask_peer fails fast for Claude Code targets and returns wake_status: \"skipped_unsupported\" rather than burning the timeout. Unknown clients use legacy send-keys wake.",
+        "Response includes a wake_status field: \"fired\" (wake attempted or reply received during grace window), \"skipped_unsupported\" (target client cannot be woken — fail-fast, no poll), \"skipped_no_target\" (no tmux pane or session resolved for target), \"disabled\" (OXTAIL_ASK_PEER_WAKE_STRATEGY=off).",
+        "Behavior: enqueues the body to the target's mailbox, waits ~500ms for a hook-delivered reply (rare: peer was mid-turn, hook delivered as additionalContext), fires the per-client wake, then polls this session's mailbox at 200ms for a reply from the target. Fail-fast for skipped_unsupported skips polling entirely; the message is still enqueued and will be delivered the next time the peer enters a turn.",
+        "Returns when the target sends a message back (via send_message) whose from_session_id matches them, or when the timeout elapses (returns reply: null, timed_out: true). timed_out is false on fail-fast (we didn't actually poll). Timeout defaults to 45000ms; user-tunable via OXTAIL_ASK_PEER_TIMEOUT_MS env var.",
+        "Wake strategy can be overridden via OXTAIL_ASK_PEER_WAKE_STRATEGY=auto|legacy|off (default auto). legacy = v0.6 behavior for every client (no gap, no per-client routing). off = no wake fired; ask_peer becomes a pure blocking poll until the peer naturally enters a turn or timeout.",
         "Target must have a registered client.session_id (Codex peers must call register_my_session first).",
         "Late replies that arrive after timeout are delivered normally via read_my_messages / the PreToolUse hook.",
         "Body framing: peers see the body verbatim. Include a short assignment-style framing (objective, what you want them to do) so they treat it as a delegation, not chat.",
@@ -975,6 +1075,7 @@ server.registerTool("ask_peer", {
     });
     let reply = null;
     let aborted = false;
+    let wakeStatus = "skipped_no_target";
     try {
         // Grace window: rare hook-delivery path. If peer was mid-tool-call when
         // our outbound arrived, their hook delivered it as additionalContext and
@@ -982,9 +1083,24 @@ server.registerTool("ask_peer", {
         await askPeerDelay(ASK_PEER_GRACE_MS, extra.signal);
         reply = mailbox.drainMatchingSession(entry.server_pid, expectedSessionId);
         if (!reply) {
-            // Common path: peer was idle; fire wake + poll.
-            askPeerWake(peer.tmux_pane, peer.tmux_session);
-            reply = await askPeerPoll(entry.server_pid, expectedSessionId, deadlineMs, extra.signal);
+            // Common path: peer was idle. Route the wake per client_type.
+            wakeStatus = await wakePeer(peer);
+            if (wakeStatus === "skipped_unsupported") {
+                // Claude Code idle has no external wake surface — polling would just
+                // burn the caller's wall-clock budget for no reason. Return fast so
+                // the caller can fall back to send_message + read_my_messages, or
+                // wait until the peer is observed mid-turn via list_project_sessions.
+                // The outbound has been enqueued; it'll be delivered next time the
+                // peer enters a turn (via PreToolUse hook or explicit read_my_messages).
+            }
+            else {
+                reply = await askPeerPoll(entry.server_pid, expectedSessionId, deadlineMs, extra.signal);
+            }
+        }
+        else {
+            // Reply arrived during grace window — peer was already mid-turn and
+            // the hook delivered the outbound to it as additionalContext.
+            wakeStatus = "fired";
         }
     }
     catch (e) {
@@ -1012,11 +1128,18 @@ server.registerTool("ask_peer", {
         // Throw to signal the framework that the request did not complete.
         throw new Error("ask_peer aborted by client");
     }
+    // timed_out is reserved for "we waited and got nothing" — i.e. we actually
+    // polled to the deadline. A fail-fast for an unwakeable client (no poll
+    // attempted) is NOT a timeout; the message has been enqueued and will be
+    // delivered when the peer next enters a turn.
+    const polled = wakeStatus !== "skipped_unsupported";
+    const timedOut = polled && reply === null;
     trace("ask_peer_end", {
         target_session_id: expectedSessionId,
         message_id: msg.id,
         duration_ms: Date.now() - startedAt,
-        timed_out: reply === null,
+        wake_status: wakeStatus,
+        timed_out: timedOut,
     });
     return {
         content: [
@@ -1026,6 +1149,7 @@ server.registerTool("ask_peer", {
                     schema_version: 1,
                     ok: true,
                     message_id: msg.id,
+                    wake_status: wakeStatus,
                     reply: reply
                         ? {
                             id: reply.id,
@@ -1034,7 +1158,7 @@ server.registerTool("ask_peer", {
                             from_session_id: reply.from_session_id ?? null,
                         }
                         : null,
-                    timed_out: reply === null,
+                    timed_out: timedOut,
                 }, null, 2),
             },
         ],
@@ -1057,6 +1181,14 @@ function maybeHookHint() {
     }
     process.stderr.write("[oxtail] PreToolUse hook not installed — run `npx oxtail install-hook` to enable mid-turn peer messaging.\n");
 }
-const transport = new StdioServerTransport();
-await server.connect(transport);
-maybeHookHint();
+// Importing server.ts (e.g. from a test that needs an exported helper) used
+// to await server.connect(transport) at module load — which never resolves
+// without stdin EOF and hung `npm test` indefinitely. Gate the transport
+// behind a direct-invocation check, mirroring scripts/install-hook.mjs.
+const invokedDirectly = typeof process.argv[1] === "string" &&
+    import.meta.url === new URL(process.argv[1], "file:").href;
+if (invokedDirectly) {
+    const transport = new StdioServerTransport();
+    await server.connect(transport);
+    maybeHookHint();
+}

package/integrations/codex/{oxtail-register → oxtail-join}/SKILL.md

@@ -1,11 +1,11 @@
 ---
-name: oxtail-register
-description: Register the current Codex agent session with the oxtail MCP peer registry. Use when the user asks to join oxtail, register with oxtail, run oxtail-register, fix oxtail client_session_id detection, or make this Codex session visible/readable to peer agents in the same project.
+name: oxtail-join
+description: Join this Codex session into the oxtail MCP peer registry. Use when the user asks to join oxtail, register with oxtail, run oxtail-join, fix oxtail client_session_id detection, or make this Codex session visible/readable to peer agents in the same project.
 ---
 
-# Oxtail Register
+# Oxtail Join
 
-Register this Codex session with oxtail quickly and verify the result.
+Join this Codex session into the oxtail peer registry quickly and verify the result.
 
 ## Communication Contract
 

package/integrations/codex/oxtail-join/agents/openai.yaml

@@ -0,0 +1,10 @@
+interface:
+  display_name: "Oxtail Join"
+  short_description: "Join this Codex session to the oxtail peer registry"
+  default_prompt: "Use $oxtail-join to register this Codex session with the oxtail peer registry."
+
+dependencies:
+  tools:
+    - type: "mcp"
+      value: "oxtail"
+      description: "Local oxtail MCP server exposing session registration tools"

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "oxtail",
-  "version": "0.6.0",
+  "version": "0.7.0",
   "private": false,
   "type": "module",
   "description": "Coordination layer for parallel AI coding agent sessions, exposed over MCP.",

package/integrations/codex/oxtail-register/agents/openai.yaml

@@ -1,10 +0,0 @@
-interface:
-  display_name: "Oxtail Register"
-  short_description: "Register Codex with oxtail peers"
-  default_prompt: "Use $oxtail-register to register this Codex session with the oxtail peer registry."
-
-dependencies:
-  tools:
-    - type: "mcp"
-      value: "oxtail"
-      description: "Local oxtail MCP server exposing session registration tools"