oxtail 0.4.0 → 0.6.0

package/AGENTS.md

@@ -17,15 +17,19 @@ Scope is **project-root as the unit**. Sessions in one project root see each oth
 - **Registry (leaning):** `tmux list-sessions` filtered by project-derived names, rather than a custom JSON registry. Free dead-session detection, free naming, no daemon to maintain. Decision pending real-use signals.
 - **Project scoping:** project root inferred from session CWD at agent startup.
 
-## Status: v0.4.0 shipped, dogfooding
+## Status: v0.6.0 shipped, dogfooding
 
-Six MCP tools live: `list_project_sessions`, `read_session`, `claim_session`, `set_my_state`, `register_my_session`, and `get_my_session`. Registered both project-locally (via `.mcp.json` using `tsx ./src/server.ts` for the dev loop) and globally (in `~/.claude.json` and `~/.codex/config.toml`, pointing at `dist/server.js`).
+Nine MCP tools live: `list_project_sessions`, `read_session`, `claim_session`, `set_my_state`, `register_my_session`, `get_my_session`, the v0.5 messaging pair `send_message` and `read_my_messages`, and the v0.6 delegate-and-wait primitive `ask_peer`. Registered both project-locally (via `.mcp.json` using `tsx ./src/server.ts` for the dev loop) and globally (in `~/.claude.json` and `~/.codex/config.toml`, pointing at `dist/server.js`).
 
 The v0.4.0 change: peer `client_session_id` and `transcript_path` now resolve reliably for Claude Code and Codex peers, even though Claude Code strips its session-id env var from MCP children. Detection layers in `src/detect/` — env, then birth-time fingerprint matching of transcript files, with a `claim_session` escape hatch (`register_my_session` is kept for debugging) — see `README.md` for details.
 
 The follow-on additions (`claim_session`, `set_my_state`) introduce a peer-awareness layer: `list_project_sessions` now surfaces each peer's `state` card so an agent can learn what its peers are doing without paying for `read_session`. Raw transcripts become the deep-dive fallback, not the default mode of peer awareness.
 
-Current phase remains **dogfooding**: use the tools in real parallel-agent work, log friction in `NOTES.md`. Each version (v1 list_project_sessions → v0.2 read_session → v0.3 reliable peer identity → v0.4 peer-awareness state cards) shipped only after observed friction named the next addition; the same gating applies to whatever comes next.
+Current phase remains **dogfooding**: use the tools in real parallel-agent work, log friction in `NOTES.md`. Each version (v0.1 list_project_sessions → v0.2 read_session → v0.3 reliable peer identity → v0.4 peer-awareness state cards → v0.5 peer-to-peer messaging → v0.6 delegate-and-wait) shipped only after observed friction named the next addition; the same gating applies to whatever comes next.
+
+The v0.5 change: two new MCP tools (`send_message`, `read_my_messages`) plus an opt-in `PreToolUse` hook installable via `npx oxtail install-hook`. Friction observed while pairing on Terminator — two agents in the same project root can see each other's state cards and transcripts but couldn't say anything to each other. Now they can. Claude Code peers see messages mid-turn (via the hook); Codex peers (or unhooked Claude Code) see them next-turn (via polling `read_my_messages`).
+
+The v0.6 change: one new MCP tool (`ask_peer`) that turns v0.5's async pings into synchronous delegate-and-wait. Friction observed while dogfooding v0.5 — `send_message` lets agents say things to each other, but the sender doesn't stay in-turn waiting for a reply, and an idle receiver doesn't get nudged. `ask_peer` blocks server-side until a reply with a matching `from_session_id` lands (or a fixed timeout elapses) and fires a `tmux send-keys` wake to rouse idle peers. The result: an agent talking to its user can delegate to a peer, exchange multiple rounds inside one of its own turns, and report back synthesized findings.
 
 ## How to collaborate on this project
 
@@ -41,9 +45,17 @@ Current phase remains **dogfooding**: use the tools in real parallel-agent work,
 3. **Both Claude Code and Codex CLI must work** with whatever we build. MCP is the cross-tool protocol; Skills are Claude-specific syntactic sugar that wraps MCP tools, never primary functionality.
 4. **Minimum viable first.** One MCP tool that's actually used > five speculative ones.
 
+## Recently shipped
+
+- **Delegate-and-wait (v0.6).** `ask_peer({ target, body })` blocks server-side until the peer replies (filtered by `from_session_id`) or a fixed timeout elapses, with a `tmux send-keys` wake fallback for idle peers. Late replies fall back to the v0.5 hook / poll delivery path. Target must have a registered `client.session_id`.
+- **Cross-session messaging (v0.5).** `send_message({ target, body })` + `read_my_messages()`. Mailbox lives at `~/.oxtail/mailboxes/<server_pid>.jsonl`, drained under an `mkdir`-based advisory lock. Opt-in PreToolUse hook (`npx oxtail install-hook`) for mid-turn delivery to Claude Code.
+
 ## Deliberately deferred
 
 - **Output capture** (vs. metadata only). Costs a wrapper layer (`script -F` or pty-mirror). Only worth doing if real friction shows metadata isn't enough.
-- **Cross-session messaging** (note from session A to session B). Probably useful eventually; not until real use names the shape.
+- **Codex mid-turn delivery.** Pending Codex CLI exposing a hook surface.
+- **Delivery receipts / read receipts.** Sender learns `{ ok: true, message_id }`; whether the recipient saw it is invisible. Add when real use names the shape.
+- **Broadcast / multi-recipient send_message.** 1:1 only in v0.5.
+- **Orphan mailbox cleanup.** Mailbox files for dead pids accumulate in `~/.oxtail/mailboxes/`. Tiny and harmless; revisit when real waste shows up in `du`.
 - **Skill set.** Decide after the first MCP tool exists and we know what it feels like to use raw.
 - **MCP tool naming.** Pick after observation tells us the verbs.

package/README.md

@@ -19,7 +19,7 @@ End users — paste into your MCP config and oxtail is fetched from npm on first
 **Claude Code** — add to `~/.claude.json` (global) or any project's `.mcp.json`:
 
 ```jsonc
-{ "mcpServers": { "oxtail": { "command": "npx", "args": ["-y", "oxtail@0.4.0"] } } }
+{ "mcpServers": { "oxtail": { "command": "npx", "args": ["-y", "oxtail@0.6.0"] } } }
 ```
 
 **Codex CLI** — add to `~/.codex/config.toml`:
@@ -27,14 +27,14 @@ End users — paste into your MCP config and oxtail is fetched from npm on first
 ```toml
 [mcp_servers.oxtail]
 command = "npx"
-args = ["-y", "oxtail@0.4.0"]
+args = ["-y", "oxtail@0.6.0"]
 ```
 
 **Claude slash command** (`/oxtail-join`):
 
 ```sh
 mkdir -p ~/.claude/commands
-curl -L https://raw.githubusercontent.com/d4j3y2k/oxtail/v0.4.0/.claude/commands/oxtail-join.md \
+curl -L https://raw.githubusercontent.com/d4j3y2k/oxtail/v0.6.0/.claude/commands/oxtail-join.md \
   -o ~/.claude/commands/oxtail-join.md
 ```
 
@@ -42,9 +42,9 @@ curl -L https://raw.githubusercontent.com/d4j3y2k/oxtail/v0.4.0/.claude/commands
 
 ```sh
 mkdir -p ~/.codex/skills/oxtail-register/agents
-curl -L https://raw.githubusercontent.com/d4j3y2k/oxtail/v0.4.0/integrations/codex/oxtail-register/SKILL.md \
+curl -L https://raw.githubusercontent.com/d4j3y2k/oxtail/v0.6.0/integrations/codex/oxtail-register/SKILL.md \
   -o ~/.codex/skills/oxtail-register/SKILL.md
-curl -L https://raw.githubusercontent.com/d4j3y2k/oxtail/v0.4.0/integrations/codex/oxtail-register/agents/openai.yaml \
+curl -L https://raw.githubusercontent.com/d4j3y2k/oxtail/v0.6.0/integrations/codex/oxtail-register/agents/openai.yaml \
   -o ~/.codex/skills/oxtail-register/agents/openai.yaml
 ```
 
@@ -59,14 +59,17 @@ Contributing? `git clone https://github.com/d4j3y2k/oxtail && cd oxtail && npm i
 
 ## MCP tools
 
-- `list_project_sessions` — tmux sessions in or under a given project root, enriched with `client_type`, `client_session_id`, and the peer's `state` card for oxtail-aware peers.
-- `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.
+- `list_project_sessions` — tmux sessions in or under a given project root, enriched with `client_type`, `client_session_id`, and the peer's `state` card. Returns **one row per registered agent** — rows may share `name` when peers share a tmux session (Terminator multi-window). Disambiguate via `client_session_id`.
+- `read_session` — the recent transcript of a peer session, as clean per-turn messages when the peer is oxtail-aware (Claude Code and Codex CLI), or as raw tmux pane text otherwise. Accepts a tmux session name OR a `client_session_id` UUID; an ambiguous tmux name returns `ambiguous-target` with the candidate UUIDs.
 - `claim_session` — single-shot session registration. The routine path: `Bash echo $CLAUDE_CODE_SESSION_ID` (or `$CODEX_THREAD_ID` for Codex) → `claim_session({ session_id })`. Returns `{ ok, session_id, transcript_path }`.
 - `set_my_state` — write a small "state card" onto this session's registry entry so peers can see what we're doing without reading our transcript. v1 surfaces a single field, `purpose` (≤200 chars).
+- `send_message` — **fire-and-forget** message to a peer. **Does NOT wake an idle peer** — use `ask_peer` for that. Target is a tmux session name or a raw `client_session_id` UUID. Body ≤ 8KB. Delivery is async via the peer's mailbox file. (v0.5+)
+- `read_my_messages` — drain this session's mailbox and return any queued messages. Codex peers (and unhooked Claude Code) poll this; Claude Code peers with the PreToolUse hook installed see messages mid-turn instead. (v0.5+)
+- `ask_peer` — **synchronous delegate-and-wait**. Wakes the peer via `tmux send-keys` and **blocks until they reply** (or the fixed timeout elapses, default 45s, tunable via `OXTAIL_ASK_PEER_TIMEOUT_MS`). Returns the peer's reply body. Use this for delegate-and-wait dynamics; use `send_message` for fire-and-forget. (v0.6+)
 - `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.4.0/AGENTS.md) for scope and architecture.
+See [design principles](https://github.com/d4j3y2k/oxtail/blob/v0.5.0/AGENTS.md) for scope and architecture.
 
 ## Usage from an agent
 
@@ -77,6 +80,12 @@ list_project_sessions({ project_root: "/path/to/project" })
 read_session({ name: "primary" })                    // auto: transcript if peer registered, else pane
 read_session({ name: "claude", mode: "transcript", limit: 50 })
 read_session({ name: "primary", mode: "pane", pane_lines: 500 })
+read_session({ name: "<peer-uuid>", mode: "transcript" })   // UUID form: needed when peers share a tmux session
+send_message({ target: "primary", body: "<system-reminder>checking in</system-reminder>" })
+send_message({ target: "<peer-uuid>", body: "..." })        // UUID form: same disambiguation
+read_my_messages()
+ask_peer({ target: "primary", body: "[Handoff] please audit X and tell me what you find" })
+  // → blocks server-side until the peer replies via send_message, then returns their body
 ```
 
 Omitting `project_root` triggers a best-effort `.git`-ancestor walk from the server's own cwd. The response includes `inferred: true` when this happens. Pass `project_root` explicitly when you can.
@@ -85,6 +94,101 @@ Omitting `project_root` triggers a best-effort `.git`-ancestor walk from the ser
 
 The cheapest way to learn what peers are doing is `list_project_sessions`. Each row carries an optional `state` card written by the peer via `set_my_state` — currently `{ purpose, updated_at }`. Reading the card costs almost nothing compared to `read_session`, which spends tokens on the full transcript. Use `read_session` when the card isn't enough.
 
+## Peer messaging (v0.5)
+
+Two MCP tools let peers in the same project root talk to each other:
+
+```
+send_message({ target: "<tmux-session-name OR client_session_id UUID>", body: "..." })
+  → { ok: true, message_id, target_session_id, target_server_pid }
+
+read_my_messages()
+  → { ok: true, drained: true, count, messages: [...] }
+```
+
+The mailbox lives at `~/.oxtail/mailboxes/<server_pid>.jsonl`, append-only JSONL, drained under an `mkdir`-based advisory lock. The transport is intentionally dumb: 8KB UTF-8 body cap, sender chooses the framing (raw text or pre-wrapped `<system-reminder>...</system-reminder>`).
+
+Cross-project sends are rejected, never silently dropped. Sending to a peer with the same tmux session name as another live peer returns `ambiguous-target` with the candidate `client_session_id`s — use the UUID form to disambiguate.
+
+### Mid-turn vs next-turn delivery (the asymmetry)
+
+Claude Code peers can receive messages **mid-turn** via an opt-in PreToolUse hook:
+
+```sh
+npx oxtail install-hook
+```
+
+This drops a small bash script at `~/.oxtail/hooks/pretooluse.sh` and adds a `hooks.PreToolUse` entry in `~/.claude/settings.json`. The hook reads each `PreToolUse` event's `session_id` from stdin, locates the matching mailbox, and emits `additionalContext` into the next tool-call boundary. Reverse with `npx oxtail uninstall-hook`.
+
+Codex CLI peers and any Claude Code session without the hook installed receive messages **next-turn** by calling `read_my_messages` explicitly. Both clients send messages identically. The asymmetry exists because Claude Code exposes a PreToolUse hook surface that injects `additionalContext`; Codex CLI does not currently expose an equivalent.
+
+**Caveat for Claude Code receivers:** PreToolUse fires only before a tool call. A turn that produces only text — no tool calls — never triggers the hook; messages enqueued during that turn surface on the next tool call (or via an explicit `read_my_messages`). For pair-debugging UX, senders should not assume mid-turn delivery is universal.
+
+### Hook coexistence
+
+The oxtail hook coexists with other `hooks.PreToolUse` entries. **Verified against Terminator's `_terminatorHook` v1 in Claude Code 2.1.139:** both hooks' `additionalContext` envelopes reached the model. Install order: Terminator first, oxtail second — `install-hook.mjs` appends to a non-empty array, which matches the verified configuration. If you reinstall hooks in a different order, you may need to re-test.
+
+If you have a PreToolUse hook installed that isn't from Terminator and isn't oxtail, `install-hook` prints a one-line note and proceeds — coexistence behavior with arbitrary third-party hooks is not pre-verified.
+
+### Trust model
+
+oxtail trusts any process running as the **same local user** to enqueue messages. The mailbox directory is mode `0o700` (private), so other users on the host cannot read or write. **On a shared-tenancy box (containers, multi-user dev hosts, etc.), do not run oxtail-aware agents:** any local process under your user can inject `<system-reminder>` content directly into a Claude session. The threat boundary is the same as `~/.ssh/` — what your user processes do, you trust.
+
+## Delegate-and-wait (v0.6)
+
+`ask_peer` extends v0.5's mailbox transport into a synchronous primitive:
+
+```
+ask_peer({ target, body })
+  → { ok: true, message_id, reply: { id, body, enqueued_at, from_session_id } | null, timed_out }
+```
+
+Mechanics:
+
+1. Enqueue `body` into the target's mailbox (same as `send_message`).
+2. Wait ~500ms for a hook-delivered reply (rare path — handles the case where the peer was already mid-tool-call and replied immediately).
+3. Fire a `tmux send-keys` wake against the peer's pane: a single literal line `[oxtail] new peer message — run mcp__oxtail__read_my_messages and respond via mcp__oxtail__send_message` followed by Enter. This nudges idle peers without requiring the human at the other end to type.
+4. Poll the caller's mailbox at 200ms for a reply with `from_session_id == target.session_id`. Other peers' messages stay in the mailbox untouched.
+5. Return the reply on match, or `{ reply: null, timed_out: true }` after the fixed timeout. Late replies fall back to the normal v0.5 hook / `read_my_messages` path — never lost, just delivered out of band.
+
+Constraints:
+
+- The target peer must have a registered `client.session_id`. Codex peers must call `claim_session` / `register_my_session` first; without that, `ask_peer` returns `error: "peer-has-no-session-id"` rather than guessing.
+- Timeout defaults to 45000ms (conservative under typical MCP-client tool-call abort windows). For longer dialogues, the calling agent chains multiple `ask_peer` calls in one turn rather than configuring a longer single block.
+- The wake is best-effort. If `tmux send-keys` fails against the cached pane id (Terminator-style window churn can leave the id stale), oxtail retries against the tmux session name (which targets the currently-active pane). If both fail, the peer may still respond on its own via polling — the only loss is the immediacy of the nudge.
+
+### Tuning the timeout
+
+If `ask_peer` returns an abort error before its built-in 45s timeout fires, your MCP client's tool-call ceiling is lower than 45s. Override the bound at server startup:
+
+```sh
+OXTAIL_ASK_PEER_TIMEOUT_MS=30000 npx -y oxtail@0.6.0
+```
+
+The server reads the env var once at boot and uses it as the fixed timeout for all `ask_peer` calls in that session. Values must be positive numbers; anything else falls back to the 45000ms default.
+
+### Recommended permissions for autonomous agent-to-agent collaboration
+
+The user-approval prompt on every `ask_peer` call interrupts the back-and-forth dynamic. To allow agents to initiate delegation without per-call prompts, add to `~/.claude/settings.json`:
+
+```jsonc
+{
+  "permissions": {
+    "allow": [
+      "mcp__oxtail__ask_peer",
+      "mcp__oxtail__send_message",
+      "mcp__oxtail__read_my_messages"
+    ]
+  }
+}
+```
+
+Without an allowlist, Claude Code prompts on first use of each MCP tool with an "always allow" option — pick that once per project to get the same effect.
+
+### Body framing
+
+Peers see the body verbatim. A handoff is naturally read as an assignment, not chat, when framed that way — include an objective and a requested next action. The repo doesn't ship a fixed envelope convention yet; convention will follow real use.
+
 ## Self-registration and the peer registry
 
 Each oxtail server, when spawned by an agent, writes a small record to `~/.oxtail/sessions/<pid>.json` containing the client type, session id, transcript path, and tmux pane. Sibling servers read this directory to find peer transcripts. Records auto-clean on process exit and on read (dead PIDs pruned). Sessions whose agents are not oxtail-aware (or are not LLM agents at all — bash, vim, vite dev servers) still show up in `list_project_sessions` and are readable via `read_session` in pane mode.
@@ -105,4 +209,4 @@ If `MCP_TRACE_FILE` is set in the environment, every detection run appends an ND
 
 ## Status
 
-v0.4.0. Reliable peer identity: `client_session_id` resolves automatically for Claude Code and Codex via filesystem fingerprint matching, with a self-register escape hatch for ambiguous cases. Project-local and global registrations both supported.
+v0.6.0. Adds `ask_peer` on top of v0.5's mailbox transport: an agent can send a message and block until the peer replies, with an automatic `tmux send-keys` wake for idle peers. Combined with the existing PreToolUse hook, two Claude Code sessions can now sustain a back-and-forth handoff inside a single turn of the delegating agent. Codex peers are supported as targets once they've claimed a session.

package/assets/pretooluse.sh

@@ -0,0 +1,120 @@
+#!/usr/bin/env bash
+# oxtail PreToolUse hook — delivers peer messages mid-turn to Claude Code.
+#
+# Reads ~/.oxtail/mailboxes/<my-server-pid>.jsonl, emits a hookSpecificOutput
+# envelope, and truncates the mailbox under lock. Pure bash + awk; no jq,
+# python, or node. Exits 0 on every error path so it never blocks a tool call.
+#
+# Step 0a verified that Claude Code strips CLAUDE_CODE_SESSION_ID from hook
+# subprocesses but delivers it via stdin JSON. Stdin is the only path; env
+# is dead code and not consulted here.
+
+set -u
+
+# 1. Read session_id from stdin JSON. Claude Code's PreToolUse contract
+#    delivers a single JSON line on stdin: {"session_id":"...", ...}. If
+#    stdin is a tty (interactive run), exit silently.
+sid=""
+if [ ! -t 0 ]; then
+  payload=$(cat 2>/dev/null || true)
+  sid=$(printf '%s' "$payload" | awk '
+    {
+      p = index($0, "\"session_id\":\"")
+      if (p == 0) next
+      rest = substr($0, p + 14)
+      out = ""
+      i = 1; n = length(rest)
+      while (i <= n) {
+        c = substr(rest, i, 1)
+        if (c == "\\") {
+          if (i+1 <= n) { out = out substr(rest, i, 2); i += 2 } else { i += 1 }
+        } else if (c == "\"") {
+          break
+        } else {
+          out = out c; i += 1
+        }
+      }
+      print out; exit
+    }
+  ')
+fi
+[ -z "$sid" ] && exit 0
+
+sessions_dir="$HOME/.oxtail/sessions"
+mailboxes_dir="$HOME/.oxtail/mailboxes"
+[ -d "$sessions_dir" ] || exit 0
+[ -d "$mailboxes_dir" ] || exit 0
+
+# 2. Find this session's MCP-server pid. Registry files are pretty-printed
+#    JSON (key/value separated by ": " with a space), so use grep -E with
+#    [[:space:]]* to tolerate either form. -F (fixed-string) is unsafe.
+entry_file=$(grep -lE "\"session_id\"[[:space:]]*:[[:space:]]*\"$sid\"" "$sessions_dir"/*.json 2>/dev/null | head -n 1) || true
+[ -z "$entry_file" ] && exit 0
+
+pid=$(basename "$entry_file" .json)
+case "$pid" in *[!0-9]*) exit 0 ;; esac
+
+mbox="$mailboxes_dir/$pid.jsonl"
+[ -f "$mbox" ] || exit 0
+[ -s "$mbox" ] || exit 0
+
+# 3. Acquire mkdir-based lock. Staleness window is 30s; matches
+#    src/mailbox.ts:LOCK_STALE_MS. We can't use `find -mmin +0.5` portably —
+#    BSD find and `bfs` reject fractional -mmin — so we read mtime via stat.
+#    GNU and BSD stat formats differ, so try both.
+LOCK_STALE_SECS=30
+acquired=0
+for i in $(seq 1 50); do
+  if mkdir "$mbox.lock" 2>/dev/null; then acquired=1; break; fi
+  now=$(date +%s 2>/dev/null || echo 0)
+  mtime=$(stat -c %Y "$mbox.lock" 2>/dev/null || stat -f %m "$mbox.lock" 2>/dev/null || echo 0)
+  if [ "$mtime" -gt 0 ] && [ $((now - mtime)) -gt "$LOCK_STALE_SECS" ]; then
+    rmdir "$mbox.lock" 2>/dev/null
+  fi
+  sleep 0.01
+done
+[ "$acquired" -eq 1 ] || exit 0
+
+# 4. Extract every line's body field (still JSON-encoded), join with literal
+#    \n\n separators, emit hookSpecificOutput envelope. Truncating happens
+#    after the awk completes; if awk's output never reaches Claude Code we'd
+#    rather have the messages still in the box than lost.
+output=$(awk '
+  BEGIN { count = 0 }
+  {
+    p = index($0, "\"body\":\"")
+    if (p == 0) next
+    rest = substr($0, p + 8)
+    out = ""
+    i = 1; n = length(rest)
+    while (i <= n) {
+      c = substr(rest, i, 1)
+      if (c == "\\") {
+        if (i + 1 <= n) { out = out substr(rest, i, 2); i += 2 } else { i += 1 }
+      } else if (c == "\"") {
+        break
+      } else {
+        out = out c
+        i += 1
+      }
+    }
+    bodies[count++] = out
+  }
+  END {
+    if (count == 0) exit 0
+    ctx = ""
+    for (j = 0; j < count; j++) {
+      if (j > 0) ctx = ctx "\\n\\n"
+      ctx = ctx bodies[j]
+    }
+    printf("{\"hookSpecificOutput\":{\"hookEventName\":\"PreToolUse\",\"additionalContext\":\"%s\"}}\n", ctx)
+  }
+' < "$mbox")
+
+if [ -n "$output" ]; then
+  printf '%s' "$output"
+  : > "$mbox"
+fi
+
+rmdir "$mbox.lock" 2>/dev/null || true
+exit 0

package/dist/mailbox.js

@@ -0,0 +1,242 @@
+import { randomBytes } from "node:crypto";
+import { appendFileSync, mkdirSync, readFileSync, rmdirSync, statSync, truncateSync, writeFileSync, } from "node:fs";
+import { homedir } from "node:os";
+import { join } from "node:path";
+import { trace } from "./trace.js";
+// Resolved lazily so tests can swap HOME between cases. Each call re-reads
+// homedir(), which on POSIX defers to $HOME.
+function mailboxesDir() {
+    return join(homedir(), ".oxtail", "mailboxes");
+}
+// Lock staleness window. The drainer reads the file, builds the JSON envelope,
+// and writes the truncate back to disk all under lock — under slow disks or OS
+// hiccups, a legitimate-but-slow drain can approach the original 5s threshold
+// and let a peer steal the lock. 30s widens the window to make accidental
+// theft very rare; the trade-off is that a genuinely crashed drainer holds the
+// lock 25s longer before recovery. Worth it.
+//
+// Sync this value with assets/pretooluse.sh (find -mmin +0.5 ≈ 30s).
+const LOCK_STALE_MS = 30_000;
+const LOCK_RETRY_LIMIT = 50;
+const LOCK_RETRY_DELAY_MS = 10;
+function mailboxPath(pid) {
+    return join(mailboxesDir(), `${pid}.jsonl`);
+}
+function lockPath(pid) {
+    return `${mailboxPath(pid)}.lock`;
+}
+function sleepSync(ms) {
+    const end = Date.now() + ms;
+    while (Date.now() < end) {
+        // tight spin — short enough (10ms) that this is acceptable
+    }
+}
+export function acquireLock(pid) {
+    mkdirSync(mailboxesDir(), { recursive: true, mode: 0o700 });
+    const lock = lockPath(pid);
+    for (let i = 0; i < LOCK_RETRY_LIMIT; i++) {
+        try {
+            mkdirSync(lock, { mode: 0o700 });
+            return;
+        }
+        catch (e) {
+            const err = e;
+            if (err.code !== "EEXIST")
+                throw err;
+            // Check staleness. If older than LOCK_STALE_MS, force-clear and retry.
+            try {
+                const st = statSync(lock);
+                if (Date.now() - st.mtimeMs > LOCK_STALE_MS) {
+                    try {
+                        rmdirSync(lock);
+                        trace("mailbox_lock_stale_clear", { pid });
+                    }
+                    catch {
+                        // raced with another clearer; fall through to retry
+                    }
+                    continue;
+                }
+            }
+            catch {
+                // stat may race; just retry
+            }
+            sleepSync(LOCK_RETRY_DELAY_MS);
+        }
+    }
+    throw new Error(`could not acquire mailbox lock for pid ${pid}`);
+}
+export function releaseLock(pid) {
+    try {
+        rmdirSync(lockPath(pid));
+    }
+    catch {
+        // ignore ENOENT / not-empty / EPERM
+    }
+}
+// Critical: the serialized JSONL line must always begin
+// `{"schema_version":1,"id":"...","body":"`. The awk extractor in
+// assets/pretooluse.sh assumes `"body":"` is the third key. A future refactor
+// that uses Object.assign / spread / inserts a key could silently reorder and
+// break the hook without breaking unit tests that don't check serialization.
+// The runtime regex below catches that.
+const FIELD_ORDER_PREFIX = /^\{"schema_version":1,"id":"[0-9a-f]{16}","body":"/;
+export function enqueue(target_pid, body, from_session_id) {
+    const msg = {
+        schema_version: 1,
+        id: randomBytes(8).toString("hex"),
+        body,
+        enqueued_at: Math.floor(Date.now() / 1000),
+        ...(from_session_id ? { from_session_id } : {}),
+    };
+    // Build the line by inserting keys in the invariant order. Node's
+    // JSON.stringify preserves insertion order for non-integer string keys,
+    // which the test suite pins.
+    const obj = {
+        schema_version: msg.schema_version,
+        id: msg.id,
+        body: msg.body,
+        enqueued_at: msg.enqueued_at,
+    };
+    if (from_session_id)
+        obj.from_session_id = from_session_id;
+    const line = JSON.stringify(obj) + "\n";
+    if (!FIELD_ORDER_PREFIX.test(line)) {
+        throw new Error(`mailbox enqueue: serialized line violates field-order invariant. ` +
+            `Got prefix: ${line.slice(0, 80)}`);
+    }
+    acquireLock(target_pid);
+    try {
+        appendFileSync(mailboxPath(target_pid), line);
+    }
+    finally {
+        releaseLock(target_pid);
+    }
+    return msg;
+}
+export function drain(my_pid) {
+    acquireLock(my_pid);
+    try {
+        let raw;
+        try {
+            raw = readFileSync(mailboxPath(my_pid), "utf8");
+        }
+        catch (e) {
+            const err = e;
+            if (err.code === "ENOENT")
+                return [];
+            throw err;
+        }
+        if (!raw)
+            return [];
+        const out = [];
+        for (const line of raw.split("\n")) {
+            if (!line)
+                continue;
+            let parsed;
+            try {
+                parsed = JSON.parse(line);
+            }
+            catch {
+                trace("mailbox_drain_skip_invalid", { pid: my_pid, line });
+                continue;
+            }
+            if (parsed &&
+                typeof parsed === "object" &&
+                parsed.schema_version === 1 &&
+                typeof parsed.id === "string" &&
+                typeof parsed.body === "string") {
+                out.push(parsed);
+            }
+            else {
+                trace("mailbox_drain_skip_invalid", { pid: my_pid, line });
+            }
+        }
+        try {
+            truncateSync(mailboxPath(my_pid), 0);
+        }
+        catch (e) {
+            const err = e;
+            if (err.code !== "ENOENT")
+                throw err;
+        }
+        return out;
+    }
+    finally {
+        releaseLock(my_pid);
+    }
+}
+// Drain the first message in this mailbox whose from_session_id matches
+// `from_session_id`, leaving any preceding and following messages untouched.
+// Used by ask_peer to consume exactly the reply it's waiting on without
+// stealing messages from concurrent peers.
+//
+// Critical invariant: surviving raw lines are written back byte-exact. The
+// awk extractor in assets/pretooluse.sh assumes the FIELD_ORDER_PREFIX layout;
+// re-serializing via JSON.stringify could reorder keys and silently break the
+// hook for messages that stay in the mailbox.
+export function drainMatchingSession(my_pid, from_session_id) {
+    acquireLock(my_pid);
+    try {
+        let raw;
+        try {
+            raw = readFileSync(mailboxPath(my_pid), "utf8");
+        }
+        catch (e) {
+            const err = e;
+            if (err.code === "ENOENT")
+                return null;
+            throw err;
+        }
+        if (!raw)
+            return null;
+        const lines = raw.split("\n").filter((l) => l.length > 0);
+        let matchIdx = -1;
+        let matchedMsg = null;
+        for (let i = 0; i < lines.length; i++) {
+            let parsed;
+            try {
+                parsed = JSON.parse(lines[i]);
+            }
+            catch {
+                continue;
+            }
+            if (parsed &&
+                typeof parsed === "object" &&
+                parsed.schema_version === 1 &&
+                parsed.from_session_id === from_session_id) {
+                matchIdx = i;
+                matchedMsg = parsed;
+                break;
+            }
+        }
+        if (matchIdx < 0 || !matchedMsg)
+            return null;
+        const surviving = [
+            ...lines.slice(0, matchIdx),
+            ...lines.slice(matchIdx + 1),
+        ];
+        if (surviving.length === 0) {
+            try {
+                truncateSync(mailboxPath(my_pid), 0);
+            }
+            catch (e) {
+                const err = e;
+                if (err.code !== "ENOENT")
+                    throw err;
+            }
+        }
+        else {
+            writeFileSync(mailboxPath(my_pid), surviving.join("\n") + "\n");
+        }
+        return matchedMsg;
+    }
+    finally {
+        releaseLock(my_pid);
+    }
+}
+export function mailboxFilePath(pid) {
+    return mailboxPath(pid);
+}
+export function mailboxLockPath(pid) {
+    return lockPath(pid);
+}

package/dist/registry.js

@@ -2,25 +2,29 @@ import { execFileSync } from "node:child_process";
 import { chmodSync, existsSync, mkdirSync, readFileSync, readdirSync, renameSync, unlinkSync, writeFileSync, } from "node:fs";
 import { homedir } from "node:os";
 import { join } from "node:path";
-const REGISTRY_DIR = join(homedir(), ".oxtail", "sessions");
+// Lazy so tests can swap HOME between cases; homedir() defers to $HOME on POSIX.
+function registryDir() {
+    return join(homedir(), ".oxtail", "sessions");
+}
 function ensureDir() {
-    if (!existsSync(REGISTRY_DIR)) {
-        mkdirSync(REGISTRY_DIR, { recursive: true, mode: 0o700 });
+    const dir = registryDir();
+    if (!existsSync(dir)) {
+        mkdirSync(dir, { recursive: true, mode: 0o700 });
         return;
     }
     // Migration: tighten perms for users upgrading from <0.4.0, where the dir
     // and entries were created at default umask (typically 0o755 / 0o644).
     try {
-        chmodSync(REGISTRY_DIR, 0o700);
+        chmodSync(dir, 0o700);
     }
     catch {
         // not our dir or fs doesn't support; leave it
     }
-    for (const file of readdirSync(REGISTRY_DIR)) {
+    for (const file of readdirSync(dir)) {
         if (!file.endsWith(".json"))
             continue;
         try {
-            chmodSync(join(REGISTRY_DIR, file), 0o600);
+            chmodSync(join(dir, file), 0o600);
         }
         catch {
             // ignore
@@ -28,7 +32,7 @@ function ensureDir() {
     }
 }
 function entryPath(pid) {
-    return join(REGISTRY_DIR, `${pid}.json`);
+    return join(registryDir(), `${pid}.json`);
 }
 function resolveTmuxSessionFromPane(pane) {
     if (!pane)
@@ -168,13 +172,14 @@ function isAlive(pid) {
     }
 }
 export function readAll() {
-    if (!existsSync(REGISTRY_DIR))
+    const dir = registryDir();
+    if (!existsSync(dir))
         return [];
     const out = [];
-    for (const file of readdirSync(REGISTRY_DIR)) {
+    for (const file of readdirSync(dir)) {
         if (!file.endsWith(".json"))
             continue;
-        const full = join(REGISTRY_DIR, file);
+        const full = join(dir, file);
         let entry;
         try {
             entry = JSON.parse(readFileSync(full, "utf8"));