oxtail 0.10.3 → 0.12.0

package/AGENTS.md

@@ -58,6 +58,8 @@ The v0.9/v0.10.1 changes close the public dogfooding gaps found by real peer tra
 
 ## Recently shipped
 
+- **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.
 - **Per-client wake routing (v0.7, refined).** `ask_peer` routes its wake mechanism per `client_type`. **Codex**: paste-burst-aware send-keys (500ms gap between text and Enter) — verified to submit. **Claude Code**: same send-keys mechanism without the gap (no paste-burst in its TUI) — verified end-to-end 2026-05-13 against `oxtail-claudejr`. v0.7 originally fail-fasted Claude Code targets under a hook-catalog argument; the follow-up restored symmetric wake after falsifying that conclusion empirically. Response includes 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.

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.12.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.12.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.12.0/integrations/codex/oxtail-join/agents/openai.yaml \
   -o ~/.codex/skills/oxtail-join/agents/openai.yaml
 ```
 
@@ -65,13 +65,13 @@ 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. Transcript reads are **budgeted** so a casual read can't blow your context window: by default the last 20 messages and ~24KB of text (newest-first), per-message ISO timestamps omitted. `count_truncated` / `bytes_truncated` say which budget bit; raise `limit` + `max_bytes` to pull more, set `include_timestamps: true` to keep timestamps, and pass `tail_scan: true` to read the file tail without parsing the whole transcript (qualifies `total_messages` via `total_messages_exact`).
 - `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. Target is a tmux session name or a raw `client_session_id` UUID. Body ≤ 8KB. Delivery is async via the peer's mailbox file. By default 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`. (v0.5+)
+- `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+)
 - `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.12.0/AGENTS.md) for scope and architecture.
 
 ## Usage from an agent
 
@@ -147,7 +147,18 @@ send_message({ target: "<peer>", body: "...", wake: "auto" })
 // → { ok: true, message_id, ..., wake_status: "fired" | "skipped_busy" | "skipped_no_target" | "disabled" }
 ```
 
-It is **state-gated** off the activity flag above: if the peer is mid-turn (`busy`), the wake is skipped (`skipped_busy`) because its PreToolUse/Stop hooks will deliver during the turn — no point typing into a busy composer. Idle, unknown (hooks not installed), or stale-busy peers get a per-client `tmux send-keys` wake (Codex gets the paste-burst-aware gap; Claude Code does not). `wake: "off"` (the default) preserves the pure fire-and-forget contract.
+It is **state-gated** off the activity flag above: if the peer is mid-turn (`busy`), the wake is skipped (`skipped_busy`) because its PreToolUse/Stop hooks will deliver during the turn — no point typing into a busy composer. Idle, unknown (hooks not installed), or stale-busy peers get a per-client `tmux send-keys` wake (Codex gets the paste-burst-aware gap; Claude Code does not). `wake: "off"` preserves the pure fire-and-forget contract.
+
+**Wake-on-reply (the default for replies).** A reply — a `send_message` that carries `reply_to` — auto-wakes the requester **by default**, so an awaited answer doesn't strand an idle peer and force a human to relay it. You don't have to remember `wake: "auto"`; pass `wake: "off"` to opt out.
+
+```js
+send_message({ target: "<requester>", body: "...", reply_to: "<request_id>" })
+// → { ok: true, ..., wake_status: "...", wake_reason: "reply_to_default" }
+```
+
+The reply path is deliberately **stricter** than explicit `wake: "auto"`. It fires only when the target is **freshly idle** — an `idle` activity marker newer than `OXTAIL_AUTOWAKE_FRESH_IDLE_MS` (default 5 min). Stale, unknown, missing, or busy state yields `skipped_no_fresh_idle` (no best-effort wake — typing unprompted into a terminal that may be unattended is the risk we refuse to take). Two more guards bound it: a **per-target rate limit** (`OXTAIL_AUTOWAKE_MIN_INTERVAL_MS`, default 4s → `skipped_rate_limited`) since one wake already drains the whole mailbox, and a **one-wake dedupe** keyed on `(session_id, reply_to)` (`skipped_deduped`) so a duplicate or late hook drain of the same reply can't re-fire. If the dedupe/rate store is somehow unwritable the wake degrades to `skipped_store_error` rather than failing the (already-delivered) message. The env kill-switch `OXTAIL_AUTOWAKE=off` disables reply auto-wake entirely (`wake_status: "disabled"`). Every outcome that reaches the gate surfaces a `wake_status`; the reply path also stamps `wake_reason: "reply_to_default"` (present even on a resolve error like `ambiguous-target`, where there's no single target to wake).
+
+**Coverage (which requesters this reaches).** The fresh-idle gate keys on the requester's busy/idle activity marker, which only the Claude Code hooks maintain. So wake-on-reply currently closes the stranding for a **hooked Claude Code requester** (the originally-observed case: a peer's async reply to an idle Claude session). A **Codex** requester — or a Claude requester without the hooks installed — has no idle marker, so a reply with `wake` unset returns `skipped_no_fresh_idle` and is **not** auto-woken; reach it with an explicit `wake: "auto"`, which always takes the lenient wake path (idle/unknown/stale all wake; only a fresh-`busy` peer is skipped) and bypasses the strict fresh-idle gate even for a reply. Closing the Codex/unhooked-requester direction *by default* needs a requester-side waiter signal (`expects_reply`), which is the next slice — a blind `unknown ⇒ wake` default is deliberately avoided because it reintroduces the double-wake-an-active-waiter risk this gate exists to prevent.
 
 **Codex and the wake matrix.** The send-keys wake needs a tmux pane. A Codex peer running **outside tmux** has none, so it returns `wake_status: "skipped_no_target"` — its idle delivery stays poll-based (`read_my_messages`). Run Codex **inside a tmux pane** to get symmetric idle-wake; the routing already handles the Codex paste-burst case.
 
@@ -161,6 +172,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:
@@ -171,7 +184,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,
@@ -179,7 +192,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.
 
@@ -209,9 +222,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
 
@@ -270,10 +287,24 @@ 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.12.0. Pushes the autonomous peer-messaging matrix toward zero human relay, then hardens the wake path.
 
+- **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/autowake.js

@@ -0,0 +1,238 @@
+// Slice 1 — wake-on-reply (interim liveness patch).
+//
+// When a `send_message` carries a `reply_to` (i.e. it is answering an earlier
+// ask) and the caller did NOT explicitly pass `wake:"off"`, oxtail auto-wakes
+// the original requester so an awaited answer doesn't strand an idle peer and
+// force a human relay. This module is the GATE that decides whether that
+// reply-default wake is allowed to fire. The actual send-keys is left to the
+// caller (server.ts `wakePeer`) so this module stays free of tmux/process
+// concerns and is unit-testable against a temp directory.
+//
+// The guards are deliberately conservative. A reply auto-wake types into the
+// peer's terminal WITHOUT the human at that terminal having asked for anything
+// this turn, so we only do it when ALL of these hold:
+//   1. kill-switch `OXTAIL_AUTOWAKE` is not "off"
+//   2. the target is FRESH-IDLE — its activity marker says "idle" AND is newer
+//      than a max-age threshold. Stale / unknown / missing ⇒ no wake (we do NOT
+//      fall back to a best-effort wake the way the lenient wake:auto path does).
+//   3. we have not woken this target too recently (per-target rate limit)
+//   4. we have not already woken for THIS exact (session_id, reply_to) — a
+//      one-wake dedupe that survives duplicate / late hook drains.
+//
+// Everything is keyed on the target's `client.session_id` (the agent identity,
+// per AGENTS.md), never server_pid / tmux name.
+import { createHash } from "node:crypto";
+import { closeSync, mkdirSync, openSync, readdirSync, statSync, unlinkSync, utimesSync, writeFileSync, } from "node:fs";
+import { homedir } from "node:os";
+import { join } from "node:path";
+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;
+}
+// Fresh-idle window: how recently the peer must have gone idle for a reply
+// auto-wake to fire. This is the MAX-AGE threshold the spec calls for, and it
+// is intentionally a SEPARATE, stricter gate than the 10-minute busy-TTL used
+// by the lenient `wake:"auto"` path: that path wakes on idle/unknown/stale, but
+// a reply auto-wake fires unprompted, so we cap how old "idle" may be before we
+// stop trusting that the peer is still sitting at its prompt. The 5-minute
+// default leans conservative (an unprompted wake into a possibly-unattended
+// terminal is the risk) while still covering a normal minute-scale
+// ask→work→reply round-trip; raise it via OXTAIL_AUTOWAKE_FRESH_IDLE_MS if
+// dogfooding shows replies regularly land later.
+export const FRESH_IDLE_MAX_AGE_MS = envPosInt("OXTAIL_AUTOWAKE_FRESH_IDLE_MS", 5 * 60 * 1000);
+// Per-target rate limit: the minimum gap between two reply auto-wakes to the
+// same session_id. A single recent wake already pulls an idle peer into a turn
+// that drains its whole mailbox, so additional keystroke wakes inside this
+// window are redundant noise into a terminal. Conservative by design.
+export const MIN_INTERVAL_MS = envPosInt("OXTAIL_AUTOWAKE_MIN_INTERVAL_MS", 4000);
+// One-wake dedupe lifetime: how long a (session_id, reply_to) wake record is
+// honored before it is GC'd. Comfortably longer than any single ask/reply
+// round-trip so a late/duplicate hook drain of the same reply can't re-wake.
+export const DEDUPE_TTL_MS = envPosInt("OXTAIL_AUTOWAKE_DEDUPE_TTL_MS", 60 * 60 * 1000);
+// The kill-switch. Any casing of "off" disables reply auto-wake entirely.
+export function autowakeKillSwitchOff(env = process.env) {
+    return String(env.OXTAIL_AUTOWAKE ?? "").trim().toLowerCase() === "off";
+}
+// FRESH-IDLE gate. Only a recent "idle" marker qualifies. A negative age means
+// the activity file's mtime is in the future (clock skew) — untrusted, treated
+// as not-fresh.
+export function isFreshIdle(act, maxAgeMs = FRESH_IDLE_MAX_AGE_MS) {
+    if (!act || act.status !== "idle")
+        return false;
+    return act.ageMs >= 0 && act.ageMs < maxAgeMs;
+}
+// --- persistent dedupe / rate-limit store ------------------------------------
+// One small file per record under ~/.oxtail/autowake/. mtime is the source of
+// truth (driven by the injected nowMs so the store is deterministic in tests);
+// the body is a debug breadcrumb. GC'd by age.
+export function defaultAutowakeDir() {
+    return join(homedir(), ".oxtail", "autowake");
+}
+function hash(s) {
+    // reply_to is caller-controlled, so never build a filename from it directly.
+    return createHash("sha256").update(s).digest("hex").slice(0, 32);
+}
+function dedupePath(dir, sessionId, replyTo) {
+    // JSON-encode the pair so the boundary is unambiguous: reply_to is
+    // caller-controlled and could otherwise be crafted to collide with a
+    // different (sessionId, replyTo) split under a plain separator.
+    return join(dir, `d-${hash(JSON.stringify([sessionId, replyTo]))}`);
+}
+function ratePath(dir, sessionId) {
+    return join(dir, `r-${hash(sessionId)}`);
+}
+function setMtime(path, nowMs) {
+    const t = nowMs / 1000;
+    try {
+        utimesSync(path, t, t);
+    }
+    catch {
+        // best effort — mtime drives TTL math, but a failure here only makes the
+        // record look fresher/staler by the small real-vs-injected clock delta.
+    }
+}
+// Read-only: has a wake for this (session_id, reply_to) happened within the TTL?
+export function isDuplicateWake(dir, sessionId, replyTo, nowMs, ttlMs = DEDUPE_TTL_MS) {
+    try {
+        const st = statSync(dedupePath(dir, sessionId, replyTo));
+        return nowMs - st.mtimeMs < ttlMs;
+    }
+    catch {
+        return false;
+    }
+}
+// Read-only: have we woken this target within the min-interval window?
+export function isRateLimited(dir, sessionId, nowMs, minIntervalMs = MIN_INTERVAL_MS) {
+    try {
+        const st = statSync(ratePath(dir, sessionId));
+        return nowMs - st.mtimeMs < minIntervalMs;
+    }
+    catch {
+        return false;
+    }
+}
+function stampRate(dir, sessionId, nowMs) {
+    const p = ratePath(dir, sessionId);
+    try {
+        writeFileSync(p, String(nowMs));
+        setMtime(p, nowMs);
+    }
+    catch {
+        // best effort
+    }
+}
+// Atomically claim the (session_id, reply_to) wake slot. Returns true if THIS
+// caller won (no fresh record existed) and may proceed to fire; false if a
+// concurrent / duplicate claim already holds it. On a win, also stamps the
+// per-target rate record so distinct replies inside MIN_INTERVAL_MS are
+// suppressed. A stale record (older than TTL) is cleared first so the slot can
+// be reclaimed after the GC horizon.
+export function claimWake(dir, sessionId, replyTo, nowMs, ttlMs = DEDUPE_TTL_MS) {
+    mkdirSync(dir, { recursive: true });
+    const dpath = dedupePath(dir, sessionId, replyTo);
+    try {
+        const st = statSync(dpath);
+        if (nowMs - st.mtimeMs >= ttlMs)
+            unlinkSync(dpath);
+    }
+    catch (e) {
+        // ENOENT = no prior record (the common path) → fine. Any OTHER error (e.g.
+        // failing to unlink a STALE record because the store is unhealthy) must
+        // propagate so the caller degrades to skipped_store_error — otherwise the
+        // imminent openSync("wx") EEXIST on the un-removed stale record would be
+        // misreported as a genuine dedupe hit.
+        if (e.code !== "ENOENT")
+            throw e;
+    }
+    let won = false;
+    try {
+        const fd = openSync(dpath, "wx"); // atomic create-exclusive: closes the race
+        try {
+            writeFileSync(fd, JSON.stringify({ sessionId, replyTo, at: nowMs }));
+        }
+        finally {
+            closeSync(fd);
+        }
+        setMtime(dpath, nowMs);
+        won = true;
+    }
+    catch (e) {
+        // EEXIST: a fresh claim already exists → genuine duplicate (skip, no throw).
+        // Any OTHER error means the store itself is unusable (e.g. a permission
+        // problem) — don't misreport it as a duplicate; rethrow so the caller can
+        // degrade it to a deterministic store-error status instead of silently
+        // suppressing a legitimate wake.
+        if (e.code === "EEXIST") {
+            won = false;
+        }
+        else {
+            throw e;
+        }
+    }
+    if (won)
+        stampRate(dir, sessionId, nowMs);
+    return won;
+}
+// Remove autowake records older than the dedupe TTL. Cheap, low-volume dir;
+// run opportunistically on each decision so records can't accumulate.
+export function gcAutowake(dir, nowMs, ttlMs = DEDUPE_TTL_MS) {
+    let names;
+    try {
+        names = readdirSync(dir);
+    }
+    catch {
+        return; // dir not created yet
+    }
+    for (const name of names) {
+        if (name[0] !== "d" && name[0] !== "r")
+            continue;
+        const p = join(dir, name);
+        try {
+            const st = statSync(p);
+            if (nowMs - st.mtimeMs >= ttlMs)
+                unlinkSync(p);
+        }
+        catch {
+            // best effort
+        }
+    }
+}
+// The decision. Pure of tmux/process concerns: given the target identity, the
+// reply_to, a snapshot of the target's activity, the current time, and the
+// store directory, return whether the reply-default wake may fire. The caller
+// performs the actual send-keys when fire === true.
+export function decideReplyAutoWake(input) {
+    const { dir, sessionId, replyTo, activity, nowMs } = input;
+    if (autowakeKillSwitchOff(input.env))
+        return { fire: false, status: "disabled" };
+    // Identity is required: dedupe/rate/activity all key on session_id, and
+    // without it we cannot confirm fresh-idle. An unclaimed peer is never auto-woken.
+    if (!sessionId)
+        return { fire: false, status: "skipped_no_fresh_idle" };
+    if (!isFreshIdle(activity))
+        return { fire: false, status: "skipped_no_fresh_idle" };
+    // Wake bookkeeping is best-effort: send_message has ALREADY enqueued the
+    // reply by the time we run, so a broken dedupe/rate store (e.g. ~/.oxtail/
+    // autowake is a file, or a permission error) must degrade to a deterministic
+    // status — NEVER throw, which would surface as a tool error on an already-
+    // delivered message and invite a duplicate retry.
+    try {
+        gcAutowake(dir, nowMs); // opportunistic sweep before we read/claim
+        // Read-only dedupe first so a sequential duplicate reply reports the precise
+        // reason; then the per-target rate limit; then an atomic claim to close the
+        // concurrent-duplicate race (and to stamp the rate record on success).
+        if (isDuplicateWake(dir, sessionId, replyTo, nowMs))
+            return { fire: false, status: "skipped_deduped" };
+        if (isRateLimited(dir, sessionId, nowMs))
+            return { fire: false, status: "skipped_rate_limited" };
+        if (!claimWake(dir, sessionId, replyTo, nowMs))
+            return { fire: false, status: "skipped_deduped" };
+    }
+    catch {
+        return { fire: false, status: "skipped_store_error" };
+    }
+    return { fire: true };
+}

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/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,9 +10,11 @@ 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 { 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(...)`
@@ -32,6 +34,10 @@ import { recoverClaim, resolveAncestors, writeClaim } from "./claims.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
@@ -1002,7 +1008,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.",
-        "By default 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). Response then carries wake_status: \"fired\" | \"skipped_busy\" | \"skipped_no_target\" | \"disabled\".",
+        "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: {
@@ -1020,7 +1026,7 @@ server.registerTool("send_message", {
         wake: z
             .enum(["off", "auto"])
             .optional()
-            .describe('Wake strategy. "off" (default): pure fire-and-forget, no nudge. "auto": nudge an idle peer via per-client send-keys, state-gated (skipped if the peer is mid-turn). Response carries wake_status when set.'),
+            .describe('Wake strategy. Default (unset): no nudge for a plain message, but a reply (reply_to set) auto-wakes a freshly-idle requester. "off": pure fire-and-forget, no nudge even for a reply. "auto": nudge an idle peer via per-client send-keys, state-gated (skipped if the peer is mid-turn). Response carries wake_status when set.'),
         reply_to: z
             .string()
             .min(1)
@@ -1035,11 +1041,14 @@ server.registerTool("send_message", {
 }, async ({ target, body, wake, reply_to, source_message_id }) => {
     const resolved = resolveTarget(target, entry);
     if (!resolved.ok) {
-        const wake_status = wake === "auto" ? resolveErrorWakeStatus(resolved.error) : undefined;
+        const replyDefault = replyAutoWakeTriggered(wake, reply_to);
+        const wakeIntended = wake === "auto" || replyDefault;
+        const wake_status = wakeIntended ? resolveErrorWakeStatus(resolved.error) : undefined;
         return jsonResult({
             schema_version: 1,
             ...resolved,
             ...(wake_status ? { wake_status } : {}),
+            ...(replyDefault ? { wake_reason: "reply_to_default" } : {}),
         });
     }
     const peer = resolved.entry;
@@ -1048,7 +1057,15 @@ server.registerTool("send_message", {
         reply_to,
         source_message_id,
     });
-    const wake_status = wake === "auto" ? await wakeForSend(peer) : undefined;
+    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,
@@ -1056,6 +1073,7 @@ server.registerTool("send_message", {
         target_session_id: peer.client.session_id,
         target_server_pid: peer.server_pid,
         ...(wake_status ? { wake_status } : {}),
+        ...(wake_reason ? { wake_reason } : {}),
     });
 });
 // read_my_messages budget. A session's union drain can return a backlog; cap
@@ -1246,11 +1264,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"],
@@ -1297,46 +1315,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 -------------------------------------------
@@ -1376,6 +1409,63 @@ async function wakeForSend(peer) {
     }
     return wakePeer(peer);
 }
+// --- Slice 1: wake-on-reply (reply_to default) -------------------------------
+// A send_message that carries a reply_to is answering an earlier ask. The wake
+// arg is a three-way for a reply:
+//   unset  → the STRICT reply-default auto-wake (fresh-idle only, rate limit,
+//            one-wake dedupe, env kill-switch — autowake.ts). wake_reason:
+//            "reply_to_default".
+//   "auto" → the caller explicitly opts into the LENIENT wakeForSend path
+//            (idle/unknown/stale all wake; only fresh-busy is skipped). This is
+//            the escape hatch for a requester with no idle marker — a Codex or
+//            hookless-Claude requester that the strict gate skips as
+//            skipped_no_fresh_idle. Not flagged reply_to_default: the caller
+//            asked for it explicitly.
+//   "off"  → no wake at all.
+// Here we just wire identity/activity/time into the strict gate and fire the
+// existing send-keys path when it says go.
+//
+// Note (per Codex's slice-1 correction): the fresh-idle gate makes an explicit
+// "is the requester actively blocked in ask_peer?" suppression unnecessary —
+// an active waiter is mid-turn and therefore marked busy, so it never reads as
+// fresh-idle. That holds only as long as the busy/idle freshness is correct;
+// it is not an independent proof.
+//
+// Triggers the STRICT reply-default path: a reply (reply_to set) with wake
+// UNSET. Explicit "auto"/"off" opt out of the strict path (auto → lenient,
+// off → none), so this is false for them.
+function replyAutoWakeTriggered(wake, replyTo) {
+    return !!replyTo && wake === undefined;
+}
+async function autoWakeOnReply(peer, replyTo) {
+    const sid = peer.client.session_id;
+    const decision = decideReplyAutoWake({
+        dir: defaultAutowakeDir(),
+        sessionId: sid ?? null,
+        replyTo,
+        activity: readActivity(sid),
+        nowMs: Date.now(),
+    });
+    if (!decision.fire) {
+        trace("autowake_reply_skipped", { target_session_id: sid, status: decision.status });
+        return decision.status;
+    }
+    trace("autowake_reply_fire", { target_session_id: sid });
+    return wakePeer(peer);
+}
+// Resolve the wake for a send_message. The strict reply-default path engages
+// only for a reply with wake UNSET; an explicit wake:"auto" always means the
+// lenient wakeForSend path (even for a reply — the Codex/hookless escape hatch),
+// and wake:"off" means no wake. Returns the status + reason to surface.
+async function resolveSendWake(peer, wake, replyTo) {
+    if (replyAutoWakeTriggered(wake, replyTo)) {
+        return { wake_status: await autoWakeOnReply(peer, replyTo), wake_reason: "reply_to_default" };
+    }
+    if (wake === "auto") {
+        return { wake_status: await wakeForSend(peer) };
+    }
+    return {};
+}
 // 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
 // mailbox lock when there's a probable hit. The lock is held only inside
@@ -1500,6 +1590,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.10.3",
+  "version": "0.12.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.`);