oxtail 0.8.0 → 0.9.1

package/dist/claims.js

@@ -0,0 +1,228 @@
+// Sticky-claim store. A Codex MCP child restarts with session_id=null (its
+// CODEX_THREAD_ID is stripped from the MCP subprocess env, same structural
+// stripping as Claude Code's CLAUDE_CODE_SESSION_ID), so without help the agent
+// must re-run `echo $CODEX_THREAD_ID` → claim_session after every restart.
+//
+// On claim we persist a small record keyed by client_type + cwd + the MCP
+// server's ANCESTOR CHAIN (nearest-first, bounded, each ancestor tagged with a
+// start-time signature). On a later startup, when env- and birth-time detection
+// both fail, we recover the prior session_id by finding a record whose stored
+// ancestor chain still shares a live process with the current child's chain —
+// i.e. the same agent host is still running above us.
+//
+// Why the chain and not a single parent pid: the MCP server's immediate parent
+// is often a transient launcher (npx/tsx/a shell) that is re-spawned per start,
+// so process.ppid alone is not stable across a restart. The agent HOST, a few
+// levels up, is. Matching on a shared (pid, signature) anywhere in the bounded
+// chain finds that host through whatever launchers sit beneath it. The
+// signature (process start time) means a reused pid can't masquerade as the
+// original ancestor.
+//
+// Why not cwd alone: two agent sessions can share a project root, so a cwd-only
+// key collides. Why not birth-time on restart: the transcript predates the
+// restarted child's started_at, so the positive-delta birth-time rule abstains.
+//
+// Recovery is conservative: it adopts ONLY when exactly one record matches the
+// live ancestry and the recorded transcript still exists. Any ambiguity (zero
+// or multiple matching claims) → null → the caller falls back to the explicit
+// claim_session next_step rather than guessing.
+//
+// A live registry entry that already holds the recovered session_id is NOT a
+// conflict: per the AGENTS.md invariant, session_id IS the agent identity, so a
+// same-session_id sibling is the same agent's other MCP child (the documented
+// dual-scope setup), not an impostor. Recovery proceeds alongside it;
+// readAll()/dedupeBySessionId collapses the duplicates downstream.
+import { execFileSync } from "node:child_process";
+import { createHash } from "node:crypto";
+import { existsSync, mkdirSync, readFileSync, readdirSync, renameSync, unlinkSync, writeFileSync, } from "node:fs";
+import { homedir } from "node:os";
+import { join } from "node:path";
+// How far up the process tree to look for a shared host. Deep enough to clear
+// launcher(s) between the host and the MCP server; if it also catches a shared
+// terminal/login-shell, the "exactly one match" guard still keeps recovery safe
+// (ambiguity → abstain → explicit claim).
+const ANCESTRY_DEPTH = 8;
+// Records older than this with no live evidence are GC'd on the next write.
+const CLAIM_MAX_AGE_MS = 14 * 24 * 60 * 60 * 1000;
+// Lazy so tests can swap HOME between cases; homedir() defers to $HOME on POSIX.
+export function claimsDir() {
+    return join(homedir(), ".oxtail", "claims");
+}
+function ensureClaimsDir() {
+    const dir = claimsDir();
+    if (!existsSync(dir))
+        mkdirSync(dir, { recursive: true, mode: 0o700 });
+}
+// One `ps` call → pid -> { ppid, sig }, where sig is the process start time
+// (lstart). lstart carries spaces, so it's everything after the first two
+// columns. Empty map if ps is unavailable (recovery then simply abstains).
+function snapshotProcs() {
+    const map = new Map();
+    try {
+        const out = execFileSync("ps", ["-A", "-o", "pid=,ppid=,lstart="], {
+            encoding: "utf8",
+            stdio: ["ignore", "pipe", "pipe"],
+        });
+        for (const line of out.split("\n")) {
+            const t = line.trim();
+            if (!t)
+                continue;
+            const parts = t.split(/\s+/);
+            if (parts.length < 3)
+                continue;
+            const pid = Number(parts[0]);
+            const ppid = Number(parts[1]);
+            if (!Number.isFinite(pid) || !Number.isFinite(ppid))
+                continue;
+            map.set(pid, { ppid, sig: parts.slice(2).join(" ") });
+        }
+    }
+    catch {
+        // ps unavailable — leave map empty
+    }
+    return map;
+}
+// The MCP server's ancestor chain, nearest-first, bounded to ANCESTRY_DEPTH.
+// Stops at pid <= 1 (init/launchd). Each ancestor carries a start-time sig.
+export function resolveAncestors(startPpid = process.ppid, procs = snapshotProcs(), depth = ANCESTRY_DEPTH) {
+    const out = [];
+    let pid = startPpid;
+    for (let i = 0; i < depth && pid > 1; i++) {
+        const node = procs.get(pid);
+        out.push({ pid, sig: node?.sig ?? "" });
+        if (!node)
+            break;
+        pid = node.ppid;
+    }
+    return out;
+}
+// True if the chains share a live process — same pid AND start-time signature.
+// An empty sig never matches (degraded ps output must not produce false hits).
+function chainsOverlap(a, b) {
+    for (const x of a) {
+        if (!x.sig)
+            continue;
+        for (const y of b) {
+            if (x.pid === y.pid && x.sig === y.sig)
+                return true;
+        }
+    }
+    return false;
+}
+function claimKey(clientType, cwd, sessionId) {
+    return createHash("sha256")
+        .update(`${clientType} ${cwd} ${sessionId}`)
+        .digest("hex")
+        .slice(0, 32);
+}
+function claimPath(key) {
+    return join(claimsDir(), `${key}.json`);
+}
+// Persist (or refresh) the sticky claim. Keyed by session, so re-claiming the
+// same session overwrites in place while distinct sessions in one cwd coexist.
+// Atomic temp+rename so a concurrent reader never sees a torn write.
+export function writeClaim(input) {
+    ensureClaimsDir();
+    gcStaleClaims();
+    const rec = {
+        schema_version: 1,
+        client_type: input.client_type,
+        cwd: input.cwd,
+        ancestors: input.ancestors,
+        session_id: input.session_id,
+        transcript_path: input.transcript_path,
+        claimed_at: input.claimed_at,
+        server_pid: input.server_pid,
+    };
+    const final = claimPath(claimKey(input.client_type, input.cwd, input.session_id));
+    const tmp = `${final}.${process.pid}.tmp`;
+    try {
+        writeFileSync(tmp, JSON.stringify(rec, null, 2), { mode: 0o600 });
+        renameSync(tmp, final);
+    }
+    catch {
+        try {
+            unlinkSync(tmp);
+        }
+        catch {
+            // already gone
+        }
+    }
+}
+// Recover the previously-claimed session for this (client_type, cwd) whose
+// stored ancestry still shares a live process with `ancestors`. Returns the
+// record only when exactly one record is an unambiguously safe match; otherwise
+// null (caller falls back to explicit claim_session).
+export function recoverClaim(clientType, cwd, ancestors, deps = {}) {
+    const exists = deps.transcriptExists ?? existsSync;
+    const dir = claimsDir();
+    if (!existsSync(dir))
+        return null;
+    let files;
+    try {
+        files = readdirSync(dir);
+    }
+    catch {
+        return null;
+    }
+    const matches = [];
+    for (const f of files) {
+        if (!f.endsWith(".json"))
+            continue;
+        let rec;
+        try {
+            rec = JSON.parse(readFileSync(join(dir, f), "utf8"));
+        }
+        catch {
+            continue;
+        }
+        if (rec.client_type !== clientType || rec.cwd !== cwd)
+            continue;
+        if (!rec.session_id || !rec.transcript_path)
+            continue;
+        if (!Array.isArray(rec.ancestors) || !chainsOverlap(rec.ancestors, ancestors))
+            continue;
+        if (!exists(rec.transcript_path))
+            continue;
+        matches.push(rec);
+    }
+    // Exactly one safe match adopts; zero or ambiguous (>1) → abstain.
+    return matches.length === 1 ? matches[0] : null;
+}
+// Drop records that are clearly dead: transcript gone, or older than the max
+// age. Best-effort; never throws. A dead process pid alone is NOT grounds for
+// removal — that's exactly the restart case recovery exists to serve.
+export function gcStaleClaims(nowMs = Date.now()) {
+    const dir = claimsDir();
+    if (!existsSync(dir))
+        return;
+    let files;
+    try {
+        files = readdirSync(dir);
+    }
+    catch {
+        return;
+    }
+    for (const f of files) {
+        if (!f.endsWith(".json"))
+            continue;
+        const full = join(dir, f);
+        let rec;
+        try {
+            rec = JSON.parse(readFileSync(full, "utf8"));
+        }
+        catch {
+            continue;
+        }
+        const transcriptGone = !rec.transcript_path || !existsSync(rec.transcript_path);
+        const tooOld = nowMs - rec.claimed_at * 1000 > CLAIM_MAX_AGE_MS;
+        if (transcriptGone || tooOld) {
+            try {
+                unlinkSync(full);
+            }
+            catch {
+                // already gone
+            }
+        }
+    }
+}

package/dist/clients.js

@@ -90,13 +90,13 @@ function recentCodexDateDirs(base, days) {
     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;
+    if (env.CLAUDECODE === "1") {
+        const sessionId = env.CLAUDE_CODE_SESSION_ID ?? null;
         return {
             type: "claude-code",
             session_id: sessionId,
-            transcript_path: claudeTranscriptPath(sessionId, cwd),
-            session_id_source: "env",
+            transcript_path: sessionId ? claudeTranscriptPath(sessionId, cwd) : null,
+            session_id_source: sessionId ? "env" : null,
             cwd,
         };
     }

package/dist/mailbox.js

@@ -26,10 +26,7 @@ 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
-    }
+    Atomics.wait(new Int32Array(new SharedArrayBuffer(4)), 0, 0, ms);
 }
 export function acquireLock(pid) {
     mkdirSync(mailboxesDir(), { recursive: true, mode: 0o700 });