@instaclaw/dispatch 0.6.2 → 0.7.0

package/dist/connection.js

@@ -15,9 +15,69 @@ export function connect(opts) {
     const url = buildAuthUrl(opts.vmAddress, opts.port, opts.gatewayToken);
     console.log(`  Connecting to ${opts.vmAddress}:${opts.port}...`);
     ws = new WebSocket(url, {
-        rejectUnauthorized: false, // Accept self-signed certs (TOFU model)
+        // rejectUnauthorized stays false ON PURPOSE and is NOT the defect.
+        //
+        // The VM generates its own certificate with CN=dispatch-server (see
+        // dispatch-server.js), so ordinary hostname verification could never pass:
+        // we connect by IP address, and no CA has ever vouched for that name. Turning
+        // this to true without shipping something else in its place would simply break
+        // every connection.
+        //
+        // The real defect was that the TOFU half was designed and never built:
+        // certFingerprint and onCertFingerprint were declared in this file, threaded
+        // through from index.ts:180 and :206, and then never computed, never invoked,
+        // and never compared. So the transport accepted ANY certificate, forever,
+        // including an attacker's. That is what the block below closes.
+        rejectUnauthorized: false,
         handshakeTimeout: 10000,
     });
+    // ── Trust On First Use, the half that was missing ──────────────────────────
+    // On the first connection we record the peer's certificate fingerprint. On every
+    // later connection we compare. A changed fingerprint means the machine answering
+    // on this address is not the machine we paired with, which is exactly the
+    // dangling-DNS and address-reassignment case this fleet has already been shown to
+    // produce.
+    //
+    // SHIPS UNARMED: mismatch WARNS by default and only refuses when
+    // INSTACLAW_DISPATCH_PIN_ENFORCE is set. Enforcement is a separate word, because
+    // turning it on before every paired client has recorded a fingerprint would lock
+    // people out of their own machines.
+    ws.on("upgrade", (res) => {
+        try {
+            const sock = res.socket;
+            if (typeof sock.getPeerCertificate !== "function")
+                return;
+            const peer = sock.getPeerCertificate();
+            const fp = peer && peer.fingerprint256;
+            if (!fp)
+                return;
+            if (!opts.certFingerprint) {
+                // First use: adopt and persist via the callback index.ts already supplies.
+                opts.onCertFingerprint?.(fp);
+                return;
+            }
+            if (opts.certFingerprint === fp)
+                return;
+            const msg = `certificate fingerprint CHANGED for ${opts.vmAddress}.\n` +
+                `  expected ${opts.certFingerprint}\n` +
+                `  received ${fp}\n` +
+                `  The machine answering on this address is not the one you paired with.`;
+            if (process.env.INSTACLAW_DISPATCH_PIN_ENFORCE) {
+                console.error(`  REFUSING: ${msg}`);
+                try {
+                    ws?.close(1008, "cert fingerprint mismatch");
+                }
+                catch { /* closing anyway */ }
+            }
+            else {
+                console.warn(`  WARNING: ${msg}\n  Set INSTACLAW_DISPATCH_PIN_ENFORCE=1 to refuse instead of warn.`);
+            }
+        }
+        catch {
+            // Never let the pin check break a working connection. It is a check, not a
+            // dependency.
+        }
+    });
     ws.on("open", () => {
         reconnectDelay = 1000; // Reset backoff
         console.log(`  Connected to agent on ${opts.vmAddress}`);

package/dist/executor.d.ts

@@ -1,4 +1,6 @@
 import type { DispatchCommand } from "./types.js";
+/** Call once at start, before any command. Throws (the client must not start) on a start refusal. */
+export declare function initScope(): Promise<boolean>;
 export interface ExecutionResult {
     success: boolean;
     data?: Record<string, unknown>;

package/dist/executor.js

@@ -4,6 +4,30 @@
  */
 import { execSync, exec as execCb } from "child_process";
 import { captureScreenshot } from "./screenshot.js";
+import { commandNamesOwnPage, OWN_PAGE_REFUSAL } from "./own-pages.js";
+import { Scope, loadScopeConfig } from "./scope.js";
+// PASS 43 SCOPED MODE (scope.ts, PRD 43.11): null unless INSTACLAW_DISPATCH_SCOPE_FILE is set.
+let scope = null;
+async function liveWindows() { return (await (await getUC()).windowList()); }
+/** Call once at start, before any command. Throws (the client must not start) on a start refusal. */
+export async function initScope() {
+    const cfg = loadScopeConfig();
+    if (!cfg)
+        return false;
+    const base = await liveWindows();
+    const why = Scope.startRefusal(cfg, base);
+    if (why)
+        throw new Error(`scoped mode refused to start: ${why}`);
+    scope = new Scope(cfg, base);
+    return true;
+}
+/** The kill point: the refusal goes back to the agent, then the client exits (no retry in another form). */
+function scopeRefused(v, what) {
+    const msg = scope.refuse(v, what);
+    console.log(`  SCOPE REFUSED: ${v.why}; stopping (would have touched: ${v.wouldTouch})`);
+    setTimeout(() => process.exit(3), 500);
+    return { success: false, error: msg };
+}
 // Dynamic import for usecomputer (ESM)
 let uc = null;
 // Track the most recent coordMap from screenshots for click mapping
@@ -31,10 +55,22 @@ export async function executeCommand(command) {
             case "drag":
                 return await doDrag(params);
             case "windows":
+                if (scope)
+                    return { success: true, data: { windows: scope.windows(await liveWindows()) } };
                 return await listWindows();
             case "batch":
                 return await executeBatch(params);
             case "exec":
+                // THE OWN-PAGES REFUSAL (own-pages.ts). Closes the exec vector only; read that file for
+                // what it deliberately does NOT close.
+                if (scope) {
+                    const v = scope.exec(String(params?.command ?? command.command ?? ""));
+                    if (!v.ok)
+                        return scopeRefused(v, "exec");
+                }
+                if (commandNamesOwnPage(String(command.command ?? ""))) {
+                    throw new Error(OWN_PAGE_REFUSAL);
+                }
                 return await doExec(params);
             default:
                 return { success: false, error: `Unknown command type: ${type}` };
@@ -121,7 +157,15 @@ async function executeBatch(params) {
     return batchResult;
 }
 async function takeScreenshot(params) {
+    let windowId;
+    if (scope) {
+        const v = scope.screenshot(await liveWindows());
+        if (!v.ok)
+            return scopeRefused(v, "screenshot");
+        windowId = v.windowId;
+    }
     const capture = await captureScreenshot({
+        windowId,
         format: params.format || "webp",
         quality: Number(params.quality) || 55,
         maxWidth: Number(params.maxWidth) || 1280,
@@ -158,12 +202,22 @@ async function doClick(params) {
             // If mapping fails, fall back to raw coords
         }
     }
+    if (scope) {
+        const v = scope.point(await liveWindows(), point, "a click");
+        if (!v.ok)
+            return scopeRefused(v, "click");
+    }
     await usecomputer.click({ point, button: "left", count: 1 });
     return { success: true, data: { action: "click", x, y, mappedX: point.x, mappedY: point.y, coordMap: coordMap || "none" } };
 }
 async function doType(params) {
     const usecomputer = await getUC();
     const text = String(params.text);
+    if (scope) {
+        const v = scope.keys(await liveWindows(), "typing");
+        if (!v.ok)
+            return scopeRefused(v, "type");
+    }
     try {
         await usecomputer.typeText({ text, delayMs: null });
     }
@@ -181,6 +235,11 @@ async function doType(params) {
 async function doPress(params) {
     const usecomputer = await getUC();
     const key = String(params.key);
+    if (scope) {
+        const v = scope.keys(await liveWindows(), "a key press");
+        if (!v.ok)
+            return scopeRefused(v, "press");
+    }
     await usecomputer.press({ key, count: null, delayMs: null });
     return { success: true, data: { action: "press", key } };
 }
@@ -188,6 +247,11 @@ async function doScroll(params) {
     const usecomputer = await getUC();
     const direction = String(params.direction);
     const amount = Number(params.amount || 3);
+    if (scope) {
+        const v = scope.point(await liveWindows(), await usecomputer.mousePosition(), "a scroll");
+        if (!v.ok)
+            return scopeRefused(v, "scroll");
+    }
     await usecomputer.scroll({ direction, amount, at: null });
     return { success: true, data: { action: "scroll", direction, amount } };
 }
@@ -204,6 +268,14 @@ async function doDrag(params) {
         }
         catch { }
     }
+    if (scope) {
+        const w = await liveWindows();
+        for (const [p, n] of [[from, "a drag start"], [to, "a drag end"]]) {
+            const v = scope.point(w, p, n);
+            if (!v.ok)
+                return scopeRefused(v, "drag");
+        }
+    }
     await usecomputer.drag({ from, to, durationMs: null, button: null });
     return { success: true, data: { action: "drag" } };
 }

package/dist/index.js

@@ -11,6 +11,7 @@ import { loadConfig, saveConfig, getConfigPath } from "./config.js";
 import { checkPermissions, runPermissionTest } from "./permissions.js";
 import { connect, disconnect } from "./connection.js";
 import { closeSupervisor, setMode } from "./supervisor.js";
+import { initScope } from "./executor.js";
 import chalk from "chalk";
 import readline from "readline";
 import os from "os";
@@ -20,12 +21,19 @@ const API_BASE = "https://instaclaw.io";
 // Temp file to persist pairing code + args across Terminal restarts
 const RETRY_FILE = path.join(os.tmpdir(), "instaclaw-dispatch-retry.json");
 const RETRY_MAX_AGE_MS = 10 * 60 * 1000; // 10 minutes
+/** The client's own version, read from its package.json (one directory above dist/). */
+const CLIENT_VERSION = (() => { try {
+    return JSON.parse(fs.readFileSync(path.join(path.dirname(new URL(import.meta.url).pathname), "..", "package.json"), "utf8")).version;
+}
+catch {
+    return "unknown";
+} })();
 async function main() {
+    const args = parseArgs(); // first: --help and unknown flags exit here, before any banner, check or capture
     console.log(`
-  ${chalk.bold("InstaClaw Dispatch")} ${chalk.dim("— Remote Computer Control")}
+  ${chalk.bold("InstaClaw Dispatch")} ${chalk.dim("Remote Computer Control")}
   ${chalk.dim("─────────────────────────────────────────────")}
   `);
-    const args = parseArgs();
     // ── Auto-retry: check if we're resuming after a Terminal restart ──
     const retry = loadRetryState();
     if (!args.pair && !args.token && retry) {
@@ -53,7 +61,7 @@ async function main() {
                 console.log(`    → Enable "${terminal}"`);
                 console.log("");
                 console.log(chalk.yellow(`  ⚠  Enabling Accessibility will close ${terminal}.`));
-                console.log(chalk.yellow(`     Don't worry — just reopen ${terminal} and run the same command.`));
+                console.log(chalk.yellow(`     Don't worry. Just reopen ${terminal} and run the same command.`));
                 if (args.pair) {
                     console.log(chalk.green(`     Your pairing code ${chalk.bold(args.pair)} will still work.`));
                 }
@@ -83,13 +91,13 @@ async function main() {
                 console.log(`  After granting permissions and reopening ${terminal}, run:`);
                 console.log("");
                 if (args.pair) {
-                    console.log(`  ${chalk.cyan(`npx @instaclaw/dispatch@0.5.0 --pair ${args.pair}`)}`);
+                    console.log(`  ${chalk.cyan(`npx @instaclaw/dispatch@latest --pair ${args.pair}`)}`);
                 }
                 else {
                     console.log(`  ${chalk.cyan("npx @instaclaw/dispatch")}`);
                 }
                 console.log("");
-                console.log(`  ${chalk.dim("Or just reopen Terminal — we'll auto-resume if possible.")}`);
+                console.log(`  ${chalk.dim("Or just reopen Terminal and we'll auto-resume if possible.")}`);
                 console.log("");
                 console.log(`  Press ${chalk.bold("Enter")} when ready (or grant Accessibility and Terminal will restart)...`);
                 await waitForEnter();
@@ -97,7 +105,7 @@ async function main() {
                 const recheck = checkPermissions();
                 if (recheck.accessibility === false) {
                     console.log(`\n  ${chalk.yellow("⚠")} Accessibility still not granted. Click/type commands will fail.`);
-                    console.log(`  ${chalk.dim("Continuing anyway — screenshots may still work.\n")}`);
+                    console.log(`  ${chalk.dim("Continuing anyway. Screenshots may still work.\n")}`);
                 }
                 else {
                     console.log(`\n  ${chalk.green("✓")} Permissions: all OK\n`);
@@ -114,7 +122,7 @@ async function main() {
             }
             else {
                 console.log(`  ${chalk.yellow("⚠")} ${test.error}`);
-                console.log("  Continuing anyway — some commands may fail.\n");
+                console.log("  Continuing anyway. Some commands may fail.\n");
             }
             clearRetryState();
         }
@@ -159,6 +167,15 @@ async function main() {
     console.log(`  ${chalk.dim("VM:")}   ${config.vmAddress}:${config.port}`);
     console.log(`  ${chalk.dim("Mode:")} ${config.mode}`);
     console.log(`  ${chalk.dim("Token:")} ${config.gatewayToken.substring(0, 8)}...\n`);
+    // ── 2b. PASS 43 scoped mode (scope.ts): fixed at start, before any command can arrive; a refusal to start ends here. ──
+    try {
+        if (await initScope())
+            console.log(`  ${chalk.yellow("Scoped mode")}: only windows this test opens; the first refusal stops the client.`);
+    }
+    catch (e) {
+        console.log(`  ${chalk.red("✗")} ${e.message}`);
+        process.exit(3);
+    }
     // ── 3. Connect to VM ──
     connect({
         vmAddress: config.vmAddress,
@@ -339,6 +356,22 @@ function parseArgs() {
         else if ((args[i] === "--pair" || args[i] === "--code") && args[i + 1]) {
             result.pair = args[++i];
         }
+        else {
+            // PASS 43 (PRD 43.18): --help, --version and ANY argument this client does not know print and exit BEFORE anything
+            // starts. An unknown flag used to fall through and start the full client: its permission check runs a full screen
+            // capture (measured 2026-10-31 by `--help` on a Mac it was never meant to touch).
+            const known = args[i] === "--help" || args[i] === "-h" || args[i] === "--version" || args[i] === "-V";
+            if (args[i] === "--version" || args[i] === "-V") {
+                console.log(CLIENT_VERSION);
+                process.exit(0);
+            }
+            console.log(`${known ? "" : `  Unknown argument: ${args[i]}\n\n`}  Usage:
+    npx @instaclaw/dispatch --pair ABCD-1234 [--autonomous]   pair with the code from your dashboard
+    npx @instaclaw/dispatch --token TOKEN --vm HOST           direct connect (advanced)
+    npx @instaclaw/dispatch --help | --version
+  Nothing was started.`);
+            process.exit(known ? 0 : 2);
+        }
     }
     return result;
 }

package/dist/own-pages.d.ts

@@ -0,0 +1,3 @@
+/** True when a shell command names one of our own web origins, gateway subdomains excepted. */
+export declare function commandNamesOwnPage(command: string): boolean;
+export declare const OWN_PAGE_REFUSAL = "Refused: this would act on an InstaClaw page. Your agent is not allowed to approve its own actions.";

package/dist/own-pages.js

@@ -0,0 +1,46 @@
+/**
+ * THE OWN-PAGES REFUSAL, Node CLI. Parity with the Mac app's OwnPages.swift and the extension's
+ * isForbiddenAgentUrl.
+ *
+ * READ THIS BEFORE TRUSTING IT. This closes ONE vector and deliberately does not pretend to close
+ * the one that matters most.
+ *
+ * WHAT IT CLOSES: an `exec` whose command text names one of our own web origins, so the agent
+ * cannot curl an approval endpoint or drive a browser at our pages by naming them.
+ *
+ * WHAT IT CANNOT CLOSE, and no client side check ever will: this CLI can `click` at coordinates and
+ * `type` text on the owner's real desktop. To approve its own spend it needs only `screenshot` to
+ * find the button and `click` to press it. A click carries no text, so no pattern can match it, and
+ * from the operating system's point of view it is indistinguishable from the owner's own click.
+ * CONNECTORS reached the same conclusion independently in lib/owner-request-origin.ts: "a click on
+ * the owner's screen is indistinguishable from the owner's click. THIS MODULE CANNOT" detect it.
+ * FRONTIER reached it too, in lib/frontier-approval-outofband.ts: "a URL-pattern block does not
+ * survive... Dispatch bypasses the browser entirely."
+ *
+ * SO THE REAL FIX IS NOT HERE. It is the out of band completion token FRONTIER already built, which
+ * requires a factor delivered to a surface the agent has no path to. That module is PURE and INERT
+ * with no route importing it. Until it is wired, a machine running this CLI in autonomous mode can
+ * approve its own spend, and adding more client side checks here would be theatre that makes the
+ * hole look closed.
+ */
+const FORBIDDEN_HOSTS = ["instaclaw.io", "www.instaclaw.io"];
+/** True when a shell command names one of our own web origins, gateway subdomains excepted. */
+export function commandNamesOwnPage(command) {
+    const c = String(command || "").toLowerCase();
+    for (const host of FORBIDDEN_HOSTS) {
+        let idx = 0;
+        for (;;) {
+            const at = c.indexOf(host, idx);
+            if (at === -1)
+                break;
+            const prefix = c.slice(0, at);
+            // The customer's own gateway (vm-123.vm.instaclaw.io) is explicitly allowed.
+            if (!prefix.endsWith(".vm.") && !prefix.endsWith("vm."))
+                return true;
+            idx = at + host.length;
+        }
+    }
+    return false;
+}
+export const OWN_PAGE_REFUSAL = "Refused: this would act on an InstaClaw page. Your agent is not allowed to approve its own actions.";
+//# sourceMappingURL=own-pages.js.map

package/dist/permissions.js

@@ -59,7 +59,7 @@ export async function runPermissionTest() {
             fs.unlinkSync(tmpPath);
             if (size > 500)
                 return { ok: true };
-            return { ok: false, error: "Screenshot captured but empty — Screen Recording permission may be missing" };
+            return { ok: false, error: "Screenshot captured but empty. Screen Recording permission may be missing" };
         }
         return { ok: false, error: "Screenshot file not created" };
     }

package/dist/scope.d.ts

@@ -0,0 +1,51 @@
+export type Win = {
+    id: number;
+    ownerPid: number;
+    ownerName: string;
+    title: string;
+    x: number;
+    y: number;
+    width: number;
+    height: number;
+};
+export type ScopeConfig = {
+    apps: string[];
+    folder: string;
+    log: string;
+};
+export type Verdict = {
+    ok: true;
+    windowId?: number;
+} | {
+    ok: false;
+    why: string;
+    wouldTouch: string;
+};
+export declare class Scope {
+    readonly cfg: ScopeConfig;
+    readonly baselineIds: Set<number>;
+    readonly baselinePids: Set<number>;
+    constructor(cfg: ScopeConfig, baseline: Win[]);
+    /** Refuse to start when an allowed app already has a window: its windows could be the owner's. */
+    static startRefusal(cfg: ScopeConfig, baseline: Win[]): string | null;
+    isTestWindow(w: Win): boolean;
+    /** The topmost window containing a desktop point (front to back), if any. */
+    static topAt(wins: Win[], p: {
+        x: number;
+        y: number;
+    }): Win | null;
+    private describe;
+    screenshot(wins: Win[]): Verdict;
+    windows(wins: Win[]): Win[];
+    point(wins: Win[], p: {
+        x: number;
+        y: number;
+    }, what: string): Verdict;
+    keys(wins: Win[], what: string): Verdict;
+    exec(command: string): Verdict;
+    /** The kill point: log what it would have touched (locally), then the caller exits. */
+    refuse(v: Extract<Verdict, {
+        ok: false;
+    }>, command: string): string;
+}
+export declare function loadScopeConfig(): ScopeConfig | null;

package/dist/scope.js

@@ -0,0 +1,88 @@
+/**
+ * SCOPED MODE (DISPATCH pass 43, PRD 43.11): the client acts ONLY inside windows the test opened itself.
+ *
+ * Written for one machine first: Cooper's own Mac, under his line "only windows you open yourself, nothing closed, quit,
+ * deleted or typed into that you did not open". It is fail closed by construction:
+ *   - At start, every window that exists is recorded and refused forever (the BASELINE). If an allowed app is already
+ *     running, the client REFUSES TO START: a window of a running app cannot be told apart from the owner's own.
+ *   - A screenshot is of the frontmost TEST window only, never the full screen (his screen holds terminals and keys).
+ *     `windows` returns test windows only, so no title of his reaches a model.
+ *   - A click, drag or scroll lands only when the desktop point is inside a test window AND that window is the topmost
+ *     one at the point. Typing and keys only when the frontmost window is a test window.
+ *   - `exec` runs only the exact allowed commands (open an allowed app; make the test folder).
+ *   - THE KILL POINT: the first refusal logs, locally only, what it would have touched, and the client exits. The agent
+ *     is told only "refused: outside the test's own windows", never a title of the owner's.
+ * Enabled when INSTACLAW_DISPATCH_SCOPE_FILE names a JSON file: { "apps": ["TextEdit"], "folder": "/Users/x/dir", "log": "/path" }.
+ *
+ * ASSUMPTION, stated: the window list is front to back (CGWindowListCopyWindowInfo's order for on screen windows). It is
+ * proven on the rented Mac before his Mac (J5a), never assumed there.
+ */
+import * as fs from "node:fs";
+export class Scope {
+    cfg;
+    baselineIds;
+    baselinePids;
+    constructor(cfg, baseline) {
+        this.cfg = cfg;
+        this.baselineIds = new Set(baseline.map((w) => w.id));
+        this.baselinePids = new Set(baseline.map((w) => w.ownerPid));
+    }
+    /** Refuse to start when an allowed app already has a window: its windows could be the owner's. */
+    static startRefusal(cfg, baseline) {
+        if (!cfg.apps.length)
+            return "no allowed app is named";
+        if (!cfg.folder.startsWith("/") || cfg.folder.includes(".."))
+            return "the test folder is not an absolute plain path";
+        const open = baseline.filter((w) => cfg.apps.includes(w.ownerName));
+        return open.length ? `${open[0].ownerName} is already open; close it yourself first, or the test cannot tell your windows from its own` : null;
+    }
+    isTestWindow(w) {
+        return !this.baselineIds.has(w.id) && !this.baselinePids.has(w.ownerPid) && this.cfg.apps.includes(w.ownerName);
+    }
+    /** The topmost window containing a desktop point (front to back), if any. */
+    static topAt(wins, p) {
+        return wins.find((w) => p.x >= w.x && p.x < w.x + w.width && p.y >= w.y && p.y < w.y + w.height) ?? null;
+    }
+    describe(w) { return w ? `${w.ownerName} window ${w.id} "${w.title.slice(0, 60)}"` : "no window (the desktop or the menu bar)"; }
+    screenshot(wins) {
+        const t = wins.find((w) => this.isTestWindow(w));
+        return t ? { ok: true, windowId: t.id } : { ok: false, why: "no test window is open", wouldTouch: "a capture of the whole screen" };
+    }
+    windows(wins) { return wins.filter((w) => this.isTestWindow(w)); }
+    point(wins, p, what) {
+        const top = Scope.topAt(wins, p);
+        return top && this.isTestWindow(top) ? { ok: true } : { ok: false, why: `${what} outside the test's own windows`, wouldTouch: this.describe(top) };
+    }
+    keys(wins, what) {
+        const front = wins[0] ?? null;
+        return front && this.isTestWindow(front) ? { ok: true } : { ok: false, why: `${what} while the front window is not the test's`, wouldTouch: this.describe(front) };
+    }
+    exec(command) {
+        const c = command.trim();
+        const apps = this.cfg.apps.map((a) => a.replace(/[.*+?^${}()|[\]\\]/g, "\\$&")).join("|");
+        if (new RegExp(`^open -a (${apps})$`).test(c))
+            return { ok: true };
+        if (c === `mkdir -p ${this.cfg.folder}` || c === `mkdir -p "${this.cfg.folder}"`)
+            return { ok: true };
+        return { ok: false, why: "a shell command outside the allowed list", wouldTouch: `the shell: ${c.slice(0, 80)}` };
+    }
+    /** The kill point: log what it would have touched (locally), then the caller exits. */
+    refuse(v, command) {
+        const line = JSON.stringify({ at: new Date().toISOString(), refused: command, why: v.why, would_touch: v.wouldTouch });
+        try {
+            fs.appendFileSync(this.cfg.log, line + "\n");
+        }
+        catch { }
+        return "refused: outside the test's own windows; the test stopped here";
+    }
+}
+export function loadScopeConfig() {
+    const f = process.env.INSTACLAW_DISPATCH_SCOPE_FILE;
+    if (!f)
+        return null;
+    const j = JSON.parse(fs.readFileSync(f, "utf8"));
+    if (!Array.isArray(j.apps) || typeof j.folder !== "string" || typeof j.log !== "string")
+        throw new Error("scope file needs apps, folder and log");
+    return { apps: j.apps.map(String), folder: j.folder, log: j.log };
+}
+//# sourceMappingURL=scope.js.map

package/dist/screenshot.d.ts

@@ -3,6 +3,8 @@ export interface ScreenshotOptions {
     quality?: number;
     /** Max width — downscale if screen is larger (default 1280) */
     maxWidth?: number;
+    /** PASS 43 scoped mode: capture this one window only, never the full screen. */
+    windowId?: number;
 }
 export interface ScreenshotCapture {
     buffer: Buffer;

package/dist/screenshot.js

@@ -26,7 +26,7 @@ export async function captureScreenshot(opts = {}) {
     const quality = opts.quality || 55;
     const maxWidth = opts.maxWidth || 1280;
     try {
-        const result = await uc.screenshot({ path: tmpPath, display: null, window: null, region: null, annotate: null });
+        const result = await uc.screenshot({ path: tmpPath, display: null, window: opts.windowId ?? null, region: null, annotate: null });
         const pngBuffer = fs.readFileSync(tmpPath);
         let outputBuffer;
         let outWidth = result.imageWidth;

package/dist/supervisor.d.ts

@@ -1,4 +1,6 @@
 import type { DispatchCommand } from "./types.js";
 export declare function setMode(m: "supervised" | "autonomous"): void;
 export declare function requestApproval(command: DispatchCommand): Promise<boolean>;
+/** True when the agent's own stated intent names a consequential act. */
+export declare function descriptionIsConsequential(description: unknown): boolean;
 export declare function closeSupervisor(): void;

package/dist/supervisor.js

@@ -39,20 +39,44 @@ export function setMode(m) {
     mode = m;
 }
 export async function requestApproval(command) {
-    // Always auto-approve passive commands
+    // Passive commands (a screenshot, the window list, status) are approved without a per action prompt ONLY when the
+    // owner opted in (autonomous) or is at the terminal that started the session. PASS 43 (PRD 43.18): they were approved
+    // unconditionally, so a session that never opted in, with no terminal, handed out a FULL SCREEN capture and every
+    // window's title. Measured on main's 0.7.0 at 2026-10-31 20:3xZ: screenshot, windows and status all true.
     if (AUTO_APPROVE_TYPES.has(command.type)) {
-        return true;
+        if (rl || mode === "autonomous")
+            return true;
+        console.log(`\n  Agent wants to: ${formatCommand(command)}`);
+        console.log("  REFUSED. This session did not opt in, and nothing here can show you what it would see.");
+        return false;
     }
     const desc = formatCommand(command);
     const dangerous = isDangerous(command);
-    // Non-interactive (no TTY) — auto-approve everything (can't prompt)
+    // THE NO-TTY PATH, CORRECTED 2026-09-23. It previously read "can't prompt, therefore approve".
+    //
+    // That is the wrong direction and it was the more serious half of this hole. `rl` exists only
+    // when stdin is a TTY, so ANY script, launchd job, systemd unit, CI runner or wrapper fell into
+    // this branch and received full auto-approval while the session was in the DEFAULT supervised
+    // mode, which nobody opted into. Measured against the published 0.6.2 on 2026-09-23: supervised
+    // with no TTY returned screenshot=true click=true type=true.
+    //
+    // Being unable to ask for consent is not the same as having it. We now refuse unless autonomous
+    // was explicitly chosen, which preserves the documented path exactly (the dashboard prints
+    // --autonomous) and closes the silent one.
     if (!rl) {
         if (dangerous) {
             console.log(`\n  BLOCKED (dangerous, no TTY): ${desc}`);
             return false;
         }
-        console.log(`\n  Agent wants to: ${desc}`);
-        console.log("  Auto-approved (non-interactive mode)");
+        if (mode !== "autonomous") {
+            console.log(`\n  Agent wants to: ${desc}`);
+            console.log("  REFUSED. This session did not opt in, and nothing here can show you");
+            console.log("  what is happening or let you stop it.");
+            console.log("  Start Dispatch from your dashboard, or re-run with --autonomous.");
+            return false;
+        }
+        console.log(`\n  Agent: ${desc}`);
+        console.log("  Auto-approved (autonomous, non-interactive)");
         return true;
     }
     // Autonomous mode — auto-approve non-dangerous actions
@@ -63,7 +87,7 @@ export async function requestApproval(command) {
     // Supervised mode OR dangerous action in autonomous mode — prompt user
     console.log(`\n  Agent wants to: ${desc}`);
     if (dangerous) {
-        console.log("  ⚠️  DANGEROUS ACTION — requires confirmation");
+        console.log("  ⚠️  DANGEROUS ACTION, requires confirmation");
     }
     return new Promise((resolve) => {
         rl.question("  [Enter] to approve, [n] to deny: ", (answer) => {
@@ -75,23 +99,72 @@ export async function requestApproval(command) {
         });
     });
 }
-function isDangerous(cmd) {
-    const p = cmd.params;
-    if (cmd.type === "type") {
-        const text = String(p.text || "");
-        return DANGEROUS_TEXT_PATTERNS.some((pat) => pat.test(text));
-    }
-    if (cmd.type === "press") {
-        const key = String(p.key || "").toLowerCase();
-        return DANGEROUS_KEY_COMBOS.has(key);
-    }
-    // Check exec commands for dangerous patterns
-    if (cmd.type === "exec") {
+/**
+ * Per-type danger classification.
+ *
+ * EXHAUSTIVE BY CONSTRUCTION. This is a Record over the declared union, so adding an
+ * eleventh member to DispatchCommand["type"] is a COMPILE ERROR until it is classified
+ * here. Before 2026-09-23 this was an if chain that handled four of the ten declared
+ * types and let the other six reach a bare "return false".
+ *
+ * WHAT IS DELIBERATELY UNCHANGED, and why. click, scroll and drag stay not dangerous.
+ * They are the ordinary acting verbs of autonomous mode, and the dashboard's own
+ * fallback command ends in --autonomous, so classifying them dangerous would refuse the
+ * product's documented use. The protection against acting with no person present is the
+ * no TTY branch in confirmAction, never this table. Every verdict for the ten known
+ * types is preserved exactly as it shipped.
+ */
+/**
+ * CONSEQUENTIAL INTENT, read from the command's OWN description.
+ *
+ * Cooper's ruling of 2026-09-23: an opted-in session acts without asking per action, and pauses
+ * only before an act that leaves the customer's account or cannot be undone, namely sending,
+ * buying, deleting or submitting.
+ *
+ * A click carries coordinates, so this layer cannot know what sits under the cursor. But the
+ * BOX sends a `description` alongside it, which is the agent stating its own intent, and before
+ * 2026-09-23 nothing read it. Measured that day against the published 0.6.2 and against this
+ * build: "Send the email", "Buy it now" and "Delete the file" were ALL auto-approved.
+ *
+ * HONEST LIMIT, stated because it decides where the real fix lives: this only sees intent the
+ * agent chose to write down. An agent that sends no description, or writes "click the button",
+ * passes straight through. So this is the LAST line and not the authoritative one. The
+ * authoritative pause belongs in the agent's own instructions, which CORTEX owns, and this is
+ * filed there. Defence in depth, not a substitute.
+ */
+const CONSEQUENTIAL_INTENT_PATTERNS = [
+    // Leaves the customer's account
+    /\bsend(s|ing)?\b/i, /\bsubmit(s|ting)?\b/i, /\bpost(s|ing)?\b/i,
+    /\bpublish(es|ing)?\b/i, /\bshare(s|ing)?\b/i, /\breply\b/i, /\bforward(s|ing)?\b/i,
+    // Spends money
+    /\bbuy(s|ing)?\b/i, /\bpurchase(s|ing)?\b/i, /\bpay(s|ing|ment)?\b/i,
+    /\bcheckout\b/i, /\border\b/i, /\btransfer(s|ring)?\b/i, /\bwithdraw(s|ing)?\b/i,
+    // Cannot be undone
+    /\bdelete(s|ing)?\b/i, /\bremove(s|ing)?\b/i, /\btrash\b/i, /\berase(s|ing)?\b/i,
+    /\bconfirm(s|ing)?\b/i, /\bapprove(s|ing)?\b/i, /\baccept(s|ing)?\b/i,
+];
+/** True when the agent's own stated intent names a consequential act. */
+export function descriptionIsConsequential(description) {
+    const d = String(description || "");
+    if (!d)
+        return false;
+    return CONSEQUENTIAL_INTENT_PATTERNS.some((pat) => pat.test(d));
+}
+const DANGER_BY_TYPE = {
+    // Reads. They observe the computer and change nothing.
+    screenshot: () => false,
+    status: () => false,
+    windows: () => false,
+    // Acting verbs, deliberately not dangerous. See the note above.
+    click: () => false,
+    scroll: () => false,
+    drag: () => false,
+    type: (p) => DANGEROUS_TEXT_PATTERNS.some((pat) => pat.test(String(p.text || ""))),
+    press: (p) => DANGEROUS_KEY_COMBOS.has(String(p.key || "").toLowerCase()),
+    exec: (p) => {
         const command = String(p.command || "");
-        // Check against text patterns (reuses the same dangerous detection)
         if (DANGEROUS_TEXT_PATTERNS.some((pat) => pat.test(command)))
             return true;
-        // Additional exec-specific dangerous patterns
         if (/\brm\s+-rf\b/.test(command))
             return true;
         if (/\bsudo\b/.test(command))
@@ -101,21 +174,37 @@ function isDangerous(cmd) {
         if (/\bcurl\b.*\|\s*(bash|sh)\b/.test(command))
             return true;
         return false;
-    }
-    // Check all sub-actions in a batch
-    if (cmd.type === "batch") {
+    },
+    batch: (p) => {
         const actions = p.actions;
-        if (Array.isArray(actions)) {
-            return actions.some((a) => isDangerous({ id: "", type: a.type, params: a.params || {} }));
-        }
-    }
-    return false;
+        if (!Array.isArray(actions))
+            return false;
+        return actions.some((a) => isDangerous({
+            id: "",
+            type: a.type,
+            params: a.params || {},
+        }));
+    },
+};
+function isDangerous(cmd) {
+    // THE INTENT CHECK, before the per-type table. Applies to EVERY type, because a described
+    // exec or drag is just as consequential as a described click.
+    if (descriptionIsConsequential(cmd.description))
+        return true;
+    const classify = DANGER_BY_TYPE[cmd.type];
+    // FAIL CLOSED on a type this build has never heard of. A newer or a hostile server can
+    // send one, and before 2026-09-23 it reached "return false" and was called safe.
+    // Calling it dangerous costs nothing real, because the executor cannot run a type it
+    // does not implement either, and it means the next type added cannot arrive unclassified.
+    if (typeof classify !== "function")
+        return true;
+    return classify(cmd.params);
 }
 function formatCommand(cmd) {
     const p = cmd.params;
     switch (cmd.type) {
         case "click":
-            return `Click at (${p.x}, ${p.y})${cmd.description ? ` — "${cmd.description}"` : ""}`;
+            return `Click at (${p.x}, ${p.y})${cmd.description ? `, "${cmd.description}"` : ""}`;
         case "type":
             return `Type: "${String(p.text).substring(0, 50)}${String(p.text).length > 50 ? "..." : ""}"`;
         case "press":

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@instaclaw/dispatch",
-  "version": "0.6.2",
-  "description": "Let your InstaClaw AI agent control your computer — screenshots, clicks, typing, and more via a secure WebSocket relay",
+  "version": "0.7.0",
+  "description": "Let your InstaClaw AI agent control your computer \u2014 screenshots, clicks, typing, and more via a secure WebSocket relay",
   "bin": {
     "instaclaw-dispatch": "./dist/index.js"
   },