@cruxy/cli 1.11.0 → 1.11.2

package/README.md

@@ -219,6 +219,7 @@ once. Reduced motion is also implied by screen-reader mode.
 | Variable              | Effect                                                                         |
 | --------------------- | ------------------------------------------------------------------------------ |
 | `CRUXY_NO_ALT_SCREEN` | Keep the full-screen TUI in the normal buffer instead of the alternate screen. |
+| `CRUXY_NO_MOUSE`      | Leave the mouse to the terminal — the wheel scrolls the window, not the pane.  |
 
 By default the TUI runs on the terminal's alternate screen — the second buffer
 `less` and `vim` use. Leaving it restores the normal buffer byte for byte, so
@@ -237,6 +238,17 @@ prefer your shell to keep the frame. It changes nothing else about the TUI, and
 it is ignored where the TUI does not run at all (a pipe, a screen reader,
 `TERM=dumb`).
 
+### The mouse
+
+While the TUI is active it turns mouse reporting on, so the wheel scrolls the
+conversation (or the selected view) the way Page Up and Page Down do, instead
+of scrolling the terminal window over a buffer that has no scrollback. The
+trade is the one `less` and `vim` make: **native text selection needs Shift
+(Option in Terminal.app) while the TUI is active.** If you select text
+constantly, set `CRUXY_NO_MOUSE=1` — the wheel goes back to the terminal, and
+nothing else about the TUI changes. It is implied off wherever the alternate
+screen is off, because the two are turned on and released as one.
+
 However cruxy exits — quit, `kill -TERM`, a hangup when the window closes, an
 uncaught error — the terminal is handed back: the frame erased, the cursor
 shown, the alternate screen left.

package/dist/agent/context.js

@@ -41,6 +41,11 @@ export function readContext(messages, budget) {
     // reserve covers the system prompt and tool schemas that `estimateTokens`
     // never sees, and omitting it here would under-report by ~4.5k tokens and let
     // the panel read "comfortable" while the seam was about to compact.
+    //
+    // It is an ALLOWANCE, not a measurement, and every renderer of `used` has
+    // to be able to say so — hence `reserve` travels with the reading. It is
+    // fixed by config: it does not grow when CRUXY.md, recalled memory, LSP,
+    // web or MCP tool schemas grow the actual request.
     const used = estimateTokens(messages) + budget.reserveTokens;
     const total = budget.maxTokens;
     return {
@@ -48,6 +53,7 @@ export function readContext(messages, budget) {
         total,
         fraction: total <= 0 ? 1 : Math.min(1, Math.max(0, used / total)),
         compactAt: Math.round(budget.compactThreshold * total),
+        reserve: budget.reserveTokens,
     };
 }
 /**

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/cli/session-commands.js

@@ -63,6 +63,10 @@ export async function dispatchCommand(input, ctx) {
         return { kind: "exit" };
     if (trimmed === "/clear") {
         session.clear();
+        // The screen too, where the shell owns one. A history reset that left the
+        // old transcript on screen above its own confirmation read as a reset that
+        // had not happened — the context WAS empty; only the screen said otherwise.
+        out.clear?.();
         out.print(t.muted("history cleared"));
         return { kind: "handled" };
     }

package/dist/components/input.js

@@ -75,7 +75,7 @@ export async function readSingleKey(stdin = process.stdin) {
     const keys = createKeyReader(stdin);
     keys.begin();
     try {
-        const key = await keys.read();
+        const key = await readAnswerKey(keys);
         switch (key.kind) {
             case "char":
                 return key.char;
@@ -89,6 +89,23 @@ export async function readSingleKey(stdin = process.stdin) {
         keys.restore();
     }
 }
+/**
+ * The next key that can be an ANSWER — a wheel notch is not one.
+ *
+ * Every single-key prompt maps "anything unmapped" to the safe default (deny,
+ * cancel, no). That is right for an arrow or a function key, and wrong for the
+ * mouse wheel: with mouse reporting on (the TUI turns it on), a reader who
+ * scrolls back to check what a prompt is about would answer it "no" by doing
+ * so. The wheel is a scroll, never a reply, so it is skipped here and the
+ * prompt keeps waiting.
+ */
+export async function readAnswerKey(keys) {
+    for (;;) {
+        const key = await keys.read();
+        if (key.kind !== "wheel-up" && key.kind !== "wheel-down")
+            return key;
+    }
+}
 /** The real environment: frames to stderr, keys from stdin, caps from stderr. */
 export function defaultComponentIO() {
     // Detection resolves both axes (stderr for output, stdin for input) and their

package/dist/components/keys.js

@@ -26,6 +26,22 @@ const CBT = 0x5a;
  * not rejected, so these are matched on the leading number instead.
  */
 const TILDE = 0x7e;
+/**
+ * The two mouse encodings a terminal can answer `?1000h` with.
+ *
+ * SGR (`?1006h`, the one the TUI asks for) sends `ESC [ < Cb ; Cx ; Cy M` for
+ * a press and `… m` for a release, all in printable ASCII. A terminal that does
+ * not know SGR falls back to X10: `ESC [ M` followed by THREE RAW BYTES
+ * (button+32, column+32, row+32). The X10 form has to be recognised even though
+ * it is never requested, because the alternative is worse than an unmapped key:
+ * the generic CSI rule below would stop at the `M`, and the three bytes after
+ * it — printable, by construction — would land in the input line as text.
+ */
+const SGR_MOUSE_INTRO = 0x3c; // <
+const X10_MOUSE_FINAL = 0x4d; // M
+/** Bit 6 of the button code marks a wheel event; bit 0 says which way. */
+const MOUSE_WHEEL_FLAG = 64;
+const X10_MOUSE_PAYLOAD = 3;
 /** Leading `~`-sequence parameter → key. `ESC [ 5 ~` / `ESC [ 6 ~`. */
 const TILDES = {
     5: "page-up",
@@ -43,9 +59,10 @@ const ARROWS = {
  * keys per chunk; all are returned in order.
  *
  * Escape handling is deliberately simple: `ESC [ A..D` decodes to an arrow,
- * `ESC [ … Z` decodes to Shift+Tab, any other CSI sequence (`ESC [ …final`) is
- * swallowed whole (unmapped keys must not leak garbage chars into a query), and
- * a lone ESC decodes to `escape`. Terminals send arrow sequences atomically in practice; a sequence
+ * `ESC [ … Z` decodes to Shift+Tab, a mouse report (SGR `ESC [ < … M`, or X10
+ * `ESC [ M` + 3 bytes) decodes to a wheel notch or to nothing, any other CSI
+ * sequence (`ESC [ …final`) is swallowed whole (unmapped keys must not leak
+ * garbage chars into a query), and a lone ESC decodes to `escape`. Terminals send arrow sequences atomically in practice; a sequence
  * split across chunks degrades to `escape` + literal chars, which is safe
  * (escape cancels).
  */
@@ -56,12 +73,44 @@ export function decodeKeys(chunk) {
         const byte = buf[i];
         if (byte === ESC) {
             if (buf[i + 1] === 0x5b /* [ */) {
+                // X10 mouse: `ESC [ M` plus three raw payload bytes. Consumed as one
+                // unit BEFORE the generic CSI walk, which would otherwise treat `M` as
+                // the final byte and hand the payload to the printable branch.
+                if (buf[i + 2] === X10_MOUSE_FINAL) {
+                    const end = i + 3 + X10_MOUSE_PAYLOAD;
+                    if (end <= buf.length) {
+                        const wheel = mouseWheel(buf[i + 3] - 32);
+                        if (wheel)
+                            keys.push({ kind: wheel });
+                        i = end;
+                        continue;
+                    }
+                    // Truncated at the chunk boundary: the same degradation as any other
+                    // partial CSI — escape, and drop the tail.
+                    keys.push({ kind: "escape" });
+                    i = buf.length;
+                    continue;
+                }
                 // CSI: consume parameter/intermediate bytes (0x20–0x3f) up to the
                 // final byte (0x40–0x7e); map arrows, swallow everything else.
                 let j = i + 2;
                 while (j < buf.length && buf[j] >= 0x20 && buf[j] <= 0x3f)
                     j++;
                 if (j < buf.length) {
+                    if (buf[i + 2] === SGR_MOUSE_INTRO) {
+                        // SGR mouse: `ESC [ < Cb ; Cx ; Cy M|m`. Only the button code is
+                        // read — the wheel has no position — and a press is the only edge
+                        // a wheel has, so `m` (release) never maps to anything.
+                        let cb = 0;
+                        for (let k = i + 3; k < j && buf[k] >= 0x30 && buf[k] <= 0x39; k++) {
+                            cb = cb * 10 + (buf[k] - 0x30);
+                        }
+                        const wheel = buf[j] === X10_MOUSE_FINAL ? mouseWheel(cb) : null;
+                        if (wheel)
+                            keys.push({ kind: wheel });
+                        i = j + 1;
+                        continue;
+                    }
                     if (buf[j] === CBT) {
                         // Shift+Tab, in BOTH its forms: bare `ESC [ Z`, and the
                         // parameterized `ESC [ 1 ; 2 Z` some terminals send when a modifier
@@ -165,3 +214,17 @@ export function decodeKeys(chunk) {
     }
     return keys;
 }
+/**
+ * A mouse button code → the wheel direction it encodes, or null for any other
+ * mouse event. Modifier bits (shift 4, meta 8, ctrl 16) are masked off so a
+ * wheel with a modifier held still scrolls; the low two bits pick the direction.
+ */
+function mouseWheel(button) {
+    if ((button & MOUSE_WHEEL_FLAG) === 0)
+        return null;
+    return (button & 3) === 0
+        ? "wheel-up"
+        : (button & 3) === 1
+            ? "wheel-down"
+            : null;
+}

package/dist/config/schema.js

@@ -133,7 +133,14 @@ export const ContextConfigSchema = z
      * sees — the system prompt and every tool's JSON schema — added to the
      * measured history before the threshold test so the trigger reflects the
      * real request size, not just the visible messages. Roughly the size of
-     * the built system prompt plus the default tool catalogue today.
+     * the built system prompt plus the default tool catalogue today (about
+     * 3.7k measured for the prompt and 14 tool schemas).
+     *
+     * An ALLOWANCE, not a measurement — the context panel and `/context` say
+     * so. It is the same number on every turn, so it does not track the parts
+     * of a request that vary: CRUXY.md, recalled memory, LSP context, web
+     * results and MCP tool schemas all make the real request larger without
+     * moving it. Raise it if a project carries a lot of those.
      */
     reserveTokens: z.number().int().nonnegative().default(4500),
     /** Most-recent messages always kept verbatim (a floor; the cut rounds up to

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.
  *