@cruxy/cli 1.11.1 → 1.11.2

package/dist/checkpoint/service.js

@@ -8,6 +8,7 @@ import { captureFiles } from "./capture.js";
 import { GitCheckpointStore } from "./git-store.js";
 import { ShadowCheckpointStore } from "./shadow-store.js";
 import { applyRollback, buildRollbackPreview, computeRollbackPlan, } from "./restore.js";
+import { describeOwner, selfStamp, } from "../utils/process-owner.js";
 /** Is `root` inside a git working tree? (Decides the checkpoint substrate.) */
 export function isGitWorkTree(root) {
     const res = runGitCapture(["rev-parse", "--is-inside-work-tree"], root);
@@ -112,6 +113,7 @@ export class CheckpointService {
             files: entries,
             touchedPaths: [],
             hasShellMutations: false,
+            owner: selfStamp(),
         };
         await this.writeManifest(checkpoint);
         await this.prune();
@@ -203,10 +205,27 @@ export class CheckpointService {
         const applied = await applyRollback(this.root, plan, store);
         return { kind: "applied", checkpoint, applied };
     }
-    /** Enforce `checkpoint.retention`: drop oldest manifests, then GC content. */
+    /**
+     * Enforce `checkpoint.retention`: drop oldest manifests, then GC content.
+     *
+     * ACROSS PROCESSES (P1). `.cruxy/checkpoints/` is per root, not per process,
+     * and every cruxy in the project prunes it by count — so a second session
+     * creating its own checkpoints pushed the first session's out of the
+     * window and swept their objects, and the first session's `cruxy rollback`
+     * then failed or restored the wrong thing. A checkpoint whose recorded
+     * owner is another LIVE process is therefore not this process's to prune:
+     * it is set aside, its objects stay referenced, and the retention count is
+     * applied to everything else. The bound is exceeded by at most the live
+     * foreign checkpoints, and only while their owners run: a crashed owner's
+     * checkpoints are ordinary candidates the next time anyone prunes, because
+     * liveness is pid + start-time asked of the OS, never a file that must be
+     * cleaned up.
+     */
     async prune() {
         const all = await this.list();
-        const doomed = all.slice(this.config.checkpoint.retention);
+        const protectedIds = foreignLive(all);
+        const candidates = all.filter((c) => !protectedIds.has(c.id));
+        const doomed = candidates.slice(this.config.checkpoint.retention);
         if (doomed.length === 0)
             return;
         for (const checkpoint of doomed) {
@@ -214,7 +233,7 @@ export class CheckpointService {
                 force: true,
             });
         }
-        const survivors = all.slice(0, this.config.checkpoint.retention);
+        const survivors = all.filter((c) => !doomed.includes(c));
         const referenced = new Set(survivors.flatMap((c) => c.files.map((f) => f.oid)));
         // The shadow pool is ours to sweep; git's dangling objects belong to git gc.
         await new ShadowCheckpointStore(this.root).collect(referenced);
@@ -266,6 +285,28 @@ export class CheckpointService {
         return parsed;
     }
 }
+/**
+ * Ids of the checkpoints another LIVE process owns (P1 — see {@link prune}).
+ * One liveness lookup per distinct owner, not per manifest: the darwin lookup
+ * is a `ps` call, and a project can hold many checkpoints from one session.
+ */
+function foreignLive(all) {
+    const ids = new Set();
+    const status = new Map();
+    for (const c of all) {
+        if (!c.owner)
+            continue;
+        const key = `${c.owner.pid}:${c.owner.token}`;
+        let s = status.get(key);
+        if (s === undefined) {
+            s = describeOwner(c.owner);
+            status.set(key, s);
+        }
+        if (s === "live")
+            ids.add(c.id);
+    }
+    return ids;
+}
 /** `ck-<utc-stamp>-<rand>` — sortable, collision-safe enough for a local CLI. */
 function newCheckpointId() {
     const stamp = new Date()

package/dist/cli/commands/sessions.js

@@ -7,6 +7,7 @@ import { SESSION_FILE_EXT, matchSessionRefs, listSessionRefs, pruneSessions, ses
 import { themeForColor } from "../../theme/index.js";
 import { formatBytes } from "../../utils/disk.js";
 import { logger } from "../../utils/logger.js";
+import { describeHolder, removeOwnerFile, sessionHeldBy, } from "../../session/owner.js";
 /**
  * `cruxy sessions` (#257) — see and bound what `~/.cruxy/projects/<project>/`
  * is holding.
@@ -149,8 +150,15 @@ export function sessionsCommand() {
                 "sessions are per-directory; check you are in the right one",
             ]);
         }
+        // Not while another cruxy is writing it (P1): its next append would
+        // recreate the file headless and leave a session nothing can load.
+        const holder = sessionHeldBy(matches[0].file);
+        if (holder) {
+            throw usageError(`session ${shortId(matches[0].sessionId)} is open in another cruxy (${describeHolder(holder)})`, ["quit that cruxy first, then delete it"]);
+        }
         try {
             unlinkSync(matches[0].file);
+            removeOwnerFile(matches[0].file);
         }
         catch (err) {
             throw usageError(`could not delete session ${shortId(matches[0].sessionId)}`, [`${matches[0].file}: ${err.message}`]);

package/dist/errors/constructors.js

@@ -545,16 +545,25 @@ export function indexEmbedderUnavailable(underlying) {
  * exact "reads like success, isn't" trap C.17 forbids. The `search_codebase`
  * tool instead surfaces it as a tool error and points the model at `grep_files`.
  */
-export function indexEmbedderDownloadFailed(underlying) {
+export function indexEmbedderDownloadFailed(underlying, opts = {}) {
+    // A refused archive is not a connectivity problem: the download succeeded
+    // and cruxy's extractor rejected an entry (path traversal, a link, an
+    // unexpected layout). Retrying will refuse it again, so say so.
+    const nextSteps = opts.archiveRefused
+        ? [
+            "the model archive was refused by cruxy's extraction guard and nothing was written; this is not a connectivity problem",
+            "do not retry blindly — if it persists, report it with the message above (the upstream archive may have changed shape)",
+        ]
+        : [
+            "check your internet connection — the model (bge-small-en-v1.5, ~77 MB) downloads once on first use",
+            "if you are behind a proxy or firewall, allow access to storage.googleapis.com (the qdrant-fastembed bucket); HTTPS_PROXY / NO_PROXY are honored",
+            "once the download succeeds it is cached under ~/.cruxy/models and never re-fetched",
+        ];
     return new CruxyError({
         code: ErrorCode.IndexEmbedderDownloadFailed,
         title: "the local embedding model could not be downloaded or initialized",
         cause: messageOf(underlying),
-        nextSteps: [
-            "check your internet connection — the model (bge-small-en-v1.5) downloads once on first use",
-            "if you are behind a proxy or firewall, allow access to the model host (Hugging Face) and set HTTPS_PROXY",
-            "once the download succeeds it is cached under ~/.cruxy/models and never re-fetched",
-        ],
+        nextSteps,
         underlying,
     });
 }

package/dist/errors/types.js

@@ -99,6 +99,12 @@ export const ErrorCode = {
     PermissionDenied: "CRUXY_E_PERMISSION_DENIED",
     PathEscape: "CRUXY_E_PATH_ESCAPE",
     CheckpointFailed: "CRUXY_E_CHECKPOINT_FAILED",
+    /** A mutating file tool re-read its target immediately before the approved
+     * write and found it was not the file the approval was granted against (P1):
+     * changed, deleted, or created by something else during the approval wait.
+     * Refused with nothing written — the approval covered a diff against ONE
+     * specific state, and that state moved. See `tools/file/snapshot.ts`. */
+    FileChangedSinceRead: "CRUXY_E_FILE_CHANGED_SINCE_READ",
     // index (exit 8)
     /** The fastembed native module could not be LOADED (missing/broken install,
      * un-built onnxruntime-node addon). Fail-loud by design — the embedder never
@@ -341,6 +347,7 @@ const EXIT_CODES = {
     [ErrorCode.PermissionDenied]: 7,
     [ErrorCode.PathEscape]: 7,
     [ErrorCode.CheckpointFailed]: 7,
+    [ErrorCode.FileChangedSinceRead]: 7,
     [ErrorCode.IndexEmbedderUnavailable]: 8,
     [ErrorCode.IndexEmbedderDownloadFailed]: 8,
     [ErrorCode.IndexStoreUnavailable]: 8,

package/dist/indexing/embedder.js

@@ -1,5 +1,7 @@
-import { promises as fs } from "node:fs";
+import path from "node:path";
+import { globalDir } from "../config/paths.js";
 import { indexEmbedderDownloadFailed, indexEmbedderUnavailable, } from "../errors/index.js";
+import { ensureModelDir, MODEL_ONNX_FILE, } from "./model-cache.js";
 import { l2normalize } from "./util.js";
 /**
  * Output dimensionality of bge-small-en-v1.5, and the default size of the
@@ -69,6 +71,12 @@ export class HashingEmbedder {
  * registering the `search_codebase` tool stays cheap and the heavy ONNX runtime
  * only loads when an index is actually built or queried.
  *
+ * The model files are provisioned by cruxy ({@link ensureModelDir}), NOT by
+ * fastembed: fastembed is initialised with `model: CUSTOM` and an absolute
+ * directory, which in its `init` makes its own `retrieveModel` (tar@6-based
+ * download + extract, #306) unreachable. `CUSTOM` changes nothing else for this
+ * model — fastembed's only model-specific branch is for multilingual-e5.
+ *
  * Embedding is CPU-bound and single-threaded inside ONNX, so throughput is
  * bounded by `batchSize` (fed sequentially through fastembed's batching
  * generator) rather than by JS-level concurrency.
@@ -84,23 +92,29 @@ export class FastEmbedEmbedder {
     getModel() {
         if (!this.model) {
             this.model = (async () => {
+                const cacheDir = this.opts.cacheDir ?? path.join(globalDir(), "models");
+                const provision = this.opts.provision ?? ((dir) => ensureModelDir({ cacheDir: dir }));
+                let modelDir;
+                try {
+                    modelDir = await provision(cacheDir);
+                }
+                catch (err) {
+                    throw indexEmbedderDownloadFailed(err, {
+                        archiveRefused: isRefusedArchive(err),
+                    });
+                }
                 try {
                     const mod = await import("fastembed");
-                    // fastembed's init does a non-recursive mkdir of the cache dir, so it
-                    // fails if an ancestor (e.g. ~/.cruxy) doesn't exist yet. Create it first.
-                    if (this.opts.cacheDir) {
-                        await fs.mkdir(this.opts.cacheDir, { recursive: true });
-                    }
                     return (await mod.FlagEmbedding.init({
-                        model: mod.EmbeddingModel.BGESmallENV15,
+                        model: mod.EmbeddingModel.CUSTOM,
+                        modelAbsoluteDirPath: modelDir,
+                        modelName: MODEL_ONNX_FILE,
                         maxLength: this.opts.maxLength ?? 512,
-                        cacheDir: this.opts.cacheDir,
-                        showDownloadProgress: this.opts.showDownloadProgress ?? false,
+                        showDownloadProgress: false,
                     }));
                 }
                 catch (err) {
-                    // The heavy path: first-run model download/decompress or ONNX-runtime
-                    // init failed (offline, unreachable model bucket, proxy). Surface a
+                    // ONNX-runtime init failed on a verified model directory. Surface a
                     // typed, actionable error instead of letting it collapse into the
                     // generic CRUXY_E_INDEX_FAILED ("re-run --verbose"). Still fail-loud —
                     // this never degrades to the lexical backend. (Module-*load* failure is
@@ -128,6 +142,15 @@ export class FastEmbedEmbedder {
         return l2normalize(Float32Array.from(await model.queryEmbed(text)));
     }
 }
+/**
+ * Duck-typed on purpose: tests re-import this module across
+ * `vi.resetModules()`, which would defeat an `instanceof ModelCacheError`.
+ */
+function isRefusedArchive(err) {
+    return (err instanceof Error &&
+        err.name === "ModelCacheError" &&
+        err.kind === "refused");
+}
 /**
  * Build the **production** embedder: fastembed / bge-small-en-v1.5.
  *

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/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";