mindweave 0.0.1 → 2.1.2

package/dist/tools/backgroundShells.js

@@ -0,0 +1,468 @@
+/**
+ * backgroundShells.ts — long-running commands that outlive a turn.
+ *
+ * When a command crosses its timeout (or the model asks for `run_in_background`),
+ * run_command hands the LIVE process to this manager instead of killing it. The
+ * manager owns the registry of background shells per session, buffers their output
+ * (capped, so a chatty dev server never floods memory or the model's context), and
+ * exposes:
+ *
+ *   - `read(id)`  — only the NEW output since the last read (incremental).
+ *   - `kill(id)`  — whole-tree kill.
+ *   - `list()`    — running + finished shells (for the UI and /shells).
+ *
+ * Two ONE-SHOT, self-cleaning event channels keep notifications from leaking
+ * (avoiding the common footgun where finished jobs re-inject into the model forever):
+ *   - `takeUiEvents()` — shells that came up or stopped, not yet shown in the chat.
+ *   - `drainEvents()`  — the same for the MODEL, each with a tail of output, so it is
+ *                        told once and then never again.
+ *
+ * Every event is delivered. What varies is whether it INTERRUPTS the session: a stop
+ * the user caused arrives as background fact on the next turn rather than waking the
+ * model, which is what stops it reopening an app somebody just closed.
+ *
+ * Client-side, like the alternator lanes: it holds live process handles, never
+ * crosses the engine↔brain wire. All children are killed on process exit.
+ */
+import { promises as fs } from "node:fs";
+import { killTree, killTreeSync } from "./killTree.js";
+const MAX_BUFFER_CHARS = 5_000_000; // cap one shell's retained output (runaway server)
+export const MAX_READ_CHARS = 30_000; // cap a single `shells` read
+const TAIL_CHARS = 2_000; // how much trailing output rides on a completion note
+/**
+ * How long a server has to stay up before we treat its death as "someone stopped it"
+ * rather than "it failed to start".
+ *
+ * This is the one honest way to tell the two apart, because the exit status cannot:
+ * measured on Windows, a user closing an app reports `code 1`, and so does a server
+ * that crashed because its port was taken. Duration separates them cleanly — a port
+ * conflict dies in under a second, a session you close has been up for minutes.
+ *
+ * Borrowed from process supervisors, which hit this decades ago: supervisord counts a
+ * program as failed-to-start if it exits before `startsecs` (default 1s) regardless of
+ * its exit code. 10s is deliberately generous, since a dev server can take several
+ * seconds to bind a port and fail.
+ */
+const STARTUP_GRACE_MS = 10_000;
+/**
+ * How long to wait after `exit` for `close` before finalizing anyway.
+ *
+ * `close` fires only once every stdio stream is closed, and a surviving grandchild can
+ * hold the pipe open forever, which strands the entry as permanently "running".
+ * `exit` fires when the process itself goes, so it is the backstop; the delay lets
+ * `close` win normally so buffered output is not lost.
+ */
+const EXIT_GRACE_MS = 2_000;
+/**
+ * Guess a notify policy from the command, for callers that did not declare one.
+ *
+ * This is a FALLBACK, not the decision. The policy is declared at call time; this only
+ * picks a default when nothing was said, so a caller that forgets does not regress to
+ * "reopen the app the user just closed". Being a list of names, it is wrong for
+ * everything nobody thought of (`cargo run`, `docker compose up`, `flask run`, a plain
+ * path to a binary) — which is exactly why it is no longer the authority.
+ */
+export function guessNotifyPolicy(command) {
+    return isInteractiveServerCommand(command) ? "on_failure" : "on_finish";
+}
+/**
+ * Is this command a dev server / interactive app — something that runs until stopped,
+ * where "it exited" means the USER closed it, NOT that a task finished? (pure/tested)
+ *
+ * Only used now to pick a default (see `guessNotifyPolicy`). A finite task (build,
+ * test, lint) that finishes IS a result worth surfacing, but a dev server exiting is
+ * just the user closing their app, and reacting to it makes the model reopen the thing
+ * they just closed. `build` variants are finite tasks, so they're excluded even though
+ * they share a runner name.
+ */
+export function isInteractiveServerCommand(command) {
+    const c = command.toLowerCase();
+    if (/\bbuild\b/.test(c))
+        return false; // `next build`, `tauri build`, `vite build` — finite
+    // Package-runner dev/serve/start/preview scripts: `npm run dev`, `pnpm start`, `yarn serve`.
+    if (/\b(npm|pnpm|yarn|bun)\b[^\n]*\b(dev|serve|start|preview)\b/.test(c))
+        return true;
+    // Dev servers / desktop-app runners invoked directly.
+    return /\b(tauri|vite|next|nuxt|remix|astro|nodemon|electron|expo|ng|http-server|live-server|serve|webpack-dev-server|watchexec)\b/.test(c);
+}
+/**
+ * Should a finished shell INTERRUPT the user with a turn? (pure/tested)
+ *
+ * Note the narrow question. This does NOT decide whether the model is told: it is
+ * always told (see `drainEvents`). Swallowing the event was the real defect — the
+ * model could not say "your app stopped", and if asked why the app was down it had
+ * nothing. This decides only whether the stop is worth breaking into the session for.
+ *
+ * The rule, in the user's words: don't reopen something they closed, unless it
+ * crashed before they ever got to see it.
+ *
+ *   - `never` → nothing is ever worth interrupting for
+ *   - somebody killed it → the agent or the user did that on purpose, so they know
+ *   - `on_finish` → the result is the point, always interrupt
+ *   - a signal ended it → someone stopped it deliberately
+ *   - otherwise → interrupt ONLY if it never came up, because then the user never saw
+ *     it running and cannot know it failed
+ *
+ * Deliberately NOT consulted: the exit code and the duration. Exit status cannot tell
+ * these cases apart — measured on Windows, a closed app and a port conflict both report
+ * code 1, and a signalled process reports none at all. `cameUp` is the fact that
+ * actually separates them, and it is established in ONE place (the readiness timer)
+ * rather than recomputed here from a second set of numbers.
+ */
+export function shouldWakeOnEnd(end) {
+    if (end.notify === "never")
+        return false;
+    if (end.killed)
+        return false;
+    if (end.notify === "on_finish")
+        return true;
+    if (end.signal)
+        return false;
+    return !end.cameUp;
+}
+/**
+ * Is `command` already running as one of these shells? (pure/tested) Matches on the
+ * normalized command string, so launching the very same server a second time is caught
+ * — the failure where the model fires `npm run tauri dev` twice, the copies collide on
+ * the port, and it then fights the conflict it created. Distinct servers (a frontend and
+ * a backend) don't match each other, so running both is still fine.
+ */
+export function findRunningDuplicate(running, command) {
+    const norm = (s) => s.toLowerCase().replace(/\s+/g, " ").trim();
+    const target = norm(command);
+    return running.find((s) => norm(s.command) === target);
+}
+/** How long after a user closes an app a re-launch of the same command is refused. Long
+ *  enough to break the close→reopen loop that plays out over a turn or two; short enough
+ *  that a restart the user genuinely asks for a while later is not held back. */
+export const REOPEN_COOLDOWN_MS = 2 * 60 * 1000;
+/**
+ * Was `command` an app the USER just closed? (pure/tested)
+ *
+ * The loop this breaks: the user closes their app, an agent that ignores the "do not
+ * reopen" note fires run_command again, the user closes it again, and round it goes. A
+ * match here lets the tool refuse the re-launch instead of reopening what the user shut.
+ *
+ * The signal is "it came up, then ended, and the AGENT did not kill it" — `ready` and
+ * `stoppedBy !== "agent"`. That is deliberately the same fact `shouldWakeOnEnd` treats as
+ * the user stopping their own app. It leaves the agent's OWN restart flow (kill_shell then
+ * relaunch) untouched, because that ending is `stoppedBy: "agent"`; and it never blocks a
+ * server that failed to start (`ready` is false), which the agent should be free to fix.
+ * Matched on the normalized command within a cooldown, so a later, deliberate restart is
+ * not held back.
+ */
+export function findRecentUserClose(shells, command, now, windowMs = REOPEN_COOLDOWN_MS) {
+    const norm = (s) => s.toLowerCase().replace(/\s+/g, " ").trim();
+    const target = norm(command);
+    return shells.find((s) => s.status !== "running" &&
+        s.ready &&
+        s.stoppedBy !== "agent" &&
+        s.finishedAt !== null &&
+        now - s.finishedAt < windowMs &&
+        norm(s.command) === target);
+}
+const active = new Set();
+let cleanupRegistered = false;
+export class BackgroundShells {
+    startupGraceMs;
+    exitGraceMs;
+    seq = 0;
+    shells = new Map();
+    onChange = null;
+    /**
+     * The two grace periods, injectable ONLY so tests can exercise the mechanism
+     * without waiting out real seconds. The defaults are the shipped behaviour and no
+     * production caller passes anything: a suite that waits out a 10s startup grace
+     * per case was 73% of the whole run's wall time, and that cost lands again on
+     * every contributor and every CI job.
+     */
+    constructor(startupGraceMs = STARTUP_GRACE_MS, exitGraceMs = EXIT_GRACE_MS) {
+        this.startupGraceMs = startupGraceMs;
+        this.exitGraceMs = exitGraceMs;
+        active.add(this);
+        registerCleanup();
+    }
+    /** Subscribe to state changes (start / finish / kill) — the UI re-renders. */
+    setOnChange(cb) {
+        this.onChange = cb;
+    }
+    /** Take ownership of a live child process and start buffering its output. */
+    adopt(child, opts) {
+        const id = ++this.seq;
+        const entry = {
+            id,
+            command: opts.command,
+            cwd: opts.cwd,
+            status: "running",
+            exitCode: null,
+            startedAt: Date.now(),
+            finishedAt: null,
+            child,
+            buffer: "",
+            readOffset: 0,
+            truncated: false,
+            notify: opts.notify ?? guessNotifyPolicy(opts.command),
+            ready: false,
+            reported: false,
+            uiNotified: false,
+            wakeOnEnd: false,
+            readyReported: false,
+            readyUiNotified: false,
+            readyTimer: null,
+            cwdFile: opts.cwdFile,
+            tempFile: opts.tempFile,
+        };
+        this.shells.set(id, entry);
+        if (opts.initial)
+            this.append(entry, opts.initial);
+        // The readiness signal. A server that is still alive after the startup grace has
+        // come up, and that is the one positive event worth reporting for something that
+        // never "finishes". Without it the model was told to promise a report it could not
+        // give: the only event it could ever receive was the end, which for a server is
+        // deliberately suppressed. Tasks don't need it — their event is completion.
+        if (entry.notify === "on_failure") {
+            entry.readyTimer = setTimeout(() => {
+                entry.readyTimer = null;
+                if (entry.status !== "running")
+                    return;
+                entry.ready = true;
+                this.emit();
+            }, this.startupGraceMs);
+            entry.readyTimer.unref?.();
+        }
+        const collect = (chunk) => this.append(entry, chunk.toString("utf8"));
+        child.stdout?.on("data", collect);
+        child.stderr?.on("data", collect);
+        // `signal` is captured, not dropped: a process ended by SIGTERM/SIGINT reports
+        // `code === null`, and without the signal there is no way to tell that from a
+        // crash.
+        child.on("close", (code, signal) => this.onClose(entry, code, signal, false));
+        child.on("error", () => this.onClose(entry, null, null, false));
+        // Backstop for a `close` that never arrives because a surviving grandchild still
+        // holds the stdio pipe. Without this the entry stays "running" for the rest of the
+        // session: the UI shows a dead shell, and `runningCount()` is permanently wrong.
+        child.on("exit", (code, signal) => {
+            const timer = setTimeout(() => this.onClose(entry, code, signal, false), this.exitGraceMs);
+            timer.unref?.();
+        });
+        this.emit();
+        return view(entry);
+    }
+    append(entry, text) {
+        entry.buffer += text;
+        if (entry.buffer.length > MAX_BUFFER_CHARS) {
+            // Keep the tail — the recent output is what matters for tests/errors.
+            entry.buffer = entry.buffer.slice(entry.buffer.length - MAX_BUFFER_CHARS);
+            entry.readOffset = Math.min(entry.readOffset, entry.buffer.length);
+            entry.truncated = true;
+        }
+    }
+    onClose(entry, code, signal, killed, by) {
+        if (entry.status !== "running")
+            return;
+        entry.status = killed ? "killed" : "exited";
+        entry.exitCode = code;
+        if (signal)
+            entry.signal = signal;
+        entry.finishedAt = Date.now();
+        entry.child = null;
+        if (by)
+            entry.stoppedBy = by;
+        if (entry.readyTimer) {
+            clearTimeout(entry.readyTimer);
+            entry.readyTimer = null;
+        }
+        // A pending "it's up" must not fire after the thing has already stopped. Note this
+        // clears the PENDING notice, not `entry.ready`: whether it ever came up is the fact
+        // the wake decision below is built on, and it has to survive.
+        entry.readyReported = true;
+        entry.readyUiNotified = true;
+        // Whether this ending is worth interrupting for. It is NOT marked reported here:
+        // the model is always told (drainEvents), it just isn't always interrupted. Marking
+        // it reported is what used to delete the event outright, leaving the model unable
+        // to say the app had stopped at all.
+        entry.wakeOnEnd = shouldWakeOnEnd({
+            notify: entry.notify,
+            killed,
+            signal,
+            cameUp: entry.ready,
+        });
+        if (entry.cwdFile)
+            void fs.rm(entry.cwdFile, { force: true }).catch(() => { });
+        if (entry.tempFile)
+            void fs.rm(entry.tempFile, { force: true }).catch(() => { });
+        this.emit();
+    }
+    /** New output since the last read of this shell, plus its current status. */
+    async read(id) {
+        const entry = this.shells.get(id);
+        if (!entry)
+            return null;
+        let chunk = entry.buffer.slice(entry.readOffset);
+        entry.readOffset = entry.buffer.length;
+        if (chunk.length > MAX_READ_CHARS) {
+            chunk = `… (earlier output omitted)\n${chunk.slice(chunk.length - MAX_READ_CHARS)}`;
+        }
+        return { info: view(entry), chunk };
+    }
+    /**
+     * Kill a running shell (whole tree). Returns false if it isn't running.
+     *
+     * `by` records WHO stopped it. Neither actor is woken about it, since both already
+     * know, but the difference is kept so the model can say "you stopped it" rather than
+     * guessing that it crashed.
+     */
+    kill(id, by = "agent") {
+        const entry = this.shells.get(id);
+        if (!entry || entry.status !== "running" || !entry.child)
+            return false;
+        killTree(entry.child.pid);
+        this.onClose(entry, null, null, true, by);
+        return true;
+    }
+    list() {
+        return [...this.shells.values()].map(view);
+    }
+    running() {
+        return this.list().filter((s) => s.status === "running");
+    }
+    runningCount() {
+        return this.running().length;
+    }
+    /**
+     * Events worth INTERRUPTING for: a shell that just came up, or one that ended in a
+     * way the user cannot already know about.
+     *
+     * This is deliberately narrower than "events not yet told". A stop the user caused
+     * still gets delivered on the next turn (see `drainEvents`); it just doesn't break
+     * into the session, which is what stops the agent reopening a closed app.
+     */
+    pendingCount() {
+        return [...this.shells.values()].filter((e) => (e.status !== "running" && !e.reported && e.wakeOnEnd) || (e.ready && !e.readyReported)).length;
+    }
+    /** One-shot for the UI: shells that came up or stopped and aren't in the chat yet. */
+    takeUiEvents() {
+        const out = [];
+        for (const entry of this.shells.values()) {
+            if (entry.ready && !entry.readyUiNotified) {
+                entry.readyUiNotified = true;
+                out.push({ info: view(entry), kind: "ready" });
+            }
+            if (entry.status !== "running" && !entry.uiNotified) {
+                entry.uiNotified = true;
+                out.push({ info: view(entry), kind: "ended" });
+            }
+        }
+        return out;
+    }
+    /**
+     * One-shot for the MODEL: EVERYTHING it hasn't been told, each with a tail of output.
+     *
+     * Every ending is delivered, including the ones not worth interrupting for. Those
+     * used to be deleted, which left the model unable to say an app had stopped, or to
+     * answer why it was down. `wake` carries whether this was the interrupting kind, so
+     * the caller can word it as news or as background fact.
+     *
+     * Both kinds go through this single channel, and both mark themselves so nothing is
+     * ever injected twice. That one-shot property is the whole reason background jobs
+     * don't slowly eat the context window, and it must survive any change here.
+     */
+    async drainEvents() {
+        const out = [];
+        const tailOf = (entry) => entry.buffer.slice(Math.max(0, entry.buffer.length - TAIL_CHARS));
+        for (const entry of this.shells.values()) {
+            if (entry.ready && !entry.readyReported) {
+                entry.readyReported = true;
+                out.push({ info: view(entry), kind: "ready", tail: tailOf(entry), wake: true });
+            }
+            if (entry.status !== "running" && !entry.reported) {
+                entry.reported = true;
+                out.push({ info: view(entry), kind: "ended", tail: tailOf(entry), wake: entry.wakeOnEnd });
+            }
+        }
+        return out;
+    }
+    /**
+     * Kill every running shell and drop the registry (session swap / exit).
+     *
+     * `sync` is required when disposing from a process-exit handler: the default
+     * kill spawns `taskkill` asynchronously, and Node runs no async work during
+     * exit, so the shells would outlive us. Measured, not assumed.
+     */
+    dispose(sync = false) {
+        for (const entry of this.shells.values()) {
+            // Kill by CHILD PRESENT, not by recorded status. A shell we have marked
+            // "ended" only means its WRAPPER exited, and on POSIX that says nothing about
+            // its descendants: kill the `sh -c` and the program it started is orphaned and
+            // keeps running, still holding the stdio pipes. MEASURED on Linux, where the
+            // orphan outlived the whole test process and stopped it from ever exiting.
+            // The group kill still reaches it, because a process group survives its leader
+            // as long as it has members. Signalling an already-dead pid is a harmless
+            // no-op, so there is nothing to lose by not consulting the status first.
+            if (entry.child) {
+                if (sync)
+                    killTreeSync(entry.child.pid);
+                else
+                    killTree(entry.child.pid);
+            }
+            if (entry.cwdFile)
+                void fs.rm(entry.cwdFile, { force: true }).catch(() => { });
+            if (entry.tempFile)
+                void fs.rm(entry.tempFile, { force: true }).catch(() => { });
+        }
+        this.shells.clear();
+        active.delete(this);
+    }
+    emit() {
+        this.onChange?.();
+    }
+}
+function view(e) {
+    return {
+        id: e.id,
+        command: e.command,
+        cwd: e.cwd,
+        status: e.status,
+        exitCode: e.exitCode,
+        startedAt: e.startedAt,
+        finishedAt: e.finishedAt,
+        notify: e.notify,
+        ready: e.ready,
+        ...(e.signal ? { signal: e.signal } : {}),
+        ...(e.stoppedBy ? { stoppedBy: e.stoppedBy } : {}),
+        ...(e.truncated ? { truncated: true } : {}),
+        ...(detectPort(e.buffer) !== undefined ? { port: detectPort(e.buffer) } : {}),
+    };
+}
+/** Kill any background processes still running when the process exits. */
+function registerCleanup() {
+    if (cleanupRegistered)
+        return;
+    cleanupRegistered = true;
+    process.once("exit", () => {
+        // Synchronous kill: an async one never reaches the OS from here.
+        for (const mgr of active)
+            mgr.dispose(true);
+    });
+}
+/**
+ * The port a process announced in its own output.
+ *
+ * A backgrounded dev server is only useful if you know where it is listening, and the
+ * one thing that knows is the server itself — it prints the URL on startup. So this
+ * reads the buffer rather than inspecting sockets: no privileges, no platform-specific
+ * netstat parsing, and it cannot report a port belonging to some other process.
+ *
+ * The FIRST announcement wins. A framework often prints a local URL and then a network
+ * one for the same port, and some print a proxy target afterwards; the first line is
+ * the one describing the server that just came up.
+ */
+export function detectPort(output) {
+    const m = /(?:https?:\/\/)(?:localhost|127\.0\.0\.1|0\.0\.0\.0|\[::1\]):(\d{2,5})/i.exec(output) ??
+        /\b(?:listening|running|started|ready)\b[^\n]*?\bport\b\s*:?\s*(\d{2,5})/i.exec(output);
+    if (!m)
+        return undefined;
+    const port = Number(m[1]);
+    return port >= 1 && port <= 65535 ? port : undefined;
+}
+//# sourceMappingURL=backgroundShells.js.map

package/dist/tools/backgroundShells.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"backgroundShells.js","sourceRoot":"","sources":["../../src/tools/backgroundShells.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;GAyBG;AACH,OAAO,EAAE,QAAQ,IAAI,EAAE,EAAE,MAAM,SAAS,CAAC;AAEzC,OAAO,EAAE,QAAQ,EAAE,YAAY,EAAE,MAAM,eAAe,CAAC;AAEvD,MAAM,gBAAgB,GAAG,SAAS,CAAC,CAAC,mDAAmD;AACvF,MAAM,CAAC,MAAM,cAAc,GAAG,MAAM,CAAC,CAAC,6BAA6B;AACnE,MAAM,UAAU,GAAG,KAAK,CAAC,CAAC,sDAAsD;AAEhF;;;;;;;;;;;;;GAaG;AACH,MAAM,gBAAgB,GAAG,MAAM,CAAC;AAEhC;;;;;;;GAOG;AACH,MAAM,aAAa,GAAG,KAAK,CAAC;AA2B5B;;;;;;;;GAQG;AACH,MAAM,UAAU,iBAAiB,CAAC,OAAe;IAC/C,OAAO,0BAA0B,CAAC,OAAO,CAAC,CAAC,CAAC,CAAC,YAAY,CAAC,CAAC,CAAC,WAAW,CAAC;AAC1E,CAAC;AAED;;;;;;;;;GASG;AACH,MAAM,UAAU,0BAA0B,CAAC,OAAe;IACxD,MAAM,CAAC,GAAG,OAAO,CAAC,WAAW,EAAE,CAAC;IAChC,IAAI,WAAW,CAAC,IAAI,CAAC,CAAC,CAAC;QAAE,OAAO,KAAK,CAAC,CAAC,qDAAqD;IAC5F,6FAA6F;IAC7F,IAAI,4DAA4D,CAAC,IAAI,CAAC,CAAC,CAAC;QAAE,OAAO,IAAI,CAAC;IACtF,sDAAsD;IACtD,OAAO,4HAA4H,CAAC,IAAI,CACtI,CAAC,CACF,CAAC;AACJ,CAAC;AAED;;;;;;;;;;;;;;;;;;;;;;;GAuBG;AACH,MAAM,UAAU,eAAe,CAAC,GAK/B;IACC,IAAI,GAAG,CAAC,MAAM,KAAK,OAAO;QAAE,OAAO,KAAK,CAAC;IACzC,IAAI,GAAG,CAAC,MAAM;QAAE,OAAO,KAAK,CAAC;IAC7B,IAAI,GAAG,CAAC,MAAM,KAAK,WAAW;QAAE,OAAO,IAAI,CAAC;IAC5C,IAAI,GAAG,CAAC,MAAM;QAAE,OAAO,KAAK,CAAC;IAC7B,OAAO,CAAC,GAAG,CAAC,MAAM,CAAC;AACrB,CAAC;AAED;;;;;;GAMG;AACH,MAAM,UAAU,oBAAoB,CAClC,OAA6B,EAC7B,OAAe;IAEf,MAAM,IAAI,GAAG,CAAC,CAAS,EAAE,EAAE,CAAC,CAAC,CAAC,WAAW,EAAE,CAAC,OAAO,CAAC,MAAM,EAAE,GAAG,CAAC,CAAC,IAAI,EAAE,CAAC;IACxE,MAAM,MAAM,GAAG,IAAI,CAAC,OAAO,CAAC,CAAC;IAC7B,OAAO,OAAO,CAAC,IAAI,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,IAAI,CAAC,CAAC,CAAC,OAAO,CAAC,KAAK,MAAM,CAAC,CAAC;AACzD,CAAC;AAED;;iFAEiF;AACjF,MAAM,CAAC,MAAM,kBAAkB,GAAG,CAAC,GAAG,EAAE,GAAG,IAAI,CAAC;AAEhD;;;;;;;;;;;;;;GAcG;AACH,MAAM,UAAU,mBAAmB,CACjC,MAA4B,EAC5B,OAAe,EACf,GAAW,EACX,WAAmB,kBAAkB;IAErC,MAAM,IAAI,GAAG,CAAC,CAAS,EAAE,EAAE,CAAC,CAAC,CAAC,WAAW,EAAE,CAAC,OAAO,CAAC,MAAM,EAAE,GAAG,CAAC,CAAC,IAAI,EAAE,CAAC;IACxE,MAAM,MAAM,GAAG,IAAI,CAAC,OAAO,CAAC,CAAC;IAC7B,OAAO,MAAM,CAAC,IAAI,CAChB,CAAC,CAAC,EAAE,EAAE,CACJ,CAAC,CAAC,MAAM,KAAK,SAAS;QACtB,CAAC,CAAC,KAAK;QACP,CAAC,CAAC,SAAS,KAAK,OAAO;QACvB,CAAC,CAAC,UAAU,KAAK,IAAI;QACrB,GAAG,GAAG,CAAC,CAAC,UAAU,GAAG,QAAQ;QAC7B,IAAI,CAAC,CAAC,CAAC,OAAO,CAAC,KAAK,MAAM,CAC7B,CAAC;AACJ,CAAC;AAuED,MAAM,MAAM,GAAG,IAAI,GAAG,EAAoB,CAAC;AAC3C,IAAI,iBAAiB,GAAG,KAAK,CAAC;AAE9B,MAAM,OAAO,gBAAgB;IAaR;IACA;IAbX,GAAG,GAAG,CAAC,CAAC;IACR,MAAM,GAAG,IAAI,GAAG,EAAiB,CAAC;IAClC,QAAQ,GAAwB,IAAI,CAAC;IAE7C;;;;;;OAMG;IACH,YACmB,iBAAiB,gBAAgB,EACjC,cAAc,aAAa;QAD3B,mBAAc,GAAd,cAAc,CAAmB;QACjC,gBAAW,GAAX,WAAW,CAAgB;QAE5C,MAAM,CAAC,GAAG,CAAC,IAAI,CAAC,CAAC;QACjB,eAAe,EAAE,CAAC;IACpB,CAAC;IAED,8EAA8E;IAC9E,WAAW,CAAC,EAAuB;QACjC,IAAI,CAAC,QAAQ,GAAG,EAAE,CAAC;IACrB,CAAC;IAED,6EAA6E;IAC7E,KAAK,CAAC,KAAmB,EAAE,IAAkB;QAC3C,MAAM,EAAE,GAAG,EAAE,IAAI,CAAC,GAAG,CAAC;QACtB,MAAM,KAAK,GAAU;YACnB,EAAE;YACF,OAAO,EAAE,IAAI,CAAC,OAAO;YACrB,GAAG,EAAE,IAAI,CAAC,GAAG;YACb,MAAM,EAAE,SAAS;YACjB,QAAQ,EAAE,IAAI;YACd,SAAS,EAAE,IAAI,CAAC,GAAG,EAAE;YACrB,UAAU,EAAE,IAAI;YAChB,KAAK;YACL,MAAM,EAAE,EAAE;YACV,UAAU,EAAE,CAAC;YACb,SAAS,EAAE,KAAK;YAChB,MAAM,EAAE,IAAI,CAAC,MAAM,IAAI,iBAAiB,CAAC,IAAI,CAAC,OAAO,CAAC;YACtD,KAAK,EAAE,KAAK;YACZ,QAAQ,EAAE,KAAK;YACf,UAAU,EAAE,KAAK;YACjB,SAAS,EAAE,KAAK;YAChB,aAAa,EAAE,KAAK;YACpB,eAAe,EAAE,KAAK;YACtB,UAAU,EAAE,IAAI;YAChB,OAAO,EAAE,IAAI,CAAC,OAAO;YACrB,QAAQ,EAAE,IAAI,CAAC,QAAQ;SACxB,CAAC;QACF,IAAI,CAAC,MAAM,CAAC,GAAG,CAAC,EAAE,EAAE,KAAK,CAAC,CAAC;QAC3B,IAAI,IAAI,CAAC,OAAO;YAAE,IAAI,CAAC,MAAM,CAAC,KAAK,EAAE,IAAI,CAAC,OAAO,CAAC,CAAC;QAEnD,iFAAiF;QACjF,iFAAiF;QACjF,mFAAmF;QACnF,gFAAgF;QAChF,4EAA4E;QAC5E,IAAI,KAAK,CAAC,MAAM,KAAK,YAAY,EAAE,CAAC;YAClC,KAAK,CAAC,UAAU,GAAG,UAAU,CAAC,GAAG,EAAE;gBACjC,KAAK,CAAC,UAAU,GAAG,IAAI,CAAC;gBACxB,IAAI,KAAK,CAAC,MAAM,KAAK,SAAS;oBAAE,OAAO;gBACvC,KAAK,CAAC,KAAK,GAAG,IAAI,CAAC;gBACnB,IAAI,CAAC,IAAI,EAAE,CAAC;YACd,CAAC,EAAE,IAAI,CAAC,cAAc,CAAC,CAAC;YACxB,KAAK,CAAC,UAAU,CAAC,KAAK,EAAE,EAAE,CAAC;QAC7B,CAAC;QAED,MAAM,OAAO,GAAG,CAAC,KAAa,EAAE,EAAE,CAAC,IAAI,CAAC,MAAM,CAAC,KAAK,EAAE,KAAK,CAAC,QAAQ,CAAC,MAAM,CAAC,CAAC,CAAC;QAC9E,KAAK,CAAC,MAAM,EAAE,EAAE,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;QAClC,KAAK,CAAC,MAAM,EAAE,EAAE,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;QAClC,+EAA+E;QAC/E,8EAA8E;QAC9E,SAAS;QACT,KAAK,CAAC,EAAE,CAAC,OAAO,EAAE,CAAC,IAAI,EAAE,MAAM,EAAE,EAAE,CAAC,IAAI,CAAC,OAAO,CAAC,KAAK,EAAE,IAAI,EAAE,MAAM,EAAE,KAAK,CAAC,CAAC,CAAC;QAC9E,KAAK,CAAC,EAAE,CAAC,OAAO,EAAE,GAAG,EAAE,CAAC,IAAI,CAAC,OAAO,CAAC,KAAK,EAAE,IAAI,EAAE,IAAI,EAAE,KAAK,CAAC,CAAC,CAAC;QAChE,iFAAiF;QACjF,mFAAmF;QACnF,iFAAiF;QACjF,KAAK,CAAC,EAAE,CAAC,MAAM,EAAE,CAAC,IAAI,EAAE,MAAM,EAAE,EAAE;YAChC,MAAM,KAAK,GAAG,UAAU,CAAC,GAAG,EAAE,CAAC,IAAI,CAAC,OAAO,CAAC,KAAK,EAAE,IAAI,EAAE,MAAM,EAAE,KAAK,CAAC,EAAE,IAAI,CAAC,WAAW,CAAC,CAAC;YAC3F,KAAK,CAAC,KAAK,EAAE,EAAE,CAAC;QAClB,CAAC,CAAC,CAAC;QAEH,IAAI,CAAC,IAAI,EAAE,CAAC;QACZ,OAAO,IAAI,CAAC,KAAK,CAAC,CAAC;IACrB,CAAC;IAEO,MAAM,CAAC,KAAY,EAAE,IAAY;QACvC,KAAK,CAAC,MAAM,IAAI,IAAI,CAAC;QACrB,IAAI,KAAK,CAAC,MAAM,CAAC,MAAM,GAAG,gBAAgB,EAAE,CAAC;YAC3C,sEAAsE;YACtE,KAAK,CAAC,MAAM,GAAG,KAAK,CAAC,MAAM,CAAC,KAAK,CAAC,KAAK,CAAC,MAAM,CAAC,MAAM,GAAG,gBAAgB,CAAC,CAAC;YAC1E,KAAK,CAAC,UAAU,GAAG,IAAI,CAAC,GAAG,CAAC,KAAK,CAAC,UAAU,EAAE,KAAK,CAAC,MAAM,CAAC,MAAM,CAAC,CAAC;YACnE,KAAK,CAAC,SAAS,GAAG,IAAI,CAAC;QACzB,CAAC;IACH,CAAC;IAEO,OAAO,CACb,KAAY,EACZ,IAAmB,EACnB,MAAqB,EACrB,MAAe,EACf,EAAc;QAEd,IAAI,KAAK,CAAC,MAAM,KAAK,SAAS;YAAE,OAAO;QACvC,KAAK,CAAC,MAAM,GAAG,MAAM,CAAC,CAAC,CAAC,QAAQ,CAAC,CAAC,CAAC,QAAQ,CAAC;QAC5C,KAAK,CAAC,QAAQ,GAAG,IAAI,CAAC;QACtB,IAAI,MAAM;YAAE,KAAK,CAAC,MAAM,GAAG,MAAM,CAAC;QAClC,KAAK,CAAC,UAAU,GAAG,IAAI,CAAC,GAAG,EAAE,CAAC;QAC9B,KAAK,CAAC,KAAK,GAAG,IAAI,CAAC;QACnB,IAAI,EAAE;YAAE,KAAK,CAAC,SAAS,GAAG,EAAE,CAAC;QAC7B,IAAI,KAAK,CAAC,UAAU,EAAE,CAAC;YACrB,YAAY,CAAC,KAAK,CAAC,UAAU,CAAC,CAAC;YAC/B,KAAK,CAAC,UAAU,GAAG,IAAI,CAAC;QAC1B,CAAC;QACD,mFAAmF;QACnF,oFAAoF;QACpF,8DAA8D;QAC9D,KAAK,CAAC,aAAa,GAAG,IAAI,CAAC;QAC3B,KAAK,CAAC,eAAe,GAAG,IAAI,CAAC;QAC7B,iFAAiF;QACjF,oFAAoF;QACpF,kFAAkF;QAClF,qCAAqC;QACrC,KAAK,CAAC,SAAS,GAAG,eAAe,CAAC;YAChC,MAAM,EAAE,KAAK,CAAC,MAAM;YACpB,MAAM;YACN,MAAM;YACN,MAAM,EAAE,KAAK,CAAC,KAAK;SACpB,CAAC,CAAC;QACH,IAAI,KAAK,CAAC,OAAO;YAAE,KAAK,EAAE,CAAC,EAAE,CAAC,KAAK,CAAC,OAAO,EAAE,EAAE,KAAK,EAAE,IAAI,EAAE,CAAC,CAAC,KAAK,CAAC,GAAG,EAAE,GAAE,CAAC,CAAC,CAAC;QAC9E,IAAI,KAAK,CAAC,QAAQ;YAAE,KAAK,EAAE,CAAC,EAAE,CAAC,KAAK,CAAC,QAAQ,EAAE,EAAE,KAAK,EAAE,IAAI,EAAE,CAAC,CAAC,KAAK,CAAC,GAAG,EAAE,GAAE,CAAC,CAAC,CAAC;QAChF,IAAI,CAAC,IAAI,EAAE,CAAC;IACd,CAAC;IAED,6EAA6E;IAC7E,KAAK,CAAC,IAAI,CAAC,EAAU;QACnB,MAAM,KAAK,GAAG,IAAI,CAAC,MAAM,CAAC,GAAG,CAAC,EAAE,CAAC,CAAC;QAClC,IAAI,CAAC,KAAK;YAAE,OAAO,IAAI,CAAC;QACxB,IAAI,KAAK,GAAG,KAAK,CAAC,MAAM,CAAC,KAAK,CAAC,KAAK,CAAC,UAAU,CAAC,CAAC;QACjD,KAAK,CAAC,UAAU,GAAG,KAAK,CAAC,MAAM,CAAC,MAAM,CAAC;QACvC,IAAI,KAAK,CAAC,MAAM,GAAG,cAAc,EAAE,CAAC;YAClC,KAAK,GAAG,+BAA+B,KAAK,CAAC,KAAK,CAAC,KAAK,CAAC,MAAM,GAAG,cAAc,CAAC,EAAE,CAAC;QACtF,CAAC;QACD,OAAO,EAAE,IAAI,EAAE,IAAI,CAAC,KAAK,CAAC,EAAE,KAAK,EAAE,CAAC;IACtC,CAAC;IAED;;;;;;OAMG;IACH,IAAI,CAAC,EAAU,EAAE,KAAgB,OAAO;QACtC,MAAM,KAAK,GAAG,IAAI,CAAC,MAAM,CAAC,GAAG,CAAC,EAAE,CAAC,CAAC;QAClC,IAAI,CAAC,KAAK,IAAI,KAAK,CAAC,MAAM,KAAK,SAAS,IAAI,CAAC,KAAK,CAAC,KAAK;YAAE,OAAO,KAAK,CAAC;QACvE,QAAQ,CAAC,KAAK,CAAC,KAAK,CAAC,GAAG,CAAC,CAAC;QAC1B,IAAI,CAAC,OAAO,CAAC,KAAK,EAAE,IAAI,EAAE,IAAI,EAAE,IAAI,EAAE,EAAE,CAAC,CAAC;QAC1C,OAAO,IAAI,CAAC;IACd,CAAC;IAED,IAAI;QACF,OAAO,CAAC,GAAG,IAAI,CAAC,MAAM,CAAC,MAAM,EAAE,CAAC,CAAC,GAAG,CAAC,IAAI,CAAC,CAAC;IAC7C,CAAC;IACD,OAAO;QACL,OAAO,IAAI,CAAC,IAAI,EAAE,CAAC,MAAM,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,MAAM,KAAK,SAAS,CAAC,CAAC;IAC3D,CAAC;IACD,YAAY;QACV,OAAO,IAAI,CAAC,OAAO,EAAE,CAAC,MAAM,CAAC;IAC/B,CAAC;IACD;;;;;;;OAOG;IACH,YAAY;QACV,OAAO,CAAC,GAAG,IAAI,CAAC,MAAM,CAAC,MAAM,EAAE,CAAC,CAAC,MAAM,CACrC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,CAAC,MAAM,KAAK,SAAS,IAAI,CAAC,CAAC,CAAC,QAAQ,IAAI,CAAC,CAAC,SAAS,CAAC,IAAI,CAAC,CAAC,CAAC,KAAK,IAAI,CAAC,CAAC,CAAC,aAAa,CAAC,CAC/F,CAAC,MAAM,CAAC;IACX,CAAC;IAED,sFAAsF;IACtF,YAAY;QACV,MAAM,GAAG,GAAgD,EAAE,CAAC;QAC5D,KAAK,MAAM,KAAK,IAAI,IAAI,CAAC,MAAM,CAAC,MAAM,EAAE,EAAE,CAAC;YACzC,IAAI,KAAK,CAAC,KAAK,IAAI,CAAC,KAAK,CAAC,eAAe,EAAE,CAAC;gBAC1C,KAAK,CAAC,eAAe,GAAG,IAAI,CAAC;gBAC7B,GAAG,CAAC,IAAI,CAAC,EAAE,IAAI,EAAE,IAAI,CAAC,KAAK,CAAC,EAAE,IAAI,EAAE,OAAO,EAAE,CAAC,CAAC;YACjD,CAAC;YACD,IAAI,KAAK,CAAC,MAAM,KAAK,SAAS,IAAI,CAAC,KAAK,CAAC,UAAU,EAAE,CAAC;gBACpD,KAAK,CAAC,UAAU,GAAG,IAAI,CAAC;gBACxB,GAAG,CAAC,IAAI,CAAC,EAAE,IAAI,EAAE,IAAI,CAAC,KAAK,CAAC,EAAE,IAAI,EAAE,OAAO,EAAE,CAAC,CAAC;YACjD,CAAC;QACH,CAAC;QACD,OAAO,GAAG,CAAC;IACb,CAAC;IAED;;;;;;;;;;;OAWG;IACH,KAAK,CAAC,WAAW;QAGf,MAAM,GAAG,GAA6E,EAAE,CAAC;QACzF,MAAM,MAAM,GAAG,CAAC,KAAY,EAAE,EAAE,CAAC,KAAK,CAAC,MAAM,CAAC,KAAK,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC,EAAE,KAAK,CAAC,MAAM,CAAC,MAAM,GAAG,UAAU,CAAC,CAAC,CAAC;QACnG,KAAK,MAAM,KAAK,IAAI,IAAI,CAAC,MAAM,CAAC,MAAM,EAAE,EAAE,CAAC;YACzC,IAAI,KAAK,CAAC,KAAK,IAAI,CAAC,KAAK,CAAC,aAAa,EAAE,CAAC;gBACxC,KAAK,CAAC,aAAa,GAAG,IAAI,CAAC;gBAC3B,GAAG,CAAC,IAAI,CAAC,EAAE,IAAI,EAAE,IAAI,CAAC,KAAK,CAAC,EAAE,IAAI,EAAE,OAAO,EAAE,IAAI,EAAE,MAAM,CAAC,KAAK,CAAC,EAAE,IAAI,EAAE,IAAI,EAAE,CAAC,CAAC;YAClF,CAAC;YACD,IAAI,KAAK,CAAC,MAAM,KAAK,SAAS,IAAI,CAAC,KAAK,CAAC,QAAQ,EAAE,CAAC;gBAClD,KAAK,CAAC,QAAQ,GAAG,IAAI,CAAC;gBACtB,GAAG,CAAC,IAAI,CAAC,EAAE,IAAI,EAAE,IAAI,CAAC,KAAK,CAAC,EAAE,IAAI,EAAE,OAAO,EAAE,IAAI,EAAE,MAAM,CAAC,KAAK,CAAC,EAAE,IAAI,EAAE,KAAK,CAAC,SAAS,EAAE,CAAC,CAAC;YAC7F,CAAC;QACH,CAAC;QACD,OAAO,GAAG,CAAC;IACb,CAAC;IAED;;;;;;OAMG;IACH,OAAO,CAAC,IAAI,GAAG,KAAK;QAClB,KAAK,MAAM,KAAK,IAAI,IAAI,CAAC,MAAM,CAAC,MAAM,EAAE,EAAE,CAAC;YACzC,wEAAwE;YACxE,8EAA8E;YAC9E,+EAA+E;YAC/E,6EAA6E;YAC7E,2EAA2E;YAC3E,+EAA+E;YAC/E,0EAA0E;YAC1E,yEAAyE;YACzE,IAAI,KAAK,CAAC,KAAK,EAAE,CAAC;gBAChB,IAAI,IAAI;oBAAE,YAAY,CAAC,KAAK,CAAC,KAAK,CAAC,GAAG,CAAC,CAAC;;oBACnC,QAAQ,CAAC,KAAK,CAAC,KAAK,CAAC,GAAG,CAAC,CAAC;YACjC,CAAC;YACD,IAAI,KAAK,CAAC,OAAO;gBAAE,KAAK,EAAE,CAAC,EAAE,CAAC,KAAK,CAAC,OAAO,EAAE,EAAE,KAAK,EAAE,IAAI,EAAE,CAAC,CAAC,KAAK,CAAC,GAAG,EAAE,GAAE,CAAC,CAAC,CAAC;YAC9E,IAAI,KAAK,CAAC,QAAQ;gBAAE,KAAK,EAAE,CAAC,EAAE,CAAC,KAAK,CAAC,QAAQ,EAAE,EAAE,KAAK,EAAE,IAAI,EAAE,CAAC,CAAC,KAAK,CAAC,GAAG,EAAE,GAAE,CAAC,CAAC,CAAC;QAClF,CAAC;QACD,IAAI,CAAC,MAAM,CAAC,KAAK,EAAE,CAAC;QACpB,MAAM,CAAC,MAAM,CAAC,IAAI,CAAC,CAAC;IACtB,CAAC;IAEO,IAAI;QACV,IAAI,CAAC,QAAQ,EAAE,EAAE,CAAC;IACpB,CAAC;CACF;AAED,SAAS,IAAI,CAAC,CAAQ;IACpB,OAAO;QACL,EAAE,EAAE,CAAC,CAAC,EAAE;QACR,OAAO,EAAE,CAAC,CAAC,OAAO;QAClB,GAAG,EAAE,CAAC,CAAC,GAAG;QACV,MAAM,EAAE,CAAC,CAAC,MAAM;QAChB,QAAQ,EAAE,CAAC,CAAC,QAAQ;QACpB,SAAS,EAAE,CAAC,CAAC,SAAS;QACtB,UAAU,EAAE,CAAC,CAAC,UAAU;QACxB,MAAM,EAAE,CAAC,CAAC,MAAM;QAChB,KAAK,EAAE,CAAC,CAAC,KAAK;QACd,GAAG,CAAC,CAAC,CAAC,MAAM,CAAC,CAAC,CAAC,EAAE,MAAM,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;QACzC,GAAG,CAAC,CAAC,CAAC,SAAS,CAAC,CAAC,CAAC,EAAE,SAAS,EAAE,CAAC,CAAC,SAAS,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;QAClD,GAAG,CAAC,CAAC,CAAC,SAAS,CAAC,CAAC,CAAC,EAAE,SAAS,EAAE,IAAI,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;QAC3C,GAAG,CAAC,UAAU,CAAC,CAAC,CAAC,MAAM,CAAC,KAAK,SAAS,CAAC,CAAC,CAAC,EAAE,IAAI,EAAE,UAAU,CAAC,CAAC,CAAC,MAAM,CAAC,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;KAC9E,CAAC;AACJ,CAAC;AAED,0EAA0E;AAC1E,SAAS,eAAe;IACtB,IAAI,iBAAiB;QAAE,OAAO;IAC9B,iBAAiB,GAAG,IAAI,CAAC;IACzB,OAAO,CAAC,IAAI,CAAC,MAAM,EAAE,GAAG,EAAE;QACxB,iEAAiE;QACjE,KAAK,MAAM,GAAG,IAAI,MAAM;YAAE,GAAG,CAAC,OAAO,CAAC,IAAI,CAAC,CAAC;IAC9C,CAAC,CAAC,CAAC;AACL,CAAC;AAED;;;;;;;;;;;GAWG;AACH,MAAM,UAAU,UAAU,CAAC,MAAc;IACvC,MAAM,CAAC,GACL,yEAAyE,CAAC,IAAI,CAAC,MAAM,CAAC;QACtF,0EAA0E,CAAC,IAAI,CAAC,MAAM,CAAC,CAAC;IAC1F,IAAI,CAAC,CAAC;QAAE,OAAO,SAAS,CAAC;IACzB,MAAM,IAAI,GAAG,MAAM,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC;IAC1B,OAAO,IAAI,IAAI,CAAC,IAAI,IAAI,IAAI,KAAK,CAAC,CAAC,CAAC,IAAI,CAAC,CAAC,CAAC,SAAS,CAAC;AACvD,CAAC"}

package/dist/tools/captureSweep.js

@@ -0,0 +1,77 @@
+/**
+ * captureSweep.ts — clear out screenshots that have outlived their usefulness.
+ *
+ * `screenshot` writes each capture to its own temp directory so the model can be
+ * handed the file and compaction can drop and restore the reference. Nothing removed
+ * them, so every window ever photographed stayed on disk indefinitely — and unlike
+ * the rest of the agent's temp files, a capture holds whatever happened to be on
+ * screen at the time.
+ *
+ * Deleting immediately after sending was considered and rejected: the reference
+ * survives in the transcript, compaction can bring an image back, and a capture the
+ * model may still be asked about should not be a dangling path. So they live for a
+ * few days and are swept by age at startup, which also catches anything left behind
+ * by a crash — the case a shutdown hook would miss.
+ *
+ * Best-effort throughout. A sweep that cannot read the temp directory, or that races
+ * another Mindweave deleting the same folder, must never keep the CLI from starting.
+ */
+import { readdir, rm, stat } from "node:fs/promises";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+/** How long a capture is kept. One edit changes the policy. */
+export const CAPTURE_MAX_AGE_MS = 7 * 24 * 60 * 60 * 1000; // 7 days
+/** Temp directory prefixes this sweep owns. Must match what creates them. */
+export const SWEPT_PREFIXES = ["mindweave-shot-"];
+/** Does this directory name belong to us? (pure) */
+export function isSweptName(name) {
+    return SWEPT_PREFIXES.some((p) => name.startsWith(p));
+}
+/**
+ * Should an entry be removed, given its age? (pure)
+ *
+ * Split out from the I/O so the policy can be tested without fabricating timestamps
+ * on a real filesystem, and so "how old is too old" is one comparison in one place.
+ */
+export function isExpired(mtimeMs, now, maxAgeMs = CAPTURE_MAX_AGE_MS) {
+    return now - mtimeMs > maxAgeMs;
+}
+/**
+ * Remove expired capture directories. Returns how many went.
+ *
+ * `dir` and `now` are parameters so tests drive a fabricated tree rather than the
+ * real temp directory, where a stray match would delete a developer's actual files.
+ */
+export async function sweepCaptures(dir = tmpdir(), now = Date.now(), maxAgeMs = CAPTURE_MAX_AGE_MS) {
+    let removed = 0;
+    let names;
+    try {
+        names = await readdir(dir);
+    }
+    catch {
+        return 0; // unreadable temp directory is not our problem to solve
+    }
+    for (const name of names) {
+        if (!isSweptName(name))
+            continue;
+        const full = join(dir, name);
+        try {
+            const info = await stat(full);
+            if (!info.isDirectory())
+                continue;
+            if (!isExpired(info.mtimeMs, now, maxAgeMs))
+                continue;
+            await rm(full, { recursive: true, force: true });
+            removed++;
+        }
+        catch {
+            // Vanished under us, locked, or not ours to delete. Skip it.
+        }
+    }
+    return removed;
+}
+/** Fire-and-forget sweep for startup: never awaited, never throws, never logs. */
+export function sweepCapturesInBackground() {
+    void sweepCaptures().catch(() => { });
+}
+//# sourceMappingURL=captureSweep.js.map

package/dist/tools/captureSweep.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"captureSweep.js","sourceRoot":"","sources":["../../src/tools/captureSweep.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;GAiBG;AACH,OAAO,EAAE,OAAO,EAAE,EAAE,EAAE,IAAI,EAAE,MAAM,kBAAkB,CAAC;AACrD,OAAO,EAAE,MAAM,EAAE,MAAM,SAAS,CAAC;AACjC,OAAO,EAAE,IAAI,EAAE,MAAM,WAAW,CAAC;AAEjC,+DAA+D;AAC/D,MAAM,CAAC,MAAM,kBAAkB,GAAG,CAAC,GAAG,EAAE,GAAG,EAAE,GAAG,EAAE,GAAG,IAAI,CAAC,CAAC,SAAS;AAEpE,6EAA6E;AAC7E,MAAM,CAAC,MAAM,cAAc,GAAG,CAAC,iBAAiB,CAAU,CAAC;AAE3D,oDAAoD;AACpD,MAAM,UAAU,WAAW,CAAC,IAAY;IACtC,OAAO,cAAc,CAAC,IAAI,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,IAAI,CAAC,UAAU,CAAC,CAAC,CAAC,CAAC,CAAC;AACxD,CAAC;AAED;;;;;GAKG;AACH,MAAM,UAAU,SAAS,CAAC,OAAe,EAAE,GAAW,EAAE,QAAQ,GAAG,kBAAkB;IACnF,OAAO,GAAG,GAAG,OAAO,GAAG,QAAQ,CAAC;AAClC,CAAC;AAED;;;;;GAKG;AACH,MAAM,CAAC,KAAK,UAAU,aAAa,CACjC,MAAc,MAAM,EAAE,EACtB,MAAc,IAAI,CAAC,GAAG,EAAE,EACxB,WAAmB,kBAAkB;IAErC,IAAI,OAAO,GAAG,CAAC,CAAC;IAChB,IAAI,KAAe,CAAC;IACpB,IAAI,CAAC;QACH,KAAK,GAAG,MAAM,OAAO,CAAC,GAAG,CAAC,CAAC;IAC7B,CAAC;IAAC,MAAM,CAAC;QACP,OAAO,CAAC,CAAC,CAAC,wDAAwD;IACpE,CAAC;IAED,KAAK,MAAM,IAAI,IAAI,KAAK,EAAE,CAAC;QACzB,IAAI,CAAC,WAAW,CAAC,IAAI,CAAC;YAAE,SAAS;QACjC,MAAM,IAAI,GAAG,IAAI,CAAC,GAAG,EAAE,IAAI,CAAC,CAAC;QAC7B,IAAI,CAAC;YACH,MAAM,IAAI,GAAG,MAAM,IAAI,CAAC,IAAI,CAAC,CAAC;YAC9B,IAAI,CAAC,IAAI,CAAC,WAAW,EAAE;gBAAE,SAAS;YAClC,IAAI,CAAC,SAAS,CAAC,IAAI,CAAC,OAAO,EAAE,GAAG,EAAE,QAAQ,CAAC;gBAAE,SAAS;YACtD,MAAM,EAAE,CAAC,IAAI,EAAE,EAAE,SAAS,EAAE,IAAI,EAAE,KAAK,EAAE,IAAI,EAAE,CAAC,CAAC;YACjD,OAAO,EAAE,CAAC;QACZ,CAAC;QAAC,MAAM,CAAC;YACP,6DAA6D;QAC/D,CAAC;IACH,CAAC;IACD,OAAO,OAAO,CAAC;AACjB,CAAC;AAED,kFAAkF;AAClF,MAAM,UAAU,yBAAyB;IACvC,KAAK,aAAa,EAAE,CAAC,KAAK,CAAC,GAAG,EAAE,GAAE,CAAC,CAAC,CAAC;AACvC,CAAC"}

package/dist/tools/chassisMux.js

@@ -0,0 +1,92 @@
+/**
+ * chassisMux.ts — query the right code map(s) in a multi-root workspace.
+ *
+ * Each session root has its own chassis (a code map only knows its own files). The
+ * code-intelligence tools route through here so they stay correct across roots:
+ *   - path queries (outline) hit the chassis that OWNS the file;
+ *   - name queries (definition/references) MERGE across every root;
+ *   - relevance ranks within each root, then merges by score.
+ * Single-root sessions fall straight through to the one chassis — no overhead.
+ */
+import { isAbsolute, relative } from "node:path";
+import { CodeGraph } from "../alternator/chassis/graph.js";
+/** Every chassis in play (per-root set, or just the primary). */
+export function allChassis(ctx) {
+    if (ctx.chassisByRoot && ctx.chassisByRoot.size > 0)
+        return [...ctx.chassisByRoot.values()];
+    return ctx.chassis ? [ctx.chassis] : [];
+}
+/** The chassis whose root contains `abs`, or the primary as a fallback. */
+export function chassisForPath(ctx, abs) {
+    if (ctx.chassisByRoot) {
+        for (const [root, chassis] of ctx.chassisByRoot) {
+            const rel = relative(root, abs);
+            if (rel === "" || (!rel.startsWith("..") && !isAbsolute(rel)))
+                return chassis;
+        }
+    }
+    return ctx.chassis;
+}
+/**
+ * Confidence for a MERGED list, which is the confidence of its weakest part.
+ *
+ * The merged list is one list to the reader, and the caveat printed from this value
+ * governs all of it. So a root running a language server must not vouch for a root
+ * that is on the tree-sitter tier: taking the best there marks name-level entries
+ * `resolved` purely by association, and `resolved` is exactly what suppresses the
+ * "verify with grep" note those entries need. Each `Ref` still carries its own
+ * per-entry confidence for anyone who wants the finer answer.
+ */
+function mergedConfidence(values) {
+    return values.every((c) => c === "resolved") && values.length > 0 ? "resolved" : "name-level";
+}
+/** Where a symbol is defined, merged across every root. */
+export async function mergedDefinition(ctx, name) {
+    const list = allChassis(ctx);
+    if (list.length === 1)
+        return list[0].definition(name);
+    const symbols = [];
+    const confidences = [];
+    for (const ch of list) {
+        const r = await ch.definition(name);
+        symbols.push(...r.symbols);
+        if (r.symbols.length)
+            confidences.push(r.confidence);
+    }
+    return { symbols, confidence: mergedConfidence(confidences) };
+}
+/** Who references a symbol, merged across every root. */
+export async function mergedReferences(ctx, name) {
+    const list = allChassis(ctx);
+    if (list.length === 1)
+        return list[0].references(name);
+    const refs = [];
+    const confidences = [];
+    for (const ch of list) {
+        const r = await ch.references(name);
+        refs.push(...r.refs);
+        if (r.refs.length)
+            confidences.push(r.confidence);
+    }
+    return { refs, confidence: mergedConfidence(confidences) };
+}
+/** The span(s) of a named symbol's definition, across every root. A `path` is only
+ *  ever inside one root, so passing it naturally narrows the result to that root. */
+export async function symbolSpans(ctx, name, opts = {}) {
+    const list = allChassis(ctx);
+    if (list.length === 0)
+        return [];
+    if (list.length === 1)
+        return list[0].span(name, opts);
+    const spans = [];
+    for (const ch of list)
+        spans.push(...(await ch.span(name, opts)));
+    return spans;
+}
+/** A chassis's underlying code graph, if it exposes one (CodeChassis does; the
+ *  null/test chassis may not). */
+function graphOf(chassis) {
+    const g = chassis.graphRef?.();
+    return g instanceof CodeGraph ? g : null;
+}
+//# sourceMappingURL=chassisMux.js.map