@pugi/cli 0.1.0-alpha.9 → 0.1.0-beta.2

package/dist/core/repl/slash-commands.js

@@ -1,5 +1,5 @@
 /**
- * REPL slash command registry — Sprint α5.7, expanded α6.14 wave 2.
+ * REPL slash command registry - Sprint α5.7, expanded α6.14 wave 2.
  *
  * The REPL input box surfaces a palette of slash commands the operator
  * can run from inside a persistent session. The wave-2 expansion (CEO
@@ -15,44 +15,35 @@
  *
  * Tiering (per CEO wave-2 spec):
  *
- *   Tier 1 — wired against real state (3 + existing 6 = 9 wired):
+ *   Tier 1 - wired against real state (3 + existing 6 = 9 wired):
  *     brief, agents, stop, help, quit, web, clear, version, jobs.
  *
- *   Tier 2 — best-effort wiring against existing surfaces (3):
+ *   Tier 2 - best-effort wiring against existing surfaces (3):
  *     diff, cost, status.
  *
- *   Tier 3 — deterministic stubs ("coming in αX.Y") (8):
+ *   Tier 3 - deterministic stubs ("coming in αX.Y") (8):
  *     compact, resume, memory, config, privacy, budget, mcp, undo.
  *
  * Brand voice (brandbook §08): power words `brief / dispatch / stop /
  * agents / quit / shipped`. Tagline `Brief it. It ships.` reserved for
- * `/quit` confirmation and `/help` footer — never inline.
+ * `/quit` confirmation and `/help` footer - never inline.
  */
 import { listRoles } from '../agents/registry.js';
 /**
  * Deterministic stub copy returned by the Tier 3 commands. Spec'd
  * inline so the unit test can pin the exact text without poking at
  * the help overlay. The version tag at the end maps to the sprint we
- * intend to land the real wiring in.
+ * intend to land the real wiring in. Keyed by StubSlashCommandName
+ * (not the full SlashCommandName union) so wired commands cannot
+ * silently appear here with empty placeholders.
  */
 export const SLASH_STUB_MESSAGES = Object.freeze({
-    brief: '',
-    agents: '',
-    stop: '',
-    help: '',
-    quit: '',
-    web: '',
-    clear: '',
-    version: '',
-    jobs: '',
-    diff: '',
-    cost: '',
-    status: '',
-    compact: 'Manual context compaction lands in α6.5.',
-    resume: 'Resume last session lands in α6.4 once SQLite session.db lands.',
-    memory: 'Session memory editor lands in α6.5.',
+    compact: 'Manual context compaction lands in α6.5b.',
+    memory: 'Session memory editor lands in α6.5b.',
     config: 'Run `pugi config list` from a fresh shell for the full surface; in-REPL editor lands in α6.5.',
-    privacy: 'Run `pugi privacy show` from a fresh shell; in-REPL toggle lands in α6.5.',
+    // alpha 6.13: /privacy graduated from stub; nothing reads this at
+    // runtime but the type record stays exhaustive.
+    privacy: '',
     budget: 'Run `pugi budget` from a fresh shell; in-REPL summary lands in α6.5.',
     mcp: 'Run `pugi config mcp list` from a fresh shell; in-REPL palette lands in α6.5.',
     undo: 'Run `pugi undo` from a fresh shell; in-REPL undo lands in α6.5.',
@@ -63,19 +54,22 @@ export const SLASH_COMMAND_HELP = Object.freeze([
     { name: 'agents', args: '', gloss: 'List the on-watch agent roster', group: 'Workforce dispatch' },
     { name: 'stop', args: '<persona>', gloss: 'Stop one agent by persona slug', group: 'Workforce dispatch' },
     { name: 'jobs', args: '', gloss: 'List background jobs', group: 'Workforce dispatch' },
+    { name: 'ask', args: '<question>', gloss: 'Surface a yes/no modal locally (α6.3 forcing question)', group: 'Workforce dispatch' },
     // Session
     { name: 'clear', args: '', gloss: 'Clear conversation pane', group: 'Session' },
-    { name: 'resume', args: '', gloss: 'Resume last session  (α6.4)', group: 'Session', stub: true },
-    { name: 'compact', args: '', gloss: 'Manual context compaction  (α6.5)', group: 'Session', stub: true },
-    { name: 'memory', args: '', gloss: 'Session memory editor  (α6.5)', group: 'Session', stub: true },
+    { name: 'resume', args: '', gloss: 'Pick a stored session to restore', group: 'Session' },
+    { name: 'context', args: '', gloss: 'Show three-tier context summary (Tier 0 skeleton + Tier 1 working set)', group: 'Session' },
+    { name: 'compact', args: '', gloss: 'Manual context compaction  (α6.5b)', group: 'Session', stub: true },
+    { name: 'memory', args: '', gloss: 'Session memory editor  (α6.5b)', group: 'Session', stub: true },
     // Pugi tools
     { name: 'web', args: '<url>', gloss: 'Fetch a URL into context', group: 'Pugi tools' },
     { name: 'diff', args: '', gloss: 'Show pending diff', group: 'Pugi tools' },
     { name: 'cost', args: '', gloss: 'Token usage + budget', group: 'Pugi tools' },
     { name: 'status', args: '', gloss: 'Backend + tenant status', group: 'Pugi tools' },
+    { name: 'consensus', args: '[ref]', gloss: '3-model consensus review (codex · claude · deepseek)', group: 'Pugi tools' },
     // Settings
     { name: 'config', args: '', gloss: 'Show config', group: 'Settings', stub: true },
-    { name: 'privacy', args: '', gloss: 'Show privacy mode', group: 'Settings', stub: true },
+    { name: 'privacy', args: '', gloss: 'Show privacy mode + contract', group: 'Settings' },
     { name: 'budget', args: '', gloss: 'Show usage budget', group: 'Settings', stub: true },
     { name: 'mcp', args: '', gloss: 'List MCP servers', group: 'Settings', stub: true },
     { name: 'undo', args: '', gloss: 'Undo last write', group: 'Settings', stub: true },
@@ -101,7 +95,7 @@ export const SLASH_COMMAND_GROUPS = Object.freeze([
  *   - Empty / whitespace-only input returns `noop` with the original
  *     text so the REPL can ignore it without printing anything.
  *   - Input that does not start with `/` is treated as an implicit
- *     `/brief <text>` — the most-common operator action.
+ *     `/brief <text>` - the most-common operator action.
  *   - `/<name> [args]` resolves the name against the registry; unknown
  *     names return `error` so the REPL can render a one-line tip
  *     instead of silently dropping the input.
@@ -109,7 +103,7 @@ export const SLASH_COMMAND_GROUPS = Object.freeze([
  *     can render the deterministic "coming in αX.Y" copy uniformly.
  *
  * The function never throws. Bad input maps to a structured result the
- * REPL can render — the alternative (throwing from a keystroke handler)
+ * REPL can render - the alternative (throwing from a keystroke handler)
  * would unmount Ink mid-frame.
  */
 export function parseSlashCommand(input) {
@@ -178,6 +172,12 @@ export function parseSlashCommand(input) {
         case 'jobs': {
             return { kind: 'jobs' };
         }
+        case 'ask': {
+            if (tail.length === 0) {
+                return { kind: 'error', message: 'Usage: /ask <question>' };
+            }
+            return { kind: 'ask', question: tail };
+        }
         case 'diff': {
             return { kind: 'diff' };
         }
@@ -187,18 +187,45 @@ export function parseSlashCommand(input) {
         case 'status': {
             return { kind: 'status' };
         }
+        case 'consensus':
+        case 'review-consensus': {
+            // Optional argument: a ref string forwarded verbatim to the
+            // consensus diff-capture (`HEAD~1`, `--pr 123`, etc). Empty tail
+            // means "default base ref".
+            return { kind: 'consensus', ref: tail };
+        }
+        case 'resume': {
+            // α6.4: wired against the local SessionStore. The REPL session
+            // owns the picker UI (Ink select over the 10 most recent rows)
+            // so the slash-command layer stays UI-agnostic.
+            return { kind: 'resume' };
+        }
+        case 'context':
+        case 'ctx': {
+            // α6.5: surface Tier 0 + Tier 1 status. The session module
+            // renders the summary as system lines so the operator can see
+            // skeleton size + working-set utilisation at a glance.
+            return { kind: 'context' };
+        }
+        case 'privacy': {
+            // alpha 6.13: real handler - the session module prints the
+            // contract doc + the current mode banner. Tail is ignored (no
+            // sub-commands today; mode flips go through
+            // `pugi config set privacy=<mode>` from a fresh shell so the
+            // device flow + audit identity are wired correctly).
+            return { kind: 'privacy' };
+        }
         case 'compact':
-        case 'resume':
         case 'memory':
         case 'config':
-        case 'privacy':
         case 'budget':
         case 'mcp':
         case 'undo': {
+            const stubName = name;
             return {
                 kind: 'stub',
-                name: name,
-                message: SLASH_STUB_MESSAGES[name],
+                name: stubName,
+                message: SLASH_STUB_MESSAGES[stubName],
             };
         }
         default: {

package/dist/core/repl/store/index.js

@@ -0,0 +1,12 @@
+/**
+ * Public re-exports for the SessionStore module — Sprint α6.4.
+ *
+ * Consumers (`repl/session.ts`, `runtime/cli.ts`, the `/resume`
+ * dispatcher) import from `./store/index.js` so the internal split
+ * (types / lockfile / jsonl-log / session-store / uuid-v7) can change
+ * without touching the call sites.
+ */
+export { SessionLockBusyError, } from './types.js';
+export { SqliteSessionStore, SqliteSessionStoreReadOnlyView, FtsSyntaxError, resolveProjectStoreDir, } from './session-store.js';
+export { uuidV7, uuidV7Timestamp } from './uuid-v7.js';
+//# sourceMappingURL=index.js.map

package/dist/core/repl/store/jsonl-log.js

@@ -0,0 +1,321 @@
+/**
+ * Append-only JSONL event log — Sprint α6.4 (PR-PUGI-CLI-SESSION-STORE).
+ *
+ * Durable truth for the session. The SQLite index is rebuildable from
+ * the JSONL; if the index is lost or corrupt, `pugi sessions --rebuild`
+ * walks every line and reconstructs the table. The JSONL is therefore
+ * the source of truth and the SQLite is the cache.
+ *
+ * File layout per session directory:
+ *
+ *   <sessionDir>/events.0.jsonl       active rotation file
+ *   <sessionDir>/events.1.jsonl       previous rotation, oldest event first
+ *   <sessionDir>/events.2.jsonl       older still
+ *   ...
+ *
+ * Rotation threshold is 50 MB per spec §4.2 must-ship #2. When the
+ * active file exceeds the threshold AFTER a write, we close it, rename
+ * it to the next numbered slot, and resume appending to a fresh
+ * `events.0.jsonl`. The reader stitches across files in REVERSE numeric
+ * order so the on-disk order is preserved.
+ *
+ * Crash safety:
+ *
+ *   - Each write is a single `appendFileSync` of `JSON.stringify(event)\n`.
+ *     On Linux/macOS, append-mode writes of bytes < PIPE_BUF (4096) are
+ *     atomic with respect to other appends. Our events are well under
+ *     4 KB so the OS guarantees per-line atomicity even if two
+ *     processes hold append fds (the lockfile already prevents that,
+ *     but defence-in-depth).
+ *   - After each write we call `fsync(fd)` so the bytes are durable
+ *     against power loss / kernel panic. Slow but correct — the
+ *     conversation-flow path is throughput-bound by the LLM, not by
+ *     the disk, so a few hundred extra microseconds per event is
+ *     invisible to the operator.
+ *   - On reopen we walk every line and drop any that fail JSON parse.
+ *     A crash mid-write leaves a truncated tail; we treat it as
+ *     "event was never written" and continue from there. The next
+ *     write may overlap with the truncated bytes; that is acceptable
+ *     because the truncated line is invalid JSON either way and the
+ *     reader is already designed to skip it.
+ */
+import { closeSync, existsSync, fsyncSync, mkdirSync, openSync, readdirSync, readFileSync, renameSync, statSync, writeSync, } from 'node:fs';
+import { resolve } from 'node:path';
+/**
+ * Rotate the active JSONL file when its size exceeds this threshold.
+ * Picked per spec §4.2. Operators can override via the
+ * `PUGI_SESSION_LOG_ROTATE_BYTES` env so heavy-traffic dogfooding can
+ * keep more events in the active file before rotation.
+ */
+const DEFAULT_ROTATE_BYTES = 50 * 1024 * 1024;
+/**
+ * Active JSONL filename. The store opens fd against this path; the
+ * reader stitches across `events.<n>.jsonl` for n > 0.
+ */
+const ACTIVE_FILE = 'events.0.jsonl';
+/**
+ * Append-only writer + reader for one session's JSONL log. The writer
+ * keeps a fd open for the lifetime of the session so each append
+ * avoids a fresh syscall pair; the fd is reopened transparently on
+ * rotation. `close()` releases the fd and is idempotent.
+ */
+export class JsonlEventLog {
+    sessionDir;
+    rotateBytes;
+    activeFd = null;
+    activeBytes = 0;
+    constructor(opts) {
+        this.sessionDir = opts.sessionDir;
+        this.rotateBytes =
+            opts.rotateBytes
+                ?? readEnvInt('PUGI_SESSION_LOG_ROTATE_BYTES')
+                ?? DEFAULT_ROTATE_BYTES;
+        mkdirSync(this.sessionDir, { recursive: true, mode: 0o700 });
+    }
+    /**
+     * Append one event. Returns the on-disk byte length written so the
+     * caller can budget without re-stat()-ing the file. The write is
+     * fsynced before this call returns.
+     *
+     * Rotation runs AFTER the event is durable. A rotation failure does
+     * NOT roll back the write — the event is already on disk. The error
+     * is surfaced to the caller so the operator knows the rotation
+     * threshold was tripped but the underlying filesystem refused the
+     * rename (EPERM / EXDEV / ENOSPC during rename). The next append
+     * will attempt rotation again from a fresh ensureFd().
+     */
+    append(event) {
+        const line = `${JSON.stringify(event)}\n`;
+        const fd = this.ensureFd();
+        const bytes = Buffer.byteLength(line, 'utf8');
+        writeSync(fd, line, null, 'utf8');
+        fsyncSync(fd);
+        this.activeBytes += bytes;
+        if (this.activeBytes >= this.rotateBytes) {
+            this.rotate();
+        }
+        return bytes;
+    }
+    /**
+     * Load events in insertion order. Stitches across rotation files in
+     * REVERSE numeric order (events.N.jsonl ... events.0.jsonl) so the
+     * returned stream is oldest-first.
+     *
+     * `fromOffset` skips the first N events from the stitched stream;
+     * `limit` caps the returned count. Defaults: return all events.
+     */
+    read(opts) {
+        const files = this.discoverRotationFiles();
+        // Reverse numeric order so events.N.jsonl (oldest) is read first.
+        const ordered = files.slice().sort((a, b) => b.index - a.index);
+        const fromOffset = Math.max(0, opts?.fromOffset ?? 0);
+        const limit = clampLimit(opts?.limit ?? Number.MAX_SAFE_INTEGER);
+        const out = [];
+        let skipped = 0;
+        for (const file of ordered) {
+            const raw = safeReadText(file.path);
+            if (raw.length === 0)
+                continue;
+            for (const line of raw.split('\n')) {
+                const trimmed = line.trim();
+                if (trimmed.length === 0)
+                    continue;
+                const parsed = safeParseEvent(trimmed);
+                if (!parsed)
+                    continue;
+                if (skipped < fromOffset) {
+                    skipped += 1;
+                    continue;
+                }
+                out.push(parsed);
+                if (out.length >= limit)
+                    return out;
+            }
+        }
+        return out;
+    }
+    /**
+     * Count the total events on disk (across all rotation files). Used
+     * by the SessionStore to reconcile `event_count` on the SQLite row
+     * after a crash recovery walk.
+     */
+    countEvents() {
+        const files = this.discoverRotationFiles();
+        let total = 0;
+        for (const file of files) {
+            const raw = safeReadText(file.path);
+            if (raw.length === 0)
+                continue;
+            for (const line of raw.split('\n')) {
+                const trimmed = line.trim();
+                if (trimmed.length === 0)
+                    continue;
+                if (safeParseEvent(trimmed))
+                    total += 1;
+            }
+        }
+        return total;
+    }
+    /** Release the file descriptor. Idempotent. */
+    close() {
+        if (this.activeFd !== null) {
+            try {
+                fsyncSync(this.activeFd);
+            }
+            catch {
+                /* ignore — fd may have been closed elsewhere */
+            }
+            try {
+                closeSync(this.activeFd);
+            }
+            catch {
+                /* ignore */
+            }
+            this.activeFd = null;
+        }
+    }
+    ensureFd() {
+        if (this.activeFd !== null)
+            return this.activeFd;
+        const path = resolve(this.sessionDir, ACTIVE_FILE);
+        // Read the existing size BEFORE opening with 'a' — `openSync(path,
+        // 'a', ...)` creates the file when missing, which makes a post-open
+        // `existsSync` always true. If a previous rotate() failed midway
+        // and left stale bytes at this path, we want `activeBytes` to
+        // inherit the real pre-open size so the next append accounting is
+        // consistent. Without this ordering the rotate-threshold check
+        // tripped on a fresh 0-byte file holding pre-rotation bytes,
+        // causing an immediate re-rotation loop.
+        let preOpenBytes = 0;
+        try {
+            preOpenBytes = existsSync(path) ? statSync(path).size : 0;
+        }
+        catch {
+            preOpenBytes = 0;
+        }
+        // O_APPEND so concurrent appends from a future feature (e.g. an
+        // out-of-band tool process) cannot overwrite each other. The
+        // lockfile already serializes us; this is defence-in-depth.
+        this.activeFd = openSync(path, 'a', 0o600);
+        this.activeBytes = preOpenBytes;
+        return this.activeFd;
+    }
+    /**
+     * Close the active file, shift every existing rotation file's number
+     * up by one (events.N -> events.N+1), and reopen a fresh
+     * events.0.jsonl. Synchronous and rare (50 MB / few-KB events =
+     * thousands of events between rotations).
+     *
+     * A rename failure is NOT swallowed — we rethrow so the caller knows
+     * the active file is over the threshold but the data inside it is
+     * still durable (we already fsynced before invoking rotate). Without
+     * the rethrow, ensureFd() inherited the pre-rotation size on the
+     * next append and tripped an infinite re-rotation loop.
+     */
+    rotate() {
+        this.close();
+        const files = this.discoverRotationFiles();
+        // Rename in REVERSE order so we never clobber an existing slot.
+        const ordered = files.slice().sort((a, b) => b.index - a.index);
+        const renameErrors = [];
+        for (const file of ordered) {
+            const next = resolve(this.sessionDir, `events.${file.index + 1}.jsonl`);
+            try {
+                renameSync(file.path, next);
+            }
+            catch (err) {
+                // Collect every failed rename so the caller sees the full
+                // picture instead of just the first failure. We still
+                // continue the loop: any rename that succeeds shifts at
+                // least some history out of the way.
+                renameErrors.push(err instanceof Error ? err : new Error(String(err)));
+            }
+        }
+        this.activeBytes = 0;
+        if (renameErrors.length > 0) {
+            const msg = renameErrors.map((e) => e.message).join('; ');
+            const wrapped = new Error(`JSONL rotation failed in ${this.sessionDir}: ${msg}. ` +
+                'The data already on disk is safe; the active log may exceed ' +
+                'the configured threshold until the underlying issue is fixed.');
+            // Preserve the original errors on .cause for upstream
+            // observability. Node 16.9+ supports the standard cause field.
+            wrapped.cause = renameErrors;
+            throw wrapped;
+        }
+        // Lazily reopen on next append.
+    }
+    /**
+     * Walk the session directory and return every `events.<n>.jsonl`
+     * file with its numeric index. Sort order is left to the caller.
+     */
+    discoverRotationFiles() {
+        if (!existsSync(this.sessionDir))
+            return [];
+        let entries;
+        try {
+            entries = readdirSync(this.sessionDir);
+        }
+        catch {
+            return [];
+        }
+        const out = [];
+        for (const name of entries) {
+            const match = /^events\.(\d+)\.jsonl$/.exec(name);
+            if (!match)
+                continue;
+            const index = Number.parseInt(match[1] ?? '', 10);
+            if (!Number.isFinite(index))
+                continue;
+            out.push({ index, path: resolve(this.sessionDir, name) });
+        }
+        return out;
+    }
+}
+function safeReadText(path) {
+    try {
+        return readFileSync(path, 'utf8');
+    }
+    catch {
+        return '';
+    }
+}
+function safeParseEvent(line) {
+    try {
+        const parsed = JSON.parse(line);
+        if (typeof parsed === 'object'
+            && parsed !== null
+            && typeof parsed.t === 'number'
+            && typeof parsed.kind === 'string') {
+            // `payload` may be undefined on the wire (older clients); coerce
+            // to null so the consumer never has to type-narrow `unknown |
+            // undefined`.
+            const payload = parsed.payload ?? null;
+            return {
+                t: parsed.t,
+                kind: parsed.kind,
+                payload,
+            };
+        }
+    }
+    catch {
+        /* fall through — truncated tail, JSON parse error */
+    }
+    return null;
+}
+function clampLimit(raw) {
+    if (!Number.isFinite(raw) || raw <= 0)
+        return 1;
+    if (raw > 100000)
+        return 100000;
+    return Math.floor(raw);
+}
+function readEnvInt(key) {
+    const raw = process.env[key];
+    if (!raw)
+        return undefined;
+    const n = Number.parseInt(raw, 10);
+    if (!Number.isFinite(n) || n <= 0)
+        return undefined;
+    return n;
+}
+//# sourceMappingURL=jsonl-log.js.map

package/dist/core/repl/store/lockfile.js

@@ -0,0 +1,155 @@
+/**
+ * PID lockfile — Sprint α6.4 (PR-PUGI-CLI-SESSION-STORE).
+ *
+ * Prevents two REPL processes in the same project directory from
+ * writing to the same `session.db` concurrently. SQLite's WAL handles
+ * that case correctly at the page level, but the JSONL event log lives
+ * outside the SQL transaction — concurrent appends from two processes
+ * would interleave events. The lockfile is the higher-level mutex.
+ *
+ * Algorithm:
+ *
+ *   1. Try `O_CREAT | O_EXCL` open of `<dir>/session.lock`. Write the
+ *      caller's PID + process start time as the body. If the open
+ *      succeeds, we hold the lock; return.
+ *   2. If `EEXIST`, read the existing PID. Probe with `kill(pid, 0)`
+ *      (signal 0 = "check liveness, do not deliver"). If the probe
+ *      returns ESRCH, the holder is dead — unlink the stale lock and
+ *      retry the exclusive create.
+ *   3. If the probe says the PID is alive, throw `SessionLockBusyError`
+ *      so the caller surfaces a clean message to the operator.
+ *
+ * Why not `proper-lockfile`: pulling a 14kB dependency for a 60-line
+ * PID file is poor cost/benefit. The stale-detection loop is the only
+ * tricky part and we test it explicitly. The dependency would also
+ * pull `signal-exit` + `retry` transitively, raising the install
+ * footprint of the CLI bundle.
+ *
+ * Brand voice / privacy: the lockfile body is `{"pid":N,"createdAt":"…"}`
+ * — operator-readable if they `cat` the file, no secrets. Mode 0600 so
+ * other users on the box cannot read which PID is editing the store.
+ */
+import { closeSync, openSync, readFileSync, unlinkSync, writeSync, } from 'node:fs';
+import { SessionLockBusyError } from './types.js';
+/**
+ * Take an exclusive lock on `lockPath`. Throws `SessionLockBusyError`
+ * if a live process already holds the lock. `kill` is injectable for
+ * tests so the stale-detection branch is exercisable without spawning
+ * a real child process.
+ */
+export function takeLock(lockPath, options) {
+    const kill = options?.kill ?? ((pid, signal) => process.kill(pid, signal));
+    const now = options?.now ?? (() => new Date());
+    const body = { pid: process.pid, createdAt: now().toISOString() };
+    const serialized = JSON.stringify(body);
+    // First attempt: exclusive create. Retry once if the existing lock
+    // turns out to be stale (dead PID).
+    for (let attempt = 0; attempt < 2; attempt += 1) {
+        try {
+            const fd = openSync(lockPath, 'wx', 0o600);
+            try {
+                writeSync(fd, serialized);
+            }
+            finally {
+                closeSync(fd);
+            }
+            return { path: lockPath, release: () => releaseLock(lockPath, process.pid) };
+        }
+        catch (error) {
+            // EEXIST is the only branch that triggers stale-detection. Any
+            // other error (EACCES, ENOENT on parent, ENOSPC) propagates so
+            // the caller sees the real failure.
+            if (!isEexist(error)) {
+                throw error;
+            }
+            const holder = readLockBody(lockPath);
+            if (!holder) {
+                // Corrupt body — treat as stale and unlink.
+                tryUnlink(lockPath);
+                continue;
+            }
+            if (holder.pid === process.pid) {
+                // We already hold the lock (reentrant open from same process).
+                // Return a handle that is a no-op on release; the original
+                // owner's release will unlink.
+                return { path: lockPath, release: () => undefined };
+            }
+            if (isAlive(holder.pid, kill)) {
+                throw new SessionLockBusyError(holder.pid, lockPath);
+            }
+            // Stale lock — unlink and retry the exclusive create.
+            tryUnlink(lockPath);
+        }
+    }
+    // Two retries failed — the lock is contested by another process
+    // racing us. Surface as busy rather than spinning.
+    const holder = readLockBody(lockPath);
+    throw new SessionLockBusyError(holder?.pid ?? 0, lockPath);
+}
+/**
+ * Read a lockfile body. Returns null when the file is missing,
+ * unreadable, or malformed. The store never throws from this path —
+ * the caller treats null as "stale, unlink and retry".
+ */
+export function readLockBody(lockPath) {
+    let raw;
+    try {
+        raw = readFileSync(lockPath, 'utf8');
+    }
+    catch {
+        return null;
+    }
+    try {
+        const parsed = JSON.parse(raw);
+        if (typeof parsed === 'object'
+            && parsed !== null
+            && typeof parsed.pid === 'number'
+            && typeof parsed.createdAt === 'string') {
+            return parsed;
+        }
+    }
+    catch {
+        /* fall through */
+    }
+    return null;
+}
+function isAlive(pid, kill) {
+    if (!Number.isFinite(pid) || pid <= 0)
+        return false;
+    try {
+        kill(pid, 0);
+        return true;
+    }
+    catch (error) {
+        // ESRCH = no such process. Any other error (EPERM = process exists
+        // but we lack permission) means the process IS alive.
+        const code = error?.code;
+        if (code === 'ESRCH')
+            return false;
+        return true;
+    }
+}
+function releaseLock(lockPath, expectedPid) {
+    const holder = readLockBody(lockPath);
+    if (!holder)
+        return;
+    // Defence-in-depth: only unlink if we still own the lock. A future
+    // session may have taken over after our process died and was
+    // replaced — better to leave the new owner's file in place than to
+    // race-condition delete it.
+    if (holder.pid !== expectedPid)
+        return;
+    tryUnlink(lockPath);
+}
+function tryUnlink(path) {
+    try {
+        unlinkSync(path);
+    }
+    catch {
+        /* ignore — file may be gone already */
+    }
+}
+function isEexist(error) {
+    return error?.code === 'EEXIST';
+}
+//# sourceMappingURL=lockfile.js.map