@nanhara/hara 0.122.2 → 0.122.4

package/dist/tools/builtin.js

@@ -4,7 +4,7 @@ import { resolve, isAbsolute } from "node:path";
 import { stdout as procOut } from "node:process";
 import { registerTool } from "./registry.js";
 import { runShell } from "../sandbox.js";
-import { nearestPaths } from "../fs-walk.js";
+import { nearestPathsAsync } from "../fs-walk.js";
 import { emitDiff } from "../diff.js";
 import { recordEdit } from "../undo.js";
 import { atomicWriteText, bindAtomicWritePath } from "../fs-write.js";
@@ -140,7 +140,7 @@ registerTool({
         catch (e) {
             if (e instanceof BinaryFileError)
                 return `Error: cannot read ${input.path}: file appears binary; use an image/media-specific tool or inspect it with \`file\`.`;
-            const near = nearestPaths(ctx.cwd, input.path);
+            const near = await nearestPathsAsync(ctx.cwd, input.path, 3, { timeoutMs: 1_000, signal: ctx.signal });
             return `Error: cannot read ${input.path}: ${e.message ?? e.code}.` + (near.length ? ` Did you mean: ${near.join(", ")}?` : "");
         }
     },
@@ -185,6 +185,7 @@ registerTool({
                 expected: prev,
                 expectedIdentity: prevSnapshot ?? undefined,
                 boundary,
+                signal: ctx.signal,
             });
         }
         catch (error) {
@@ -209,6 +210,7 @@ registerTool({
         required: ["command"],
     },
     kind: "exec",
+    requiresProjectWorkspace: true,
     async run(input, ctx) {
         const protectedReason = sensitiveShellCommandReason(String(input.command ?? ""), ctx.cwd);
         if (protectedReason) {
@@ -259,6 +261,7 @@ registerTool({
                 timeout,
                 maxBuffer: 10 * 1024 * 1024,
                 onData: live,
+                signal: ctx.signal,
             });
             flushLive();
             const combined = (stdout || "") + (stderr ? `\n[stderr]\n${stderr}` : "");

package/dist/tools/codebase.js

@@ -2,51 +2,95 @@
 // repo's code/text (respects .gitignore via listProjectFiles), ranked by how many distinct query words a
 // file contains, returning the densest snippet. Distinct from grep (exact pattern): this finds *related*
 // code from a natural-language query. The interface a semantic (zvec) index slots into later.
-import { readFileSync } from "node:fs";
-import { join } from "node:path";
+import { statSync } from "node:fs";
+import { isAbsolute, join, resolve } from "node:path";
 import { registerTool } from "./registry.js";
-import { listProjectFiles, isProbablyBinary, fileSize } from "../fs-walk.js";
+import { listProjectFilesAsync } from "../fs-walk.js";
 import { findProjectRoot } from "../context/agents-md.js";
 import { loadConfig } from "../config.js";
 import { getEmbedder } from "../search/embed.js";
 import { queryIndex, indexExists } from "../search/semindex.js";
+import { recursiveRootContainsHome, recursiveHomeSearchError } from "../context/workspace-scope.js";
+import { readVerifiedRegularFileSnapshotSync } from "../fs-read.js";
 const MAX_FILE = 200_000; // skip very large files
+const INVENTORY_TIMEOUT_MS = 2_000;
+const LEXICAL_TIMEOUT_MS = 5_000;
 const CODE_RE = /\.(ts|tsx|js|jsx|mjs|cjs|py|go|rs|java|kt|rb|php|c|h|cc|cpp|hpp|cs|swift|scala|sh|bash|sql|md|mdx|json|ya?ml|toml|html|css|scss|less|vue|svelte|astro|tf|proto|graphql|gql|gradle|txt)$/i;
 registerTool({
     name: "codebase_search",
     description: "Find code in THIS project relevant to a natural-language query — ranked by relevance (not exact match). " +
         "Use it to locate similar/related code while working ('where is auth handled?', 'retry logic'); use grep " +
-        "for exact strings/regex. Returns the top files with their most relevant snippet (file:line).",
+        "for exact strings/regex. Returns the top files with their most relevant snippet (file:line). When Hara " +
+        "was started in the home directory, set path to a specific project subdirectory.",
     input_schema: {
         type: "object",
-        properties: { query: { type: "string" }, limit: { type: "number", description: "default 6 (max 20)" } },
+        properties: {
+            query: { type: "string" },
+            limit: { type: "number", description: "default 6 (max 20)" },
+            path: { type: "string", description: "project directory (default: cwd)" },
+        },
         required: ["query"],
     },
     kind: "read",
     async run(input, ctx) {
+        if (ctx.signal?.aborted)
+            throw new Error("codebase_search interrupted by agent run deadline or cancellation");
         const words = [...new Set(String(input.query ?? "").toLowerCase().split(/\s+/).filter((w) => w.length > 1))];
         if (!words.length)
             return "(empty query)";
         const need = Math.min(2, words.length); // require most of the query to actually appear (conceptual overlap)
         const limit = Math.min(Number(input.limit) || 6, 20);
-        const root = findProjectRoot(ctx.cwd);
+        const requestedRoot = typeof input.path === "string" && input.path.trim()
+            ? (isAbsolute(input.path) ? input.path : resolve(ctx.cwd, input.path))
+            : ctx.cwd;
+        try {
+            if (!statSync(requestedRoot).isDirectory())
+                return `Error: codebase_search path is not a directory: ${input.path ?? "."}`;
+        }
+        catch {
+            return `Error: no such codebase_search path: ${input.path ?? "."}`;
+        }
+        if (recursiveRootContainsHome(requestedRoot))
+            return recursiveHomeSearchError("codebase_search");
+        const root = findProjectRoot(requestedRoot);
+        if (recursiveRootContainsHome(root))
+            return recursiveHomeSearchError("codebase_search");
         const hits = [];
-        for (const rel of listProjectFiles(root)) {
+        const inventory = await listProjectFilesAsync(root, {
+            maxFiles: 8_000,
+            maxDirectories: 20_000,
+            maxEntries: 100_000,
+            timeoutMs: INVENTORY_TIMEOUT_MS,
+            signal: ctx.signal,
+            yieldEvery: 64,
+        });
+        const lexicalStartedAt = Date.now();
+        let lexicalTimedOut = false;
+        let fileIndex = 0;
+        for (const rel of inventory.files) {
+            if (ctx.signal?.aborted)
+                throw new Error("codebase_search interrupted by agent run deadline or cancellation");
+            if (fileIndex++ > 0 && fileIndex % 32 === 0) {
+                await new Promise((resolveTurn) => setImmediate(resolveTurn));
+                if (ctx.signal?.aborted)
+                    throw new Error("codebase_search interrupted by agent run deadline or cancellation");
+                if (Date.now() - lexicalStartedAt >= LEXICAL_TIMEOUT_MS) {
+                    lexicalTimedOut = true;
+                    break;
+                }
+            }
             if (!CODE_RE.test(rel))
                 continue;
             const abs = join(root, rel);
-            if (fileSize(abs) > MAX_FILE)
-                continue;
-            let buf;
+            let text;
             try {
-                buf = readFileSync(abs);
+                text = readVerifiedRegularFileSnapshotSync(abs, MAX_FILE, { action: "search" }).text;
             }
             catch {
                 continue;
             }
-            if (isProbablyBinary(buf))
+            if (text.includes("\0"))
                 continue;
-            const text = buf.toString("utf8");
             const lower = text.toLowerCase();
             const present = words.filter((w) => lower.includes(w));
             if (present.length < need)
@@ -74,11 +118,11 @@ registerTool({
         const seen = new Set();
         // Tool execution can be dispatched to a registered agent home without changing process.cwd(). Its
         // semantic-search provider/index settings belong to the tool context, not to the launcher directory.
-        const cfg = loadConfig({ cwd: ctx.cwd });
+        const cfg = loadConfig({ cwd: root });
         const embed = getEmbedder(cfg);
-        if (embed && indexExists("repo", ctx.cwd)) {
+        if (embed && indexExists("repo", root)) {
             try {
-                for (const s of await queryIndex("repo", String(input.query), embed, ctx.cwd, limit)) {
+                for (const s of await queryIndex("repo", String(input.query), embed, root, limit, ctx.signal)) {
                     if (s.score < 0.2 || seen.has(s.file))
                         continue;
                     seen.add(s.file);
@@ -86,6 +130,8 @@ registerTool({
                 }
             }
             catch {
+                if (ctx.signal?.aborted)
+                    throw new Error("codebase_search interrupted by agent run deadline or cancellation");
                 /* embedding endpoint down → degrade to lexical */
             }
         }
@@ -97,8 +143,11 @@ registerTool({
             seen.add(h.file);
             out.push(`${h.file}:${h.line}\n${h.snippet}`);
         }
+        const boundedNote = inventory.truncated
+            ? `(project inventory stopped at its ${inventory.reason?.replace("_", " ") ?? "safety limit"})`
+            : lexicalTimedOut ? `(lexical scan stopped at its ${LEXICAL_TIMEOUT_MS}ms safety budget)` : "";
         if (!out.length)
-            return "(no relevant code found)";
-        return out.join("\n\n---\n\n");
+            return boundedNote ? `(no relevant code found)\n${boundedNote}` : "(no relevant code found)";
+        return (boundedNote ? `${boundedNote}\n\n` : "") + out.join("\n\n---\n\n");
     },
 });

package/dist/tools/computer.js

@@ -4,12 +4,13 @@
 // frontmost-window check before any pointer/keyboard action) + dangerous-key blocklist + a once-per-session
 // grant (tool kind "computer" always confirms once, even in full-auto). Screenshots are read via the vision
 // sidecar (ctx.describeImage) so a text main model can still "see" them.
-import { spawnSync } from "node:child_process";
+import { spawn, spawnSync } from "node:child_process";
 import { existsSync, statSync } from "node:fs";
 import { tmpdir } from "node:os";
 import { join } from "node:path";
 import { registerTool } from "./registry.js";
 import { loadConfig } from "../config.js";
+import { terminateSubprocessTree, toolSubprocessEnv } from "../security/subprocess-env.js";
 const RANK = { off: 0, read: 1, click: 2, full: 3 };
 const ACTION_MIN = { screenshot: "read", find: "read", activate: "click", move: "click", click: "click", type: "full", key: "full" };
 // dangerous combos refused even at full tier (quit / close / delete / task-switch-kill).
@@ -46,30 +47,106 @@ function fail(msg) {
     }
     return `Failed: ${msg}  [${consecFails}/${FAIL_LIMIT} before I stop]`;
 }
-function run(cmd, args) {
+/** Doctor runs outside an agent turn and may retain a small bounded synchronous availability probe. */
+function runProbeSync(cmd, args) {
     try {
-        const r = spawnSync(cmd, args, { encoding: "utf8", timeout: 15000 });
+        const r = spawnSync(cmd, args, { encoding: "utf8", timeout: 3_000, env: toolSubprocessEnv() });
         return { ok: r.status === 0, out: ((r.stdout || "") + (r.stderr || "")).trim() };
     }
     catch (e) {
         return { ok: false, out: e?.message || "spawn failed" };
     }
 }
-function has(cmd) {
-    return (process.platform === "win32" ? run("where", [cmd]) : run("which", [cmd])).ok;
+function hasProbeSync(cmd) {
+    return (process.platform === "win32" ? runProbeSync("where", [cmd]) : runProbeSync("which", [cmd])).ok;
 }
-const ps = (script) => run("powershell", ["-NoProfile", "-Command", script]);
+class ComputerInterruptedError extends Error {
+    constructor() {
+        super("computer action interrupted by agent run deadline or cancellation");
+    }
+}
+/** Async, signal-aware command primitive for every agent-driven screen action. It owns a process group so
+ *  Esc/deadline kills descendants as well as the direct launcher, and it rechecks the signal before spawn. */
+async function run(cmd, args, signal, input, timeoutMs = 15_000) {
+    if (signal?.aborted)
+        throw new ComputerInterruptedError();
+    return await new Promise((resolve, reject) => {
+        const processGroup = process.platform !== "win32";
+        let child;
+        try {
+            child = spawn(cmd, args, { detached: processGroup, env: toolSubprocessEnv() });
+        }
+        catch (error) {
+            resolve({ ok: false, out: error instanceof Error ? error.message : "spawn failed" });
+            return;
+        }
+        let stdout = "";
+        let stderr = "";
+        let done = false;
+        let timedOut = false;
+        let aborted = false;
+        let fallback;
+        const append = (current, chunk) => current.length >= 256 * 1024 ? current : current + chunk.toString().slice(0, 256 * 1024 - current.length);
+        const settle = (code, launchError) => {
+            if (done)
+                return;
+            done = true;
+            clearTimeout(timer);
+            if (fallback)
+                clearTimeout(fallback);
+            signal?.removeEventListener("abort", abortRun);
+            const out = (stdout + stderr).trim();
+            if (aborted)
+                reject(new ComputerInterruptedError());
+            else if (launchError)
+                resolve({ ok: false, out: launchError.message });
+            else if (timedOut)
+                resolve({ ok: false, out: `timed out after ${timeoutMs}ms${out ? `: ${out}` : ""}` });
+            else
+                resolve({ ok: code === 0, out });
+        };
+        const stop = (fromAbort) => {
+            if (done || aborted || timedOut)
+                return;
+            aborted = fromAbort;
+            timedOut = !fromAbort;
+            terminateSubprocessTree(child, { force: true, processGroup });
+            // A daemon can escape while retaining pipes. Destroy our ends so the API still settles promptly.
+            fallback = setTimeout(() => {
+                child.stdout?.destroy();
+                child.stderr?.destroy();
+                settle(null);
+            }, 750);
+        };
+        const abortRun = () => stop(true);
+        const timer = setTimeout(() => stop(false), timeoutMs);
+        signal?.addEventListener("abort", abortRun, { once: true });
+        if (signal?.aborted) {
+            abortRun();
+        }
+        child.stdout?.on("data", (chunk) => { if (!done)
+            stdout = append(stdout, chunk); });
+        child.stderr?.on("data", (chunk) => { if (!done)
+            stderr = append(stderr, chunk); });
+        child.stdin?.on("error", () => { });
+        child.stdin?.end(input);
+        child.once("error", (error) => settle(null, error));
+        child.once("close", (code) => settle(code));
+    });
+}
+const has = async (cmd, signal) => (await (process.platform === "win32" ? run("where", [cmd], signal) : run("which", [cmd], signal))).ok;
+const ps = (script, signal) => run("powershell", ["-NoProfile", "-Command", script], signal);
 /** Put text on the OS clipboard (so `type` can paste it — IME-safe + Unicode-safe, unlike keystroke injection). */
-function setClipboard(text) {
+async function setClipboard(text, signal) {
     try {
         if (process.platform === "darwin")
-            return spawnSync("pbcopy", [], { input: text, timeout: 5000 }).status === 0;
+            return (await run("pbcopy", [], signal, text, 5_000)).ok;
         if (process.platform === "win32")
-            return spawnSync("clip", [], { input: text, timeout: 5000 }).status === 0;
-        if (has("wl-copy"))
-            return spawnSync("wl-copy", [], { input: text, timeout: 5000 }).status === 0;
-        if (has("xclip"))
-            return spawnSync("xclip", ["-selection", "clipboard"], { input: text, timeout: 5000 }).status === 0;
+            return (await run("clip", [], signal, text, 5_000)).ok;
+        if (await has("wl-copy", signal))
+            return (await run("wl-copy", [], signal, text, 5_000)).ok;
+        if (await has("xclip", signal))
+            return (await run("xclip", ["-selection", "clipboard"], signal, text, 5_000)).ok;
     }
     catch {
         /* fall through */
@@ -81,25 +158,25 @@ function tmpShot() {
     seq += 1;
     return join(tmpdir(), `hara-screen-${process.pid}-${Date.now()}-${seq}.png`);
 }
-function screenshot() {
+async function screenshot(signal) {
     const out = tmpShot();
     if (process.platform === "darwin") {
-        if (!run("screencapture", ["-x", out]).ok)
+        if (!(await run("screencapture", ["-x", out], signal)).ok)
             return { error: "screencapture failed (grant Screen Recording permission)" };
     }
     else if (process.platform === "linux") {
-        if (has("scrot"))
-            run("scrot", ["-o", out]);
-        else if (has("import"))
-            run("import", ["-window", "root", out]);
-        else if (has("grim"))
-            run("grim", [out]);
+        if (await has("scrot", signal))
+            await run("scrot", ["-o", out], signal);
+        else if (await has("import", signal))
+            await run("import", ["-window", "root", out], signal);
+        else if (await has("grim", signal))
+            await run("grim", [out], signal);
         else
             return { error: "no screenshot tool — install scrot / imagemagick / grim" };
     }
     else if (process.platform === "win32") {
         const script = `Add-Type -AssemblyName System.Windows.Forms,System.Drawing; $b=[System.Windows.Forms.Screen]::PrimaryScreen.Bounds; $bmp=New-Object System.Drawing.Bitmap($b.Width,$b.Height); $g=[System.Drawing.Graphics]::FromImage($bmp); $g.CopyFromScreen($b.Location,[System.Drawing.Point]::Empty,$b.Size); $bmp.Save(${JSON.stringify(out)})`;
-        if (!ps(script).ok)
+        if (!(await ps(script, signal)).ok)
             return { error: "PowerShell screenshot failed" };
     }
     else {
@@ -115,39 +192,41 @@ function screenshot() {
     return { path: out };
 }
 /** Bring an app to the foreground so screenshots/clicks land on IT, not the terminal hara runs in. */
-function activateApp(app) {
+async function activateApp(app, signal) {
     if (process.platform === "darwin") {
         // `open -a` reliably launches+foregrounds; `osascript … activate` often leaves another window on top.
-        const r = run("open", ["-a", app]);
+        const r = await run("open", ["-a", app], signal);
         return { ok: r.ok, msg: r.ok ? `activated ${app}` : r.out || `couldn't activate ${app}` };
     }
     if (process.platform === "win32") {
-        const r = ps(`(New-Object -ComObject WScript.Shell).AppActivate(${JSON.stringify(app)})`);
+        const r = await ps(`(New-Object -ComObject WScript.Shell).AppActivate(${JSON.stringify(app)})`, signal);
         return { ok: r.ok, msg: r.ok ? `activated ${app}` : r.out || `couldn't activate ${app}` };
     }
     if (process.platform === "linux") {
-        const r = has("wmctrl") ? run("wmctrl", ["-a", app]) : run("xdotool", ["search", "--name", app, "windowactivate"]);
+        const r = await (await has("wmctrl", signal)
+            ? run("wmctrl", ["-a", app], signal)
+            : run("xdotool", ["search", "--name", app, "windowactivate"], signal));
         return { ok: r.ok, msg: r.ok ? `activated ${app}` : r.out || `couldn't activate ${app} (need wmctrl/xdotool)` };
     }
     return { ok: false, msg: `activate unsupported on ${process.platform}` };
 }
 /** Logical screen size in the coordinate space the click backends use (points on mac, pixels on win/linux).
  *  Grounding returns 0..1 fractions, so click = fraction × this. null if undetectable. */
-function screenSize() {
+async function screenSize(signal) {
     try {
         if (process.platform === "darwin") {
-            const r = run("osascript", ["-e", 'tell application "Finder" to get bounds of window of desktop']);
+            const r = await run("osascript", ["-e", 'tell application "Finder" to get bounds of window of desktop'], signal);
             const n = r.out.match(/-?\d+/g);
             if (n && n.length >= 4)
                 return { w: Number(n[2]), h: Number(n[3]) };
         }
         else if (process.platform === "linux") {
-            const [w, h] = run("xdotool", ["getdisplaygeometry"]).out.trim().split(/\s+/).map(Number);
+            const [w, h] = (await run("xdotool", ["getdisplaygeometry"], signal)).out.trim().split(/\s+/).map(Number);
             if (w && h)
                 return { w, h };
         }
         else if (process.platform === "win32") {
-            const [w, h] = ps('Add-Type -AssemblyName System.Windows.Forms; $b=[System.Windows.Forms.Screen]::PrimaryScreen.Bounds; "$($b.Width) $($b.Height)"').out.trim().split(/\s+/).map(Number);
+            const [w, h] = (await ps('Add-Type -AssemblyName System.Windows.Forms; $b=[System.Windows.Forms.Screen]::PrimaryScreen.Bounds; "$($b.Width) $($b.Height)"', signal)).out.trim().split(/\s+/).map(Number);
             if (w && h)
                 return { w, h };
         }
@@ -158,25 +237,25 @@ function screenSize() {
     return null;
 }
 /** Name of the frontmost application/window (for the allowlist check). "" if undetectable. */
-function frontmostApp() {
+async function frontmostApp(signal) {
     if (process.platform === "darwin") {
-        const r = run("osascript", ["-e", 'tell application "System Events" to get name of first application process whose frontmost is true']);
+        const r = await run("osascript", ["-e", 'tell application "System Events" to get name of first application process whose frontmost is true'], signal);
         return r.ok ? r.out : "";
     }
     if (process.platform === "linux") {
-        const r = run("xdotool", ["getactivewindow", "getwindowclassname"]);
+        const r = await run("xdotool", ["getactivewindow", "getwindowclassname"], signal);
         return r.ok ? r.out : "";
     }
     if (process.platform === "win32") {
         const script = `Add-Type @"
 using System;using System.Runtime.InteropServices;public class Hw{[DllImport("user32.dll")]public static extern IntPtr GetForegroundWindow();[DllImport("user32.dll")]public static extern int GetWindowThreadProcessId(IntPtr h,out int p);}
 "@; $p=0;[void][Hw]::GetWindowThreadProcessId([Hw]::GetForegroundWindow(),[ref]$p);(Get-Process -Id $p).ProcessName`;
-        const r = ps(script);
+        const r = await ps(script, signal);
         return r.ok ? r.out : "";
     }
     return "";
 }
-function pointerOrKeyboard(action, input) {
+async function pointerOrKeyboard(action, input, signal) {
     const x = Math.round(Number(input.x));
     const y = Math.round(Number(input.y));
     const mac = process.platform === "darwin";
@@ -186,24 +265,24 @@ function pointerOrKeyboard(action, input) {
         if (!Number.isFinite(x) || !Number.isFinite(y))
             return { ok: false, msg: `${action} needs x,y` };
         if (mac) {
-            if (!has("cliclick"))
+            if (!(await has("cliclick", signal)))
                 return { ok: false, msg: "cliclick not found — install with `brew install cliclick`" };
-            const r = run("cliclick", [`${action === "click" ? "c" : "m"}:${x},${y}`]);
+            const r = await run("cliclick", [`${action === "click" ? "c" : "m"}:${x},${y}`], signal);
             return { ok: r.ok, msg: r.ok ? `${action} at ${x},${y}` : r.out };
         }
         if (lin) {
-            if (!has("xdotool"))
+            if (!(await has("xdotool", signal)))
                 return { ok: false, msg: "xdotool not found" };
-            const r = run("xdotool", action === "click" ? ["mousemove", `${x}`, `${y}`, "click", "1"] : ["mousemove", `${x}`, `${y}`]);
+            const r = await run("xdotool", action === "click" ? ["mousemove", `${x}`, `${y}`, "click", "1"] : ["mousemove", `${x}`, `${y}`], signal);
             return { ok: r.ok, msg: r.ok ? `${action} at ${x},${y}` : r.out };
         }
         if (win) {
             const move = `Add-Type -AssemblyName System.Windows.Forms;[System.Windows.Forms.Cursor]::Position=New-Object System.Drawing.Point(${x},${y})`;
-            const m1 = ps(`Add-Type -AssemblyName System.Drawing;${move}`);
+            const m1 = await ps(`Add-Type -AssemblyName System.Drawing;${move}`, signal);
             if (action === "click" && m1.ok) {
-                ps(`Add-Type @"
+                await ps(`Add-Type @"
 using System;using System.Runtime.InteropServices;public class Ms{[DllImport("user32.dll")]public static extern void mouse_event(int f,int x,int y,int d,int e);}
-"@; [Ms]::mouse_event(0x2,0,0,0,0);[Ms]::mouse_event(0x4,0,0,0,0)`);
+"@; [Ms]::mouse_event(0x2,0,0,0,0);[Ms]::mouse_event(0x4,0,0,0,0)`, signal);
             }
             return { ok: m1.ok, msg: m1.ok ? `${action} at ${x},${y}` : m1.out };
         }
@@ -214,38 +293,38 @@ using System;using System.Runtime.InteropServices;public class Ms{[DllImport("us
             return { ok: false, msg: "type needs text" };
         // IME-safe path: set the clipboard and paste. Keystroke injection (below) is intercepted/garbled by a
         // CJK input method and can't enter Chinese/emoji reliably; pasting is immune and Unicode-safe.
-        if (setClipboard(text)) {
-            if (mac && has("cliclick")) {
-                const r = run("cliclick", ["kd:cmd", "t:v", "ku:cmd"]); // Cmd+V
+        if (await setClipboard(text, signal)) {
+            if (mac && await has("cliclick", signal)) {
+                const r = await run("cliclick", ["kd:cmd", "t:v", "ku:cmd"], signal); // Cmd+V
                 if (r.ok)
                     return { ok: true, msg: `pasted ${text.length} chars` };
             }
-            else if (lin && has("xdotool")) {
-                const r = run("xdotool", ["key", "ctrl+v"]);
+            else if (lin && await has("xdotool", signal)) {
+                const r = await run("xdotool", ["key", "ctrl+v"], signal);
                 if (r.ok)
                     return { ok: true, msg: `pasted ${text.length} chars` };
             }
             else if (win) {
-                const r = ps("Add-Type -AssemblyName System.Windows.Forms;[System.Windows.Forms.SendKeys]::SendWait('^v')");
+                const r = await ps("Add-Type -AssemblyName System.Windows.Forms;[System.Windows.Forms.SendKeys]::SendWait('^v')", signal);
                 if (r.ok)
                     return { ok: true, msg: `pasted ${text.length} chars` };
             }
         }
         // Fallback: keystroke injection (fine for ASCII when no IME is active).
         if (mac) {
-            if (!has("cliclick"))
+            if (!(await has("cliclick", signal)))
                 return { ok: false, msg: "cliclick not found — install with `brew install cliclick`" };
-            const r = run("cliclick", [`t:${text}`]);
+            const r = await run("cliclick", [`t:${text}`], signal);
             return { ok: r.ok, msg: r.ok ? `typed ${text.length} chars (keystroke)` : r.out };
         }
         if (lin) {
-            if (!has("xdotool"))
+            if (!(await has("xdotool", signal)))
                 return { ok: false, msg: "xdotool not found" };
-            const r = run("xdotool", ["type", "--clearmodifiers", text]);
+            const r = await run("xdotool", ["type", "--clearmodifiers", text], signal);
             return { ok: r.ok, msg: r.ok ? `typed ${text.length} chars (keystroke)` : r.out };
         }
         if (win) {
-            const r = ps(`Add-Type -AssemblyName System.Windows.Forms;[System.Windows.Forms.SendKeys]::SendWait(${JSON.stringify(text)})`);
+            const r = await ps(`Add-Type -AssemblyName System.Windows.Forms;[System.Windows.Forms.SendKeys]::SendWait(${JSON.stringify(text)})`, signal);
             return { ok: r.ok, msg: r.ok ? `typed ${text.length} chars (keystroke)` : r.out };
         }
     }
@@ -256,19 +335,19 @@ using System;using System.Runtime.InteropServices;public class Ms{[DllImport("us
         if (keyIsBlocked(keys))
             return { ok: false, msg: `refused dangerous key combo: ${keys}` };
         if (mac) {
-            if (!has("cliclick"))
+            if (!(await has("cliclick", signal)))
                 return { ok: false, msg: "cliclick not found — install with `brew install cliclick`" };
-            const r = run("cliclick", [`kp:${keys}`]);
+            const r = await run("cliclick", [`kp:${keys}`], signal);
             return { ok: r.ok, msg: r.ok ? `pressed ${keys}` : r.out };
         }
         if (lin) {
-            if (!has("xdotool"))
+            if (!(await has("xdotool", signal)))
                 return { ok: false, msg: "xdotool not found" };
-            const r = run("xdotool", ["key", keys]);
+            const r = await run("xdotool", ["key", keys], signal);
             return { ok: r.ok, msg: r.ok ? `pressed ${keys}` : r.out };
         }
         if (win) {
-            const r = ps(`Add-Type -AssemblyName System.Windows.Forms;[System.Windows.Forms.SendKeys]::SendWait(${JSON.stringify(keys)})`);
+            const r = await ps(`Add-Type -AssemblyName System.Windows.Forms;[System.Windows.Forms.SendKeys]::SendWait(${JSON.stringify(keys)})`, signal);
             return { ok: r.ok, msg: r.ok ? `pressed ${keys}` : r.out };
         }
     }
@@ -277,9 +356,9 @@ using System;using System.Runtime.InteropServices;public class Ms{[DllImport("us
 /** Per-OS backend availability — for `hara doctor`. */
 export function computerBackends() {
     if (process.platform === "darwin")
-        return `screencapture ✓ · cliclick ${has("cliclick") ? "✓" : "✗ (brew install cliclick)"}`;
+        return `screencapture ✓ · cliclick ${hasProbeSync("cliclick") ? "✓" : "✗ (brew install cliclick)"}`;
     if (process.platform === "linux")
-        return `scrot ${has("scrot") ? "✓" : "✗"} · xdotool ${has("xdotool") ? "✓" : "✗"}`;
+        return `scrot ${hasProbeSync("scrot") ? "✓" : "✗"} · xdotool ${hasProbeSync("xdotool") ? "✓" : "✗"}`;
     if (process.platform === "win32")
         return "PowerShell (built-in)";
     return `unsupported (${process.platform})`;
@@ -313,6 +392,8 @@ if (!process.env.HARA_GATEWAY || process.env.HARA_GATEWAY_COMPUTER === "1") {
         },
         kind: "computer",
         async run(input, ctx) {
+            if (ctx.signal?.aborted)
+                throw new ComputerInterruptedError();
             const cfg = loadConfig();
             const tier = cfg.computerUse;
             if (tier === "off")
@@ -327,25 +408,25 @@ if (!process.env.HARA_GATEWAY || process.env.HARA_GATEWAY_COMPUTER === "1") {
                     return "activate needs an `app` name (e.g. 'WeChat').";
                 if (!cfg.computerApps.some((a) => a.toLowerCase() === app.toLowerCase()))
                     return `Refused: "${app}" isn't in your allowlist (${cfg.computerApps.join(", ") || "empty"}). Add it: \`hara config set computerApps "${app}"\`.`;
-                const r = activateApp(app);
+                const r = await activateApp(app, ctx.signal);
                 return r.ok ? ok(`✓ ${r.msg} — now screenshot/find/click to act on it`) : fail(r.msg);
             }
             if (action !== "screenshot" && action !== "find") {
                 // per-app allowlist: only act when an allowlisted app is frontmost (the key guard against wrong-window clicks)
                 if (!cfg.computerApps.length)
                     return "No apps allowlisted — set `hara config set computerApps \"App Name, …\"` before clicking/typing.";
-                const app = frontmostApp();
+                const app = await frontmostApp(ctx.signal);
                 const allowed = cfg.computerApps.some((a) => a.toLowerCase() === app.toLowerCase());
                 if (!allowed)
                     return `Refused: frontmost app "${app || "unknown"}" isn't in your allowlist (${cfg.computerApps.join(", ")}). Switch to an allowed app or update computerApps.`;
             }
             if (action === "screenshot") {
-                const s = screenshot();
+                const s = await screenshot(ctx.signal);
                 if (s.error)
                     return fail(`screenshot — ${s.error}`);
                 if (ctx.describeImage) {
                     try {
-                        const desc = await ctx.describeImage(s.path, input.focus ? String(input.focus) : undefined);
+                        const desc = await ctx.describeImage(s.path, input.focus ? String(input.focus) : undefined, ctx.signal);
                         if (desc)
                             return ok(`Screenshot (read via vision):\n${desc}`);
                     }
@@ -364,13 +445,13 @@ if (!process.env.HARA_GATEWAY || process.env.HARA_GATEWAY_COMPUTER === "1") {
                     return action === "find" ? "find needs a `target` (what to locate)." : "click/move needs `x,y` or a `target`.";
                 if (!ctx.locate)
                     return "Grounding needs a vision model that can see images — set one: `hara config set visionModel <model>`.";
-                const s = screenshot();
+                const s = await screenshot(ctx.signal);
                 if (s.error)
                     return fail(`screenshot — ${s.error}`);
-                const loc = await ctx.locate(s.path, target);
+                const loc = await ctx.locate(s.path, target, ctx.signal);
                 if (!loc)
                     return fail(`couldn't locate "${target}" on screen — try a screenshot first, or rephrase the target`);
-                const size = screenSize();
+                const size = await screenSize(ctx.signal);
                 if (!size)
                     return fail(`located "${target}" but couldn't read the screen size to convert coordinates`);
                 const gx = Math.round(loc.x * size.w);
@@ -380,7 +461,7 @@ if (!process.env.HARA_GATEWAY || process.env.HARA_GATEWAY_COMPUTER === "1") {
                 input.x = gx;
                 input.y = gy;
             }
-            const r = pointerOrKeyboard(action, input);
+            const r = await pointerOrKeyboard(action, input, ctx.signal);
             return r.ok ? ok(`✓ ${r.msg}${needsLocate ? ` (located "${input.target}")` : ""}`) : fail(r.msg);
         },
     });