oxtail 0.4.0

package/.claude/commands/oxtail-join.md

@@ -0,0 +1,10 @@
+Initiate this Claude session's participation in oxtail's peer registry so sibling agents in this project root can resolve our `client_session_id` and read our transcript directly (rather than falling back to raw tmux pane capture).
+
+Why this is needed: Claude Code strips `CLAUDE_CODE_SESSION_ID` from MCP children, so the oxtail server can't read our session id from its own env. The var IS available in Bash tool subshells. When two or more Claude Code sessions share a project, birth-time fingerprint matching also can't safely disambiguate. So we register manually.
+
+Do this:
+
+1. Run `echo "$CLAUDE_CODE_SESSION_ID"` via the Bash tool. Confirm a UUID comes back.
+2. Call the oxtail MCP tool `claim_session` with `{ session_id: "<the UUID from step 1>" }`. Report back `session_id` and `transcript_path` from the response.
+
+If step 1 returns empty, we are not running inside Claude Code — bail out and tell the user.

package/AGENTS.md

@@ -0,0 +1,49 @@
+# oxtail
+
+A coordination layer for parallel AI coding agent sessions. Multiple Claude Code or Codex CLI sessions working in the same project root become aware of each other through an MCP server (running locally) that exposes peer-discovery and cross-session-state tools.
+
+Scope is **project-root as the unit**. Sessions in one project root see each other; sessions in another see each other; cross-project there is no visibility, by design.
+
+## What this isn't
+
+- **Not a phone client.** An earlier client-side experiment explored a custom phone PWA for AI coding agents. It's paused — Termius + tmux + plain SSH won the daily-drive comparison. The actual unmet need is coordination logic, not a custom client.
+- **Not a competitor to Terminator.** Terminator is a separate desktop multi-agent orchestration tool with its own coherent UI. oxtail is a server-side layer that any MCP client can leverage. Both coexist; oxtail is intentionally a separate repo to keep Terminator's identity clean.
+- **Not a wrapper around tmux.** tmux is the implementation primitive most likely to back the session registry, but oxtail's identity is "agent peer awareness," not "session multiplexing." Don't bake "tmux" into tool names or public surface.
+
+## Architecture sketch
+
+- **Transport:** MCP. Both Claude Code and Codex CLI speak it natively, so one server serves both.
+- **Surface:** invocable from any client that hosts an agent — phone via SSH+Termius, desktop iTerm, the iOS Claude app, etc. The client is irrelevant to oxtail.
+- **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
+
+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`).
+
+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.
+
+## How to collaborate on this project
+
+- **Don't add features without observed friction.** Speculative structure locks in design before observation has informed it. The publish-readiness work (LICENSE, README restructure, npm metadata) was the exception, because "ship it so a third party can install it" is itself the observed need.
+- **Ask clarifying questions** about scope, architecture, the MCP tool set, anything unclear. Surfacing assumptions matters more than guessing.
+- **Keep observation notes in `NOTES.md`** (or a single scratchpad). Don't sprawl across multiple unstructured files.
+- **Don't change code based on theories — change it based on observed deltas** between actual behavior and current capability. Theorizing an orchestration API before real friction surfaces is the same antipattern as theorizing a UI fix before instrumenting.
+
+## Design principles (locked in)
+
+1. **Project-scoped, never global.** No cross-project visibility, ever.
+2. **Implementation detail stays out of public naming.** tmux is plumbing.
+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.
+
+## 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.
+- **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/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 David Kim
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,108 @@
+# oxtail
+
+Run two or more coding agents in the same repo and let them see each other. oxtail is a local MCP server that gives parallel Claude Code and Codex CLI sessions peer awareness: each session can list the others running in the same project root, read their state cards, and (when needed) read their transcripts directly. No fixed cap — every oxtail-aware session in the project shows up in `list_project_sessions`.
+
+Works for any mix of clients that speak MCP — Claude Code, Codex CLI, or one of each. Scope is **project-root as the unit**: sessions in `/path/to/foo` see each other; sessions in `/path/to/bar` see each other; cross-project there is no visibility, by design.
+
+## Privacy
+
+oxtail reads what's on disk locally and surfaces it to peers on the same machine.
+
+- The session registry at `~/.oxtail/sessions/<pid>.json` is created mode `0o700`/`0o600` (v0.4.0+). Files there contain your session id, transcript path, cwd, and `state.purpose` text. Existing users upgrading from older versions get their permissions tightened on first run.
+- `read_session` returns whatever the user typed and what the peer agent produced. Treat the returned content as context, not as fresh user input.
+- This is designed for **single-user-on-one-machine** use. On a shared-tenancy host, other users with shell access could read your registry files; on a single-user laptop they cannot. Crossing user boundaries is out of scope.
+
+## Install
+
+End users — paste into your MCP config and oxtail is fetched from npm on first use. Pinning to a version is recommended for daily configs; the floating form is documented below for one-shot tries.
+
+**Claude Code** — add to `~/.claude.json` (global) or any project's `.mcp.json`:
+
+```jsonc
+{ "mcpServers": { "oxtail": { "command": "npx", "args": ["-y", "oxtail@0.4.0"] } } }
+```
+
+**Codex CLI** — add to `~/.codex/config.toml`:
+
+```toml
+[mcp_servers.oxtail]
+command = "npx"
+args = ["-y", "oxtail@0.4.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 \
+  -o ~/.claude/commands/oxtail-join.md
+```
+
+**Codex skill** (`/oxtail-register`):
+
+```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 \
+  -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 \
+  -o ~/.codex/skills/oxtail-register/agents/openai.yaml
+```
+
+Floating form (`npx -y oxtail` with no `@`) exists for trying it out; don't pin daily configs to it — it floats end users into whatever the next published version turns out to be.
+
+Contributing? `git clone https://github.com/d4j3y2k/oxtail && cd oxtail && npm install && npm test`.
+
+## Requirements
+
+- `tmux` on `PATH`
+- Node 20+
+
+## 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.
+- `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).
+- `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.
+
+## Usage from an agent
+
+```
+claim_session({ session_id: "<uuid from $CLAUDE_CODE_SESSION_ID or $CODEX_THREAD_ID>" })
+set_my_state({ purpose: "wiring up state cards" })
+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 })
+```
+
+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.
+
+## Peer awareness without raw transcripts
+
+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.
+
+## 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.
+
+## How session_id resolution works (v0.4.0)
+
+Claude Code does not propagate `CLAUDE_CODE_SESSION_ID` to MCP child processes — and a process-tree spike confirmed it isn't recoverable via parent-env inspection either: the var only lives in Bash tool subshells. The MCP `initialize` handshake also carries no session id. So oxtail uses a layered detection strategy:
+
+1. **`env`** — direct read of `CLAUDE_CODE_SESSION_ID` / `CODEX_THREAD_ID`. Structurally null on Claude Code today; fires on Codex when `CODEX_THREAD_ID` is present in the MCP env.
+2. **`birth-time`** — match the MCP server's `started_at` against `*.jsonl` birth times in the project transcript dir. Resolves only when there is exactly one post-start candidate within a 5-minute window. Two or more in-window candidates means another agent is sharing this project, in which case birth-time abstains rather than guess.
+3. **`register_my_session`** — designed escape hatch. The agent reads its own session id from a Bash tool subshell (`echo $CLAUDE_CODE_SESSION_ID`) and pins it.
+
+Detection runs on startup, again at MCP handshake (`oninitialized`), and is retried at +1s/+5s/+30s/+5min via `unref`'d timers — covering the case where the transcript file doesn't exist yet at handshake time.
+
+When a strategy doesn't fire, it returns an abstention with a `reason` (e.g. `"2 post-start transcripts in 5min window — ambiguous"`), and `get_my_session` adds a top-level `next_step` block carrying the exact bash command to run for the escape hatch. A fresh agent can act in one round trip without investigating each null.
+
+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.
+
+## 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.

package/dist/clients.js

@@ -0,0 +1,138 @@
+import { existsSync, readdirSync } from "node:fs";
+import { homedir } from "node:os";
+import { join } from "node:path";
+import { diagnoseDetect } from "./detect/index.js";
+import { codexSessionIdFromEnv } from "./detect/envStrategy.js";
+function encodeCwdForClaudeProjects(cwd) {
+    return cwd.replace(/\//g, "-");
+}
+function claudeTranscriptPath(sessionId, cwd) {
+    return join(homedir(), ".claude", "projects", encodeCwdForClaudeProjects(cwd), `${sessionId}.jsonl`);
+}
+export function transcriptPathFor(type, sessionId, cwd) {
+    if (type === "claude-code")
+        return claudeTranscriptPath(sessionId, cwd);
+    if (type === "codex")
+        return findCodexTranscriptPath(sessionId);
+    return null;
+}
+// Run the detection composer to fill in `session_id` and `transcript_path`
+// when env-based detection couldn't get them. Returns the (possibly updated)
+// client plus the per-strategy diagnosis (or null if detection was skipped
+// because the client was already resolved or its type is unknown).
+export function enrichWithDiagnosis(client, started_at, env = process.env) {
+    if (client.session_id || client.type === "unknown") {
+        return { client, diagnosis: null };
+    }
+    const diagnosis = diagnoseDetect({
+        type: client.type,
+        cwd: client.cwd,
+        started_at,
+        env,
+    });
+    if (!diagnosis.winning)
+        return { client, diagnosis };
+    return {
+        client: {
+            ...client,
+            session_id: diagnosis.winning.session_id,
+            transcript_path: transcriptPathFor(client.type, diagnosis.winning.session_id, client.cwd),
+            session_id_source: diagnosis.winning.source,
+        },
+        diagnosis,
+    };
+}
+// Convenience wrapper when the caller doesn't need the diagnosis.
+export function enrichSessionId(client, started_at, env = process.env) {
+    return enrichWithDiagnosis(client, started_at, env).client;
+}
+// Codex stores transcripts at ~/.codex/sessions/<Y>/<M>/<D>/rollout-<iso>-<uuid>.jsonl
+// where the UUID in the filename matches the session_id. We don't know which date
+// dir to look in, so search the most recent few days in both UTC and local time.
+function findCodexTranscriptPath(sessionId) {
+    const base = join(homedir(), ".codex", "sessions");
+    if (!existsSync(base))
+        return null;
+    const dirs = recentCodexDateDirs(base, 3);
+    for (const dir of dirs) {
+        if (!existsSync(dir))
+            continue;
+        let entries;
+        try {
+            entries = readdirSync(dir);
+        }
+        catch {
+            continue;
+        }
+        for (const f of entries) {
+            if (f.endsWith(".jsonl") && f.includes(sessionId)) {
+                return join(dir, f);
+            }
+        }
+    }
+    return null;
+}
+function recentCodexDateDirs(base, days) {
+    const out = new Set();
+    const now = Date.now();
+    for (let i = 0; i < days; i++) {
+        const d = new Date(now - i * 86_400_000);
+        for (const utc of [true, false]) {
+            const y = utc ? d.getUTCFullYear() : d.getFullYear();
+            const m = (utc ? d.getUTCMonth() : d.getMonth()) + 1;
+            const day = utc ? d.getUTCDate() : d.getDate();
+            const yyyy = String(y);
+            const mm = String(m).padStart(2, "0");
+            const dd = String(day).padStart(2, "0");
+            out.add(join(base, yyyy, mm, dd));
+        }
+    }
+    return Array.from(out);
+}
+export function detectClient(env = process.env, cwd = process.cwd()) {
+    if (env.CLAUDECODE === "1" && env.CLAUDE_CODE_SESSION_ID) {
+        const sessionId = env.CLAUDE_CODE_SESSION_ID;
+        return {
+            type: "claude-code",
+            session_id: sessionId,
+            transcript_path: claudeTranscriptPath(sessionId, cwd),
+            session_id_source: "env",
+            cwd,
+        };
+    }
+    if (env.CODEX_HOME || env.CODEX_THREAD_ID || env.CODEX_COMPANION_SESSION_ID || env.CODEX_RUNTIME) {
+        const sessionId = codexSessionIdFromEnv(env);
+        return {
+            type: "codex",
+            session_id: sessionId,
+            transcript_path: sessionId ? findCodexTranscriptPath(sessionId) : null,
+            session_id_source: sessionId ? "env" : null,
+            cwd,
+        };
+    }
+    return { type: "unknown", session_id: null, transcript_path: null, session_id_source: null, cwd };
+}
+export function clientFromHandshake(info, env = process.env, cwd = process.cwd()) {
+    const name = info?.name?.toLowerCase() ?? "";
+    if (name.includes("claude")) {
+        const sessionId = env.CLAUDE_CODE_SESSION_ID ?? null;
+        return {
+            type: "claude-code",
+            session_id: sessionId,
+            transcript_path: sessionId ? claudeTranscriptPath(sessionId, cwd) : null,
+            session_id_source: sessionId ? "env" : null,
+            cwd,
+        };
+    }
+    if (name.includes("codex")) {
+        const sessionId = codexSessionIdFromEnv(env);
+        return {
+            type: "codex",
+            session_id: sessionId,
+            transcript_path: sessionId ? findCodexTranscriptPath(sessionId) : null,
+            session_id_source: sessionId ? "env" : null,
+            cwd,
+        };
+    }
+    return detectClient(env, cwd);
+}

package/dist/detect/birthTimeMatchStrategy.js

@@ -0,0 +1,171 @@
+import { closeSync, existsSync, openSync, readSync, readdirSync, statSync } from "node:fs";
+import { homedir } from "node:os";
+import { join } from "node:path";
+const FIVE_MIN_MS = 5 * 60 * 1000;
+const UUID_RE = /([0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12})/;
+// Returns the unique post-start candidate inside the window, or null if there
+// are zero or multiple. Multiple positive-delta candidates means another
+// Claude Code is sharing this project; we can't safely guess which transcript
+// belongs to us, so we fall through to register_my_session.
+export function pickByDelta(candidates, startedAtMs, windowMs = FIVE_MIN_MS) {
+    const ranked = candidates
+        .map((c) => ({ ...c, delta: c.birth_ms - startedAtMs }))
+        .filter((c) => c.delta > 0 && c.delta <= windowMs);
+    if (ranked.length !== 1)
+        return null;
+    return { session_id: ranked[0].session_id, birth_ms: ranked[0].birth_ms };
+}
+function fileBirthMs(path) {
+    try {
+        const s = statSync(path);
+        return s.birthtimeMs > 0 ? s.birthtimeMs : s.mtimeMs;
+    }
+    catch {
+        return 0;
+    }
+}
+function encodeCwdForClaudeProjects(cwd) {
+    return cwd.replace(/\//g, "-");
+}
+export function listClaudeCandidates(cwd, base = homedir()) {
+    const dir = join(base, ".claude", "projects", encodeCwdForClaudeProjects(cwd));
+    if (!existsSync(dir))
+        return [];
+    const out = [];
+    let entries;
+    try {
+        entries = readdirSync(dir);
+    }
+    catch {
+        return [];
+    }
+    for (const f of entries) {
+        if (!f.endsWith(".jsonl"))
+            continue;
+        const session_id = f.slice(0, -".jsonl".length);
+        out.push({ session_id, birth_ms: fileBirthMs(join(dir, f)) });
+    }
+    return out;
+}
+// Reads up to 4KB from the start of the file — enough to capture the first
+// JSONL line without slurping multi-MB transcripts.
+function readFirstLine(path, maxBytes = 4096) {
+    let fd;
+    try {
+        fd = openSync(path, "r");
+    }
+    catch {
+        return "";
+    }
+    try {
+        const buf = Buffer.alloc(maxBytes);
+        const n = readSync(fd, buf, 0, maxBytes, 0);
+        const text = buf.toString("utf8", 0, n);
+        const nl = text.indexOf("\n");
+        return nl === -1 ? text : text.slice(0, nl);
+    }
+    catch {
+        return "";
+    }
+    finally {
+        closeSync(fd);
+    }
+}
+function firstLineCwd(path) {
+    const line = readFirstLine(path);
+    if (!line)
+        return null;
+    try {
+        const obj = JSON.parse(line);
+        const c = obj?.payload?.cwd;
+        return typeof c === "string" ? c : null;
+    }
+    catch {
+        return null;
+    }
+}
+export function listCodexCandidatesIn(dirs, cwd) {
+    const out = [];
+    for (const dir of dirs) {
+        if (!existsSync(dir))
+            continue;
+        let entries;
+        try {
+            entries = readdirSync(dir);
+        }
+        catch {
+            continue;
+        }
+        for (const f of entries) {
+            if (!f.endsWith(".jsonl"))
+                continue;
+            const m = f.match(UUID_RE);
+            if (!m)
+                continue;
+            const path = join(dir, f);
+            const fileCwd = firstLineCwd(path);
+            if (fileCwd !== cwd)
+                continue;
+            out.push({ session_id: m[1], birth_ms: fileBirthMs(path) });
+        }
+    }
+    return out;
+}
+export function recentCodexDateDirs(base, days = 3) {
+    const out = new Set();
+    const now = Date.now();
+    for (let i = 0; i < days; i++) {
+        const d = new Date(now - i * 86_400_000);
+        for (const utc of [true, false]) {
+            const y = utc ? d.getUTCFullYear() : d.getFullYear();
+            const m = (utc ? d.getUTCMonth() : d.getMonth()) + 1;
+            const day = utc ? d.getUTCDate() : d.getDate();
+            out.add(join(base, String(y), String(m).padStart(2, "0"), String(day).padStart(2, "0")));
+        }
+    }
+    return Array.from(out);
+}
+export function listCodexCandidates(cwd, base = homedir()) {
+    const sessionsBase = join(base, ".codex", "sessions");
+    if (!existsSync(sessionsBase))
+        return [];
+    return listCodexCandidatesIn(recentCodexDateDirs(sessionsBase), cwd);
+}
+function abstainReason(type, candidates, startedAtMs) {
+    if (candidates.length === 0) {
+        const where = type === "claude-code" ? "~/.claude/projects/<encoded-cwd>" : "~/.codex/sessions/<recent>";
+        return {
+            abstain: true,
+            reason: `no transcript files in ${where} for this cwd; agent may not have started a transcript yet.`,
+        };
+    }
+    const ranked = candidates
+        .map((c) => ({ ...c, delta: c.birth_ms - startedAtMs }))
+        .filter((c) => c.delta > 0 && c.delta <= FIVE_MIN_MS);
+    if (ranked.length === 0) {
+        return {
+            abstain: true,
+            reason: `${candidates.length} transcript(s) in dir but none post-date this MCP server's started_at; transcript hasn't been created yet (retries scheduled).`,
+        };
+    }
+    return {
+        abstain: true,
+        structural: true,
+        reason: `${ranked.length} post-start transcripts in 5min window — ambiguous (multiple agents in this project). Cannot safely guess which is ours; call register_my_session.`,
+    };
+}
+export const birthTimeMatchStrategy = (ctx) => {
+    if (ctx.type === "unknown") {
+        return {
+            abstain: true,
+            reason: "client type unknown — no transcript directory to scan.",
+        };
+    }
+    const startedAtMs = ctx.started_at * 1000;
+    const candidates = ctx.type === "claude-code" ? listClaudeCandidates(ctx.cwd) : listCodexCandidates(ctx.cwd);
+    const pick = pickByDelta(candidates, startedAtMs);
+    if (pick) {
+        return { session_id: pick.session_id, source: "birth-time", confidence: "medium" };
+    }
+    return abstainReason(ctx.type, candidates, startedAtMs);
+};

package/dist/detect/envStrategy.js

@@ -0,0 +1,28 @@
+export function codexSessionIdFromEnv(env) {
+    return env.CODEX_THREAD_ID || env.CODEX_COMPANION_SESSION_ID || null;
+}
+export const envStrategy = (ctx) => {
+    if (ctx.type === "claude-code") {
+        const id = ctx.env.CLAUDE_CODE_SESSION_ID;
+        if (id)
+            return { session_id: id, source: "env", confidence: "high" };
+        return {
+            abstain: true,
+            structural: true,
+            reason: "CLAUDE_CODE_SESSION_ID not in MCP env. Claude Code strips it from MCP children (verified across the full process tree); this is structural, not a bug. The var IS available inside Bash tool subshells.",
+        };
+    }
+    if (ctx.type === "codex") {
+        const id = codexSessionIdFromEnv(ctx.env);
+        if (id)
+            return { session_id: id, source: "env", confidence: "high" };
+        return {
+            abstain: true,
+            reason: "CODEX_THREAD_ID is not in MCP env.",
+        };
+    }
+    return {
+        abstain: true,
+        reason: "client type unknown — no env var configured for this client.",
+    };
+};

package/dist/detect/index.js

@@ -0,0 +1,48 @@
+import { birthTimeMatchStrategy } from "./birthTimeMatchStrategy.js";
+import { envStrategy } from "./envStrategy.js";
+import { isHit, } from "./types.js";
+export { isAbstain, isHit } from "./types.js";
+export { birthTimeMatchStrategy } from "./birthTimeMatchStrategy.js";
+export { envStrategy } from "./envStrategy.js";
+export function composeDetectors(strategies) {
+    return (ctx) => {
+        for (const strategy of strategies) {
+            const result = strategy(ctx);
+            if (isHit(result))
+                return result;
+        }
+        return null;
+    };
+}
+export const detectSessionId = composeDetectors([envStrategy, birthTimeMatchStrategy]);
+const NAMED_STRATEGIES = [
+    ["env", envStrategy],
+    ["birth-time", birthTimeMatchStrategy],
+];
+function nextStepFor(ctx) {
+    const varName = ctx.type === "codex" ? "CODEX_THREAD_ID" : "CLAUDE_CODE_SESSION_ID";
+    return {
+        tool: "register_my_session",
+        instruction: `Read your own session id from a Bash tool subshell, then call register_my_session({ session_id }).`,
+        bash_command: `echo $${varName}`,
+    };
+}
+// Runs every built-in strategy and reports each outcome. When no strategy
+// resolved the session id, includes a `next_step` that points the caller at
+// the register_my_session escape hatch with the exact bash command to run —
+// so a fresh agent doesn't have to investigate why each strategy abstained.
+export function diagnoseDetect(ctx) {
+    const per_strategy = {};
+    let winning = null;
+    for (const [name, strat] of NAMED_STRATEGIES) {
+        const result = strat(ctx);
+        per_strategy[name] = result;
+        if (isHit(result) && !winning)
+            winning = { ...result, strategy: name };
+    }
+    return {
+        per_strategy,
+        winning,
+        next_step: winning ? null : nextStepFor(ctx),
+    };
+}

package/dist/detect/types.js

@@ -0,0 +1,6 @@
+export function isAbstain(o) {
+    return "abstain" in o;
+}
+export function isHit(o) {
+    return !isAbstain(o);
+}