@cruxy/cli 1.11.0 → 1.11.2

package/dist/indexing/model-cache.js

@@ -0,0 +1,399 @@
+import { randomBytes } from "node:crypto";
+import { promises as fs } from "node:fs";
+import path from "node:path";
+import { EnvHttpProxyAgent, fetch as undiciFetch } from "undici";
+import { extract as tarExtract } from "tar";
+/**
+ * Cruxy-owned download + extraction of the local embedding model.
+ *
+ * Why this exists (#306): fastembed's own `retrieveModel` extracts the model
+ * tarball with `tar@6.2.1`, which carries a family of path-traversal /
+ * symlink-poisoning advisories, has no fixed 6.x, and cannot be overridden to
+ * tar 7 (fastembed does `import tar from "tar"`; tar 7 has no default export —
+ * the override was tested and breaks `cruxy index` at module link). fastembed
+ * 2.1.0 is its latest release and pins `tar ^6.2.0`.
+ *
+ * So cruxy provisions the model directory itself and hands fastembed an
+ * absolute path via `model: CUSTOM` + `modelAbsoluteDirPath`. In fastembed's
+ * `init`, `retrieveModel` sits on the other arm of a ternary on `CUSTOM`, so it
+ * is unreachable once we go through this module — tar 6 stays in the
+ * dependency tree (scanners will keep flagging it) but never runs.
+ *
+ * This code writes to every user's disk, so the archive is treated as hostile:
+ *  - every entry is checked by an explicit allow-list (regular files and
+ *    directories only; a single top-level directory named for the model; no
+ *    `..`, absolute, drive-letter, backslash or NUL paths; bounded count and
+ *    size) — never the library's defaults alone. A refused entry fails the
+ *    whole extraction; it is never silently skipped.
+ *  - download and extraction happen in a staging directory next to the final
+ *    one; the final directory appears only via a rename after the required
+ *    file set has been verified, so an interrupted run can never leave a
+ *    directory that looks complete.
+ *  - a completion marker records the verified file sizes; a cache hit requires
+ *    the marker AND matching sizes, so a partial or tampered directory is
+ *    redone rather than used.
+ */
+/** Model directory name inside the cache; also the archive's top-level dir. */
+export const MODEL_NAME = "fast-bge-small-en-v1.5";
+/** Where fastembed (and Qdrant's Python fastembed) fetch this archive from. */
+export const MODEL_ARCHIVE_URL = `https://storage.googleapis.com/qdrant-fastembed/${MODEL_NAME}.tar.gz`;
+/** The ONNX graph fastembed loads from the model directory. */
+export const MODEL_ONNX_FILE = "model_optimized.onnx";
+/**
+ * Files fastembed's `init` reads. The archive also ships `ort_config.json` and
+ * `vocab.txt`; they are extracted if present but not required.
+ */
+export const REQUIRED_FILES = [
+    "config.json",
+    MODEL_ONNX_FILE,
+    "special_tokens_map.json",
+    "tokenizer.json",
+    "tokenizer_config.json",
+];
+/** Written into the model dir after verification; absent ⇒ incomplete. */
+export const MARKER_FILE = ".cruxy-model.json";
+/** Compressed archive ceiling (the real one is ~77 MB). */
+export const MAX_ARCHIVE_BYTES = 512 * 1024 * 1024;
+/** Sum of declared entry sizes ceiling (the real one is ~134 MB). */
+export const MAX_EXTRACTED_BYTES = 1024 * 1024 * 1024;
+/** Entry-count ceiling (the real archive has 8). */
+export const MAX_ENTRIES = 64;
+/** Abort the download if no bytes arrive for this long. */
+const IDLE_TIMEOUT_MS = 60_000;
+/** Staging dirs older than this are leftovers of a dead run and are swept. */
+const STALE_STAGING_MS = 6 * 60 * 60 * 1000;
+/**
+ * Failure of the download / extraction / verification pipeline. `kind` lets
+ * the caller pick next steps: a `download` failure is the classic offline
+ * first run; `refused` means the archive contained an entry the allow-list
+ * rejected (retrying blindly is wrong); `incomplete` means the archive did not
+ * contain the required file set, or the extracted set failed verification.
+ */
+export class ModelCacheError extends Error {
+    kind;
+    constructor(kind, message, cause) {
+        super(message, cause === undefined ? undefined : { cause });
+        this.name = "ModelCacheError";
+        this.kind = kind;
+    }
+}
+/**
+ * Ensure `<cacheDir>/<MODEL_NAME>` holds a verified, complete model and return
+ * that absolute path. Downloads and extracts only when the cache is missing or
+ * fails verification; never trusts a directory without its marker.
+ */
+export async function ensureModelDir(opts) {
+    const cacheDir = path.resolve(opts.cacheDir);
+    const modelDir = path.join(cacheDir, MODEL_NAME);
+    if (await isCompleteModelDir(modelDir))
+        return modelDir;
+    await fs.mkdir(cacheDir, { recursive: true });
+    await sweepStaleStaging(cacheDir);
+    // Stage next to the destination so the final publish is a same-filesystem
+    // rename (atomic on POSIX; on Windows it either succeeds or throws).
+    const stagingDir = path.join(cacheDir, `.${MODEL_NAME}.tmp-${process.pid}-${randomBytes(4).toString("hex")}`);
+    const archivePath = `${stagingDir}.tar.gz`;
+    try {
+        await fs.mkdir(stagingDir, { recursive: true });
+        await downloadArchive(opts.url ?? MODEL_ARCHIVE_URL, archivePath, opts.fetchImpl, opts.onProgress);
+        opts.onProgress?.({ phase: "extract" });
+        await extractArchive(archivePath, stagingDir);
+        opts.onProgress?.({ phase: "verify" });
+        const extracted = path.join(stagingDir, MODEL_NAME);
+        const files = await verifyModelDir(extracted);
+        await writeMarker(extracted, files);
+        await publish(extracted, modelDir);
+        return modelDir;
+    }
+    finally {
+        await fs.rm(archivePath, { force: true }).catch(() => { });
+        await fs.rm(stagingDir, { recursive: true, force: true }).catch(() => { });
+    }
+}
+/**
+ * True only when the marker exists, parses, names this model, and every
+ * required file is a regular file whose size matches the marker. Anything
+ * else — a missing marker (a partial or legacy extraction), a size mismatch,
+ * a symlink where a file should be — is "incomplete" and gets redone.
+ */
+export async function isCompleteModelDir(modelDir) {
+    let marker;
+    try {
+        const raw = await fs.readFile(path.join(modelDir, MARKER_FILE), "utf8");
+        marker = JSON.parse(raw);
+    }
+    catch {
+        return false;
+    }
+    if (!marker ||
+        marker.version !== 1 ||
+        marker.model !== MODEL_NAME ||
+        typeof marker.files !== "object" ||
+        marker.files === null) {
+        return false;
+    }
+    for (const name of REQUIRED_FILES) {
+        const expected = marker.files[name];
+        if (typeof expected !== "number" || expected <= 0)
+            return false;
+        const st = await fs.lstat(path.join(modelDir, name)).catch(() => null);
+        if (!st || !st.isFile() || st.size !== expected)
+            return false;
+    }
+    return true;
+}
+// ── download ──────────────────────────────────────────────────────────────────
+async function downloadArchive(url, dest, fetchImpl, onProgress) {
+    const doFetch = fetchImpl ?? undiciFetch;
+    const controller = new AbortController();
+    let idle;
+    const armIdle = () => {
+        if (idle)
+            clearTimeout(idle);
+        idle = setTimeout(() => controller.abort(new Error(`no data for ${IDLE_TIMEOUT_MS}ms`)), IDLE_TIMEOUT_MS);
+        idle.unref?.();
+    };
+    let res;
+    try {
+        armIdle();
+        res = await doFetch(url, {
+            signal: controller.signal,
+            redirect: "follow",
+            // Honor HTTPS_PROXY / NO_PROXY for this fixed, public URL (the web tool
+            // deliberately does not; it has an SSRF guard to protect instead). The
+            // agent is built only when a proxy is configured: undici prints an
+            // "experimental" warning on construction, and non-proxy users should
+            // never see it.
+            ...(fetchImpl || !proxyConfigured()
+                ? {}
+                : { dispatcher: new EnvHttpProxyAgent() }),
+        });
+    }
+    catch (err) {
+        if (idle)
+            clearTimeout(idle);
+        throw new ModelCacheError("download", `downloading ${url} failed: ${messageOf(err)}`, err);
+    }
+    try {
+        if (!res.ok) {
+            throw new ModelCacheError("download", `downloading ${url} failed: HTTP ${res.status}`);
+        }
+        const declared = Number(res.headers.get("content-length") ?? "");
+        if (Number.isFinite(declared) && declared > MAX_ARCHIVE_BYTES) {
+            throw new ModelCacheError("refused", `refused model archive: Content-Length ${declared} exceeds the ${MAX_ARCHIVE_BYTES}-byte ceiling`);
+        }
+        if (!res.body) {
+            throw new ModelCacheError("download", `downloading ${url}: empty body`);
+        }
+        const total = Number.isFinite(declared) && declared > 0 ? declared : undefined;
+        const fh = await fs.open(dest, "w");
+        let received = 0;
+        try {
+            for await (const chunk of res.body) {
+                armIdle();
+                received += chunk.byteLength;
+                if (received > MAX_ARCHIVE_BYTES) {
+                    controller.abort();
+                    throw new ModelCacheError("refused", `refused model archive: body exceeds the ${MAX_ARCHIVE_BYTES}-byte ceiling`);
+                }
+                await fh.write(chunk);
+                onProgress?.({ phase: "download", received, total });
+            }
+            if (total !== undefined && received !== total) {
+                throw new ModelCacheError("download", `downloading ${url}: connection closed after ${received} of ${total} bytes`);
+            }
+        }
+        catch (err) {
+            if (err instanceof ModelCacheError)
+                throw err;
+            throw new ModelCacheError("download", `downloading ${url} failed: ${messageOf(err)}`, err);
+        }
+        finally {
+            await fh.close();
+        }
+    }
+    finally {
+        if (idle)
+            clearTimeout(idle);
+    }
+}
+// ── extraction ────────────────────────────────────────────────────────────────
+/**
+ * Decide whether one archive entry may be written. Returns a reason string to
+ * refuse, or null to allow. Deliberately an allow-list: anything not proven
+ * safe is refused. Runs BEFORE tar's own checks, and independently of them.
+ */
+export function refuseEntry(entryPath, type, linkpath) {
+    if (type !== "File" && type !== "Directory") {
+        return `entry type ${type} is not allowed (${entryPath})`;
+    }
+    if (linkpath)
+        return `entry carries a link target (${entryPath})`;
+    if (entryPath.length === 0)
+        return "empty entry path";
+    if (entryPath.includes("\0"))
+        return "entry path contains NUL";
+    if (entryPath.includes("\\"))
+        return `entry path contains a backslash (${entryPath})`;
+    if (entryPath.startsWith("/"))
+        return `absolute entry path (${entryPath})`;
+    if (/^[A-Za-z]:/.test(entryPath))
+        return `drive-letter entry path (${entryPath})`;
+    const parts = entryPath.split("/");
+    // A directory entry may end with "/"; nothing else may have an empty segment.
+    if (type === "Directory" &&
+        parts.length > 1 &&
+        parts[parts.length - 1] === "") {
+        parts.pop();
+    }
+    for (const seg of parts) {
+        if (seg === "" || seg === "." || seg === "..") {
+            return `entry path has an empty, "." or ".." segment (${entryPath})`;
+        }
+    }
+    if (parts[0] !== MODEL_NAME) {
+        return `entry is outside the ${MODEL_NAME}/ directory (${entryPath})`;
+    }
+    if (type === "Directory" && parts.length !== 1) {
+        return `nested directory not allowed (${entryPath})`;
+    }
+    if (type === "File" && parts.length !== 2) {
+        return `file must sit directly under ${MODEL_NAME}/ (${entryPath})`;
+    }
+    return null;
+}
+async function extractArchive(archivePath, cwd) {
+    const refused = [];
+    let entries = 0;
+    let declaredBytes = 0;
+    // On the extract path tar always hands a ReadEntry (Stats is the create-side
+    // shape of the same option), but keep the narrowing explicit.
+    const filter = (entryPath, entry) => {
+        entries += 1;
+        if (entries > MAX_ENTRIES) {
+            refused.push(`more than ${MAX_ENTRIES} entries`);
+            return false;
+        }
+        if (!("header" in entry)) {
+            refused.push(`unexpected non-archive entry (${entryPath})`);
+            return false;
+        }
+        const reason = refuseEntry(entryPath, String(entry.type), entry.linkpath ? String(entry.linkpath) : undefined);
+        if (reason) {
+            refused.push(reason);
+            return false;
+        }
+        declaredBytes += Number(entry.size ?? 0);
+        if (declaredBytes > MAX_EXTRACTED_BYTES) {
+            refused.push(`declared size exceeds the ${MAX_EXTRACTED_BYTES}-byte ceiling`);
+            return false;
+        }
+        return true;
+    };
+    try {
+        await tarExtract({
+            file: archivePath,
+            cwd,
+            // tar's own guards stay on as a second layer: strict turns its warnings
+            // (e.g. its independent ".." detection) into errors; preservePaths=false
+            // keeps its absolute-path stripping; no ownership or mode replay.
+            strict: true,
+            preservePaths: false,
+            preserveOwner: false,
+            noChmod: true,
+            noMtime: true,
+            filter,
+        });
+    }
+    catch (err) {
+        if (refused.length > 0) {
+            throw new ModelCacheError("refused", `refused model archive: ${refused.join("; ")}`, err);
+        }
+        throw new ModelCacheError("incomplete", `extracting the model archive failed: ${messageOf(err)}`, err);
+    }
+    if (refused.length > 0) {
+        throw new ModelCacheError("refused", `refused model archive: ${refused.join("; ")}`);
+    }
+}
+// ── verification + publish ────────────────────────────────────────────────────
+/**
+ * Every required file must be a regular, non-empty file; nothing in the dir
+ * may be a symlink (belt and braces over the entry filter). Returns the size
+ * manifest for the marker.
+ */
+async function verifyModelDir(dir) {
+    const st = await fs.lstat(dir).catch(() => null);
+    if (!st || !st.isDirectory()) {
+        throw new ModelCacheError("incomplete", `model archive did not contain a ${MODEL_NAME}/ directory`);
+    }
+    const files = {};
+    for (const name of await fs.readdir(dir)) {
+        const s = await fs.lstat(path.join(dir, name));
+        if (s.isSymbolicLink()) {
+            throw new ModelCacheError("refused", `symlink found after extraction: ${name}`);
+        }
+        if (s.isFile())
+            files[name] = s.size;
+    }
+    const missing = REQUIRED_FILES.filter((n) => !(files[n] > 0));
+    if (missing.length > 0) {
+        throw new ModelCacheError("incomplete", `model archive is missing or has empty required file(s): ${missing.join(", ")}`);
+    }
+    return files;
+}
+async function writeMarker(dir, files) {
+    const marker = {
+        version: 1,
+        model: MODEL_NAME,
+        files,
+        extractedAt: new Date().toISOString(),
+    };
+    await fs.writeFile(path.join(dir, MARKER_FILE), JSON.stringify(marker, null, 2));
+}
+/** Rename the verified staging dir into place; tolerate a concurrent winner. */
+async function publish(from, to) {
+    try {
+        await fs.rename(from, to);
+        return;
+    }
+    catch (err) {
+        // Another process may have published a complete model meanwhile — accept
+        // it. Otherwise whatever is there failed verification: replace it.
+        if (await isCompleteModelDir(to))
+            return;
+        await fs.rm(to, { recursive: true, force: true });
+        try {
+            await fs.rename(from, to);
+        }
+        catch (err2) {
+            throw new ModelCacheError("incomplete", `could not move the verified model into ${to}: ${messageOf(err2)}`, err2 ?? err);
+        }
+    }
+}
+async function sweepStaleStaging(cacheDir) {
+    const prefix = `.${MODEL_NAME}.tmp-`;
+    const now = Date.now();
+    let names;
+    try {
+        names = await fs.readdir(cacheDir);
+    }
+    catch {
+        return;
+    }
+    for (const name of names) {
+        if (!name.startsWith(prefix))
+            continue;
+        const p = path.join(cacheDir, name);
+        const st = await fs.lstat(p).catch(() => null);
+        if (st && now - st.mtimeMs > STALE_STAGING_MS) {
+            await fs.rm(p, { recursive: true, force: true }).catch(() => { });
+        }
+    }
+}
+function proxyConfigured() {
+    const env = process.env;
+    return Boolean(env.HTTPS_PROXY || env.https_proxy || env.HTTP_PROXY || env.http_proxy);
+}
+function messageOf(err) {
+    return err instanceof Error ? err.message : String(err);
+}

package/dist/render/context-view.js

@@ -26,7 +26,11 @@ import { fit } from "./layout.js";
  *
  * The reserve is shown as its own row rather than folded into a total. It is
  * part of `used`, it is present in no message, and a breakdown that omitted it
- * would leave several thousand tokens looking unexplained.
+ * would leave several thousand tokens looking unexplained. It is labelled an
+ * ALLOWANCE (cli#4): a fixed config value standing in for the system prompt and
+ * tool schemas, not a measurement of them — and the row under it names the two
+ * ways the figure is actually inaccurate, so nobody has to discover them by
+ * being compacted early.
  */
 /** `~34k`, `~900` — the leading tilde is not decoration. See the module note. */
 function approx(n) {
@@ -68,8 +72,13 @@ export function contextReportLines(report, t, width = Infinity) {
     }
     // Named separately because it is real, unavoidable, and in no message — the
     // one part of the figure a user cannot shrink by pruning the conversation.
-    lines.push(`  ${"reserve".padEnd(13)} ${approx(report.reserveTokens).padStart(7)} ` +
-        t.muted("       system prompt + tool schemas"));
+    // And named as what it is: a fixed allowance, not a count. The two lines
+    // after it are the honest footnote — what the allowance does not track, and
+    // what the denominator is not.
+    lines.push(`  ${"allowance".padEnd(13)} ${approx(report.reserveTokens).padStart(7)} ` +
+        t.muted("       system prompt + tool schemas (a fixed setting, not measured)"));
+    lines.push(t.muted("  the allowance does not grow with CRUXY.md, memory, LSP, web or MCP schemas,"));
+    lines.push(t.muted("  and the budget is context.maxTokens — a config heuristic, not a limit read from the served tier"));
     // ── the biggest single messages ───────────────────────────────────────────
     if (report.largest.length > 0) {
         lines.push("");

package/dist/render/index.js

@@ -8,7 +8,7 @@ import { TtyRenderer } from "./tty-renderer.js";
 import { TuiRenderer } from "../tui/renderer.js";
 import { GitStatusCache } from "../tui/git-status.js";
 import { ToolVersions } from "../tui/tool-versions.js";
-import { supportsTui, usesAltScreen } from "../tui/supports.js";
+import { supportsTui, usesAltScreen, usesMouse } from "../tui/supports.js";
 export { detectCapabilities, detectReducedMotion, resolveColumns, resolveRows, DEFAULT_COLUMNS, DEFAULT_ROWS, } from "./capabilities.js";
 export { attachResize, processResizeSignal, } from "./resize.js";
 export { fit, fitMiddle, reflow, stripAnsi, visibleWidth, kvStack, MIN_VALUE_COLS, } from "./layout.js";
@@ -58,6 +58,7 @@ export function createRenderer(out = process.stdout, err = process.stderr, env =
             // for a direct construction and wrong here: an injected env exists
             // precisely so a caller can describe a terminal that is not this one.
             altScreen: usesAltScreen(caps, env),
+            mouse: usesMouse(caps, env),
         });
     }
     return caps.cursor

package/dist/session/index.js

@@ -14,6 +14,7 @@
  */
 export { PROJECTS_DIR_NAME, RESERVED_SUBDIRS, SESSION_FILE_EXT, projectDir, projectKey, projectsDir, reservedDir, sessionFile, } from "./paths.js";
 export { SessionLog } from "./log.js";
+export { claimSession, describeHolder, ownerFile, readOwner, releaseSession, removeOwnerFile, sessionHeldBy, } from "./owner.js";
 export { defaultExportName, exportMarkdown, } from "./export.js";
 export { foldEvents, readEvents, readMeta, replaySession } from "./replay.js";
 export { redactMessages } from "./redact.js";

package/dist/session/log.js

@@ -3,6 +3,7 @@ import path from "node:path";
 import { APP_VERSION } from "../constants.js";
 import { formatBytes } from "../utils/disk.js";
 import { sessionFile } from "./paths.js";
+import { claimSession, describeHolder, releaseSession, sessionHeldBy, } from "./owner.js";
 import { pruneSessions } from "./prune.js";
 import { SESSION_FILE_VERSION, } from "./types.js";
 /**
@@ -20,6 +21,8 @@ export class SessionLog {
     currentRunId;
     /** Set once a write fails: the log goes inert rather than warning per turn. */
     broken = false;
+    /** Whether this process has stamped itself as the file's owner (P1). */
+    claimed = false;
     /**
      * A NEW session's `meta` line, held until the session records something.
      * Null on a reopen (the file already has its meta) and null again the moment
@@ -77,6 +80,14 @@ export class SessionLog {
         const log = new SessionLog(file, opts);
         log.pruneOnce(opts);
         if (hasContent(file)) {
+            // OWNERSHIP (P1). A reopen is the moment a second process would start
+            // interleaving its turns into this file, so the stamp is taken here,
+            // eagerly, like the `resumed` event below. `loadResume` has already
+            // refused a file another live cruxy holds; this is the claim that makes
+            // the NEXT resume see us. A fresh session claims at its first flush
+            // instead — see {@link write} — for the same reason `meta` is buffered:
+            // a conversation with nothing in it should leave nothing on disk.
+            log.claim();
             log.write({
                 kind: "resumed",
                 at: new Date().toISOString(),
@@ -232,9 +243,46 @@ export class SessionLog {
             this.pendingMeta = null;
             if (!this.writeLine(meta))
                 return false;
+            this.claim(); // the file now exists — so can a second `--resume` of it
         }
         return this.writeLine(event);
     }
+    /**
+     * Stamp this process as the file's owner (P1 — see `owner.ts`). Idempotent.
+     * The stamp is released on process exit; a crash leaves it behind, and that
+     * is fine — a stamp is pid + start-time, so the next reader sees a dead
+     * owner and ignores it. Never fatal: an unwritable stamp is the pre-P1
+     * behaviour (no ownership), and a session must still run without one.
+     */
+    claim() {
+        if (this.claimed)
+            return;
+        // Never overwrite a LIVE owner's stamp. `loadResume` refuses that file
+        // before we get here, so this is the guard for any other writer that
+        // opens a log — and for the race two resumes in the same instant would
+        // be. Recording continues (the format tolerates it); ownership does not
+        // move, so the third process to come along still sees the real holder.
+        const holder = sessionHeldBy(this.file);
+        if (holder) {
+            this.logger?.warn(`session is open in another cruxy (${describeHolder(holder)}) — this process is not taking it over`);
+            return;
+        }
+        this.claimed = claimSession(this.file);
+        if (this.claimed)
+            releaseOnExit(this.file);
+    }
+    /**
+     * Give the file up: remove our stamp. The exit hook does this for the
+     * normal case; this is for a caller that ends a session while the process
+     * lives on (tests, and any future in-process session switch).
+     */
+    close() {
+        if (!this.claimed)
+            return;
+        this.claimed = false;
+        releaseSession(this.file);
+        claimedFiles.delete(this.file);
+    }
     /**
      * Append one event as a single line. Returns whether it landed. The first
      * failure warns and latches `broken`, so a persistent problem (a full disk)
@@ -255,6 +303,24 @@ export class SessionLog {
         }
     }
 }
+/**
+ * Every session file this process has stamped, released together on exit.
+ * ONE listener for the process rather than one per log: a test opens dozens
+ * of logs, and `process.on` warns past ten listeners.
+ */
+const claimedFiles = new Set();
+let exitHookInstalled = false;
+function releaseOnExit(file) {
+    claimedFiles.add(file);
+    if (exitHookInstalled)
+        return;
+    exitHookInstalled = true;
+    process.on("exit", () => {
+        for (const f of claimedFiles)
+            releaseSession(f);
+        claimedFiles.clear();
+    });
+}
 /**
  * Whether `file` is an existing log with content — i.e. this is a reopen.
  *

package/dist/session/owner.js

@@ -0,0 +1,123 @@
+import { mkdirSync, readFileSync, renameSync, unlinkSync, writeFileSync, } from "node:fs";
+import path from "node:path";
+import { z } from "zod";
+import { describeOwner, selfStamp, } from "../utils/process-owner.js";
+import { SESSION_FILE_EXT } from "./paths.js";
+/**
+ * Session ownership across processes (P1).
+ *
+ * A session log is one append-only file, and `SessionLog` was built so that
+ * concurrent appenders interleave whole lines rather than tearing them. That
+ * keeps the file PARSEABLE under two writers; it does not keep it MEANINGFUL.
+ * Two processes that `--resume` the same id each replay the same history,
+ * each append their own turns, and the result is one transcript with two
+ * conversations shuffled into it — replayable, and wrong.
+ *
+ * The fix is ownership, and the minimum that prevents the observed failure is
+ * a stamp, not a lock:
+ *
+ * - `<id>.owner.json` beside the log holds the {@link ProcessStamp} of the
+ *   cruxy that has it open. It is written when the session first lands on
+ *   disk (a new session) or on reopen (a resume), and removed on exit.
+ * - `--resume` reads it BEFORE replaying. A stamp whose process is still
+ *   running is a refusal; a stamp whose process is gone — or whose pid has
+ *   been recycled onto something else — is ignored and overwritten.
+ *
+ * WHY A STAMP AND NOT A LOCK. A lock file that must be deleted to be released
+ * outlives every crash, and a lock that outlives a crash is worse than no
+ * lock: the next `--resume` is refused with nothing to refuse it for, and the
+ * user learns to `rm` it — at which point it stops meaning anything. A pid +
+ * start-time stamp is self-invalidating: liveness is decided by asking the OS,
+ * never by whether cleanup ran. See `utils/process-owner.ts` for why the pid
+ * marker refused for JOB logs is category-correct for sessions.
+ *
+ * WHY NOT A PROJECT-LEVEL LOCK. Several cruxy processes in one project is the
+ * multi-agent case, not a misuse of it. What must not happen is two of them
+ * on ONE session; the stamp is scoped to exactly that.
+ */
+const OwnerSchema = z.object({
+    pid: z.number().int().positive(),
+    token: z.string().min(1),
+    startedAt: z.string(),
+    /** When the stamp was written — for messages. */
+    claimedAt: z.string(),
+});
+/** `<id>.owner.json` next to `<id>.jsonl`. */
+export function ownerFile(sessionFile) {
+    const dir = path.dirname(sessionFile);
+    const id = path.basename(sessionFile, SESSION_FILE_EXT);
+    return path.join(dir, `${id}.owner.json`);
+}
+/** The recorded owner, or null when there is none (absent, unreadable, malformed). */
+export function readOwner(sessionFile) {
+    let raw;
+    try {
+        raw = readFileSync(ownerFile(sessionFile), "utf8");
+    }
+    catch {
+        return null;
+    }
+    try {
+        const parsed = OwnerSchema.safeParse(JSON.parse(raw));
+        return parsed.success ? parsed.data : null;
+    }
+    catch {
+        return null;
+    }
+}
+/**
+ * Who has the session open right now, if anyone other than this process.
+ * A stale stamp is not a holder; neither is our own.
+ */
+export function sessionHeldBy(sessionFile) {
+    const owner = readOwner(sessionFile);
+    if (!owner)
+        return null;
+    return describeOwner(owner) === "live" ? owner : null;
+}
+/**
+ * Record this process as the session's owner. Temp-then-rename so a reader
+ * never sees a half-written stamp; `0600` like everything else in `~/.cruxy`.
+ * Never throws: a stamp that cannot be written degrades to the pre-P1
+ * behaviour (no ownership), and the session must still run.
+ */
+export function claimSession(sessionFile) {
+    const file = ownerFile(sessionFile);
+    const me = selfStamp();
+    const record = { ...me, claimedAt: new Date().toISOString() };
+    try {
+        mkdirSync(path.dirname(file), { recursive: true });
+        const tmp = `${file}.${process.pid}.tmp`;
+        writeFileSync(tmp, JSON.stringify(record), { mode: 0o600 });
+        renameSync(tmp, file);
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+/** Remove our stamp — only ours; a later owner's is left alone. Never throws. */
+export function releaseSession(sessionFile) {
+    const owner = readOwner(sessionFile);
+    if (!owner || describeOwner(owner) !== "self")
+        return;
+    try {
+        unlinkSync(ownerFile(sessionFile));
+    }
+    catch {
+        // already gone, or unwritable — nothing to do either way
+    }
+}
+/** Drop a session's stamp unconditionally — for deleting the session itself. */
+export function removeOwnerFile(sessionFile) {
+    try {
+        unlinkSync(ownerFile(sessionFile));
+    }
+    catch {
+        // no stamp to remove
+    }
+}
+/** One line for a refusal or a picker row: which process, since when. */
+export function describeHolder(stamp) {
+    return `pid ${stamp.pid}, started ${stamp.startedAt}`;
+}