oxtail 0.10.3 → 0.11.0

package/AGENTS.md

@@ -58,6 +58,7 @@ The v0.9/v0.10.1 changes close the public dogfooding gaps found by real peer tra
 
 ## Recently shipped
 
+- **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

@@ -65,7 +65,7 @@ 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`.
@@ -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.
 

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/server.js

@@ -13,6 +13,7 @@ import { trace } from "./trace.js";
 import { buildEntry, currentPaneForServerPid, 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";
 // 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(...)`
@@ -1002,7 +1003,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_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 +1021,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 +1036,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 +1052,7 @@ 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);
     return jsonResult({
         schema_version: 1,
         ok: true,
@@ -1056,6 +1060,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
@@ -1376,6 +1381,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

package/package.json

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