@bragi-gmbh/codebus 1.2.0

package/dist/sessionstore.js

@@ -0,0 +1,736 @@
+import { readFileSync, writeFileSync, mkdirSync, renameSync, rmSync, statSync } from "node:fs";
+import { homedir } from "node:os";
+import { join } from "node:path";
+import { execFileSync } from "node:child_process";
+import { Worker } from "node:worker_threads";
+import { loadRoles } from "./rolestore.js";
+import { SessionStoreError } from "./errors.js";
+// Session-scoped identity: WHO a running agent session is, keyed on a
+// durable per-conversation handle when the host provides one, and on process
+// ancestry only as a last resort for hosts that don't.
+//
+// Why this exists: multiple agents must share one repository (researcher,
+// planner, coder, verifier all working the same checkout), so the directory
+// cannot be the identity key — a dir has one binding slot, and the second
+// checkin used to displace the first (observed live: codex-host-ingress stole
+// legacy-android-host-app from claude-master-planner's open session).
+//
+// THE KEY, in priority order (docs/plans/codebus-v2-reliability.md §7 Phase A,
+// precedent #1 in §2.4 — "key identity to a durable handle, never a process",
+// the tmux server model):
+//
+//   1. A durable per-conversation env id, ALONE — never mixed with pid.
+//      CLAUDE_CODE_SESSION_ID (Claude Code transcript UUID) or CODEX_THREAD_ID
+//      (Codex resume-thread UUID). Verified stable across days, CLI upgrades,
+//      /compact, --resume, and app relaunches — exactly the durability a pid
+//      can never offer. NEVER CLAUDE_CODE_HOST_SESSION_ID: that one is
+//      per-launch, not durable, and using it would silently reintroduce the
+//      mortal-key bug this design eliminates.
+//   2. "pid@lstart" of the nearest non-plumbing ancestor — bare-terminal
+//      fallback only, when neither env var is set. start-time disambiguates
+//      pid reuse. This tier IS mortal: a restarted process gets a new key,
+//      and pruneDead below reaps it once it's actually dead (§2 below).
+//
+// Known coarseness, accepted: in a plain terminal the first non-shell ancestor
+// is the terminal APP (iTerm/Terminal is one process for all tabs), so a
+// terminal-side checkin scopes to the whole terminal app, not the tab. Agent
+// sessions — the actual use case — each have their own durable env id and
+// never hit this tier.
+//
+// EXCEPT hosts whose one process serves many conversations. Codex Desktop
+// (field incident, 2026-08-13): the ChatGPT.app runs ONE core process for ALL
+// conversations, so ancestry alone collapsed to app-wide last-checkin-wins —
+// three lane threads overwrote each other's identity (lane-2 checked in, two
+// minutes later its watch announced lane-1). This is exactly what the env-id
+// tier exists to prevent: every shell command under such a host is stamped
+// with its own thread id, so the key is the thread, full stop — no ancestry
+// walk, no pid, needed or wanted.
+const THREAD_ENV_VARS = ["CLAUDE_CODE_SESSION_ID", "CODEX_THREAD_ID"];
+// A durable env-keyed entry outlives the process that wrote it BY DESIGN (the
+// whole point is to survive restarts) — age is the only prune signal for one,
+// short of an explicit `codebus session forget`. 30 days is generous: a
+// session that hasn't re-checked-in in a month is almost certainly gone for
+// good, and the cost of keeping it a little longer is a few bytes of JSON.
+const ENV_KEY_MAX_AGE_MS = 30 * 24 * 60 * 60 * 1000;
+const sessionsFile = () => join(homedir(), ".codebus", "session-roles.json");
+// Plumbing processes between a codebus invocation and the session process.
+const SKIP = new Set(["node", "sh", "zsh", "bash", "dash", "fish", "codebus", "codebus-mcp",
+    "python", "python3", "perl", "ruby"]); // script wrappers are plumbing too — observed: a key computed under python3 stopped at python3 itself
+function psLine(pid) {
+    try {
+        const out = execFileSync("ps", ["-p", String(pid), "-o", "ppid=,lstart=,comm="], {
+            encoding: "utf8", stdio: ["ignore", "pipe", "ignore"],
+        }).trim();
+        if (!out)
+            return null;
+        // "PPID  Wed Aug 12 22:39:04 2026  /path/to/comm" — lstart is 5 tokens.
+        const m = out.match(/^\s*(\d+)\s+(\S+\s+\S+\s+\S+\s+\S+\s+\S+)\s+(.*)$/);
+        if (!m)
+            return null;
+        return { ppid: Number(m[1]), start: m[2], comm: m[3] };
+    }
+    catch {
+        return null;
+    }
+}
+const basename = (p) => p.split("/").filter(Boolean).pop() ?? p;
+/** A key is pid-keyed (mortal, ancestry-based) iff it contains "@" — the
+ * separator between pid and lstart. Env-keyed (durable) keys are the raw env
+ * value verbatim and never contain "@" in practice (both hosts mint UUIDs). */
+const isPidKeyed = (key) => key.includes("@");
+/**
+ * Split a pid-keyed key into its pid and lstart parts, tolerating every key
+ * shape this store has ever written (verified against git history —
+ * a5db2fc..7920c1f, pre-Phase-A):
+ *
+ *   - "pid@lstart"            — the CURRENT format (bare-terminal fallback,
+ *                                 sessionKey() above), and also the ORIGINAL
+ *                                 format from this store's very first version.
+ *   - "pid@lstart#<thread-id>" — a since-removed intermediate format
+ *                                 (8ae7258 "key sessions on CODEX_THREAD_ID",
+ *                                 7920c1f "generalize to Claude Code") that
+ *                                 stamped a per-conversation thread id onto a
+ *                                 pid-keyed entry with '#' as the separator.
+ *                                 Phase A (51d2011) moved that discriminator
+ *                                 onto its OWN durable, env-keyed tier
+ *                                 instead (sessionKey() above again) and this
+ *                                 suffix shape stopped being WRITTEN — but an
+ *                                 entry written by an older CLI, still
+ *                                 sitting in ~/.codebus/session-roles.json
+ *                                 across an upgrade, keeps this shape until
+ *                                 something prunes or overwrites it.
+ *
+ * A liveness check must parse ONLY the pid@lstart portion in every case:
+ * psLine().start is the raw `ps -o lstart=` output and never contains a
+ * '#...' suffix, so comparing an un-stripped tail (e.key.slice(at+1), which
+ * DOES include '#<thread-id>' for the older shape) against it can never
+ * match — every legacy '#'-suffixed entry would be judged dead on the very
+ * next write after an upgrade, dropping an already-checked-in session back
+ * to a cwd binding (or no identity at all). Returns null for anything that
+ * doesn't structurally look like one of the shapes above (a non-numeric
+ * pid) — pruneDead treats that the same as "process not found": prune,
+ * rather than guess at a shape that was never actually written.
+ */
+function parsePidKeyedKey(key) {
+    const at = key.indexOf("@");
+    if (at < 0)
+        return null;
+    const pid = Number(key.slice(0, at));
+    if (!Number.isInteger(pid) || pid <= 0)
+        return null;
+    const hash = key.indexOf("#", at + 1);
+    const start = hash < 0 ? key.slice(at + 1) : key.slice(at + 1, hash);
+    if (!start)
+        return null;
+    return { pid, start };
+}
+/**
+ * The current session's key: a durable per-conversation env id ALONE when the
+ * host provides one, or "pid@lstart" of the nearest non-plumbing ancestor for
+ * bare terminals. Null when neither is available — callers degrade to the
+ * directory-binding tier, never fail.
+ */
+export function sessionKey() {
+    // Durable handle wins outright — never mixed with pid (precedent §2.4-1:
+    // key identity to a durable handle, never a process). First match wins;
+    // a host only ever sets one of these.
+    const thread = THREAD_ENV_VARS.map((v) => process.env[v]).find(Boolean);
+    if (thread)
+        return thread;
+    // Bare-terminal fallback: mortal, ancestry-based.
+    let pid = process.ppid;
+    for (let hops = 0; hops < 12 && pid > 1; hops++) {
+        const info = psLine(pid);
+        if (!info)
+            return null;
+        if (!SKIP.has(basename(info.comm)))
+            return `${pid}@${info.start}`;
+        pid = info.ppid;
+    }
+    return null;
+}
+/** Structural validation — a store that parses as JSON but isn't shaped like
+ * one is just as untrustworthy as one that doesn't parse at all (a half
+ * written object, an array where entries should be, a stray null). */
+function isValidStore(v) {
+    if (!v || typeof v !== "object" || !Array.isArray(v.entries))
+        return false;
+    return v.entries.every((e) => !!e && typeof e === "object" &&
+        typeof e.key === "string" &&
+        typeof e.role === "string" &&
+        typeof e.added_at === "string");
+}
+/**
+ * Load the session store, distinguishing "doesn't exist yet" (ENOENT — a
+ * brand-new machine, or every entry has already been pruned/forgotten; the
+ * legitimate empty case) from every other failure (permission denied, a disk
+ * I/O error, truncated/corrupt JSON, an unexpected shape). Only the first is
+ * safe to treat as an empty store: any of the others means this session's
+ * entry might well be sitting in there, mangled, and silently returning
+ * `{ entries: [] }` is exactly how a truncated write used to make a durable,
+ * checked-in session look like it was never checked in at all — resolution
+ * would then fall through to a cwd binding and hand this session a DIFFERENT
+ * agent's identity (the foreign-identity takeover the session tier exists to
+ * eliminate). So anything past ENOENT throws SessionStoreError and resolution
+ * fails closed instead of guessing.
+ */
+function loadSessions() {
+    let raw;
+    try {
+        raw = readFileSync(sessionsFile(), "utf8");
+    }
+    catch (e) {
+        if (e.code === "ENOENT")
+            return { entries: [] };
+        throw new SessionStoreError(`could not read ${sessionsFile()}: ${e.message}`);
+    }
+    let parsed;
+    try {
+        parsed = JSON.parse(raw);
+    }
+    catch (e) {
+        throw new SessionStoreError(`${sessionsFile()} is not valid JSON (${e.message}) — truncated or corrupt write?`);
+    }
+    if (!isValidStore(parsed)) {
+        throw new SessionStoreError(`${sessionsFile()} has an unexpected shape (missing/invalid 'entries' array)`);
+    }
+    return parsed;
+}
+/**
+ * Keep pid-keyed entries only while their process is still alive with the
+ * same start time (pruneDead's original contract). Env-keyed entries are
+ * durable BY DESIGN — a checkin's whole point is to survive the process that
+ * made it — so death is never a prune signal for them; they age out instead
+ * (ENV_KEY_MAX_AGE_MS since their last (re)checkin) or are removed explicitly
+ * via `codebus session forget`. Pruning an env-keyed entry on process death
+ * was the FM-1/root-cause-2.1 bug: a restarting Codex/Claude process (new pid,
+ * SAME durable thread id) would otherwise lose its binding on every restart
+ * and silently fall through to the directory tier.
+ */
+function pruneDead(store) {
+    const now = Date.now();
+    store.entries = store.entries.filter((e) => {
+        if (!isPidKeyed(e.key)) {
+            const age = now - new Date(e.added_at).getTime();
+            return !(age > ENV_KEY_MAX_AGE_MS);
+        }
+        // parsePidKeyedKey strips a legacy '#<thread-id>' suffix before comparing
+        // — see its doc comment for the upgrade-path bug this fixes (every
+        // pre-Phase-A '#'-suffixed entry used to be pruned as dead unconditionally
+        // on the first write after upgrading, regardless of whether its process
+        // was actually still alive).
+        const parsed = parsePidKeyedKey(e.key);
+        if (!parsed)
+            return false; // "@" present but not a shape this store ever wrote — can't verify liveness, so treat like a dead/invalid entry
+        const info = psLine(parsed.pid);
+        return !!info && info.start === parsed.start;
+    });
+    return store;
+}
+/**
+ * Atomic write: a sibling temp file + rename, never a direct write to the
+ * live path. A plain writeFileSync to session-roles.json is visible to
+ * concurrent readers/writers mid-write — exactly how a reader can observe a
+ * truncated/partial file (loadSessions above then has to fail closed on it).
+ * rename(2) on the same filesystem is atomic, so every observer sees either
+ * the complete old file or the complete new one, never a partial one.
+ */
+function saveSessions(store) {
+    const dir = join(homedir(), ".codebus");
+    mkdirSync(dir, { recursive: true });
+    const file = sessionsFile();
+    const tmp = join(dir, `.session-roles.json.tmp-${process.pid}-${Date.now()}-${Math.random().toString(36).slice(2)}`);
+    writeFileSync(tmp, JSON.stringify(store, null, 2) + "\n", { mode: 0o600 });
+    renameSync(tmp, file);
+}
+// ── interprocess lock ────────────────────────────────────────────────────────
+// recordSessionRole/forgetSession are read-modify-write: load the whole store,
+// mutate it, write the whole store back. Two such cycles racing (reproduced:
+// 40 concurrent `recordSessionRole` calls survived only 10 entries) each read
+// the same pre-write snapshot and the later save clobbers the earlier one's
+// addition outright — atomic renames make individual writes non-corrupting,
+// but they do nothing for a lost update between two overlapping read-then-write
+// cycles. mkdir is the lock primitive: it's atomic and exclusive across
+// processes on every platform Node runs on (POSIX mkdir(2) fails EEXIST if the
+// directory exists; no separate lockfile library needed for that guarantee).
+//
+// Round-2 review: a stale-lock steal must never let two processes believe
+// they hold the lock at once, and a release must never tear down a lock it
+// no longer owns. The original steal/release both acted on the SAME fixed
+// path (`dir`) independently via a bare, unconditional rmSync — a
+// live-but-slow holder's lock mtime is never refreshed (a periodic heartbeat
+// was ruled out as fragile), so it can look stale and get stolen while
+// genuinely still held; when that original holder FINALLY finishes and calls
+// its own release, an unconditional rmSync(dir) deletes whatever is AT `dir`
+// by then — which by that point is the thief's LIVE lock, not the original
+// holder's dead one — letting a third writer sneak in while the thief still
+// believes it holds the lock.
+//
+// Fix has two layers:
+//
+//  1. Every acquire writes an owner token (pid + timestamp + nonce) INSIDE
+//     the lock dir. release() captures its own token in the closure and only
+//     ever tries to act on a generation it can verify is still its own.
+//
+//  2. Eviction — by release OR by a steal — never does a bare rmSync(dir)
+//     against the shared path. It goes through evictLockDir(): rename `dir`
+//     to a private, uniquely-named tomb FIRST. rename(2) atomically removes
+//     the source path the instant it succeeds, so of any number of
+//     concurrent callers racing to rename away the SAME still-existing
+//     `dir`, AT MOST ONE can ever win; everyone else gets ENOENT and does
+//     nothing further (no removal, no retry within that call). This is what
+//     makes two stealers racing the same stale lock race-free.
+//
+//     A release additionally verifies, AFTER winning that race (i.e. once it
+//     safely and exclusively holds whatever was at `dir`, in its own private
+//     tomb that nobody else can see or touch), that the evicted generation's
+//     own owner token still matches its caller's. If it does, this really
+//     was the caller's own lock — discard the tomb, done. If it does NOT —
+//     meaning release's rename raced ahead of a legitimate steal/re-mkdir and
+//     scooped up a DIFFERENT, newer generation by accident — release does
+//     NOT discard it. It puts it back (renames the tomb back to `dir`) so
+//     the rightful holder's lock is undisturbed, rather than silently
+//     destroying a live owner's lock the way the original bug did.
+//
+//     Residual, explicitly accepted window: restoring can itself only fail
+//     if a THIRD party recreates `dir` in the sub-microsecond gap between
+//     release's rename-away and its rename-back — vanishingly narrow (no
+//     intervening I/O or event-loop tick separates the two calls). Even
+//     then, the invariant that MUST hold still holds: at most one process
+//     ever has `dir` mkdir'd at a time (rename's atomicity alone guarantees
+//     that, independent of the token check), and no release ever corrupts a
+//     DIFFERENT, currently-valid claimant's lock — in that doubly-narrow
+//     case the wrongly-evicted generation is simply dropped (not restored),
+//     never double-held, and the fail-closed session-store validation (round-
+//     2 finding #1's sibling, round-1 finding #1) means a resulting
+//     unreadable/half-written session-roles.json is caught on next read
+//     rather than silently misresolved.
+//
+// Round-2 CI failure, second pass: the two layers above make eviction SAFE
+// (never corrupt a different live owner's lock) but don't stop a genuinely
+// LIVE holder's lock from *looking* stale in the first place — the owner
+// token's mtime is written once, at acquire, and never touched again while
+// held. A critical section that legitimately runs longer than LOCK_STALE_MS
+// (observed on a slower CI runner: a deliberately-long-held test lock aged
+// past 10s while still genuinely live) ages exactly like a crashed one would,
+// and a normally-polling second acquirer correctly-by-the-old-rules steals
+// it — this is the reviewer's original "ownership/HEARTBEAT validation"
+// finding; only the ownership half had landed. Fixed with a heartbeat: while
+// a lock is held, a small worker_threads.Worker — on its OWN OS thread,
+// independent of whatever the holder's main thread is doing — re-touches the
+// owner file's mtime every HEARTBEAT_INTERVAL_MS via utimesSync, and
+// staleness is judged against THAT mtime (not the lock dir's own, which only
+// ever changes at creation). A worker thread, not a plain setInterval, is
+// required here on purpose: recordSessionRole/forgetSession's critical
+// section is synchronous by design (sleepSync above included — see its own
+// comment), and a synchronous, non-yielding critical section blocks the
+// entire JS main thread including any of its own timers; a heartbeat that
+// has to keep ticking THROUGH such a critical section cannot live on that
+// same thread. A genuinely crashed holder's heartbeat thread dies with it —
+// nothing keeps refreshing the mtime — so LOCK_STALE_MS since the LAST
+// heartbeat tick (not since acquire) is still exactly the right reap signal
+// for a truly dead holder, while a live one, however long its critical
+// section runs, is never mistaken for one.
+//
+// Round-4 ai-review, the theoretical tail: even with a heartbeat, staleness
+// is fundamentally a HEURISTIC — this is a standard, unavoidable fact of
+// distributed/lease-based locking, not a gap specific to this design. No
+// scheme built on "no liveness signal in N seconds ⇒ presumed dead" can ever
+// fully distinguish a crashed process from one merely stalled longer than N
+// (OS scheduling, CPU starvation, filesystem latency, or — here — the
+// heartbeat WORKER dying without the main thread dying too). So a genuinely
+// live holder whose heartbeat stalls past LOCK_STALE_MS CAN be evicted while
+// its critical section keeps running, unaware, concurrently with the new
+// owner's. Two things follow from accepting that honestly instead of
+// pretending a wider window or a fancier stale-check closes it:
+//
+//  1. BOUND it as tightly as practical: LOCK_STALE_MS below is generous
+//     (15 missed heartbeats) — a process stalled that long while genuinely
+//     holding this lock is overwhelmingly either dead or the machine is
+//     unusable for any other purpose either, evicted or not.
+//
+//  2. Make the ACTUAL WRITE safe regardless: recordSessionRole/forgetSession
+//     re-verify (verifyStillOwned, used via the `verifyOwned` callback
+//     withSessionLock hands to its critical section) that the lock is STILL
+//     theirs immediately before the atomic commit (saveSessions' temp+rename)
+//     that follows. An evicted-while-stalled holder that reaches this point
+//     gets SessionStoreError instead of a commit — its caller's ordinary
+//     error path handles it (the write simply didn't happen; retry the
+//     operation). This makes a lost update — the new owner's write being
+//     silently clobbered by a stale holder — IMPOSSIBLE: the stale holder
+//     either aborts before committing, or (see below) there was no window
+//     left in which it could have committed instead.
+//
+// The ONLY window this cannot close is between THIS check and the commit's
+// own renameSync: microseconds, with no I/O or event-loop yield point for
+// anything else to interleave through in between (both are synchronous,
+// back-to-back calls in the same critical section). Closing even that would
+// need a filesystem-level compare-and-swap this design doesn't have — this
+// is the practical limit for a file-based lock; a further reviewer flagging
+// that microsecond gap is an accept-with-documented-bound, not a rework.
+const LOCK_STALE_MS = 30_000; // 15 missed 2s heartbeats ⇒ presumed crashed; stolen after this
+const LOCK_STEAL_GRACE_MS = 250; // re-verify staleness once more before committing to a steal — narrows, but per the above cannot fully close, the false-positive-steal window (a steal landing in the instant between two heartbeat ticks)
+const LOCK_POLL_MS = 15;
+// Must comfortably exceed LOCK_STALE_MS: a waiter has to be willing to sit
+// through one full staleness-detection cycle (so a crashed holder's lock
+// actually gets reaped and handed to it, rather than giving up right before
+// that would happen) AND tolerate a live holder whose legitimate critical
+// section runs a while past LOCK_STALE_MS too (the whole point of the
+// heartbeat above — the CI failure this fixes was exactly a well-behaved
+// waiter's own patience mattering, not just the held lock's judged staleness).
+const LOCK_TIMEOUT_MS = 45_000;
+const HEARTBEAT_INTERVAL_MS = 2_000; // well under LOCK_STALE_MS, so a live holder's marker never has a chance to look stale
+function lockDir() { return `${sessionsFile()}.lock`; }
+function ownerFile(dir) { return join(dir, "owner"); }
+/**
+ * Start a heartbeat for a held lock: a worker thread that re-touches the
+ * owner file's mtime every HEARTBEAT_INTERVAL_MS for as long as it's kept
+ * alive, independent of whatever the holder's own (possibly long-blocking,
+ * synchronous) critical section is doing on the main thread — see the
+ * section comment above for why this can't be a plain main-thread timer.
+ * `.unref()`d so an unterminated heartbeat (a bug, or a process that exits
+ * without going through release — should never happen given withSessionLock's
+ * try/finally) can never keep the process alive on its own. Errors inside the
+ * worker are swallowed: a heartbeat failing is a liveness-signal problem for
+ * OTHER processes to (rarely, harmlessly) misjudge as staleness, never a
+ * reason to crash the holder that's actually doing useful work.
+ *
+ * Round-5 ai-review (zombie heartbeat): stopHeartbeat() below fires
+ * worker.terminate() but does NOT (cannot — the store API is deliberately
+ * synchronous, so release() can't await it) wait for it to land before
+ * evictLockDir runs. In the gap between "terminate() requested" and "the
+ * worker thread actually stops", the worker can wake for one more tick and
+ * utimesSync the owner path — which by then may already belong to a NEW
+ * lock generation (this hold evicted-while-stalled, exactly the round-4
+ * scenario, and a fresh acquirer already recreated `dir` with its own
+ * token). That refresh would keep a lock the old process no longer owns
+ * looking alive, blocking anyone from ever reaping it — a zombie heartbeat,
+ * narrow but real (worst case: the new owner later crashes, and the dead
+ * lock is kept "alive" by the zombie until the OLD process eventually
+ * exits and its worker gets torn down with it).
+ *
+ * Fixed with generation-awareness instead of trying to make release()
+ * async: before EVERY touch, the worker reads the owner file's CURRENT
+ * content and compares it to the token it was started with. Touch only on
+ * an exact match; on a mismatch (a different generation now owns this path)
+ * or ENOENT (evicted and the file is gone entirely, or tombed) the worker
+ * exits itself — a stale heartbeat is a contradiction in terms once it can
+ * see it no longer owns what it's refreshing. stopHeartbeat's terminate()
+ * stays as belt-and-braces (the common, fast path: most releases happen
+ * long before the worker's next scheduled tick anyway).
+ */
+function startHeartbeat(dir, token) {
+    const worker = new Worker(`
+    const { workerData } = require("node:worker_threads");
+    const { utimesSync, readFileSync } = require("node:fs");
+    const sab = new SharedArrayBuffer(4);
+    const ia = new Int32Array(sab);
+    for (;;) {
+      Atomics.wait(ia, 0, 0, workerData.intervalMs);
+      let current;
+      try {
+        current = readFileSync(workerData.file, "utf8");
+      } catch {
+        break; // owner file gone entirely — can't confirm we still own it, so stop rather than guess
+      }
+      if (current !== workerData.token) break; // a DIFFERENT generation owns this path now — never touch a lock we don't own
+      try {
+        const now = new Date();
+        utimesSync(workerData.file, now, now);
+      } catch {
+        /* vanished between our read and this write (a steal landed in that
+         * gap) — next iteration's read sees the mismatch/ENOENT and stops;
+         * nothing to do for THIS tick. */
+      }
+    }
+    `, { eval: true, workerData: { file: ownerFile(dir), intervalMs: HEARTBEAT_INTERVAL_MS, token } });
+    worker.unref();
+    worker.on("error", () => { });
+    return worker;
+}
+/** Stop a heartbeat — best-effort, fire-and-forget (release() is synchronous
+ * and must not block waiting for worker teardown to be confirmed). Belt-and-
+ * braces alongside the worker's own generation check above (startHeartbeat's
+ * doc comment) — this is the fast, common-case path; that's the correctness
+ * backstop for the gap this alone can't close. */
+function stopHeartbeat(worker) {
+    worker.terminate().catch(() => { });
+}
+/** Synchronous sleep — the lock spin has to block (no callers here are async;
+ *  recordSessionRole/forgetSession are synchronous, deliberately, so a caller
+ *  never has to remember to await an identity-binding call). Atomics.wait on a
+ *  throwaway SharedArrayBuffer is Node's documented way to block the main
+ *  thread for a bounded time without a busy CPU spin. */
+function sleepSync(ms) {
+    Atomics.wait(new Int32Array(new SharedArrayBuffer(4)), 0, 0, ms);
+}
+/**
+ * Write this acquisition's owner token inside `dir` and return it — load-
+ * bearing now (not just diagnostic): release() uses it to verify it's still
+ * acting on its OWN generation before discarding anything (see the section
+ * comment above). A write failure here means the filesystem can't even be
+ * written to right after we just mkdir'd it — fail closed rather than hand
+ * back a lock whose ownership can never be verified later.
+ */
+function writeOwnerToken(dir) {
+    const token = `${process.pid}@${Date.now()}-${Math.random().toString(36).slice(2)}`;
+    try {
+        writeFileSync(ownerFile(dir), token);
+    }
+    catch (e) {
+        throw new SessionStoreError(`could not write lock owner token in ${dir}: ${e.message}`);
+    }
+    return token;
+}
+function readOwnerToken(dir) {
+    try {
+        return readFileSync(ownerFile(dir), "utf8");
+    }
+    catch {
+        return null;
+    }
+}
+/**
+ * Pre-commit ownership re-check (round-4 ai-review — see the section comment
+ * above for the full reasoning). Called immediately before the atomic commit
+ * that follows the critical section's mutation: if the lock's CURRENT owner
+ * token no longer matches the one captured at acquire (`token`), this holder
+ * was evicted as stale while it was still — unknown to it — running, and
+ * MUST NOT proceed to write. Throws SessionStoreError instead, which the
+ * caller's ordinary error path handles (the write simply never happened;
+ * retry the operation). A missing owner file (evicted AND the new owner has
+ * already released too) also counts as "not ours anymore" — `null` can never
+ * equal `token`.
+ */
+function verifyStillOwned(dir, token) {
+    if (readOwnerToken(dir) === token)
+        return;
+    throw new SessionStoreError(`session-store lock ownership lost mid-write (${dir}) — this hold was evicted as stale while still running ` +
+        `(a genuinely dead process is indistinguishable from one merely stalled past ${LOCK_STALE_MS}ms; see the lock ` +
+        `section in sessionstore.ts). Aborting before committing, to avoid clobbering the new owner's write — retry.`);
+}
+/**
+ * Age of the lock, in ms, judged by the owner file's mtime — the heartbeat's
+ * target, kept fresh for as long as the holder is genuinely alive (see the
+ * section comment above). Falls back to the lock DIR's own mtime only if the
+ * owner file can't be read (a sub-millisecond window right after mkdirSync,
+ * before writeOwnerToken has run, or the file vanished mid-check) — never
+ * treated as an error, just a less-precise age estimate for that instant.
+ * Null only if BOTH are unreadable (the dir itself is already gone).
+ */
+function lockAgeMs(dir) {
+    try {
+        return Date.now() - statSync(ownerFile(dir)).mtimeMs;
+    }
+    catch { /* fall through */ }
+    try {
+        return Date.now() - statSync(dir).mtimeMs;
+    }
+    catch {
+        return null;
+    }
+}
+/**
+ * Atomically evict whatever currently lives at `dir` — the ONE primitive
+ * used by both a normal release and a steal-a-stale-lock attempt (see the
+ * section comment above for why they must share it and how the safety
+ * invariant follows from that).
+ *
+ *  - `expectedToken` omitted (the STEAL path): the caller already re-verified
+ *    staleness immediately before calling this, so once the rename wins,
+ *    discard unconditionally — a steal doesn't care whose lock it was.
+ *  - `expectedToken` given (the RELEASE path): only discard if the evicted
+ *    generation's OWN owner token matches. A mismatch means this call's
+ *    rename won against a DIFFERENT, newer generation that happened to
+ *    occupy the same path — put it back (rename the tomb back to `dir`)
+ *    instead of destroying a live owner's lock. See the residual-window note
+ *    in the section comment above for the one case restoring can itself fail.
+ *
+ * Returns true iff this call's rename won the eviction race (regardless of
+ * whether the content was ultimately discarded or restored).
+ */
+function evictLockDir(dir, expectedToken) {
+    const tomb = `${dir}.evicted-${process.pid}-${Date.now()}-${Math.random().toString(36).slice(2)}`;
+    try {
+        renameSync(dir, tomb);
+    }
+    catch {
+        return false; // lost the race — some other release/steal already evicted this generation
+    }
+    if (expectedToken !== undefined && readOwnerToken(tomb) !== expectedToken) {
+        // We evicted a DIFFERENT, presumably-live generation by accident — try to
+        // put it back rather than discard someone else's live lock.
+        try {
+            renameSync(tomb, dir); // fails only if a third party already recreated `dir` in this sub-microsecond gap (see residual-window note above)
+            return true;
+        }
+        catch {
+            /* doubly-narrow race: couldn't restore — fall through and drop it.
+             * `dir` currently belongs solely to that third party, untouched by us;
+             * the invariant (never two simultaneous holders) still holds. */
+        }
+    }
+    try {
+        rmSync(tomb, { recursive: true, force: true });
+    }
+    catch { /* best-effort cleanup of our own, now-private tomb */ }
+    return true;
+}
+/** Acquire the session-store lock, spinning past concurrent holders and
+ * stealing a stale one, or throwing SessionStoreError if it can't be had
+ * within LOCK_TIMEOUT_MS (a stuck/crashed writer that leaves a lock younger
+ * than the stale threshold — vanishingly unlikely, but must fail loud, never
+ * hang forever or silently proceed unlocked). Returns the acquired lock's
+ * `dir`/`token` (so the caller can pre-commit-verify with them — see
+ * verifyStillOwned/withSessionLock below) alongside the release function. */
+function acquireSessionLock() {
+    mkdirSync(join(homedir(), ".codebus"), { recursive: true });
+    const dir = lockDir();
+    const deadline = Date.now() + LOCK_TIMEOUT_MS;
+    for (;;) {
+        try {
+            mkdirSync(dir); // no {recursive:true} — MUST fail EEXIST when already held
+            const token = writeOwnerToken(dir);
+            const heartbeat = startHeartbeat(dir, token);
+            // Release stops the heartbeat FIRST, then verifies ownership (via
+            // `token`) before discarding anything — see evictLockDir's doc comment.
+            return { dir, token, release: () => { stopHeartbeat(heartbeat); evictLockDir(dir, token); } };
+        }
+        catch (e) {
+            if (e instanceof SessionStoreError)
+                throw e; // writeOwnerToken's own failure — fail closed, not a retry-able EEXIST
+            if (e.code !== "EEXIST") {
+                throw new SessionStoreError(`could not acquire lock dir ${dir}: ${e.message}`);
+            }
+            const age = lockAgeMs(dir); // judged by the owner file's mtime — a live holder's HEARTBEAT keeps this fresh regardless of critical-section length
+            if (age !== null && age > LOCK_STALE_MS) {
+                // Re-verify once more after a short grace before committing to a
+                // steal attempt — narrows, but (see the section comment above)
+                // cannot fully close, the false-positive window (a steal landing in
+                // the instant between two heartbeat ticks).
+                sleepSync(LOCK_STEAL_GRACE_MS);
+                const ageAfterGrace = lockAgeMs(dir);
+                if (ageAfterGrace !== null && ageAfterGrace > LOCK_STALE_MS && evictLockDir(dir)) {
+                    continue; // we won the eviction race — loop back and try mkdirSync(dir) fresh
+                }
+            }
+            if (Date.now() > deadline) {
+                const owner = readOwnerToken(dir);
+                throw new SessionStoreError(`timed out after ${LOCK_TIMEOUT_MS}ms waiting for session-store lock (${dir})` +
+                    `${owner ? ` — held by ${owner}` : ""} — a stuck writer?`);
+            }
+            sleepSync(LOCK_POLL_MS);
+        }
+    }
+}
+/**
+ * Run `fn` holding the session-store lock. `fn` receives `verifyOwned` — call
+ * it immediately before the critical section's own commit (see
+ * verifyStillOwned's doc comment and the round-4 section comment above): it
+ * throws SessionStoreError if this hold was evicted as stale while still
+ * running, which must abort the write rather than let it proceed.
+ * recordSessionRole/forgetSession below both call it this way.
+ *
+ * Exported for the regression suite too (round-2's steal/release race and
+ * round-4's evicted-while-stalled-commit race both need to drive the raw
+ * lock from real, separate OS processes with an artificially slow critical
+ * section — recordSessionRole's own critical section is too fast to reliably
+ * manufacture either race).
+ */
+export function withSessionLock(fn) {
+    const { dir, token, release } = acquireSessionLock();
+    try {
+        return fn(() => verifyStillOwned(dir, token));
+    }
+    finally {
+        release();
+    }
+}
+/**
+ * Bind THIS session (the process tree the caller runs inside, or its durable
+ * env id) to a role. Returns the session key, or null if neither an env id
+ * nor a readable ancestry was available (caller should say so — silent
+ * identity failure is the enemy). The whole read-modify-write cycle runs
+ * under the session-store lock so concurrent recordSessionRole calls (from
+ * different sessions, different processes) serialize instead of racing.
+ * `verifyOwned()` runs immediately before the commit (round-4 ai-review):
+ * see withSessionLock's doc comment — an evicted-while-stalled hold aborts
+ * here with SessionStoreError instead of writing.
+ */
+export function recordSessionRole(role) {
+    const key = sessionKey();
+    if (!key)
+        return null;
+    return withSessionLock((verifyOwned) => {
+        const store = pruneDead(loadSessions());
+        store.entries = store.entries.filter((e) => e.key !== key);
+        store.entries.push({ key, role, added_at: new Date().toISOString() });
+        verifyOwned();
+        saveSessions(store);
+        return key;
+    });
+}
+/**
+ * Explicit forget for THIS session's entry — the escape hatch age-pruning
+ * exists alongside for durable env-keyed entries (they otherwise outlive
+ * their process by design and are never reaped by death). Returns the
+ * forgotten role, or null if this session had no entry to forget. Locked for
+ * the same reason as recordSessionRole above — it's the same read-modify-write
+ * shape over the same shared file, including the pre-commit `verifyOwned()`.
+ */
+export function forgetSession() {
+    const key = sessionKey();
+    if (!key)
+        return null;
+    return withSessionLock((verifyOwned) => {
+        const store = pruneDead(loadSessions());
+        const hit = store.entries.find((e) => e.key === key);
+        if (!hit)
+            return null;
+        store.entries = store.entries.filter((e) => e.key !== key);
+        verifyOwned();
+        saveSessions(store);
+        return hit.role;
+    });
+}
+/** True for an env-keyed (durable) entry old enough that the 30-day age
+ * policy says it's gone — the same test pruneDead applies at write time,
+ * applied here too so resolution enforces it on every read, not only when
+ * some other call happens to trigger a prune-and-save. Pid-keyed entries are
+ * never subject to this: their prune signal is process liveness, unrelated to
+ * age (pruneDead's own contract, unchanged here). */
+function isExpiredEnvEntry(e) {
+    if (isPidKeyed(e.key))
+        return false;
+    return Date.now() - new Date(e.added_at).getTime() > ENV_KEY_MAX_AGE_MS;
+}
+export function resolveSession() {
+    const key = sessionKey();
+    if (!key)
+        return { status: "none" };
+    const hit = loadSessions().entries.find((e) => e.key === key);
+    if (!hit)
+        return { status: "none" };
+    // Expired-by-age is resolved as "dead", never "none": this session WAS
+    // checked in (an entry exists), so resolution must stop here loudly rather
+    // than silently falling through to a cwd binding (§2.4 precedent 3).
+    if (isExpiredEnvEntry(hit))
+        return { status: "dead", role: hit.role };
+    const entry = loadRoles().roles[hit.role];
+    if (!entry || (!entry.token && !entry.assume))
+        return { status: "dead", role: hit.role };
+    return { status: "ok", role: hit.role, entry };
+}
+/**
+ * The identity THIS session was checked into, resolved against the role
+ * store, or null (covers BOTH "never checked in" and "checked in but dead" —
+ * callers that must tell those apart use resolveSession() instead). Sits
+ * between env and the directory binding in resolveConfig's precedence: a
+ * session's own checkin beats the dir default, which is what lets N agents
+ * share one repository.
+ */
+export function sessionIdentity() {
+    const r = resolveSession();
+    return r.status === "ok" ? { role: r.role, entry: r.entry } : null;
+}
+//# sourceMappingURL=sessionstore.js.map