openmausbot 0.1.83 → 0.1.85

package/dist-server/proxy-paths.js

@@ -18,6 +18,7 @@ var SPAWNED_PROXIES = {
   connectors: resolveProxy("connector-proxy"),
   mcpGate: resolveProxy("mcp-gate"),
   phone: resolveProxy("drivers/phone-proxy"),
+  hook: resolveProxy("hooks/omb-hook"),
   // Loaded by the external `pi` process via `-e`, not by this server — but
   // resolved through the same single source of truth so the packaged layout
   // check can assert it ships.

package/dist-server/server/agent-tool-policy.js

@@ -14,6 +14,7 @@ export const READ_ONLY_AGENT_TOOL_NAMES = new Set([
     "wait_delegation",
     "session_search",
     "session_read",
+    "tool_result_read",
     "list_routines",
     "skills_list",
 ]);

package/dist-server/server/bot-package.js

@@ -170,6 +170,7 @@ const packageSchema = z.object({
             schedule: packageRoutineScheduleSchema,
             durationMinutes: z.number().int().min(5).max(240),
             timeoutMinutes: z.number().int().min(5).max(240).optional(),
+            overlap: z.enum(["skip", "queue"]).optional(),
             enabledAfterInstall: z.literal(false),
         })).max(50).optional(),
         playbooks: z.array(z.object({
@@ -339,6 +340,7 @@ export function renderBotPackageMarkdown(document) {
                     ? intervalScheduleText(routine.schedule)
                     : `once at ${routine.schedule.at}`}  `,
         `**Run limit:** ${routine.timeoutMinutes === undefined ? "none" : `${routine.timeoutMinutes} minutes`}  `,
+        `**While busy:** ${routine.overlap === "queue" ? "queue one scheduled run" : "skip scheduled occurrences"}  `,
         "**Initial state:** paused — the user must enable it",
         "",
         routine.prompt,

package/dist-server/server/box.js

@@ -1229,23 +1229,42 @@ export function panelShotCommand({ width = PANEL_FRAME_WIDTH, quality = PANEL_FR
     ].join("; ");
 }
 const SHOT_CMD = panelShotCommand();
+// A compromised box can answer with an arbitrarily large "frame"; cap what
+// the server ever buffers for one (raw bytes, before base64) so a single
+// response cannot exhaust memory.
+const MAX_FRAME_BYTES = 8 * 1024 * 1024;
+const FRAME_TOO_LARGE = "the box frame exceeds the 8 MB limit";
 /** Read a file off the box as base64 — raw artifact bytes when the API
  * supports it (33% less transfer, no JSON envelope), else the files API. */
 async function readFileBase64(cfg, boxId, path) {
+    let bytes = null;
+    let tooLarge = false;
     try {
         const res = await boxFetch(cfg, `/boxes/${boxId}/artifacts?path=${encodeURIComponent(path)}`);
         if (res.ok) {
-            const bytes = Buffer.from(await res.arrayBuffer());
-            if (bytes.length)
-                return bytes.toString("base64");
+            const declaredLength = res.headers.get("content-length");
+            if (declaredLength !== null && Number(declaredLength) > MAX_FRAME_BYTES)
+                tooLarge = true;
+            else
+                bytes = Buffer.from(await res.arrayBuffer());
         }
     }
     catch {
         /* fall through */
     }
+    if (tooLarge || (bytes !== null && bytes.length > MAX_FRAME_BYTES)) {
+        throw new Error(FRAME_TOO_LARGE);
+    }
+    if (bytes?.length)
+        return bytes.toString("base64");
     const { ok, body } = await boxJson(cfg, `/boxes/${boxId}/files?path=${encodeURIComponent(path)}&encoding=base64`);
     const content = body?.content;
-    return ok && typeof content === "string" && content ? content : null;
+    if (ok && typeof content === "string" && content) {
+        if (Buffer.byteLength(content, "base64") > MAX_FRAME_BYTES)
+            throw new Error(FRAME_TOO_LARGE);
+        return content;
+    }
+    return null;
 }
 /** `knownBoxId` skips box resolution entirely — the screen poller holds
  * the id for the whole turn and must not re-resolve it every frame. */

package/dist-server/server/browser-engine.js

@@ -25,7 +25,7 @@ const DOWNLOAD_TIMEOUT_MS = 10 * 60_000;
 /** Native restore looks up a filename prefix. Fixed-length keys prevent a
  * legacy profile named work from accidentally restoring work-client. */
 export function browserRestoreKey(session) {
-    if (!/^[A-Za-z0-9_-]{1,96}$/.test(session))
+    if (!/^[A-Za-z0-9_.-]{1,96}$/.test(session))
         throw new Error("Invalid browser session.");
     return `omb-${createHash("sha256").update(session).digest("hex")}`;
 }
@@ -56,7 +56,7 @@ function ensureManagedBrowserConfig(env) {
 }
 /** Close exactly one daemon without the CLI's implicit launch envelope. */
 export async function closeBrowserSession(binaryPath, env, timeoutMs = 15_000) {
-    if (!env.AGENT_BROWSER_SESSION || !/^[A-Za-z0-9_-]{1,96}$/.test(env.AGENT_BROWSER_SESSION))
+    if (!env.AGENT_BROWSER_SESSION || !/^[A-Za-z0-9_.-]{1,96}$/.test(env.AGENT_BROWSER_SESSION))
         return false;
     // Native CLI prepends a launch even to `close` when launch flags are set.
     // Remove them, and bypass external project/user config, so closing a
@@ -85,7 +85,16 @@ export async function closeBrowserSession(binaryPath, env, timeoutMs = 15_000) {
         catch {
             return finish(false);
         }
-        const timer = setTimeout(() => { child.kill(); finish(false); }, Math.max(1, deadline - Date.now()));
+        let exited = false;
+        let killTimer;
+        const timer = setTimeout(() => {
+            // TERM lets the daemon flush; KILL after a grace period reaps a stuck one.
+            child.kill("SIGTERM");
+            killTimer = setTimeout(() => { if (!exited)
+                child.kill("SIGKILL"); }, 5_000);
+            killTimer.unref?.();
+            finish(false);
+        }, Math.max(1, deadline - Date.now()));
         timer.unref?.();
         child.stdout?.on("data", (chunk) => {
             output += String(chunk);
@@ -95,9 +104,9 @@ export async function closeBrowserSession(binaryPath, env, timeoutMs = 15_000) {
                 finish(false);
             }
         });
-        child.on("error", () => { clearTimeout(timer); finish(false); });
+        child.on("error", () => { exited = true; clearTimeout(timer); clearTimeout(killTimer); finish(false); });
         // exit can precede the last piped stdout chunk; close follows stdio.
-        child.on("close", (code) => { clearTimeout(timer); finish(code === 0); });
+        child.on("close", (code) => { exited = true; clearTimeout(timer); clearTimeout(killTimer); finish(code === 0); });
     });
     if (!(await run(["close"])).ok)
         return false;
@@ -241,6 +250,8 @@ export function resolveAgentBrowserBinary(options = {}) {
     const pinned = pinnedBinaryPath(options.dataDir, platform, options.arch);
     if (exists(pinned))
         return pinned;
+    if (options.managedOnly)
+        return null;
     return onPath(env, platform, exists);
 }
 /** Download the pinned release asset for this machine into the data dir,
@@ -263,7 +274,35 @@ export async function installAgentBrowserBinary(options = {}) {
         const response = await (options.fetchImpl ?? fetch)(url, { redirect: "follow", signal: controller.signal });
         if (!response.ok)
             throw new Error(`the agent-browser download failed (HTTP ${response.status})`);
-        body = Buffer.from(await response.arrayBuffer());
+        const declared = Number(response.headers.get("content-length") ?? NaN);
+        if (Number.isFinite(declared) && declared !== asset.bytes)
+            throw new Error("the agent-browser download did not match its pinned size; nothing was installed");
+        // Stream, never buffer whole: a body past the pin is cut off mid-flight.
+        const chunks = [];
+        let received = 0;
+        if (response.body) {
+            try {
+                for await (const chunk of response.body) {
+                    chunks.push(chunk);
+                    received += chunk.byteLength;
+                    if (received > asset.bytes) {
+                        controller.abort();
+                        break;
+                    }
+                }
+            }
+            catch (error) {
+                // Only the abort we asked for is swallowed; the size check reports it.
+                if (received <= asset.bytes)
+                    throw error;
+            }
+            body = Buffer.concat(chunks);
+        }
+        else {
+            body = Buffer.from(await response.arrayBuffer());
+            if (body.length > asset.bytes)
+                controller.abort();
+        }
     }
     finally {
         clearTimeout(timer);
@@ -273,6 +312,18 @@ export async function installAgentBrowserBinary(options = {}) {
     const digest = createHash("sha256").update(body).digest("hex");
     if (digest !== asset.sha256)
         throw new Error("the agent-browser download failed its SHA-256 check; nothing was installed");
+    // Sweep staging files abandoned by earlier runs before writing a new one.
+    try {
+        for (const name of readdirSync(directory)) {
+            if (!name.endsWith(".part"))
+                continue;
+            try {
+                unlinkSync(join(directory, name));
+            }
+            catch { /* already gone */ }
+        }
+    }
+    catch { /* best effort */ }
     const staging = `${destination}.${randomBytes(6).toString("hex")}.part`;
     writeFileSync(staging, body, { mode: 0o755 });
     if (platform !== "win32")
@@ -293,10 +344,34 @@ export function ensureChrome(binaryPath, options = {}) {
     return new Promise((done, fail) => {
         const child = spawn(binaryPath, args, { env: options.env ?? process.env, stdio: ["ignore", "pipe", "pipe"], windowsHide: true });
         let output = "";
-        child.stdout?.on("data", (chunk) => { output += String(chunk); });
-        child.stderr?.on("data", (chunk) => { output += String(chunk); });
-        child.on("error", fail);
+        // Keep only the tail: the failure path quotes the last lines, so a chatty
+        // installer cannot grow the buffer without bound while it hangs.
+        const record = (chunk) => {
+            output += String(chunk);
+            if (output.length > 262_144)
+                output = output.slice(-262_144);
+        };
+        child.stdout?.on("data", record);
+        child.stderr?.on("data", record);
+        let timedOut = false;
+        let exited = false;
+        // A hung installer gets the same wall clock as the download: TERM, then
+        // KILL after a grace period, with the promise failing at the deadline.
+        const timer = setTimeout(() => {
+            timedOut = true;
+            child.kill("SIGTERM");
+            const killTimer = setTimeout(() => { if (!exited)
+                child.kill("SIGKILL"); }, 5_000);
+            killTimer.unref?.();
+            fail(new Error("agent-browser install timed out"));
+        }, DOWNLOAD_TIMEOUT_MS);
+        timer.unref?.();
+        child.on("error", (error) => { exited = true; clearTimeout(timer); fail(error); });
         child.on("exit", (code) => {
+            exited = true;
+            clearTimeout(timer);
+            if (timedOut)
+                return; // already failed with the timeout error
             if (code === 0) {
                 options.log?.("agent-browser: Chrome is ready");
                 done();
@@ -369,6 +444,8 @@ export function agentBrowserIntegration(input) {
     };
     if (input.headless !== false)
         env.AGENT_BROWSER_HEADLESS = "1";
+    if (input.attachCdpUrl)
+        env.AGENT_BROWSER_CDP = input.attachCdpUrl;
     // MCP clients may filter the parent environment. Carry the configured
     // Chrome path explicitly without forwarding unrelated secrets or flags.
     for (const name of ["PATH", "AGENT_BROWSER_EXECUTABLE_PATH"]) {
@@ -464,7 +541,7 @@ export const BUILT_IN_BROWSER_SYSTEM_PROMPT = " You have your own web browser th
 export async function clearBrowserSessionState(binaryPath, session, options = {}) {
     // The native state-clear CLI ignores the daemon session, and even its named
     // form currently drops that name before dispatch. Never invoke it here.
-    if (!/^[A-Za-z0-9_-]{1,96}$/.test(session))
+    if (!/^[A-Za-z0-9_.-]{1,96}$/.test(session))
         return false;
     const env = browserRuntimeEnv({ ...options.env, AGENT_BROWSER_SESSION: session, AGENT_BROWSER_HEADLESS: "1" });
     let directory;

package/dist-server/server/browser-live.js

@@ -45,7 +45,7 @@ export function normalizeBrowserLiveMessage(value) {
     if (!message)
         return null;
     if (message.type === "error")
-        return { type: "error", message: "The browser stream was interrupted. Reopen the browser panel to reconnect." };
+        return { type: "error", retryable: true, message: "The browser stream was interrupted." };
     if (message.type === "url")
         return { type: "url", url: displayUrl(message.url) };
     if (message.type === "tabs" && Array.isArray(message.tabs) && message.tabs.length <= 100) {
@@ -292,7 +292,7 @@ export class BrowserLive {
         const env = browserRuntimeEnv({ ...viewer.spec.env, AGENT_BROWSER_SESSION: viewer.session });
         try {
             const { stdout } = await execute(viewer.spec.command, [...args, "--json", "--no-webmcp"], {
-                env, timeout: 30_000, maxBuffer: 1024 * 1024, encoding: "utf8", windowsHide: true,
+                env, timeout: 30_000, killSignal: "SIGKILL", maxBuffer: 1024 * 1024, encoding: "utf8", windowsHide: true,
             });
             if (!this.current(viewer))
                 throw new Error("stale viewer");
@@ -302,7 +302,8 @@ export class BrowserLive {
                 throw new Error("browser command failed");
             return data;
         }
-        catch {
+        catch (error) {
+            console.warn("browser-live:", error);
             throw new BrowserLiveError("The browser could not complete this action. Check that the browser engine is installed, then reconnect.", 503);
         }
     }
@@ -432,7 +433,7 @@ export class BrowserLive {
                     this.send(viewer, message);
             });
             socket.addEventListener("error", () => { if (!viewer.restarting) {
-                this.send(viewer, { type: "error", message: "The browser stream disconnected. Reopen the browser panel." });
+                this.send(viewer, { type: "error", retryable: true, message: "The browser stream disconnected." });
                 this.close(viewer);
             } });
             socket.addEventListener("close", () => { if (!viewer.restarting)
@@ -461,8 +462,9 @@ export class BrowserLive {
             viewer.heartbeat.unref();
         }
         catch (error) {
+            console.warn("browser-live:", error);
             if (options.res.headersSent) {
-                this.send(viewer, { type: "error", message: "The browser stream could not start. Reopen the browser panel." });
+                this.send(viewer, { type: "error", retryable: true, message: "The browser stream could not start." });
                 this.close(viewer);
                 return;
             }

package/dist-server/server/browser-runtime.js

@@ -3,6 +3,9 @@ import { DEFAULT_BROWSER_RESULT_BUDGET, shapeBrowserToolResult, slimBrowserToolL
 export const BROWSER_CONTROL_REFUSAL = "Browser tools are paused while a person controls this browser. Wait for them to hand control back; do not try another browser or execution tool.";
 const MAX_REQUEST_BYTES = 1_048_576;
 const MAX_RESPONSE_BYTES = 16_777_216;
+/** Startup, not per-request work: a cold engine spawn can exceed a tight
+ * per-request budget before anything has been accepted to guard. */
+const HANDSHAKE_TIMEOUT_MS = 1_000;
 const HOST_ENV = ["HOME", "USERPROFILE", "APPDATA", "LOCALAPPDATA", "PATH", "Path", "TMPDIR", "TMP", "TEMP", "SystemRoot", "WINDIR", "SYSTEMDRIVE", "COMSPEC", "PATHEXT", "LANG", "LC_ALL", "XDG_CONFIG_HOME", "XDG_CACHE_HOME", "XDG_RUNTIME_DIR"];
 /** MCP, viewer commands, and cleanup must resolve the same HOME/socket paths.
  * Inherit OS plumbing, never the harness's model-provider credentials. */
@@ -27,11 +30,13 @@ class BrowserClient {
     idleMs;
     maxPending;
     onClose;
-    constructor(spec, requestTimeoutMs, idleMs, maxPending, onClose) {
+    onRequestTimeout;
+    constructor(spec, requestTimeoutMs, idleMs, maxPending, onClose, onRequestTimeout) {
         this.requestTimeoutMs = requestTimeoutMs;
         this.idleMs = idleMs;
         this.maxPending = maxPending;
         this.onClose = onClose;
+        this.onRequestTimeout = onRequestTimeout;
         this.child = spawnCli(spec.command, spec.args, {
             env: browserRuntimeEnv(spec.env), stdio: ["pipe", "pipe", "pipe"], shell: false,
         });
@@ -43,7 +48,7 @@ class BrowserClient {
         this.ready = this.rpc("initialize", {
             protocolVersion: "2024-11-05", capabilities: {},
             clientInfo: { name: "openmausbot-browser", version: "1" },
-        }).then((result) => {
+        }, Math.max(this.requestTimeoutMs, HANDSHAKE_TIMEOUT_MS)).then((result) => {
             if (!result || typeof result !== "object" || !("protocolVersion" in result)) {
                 throw new TransportError("Browser engine returned an invalid handshake.");
             }
@@ -102,7 +107,7 @@ class BrowserClient {
                 void this.stop(new TransportError("Browser connection closed."));
         });
     }
-    rpc(method, params) {
+    rpc(method, params, timeoutMs = this.requestTimeoutMs) {
         if (this.stopped)
             return Promise.reject(new TransportError("Browser connection closed."));
         if (this.pending.size >= this.maxPending)
@@ -114,7 +119,13 @@ class BrowserClient {
         if (this.idleTimer)
             clearTimeout(this.idleTimer);
         return new Promise((resolve, reject) => {
-            const timer = setTimeout(() => { void this.stop(new TransportError("Browser request timed out; restart the browser before taking control.")); }, this.requestTimeoutMs);
+            const timer = setTimeout(() => {
+                // Seal the gate synchronously with the timer, before stop() teardown:
+                // the rejection can surface through the ready handshake, which sits
+                // outside agentRpc's uncertainty classifier.
+                this.onRequestTimeout();
+                void this.stop(new TransportError("Browser request timed out; restart the browser before taking control."));
+            }, timeoutMs);
             timer.unref();
             this.pending.set(id, { resolve, reject, timer });
             try {
@@ -131,11 +142,35 @@ class BrowserClient {
         if (!this.stopped && this.pending.size === 0) {
             // Only the stateless MCP transport expires; saved browser state and the
             // browser daemon itself belong to the profile, not this client.
-            this.idleTimer = setTimeout(() => { void this.stop(); }, this.idleMs);
+            this.idleTimer = setTimeout(() => { void this.stop(undefined, "transport"); }, this.idleMs);
             this.idleTimer.unref();
         }
     }
-    stop(error = new TransportError("Browser connection closed.")) {
+    /** Upstream's MCP loop exits on stdin EOF without closing the daemon.
+     * In particular, Windows taskkill /T would also kill that profile's Chrome,
+     * even when the daemon created a new process group. Idle is not shutdown. */
+    retireTransport() {
+        return new Promise((resolve) => {
+            const finish = () => {
+                clearTimeout(timer);
+                this.child.off("exit", finish);
+                resolve();
+            };
+            const timer = setTimeout(() => {
+                try {
+                    this.child.kill("SIGKILL");
+                }
+                catch { /* transport already exited */ }
+                finish();
+            }, 1_000);
+            this.child.once("exit", finish);
+            if (this.child.exitCode !== null || this.child.signalCode !== null)
+                finish();
+            else
+                this.child.stdin.end();
+        });
+    }
+    stop(error = new TransportError("Browser connection closed."), scope = "tree") {
         if (this.stoppedPromise)
             return this.stoppedPromise;
         this.stopped = true;
@@ -148,7 +183,7 @@ class BrowserClient {
         }
         this.pending.clear();
         this.onClose();
-        this.stoppedPromise = killCliTree(this.child, 1_000).then((stopped) => {
+        this.stoppedPromise = scope === "transport" ? this.retireTransport() : killCliTree(this.child, 1_000).then((stopped) => {
             if (stopped)
                 return;
             try {
@@ -211,6 +246,14 @@ export class BrowserRuntime {
     async agentRpc(session, spec, method, params, beforeDispatch) {
         if (method !== "tools/list" && method !== "tools/call")
             throw new Error("Unsupported browser method.");
+        // tools/list bypasses withAgentAction (a human may hold control), so it
+        // must refuse the closing window itself or its client outlives restart().
+        if (method !== "tools/call" && this.gate(session).closing)
+            throw new Error("The browser is closing. Try again shortly.");
+        // Uncertainty survives client replacement and never self-resolves: refuse
+        // every new browser request until an explicit restart clears it.
+        if (this.gate(session).uncertain)
+            throw new Error("A browser action was interrupted. Restart this browser before continuing.");
         const invoke = async () => {
             const key = JSON.stringify([spec.command, spec.args, Object.entries(spec.env).sort(([a], [b]) => a.localeCompare(b))]);
             let entry = this.clients.get(session);
@@ -220,6 +263,10 @@ export class BrowserRuntime {
                 const client = new BrowserClient(spec, this.options.requestTimeoutMs, this.options.idleMs, this.options.maxPending, () => {
                     if (this.clients.get(session)?.client === client)
                         this.clients.delete(session);
+                }, () => {
+                    const gate = this.gate(session);
+                    if (!gate.closing)
+                        gate.uncertain = true;
                 });
                 entry = { key, client };
                 this.clients.set(session, entry);
@@ -242,8 +289,11 @@ export class BrowserRuntime {
             catch (error) {
                 // An MCP timeout cannot prove the independent daemon stopped an
                 // accepted action. Recovery must close the browser, not just its pipe.
-                if (method === "tools/call" && error instanceof TransportError)
-                    this.gate(session).uncertain = true;
+                // A stop from close()/restart() is intentional, not uncertainty.
+                if (method === "tools/call" && error instanceof TransportError && !this.gate(session).closing) {
+                    const gate = this.gate(session);
+                    gate.uncertain = true;
+                }
                 throw error;
             }
         };
@@ -344,6 +394,10 @@ export class BrowserRuntime {
         try {
             await closeBrowser();
             await this.clients.get(session)?.client.stop();
+            // A tools/list admitted before closing set in can register a client
+            // while that stop awaits; registration is synchronous, so one re-check
+            // is deterministic and no stray transport survives to idle expiry.
+            await this.clients.get(session)?.client.stop();
             gate.uncertain = false;
             gate.owner = null;
             gate.releasing = false;
@@ -364,10 +418,11 @@ export class BrowserRuntime {
         const gate = this.gate(session);
         gate.closing = true;
         gate.ready = false;
+        // Clear before the awaited stop: any uncertain latch after this point must win.
+        gate.uncertain = false;
         this.changed(gate);
         await this.clients.get(session)?.client.stop();
         gate.closing = false;
-        gate.uncertain = false;
         this.changed(gate);
         if (!gate.owner && !gate.agents && !gate.humans)
             this.gates.delete(session);

package/dist-server/server/checkpoints.js

@@ -133,7 +133,7 @@ function disable(botId, message) {
 let gitProbe = null;
 function gitAvailable() {
     gitProbe ??= new Promise((resolveProbe) => {
-        execFile("git", ["--version"], { windowsHide: true }, (err) => resolveProbe(!err));
+        execFile("git", ["--version"], { windowsHide: true, timeout: 5_000 }, (err) => resolveProbe(!err));
     });
     return gitProbe;
 }
@@ -149,7 +149,7 @@ export function refusalReason(cwd) {
     let dir;
     try {
         stat = statSync(requested);
-        dir = realpathSync(requested);
+        dir = realpathSync.native(requested);
     }
     catch {
         return "the working folder does not exist";
@@ -158,16 +158,20 @@ export function refusalReason(cwd) {
         return "the working folder is not a folder";
     // Compare canonical paths too: otherwise /tmp/home-link -> $HOME bypasses
     // the refusal while git still follows the symlink into the protected tree.
+    // The native realpath also settles Windows' spellings of one folder —
+    // c:\users\me, C:\Users\me\DOCUME~1 — and names compare case-insensitively
+    // there, as turn-resources.ts does for workspace claims.
+    const same = (a, b) => process.platform === "win32" ? a.toLowerCase() === b.toLowerCase() : a === b;
     if (dir === parse(dir).root)
         return "checkpoints are not taken at the filesystem root";
     const requestedHome = resolve(homedir());
-    const home = existsSync(requestedHome) ? realpathSync(requestedHome) : requestedHome;
-    if (requested === requestedHome || dir === home)
+    const home = existsSync(requestedHome) ? realpathSync.native(requestedHome) : requestedHome;
+    if (same(requested, requestedHome) || same(dir, home))
         return "checkpoints are not taken in the home folder";
     for (const name of ["Desktop", "Documents", "Downloads"]) {
         const requestedProtected = join(requestedHome, name);
-        const protectedDir = existsSync(requestedProtected) ? realpathSync(requestedProtected) : requestedProtected;
-        if (requested === requestedProtected || dir === protectedDir) {
+        const protectedDir = existsSync(requestedProtected) ? realpathSync.native(requestedProtected) : requestedProtected;
+        if (same(requested, requestedProtected) || same(dir, protectedDir)) {
             return `checkpoints are not taken in the ${name} folder`;
         }
     }
@@ -201,9 +205,10 @@ function gitEnv(shadow, cwd) {
  * "." pathspec in add/restore resolves relative to it. A hung git (index
  * lock, dead network filesystem) would otherwise jam the per-repo queue for
  * the whole session, so every call carries a hard timeout. */
-function runGit(args, cwd, env) {
+function runGit(args, cwd, env, signal) {
     return new Promise((resolvePromise, rejectPromise) => {
-        execFile("git", args, { cwd, env, windowsHide: true, encoding: "utf8", timeout: 120_000, maxBuffer: 16 * 1024 * 1024 }, (err, stdout, stderr) => {
+        signal?.throwIfAborted();
+        execFile("git", args, { cwd, env, signal, windowsHide: true, encoding: "utf8", timeout: 120_000, maxBuffer: 16 * 1024 * 1024 }, (err, stdout, stderr) => {
             if (err)
                 rejectPromise(new Error(`git ${args[0]}: ${(stderr || err.message).trim().slice(0, 400)}`));
             else
@@ -215,9 +220,10 @@ function runGit(args, cwd, env) {
  * instead of `status --porcelain` emptiness on purpose — a nested repo with
  * a dirty work tree shows up in status forever while staging nothing, which
  * would either commit empty churn every turn or fail the commit outright. */
-function hasStagedChanges(cwd, env) {
+function hasStagedChanges(cwd, env, signal) {
     return new Promise((resolvePromise, rejectPromise) => {
-        execFile("git", ["diff", "--cached", "--quiet", "--ignore-submodules=dirty"], { cwd, env, windowsHide: true, encoding: "utf8", timeout: 120_000, maxBuffer: 16 * 1024 * 1024 }, (err, _stdout, stderr) => {
+        signal?.throwIfAborted();
+        execFile("git", ["diff", "--cached", "--quiet", "--ignore-submodules=dirty"], { cwd, env, signal, windowsHide: true, encoding: "utf8", timeout: 120_000, maxBuffer: 16 * 1024 * 1024 }, (err, _stdout, stderr) => {
             if (err === null)
                 resolvePromise(false);
             else if (err.code === 1)
@@ -244,46 +250,49 @@ function serialize(key, fn) {
  * always resolves — it is filtered from listings and refused as a restore
  * target, because "restore to empty" on a user's own project folder would
  * delete their files. */
-async function ensureShadow(cwd, env, shadow) {
+async function ensureShadow(cwd, env, shadow, signal) {
+    signal?.throwIfAborted();
     mkdirSync(shadow, { recursive: true, mode: 0o700 });
     writeFileSync(join(shadow, "gitconfig"), GITCONFIG, { mode: 0o600 });
     writeFileSync(join(shadow, "gitconfig_empty"), "", { mode: 0o600 });
     if (!existsSync(join(shadow, ".git", "HEAD"))) {
         // --template= keeps the user's init.templateDir hooks/config out
-        await runGit(["init", "--initial-branch=main", "--template="], cwd, env);
+        await runGit(["init", "--initial-branch=main", "--template="], cwd, env, signal);
     }
     mkdirSync(join(shadow, ".git", "info"), { recursive: true });
     writeFileSync(join(shadow, ".git", "info", "exclude"), EXCLUDES);
     try {
-        await runGit(["rev-parse", "--verify", "HEAD"], cwd, env);
+        await runGit(["rev-parse", "--verify", "HEAD"], cwd, env, signal);
     }
     catch {
         // brand-new repo (or a crash between init and first commit)
-        await runGit(["commit", "--no-verify", "--allow-empty", "-m", "checkpoint base"], cwd, env);
+        await runGit(["commit", "--no-verify", "--allow-empty", "-m", "checkpoint base"], cwd, env, signal);
     }
 }
 /** Stage everything and commit if anything actually changed. `complete`
  * records whether every path was indexable: ordinary snapshots may keep the
  * useful subset, but restore must not delete files its safety point missed. */
-async function commitAll(cwd, env, label) {
+async function commitAll(cwd, env, label, signal) {
     // --ignore-errors skips files git cannot index (unreadable, FIFOs) instead
     // of aborting — but still exits 1 when it skipped an unreadable file, so
     // the exit code is retained even though a partial snapshot remains useful.
     // Restore treats an incomplete safety point as a hard stop before touching
     // the work tree.
     let complete = true;
-    await runGit(["add", "-A", "--ignore-errors", "."], cwd, env).catch(() => {
+    await runGit(["add", "-A", "--ignore-errors", "."], cwd, env, signal).catch(() => {
         complete = false;
     });
-    if (await hasStagedChanges(cwd, env)) {
-        await runGit(["commit", "--no-verify", "-m", label], cwd, env);
+    if (await hasStagedChanges(cwd, env, signal)) {
+        await runGit(["commit", "--no-verify", "-m", label], cwd, env, signal);
     }
-    return { hash: (await runGit(["rev-parse", "HEAD"], cwd, env)).trim(), complete };
+    return { hash: (await runGit(["rev-parse", "HEAD"], cwd, env, signal)).trim(), complete };
 }
 /** Snapshot the folder. Returns the checkpoint hash, or null when the
  * feature is off for this bot, git is missing, or the folder is refused.
  * Never throws — this is called fire-and-forget on the turn path. */
-export async function snapshot(botId, cwd, label) {
+export async function snapshot(botId, cwd, label, signal) {
+    if (signal?.aborted)
+        return null;
     if (disabledBots.has(botId))
         return null;
     if (!(await gitAvailable()))
@@ -295,12 +304,51 @@ export async function snapshot(botId, cwd, label) {
         const shadow = shadowDir(botId, worktree);
         return await serialize(shadow, async () => {
             const env = gitEnv(shadow, worktree);
-            await ensureShadow(worktree, env, shadow);
-            return (await commitAll(worktree, env, label)).hash;
+            await ensureShadow(worktree, env, shadow, signal);
+            return (await commitAll(worktree, env, label, signal)).hash;
         });
     }
     catch (e) {
-        disable(botId, e instanceof Error ? e.message : String(e));
+        if (!signal?.aborted)
+            disable(botId, e instanceof Error ? e.message : String(e));
+        return null;
+    }
+}
+/** Paths that differ between two checkpoints of the same bot+folder, from
+ * `git diff --name-status` against the shadow repo. Null when the hashes
+ * are equal, the folder is refused or checkpoints are off, or git fails —
+ * the digest then simply omits its file list. Never throws (turn path). */
+export async function diffStat(botId, cwd, fromHash, toHash, signal) {
+    if (signal?.aborted)
+        return null;
+    if (fromHash === toHash)
+        return null;
+    if (disabledBots.has(botId))
+        return null;
+    if (!(await gitAvailable()))
+        return null;
+    if (refusalReason(cwd) !== null)
+        return null;
+    try {
+        const worktree = realpathSync(resolve(cwd));
+        const shadow = shadowDir(botId, worktree);
+        const env = gitEnv(shadow, worktree);
+        const out = await serialize(shadow, () => runGit(["diff", "--name-status", "--no-renames", "-z", fromHash, toHash], worktree, env, signal));
+        const diff = { changed: [], added: [], deleted: [] };
+        const fields = out.split("\0").filter((field) => field.length > 0);
+        for (let i = 0; i + 1 < fields.length; i += 2) {
+            const status = fields[i];
+            const path = fields[i + 1];
+            if (status.startsWith("A"))
+                diff.added.push(path);
+            else if (status.startsWith("D"))
+                diff.deleted.push(path);
+            else
+                diff.changed.push(path);
+        }
+        return diff;
+    }
+    catch {
         return null;
     }
 }