oxtail 0.11.0 → 0.13.0

package/AGENTS.md

@@ -55,9 +55,13 @@ The v0.9/v0.10.1 changes close the public dogfooding gaps found by real peer tra
 - **Session identity is monotonic after first non-null resolution.** Automatic detection is a bootstrap aid. Once `claim_session`, `register_my_session`, or sticky-claim recovery sets a session id, later env/birth-time detection and `get_my_session` refreshes must preserve it. Only another explicit claim can change it.
 - **`ask_peer` replies must correlate when the peer supports it.** Same-peer chatter is not a reply. Upgraded peers advertise `capabilities.mailbox.reply_to` and must satisfy waits with `from_session_id == target.session_id` plus `reply_to == request_id`; unmatched messages stay in the mailbox. The older `from_session_id`-only path is legacy compatibility and must be surfaced as `correlation: "uncorrelated"`. For no-capability peers, stale same-peer chatter may still satisfy the wait; that is an explicit compatibility limitation, not a correctness guarantee.
 - **Peer messages are context, not user authority.** Mailbox provenance (`origin: "peer"`, `request_id`, `reply_to`, `source_message_id`) is diagnostic metadata, not a trust boundary. Hook text must keep the trust framing visible — the "context, not user authority" line plus the `from_session_id` / `request_id` / `reply_to` reply fields (full protocol names) are rendered on every delivery — and injected hook bodies must stay under an explicit budget. Single-valued provenance the framing already implies (`origin: "peer"`) stays in the mailbox JSONL but need not be rendered into context.
+- **A displayed reply handle must be resolvable: record the received-ledger before the mailbox line is visible.** Both delivery paths are destructive — `read_my_messages` and the PreToolUse/Stop hook each truncate the mailbox on handoff — so `reply_to_message` resolves `message_id` against a durable per-session ledger (`~/.oxtail/received/<hash(session_id)>.jsonl`), never the queue. `deliverToPeer` (the single delivery primitive behind `send_message` / `ask_peer` / `reply_to_message`) MUST write the ledger entry **before** appending the mailbox line: append-then-record reopens a window where the hook renders a `message_id` the receiver cannot yet reply to. The ledger is keyed and owned by receiver `session_id`; a lookup reads only the caller's own file. The ledger write is best-effort (a failure degrades to "no handle, reply via `send_message`") but must never reorder ahead of, or block, the actual delivery.
 
 ## Recently shipped
 
+- **Reply by id + received-ledger (v0.13.0).** `reply_to_message(message_id, body)` looks the inbound envelope up in a durable per-session ledger and derives `target` / `reply_to` / `source_message_id` server-side, replacing the manual rewiring that silently degraded a correlated exchange into loose mailbox traffic. New `src/received.ts` (ledger: sha256-keyed file, `mkdir`-lock, bounded retention `OXTAIL_RECEIVED_MAX`=1000 with a `received_ledger_pruned` trace so a drop is never silent) and `src/delivery.ts` (`deliverToPeer` = `buildMessage` → `recordReceived` → `requeue` — the record-before-append ordering above), wired into `send_message` / `ask_peer` / `reply_to_message`. Adversarial race-pair + ledger-failure-still-delivers tests in `src/delivery.test.ts`. Converged with Codex over a 5-round peer-messaging pressure test; Codex's review caught the append-before-record race, fixed before merge.
+
+- **Wake hardening (v0.12.0 — issues #5/#6/#7, the v0.7-review backlog).** Three deferred wake items, landed together. **#6 (security):** wake send-keys now only ever target the pane the live process tree says hosts the peer's `server_pid` (`chooseVerifiedWakePane` → `currentPaneForServerPid`), never the peer's self-written `tmux_pane`/`tmux_session`; unverifiable ⇒ refuse (`skipped_no_target`). Registry-sourced tmux ids are shape-validated (`isValidTmuxPane`/`isValidTmuxSession`) and a spoofed `TMUX_PANE` env is ignored. This removed the cached-pane and session-name send-keys fallbacks (legit peers always register a real pane; churn is handled by re-resolution). **#5 (debounce):** all wake paths funnel through `wakePeer`, which coalesces repeat wakes to the same peer within `OXTAIL_WAKE_DEBOUNCE_MS` (default 1s, in-memory per process) ⇒ `skipped_debounced`. **#7 (observability):** a `wake_outcome` trace event per wake; `oxtail diagnose` summarizes wake_status counts by tool from `MCP_TRACE_FILE`; a scheduled `codex-drift.yml` fails if Codex's `PASTE_ENTER_SUPPRESS_WINDOW` drifts past our 500ms gap. New modules: `src/wake-debounce.ts`, `src/diagnose.ts`; `chooseVerifiedWakePane` in `src/registry.ts`.
 - **Wake-on-reply (Slice 1, peer-messaging refinement push).** A `send_message` that carries `reply_to` now auto-wakes the original requester **by default** (explicit `wake:"off"` opts out), closing the observed stranding where a peer's async reply to an idle requester forced a human to relay it. The reply path is a separate, stricter gate than the lenient `wake:"auto"` path (`src/autowake.ts`): it fires only for a **fresh-idle** target (idle marker newer than `OXTAIL_AUTOWAKE_FRESH_IDLE_MS`, default 5m) — stale/unknown/missing/busy ⇒ `skipped_no_fresh_idle`, never a best-effort wake — and adds a **per-target rate limit** (`skipped_rate_limited`), a persistent **one-wake dedupe** keyed on `(session_id, reply_to)` (`skipped_deduped`, GC'd by age) to survive duplicate/late hook drains, an `OXTAIL_AUTOWAKE=off` kill-switch, and a best-effort `skipped_store_error` degrade so a broken dedupe store can never turn an already-enqueued reply into a tool error. Target is resolved by `client.session_id` with the pane re-resolved immediately before send-keys (no `server_pid`/stale-pane reuse). Response surfaces `wake_status` + `wake_reason:"reply_to_default"`. **Coverage caveat:** the fresh-idle gate keys on the busy/idle marker that only the Claude Code hooks maintain, so this slice reaches a **hooked Claude Code requester** (the observed case). A Codex / hookless-Claude requester has no idle marker ⇒ `skipped_no_fresh_idle` (reach it with explicit `wake:"auto"`); closing that direction is **Slice 2** (`expects_reply:true` — a requester-side waiter signal), deliberately not faked here with a blind `unknown ⇒ wake` that would reintroduce the active-waiter double-wake.
 - **Protocol hardening (v0.10.1).** `ask_peer` now stamps outbound messages with `request_id`; reply-to-capable peers answer with `send_message({ reply_to: request_id })`, and the waiter ignores stale same-peer messages. Explicit identity claims are monotonic, so stale automatic detection cannot clobber a real client session id. PreToolUse/Stop hook pushes are body-budgeted and labeled as peer context, not user authority.
 - **Deliver-on-complete and state-gated wake (v0.9).** The Stop hook delivers waiting messages at turn end, closing the text-only-turn gap left by PreToolUse. `UserPromptSubmit`/`Stop` maintain a busy/idle flag so `send_message({ wake: "auto" })` nudges idle peers without typing into a busy composer. Sticky Codex claim recovery keeps identity across MCP child restarts.

package/README.md

@@ -36,7 +36,7 @@ args = ["-y", "oxtail@0.10.1"]
 
 ```sh
 mkdir -p ~/.claude/commands
-curl -L https://raw.githubusercontent.com/d4j3y2k/oxtail/v0.10.1/.claude/commands/oxtail-join.md \
+curl -L https://raw.githubusercontent.com/d4j3y2k/oxtail/v0.13.0/.claude/commands/oxtail-join.md \
   -o ~/.claude/commands/oxtail-join.md
 ```
 
@@ -44,9 +44,9 @@ curl -L https://raw.githubusercontent.com/d4j3y2k/oxtail/v0.10.1/.claude/command
 
 ```sh
 mkdir -p ~/.codex/skills/oxtail-join/agents
-curl -L https://raw.githubusercontent.com/d4j3y2k/oxtail/v0.10.1/integrations/codex/oxtail-join/SKILL.md \
+curl -L https://raw.githubusercontent.com/d4j3y2k/oxtail/v0.13.0/integrations/codex/oxtail-join/SKILL.md \
   -o ~/.codex/skills/oxtail-join/SKILL.md
-curl -L https://raw.githubusercontent.com/d4j3y2k/oxtail/v0.10.1/integrations/codex/oxtail-join/agents/openai.yaml \
+curl -L https://raw.githubusercontent.com/d4j3y2k/oxtail/v0.13.0/integrations/codex/oxtail-join/agents/openai.yaml \
   -o ~/.codex/skills/oxtail-join/agents/openai.yaml
 ```
 
@@ -68,10 +68,11 @@ Contributing? `git clone https://github.com/d4j3y2k/oxtail && cd oxtail && npm i
 - `send_message` — **fire-and-forget** message to a 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. A plain message does **not** wake an idle peer; pass `wake: "auto"` to nudge one (state-gated — see [Waking an idle peer](#waking-an-idle-peer)). Replies to `ask_peer` should pass `reply_to: "<request_id>"` when the inbound message carries a `request_id` — and a reply **auto-wakes the requester by default** (strictly gated; `wake: "off"` opts out). (v0.5+)
 - `read_my_messages` — drain this session's mailbox and return any queued messages. Messages include `from_session_id`, server-stamped `origin: "peer"`, and optional `request_id` / `reply_to`. Codex peers (and unhooked Claude Code) poll this; Claude Code peers with the hooks installed see messages mid-turn (PreToolUse) or at turn end (Stop) instead. (v0.5+)
 - `ask_peer` — **delegate-and-wait**. Enqueues a message with a `request_id` and blocks server-side until the peer replies with `send_message({ reply_to: request_id })` or the timeout elapses. Default timeout is 45s (`OXTAIL_ASK_PEER_TIMEOUT_MS`), and each call may pass `timeout_ms`. New peers use strict `reply_to` correlation; legacy/no-capability peers fall back to best-effort first-message matching and the response reports `correlation: "uncorrelated"`. That legacy path may stale-match old same-peer chatter, so callers should treat `uncorrelated` as compatibility-only. Use `send_message` for fire-and-forget. (v0.7+)
+- `reply_to_message` — **reply by `message_id`**. The atomic, correlation-safe alternative to hand-wiring `send_message`'s `target` + `reply_to`: pass the `message_id` the hook or `read_my_messages` showed you and the server looks the inbound envelope up in this session's durable **received-ledger**, derives the reply target (the original sender), carries `reply_to: request_id` when the inbound was an `ask_peer` (keeping the exchange correlated), and stamps `source_message_id`. Replying to a plain `send_message` works too — it just omits `reply_to`. Ownership is structural (you can only reply to a message delivered to *you*); fail-closed on an unknown/aged-out id. Same wake semantics as `send_message`, including the wake-on-reply default. (v0.13+)
 - `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.
 
-See [design principles](https://github.com/d4j3y2k/oxtail/blob/v0.10.1/AGENTS.md) for scope and architecture.
+See [design principles](https://github.com/d4j3y2k/oxtail/blob/v0.13.0/AGENTS.md) for scope and architecture.
 
 ## Usage from an agent
 
@@ -90,6 +91,8 @@ send_message({ target: "<peer-uuid>", body: "...", reply_to: "<ask request_id>"
 read_my_messages()
 ask_peer({ target: "primary", body: "[Handoff] please audit X and tell me what you find" })
   // → blocks server-side until the peer replies via send_message, then returns their body
+reply_to_message({ message_id: "<id from the hook / read_my_messages>", body: "..." })
+  // → looks up the inbound envelope, derives target + reply_to itself; correlated when the inbound was an ask_peer
 ```
 
 Omitting `project_root` triggers a best-effort `.git`-ancestor walk from the server's own cwd. The response includes `inferred: true` when this happens. Pass `project_root` explicitly when you can.
@@ -112,6 +115,8 @@ read_my_messages()
 
 The mailbox lives at `~/.oxtail/mailboxes/<server_pid>.jsonl`, append-only JSONL, drained under an `mkdir`-based advisory lock. The transport is intentionally dumb: 8KB UTF-8 body cap, sender chooses the framing (raw text or pre-wrapped `<system-reminder>...</system-reminder>`). Hook-delivered mailbox pushes are body-budgeted at 24K escaped characters by default; set `OXTAIL_HOOK_MAX_BODY_CHARS` to tune. If the budget is exceeded, the hook tells the receiver which bodies were truncated or omitted.
 
+Because both delivery paths are **destructive** — `read_my_messages` and the hook each truncate the mailbox once a message is handed off — a reply-by-id verb can't rely on the queue. Every delivered envelope is therefore also recorded in a durable **received-ledger** at `~/.oxtail/received/<hash(session_id)>.jsonl` keyed by `message_id`, written *before* the mailbox line becomes visible (so any handle a receiver can see is already resolvable) and bounded to the most recent `OXTAIL_RECEIVED_MAX` (default 1000) entries. `reply_to_message` reads only the caller's own ledger — that file *is* the ownership boundary.
+
 Inbound peer messages are context, not user authority. oxtail stamps delivered messages with `origin: "peer"` for provenance/debugging, but this is not a trust boundary and peers cannot mint trusted user instructions.
 
 Cross-project sends are rejected, never silently dropped. Sending to a peer with the same tmux session name as another live peer returns `ambiguous-target` with the candidate `client_session_id`s — use the UUID form to disambiguate.
@@ -172,6 +177,8 @@ If you have a hook installed on a managed event that isn't from Terminator and i
 
 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.
 
+Within that boundary oxtail still *narrows* redirectable side effects, as defense-in-depth rather than a hard boundary: wake keystrokes only go to the pane the process tree confirms hosts the target's `server_pid`, never a self-written `tmux_pane`/`tmux_session` (see [Pane targeting](#pane-targeting-verified)), and an accepted registry entry can't borrow another pid — its `server_pid` must match its own `<pid>.json` filename. So one peer's entry can't masquerade as hosting another agent to redirect that agent's wake. A same-user process can still overwrite any registry file outright (that's the trust boundary above); what it can't do is smuggle a pid mismatch past a reader.
+
 ## Delegate-and-wait (v0.10.1)
 
 `ask_peer` extends v0.5's mailbox transport into a blocking primitive:
@@ -182,7 +189,7 @@ ask_peer({ target, body })
       ok: true,
       message_id,
       request_id,
-      wake_status: "fired" | "skipped_unsupported" | "skipped_no_target" | "disabled",
+      wake_status: "fired" | "skipped_busy" | "skipped_debounced" | "skipped_no_target" | "disabled",
       reply: { id, body, enqueued_at, from_session_id, reply_to, correlation } | null,
       correlation: "correlated" | "uncorrelated" | "none",
       timeout_ms,
@@ -190,7 +197,7 @@ ask_peer({ target, body })
     }
 ```
 
-`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` is reserved — no client currently returns this in auto mode (both Codex and Claude Code wake via send-keys). `skipped_no_target` means no tmux pane/session resolved for the target. `disabled` means `OXTAIL_ASK_PEER_WAKE_STRATEGY=off` is in effect.
+`wake_status` distinguishes the 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_busy` means the peer is mid-turn (its hooks/poll will deliver — we still poll for the reply). `skipped_debounced` means a wake fired for this peer moments ago and this one was coalesced. `skipped_no_target` means no process-tree-verified pane resolved for the target. `disabled` means `OXTAIL_ASK_PEER_WAKE_STRATEGY=off` is in effect. (`skipped_unsupported` is reserved — no client currently returns it.)
 
 `timed_out` is `true` only when the poll loop ran to its deadline without a reply.
 
@@ -220,9 +227,13 @@ ask_peer({ target, body })
 4. Poll the caller's mailbox at 200ms. For reply-to-capable peers, only a message with both `from_session_id == target.session_id` and `reply_to == request_id` satisfies the wait; non-matching messages stay in the mailbox untouched. Legacy/no-capability peers are best-effort and are marked `correlation: "uncorrelated"`; this preserves old peers but can stale-match old same-peer chatter.
 5. Return the reply on match, or `{ reply: null, timed_out: true, wake_status, correlation: "none" }` after the 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 (verified)
+
+A peer's cached `tmux_pane` / `tmux_session` are written by the peer into its **own** registry file, so they aren't trustworthy targets for keystrokes — a malicious local peer could point them at someone else's pane. The **only** send-keys target oxtail uses is the pane the live process tree says currently hosts the peer's `server_pid` (resolved at wake-time via `ps`/`tmux` ancestry — unforgeable by editing a JSON file). This also handles pane-id churn for free: the pane is always re-resolved fresh. If `server_pid` can't be bound to any live pane, oxtail **refuses** to wake (`wake_status: "skipped_no_target"`) rather than fall back to a self-written value. `server_pid` itself is self-written too, so registry entries whose `server_pid` doesn't match their own `<pid>.json` filename are rejected — a forged entry can't borrow another process's pane. The pane id that does reach `tmux` is shape-validated (`%\d+`); session names are no longer used as a send-keys target at all. (Hardening from issue #6.)
 
-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`.
+### Wake debouncing
+
+All wake paths funnel through one place, which **coalesces** rapid repeat wakes to the same peer: if a wake fired for a peer within `OXTAIL_WAKE_DEBOUNCE_MS` (default 1s), a follow-up wake is skipped (`wake_status: "skipped_debounced"`) and relies on the still-pending response. This keeps a retried `ask_peer`, two callers racing the same peer, or a polling loop from stacking notification lines into the peer's composer. In-memory and per-process by design. (Issue #5.)
 
 ### Constraints
 
@@ -281,10 +292,25 @@ When a strategy doesn't fire, it returns an abstention with a `reason` (e.g. `"2
 
 If `MCP_TRACE_FILE` is set in the environment, every detection run appends an NDJSON record with trigger, winning strategy, per-strategy outcomes, and `next_step`. Useful for diagnosing unresolved `client_session_id`s in the wild.
 
+### Diagnosing wakes (`oxtail diagnose`)
+
+The same `MCP_TRACE_FILE` also captures a `wake_outcome` record for every wake (which tool drove it and the resulting `wake_status`). Run:
+
+```sh
+oxtail diagnose
+```
+
+to get a summary — counts by `wake_status`, broken down by tool — so "is the wake mechanism working in my environment?" is one command instead of grepping JSONL. With `MCP_TRACE_FILE` unset it just prints how to enable tracing. (Issue #7.)
+
+A scheduled CI job (`.github/workflows/codex-drift.yml`, also runnable on demand) fetches Codex's upstream `PASTE_ENTER_SUPPRESS_WINDOW` and fails if it drifts past oxtail's 500ms Codex wake gap — so a future Codex release that would break the wake surfaces as a red job rather than a silent field regression.
+
 ## Status
 
-v0.10.1. Completes the autonomous peer-messaging matrix and hardens the protocol: a message reaches a Claude Code peer whether it's mid-turn, finishing, or fully idle, and delegate-and-wait replies are correlated by `request_id` / `reply_to` for upgraded peers.
+v0.13.0. Pushes the autonomous peer-messaging matrix toward zero human relay, hardens the wake path, then makes correlated replies atomic.
 
+- **Reply by id (v0.13.0).** `reply_to_message(message_id, body)` removes the manual `target` + `reply_to` rewiring that silently degraded a correlated exchange into loose mailbox traffic: the server looks the inbound envelope up in a durable per-session **received-ledger** (`~/.oxtail/received/<hash(session_id)>.jsonl`), derives the reply target and `reply_to` itself, and enforces ownership structurally (you can only reply to a message delivered to you). The ledger is written *before* the mailbox line is visible — so a handle the hook displays is always resolvable even though both delivery paths destroy the queue entry once it is handed off. Fail-closed on an unknown/aged-out id.
+- **Wake-on-reply (v0.11.0).** A reply — `send_message` with `reply_to` — auto-wakes a freshly-idle requester by default, so an awaited answer doesn't strand an idle peer. Strictly gated (fresh-idle only, per-target rate limit, one-wake dedupe, `OXTAIL_AUTOWAKE=off` kill-switch). `wake:"off"` opts out; explicit `wake:"auto"` is the escape hatch for a requester without an idle marker (Codex / hookless Claude).
+- **Wake hardening (v0.12.0).** Wake keystrokes only ever target the pane the process tree confirms hosts the peer's `server_pid` — never a self-written `tmux_pane`/`tmux_session`, and registry entries whose `server_pid` doesn't match their filename are rejected. Rapid repeat wakes to one peer are coalesced (`skipped_debounced`). `oxtail diagnose` summarizes wake outcomes from `MCP_TRACE_FILE`, and a scheduled CI job flags drift in Codex's paste-burst window before it can break the wake.
 - **Correlated delegate-and-wait.** `ask_peer` now sends a `request_id`; upgraded peers reply with `send_message({ reply_to })`, and the waiter ignores same-peer chatter that does not match. Legacy peers are still supported, but their replies are marked `correlation: "uncorrelated"`.
 - **Identity monotonicity.** `claim_session` / `register_my_session` and sticky-claim recovery are authoritative after they set a session id; later automatic detection cannot clobber a claimed id with stale env data.
 - **Hook push budgeting and provenance.** PreToolUse/Stop delivery stamps `origin: "peer"`, reminds receivers that peer messages are not user authority, and caps hook-injected body text via `OXTAIL_HOOK_MAX_BODY_CHARS`.

package/dist/delivery.js

@@ -0,0 +1,32 @@
+import * as mailbox from "./mailbox.js";
+import { recordReceived } from "./received.js";
+import { trace } from "./trace.js";
+// Deliver a message to a peer's mailbox, recording the durable reply-handle in
+// the receiver's ledger BEFORE the mailbox line becomes visible. The ordering is
+// the correctness guarantee: a hook/poll drainer can only observe the mailbox
+// line after the append, which happens strictly after the ledger write — so any
+// message_id a receiver can drain/render already has a ledger entry behind it.
+// The reverse order (append, then record) left a window where the hook rendered
+// a handle reply_to_message could not yet resolve (the race Codex caught).
+//
+// receiverSessionId may be null/empty (an unclaimed peer): then there is no
+// ledger to own the handle and we skip the record — reply_to_message simply
+// won't find it, which is the documented fall-back-to-send_message path.
+//
+// The ledger write is best-effort: a ledger failure must NEVER drop the actual
+// delivery. Worst case the reply handle is missing and the peer falls back to
+// send_message — never the reverse (a visible line with no handle on success),
+// because record precedes append.
+export function deliverToPeer(receiverSessionId, targetPid, body, fromSessionId, options = {}) {
+    const msg = mailbox.buildMessage(body, fromSessionId, options);
+    if (receiverSessionId) {
+        try {
+            recordReceived(receiverSessionId, msg);
+        }
+        catch (e) {
+            trace("received_ledger_write_failed", { message_id: msg.id, error: String(e) });
+        }
+    }
+    mailbox.requeue(targetPid, msg);
+    return msg;
+}

package/dist/diagnose.js

@@ -0,0 +1,75 @@
+// Issue #7 — `oxtail diagnose`.
+//
+// The wake mechanism is environment-sensitive (tmux present? peer in a pane?
+// Codex paste-burst gap still sufficient?). When it silently doesn't work, a
+// user otherwise has to spelunk MCP_TRACE_FILE by hand. This summarizes the
+// `wake_outcome` trace events oxtail emits — counts by wake_status, broken down
+// by which tool drove the wake — so "is wake working here?" is one command.
+import { readFileSync } from "node:fs";
+// Keep only `wake_outcome` events, newest `limit`, and tally them. Malformed
+// JSONL lines are skipped (a trace file can be concurrently appended).
+export function summarizeWakeOutcomes(lines, limit = 200) {
+    const outcomes = [];
+    for (const line of lines) {
+        if (!line.trim())
+            continue;
+        let rec;
+        try {
+            rec = JSON.parse(line);
+        }
+        catch {
+            continue;
+        }
+        if (rec.event === "wake_outcome")
+            outcomes.push(rec);
+    }
+    const recent = limit > 0 ? outcomes.slice(-limit) : outcomes;
+    const byStatus = {};
+    const byVia = {};
+    for (const r of recent) {
+        const status = String(r.wake_status ?? "unknown");
+        const via = String(r.via ?? "unknown");
+        byStatus[status] = (byStatus[status] ?? 0) + 1;
+        const viaBucket = (byVia[via] ??= {});
+        viaBucket[status] = (viaBucket[status] ?? 0) + 1;
+    }
+    return { total: recent.length, considered: outcomes.length, byStatus, byVia };
+}
+function sortedCounts(counts) {
+    return Object.entries(counts).sort((a, b) => b[1] - a[1] || a[0].localeCompare(b[0]));
+}
+export function formatWakeSummary(s) {
+    if (s.total === 0) {
+        return "oxtail diagnose: no wake_outcome events in the trace yet (no ask_peer / wake:auto / reply-default wakes recorded).";
+    }
+    const lines = [];
+    const capped = s.considered > s.total ? ` (newest ${s.total} of ${s.considered})` : ` (${s.total})`;
+    lines.push(`oxtail diagnose — wake outcomes${capped}:`);
+    for (const [status, n] of sortedCounts(s.byStatus)) {
+        lines.push(`  ${status}: ${n}`);
+    }
+    lines.push("by tool:");
+    for (const [via, counts] of Object.entries(s.byVia).sort()) {
+        const parts = sortedCounts(counts).map(([st, n]) => `${st} ${n}`);
+        lines.push(`  ${via}: ${parts.join(", ")}`);
+    }
+    return lines.join("\n");
+}
+// CLI entry. Returns a process exit code; `out` is injectable for tests.
+export function runDiagnose(traceFile, out = console.log) {
+    if (!traceFile) {
+        out("oxtail diagnose: MCP_TRACE_FILE is not set, so there is no trace data to summarize.");
+        out("Set MCP_TRACE_FILE=/path/to/oxtail-trace.jsonl in the oxtail MCP server's env (e.g. in .mcp.json / ~/.claude.json / ~/.codex/config.toml), reproduce some wakes, then re-run `oxtail diagnose`.");
+        return 0;
+    }
+    let content;
+    try {
+        content = readFileSync(traceFile, "utf8");
+    }
+    catch {
+        out(`oxtail diagnose: could not read trace file ${traceFile} (set MCP_TRACE_FILE and reproduce some wakes first).`);
+        return 1;
+    }
+    out(formatWakeSummary(summarizeWakeOutcomes(content.split("\n"))));
+    return 0;
+}

package/dist/mailbox.js

@@ -107,8 +107,12 @@ export function serializeMailboxLine(msg) {
     }
     return line;
 }
-export function enqueue(target_pid, body, from_session_id, options = {}) {
-    const msg = {
+// Mint a message envelope WITHOUT writing it anywhere. Split out from enqueue so
+// a higher layer (delivery.ts) can record the durable received-ledger entry
+// BEFORE the mailbox line becomes visible — the ordering that guarantees any
+// message_id a receiver can drain/render already has a ledger entry behind it.
+export function buildMessage(body, from_session_id, options = {}) {
+    return {
         schema_version: 1,
         id: randomBytes(8).toString("hex"),
         body,
@@ -120,10 +124,12 @@ export function enqueue(target_pid, body, from_session_id, options = {}) {
         ...(options.reply_to ? { reply_to: options.reply_to } : {}),
         ...(options.source_message_id ? { source_message_id: options.source_message_id } : {}),
     };
-    const line = serializeMailboxLine(msg);
+}
+export function enqueue(target_pid, body, from_session_id, options = {}) {
+    const msg = buildMessage(body, from_session_id, options);
     acquireLock(target_pid);
     try {
-        appendFileSync(mailboxPath(target_pid), line);
+        appendFileSync(mailboxPath(target_pid), serializeMailboxLine(msg));
     }
     finally {
         releaseLock(target_pid);

package/dist/received.js

@@ -0,0 +1,176 @@
+import { createHash } from "node:crypto";
+import { mkdirSync, readFileSync, rmdirSync, statSync, writeFileSync, } from "node:fs";
+import { homedir } from "node:os";
+import { join } from "node:path";
+import { trace } from "./trace.js";
+// The received-message ledger: a durable, per-session index of every inbound
+// envelope, keyed by message_id. It exists because both delivery paths are
+// DESTRUCTIVE — mailbox.drain() truncates the queue to 0 after a read, and the
+// PreToolUse hook does `:> "$m"` after rendering messages into model context.
+// So once a message is delivered, the mailbox no longer holds it. A reply verb
+// (reply_to_message) that looks a message up by id therefore cannot rely on the
+// mailbox; it needs this separate ledger.
+//
+// Correctness hinges on ORDERING, enforced by delivery.ts: the ledger entry is
+// written BEFORE the mailbox line becomes visible. A drainer can only observe
+// the line after the append, which happens strictly after this write — so any
+// message_id a receiver can see has a ledger entry behind it. (The reverse order
+// left a window where the hook rendered a handle reply_to_message couldn't yet
+// resolve — the race Codex caught in review.)
+//
+// Ownership is structural: the ledger lives at received/<hash(session_id)>, and
+// lookups only ever read the caller's own file. You can only reply to a message
+// that was delivered to YOU.
+function receivedDir() {
+    // Resolved lazily so tests can swap HOME between cases (mirrors mailbox.ts).
+    return join(homedir(), ".oxtail", "received");
+}
+// Hash the session_id into the filename (mirrors claims.ts) so two distinct ids
+// can never collide onto one ledger file — a lossy character-sanitize could map
+// different sessions to the same path. UUIDs are already path-safe; the hash is
+// defensive and collision-free.
+function ledgerKey(sessionId) {
+    return createHash("sha256").update(sessionId).digest("hex").slice(0, 32);
+}
+function ledgerPath(sessionId) {
+    return join(receivedDir(), `${ledgerKey(sessionId)}.jsonl`);
+}
+function lockPath(sessionId) {
+    return `${ledgerPath(sessionId)}.lock`;
+}
+// Lock idiom mirrors mailbox.ts (mkdir-based, staleness-cleared). The ledger
+// read-modify-write is small (bounded by receivedMax() lines) so the lock
+// window is short.
+const LOCK_STALE_MS = 30_000;
+const LOCK_RETRY_LIMIT = 50;
+const LOCK_RETRY_DELAY_MS = 10;
+// Bounded retention: keep at most this many of the most-recent inbound messages
+// per session. Read lazily so tests can tune it per-case. Generous by default so
+// a realistic mailbox burst (read_my_messages budgets 50/drain) can't push a
+// just-displayed handle out of the ledger before the receiver replies; when the
+// cap DOES bite, recordReceived traces the drop so it is never silent.
+export function receivedMax() {
+    const n = Number(process.env.OXTAIL_RECEIVED_MAX);
+    return Number.isFinite(n) && n > 0 ? Math.floor(n) : 1000;
+}
+function sleepSync(ms) {
+    Atomics.wait(new Int32Array(new SharedArrayBuffer(4)), 0, 0, ms);
+}
+function acquireLock(sessionId) {
+    mkdirSync(receivedDir(), { recursive: true, mode: 0o700 });
+    const lock = lockPath(sessionId);
+    for (let i = 0; i < LOCK_RETRY_LIMIT; i++) {
+        try {
+            mkdirSync(lock, { mode: 0o700 });
+            return;
+        }
+        catch (e) {
+            const err = e;
+            if (err.code !== "EEXIST")
+                throw err;
+            try {
+                const st = statSync(lock);
+                if (Date.now() - st.mtimeMs > LOCK_STALE_MS) {
+                    try {
+                        rmdirSync(lock);
+                        trace("received_lock_stale_clear", { session_id: sessionId });
+                    }
+                    catch {
+                        // raced with another clearer; fall through to retry
+                    }
+                    continue;
+                }
+            }
+            catch {
+                // stat may race; just retry
+            }
+            sleepSync(LOCK_RETRY_DELAY_MS);
+        }
+    }
+    throw new Error(`could not acquire received-ledger lock for ${sessionId}`);
+}
+function releaseLock(sessionId) {
+    try {
+        rmdirSync(lockPath(sessionId));
+    }
+    catch {
+        // ignore ENOENT / not-empty / EPERM
+    }
+}
+function readLines(sessionId) {
+    try {
+        const raw = readFileSync(ledgerPath(sessionId), "utf8");
+        if (!raw)
+            return [];
+        return raw.split("\n").filter((l) => l.length > 0);
+    }
+    catch (e) {
+        const err = e;
+        if (err.code === "ENOENT")
+            return [];
+        throw err;
+    }
+}
+// Append an inbound envelope to the receiver's ledger and prune to receivedMax()
+// (oldest dropped first). Called by delivery.ts BEFORE the mailbox append.
+export function recordReceived(receiverSessionId, msg) {
+    if (!receiverSessionId)
+        return;
+    acquireLock(receiverSessionId);
+    try {
+        const lines = readLines(receiverSessionId);
+        lines.push(JSON.stringify(msg));
+        const max = receivedMax();
+        let pruned = lines;
+        if (lines.length > max) {
+            pruned = lines.slice(lines.length - max);
+            // No silent caps: a dropped handle becomes reply_to_message
+            // "message-not-found", so surface that the bound bit.
+            trace("received_ledger_pruned", {
+                session_id: receiverSessionId,
+                dropped: lines.length - max,
+                kept: max,
+            });
+        }
+        writeFileSync(ledgerPath(receiverSessionId), pruned.join("\n") + "\n", {
+            mode: 0o600,
+        });
+    }
+    finally {
+        releaseLock(receiverSessionId);
+    }
+}
+// Look up a previously-received envelope by message_id in this session's ledger.
+// Newest-first scan (ids are unique, so the first match is the only match).
+// Returns null when not found / aged out — the fail-closed signal the reply
+// verb turns into message-not-found. Read under the same lock so a concurrent
+// recordReceived rewrite can't be observed half-written.
+export function lookupReceived(receiverSessionId, messageId) {
+    if (!receiverSessionId)
+        return null;
+    acquireLock(receiverSessionId);
+    try {
+        const lines = readLines(receiverSessionId);
+        for (let i = lines.length - 1; i >= 0; i--) {
+            let parsed;
+            try {
+                parsed = JSON.parse(lines[i]);
+            }
+            catch {
+                continue;
+            }
+            if (parsed &&
+                typeof parsed === "object" &&
+                parsed.id === messageId) {
+                return parsed;
+            }
+        }
+        return null;
+    }
+    finally {
+        releaseLock(receiverSessionId);
+    }
+}
+export function receivedFilePath(sessionId) {
+    return ledgerPath(sessionId);
+}

package/dist/registry.js

@@ -42,6 +42,73 @@ function ensureDir() {
 function entryPath(pid) {
     return join(registryDir(), `${pid}.json`);
 }
+// tmux's own identifiers, used to sanitize registry-sourced values before they
+// reach a `tmux` command. A pane id is always `%<n>`; a session name, per tmux's
+// rules for names we create, is `[A-Za-z0-9_-]+`. Validating defends against a
+// malicious local peer writing a crafted `tmux_pane`/`tmux_session` into its own
+// registry file to redirect or trick our wake send-keys (issue #6).
+export function isValidTmuxPane(s) {
+    return /^%\d+$/.test(s);
+}
+export function isValidTmuxSession(s) {
+    return /^[A-Za-z0-9_-]+$/.test(s);
+}
+// The ONLY trustworthy send-keys target for waking a peer: the pane the live
+// process tree says currently hosts the peer's `server_pid`. This is computed
+// from `ps`/`tmux` state (currentPaneForServerPid), so it cannot be forged by a
+// peer editing its own `~/.oxtail/sessions/<pid>.json` — unlike the cached
+// `tmux_pane`/`tmux_session` fields, which the peer self-writes. Returns null
+// (caller must refuse to wake) when:
+//   - the peer never registered a pane: a legit tmux-hosted peer always does
+//     (its session is derived from the pane), so a pane-less/session-only entry
+//     is hand-written or spoofed and must never be blind-fired; gating on a
+//     registered pane also avoids fishing for a pane from server_pid alone,
+//     which in tests can collide with the test runner's own pane.
+//   - server_pid isn't under any live tmux pane: we can't bind a trustworthy
+//     target, so we refuse rather than fall back to the self-written cached value.
+//   - the resolved pane isn't a well-formed pane id (tmux output anomaly).
+// resolvePane is injected in tests; production uses currentPaneForServerPid.
+export function chooseVerifiedWakePane(peer, resolvePane = currentPaneForServerPid) {
+    if (!peer.tmux_pane)
+        return null;
+    const live = resolvePane(peer.server_pid);
+    if (!live || !isValidTmuxPane(live))
+        return null;
+    return live;
+}
+// Extract the pid a registry filename encodes: `<pid>.json` → pid, else null.
+export function filenamePid(file) {
+    const m = /^(\d+)\.json$/.exec(file);
+    if (!m)
+        return null;
+    const pid = Number(m[1]);
+    return Number.isInteger(pid) && pid > 0 ? pid : null;
+}
+// Read + parse a registry file, enforcing the provenance invariant that a
+// process only ever writes its OWN `<pid>.json`: the parsed `server_pid` MUST
+// equal the pid in the filename. register() always writes them in agreement, so
+// a mismatch means the entry was hand-forged to borrow another process's pid —
+// the #6 redirect where a peer self-writes `server_pid: <victimPid>` so that
+// chooseVerifiedWakePane → currentPaneForServerPid resolves (and wakes) the
+// victim's pane. Such entries, plus non-`<pid>.json` names and parse failures,
+// are rejected (returns null) so no raw-registry reader trusts them. The
+// local-user trust boundary still holds (a same-user process can overwrite any
+// file), but this stops one peer's entry from impersonating another pid.
+export function readEntryFile(dir, file) {
+    const fnamePid = filenamePid(file);
+    if (fnamePid === null)
+        return null;
+    let entry;
+    try {
+        entry = JSON.parse(readFileSync(join(dir, file), "utf8"));
+    }
+    catch {
+        return null;
+    }
+    if (entry.server_pid !== fnamePid)
+        return null;
+    return entry;
+}
 function resolveTmuxSessionFromPane(pane) {
     if (!pane)
         return null;
@@ -120,7 +187,10 @@ export function findTmuxPaneByAncestry(startPid, panePids, ppids) {
     return null;
 }
 export function resolveTmuxPane(env = process.env, pid = process.pid) {
-    if (env.TMUX_PANE)
+    // TMUX_PANE is a peer-controllable env var: only trust it if it has tmux's
+    // pane-id shape (%N). A spoofed/malformed value falls through to process-tree
+    // ancestry, which can't be forged by editing the environment (issue #6).
+    if (env.TMUX_PANE && isValidTmuxPane(env.TMUX_PANE))
         return env.TMUX_PANE;
     return findTmuxPaneByAncestry(pid, listTmuxPanePids(), listAllPpids());
 }
@@ -194,16 +264,10 @@ function gcDeadSiblings(entry) {
     if (!existsSync(dir))
         return;
     for (const file of readdirSync(dir)) {
-        if (!file.endsWith(".json"))
-            continue;
+        const other = readEntryFile(dir, file);
+        if (!other)
+            continue; // skip non-<pid>.json, parse errors, and forged entries
         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)
@@ -267,16 +331,10 @@ export function readAll() {
         return [];
     const live = [];
     for (const file of readdirSync(dir)) {
-        if (!file.endsWith(".json"))
-            continue;
+        const entry = readEntryFile(dir, file);
+        if (!entry)
+            continue; // non-<pid>.json, parse error, or forged server_pid
         const full = join(dir, file);
-        let entry;
-        try {
-            entry = JSON.parse(readFileSync(full, "utf8"));
-        }
-        catch {
-            continue;
-        }
         if (!isAlive(entry.server_pid)) {
             // Reap-deferral: a dead child's mailbox may still hold undrained mail
             // that the session's union-drain (PreToolUse hook + read_my_messages)
@@ -342,15 +400,9 @@ export function sessionPidsForId(sessionId) {
         return [];
     const entries = [];
     for (const file of readdirSync(dir)) {
-        if (!file.endsWith(".json"))
-            continue;
-        let e;
-        try {
-            e = JSON.parse(readFileSync(join(dir, file), "utf8"));
-        }
-        catch {
-            continue;
-        }
+        const e = readEntryFile(dir, file);
+        if (!e)
+            continue; // skip non-<pid>.json, parse errors, and forged entries
         if (e.client.session_id === sessionId)
             entries.push(e);
     }

package/dist/server.js

@@ -10,10 +10,13 @@ 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, currentPaneForServerPid, findByTmuxSession, readAll, refreshTmuxBinding, register, sessionPidsForId, unregister, } from "./registry.js";
+import { buildEntry, chooseVerifiedWakePane, findByTmuxSession, readAll, refreshTmuxBinding, register, sessionPidsForId, unregister, } from "./registry.js";
 import * as mailbox from "./mailbox.js";
+import * as received from "./received.js";
+import { deliverToPeer } from "./delivery.js";
 import { recoverClaim, resolveAncestors, writeClaim } from "./claims.js";
 import { decideReplyAutoWake, defaultAutowakeDir } from "./autowake.js";
+import { markWoke, newWakeDebounceStore, recentlyWoke } from "./wake-debounce.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
 // session. Use named exports and await them; calling `await import(...)`
@@ -33,6 +36,10 @@ import { decideReplyAutoWake, defaultAutowakeDir } from "./autowake.js";
         await mod.uninstall();
         process.exit(0);
     }
+    if (sub === "diagnose") {
+        const { runDiagnose } = await import("./diagnose.js");
+        process.exit(runDiagnose(process.env.MCP_TRACE_FILE));
+    }
 }
 import { readClaudeTranscript, readCodexTranscript, } from "./transcripts.js";
 // Single builder for every readSession return so the field set (including the
@@ -1003,7 +1010,7 @@ function resolveTarget(target, caller) {
 server.registerTool("send_message", {
     description: [
         "Fire-and-forget message to a peer in the same project root. Target: a tmux session name OR a client_session_id (UUID). Async via the peer's mailbox — delivered mid-turn (PreToolUse hook) or next-turn (read_my_messages); cross-project targets are rejected.",
-        "A plain message does NOT wake an idle peer. Pass wake:\"auto\" to nudge one via per-client send-keys, state-gated (skipped if the peer is mid-turn). EXCEPTION (wake-on-reply): when you set reply_to, this auto-wakes the requester by default so your answer doesn't strand them idle — pass wake:\"off\" to suppress. The reply-default wake is strictly gated: it fires only for a FRESHLY-IDLE requester (one whose Claude Code hooks maintain a fresh idle marker), with a per-target rate limit and a one-wake dedupe; env kill-switch OXTAIL_AUTOWAKE=off. A requester with no idle marker (Codex, or Claude without the hooks) returns skipped_no_fresh_idle and is NOT auto-woken — use explicit wake:\"auto\" for those. Response carries wake_status (\"fired\" | \"skipped_busy\" | \"skipped_no_fresh_idle\" | \"skipped_rate_limited\" | \"skipped_deduped\" | \"skipped_store_error\" | \"skipped_no_target\" | \"disabled\") and, on the reply path, wake_reason:\"reply_to_default\".",
+        "A plain message does NOT wake an idle peer. Pass wake:\"auto\" to nudge one via per-client send-keys, state-gated (skipped if the peer is mid-turn). EXCEPTION (wake-on-reply): when you set reply_to, this auto-wakes the requester by default so your answer doesn't strand them idle — pass wake:\"off\" to suppress. The reply-default wake is strictly gated: it fires only for a FRESHLY-IDLE requester (one whose Claude Code hooks maintain a fresh idle marker), with a per-target rate limit and a one-wake dedupe; env kill-switch OXTAIL_AUTOWAKE=off. A requester with no idle marker (Codex, or Claude without the hooks) returns skipped_no_fresh_idle and is NOT auto-woken — use explicit wake:\"auto\" for those. Response carries wake_status (\"fired\" | \"skipped_busy\" | \"skipped_debounced\" | \"skipped_no_fresh_idle\" | \"skipped_rate_limited\" | \"skipped_deduped\" | \"skipped_store_error\" | \"skipped_no_target\" | \"disabled\") and, on the reply path, wake_reason:\"reply_to_default\".",
         "Body is verbatim — wrap in <system-reminder>...</system-reminder> yourself if you want that framing. When replying to ask_peer, include reply_to: request_id from the inbound message. For a blocking send-and-wait, use ask_peer instead.",
     ].join(" "),
     inputSchema: {
@@ -1048,11 +1055,23 @@ server.registerTool("send_message", {
     }
     const peer = resolved.entry;
     const fromSessionId = entry.client.session_id ?? undefined;
-    const msg = mailbox.enqueue(peer.server_pid, body, fromSessionId, {
+    // deliverToPeer records the durable reply-handle in the recipient's ledger
+    // BEFORE the mailbox line is visible, so a later reply_to_message(message_id)
+    // resolves even after the destructive mailbox/hook drain — and never sees a
+    // displayed-but-unrecorded handle (record precedes append).
+    const msg = deliverToPeer(peer.client.session_id, peer.server_pid, body, fromSessionId, {
         reply_to,
         source_message_id,
     });
     const { wake_status, wake_reason } = await resolveSendWake(peer, wake, reply_to);
+    if (wake_status) {
+        trace("wake_outcome", {
+            via: wake_reason === "reply_to_default" ? "reply_default" : "send_message",
+            wake_status,
+            target_session_id: peer.client.session_id,
+            client_type: peer.client.type,
+        });
+    }
     return jsonResult({
         schema_version: 1,
         ok: true,
@@ -1063,6 +1082,100 @@ server.registerTool("send_message", {
         ...(wake_reason ? { wake_reason } : {}),
     });
 });
+server.registerTool("reply_to_message", {
+    description: [
+        "Reply to a specific inbound peer message by its message_id — the atomic, correlation-safe alternative to hand-wiring send_message's target + reply_to. The server looks the message up in this session's durable received-ledger, so you pass only the message_id the PreToolUse hook or read_my_messages already showed you; it derives the reply target (the original sender), carries reply_to=request_id when the inbound was an ask_peer (keeping the exchange correlated), and sets source_message_id for provenance. Replying to a plain send_message works too — it just omits reply_to. Ownership is structural: you can only reply to a message delivered to you.",
+        "Delivery + wake match send_message exactly, including the wake-on-reply default: when the inbound carried a request_id and you leave wake unset, a freshly-idle requester is auto-woken; pass wake:\"auto\" to nudge any idle peer, or wake:\"off\" to suppress. Fail-closed: an unknown or aged-out message_id returns error message-not-found instead of guessing a target.",
+    ].join(" "),
+    inputSchema: {
+        message_id: z
+            .string()
+            .min(1)
+            .describe("The message_id of the inbound peer message you are replying to, as shown by the PreToolUse hook or read_my_messages."),
+        body: z
+            .string()
+            .min(1)
+            .refine((s) => Buffer.byteLength(s, "utf8") <= 8192, {
+            message: "body exceeds 8192 UTF-8 bytes",
+        })
+            .describe("Reply body, ≤8KB UTF-8. Verbatim."),
+        wake: z
+            .enum(["off", "auto"])
+            .optional()
+            .describe('Wake strategy, same semantics as send_message. Unset: wake-on-reply default (auto-wakes a freshly-idle requester when the inbound was an ask_peer). "auto": nudge any idle peer. "off": no nudge.'),
+    },
+}, async ({ message_id, body, wake }) => {
+    const myId = entry.client.session_id;
+    if (!myId) {
+        return jsonResult({
+            schema_version: 1,
+            ok: false,
+            error: "no-session-id",
+            message: "This session has not claimed a session_id, so it has no received-ledger to reply from. Call claim_session first.",
+        });
+    }
+    const inbound = received.lookupReceived(myId, message_id);
+    if (!inbound) {
+        return jsonResult({
+            schema_version: 1,
+            ok: false,
+            error: "message-not-found",
+            message: `No received message ${message_id} in this session's ledger (it may have aged out of retention, or predates reply_to_message). Fall back to send_message with an explicit target.`,
+        });
+    }
+    const targetSid = inbound.from_session_id;
+    if (!targetSid) {
+        return jsonResult({
+            schema_version: 1,
+            ok: false,
+            error: "no-reply-target",
+            message: `Inbound message ${message_id} has no from_session_id, so there is no peer to reply to.`,
+        });
+    }
+    const replyTo = inbound.request_id; // undefined when the inbound was a plain send_message
+    const resolved = resolveTarget(targetSid, entry);
+    if (!resolved.ok) {
+        const replyDefault = replyAutoWakeTriggered(wake, replyTo);
+        const wakeIntended = wake === "auto" || replyDefault;
+        const wake_status = wakeIntended ? resolveErrorWakeStatus(resolved.error) : undefined;
+        return jsonResult({
+            schema_version: 1,
+            ...resolved,
+            in_reply_to_message_id: message_id,
+            original_from_session_id: targetSid,
+            ...(wake_status ? { wake_status } : {}),
+            ...(replyDefault ? { wake_reason: "reply_to_default" } : {}),
+        });
+    }
+    const peer = resolved.entry;
+    const fromSessionId = entry.client.session_id ?? undefined;
+    // Record the reply itself into the original asker's ledger (record-before-
+    // append) so replies can be replied to in turn — chained correlation.
+    const msg = deliverToPeer(peer.client.session_id, peer.server_pid, body, fromSessionId, {
+        reply_to: replyTo,
+        source_message_id: message_id,
+    });
+    const { wake_status, wake_reason } = await resolveSendWake(peer, wake, replyTo);
+    if (wake_status) {
+        trace("wake_outcome", {
+            via: wake_reason === "reply_to_default" ? "reply_default" : "reply_to_message",
+            wake_status,
+            target_session_id: peer.client.session_id,
+            client_type: peer.client.type,
+        });
+    }
+    return jsonResult({
+        schema_version: 1,
+        ok: true,
+        message_id: msg.id,
+        in_reply_to_message_id: message_id,
+        target_session_id: peer.client.session_id,
+        target_server_pid: peer.server_pid,
+        correlation: replyTo ? "correlated" : "uncorrelated",
+        ...(wake_status ? { wake_status } : {}),
+        ...(wake_reason ? { wake_reason } : {}),
+    });
+});
 // read_my_messages budget. A session's union drain can return a backlog; cap
 // how much one call hands back so a flood (or a peer spamming near-8KB bodies)
 // can't blow the caller's context in a single drain. Overflow is NOT dropped or
@@ -1251,11 +1364,11 @@ function askPeerDelay(ms, signal) {
 // 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).
+// askPeerWakeImpl keeps a generic pane→sessionName retry for its own unit
+// tests, but PRODUCTION wakePeer now passes only the process-tree-verified pane
+// (sessionName = null): a self-written tmux_session is not a trustworthy
+// send-keys target (issue #6), and pane-id churn is handled by re-resolving the
+// pane from server_pid on every wake rather than by a session fallback.
 async function defaultFireWakeKeystrokes(target, clientType) {
     execFileSync("tmux", ["send-keys", "-t", target, "-l", ASK_PEER_WAKE_TEXT], {
         stdio: ["ignore", "pipe", "pipe"],
@@ -1302,46 +1415,61 @@ export async function askPeerWakeImpl(pane, sessionName, fire) {
 // 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."
+// In-memory per-process wake-debounce state, keyed by peer session_id. Coalesces
+// rapid repeat wakes to the same peer across all wake paths (issue #5).
+const wakeDebounce = newWakeDebounceStore();
 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 (!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", {
+    // #5: coalesce a rapid repeat wake to the same peer (concurrent/retried
+    // ask_peer, polling loops) so we don't stack a second notification line into
+    // its composer. Keyed on session_id; an unclaimed peer (no id) isn't debounced.
+    const sid = peer.client.session_id;
+    if (sid && recentlyWoke(wakeDebounce, sid, Date.now())) {
+        trace("ask_peer_wake_skipped", { reason: "debounced", target_session_id: sid });
+        return "skipped_debounced";
+    }
+    // Security (#6): tmux_pane / tmux_session come from the peer's OWN registry
+    // file, so a malicious local peer could point them at someone else's pane or
+    // session to redirect our wake keystrokes. The ONLY trustworthy send-keys
+    // target is the pane the live process tree says currently hosts the peer's
+    // server_pid — chooseVerifiedWakePane resolves that and refuses (returns null)
+    // when it can't be verified, instead of falling back to the self-written
+    // cached pane or tmux_session. This also subsumes the old stale-pane re-
+    // resolution race fix: we ALWAYS use the freshly process-tree-resolved pane.
+    const verifiedPane = chooseVerifiedWakePane(peer);
+    if (!verifiedPane) {
+        trace("ask_peer_wake_skipped", {
+            reason: "no-verified-pane",
             cached: peer.tmux_pane,
-            live: livePane,
             server_pid: peer.server_pid,
+            target_session_id: peer.client.session_id,
         });
+        return "skipped_no_target";
     }
-    else if (peer.tmux_pane && !livePane) {
-        trace("ask_peer_wake_pane_orphaned", {
+    if (verifiedPane !== peer.tmux_pane) {
+        trace("ask_peer_wake_pane_refreshed", {
             cached: peer.tmux_pane,
+            live: verifiedPane,
             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);
+    // #5: stamp the debounce BEFORE the (possibly async, paste-burst-delayed) fire
+    // so a concurrent second wakePeer for this peer — which runs while we're
+    // awaiting send-keys — sees the stamp and coalesces instead of double-firing.
+    if (sid)
+        markWoke(wakeDebounce, sid, Date.now());
+    // No session-name fallback: a self-written tmux_session could target another
+    // session, and the verified pane already handles pane-id churn. Pass null.
+    const ok = await askPeerWakeImpl(verifiedPane, null, fire);
     return ok ? "fired" : "skipped_no_target";
 }
 // --- send_message wake:auto gating -------------------------------------------
@@ -1528,7 +1656,9 @@ server.registerTool("ask_peer", {
     const requestId = randomBytes(8).toString("hex");
     const requireReplyTo = peerSupportsReplyTo(peer);
     const fromSessionId = entry.client.session_id ?? undefined;
-    const msg = mailbox.enqueue(peer.server_pid, body, fromSessionId, {
+    // Record-before-append (mirrors send_message): lets the peer answer with
+    // reply_to_message(message_id) instead of hand-wiring target + reply_to.
+    const msg = deliverToPeer(expectedSessionId, peer.server_pid, body, fromSessionId, {
         request_id: requestId,
     });
     const startedAt = Date.now();
@@ -1562,6 +1692,12 @@ server.registerTool("ask_peer", {
             // send_message wake:auto. (Codex has no activity file, so it is never
             // detected busy and still fires — unchanged for that client.)
             wakeStatus = await wakeForSend(peer);
+            trace("wake_outcome", {
+                via: "ask_peer",
+                wake_status: wakeStatus,
+                target_session_id: peer.client.session_id,
+                client_type: peer.client.type,
+            });
             if (wakeStatus === "skipped_unsupported") {
                 // Reserved branch. No client currently returns skipped_unsupported
                 // in auto mode (Codex and Claude Code both wake via send-keys).

package/dist/wake-debounce.js

@@ -0,0 +1,45 @@
+// Issue #5 — per-peer wake debouncer.
+//
+// Every wake fires `tmux send-keys` into the peer's composer. When the same peer
+// is woken again within a fraction of a second — a caller retrying ask_peer, two
+// callers targeting the same peer concurrently, or a polling loop — oxtail blasts
+// a second WAKE_TEXT line on top of the first, which (with the Codex paste-burst
+// gap) can land inside an already-active turn. This debouncer coalesces those:
+// if a wake fired for a peer within a short window, subsequent wakes are skipped
+// and rely on the still-pending response.
+//
+// Deliberately in-memory and per-process (state lives on the calling oxtail
+// server): the common burst — one caller hammering one peer — is same-process,
+// and cross-process coordination is out of scope for this slice. All wake paths
+// (ask_peer, send_message wake:"auto", the reply-default wake) funnel through
+// wakePeer, so one check there covers them all.
+function envPosInt(name, def, env = process.env) {
+    const v = env[name];
+    if (!v)
+        return def;
+    const n = Number(v);
+    return Number.isFinite(n) && n > 0 ? n : def;
+}
+// Default 1s — long enough to swallow a rapid retry / concurrent double-wake,
+// short enough that a genuinely separate follow-up wake a moment later still
+// lands. Tunable via OXTAIL_WAKE_DEBOUNCE_MS.
+export const WAKE_DEBOUNCE_MS = envPosInt("OXTAIL_WAKE_DEBOUNCE_MS", 1000);
+export function newWakeDebounceStore() {
+    return new Map();
+}
+// True if a wake fired for this key within the window — i.e. skip this one.
+export function recentlyWoke(store, key, nowMs, windowMs = WAKE_DEBOUNCE_MS) {
+    const last = store.get(key);
+    return last !== undefined && nowMs - last < windowMs;
+}
+// Record that a wake fired for this key. Opportunistically evicts stale entries
+// so the map can't grow unbounded across many short-lived peers.
+export function markWoke(store, key, nowMs, windowMs = WAKE_DEBOUNCE_MS) {
+    store.set(key, nowMs);
+    if (store.size > 256) {
+        for (const [k, t] of store) {
+            if (nowMs - t > windowMs * 10)
+                store.delete(k);
+        }
+    }
+}

package/package.json

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

package/scripts/check-codex-paste-burst.mjs

@@ -0,0 +1,63 @@
+#!/usr/bin/env node
+// Issue #7 — drift detector for Codex's paste-burst window.
+//
+// oxtail's Codex wake inserts a 500ms gap (ASK_PEER_CODEX_SUBMIT_DELAY_MS)
+// between the typed wake text and Enter, to outlast Codex's paste-burst
+// PASTE_ENTER_SUPPRESS_WINDOW — a private constant tested at 120ms. If Codex
+// bumps that window past our gap in a future release, our wake silently
+// regresses to "Enter gets swallowed" with no signal pointing at the cause.
+//
+// This script fetches the upstream constant and exits non-zero if it changed
+// (or moved/renamed). Run on a schedule (see .github/workflows/codex-drift.yml)
+// so drift surfaces as a failing job rather than a silent field regression.
+
+const URL =
+  "https://raw.githubusercontent.com/openai/codex/main/codex-rs/tui/src/bottom_pane/paste_burst.rs";
+const EXPECTED_MS = 120; // value oxtail's 500ms gap was verified against
+const OUR_GAP_MS = 500; // ASK_PEER_CODEX_SUBMIT_DELAY_MS in src/server.ts
+
+async function fetchSource(attempts = 3) {
+  let lastErr;
+  for (let i = 0; i < attempts; i++) {
+    try {
+      const res = await fetch(URL);
+      if (res.ok) return await res.text();
+      lastErr = new Error(`HTTP ${res.status}`);
+    } catch (e) {
+      lastErr = e;
+    }
+    await new Promise((r) => setTimeout(r, 1000 * (i + 1)));
+  }
+  throw lastErr;
+}
+
+let src;
+try {
+  src = await fetchSource();
+} catch (e) {
+  console.error(`drift-check: could not fetch paste_burst.rs (${e?.message ?? e}). Transient — re-run.`);
+  process.exit(2);
+}
+
+const m = src.match(/PASTE_ENTER_SUPPRESS_WINDOW[\s\S]{0,120}?from_millis\((\d+)\)/);
+if (!m) {
+  console.error(
+    "drift-check: PASTE_ENTER_SUPPRESS_WINDOW / from_millis(...) not found upstream — Codex may have renamed or restructured the paste-burst logic. Re-verify oxtail's Codex wake gap (ASK_PEER_CODEX_SUBMIT_DELAY_MS) by hand.",
+  );
+  process.exit(1);
+}
+
+const ms = Number(m[1]);
+if (ms !== EXPECTED_MS) {
+  const stillSafe = ms < OUR_GAP_MS;
+  console.error(
+    `drift-check: PASTE_ENTER_SUPPRESS_WINDOW changed ${EXPECTED_MS}ms -> ${ms}ms. ` +
+      `oxtail's gap is ${OUR_GAP_MS}ms — ` +
+      (stillSafe
+        ? "still larger, so wake should still submit, but update EXPECTED_MS here once re-verified."
+        : "NO LONGER LARGER: Codex wake will regress (Enter swallowed). Bump ASK_PEER_CODEX_SUBMIT_DELAY_MS in src/server.ts."),
+  );
+  process.exit(1);
+}
+
+console.log(`drift-check: PASTE_ENTER_SUPPRESS_WINDOW still ${ms}ms; oxtail gap ${OUR_GAP_MS}ms — OK.`);