@melaya/runner 1.1.74 → 1.1.76

package/dist/computerHelperManifest.d.ts

@@ -1,4 +1,4 @@
-export declare const COMPUTER_HELPER_VERSION = "1.2.0";
+export declare const COMPUTER_HELPER_VERSION = "1.2.1";
 export declare const COMPUTER_HELPER_MANIFEST: Record<string, {
     url: string;
     sha256: string;

package/dist/computerHelperManifest.js

@@ -5,14 +5,14 @@
 // Pinned computer helper releases for the runner CLI host (computerHostCli.ts),
 // keyed by `${process.platform}-${process.arch}`. A download is only accepted
 // when its sha256 matches.
-export const COMPUTER_HELPER_VERSION = "1.2.0";
+export const COMPUTER_HELPER_VERSION = "1.2.1";
 export const COMPUTER_HELPER_MANIFEST = {
     "linux-arm64": {
-        "url": "https://api.melaya.org/desktop/helpers/1.2.0/melaya-computer-linux-aarch64",
-        "sha256": "8f1ddb5a4bdcc7bda35439de6ec1aa962e16b199dcb510e52fb48c00782eeef9"
+        "url": "https://api.melaya.org/desktop/helpers/1.2.1/melaya-computer-linux-aarch64",
+        "sha256": "d4d47603d30e2b4f136a68b88654e331d2ea809520c8e6d1c9f8a604aa709207"
     },
     "linux-x64": {
-        "url": "https://api.melaya.org/desktop/helpers/1.2.0/melaya-computer-linux-x86_64",
-        "sha256": "1431df7dd6f6a5d8412e4120fdadc82c247965a1139b03dd585ce93b21d5e88a"
+        "url": "https://api.melaya.org/desktop/helpers/1.2.1/melaya-computer-linux-x86_64",
+        "sha256": "c2a27d0f3d62efc26486f5cbb56876dd036a9d059a39d251a2704a62af6aacfb"
     }
 };

package/dist/computerHostCli.d.ts

@@ -19,7 +19,10 @@
  * Like the desktop app, this host runs `batch` (step by step, per-step
  * `expect`), `keep_awake` (systemd-inhibit / caffeinate) and `handoff` (no one
  * is at a headless screen: unsupported) itself, and never sends them to the
- * helper.
+ * helper. Real user input (a VNC / console user) PAUSES a run instead of
+ * stopping it (2026-10-23, computerPause.ts, the same engine as the desktop
+ * app): held input is let go, a pointer stream is cancelled, the run waits
+ * until the user is idle, checks the window and continues where it was.
  *
  * computerRelay.ts (server socket <-> executor) loads this module lazily and
  * calls createCliComputerHost({ send, verbose }) when the runner is not inside
@@ -40,6 +43,8 @@
  * packages/desktop-contract/src/computer.ts (this package cannot import it).
  */
 import { type ChildProcess } from "child_process";
+/** COMPUTER_POINTER_KINDS: in a batch, these steps skip their own after-step observation except the last one. */
+export declare const QUIET_POINTER_KINDS: ReadonlySet<string>;
 export type ComputerAppTier = "view" | "click" | "full";
 export interface AllowedApp {
     appId: string;
@@ -52,6 +57,7 @@ export type ComputerRunnerToHost = {
     deadlineMs: number;
     allowedAppIds: string[];
     allowedApps?: AllowedApp[];
+    pauseBudgetMs?: number;
 } | {
     type: "computer.stop";
     reason: string;
@@ -121,7 +127,7 @@ export declare function checkCommand(msg: {
  * accepted when its sha256 matches. Empty until the first release: use
  * MELAYA_COMPUTER_HELPER or --computer-helper meanwhile.
  */
-export declare const HELPER_VERSION = "1.2.0";
+export declare const HELPER_VERSION = "1.2.1";
 export declare const HELPER_MANIFEST: Record<string, {
     url: string;
     sha256: string;
@@ -187,6 +193,11 @@ export declare class HelperProcess {
      */
     /** Releases every key / button the helper holds (helper 1.2.0+; older helpers ignore the op). */
     release(): void;
+    /**
+     * Cancels one command for a pause (pause and resume): unlike cancel(), its `stopped` reply (with the path's
+     * `progress`) still answers the request, so the host knows how far it got and continues from there.
+     */
+    pauseCancel(target: string): void;
     cancel(target?: string): void;
     get running(): boolean;
     dispose(): void;

package/dist/computerHostCli.js

@@ -19,7 +19,10 @@
  * Like the desktop app, this host runs `batch` (step by step, per-step
  * `expect`), `keep_awake` (systemd-inhibit / caffeinate) and `handoff` (no one
  * is at a headless screen: unsupported) itself, and never sends them to the
- * helper.
+ * helper. Real user input (a VNC / console user) PAUSES a run instead of
+ * stopping it (2026-10-23, computerPause.ts, the same engine as the desktop
+ * app): held input is let go, a pointer stream is cancelled, the run waits
+ * until the user is idle, checks the window and continues where it was.
  *
  * computerRelay.ts (server socket <-> executor) loads this module lazily and
  * calls createCliComputerHost({ send, verbose }) when the runner is not inside
@@ -49,6 +52,10 @@ import { homedir } from "os";
 import { delimiter, dirname, join } from "path";
 import { fileURLToPath } from "url";
 import { COMPUTER_HELPER_MANIFEST, COMPUTER_HELPER_VERSION } from "./computerHelperManifest.js";
+import { PAUSE_DEFAULTS, PauseRun, pauseNeedsIdle, pausePositionOf, pauseReportText, pauseRunStep, pauseStopText, } from "./computerPause.js";
+// ── contract mirrors ────────────────────────────────────────────────────────
+/** COMPUTER_POINTER_KINDS: in a batch, these steps skip their own after-step observation except the last one. */
+export const QUIET_POINTER_KINDS = new Set(["move", "mouse", "path", "hover", "drag", "click", "scroll", "cursor_position", "wait", "hold_key"]);
 export const COMPUTER_ACTION_KINDS = [
     "screen", "screenshot", "find", "get_text", "current_app", "list_windows", "list_apps", "list_displays",
     "clipboard_read", "ocr", "wait", "hover", "move", "scroll",
@@ -472,6 +479,13 @@ export class HelperProcess {
     release() {
         this.send({ op: "release" });
     }
+    /**
+     * Cancels one command for a pause (pause and resume): unlike cancel(), its `stopped` reply (with the path's
+     * `progress`) still answers the request, so the host knows how far it got and continues from there.
+     */
+    pauseCancel(target) {
+        this.send({ op: "cancel", target });
+    }
     cancel(target) {
         this.send(target ? { op: "cancel", target } : { op: "cancel" });
         if (!target || !this.child)
@@ -587,8 +601,30 @@ export function _resetCliComputerHost() {
     cliEnabled = false;
     cliDefaults = {};
 }
-/** Real user input seen this recently pauses a batch (`user_interrupted`). */
-const USER_INPUT_PAUSE_MS = 1_500;
+/** Most pause time (someone at the keyboard) one command may add to its deadline (contract COMPUTER_PAUSE.budgetMs, with room). */
+const MAX_PAUSE_BUDGET_MS = 300_000;
+/** A run that paused and could not go on: user_interrupted with where it stopped (a Stop keeps "stopped"). */
+function pauseStopResult(kind, stop, message, elapsedMs, steps, resumeFrom, pauses) {
+    return {
+        ...errorResult(kind, stop.reason === "stopped" ? "stopped" : "user_interrupted", message, elapsedMs),
+        ...(steps ? { steps } : {}),
+        ...(resumeFrom && stop.reason !== "stopped" ? { resumeFrom } : {}),
+        ...(pauses ? { pauses } : {}),
+    };
+}
+/** A resume position the agent copies back (stroke / point / frac, rounded). */
+function cleanPosition(p) {
+    return { stroke: Math.max(0, Math.floor(p.stroke ?? 0)), point: Math.max(0, Math.floor(p.point ?? 0)), frac: Math.round(Math.min(1, Math.max(0, p.frac ?? 0)) * 1000) / 1000 };
+}
+/** A finished command that paused for the user: status completed_with_pauses and the compact report. */
+function withPauses(r, pauses) {
+    if (!pauses)
+        return r;
+    if (!r.ok)
+        return { ...r, pauses };
+    const text = typeof r.text === "string" ? r.text : "";
+    return { ...r, text: `${text}${text ? "\n" : ""}${pauseReportText(pauses)}`, status: "completed_with_pauses", pauses };
+}
 export function createCliComputerHost(options = {}) {
     const opts = { ...cliDefaults, ...options };
     const env = opts.env ?? process.env;
@@ -604,6 +640,10 @@ export function createCliComputerHost(options = {}) {
     let capsAt = 0;
     let disposed = false;
     let lastUserInput = 0;
+    /** Bumped by stopAll: a run started before it has ended (pause and resume stop waiting). */
+    let stopGen = 0;
+    /** The run in flight that pauses for the user (pause and resume, computerPause.ts). */
+    let active = null;
     const keepAwake = opts.keepAwake ?? new KeepAwake({ spawn: opts.spawn, env });
     const ensureHelper = async () => {
         if (disposed)
@@ -624,7 +664,12 @@ export function createCliComputerHost(options = {}) {
             onEvent: (e) => {
                 if (e.event === "user_input") {
                     lastUserInput = Date.now();
-                    log("  [computer] someone is using this computer: runs pause");
+                    // Pause and resume: let go of what the run holds and cancel a pointer stream now; it goes on once they stop.
+                    if (active) {
+                        if (!active.run.interrupted)
+                            log("  [computer] someone is using this computer: the run pauses until they stop");
+                        active.run.onUserInput(active.host);
+                    }
                 }
                 else if (e.event === "log") {
                     log(`  [computer] ${String(e.message || "").slice(0, 300)}`);
@@ -654,7 +699,8 @@ export function createCliComputerHost(options = {}) {
                     kinds.add("keep_awake");
                 else
                     kinds.delete("keep_awake");
-                caps = { ...c, kinds: COMPUTER_ACTION_KINDS.filter((k) => kinds.has(k)), host: "cli" };
+                // pauseResume: this host pauses for the user and resumes (computerPause.ts), takes pauseBudgetMs and resumeFrom.
+                caps = { ...c, kinds: COMPUTER_ACTION_KINDS.filter((k) => kinds.has(k)), host: "cli", pauseResume: true };
             }
             else {
                 caps = null;
@@ -697,61 +743,160 @@ export function createCliComputerHost(options = {}) {
             return errorResult(kind, "helper_unavailable", `The computer helper stopped: ${m}`, Date.now() - started);
         }
     };
-    /** batch, run here step by step (PROTOCOL.md §7): per-step expect, onError, user-input pause, shared deadline. */
-    const runBatch = async (id, action, allowedAppIds, allowedApps, deadlineMs) => {
+    /** What the pause engine needs from this host for one command (every command still goes through runOnHelper). */
+    const pauseHost = (allowedAppIds, allowedApps, clock) => {
+        const gen = stopGen;
+        return {
+            now: () => Date.now(),
+            sleep: (ms) => new Promise((r) => setTimeout(r, ms)),
+            exec: (a, hid) => runOnHelper(hid, a, allowedAppIds, allowedApps, Math.max(500, clock.at - Date.now())),
+            cancel: (hid) => { try {
+                helper?.pauseCancel(hid);
+            }
+            catch { /* helper gone */ } },
+            release: () => { try {
+                helper?.release();
+            }
+            catch { /* best effort */ } },
+            ended: () => disposed || gen !== stopGen,
+            timeLeft: () => clock.at - Date.now(),
+            extend: (ms) => {
+                const d = ms > 0 ? Math.min(ms, clock.budgetLeft) : -Math.min(-ms, clock.used);
+                clock.budgetLeft -= d;
+                clock.used += d;
+                clock.at += d;
+                return d;
+            },
+            lastInputAt: () => lastUserInput,
+            markInput: () => { lastUserInput = Date.now(); },
+            overlay: (on) => log(on ? "  [computer] paused: someone is using this computer; it resumes when they stop" : "  [computer] resumed"),
+            quietMs: PAUSE_DEFAULTS.quietMs,
+            maxPauseMs: PAUSE_DEFAULTS.maxPauseMs,
+        };
+    };
+    /** batch, run here step by step (PROTOCOL.md §7): per-step expect, onError, pause and resume, shared deadline. */
+    const runBatch = async (id, action, allowedAppIds, allowedApps, deadlineMs, pauseBudgetMs = 0) => {
         const started = Date.now();
         const steps = action.steps || [];
         const stopDefault = action.stopOnError !== false;
+        // resumeFrom (2026-10-23): continue a batch that stopped midway; a path at that step goes on at its stroke.
+        const resume = pausePositionOf(action.resumeFrom);
+        const start = resume?.step ?? 0;
+        if (start >= steps.length)
+            return errorResult("batch", "invalid_action", `resumeFrom.step ${start} is past the last step (the batch has ${steps.length}; steps count from 0).`);
+        const clock = { at: started + deadlineMs, budgetLeft: pauseBudgetMs, used: 0 };
+        const run = new PauseRun();
+        const host = pauseHost(allowedAppIds, allowedApps, clock);
+        active = { run, host };
         const results = [];
         let failed = 0;
-        const left = () => deadlineMs - (Date.now() - started);
-        for (let i = 0; i < steps.length; i++) {
-            const step = steps[i];
-            const kind = String(step.kind || "");
-            let r;
-            let expectFailed = false;
-            if (i > 0 && Date.now() - lastUserInput < USER_INPUT_PAUSE_MS) {
-                r = errorResult(kind, "user_interrupted", "Someone started using the mouse or keyboard, so the batch paused here. Read the screen before continuing.");
-            }
-            else if (left() < 200) {
-                r = errorResult(kind, "timeout", "The batch ran out of time before this step.");
-            }
-            else if (kind === "keep_awake" || kind === "handoff") {
-                r = await runLocal(kind, step);
-            }
-            else {
-                const { expect: cond, onError: _onError, expectTimeoutMs, ...plain } = step;
-                r = await runOnHelper(`${id}.${i + 1}`, plain, allowedAppIds, allowedApps, Math.max(500, left()));
-                if (r.ok && cond && typeof cond === "object") {
-                    const timeoutMs = Math.min(Math.max(100, Number(expectTimeoutMs) || 2_000), Math.max(100, left() - 100));
-                    const ex = await runOnHelper(`${id}.${i + 1}e`, { kind: "expect", condition: cond, timeoutMs }, allowedAppIds, allowedApps, timeoutMs + 500);
-                    if (!ex.ok) {
-                        expectFailed = true;
-                        const em = ex.error?.message || "the expectation failed";
-                        r = { ok: false, kind, error: { code: ex.error?.code || "timeout", message: `The step ran but its expectation failed: ${em}` }, elapsedMs: r.elapsedMs };
+        const left = () => clock.at - Date.now();
+        try {
+            for (let i = start; i < steps.length; i++) {
+                const step = steps[i];
+                const kind = String(step.kind || "");
+                let r;
+                let expectFailed = false;
+                if (left() < 200) {
+                    r = errorResult(kind, "timeout", "The batch ran out of time before this step.");
+                }
+                else if (kind === "keep_awake" || kind === "handoff") {
+                    r = await runLocal(kind, step);
+                }
+                else {
+                    const { expect: cond, onError: _onError, expectTimeoutMs, ...own } = step;
+                    // Pointer steps other than the last skip their own after-step observation, as in the desktop app: a path
+                    // step otherwise waited ~0.1 s for a UI event a canvas never sends (1200 strokes: 160 s instead of ~20 s).
+                    const plain = QUIET_POINTER_KINDS.has(kind) && i < steps.length - 1 && own.observe === undefined ? { ...own, observe: "none" } : own;
+                    const pathStart = i === start && plain.kind === "path" && resume ? resume : null;
+                    const out = await pauseRunStep(host, run, plain, `${id}.${i + 1}`, pathStart);
+                    if ("stop" in out) {
+                        // Someone took over and the run cannot go on safely: say where, and how to continue (resumeFrom).
+                        try {
+                            helper?.release();
+                        }
+                        catch { /* best effort */ }
+                        const at = kind === "path" ? cleanPosition(out.stop.at ?? (pathStart ?? {})) : {};
+                        const resumeFrom = { step: i, ...(kind === "path" ? at : {}) };
+                        const where = `at step ${i + 1} of ${steps.length} (${kind}${kind === "path" ? `, stroke ${(at.stroke ?? 0) + 1}` : ""})`;
+                        return pauseStopResult("batch", out.stop, pauseStopText(out.stop, where, resumeFrom), Date.now() - started, results, resumeFrom, run.report());
+                    }
+                    r = out.result;
+                    if (r.ok && cond && typeof cond === "object") {
+                        const timeoutMs = Math.min(Math.max(100, Number(expectTimeoutMs) || 2_000), Math.max(100, left() - 100));
+                        // Checked on the window the step acts in: its own windowId, else the batch's (windowTitleContains never
+                        // matches some other window, 2026-10-24, with helper 1.2.2).
+                        const expectWindow = typeof plain.windowId === "string" ? plain.windowId : typeof action.windowId === "string" ? action.windowId : "";
+                        const ex = await runOnHelper(`${id}.${i + 1}e`, { kind: "expect", condition: cond, timeoutMs, ...(expectWindow ? { windowId: expectWindow } : {}) }, allowedAppIds, allowedApps, timeoutMs + 500);
+                        if (!ex.ok) {
+                            expectFailed = true;
+                            const em = ex.error?.message || "the expectation failed";
+                            r = { ok: false, kind, error: { code: ex.error?.code || "timeout", message: `The step ran but its expectation failed: ${em}` }, elapsedMs: r.elapsedMs };
+                        }
                     }
                 }
-            }
-            results.push(r);
-            if (!r.ok) {
-                failed++;
-                const code = String(r.error?.code || "internal");
-                const onError = step.onError === "continue" ? false : step.onError === "stop" ? true : stopDefault;
-                // A failed expectation follows onError; a stop, a timeout or a person at the keyboard always ends the batch.
-                const forced = !expectFailed && ["stopped", "timeout", "user_interrupted", "screen_locked", "secure_desktop"].includes(code);
-                if (onError || forced) {
-                    const msg = r.error?.message || "";
-                    // A batch that did not finish leaves nothing pressed (hold_key / mouse down without their up).
-                    try {
-                        helper?.release();
+                results.push(r);
+                if (!r.ok) {
+                    failed++;
+                    const code = String(r.error?.code || "internal");
+                    const onError = step.onError === "continue" ? false : step.onError === "stop" ? true : stopDefault;
+                    // A failed expectation follows onError; a stop, a timeout or a person at the keyboard always ends the batch.
+                    const forced = !expectFailed && ["stopped", "timeout", "user_interrupted", "screen_locked", "secure_desktop"].includes(code);
+                    if (onError || forced) {
+                        const msg = r.error?.message || "";
+                        // A batch that did not finish leaves nothing pressed (hold_key / mouse down without their up).
+                        try {
+                            helper?.release();
+                        }
+                        catch { /* best effort */ }
+                        const pauses = run.report();
+                        return { ok: false, kind: "batch", error: { code, message: `Step ${i + 1} failed: ${msg}` }, steps: results, elapsedMs: Date.now() - started, ...(pauses ? { pauses } : {}) };
                     }
-                    catch { /* best effort */ }
-                    return { ok: false, kind: "batch", error: { code, message: `Step ${i + 1} failed: ${msg}` }, steps: results, elapsedMs: Date.now() - started };
                 }
             }
         }
+        finally {
+            if (active?.run === run)
+                active = null;
+        }
+        const pauses = run.report();
         const text = failed === 0 ? `All ${results.length} steps done.` : `${results.length} steps run, ${failed} failed (onError continue).`;
-        return { ok: true, kind: "batch", text, steps: results, elapsedMs: Date.now() - started };
+        return {
+            ok: true, kind: "batch", text: pauses ? `${text}\n${pauseReportText(pauses)}` : text, steps: results, elapsedMs: Date.now() - started,
+            ...(pauses ? { status: "completed_with_pauses", pauses } : {}),
+        };
+    };
+    /** One action that sends input: it waits while someone uses the computer and resumes a path where it was. */
+    const runPausable = async (id, action, allowedAppIds, allowedApps, deadlineMs, pauseBudgetMs) => {
+        const started = Date.now();
+        const kind = String(action.kind || "screen");
+        const clock = { at: started + deadlineMs, budgetLeft: pauseBudgetMs, used: 0 };
+        const run = new PauseRun();
+        const host = pauseHost(allowedAppIds, allowedApps, clock);
+        active = { run, host };
+        try {
+            const resume = kind === "path" ? pausePositionOf(action.resumeFrom) : null;
+            const out = await pauseRunStep(host, run, action, id, resume);
+            if ("stop" in out) {
+                try {
+                    helper?.release();
+                }
+                catch { /* best effort */ }
+                if (kind === "path") {
+                    const at = cleanPosition(out.stop.at ?? resume ?? {});
+                    return pauseStopResult(kind, out.stop, pauseStopText(out.stop, `at stroke ${(at.stroke ?? 0) + 1}`, at), Date.now() - started, undefined, at, run.report());
+                }
+                return pauseStopResult(kind, out.stop, `${out.stop.message} Melaya stopped before ${kind} ran (nothing of it was done). Read the screen first, then send it again, or ask the user.`, Date.now() - started, undefined, undefined, run.report());
+            }
+            // elapsedMs of a command that paused covers the pauses too (callers subtract pausedMs, like an approval wait).
+            const r = out.result;
+            const pauses = run.report();
+            return withPauses(pauses ? { ...r, elapsedMs: Math.max(Number(r.elapsedMs) || 0, Date.now() - started) } : r, pauses);
+        }
+        finally {
+            if (active?.run === run)
+                active = null;
+        }
     };
     /** keep_awake and handoff, run by the host. */
     const runLocal = async (kind, action) => {
@@ -773,10 +918,14 @@ export function createCliComputerHost(options = {}) {
             return check.result;
         const kind = String(check.action.kind);
         const id = typeof msg.id === "string" && msg.id ? msg.id : `cli${Date.now()}`;
+        const budget = Math.floor(Number(msg.pauseBudgetMs));
+        const pauseBudgetMs = Number.isFinite(budget) && budget > 0 ? Math.min(MAX_PAUSE_BUDGET_MS, budget) : 0;
         if (kind === "keep_awake" || kind === "handoff")
             return runLocal(kind, check.action);
         if (kind === "batch")
-            return runBatch(id, check.action, check.allowedAppIds, check.allowedApps, check.deadlineMs);
+            return runBatch(id, check.action, check.allowedAppIds, check.allowedApps, check.deadlineMs, pauseBudgetMs);
+        if (pauseNeedsIdle(kind))
+            return runPausable(id, check.action, check.allowedAppIds, check.allowedApps, check.deadlineMs, pauseBudgetMs);
         return runOnHelper(id, check.action, check.allowedAppIds, check.allowedApps, check.deadlineMs);
     };
     const api = {
@@ -802,6 +951,8 @@ export function createCliComputerHost(options = {}) {
         capabilities,
         stopAll(reason) {
             log(`  [computer] stop (${String(reason || "stop").slice(0, 200)})`);
+            // A paused run stops waiting at once (Stop always wins over pause and resume).
+            stopGen++;
             helper?.cancel();
             keepAwake.release();
         },

package/dist/computerPause.d.ts

@@ -0,0 +1,179 @@
+export type PauseRec = Record<string, unknown>;
+export interface PauseRect {
+    x: number;
+    y: number;
+    width: number;
+    height: number;
+}
+/** Where a run stopped / continues: batch step, then stroke / point / frac inside a path (contract ComputerResumePoint). */
+export interface PausePosition {
+    step?: number;
+    stroke?: number;
+    point?: number;
+    frac?: number;
+}
+/** How far a cancelled path / drag got, as the helper reports it (contract ComputerPathProgress). */
+export interface PauseProgress {
+    stroke?: number;
+    point?: number;
+    frac?: number;
+    pressed?: boolean;
+}
+/** What the pauses of one command did (contract ComputerPauseReport). */
+export interface PauseReport {
+    count: number;
+    pausedMs: number;
+    refocused?: number;
+    moved?: boolean;
+    resumedStrokes?: number;
+}
+/** The part of a ComputerResult the engine reads. */
+export interface PauseResult {
+    ok: boolean;
+    kind?: string;
+    text?: string;
+    error?: {
+        code?: string;
+        message?: string;
+    };
+    [k: string]: unknown;
+}
+export interface PauseWindow {
+    windowId: string;
+    appId?: string;
+    title?: string;
+    bounds: PauseRect;
+    focused?: boolean;
+    minimized?: boolean;
+}
+export declare const PAUSE_DEFAULTS: {
+    /** The user must be idle this long before the run goes on. */
+    readonly quietMs: 1500;
+    /** One pause lasts at most this long; then the run stops with user_interrupted and a resume point. */
+    readonly maxPauseMs: 60000;
+    /** Pause time the server grants per command on top of its deadline. */
+    readonly budgetMs: 180000;
+    /** A step interrupted more often than this stops (the user keeps taking over). */
+    readonly maxResumesPerStep: 20;
+    /** Time kept back before the deadline: a pause ends in time to report where it stopped. */
+    readonly reserveMs: 1500;
+};
+/** Reads that send no input: they run while the user is busy. Everything else waits until the user is idle. */
+export declare const PAUSE_PASSIVE_KINDS: ReadonlySet<string>;
+/** Pointer streams cancelled the moment the user takes over (never fight for the cursor); short atomic writes finish. */
+export declare const PAUSE_CANCEL_KINDS: ReadonlySet<string>;
+export declare function pauseNeedsIdle(kind: string): boolean;
+export declare function pauseRectMoved(a: PauseRect, b: PauseRect, tol?: number): boolean;
+export declare function pauseRectResized(a: PauseRect, b: PauseRect, tol?: number): boolean;
+type PausePt = number[];
+/**
+ * The rest of one stroke from (point, frac): it starts on the last sample the pointer reached (pressed again there,
+ * one sample of overlap, no gap, nothing drawn twice beyond it), then every later point; times are shifted to start at
+ * 0. null when nothing is left (the stroke had reached its last point).
+ */
+export declare function pauseTrimStroke(stroke: PausePt[], point: number, frac: number): PausePt[] | null;
+/** A path from a position (strokes before `stroke` are done, that stroke goes on from point / frac); null when nothing is left. */
+export declare function pauseTrimPath(action: PauseRec, pos: PausePosition): PauseRec | null;
+/**
+ * The helper's progress on a path that was itself cut at `base`, as a position in the ORIGINAL path. The cut path's
+ * point 0 is the re-pressed sample on base segment (point -> point + 1); its point k >= 1 is base point + k.
+ */
+export declare function pauseAbsolute(base: PausePosition, rel: PauseProgress): PausePosition;
+/** A resumeFrom as a position (step, stroke, point: whole numbers >= 0; frac in 0..1); null when absent. */
+export declare function pausePositionOf(v: unknown): PausePosition | null;
+/**
+ * A window / region path moved with its window (same size only: a canvas does not scale with its window, so a resized
+ * window stops the run). null when it cannot follow (screen pixels, or resized).
+ */
+export declare function pauseShiftPath(action: PauseRec, from: PauseRect, to: PauseRect): PauseRec | null;
+/**
+ * One step after its window moved from `from` to `to`: window / region paths move with it; points in screen pixels
+ * and refs bound to a screen taken before the move cannot follow (null: stop there); a label is found again (its
+ * snapshot binding is dropped). Steps on other windows, or without coordinates, are unchanged.
+ */
+export declare function pauseShiftStep(step: PauseRec, from: PauseRect, to: PauseRect): PauseRec | null;
+export type PauseStopReason = "stopped" | "max_pause" | "deadline" | "window_closed" | "dialog" | "moved" | "refocus" | "repress" | "dropped" | "unknown_progress" | "stale" | "too_many";
+export interface PauseStop {
+    reason: PauseStopReason;
+    message: string;
+    /** Inside a path: where it stopped (stroke / point / frac in the step's original strokes). */
+    at?: PausePosition;
+}
+/** What the executor needs from its host. Every command goes through `exec` (the host's own checks apply). */
+export interface PauseHost {
+    now(): number;
+    sleep(ms: number): Promise<void>;
+    /** Runs one helper command (never batch / handoff / keep_awake) and resolves with its result, cancelled or not. */
+    exec(action: PauseRec, id: string): Promise<PauseResult>;
+    /** Cancels one running command for a pause; its (stopped) result, with `progress`, still resolves `exec`. */
+    cancel(id: string): void;
+    /** Releases every key and mouse button the helper holds. */
+    release(): void;
+    /** The command was answered elsewhere (Stop, the deadline, the app closing): stop waiting, act on nothing. */
+    ended(): boolean;
+    /** Time left before the command's deadline (ms). */
+    timeLeft(): number;
+    /** Pushes the deadline back by up to `ms` from the pause budget (negative: gives time back); returns what moved. */
+    extend(ms: number): number;
+    /** Time of the last real user input the host saw (0: none). */
+    lastInputAt(): number;
+    /** The helper refused because someone is using the computer: start a new quiet period from now. */
+    markInput(): void;
+    /** Shows / hides "Paused while you use the computer". */
+    overlay(paused: boolean): void;
+    quietMs: number;
+    maxPauseMs: number;
+}
+/** State of one command that may pause (a single action, or every step of a batch). */
+export declare class PauseRun {
+    count: number;
+    pausedMs: number;
+    refocused: number;
+    moved: boolean;
+    resumedStrokes: number;
+    /** Keys (hold_key) and buttons (mouse down) the run holds; released at a pause, pressed again before going on. */
+    readonly keys: Map<string, string>;
+    readonly buttons: Set<string>;
+    pointer: {
+        x: number;
+        y: number;
+    } | null;
+    /** The run's window (the last result's `current`). */
+    windowId: string | null;
+    /** Windows that moved during a pause: where they were first, where they are now. */
+    readonly shifts: Map<string, {
+        from: PauseRect;
+        to: PauseRect;
+    }>;
+    current: {
+        id: string;
+        kind: string;
+    } | null;
+    readonly cancelled: Set<string>;
+    /** The user took over since the last pause: the next step that sends input pauses first. */
+    interrupted: boolean;
+    holds(): boolean;
+    /** Real user input: cancel a pointer stream now, let go of what the run holds; the next step pauses. */
+    onUserInput(host: Pick<PauseHost, "cancel" | "release">): void;
+    /** What a finished step left held, where the pointer is, which window the run is in. */
+    track(action: PauseRec, r: PauseResult): void;
+    report(): PauseReport | undefined;
+    /** A step as it must run now: moved with its window if that window moved during an earlier pause (null: it cannot). */
+    adapt(step: PauseRec): PauseRec | null;
+}
+/** One line for a result that paused: how often, how long, what was done to go on. */
+export declare function pauseReportText(r: PauseReport | undefined): string;
+/** The message of a run that stopped: why, where, and how to continue (resume_from). */
+export declare function pauseStopText(stop: PauseStop, where: string, resume: PausePosition): string;
+/**
+ * One step that pauses for the user instead of failing. Before a step that sends input, it waits while the user is
+ * busy; a pointer stream the user interrupted goes on from where it was (a path from its last sample, a drag from
+ * its start if nothing was picked up, a move / hover / mouse step again). `start`: a path's resume position.
+ * Returns the step's result, or `stop` when the run cannot go on safely (the caller answers user_interrupted).
+ */
+export declare function pauseRunStep(host: PauseHost, run: PauseRun, step: PauseRec, id: string, start?: PausePosition | null): Promise<{
+    result: PauseResult;
+} | {
+    stop: PauseStop;
+}>;
+export {};

package/dist/computerPause.js

@@ -0,0 +1,488 @@
+// Pause and resume for computer control (2026-10-23), runner copy: the CLI host (computerHostCli.ts, `npx
+// @melaya/runner --computer`) pauses for the user exactly as the desktop app does. This package cannot import
+// @melaya/desktop-contract, so the engine below is a byte-identical copy of
+// packages/desktop-contract/src/computerPause.ts (server/test/computerPause.test.ts diffs the three copies).
+// Edit the contract file first, then copy the block between the markers here and into the server.
+export const PAUSE_DEFAULTS = {
+    /** The user must be idle this long before the run goes on. */
+    quietMs: 1500,
+    /** One pause lasts at most this long; then the run stops with user_interrupted and a resume point. */
+    maxPauseMs: 60_000,
+    /** Pause time the server grants per command on top of its deadline. */
+    budgetMs: 180_000,
+    /** A step interrupted more often than this stops (the user keeps taking over). */
+    maxResumesPerStep: 20,
+    /** Time kept back before the deadline: a pause ends in time to report where it stopped. */
+    reserveMs: 1500,
+};
+/** Reads that send no input: they run while the user is busy. Everything else waits until the user is idle. */
+export const PAUSE_PASSIVE_KINDS = new Set([
+    "screen", "screenshot", "find", "get_text", "current_app", "list_windows", "list_apps", "list_displays", "clipboard_read",
+    "ocr", "wait", "zoom", "cursor_position", "read_table", "expect", "handoff", "keep_awake",
+]);
+/** Pointer streams cancelled the moment the user takes over (never fight for the cursor); short atomic writes finish. */
+export const PAUSE_CANCEL_KINDS = new Set(["path", "drag", "move", "hover", "mouse"]);
+export function pauseNeedsIdle(kind) {
+    return !PAUSE_PASSIVE_KINDS.has(kind);
+}
+function pauseNum(v) {
+    const n = Number(v);
+    return Number.isFinite(n) ? n : 0;
+}
+function pauseIsRect(v) {
+    const r = v;
+    return !!r && typeof r === "object" && [r.x, r.y, r.width, r.height].every((n) => Number.isFinite(Number(n)));
+}
+export function pauseRectMoved(a, b, tol = 2) {
+    return Math.abs(a.x - b.x) > tol || Math.abs(a.y - b.y) > tol || Math.abs(a.width - b.width) > tol || Math.abs(a.height - b.height) > tol;
+}
+export function pauseRectResized(a, b, tol = 2) {
+    return Math.abs(a.width - b.width) > tol || Math.abs(a.height - b.height) > tol;
+}
+/** A position inside a stroke: frac 1 is the start of the next segment. */
+function pauseNormalize(point, frac) {
+    let p = Math.max(0, Math.floor(pauseNum(point)));
+    let f = Math.min(1, Math.max(0, pauseNum(frac)));
+    if (f >= 1) {
+        p += 1;
+        f = 0;
+    }
+    return { point: p, frac: f };
+}
+/**
+ * The rest of one stroke from (point, frac): it starts on the last sample the pointer reached (pressed again there,
+ * one sample of overlap, no gap, nothing drawn twice beyond it), then every later point; times are shifted to start at
+ * 0. null when nothing is left (the stroke had reached its last point).
+ */
+export function pauseTrimStroke(stroke, point, frac) {
+    const n = stroke.length;
+    const at = pauseNormalize(point, frac);
+    if (at.point === 0 && at.frac === 0)
+        return stroke.map((q) => q.slice());
+    if (at.point >= n - 1)
+        return null;
+    const a = stroke[at.point], b = stroke[at.point + 1];
+    const timed = a.length >= 3 && b.length >= 3;
+    const head = [a[0] + (b[0] - a[0]) * at.frac, a[1] + (b[1] - a[1]) * at.frac];
+    if (timed)
+        head.push(a[2] + (b[2] - a[2]) * at.frac);
+    const out = [head, ...stroke.slice(at.point + 1).map((q) => q.slice())];
+    if (timed) {
+        const t0 = head[2];
+        for (const q of out)
+            q[2] = Math.max(0, q[2] - t0);
+    }
+    return out;
+}
+/** A path from a position (strokes before `stroke` are done, that stroke goes on from point / frac); null when nothing is left. */
+export function pauseTrimPath(action, pos) {
+    const strokes = Array.isArray(action.strokes) ? action.strokes : [];
+    const s = Math.max(0, Math.floor(pauseNum(pos.stroke)));
+    if (s >= strokes.length)
+        return null;
+    const first = pauseTrimStroke(strokes[s], pauseNum(pos.point), pauseNum(pos.frac));
+    const next = [...(first ? [first] : []), ...strokes.slice(s + 1).map((st) => st.map((q) => q.slice()))];
+    if (!next.length)
+        return null;
+    const out = { ...action, strokes: next };
+    delete out.resumeFrom;
+    return out;
+}
+/**
+ * The helper's progress on a path that was itself cut at `base`, as a position in the ORIGINAL path. The cut path's
+ * point 0 is the re-pressed sample on base segment (point -> point + 1); its point k >= 1 is base point + k.
+ */
+export function pauseAbsolute(base, rel) {
+    const bs = Math.max(0, Math.floor(pauseNum(base.stroke)));
+    const b = pauseNormalize(base.point, base.frac);
+    const rs = Math.max(0, Math.floor(pauseNum(rel.stroke)));
+    if (!rel.pressed)
+        return rs === 0 ? { stroke: bs, point: b.point, frac: b.frac } : { stroke: bs + rs, point: 0, frac: 0 };
+    const r = pauseNormalize(rel.point, rel.frac);
+    if (rs > 0)
+        return { stroke: bs + rs, point: r.point, frac: r.frac };
+    if (r.point === 0)
+        return { stroke: bs, point: b.point, frac: b.frac + r.frac * (1 - b.frac) };
+    return { stroke: bs, point: b.point + r.point, frac: r.frac };
+}
+/** A resumeFrom as a position (step, stroke, point: whole numbers >= 0; frac in 0..1); null when absent. */
+export function pausePositionOf(v) {
+    if (!v || typeof v !== "object")
+        return null;
+    const o = v;
+    const out = {};
+    for (const k of ["step", "stroke", "point"])
+        if (o[k] !== undefined)
+            out[k] = Math.max(0, Math.floor(pauseNum(o[k])));
+    if (o.frac !== undefined)
+        out.frac = Math.min(1, Math.max(0, pauseNum(o.frac)));
+    return out;
+}
+/**
+ * A window / region path moved with its window (same size only: a canvas does not scale with its window, so a resized
+ * window stops the run). null when it cannot follow (screen pixels, or resized).
+ */
+export function pauseShiftPath(action, from, to) {
+    if (!pauseRectMoved(from, to))
+        return action;
+    if (pauseRectResized(from, to))
+        return null;
+    const anchor = action.anchor === "window" || action.anchor === "region" ? action.anchor : pauseIsRect(action.windowRect) ? "window" : "screen";
+    if (anchor === "screen")
+        return null;
+    const dx = to.x - from.x, dy = to.y - from.y;
+    const strokes = (Array.isArray(action.strokes) ? action.strokes : []).map((st) => st.map((q) => {
+        const c = q.slice();
+        c[0] = c[0] + dx;
+        c[1] = c[1] + dy;
+        return c;
+    }));
+    const out = { ...action, strokes };
+    if (pauseIsRect(action.windowRect)) {
+        const w = action.windowRect;
+        out.windowRect = { x: w.x + dx, y: w.y + dy, width: w.width, height: w.height };
+    }
+    return out;
+}
+/**
+ * One step after its window moved from `from` to `to`: window / region paths move with it; points in screen pixels
+ * and refs bound to a screen taken before the move cannot follow (null: stop there); a label is found again (its
+ * snapshot binding is dropped). Steps on other windows, or without coordinates, are unchanged.
+ */
+export function pauseShiftStep(step, from, to) {
+    if (!pauseRectMoved(from, to))
+        return step;
+    const kind = String(step.kind);
+    if (kind === "path")
+        return pauseShiftPath(step, pauseIsRect(step.windowRect) ? step.windowRect : from, to);
+    if (kind === "move")
+        return null;
+    for (const k of ["target", "from", "to"]) {
+        const t = step[k];
+        if (t && typeof t === "object" && t.x !== undefined && t.y !== undefined)
+            return null;
+    }
+    if (step.snapshotId === undefined)
+        return step;
+    for (const k of ["target", "from", "to"]) {
+        const t = step[k];
+        if (t && typeof t === "object" && typeof t.ref === "string")
+            return null;
+    }
+    const { snapshotId: _snap, ...rest } = step;
+    return rest;
+}
+/** State of one command that may pause (a single action, or every step of a batch). */
+export class PauseRun {
+    count = 0;
+    pausedMs = 0;
+    refocused = 0;
+    moved = false;
+    resumedStrokes = 0;
+    /** Keys (hold_key) and buttons (mouse down) the run holds; released at a pause, pressed again before going on. */
+    keys = new Map();
+    buttons = new Set();
+    pointer = null;
+    /** The run's window (the last result's `current`). */
+    windowId = null;
+    /** Windows that moved during a pause: where they were first, where they are now. */
+    shifts = new Map();
+    current = null;
+    cancelled = new Set();
+    /** The user took over since the last pause: the next step that sends input pauses first. */
+    interrupted = false;
+    holds() {
+        return this.keys.size > 0 || this.buttons.size > 0;
+    }
+    /** Real user input: cancel a pointer stream now, let go of what the run holds; the next step pauses. */
+    onUserInput(host) {
+        this.interrupted = true;
+        const cur = this.current;
+        if (cur && PAUSE_CANCEL_KINDS.has(cur.kind) && !this.cancelled.has(cur.id)) {
+            this.cancelled.add(cur.id);
+            host.cancel(cur.id);
+        }
+        if (this.holds())
+            host.release();
+    }
+    /** What a finished step left held, where the pointer is, which window the run is in. */
+    track(action, r) {
+        const kind = String(action.kind);
+        if (kind === "hold_key") {
+            const k = String(action.key || "").trim();
+            if (action.state === "down")
+                this.keys.set(k.toLowerCase(), k);
+            else
+                this.keys.delete(k.toLowerCase());
+        }
+        else if (kind === "mouse") {
+            const b = typeof action.button === "string" ? action.button : "left";
+            if (action.state === "down")
+                this.buttons.add(b);
+            else
+                this.buttons.delete(b);
+        }
+        const p = r.pointer;
+        const t = (action.target ?? action.to);
+        if (p && Number.isFinite(Number(p.x)) && Number.isFinite(Number(p.y)))
+            this.pointer = { x: Number(p.x), y: Number(p.y) };
+        else if (kind === "move" && Number.isFinite(Number(action.x)) && Number.isFinite(Number(action.y)))
+            this.pointer = { x: Number(action.x), y: Number(action.y) };
+        else if (t && typeof t === "object" && Number.isFinite(Number(t.x)) && Number.isFinite(Number(t.y)))
+            this.pointer = { x: Number(t.x), y: Number(t.y) };
+        const cur = r.current;
+        if (cur && typeof cur.windowId === "string" && cur.windowId)
+            this.windowId = cur.windowId;
+        else if (typeof action.windowId === "string" && action.windowId)
+            this.windowId = action.windowId;
+    }
+    report() {
+        if (!this.count)
+            return undefined;
+        return {
+            count: this.count, pausedMs: Math.round(this.pausedMs),
+            ...(this.refocused ? { refocused: this.refocused } : {}),
+            ...(this.moved ? { moved: true } : {}),
+            ...(this.resumedStrokes ? { resumedStrokes: this.resumedStrokes } : {}),
+        };
+    }
+    /** A step as it must run now: moved with its window if that window moved during an earlier pause (null: it cannot). */
+    adapt(step) {
+        if (!this.shifts.size)
+            return step;
+        const wid = typeof step.windowId === "string" ? step.windowId : this.windowId;
+        const m = wid ? this.shifts.get(wid) : undefined;
+        return m ? pauseShiftStep(step, m.from, m.to) : step;
+    }
+}
+function pauseSecs(ms) {
+    return ms >= 10_000 ? `${Math.round(ms / 1000)} s` : `${(ms / 1000).toFixed(1)} s`;
+}
+/** One line for a result that paused: how often, how long, what was done to go on. */
+export function pauseReportText(r) {
+    if (!r || !r.count)
+        return "";
+    const extra = [
+        r.refocused ? "brought the window back to the front" : "",
+        r.moved ? "followed the window to where it was moved" : "",
+        r.resumedStrokes ? `continued ${r.resumedStrokes} stroke${r.resumedStrokes === 1 ? "" : "s"} midway` : "",
+    ].filter(Boolean).join(", ");
+    return `Paused ${r.count === 1 ? "once" : `${r.count} times`} (${pauseSecs(r.pausedMs)}) while the user used the computer, then resumed${extra ? ` (${extra})` : ""}.`;
+}
+/** The message of a run that stopped: why, where, and how to continue (resume_from). */
+export function pauseStopText(stop, where, resume) {
+    return `${stop.message} Melaya stopped ${where}; nothing after that point was done. Read the screen first, then call again with the same ` +
+        `steps / strokes and resume_from ${JSON.stringify(resume)} to continue exactly there without redoing anything, or ask the user.`;
+}
+function pauseStop(reason, message, at) {
+    return { stop: { reason, message, ...(at ? { at } : {}) } };
+}
+function pauseWindows(r) {
+    if (!r.ok || !Array.isArray(r.windows))
+        return null;
+    return r.windows.filter((w) => w && typeof w.windowId === "string" && pauseIsRect(w.bounds));
+}
+/**
+ * The pause itself: let go of what the run holds, wait until the user has been idle `quietMs` (at most `maxPauseMs`,
+ * within the deadline), then check the world before going on: the window still exists, no new window of its app
+ * (a dialog) took the front, it is in front again (re-focused only now, when the user is idle), where it moved;
+ * finally press again what the run held. Returns the window move, if any.
+ */
+async function pauseHold(host, run, step, id) {
+    const t0 = host.now();
+    run.count++;
+    const n = run.count;
+    if (run.holds())
+        host.release();
+    host.overlay(true);
+    const granted = host.extend(host.maxPauseMs);
+    try {
+        const before = pauseWindows(await host.exec({ kind: "list_windows" }, `${id}~p${n}a`));
+        const wid = typeof step.windowId === "string" ? step.windowId : run.windowId;
+        const target = wid && (!before || before.some((w) => w.windowId === wid)) ? wid
+            : (before?.find((w) => w.focused && !w.minimized)?.windowId ?? wid ?? null);
+        for (;;) {
+            if (host.ended())
+                return pauseStop("stopped", "Stopped while paused.");
+            const now = host.now();
+            const quiet = now - host.lastInputAt();
+            if (quiet >= host.quietMs)
+                break;
+            if (now - t0 >= host.maxPauseMs)
+                return pauseStop("max_pause", `The user kept using the computer for more than ${Math.round(host.maxPauseMs / 1000)} s, so Melaya stopped instead of waiting longer.`);
+            if (host.timeLeft() <= PAUSE_DEFAULTS.reserveMs)
+                return pauseStop("deadline", "The time for this call ran out while Melaya waited for the user to finish.");
+            await host.sleep(Math.max(10, Math.min(100, host.quietMs - quiet + 5)));
+        }
+        run.interrupted = false;
+        if (host.ended())
+            return pauseStop("stopped", "Stopped while paused.");
+        let shift;
+        if (target) {
+            let after = pauseWindows(await host.exec({ kind: "list_windows" }, `${id}~p${n}b`));
+            let a = after?.find((w) => w.windowId === target);
+            if (after && !a)
+                return pauseStop("window_closed", "The window Melaya was working in was closed while it waited for the user.");
+            if (after && a) {
+                const f = after.find((w) => w.focused && !w.minimized);
+                if (f && f.windowId !== target && before && !before.some((w) => w.windowId === f.windowId) && (!f.appId || f.appId === a.appId)) {
+                    return pauseStop("dialog", `A new window of the app ("${String(f.title || "").slice(0, 60)}", a dialog?) opened while Melaya waited, so Melaya did not act on it.`);
+                }
+                if (a.minimized || !a.focused) {
+                    const fr = await host.exec({ kind: "focus_window", windowId: target }, `${id}~p${n}f`);
+                    if (!fr.ok || host.ended())
+                        return pauseStop("refocus", `The window could not be brought back to the front after the user switched away (${String(fr.error?.message || "focus refused").slice(0, 160)}).`);
+                    run.refocused++;
+                    if (a.minimized) {
+                        after = pauseWindows(await host.exec({ kind: "list_windows" }, `${id}~p${n}c`));
+                        a = after?.find((w) => w.windowId === target) ?? a;
+                    }
+                }
+                const b = before?.find((w) => w.windowId === target);
+                if (b && !b.minimized && !a.minimized && pauseRectMoved(b.bounds, a.bounds)) {
+                    shift = { windowId: target, from: b.bounds, to: a.bounds };
+                    const prev = run.shifts.get(target);
+                    run.shifts.set(target, { from: prev ? prev.from : b.bounds, to: a.bounds });
+                    run.moved = true;
+                }
+            }
+        }
+        // What the run held before the pause is pressed again; the pointer goes back by our own move, never assumed.
+        for (const key of run.keys.values()) {
+            const r = await host.exec({ kind: "hold_key", key, state: "down", observe: "none" }, `${id}~p${n}k`);
+            if (!r.ok || host.ended())
+                return pauseStop("repress", `Melaya could not press ${key} again after the pause.`);
+        }
+        for (const button of run.buttons) {
+            const at = run.pointer;
+            if (!at)
+                return pauseStop("repress", `Melaya let go of the ${button} mouse button for the user and does not know where to press it again.`);
+            let x = at.x, y = at.y;
+            if (shift) {
+                x += shift.to.x - shift.from.x;
+                y += shift.to.y - shift.from.y;
+            }
+            const r = await host.exec({ kind: "mouse", target: { x, y }, button, state: "down", observe: "none" }, `${id}~p${n}m`);
+            if (!r.ok || host.ended())
+                return pauseStop("repress", `Melaya could not press the ${button} mouse button again after the pause (${String(r.error?.message || "").slice(0, 160)}).`);
+        }
+        return shift ? { shift } : {};
+    }
+    finally {
+        const used = host.now() - t0;
+        run.pausedMs += used;
+        if (granted > used)
+            host.extend(-(granted - used));
+        if (!host.ended())
+            host.overlay(false);
+    }
+}
+/**
+ * One step that pauses for the user instead of failing. Before a step that sends input, it waits while the user is
+ * busy; a pointer stream the user interrupted goes on from where it was (a path from its last sample, a drag from
+ * its start if nothing was picked up, a move / hover / mouse step again). `start`: a path's resume position.
+ * Returns the step's result, or `stop` when the run cannot go on safely (the caller answers user_interrupted).
+ */
+export async function pauseRunStep(host, run, step, id, start) {
+    const kind = String(step.kind);
+    const isPath = kind === "path";
+    const adapted = run.adapt(step);
+    if (!adapted)
+        return pauseStop("moved", "The window moved while Melaya waited for the user, and this step uses screen coordinates (or a ref) of where it was.");
+    let orig = adapted;
+    let pos = isPath && start ? { stroke: start.stroke ?? 0, point: start.point ?? 0, frac: start.frac ?? 0 } : { stroke: 0, point: 0, frac: 0 };
+    const done = () => ({ ok: true, kind, text: "Nothing was left to draw: the path had reached its end.", elapsedMs: 0 });
+    const first = isPath ? pauseTrimPath(orig, pos) : orig;
+    if (!first)
+        return { result: done() };
+    let attempt = first;
+    let tries = 0;
+    let afterPause = false;
+    for (;;) {
+        if (host.ended())
+            return { result: { ok: false, kind, error: { code: "stopped", message: "Stopped." }, elapsedMs: 0 } };
+        if (pauseNeedsIdle(kind) && (run.interrupted || host.now() - host.lastInputAt() < host.quietMs)) {
+            const h = await pauseHold(host, run, orig, id);
+            if ("stop" in h)
+                return { stop: { ...h.stop, ...(isPath ? { at: pos } : {}) } };
+            afterPause = true;
+            if (h.shift) {
+                const moved = pauseShiftStep(orig, isPath && pauseIsRect(orig.windowRect) ? orig.windowRect : h.shift.from, h.shift.to);
+                if (!moved) {
+                    return pauseStop("moved", pauseRectResized(h.shift.from, h.shift.to)
+                        ? "The window was resized while Melaya waited for the user, so the coordinates planned for its old size would land elsewhere."
+                        : "The window moved while Melaya waited for the user, and this step uses screen coordinates (or a ref) of where it was.", isPath ? pos : undefined);
+                }
+                orig = moved;
+            }
+            const again = isPath ? pauseTrimPath(orig, pos) : orig;
+            if (!again)
+                return { result: done() };
+            attempt = again;
+            // The user may have come back while the window was checked: look again before sending anything.
+            continue;
+        }
+        const hid = tries === 0 ? id : `${id}~r${tries}`;
+        run.current = { id: hid, kind: String(attempt.kind) };
+        const r = await host.exec(attempt, hid);
+        run.current = null;
+        const cancelled = run.cancelled.delete(hid);
+        if (host.ended())
+            return { result: r };
+        const code = r.ok ? "" : String(r.error?.code ?? "");
+        // The helper's own check (Linux: real input within 1.5 s) refused before sending anything.
+        const refused = code === "user_interrupted";
+        if (r.ok || (!cancelled && !refused)) {
+            if (!r.ok && afterPause && (code === "frame_stale" || code === "stale_ref")) {
+                const t = (attempt.target ?? attempt.from);
+                if (attempt.snapshotId !== undefined && t && typeof t === "object" && typeof t.label === "string" && tries < PAUSE_DEFAULTS.maxResumesPerStep) {
+                    const relabel = { ...attempt };
+                    delete relabel.snapshotId;
+                    attempt = relabel;
+                    if (!isPath)
+                        orig = relabel;
+                    tries++;
+                    continue;
+                }
+                return pauseStop("stale", "The window changed while Melaya waited for the user, and this step targets an element of the screen read before the pause.", isPath ? pos : undefined);
+            }
+            if (r.ok)
+                run.track(attempt, r);
+            return { result: r };
+        }
+        if (refused)
+            host.markInput();
+        run.interrupted = true;
+        tries++;
+        if (tries > PAUSE_DEFAULTS.maxResumesPerStep)
+            return pauseStop("too_many", "The user took over this step too many times in a row.", isPath ? pos : undefined);
+        if (refused)
+            continue; // nothing was sent: the same attempt runs after the pause
+        if (isPath) {
+            const prog = r.progress;
+            if (!prog || typeof prog !== "object")
+                return pauseStop("unknown_progress", "A stroke was interrupted and this computer's helper cannot tell how far it got (it may be partly drawn).", pos);
+            if (orig.gesture === "drag") {
+                if (prog.pressed || pauseNum(prog.stroke) > 0)
+                    return pauseStop("dropped", "The drag was interrupted after it had picked the item up; letting go for the user dropped it where the pointer was.", { stroke: 0, point: 0, frac: 0 });
+                continue; // nothing picked up yet: the whole gesture again
+            }
+            pos = pauseAbsolute(pos, prog);
+            const rest = pauseTrimPath(orig, pos);
+            if (!rest)
+                return { result: done() };
+            attempt = rest;
+            if (prog.pressed)
+                run.resumedStrokes++;
+            continue;
+        }
+        if (kind === "drag") {
+            const prog = r.progress;
+            if (!prog || prog.pressed)
+                return pauseStop("dropped", "The drag was interrupted after it had picked the item up; letting go for the user dropped it where the pointer was.");
+            continue;
+        }
+        // move, hover, mouse: sending them again is the same input (the button the run held is pressed again first).
+    }
+}
+// END COMPUTER PAUSE ENGINE

package/dist/computerRelay.js

@@ -36,6 +36,8 @@ export const COMPUTER_EVENTS = {
 export const UNSUPPORTED_MESSAGE = "Computer control needs the Melaya desktop app on this computer.";
 const MIN_DEADLINE_MS = 1_000;
 const MAX_DEADLINE_MS = 31 * 60_000;
+/** Most pause time (user at the keyboard) one command may add to its deadline (contract COMPUTER_PAUSE.budgetMs, with room). */
+const MAX_PAUSE_BUDGET_MS = 300_000;
 const MAX_PENDING = 64;
 // The CLI host module is optional (it may be absent from a build): load it by
 // a variable specifier so this file compiles and runs without it.
@@ -173,14 +175,19 @@ export function attachComputerRelay(socket, opts = {}) {
         const deadlineMs = Math.min(MAX_DEADLINE_MS, Math.max(MIN_DEADLINE_MS, Math.floor(Number(p.deadlineMs) || 15_000)));
         const allowedAppIds = Array.isArray(p.allowedAppIds) ? p.allowedAppIds.filter((x) => typeof x === "string") : [];
         const allowedApps = Array.isArray(p.allowedApps) ? p.allowedApps : undefined;
+        // Pause and resume (2026-10-23): time the executor may spend paused for the user on top of the deadline
+        // (sent only to executors that report pauseResume; the server waits that much longer too).
+        const budget = Math.floor(Number(p.pauseBudgetMs));
+        const pauseBudgetMs = Number.isFinite(budget) && budget > 0 ? Math.min(MAX_PAUSE_BUDGET_MS, budget) : 0;
         const msg = {
             type: "computer.command", id, action, deadlineMs, allowedAppIds,
             ...(allowedApps ? { allowedApps } : {}),
+            ...(pauseBudgetMs ? { pauseBudgetMs } : {}),
         };
         const startedAt = Date.now();
         const timer = setTimeout(() => {
             settle(id, errorResult(kind, "timeout", "The computer did not finish before the deadline. Read the screen before retrying: the action may or may not have happened.", Date.now() - startedAt));
-        }, deadlineMs);
+        }, deadlineMs + pauseBudgetMs);
         pending.set(id, { ack, kind, startedAt, timer });
         if (hosted) {
             log(`  [computer] ${kind} -> desktop app`);

package/dist/hostChannel.d.ts

@@ -53,6 +53,7 @@ export type RunnerToHostMessage = {
         tier: "view" | "click" | "full";
         expiresAt?: string;
     }>;
+    pauseBudgetMs?: number;
 } | {
     type: "computer.stop";
     reason: string;

package/package.json

@@ -1,50 +1,50 @@
-{
-  "name": "@melaya/runner",
-  "version": "1.1.74",
-  "description": "Run Melaya AI pipelines locally with your own LM Studio or Ollama models",
-  "license": "Apache-2.0",
-  "author": "Melaya Labs LLC",
-  "private": false,
-  "type": "module",
-  "bin": {
-    "melaya-runner": "dist/cli.js"
-  },
-  "main": "dist/index.js",
-  "files": [
-    "dist/**/*.js",
-    "dist/**/*.d.ts",
-    "dist/**/*.py",
-    "localRagIngest.py",
-    "localRagRetrieve.py",
-    "localDbProbe.py",
-    "localBacklinkFetch.py",
-    "localVault.py",
-    "localVaultMirror.py",
-    "nltk_data/**",
-    "README.md",
-    "LICENSE"
-  ],
-  "scripts": {
-    "build": "tsc && node -e \"const fs=require('fs'); fs.copyFileSync('localRagIngest.py','dist/localRagIngest.py'); fs.copyFileSync('localRagRetrieve.py','dist/localRagRetrieve.py'); fs.copyFileSync('localDbProbe.py','dist/localDbProbe.py'); fs.copyFileSync('localBacklinkFetch.py','dist/localBacklinkFetch.py'); fs.copyFileSync('localVault.py','dist/localVault.py'); fs.copyFileSync('localVaultMirror.py','dist/localVaultMirror.py'); fs.copyFileSync('src/assistantHost.py','dist/assistantHost.py')\"",
-    "test": "node --test --import tsx \"src/**/*.test.ts\"",
-    "prepublishOnly": "npm run build"
-  },
-  "dependencies": {
-    "chalk": "^5.3.0",
-    "commander": "^12.0.0",
-    "ora": "^8.0.0",
-    "playwright": "^1.48.0",
-    "socket.io-client": "^4.8.0"
-  },
-  "devDependencies": {
-    "@types/node": "^20.0.0",
-    "tsx": "^4.19.2",
-    "typescript": "^5.5.0"
-  },
-  "engines": {
-    "node": ">=18"
-  },
-  "publishConfig": {
-    "access": "public"
-  }
-}
+{
+  "name": "@melaya/runner",
+  "version": "1.1.76",
+  "description": "Run Melaya AI pipelines locally with your own LM Studio or Ollama models",
+  "license": "Apache-2.0",
+  "author": "Melaya Labs LLC",
+  "private": false,
+  "type": "module",
+  "bin": {
+    "melaya-runner": "dist/cli.js"
+  },
+  "main": "dist/index.js",
+  "files": [
+    "dist/**/*.js",
+    "dist/**/*.d.ts",
+    "dist/**/*.py",
+    "localRagIngest.py",
+    "localRagRetrieve.py",
+    "localDbProbe.py",
+    "localBacklinkFetch.py",
+    "localVault.py",
+    "localVaultMirror.py",
+    "nltk_data/**",
+    "README.md",
+    "LICENSE"
+  ],
+  "scripts": {
+    "build": "tsc && node -e \"const fs=require('fs'); fs.copyFileSync('localRagIngest.py','dist/localRagIngest.py'); fs.copyFileSync('localRagRetrieve.py','dist/localRagRetrieve.py'); fs.copyFileSync('localDbProbe.py','dist/localDbProbe.py'); fs.copyFileSync('localBacklinkFetch.py','dist/localBacklinkFetch.py'); fs.copyFileSync('localVault.py','dist/localVault.py'); fs.copyFileSync('localVaultMirror.py','dist/localVaultMirror.py'); fs.copyFileSync('src/assistantHost.py','dist/assistantHost.py')\"",
+    "test": "node --test --import tsx \"src/**/*.test.ts\"",
+    "prepublishOnly": "npm run build"
+  },
+  "dependencies": {
+    "chalk": "^5.3.0",
+    "commander": "^12.0.0",
+    "ora": "^8.0.0",
+    "playwright": "^1.48.0",
+    "socket.io-client": "^4.8.0"
+  },
+  "devDependencies": {
+    "@types/node": "^20.0.0",
+    "tsx": "^4.19.2",
+    "typescript": "^5.5.0"
+  },
+  "engines": {
+    "node": ">=18"
+  },
+  "publishConfig": {
+    "access": "public"
+  }
+}