libre-webui 0.26.0 → 0.28.0

package/backend/dist/services/workRuntimeService.js

@@ -31,10 +31,286 @@ import { WorkRuntimeError, workRuntimeConfig as config, } from './workRuntimeSha
 // The public surface of the Work runtime is unchanged by the driver split:
 // consumers and tests keep importing everything from this module.
 export { WORK_RUNTIME_ADMISSION_DEFAULTS, WORK_RUNTIME_DEFAULTS, WorkRuntimeError, parseDnsServers, } from './workRuntimeShared.js';
-export { DockerWorkRuntimeDriver, buildWorkContainerRunArgs, describeDockerUnavailable, formatPreviewHost, parseManagedContainerList, parsePublishedPort, } from './workRuntimeDriver.js';
+export { DockerWorkRuntimeDriver, buildWorkContainerRunArgs, describeDockerUnavailable, formatPreviewHost, parseManagedContainerList, parsePublishedPort, resolvePublishedEndpointHost, } from './workRuntimeDriver.js';
 const logger = createLogger('services:work-runtime');
 const PREVIEW_READY_TIMEOUT_MS = 15000;
 const PREVIEW_POLL_INTERVAL_MS = 250;
+/** Most actions a single computer_act batch may carry (rakazo-scale). */
+export const WORK_COMPUTER_ACTION_LIMIT = 24;
+const WORK_COMPUTER_TEXT_LIMIT = 4000;
+const WORK_COMPUTER_WAIT_LIMIT_MS = 5000;
+const WORK_COMPUTER_WAIT_TOTAL_LIMIT_MS = 30000;
+const WORK_COMPUTER_COORDINATE_LIMIT = 10000;
+const WORK_COMPUTER_FOCUS_LIMIT = 200;
+const WORK_COMPUTER_EXPECT_TEXT_LIMIT = 300;
+const WORK_COMPUTER_EXPECT_WAIT_LIMIT_MS = 15000;
+/** xdotool key syntax: chords like ctrl+shift+t, keysyms like Return. */
+const WORK_COMPUTER_KEYS_PATTERN = /^[A-Za-z0-9_]+(\+[A-Za-z0-9_]+)*$/;
+/**
+ * Validate a computer_act batch before anything reaches the sandbox. The
+ * output is plain data safe to JSON-encode into the in-container action
+ * interpreter; every rejected batch names the exact offending action.
+ */
+export function validateWorkComputerActions(actions) {
+    if (!Array.isArray(actions) || actions.length === 0) {
+        throw new WorkRuntimeError('computer_act requires a non-empty "actions" array.', 400, 'WORK_COMPUTER_INVALID_ACTION');
+    }
+    if (actions.length > WORK_COMPUTER_ACTION_LIMIT) {
+        throw new WorkRuntimeError(`computer_act accepts at most ${WORK_COMPUTER_ACTION_LIMIT} actions per call.`, 400, 'WORK_COMPUTER_INVALID_ACTION');
+    }
+    const invalid = (index, reason) => new WorkRuntimeError(`computer_act action ${index + 1} is invalid: ${reason}`, 400, 'WORK_COMPUTER_INVALID_ACTION');
+    const coordinate = (value, index, name) => {
+        if (typeof value !== 'number' ||
+            !Number.isInteger(value) ||
+            value < 0 ||
+            value > WORK_COMPUTER_COORDINATE_LIMIT) {
+            throw invalid(index, `"${name}" must be an integer between 0 and ${WORK_COMPUTER_COORDINATE_LIMIT}.`);
+        }
+        return value;
+    };
+    const focusAssertion = (action, index) => {
+        if (action.focus === undefined)
+            return {};
+        if (typeof action.focus !== 'string' ||
+            action.focus.trim().length === 0 ||
+            action.focus.length > WORK_COMPUTER_FOCUS_LIMIT) {
+            throw invalid(index, `"focus" must be a string of 1 to ${WORK_COMPUTER_FOCUS_LIMIT} characters.`);
+        }
+        return { focus: action.focus.trim() };
+    };
+    let totalWaitMs = 0;
+    const validated = [];
+    for (const [index, value] of actions.entries()) {
+        const action = value && typeof value === 'object' && !Array.isArray(value)
+            ? value
+            : undefined;
+        if (!action || typeof action.type !== 'string') {
+            throw invalid(index, 'each action must be an object with a "type".');
+        }
+        switch (action.type) {
+            case 'move':
+                validated.push({
+                    type: 'move',
+                    x: coordinate(action.x, index, 'x'),
+                    y: coordinate(action.y, index, 'y'),
+                });
+                break;
+            case 'click':
+            case 'double_click':
+            case 'right_click': {
+                const hasX = action.x !== undefined;
+                const hasY = action.y !== undefined;
+                if (hasX !== hasY) {
+                    throw invalid(index, 'provide both "x" and "y" or neither.');
+                }
+                validated.push({
+                    type: action.type,
+                    ...(hasX
+                        ? {
+                            x: coordinate(action.x, index, 'x'),
+                            y: coordinate(action.y, index, 'y'),
+                        }
+                        : {}),
+                });
+                break;
+            }
+            case 'type': {
+                if (typeof action.text !== 'string' ||
+                    action.text.length === 0 ||
+                    action.text.length > WORK_COMPUTER_TEXT_LIMIT) {
+                    throw invalid(index, `"text" must be a string of 1 to ${WORK_COMPUTER_TEXT_LIMIT} characters.`);
+                }
+                validated.push({
+                    type: 'type',
+                    text: action.text,
+                    ...focusAssertion(action, index),
+                });
+                break;
+            }
+            case 'key': {
+                if (typeof action.keys !== 'string' ||
+                    !WORK_COMPUTER_KEYS_PATTERN.test(action.keys) ||
+                    action.keys.length > 64) {
+                    throw invalid(index, '"keys" must be an xdotool key name or chord such as "Return" or "ctrl+l".');
+                }
+                validated.push({
+                    type: 'key',
+                    keys: action.keys,
+                    ...focusAssertion(action, index),
+                });
+                break;
+            }
+            case 'scroll': {
+                if (action.direction !== 'up' && action.direction !== 'down') {
+                    throw invalid(index, '"direction" must be "up" or "down".');
+                }
+                const amount = action.amount ?? 3;
+                if (typeof amount !== 'number' ||
+                    !Number.isInteger(amount) ||
+                    amount < 1 ||
+                    amount > 20) {
+                    throw invalid(index, '"amount" must be an integer between 1 and 20.');
+                }
+                const hasX = action.x !== undefined;
+                const hasY = action.y !== undefined;
+                if (hasX !== hasY) {
+                    throw invalid(index, 'provide both "x" and "y" or neither.');
+                }
+                validated.push({
+                    type: 'scroll',
+                    direction: action.direction,
+                    amount,
+                    ...(hasX
+                        ? {
+                            x: coordinate(action.x, index, 'x'),
+                            y: coordinate(action.y, index, 'y'),
+                        }
+                        : {}),
+                });
+                break;
+            }
+            case 'scroll_until': {
+                if (action.direction !== 'up' && action.direction !== 'down') {
+                    throw invalid(index, '"direction" must be "up" or "down".');
+                }
+                const target = action.target &&
+                    typeof action.target === 'object' &&
+                    !Array.isArray(action.target)
+                    ? action.target
+                    : undefined;
+                const hasText = target?.text !== undefined;
+                const hasEdge = target?.edge !== undefined;
+                if (!target || hasText === hasEdge) {
+                    throw invalid(index, '"target" must be an object with exactly one of "text" or "edge".');
+                }
+                let validatedTarget;
+                if (hasText) {
+                    if (typeof target.text !== 'string' ||
+                        target.text.trim().length === 0 ||
+                        target.text.length > 200) {
+                        throw invalid(index, '"target.text" must be a string of 1 to 200 characters.');
+                    }
+                    validatedTarget = { text: target.text.trim() };
+                }
+                else {
+                    if (target.edge !== 'top' && target.edge !== 'bottom') {
+                        throw invalid(index, '"target.edge" must be "top" or "bottom".');
+                    }
+                    validatedTarget = { edge: target.edge };
+                }
+                if (action.maxAmount !== undefined) {
+                    if (typeof action.maxAmount !== 'number' ||
+                        !Number.isInteger(action.maxAmount) ||
+                        action.maxAmount < 1 ||
+                        action.maxAmount > 30) {
+                        throw invalid(index, '"maxAmount" must be an integer between 1 and 30.');
+                    }
+                }
+                const hasX = action.x !== undefined;
+                const hasY = action.y !== undefined;
+                if (hasX !== hasY) {
+                    throw invalid(index, 'provide both "x" and "y" or neither.');
+                }
+                validated.push({
+                    type: 'scroll_until',
+                    direction: action.direction,
+                    target: validatedTarget,
+                    ...(action.maxAmount !== undefined
+                        ? { maxAmount: action.maxAmount }
+                        : {}),
+                    ...(hasX
+                        ? {
+                            x: coordinate(action.x, index, 'x'),
+                            y: coordinate(action.y, index, 'y'),
+                        }
+                        : {}),
+                });
+                break;
+            }
+            case 'wait': {
+                if (typeof action.ms !== 'number' ||
+                    !Number.isInteger(action.ms) ||
+                    action.ms < 1 ||
+                    action.ms > WORK_COMPUTER_WAIT_LIMIT_MS) {
+                    throw invalid(index, `"ms" must be an integer between 1 and ${WORK_COMPUTER_WAIT_LIMIT_MS}.`);
+                }
+                totalWaitMs += action.ms;
+                if (totalWaitMs > WORK_COMPUTER_WAIT_TOTAL_LIMIT_MS) {
+                    throw invalid(index, `total wait time per call is limited to ${WORK_COMPUTER_WAIT_TOTAL_LIMIT_MS} ms.`);
+                }
+                validated.push({ type: 'wait', ms: action.ms });
+                break;
+            }
+            default:
+                throw invalid(index, `unknown action type "${action.type}".`);
+        }
+    }
+    return validated;
+}
+/**
+ * Validate a computer_act "expect" declaration: the outcome the batch is
+ * supposed to produce, evaluated by the runtime after the actions settle so
+ * "input delivered" cannot be mistaken for "task succeeded".
+ */
+export function validateWorkComputerExpectation(value) {
+    if (value === undefined || value === null)
+        return undefined;
+    const invalid = (reason) => new WorkRuntimeError(`computer_act "expect" is invalid: ${reason}`, 400, 'WORK_COMPUTER_INVALID_ACTION');
+    if (typeof value !== 'object' || Array.isArray(value)) {
+        throw invalid('it must be an object.');
+    }
+    const raw = value;
+    const expectation = {};
+    for (const key of ['titleContains', 'urlContains']) {
+        if (raw[key] === undefined)
+            continue;
+        if (typeof raw[key] !== 'string' ||
+            raw[key].trim().length === 0 ||
+            raw[key].length > WORK_COMPUTER_EXPECT_TEXT_LIMIT) {
+            throw invalid(`"${key}" must be a string of 1 to ${WORK_COMPUTER_EXPECT_TEXT_LIMIT} characters.`);
+        }
+        expectation[key] = raw[key].trim();
+    }
+    if (raw.regionChanged !== undefined) {
+        const region = raw.regionChanged &&
+            typeof raw.regionChanged === 'object' &&
+            !Array.isArray(raw.regionChanged)
+            ? raw.regionChanged
+            : undefined;
+        const bounded = (field, name, minimum) => {
+            if (typeof field !== 'number' ||
+                !Number.isInteger(field) ||
+                field < minimum ||
+                field > WORK_COMPUTER_COORDINATE_LIMIT) {
+                throw invalid(`"regionChanged.${name}" must be an integer between ${minimum} and ${WORK_COMPUTER_COORDINATE_LIMIT}.`);
+            }
+            return field;
+        };
+        if (!region)
+            throw invalid('"regionChanged" must be an object.');
+        expectation.regionChanged = {
+            x: bounded(region.x, 'x', 0),
+            y: bounded(region.y, 'y', 0),
+            width: bounded(region.width, 'width', 1),
+            height: bounded(region.height, 'height', 1),
+        };
+    }
+    if (raw.withinMs !== undefined) {
+        if (typeof raw.withinMs !== 'number' ||
+            !Number.isInteger(raw.withinMs) ||
+            raw.withinMs < 1 ||
+            raw.withinMs > WORK_COMPUTER_EXPECT_WAIT_LIMIT_MS) {
+            throw invalid(`"withinMs" must be an integer between 1 and ${WORK_COMPUTER_EXPECT_WAIT_LIMIT_MS}.`);
+        }
+        expectation.withinMs = raw.withinMs;
+    }
+    if (expectation.titleContains === undefined &&
+        expectation.urlContains === undefined &&
+        expectation.regionChanged === undefined) {
+        throw invalid('declare at least one of "titleContains", "urlContains", or "regionChanged".');
+    }
+    return expectation;
+}
 /** How long a run waits for the shared runtime lease before conflicting. */
 const runLeaseWaitMs = () => {
     const parsed = Number.parseInt(process.env.WORK_RUN_LEASE_WAIT_MS ?? '', 10);
@@ -85,6 +361,12 @@ export class WorkRuntimeService {
         this.runtimeLeases = new Map();
         this.previewLeaseReleases = new Map();
         this.terminalHolds = new Map();
+        this.screenHolds = new Map();
+        // Cross-replica mirror of screenHolds: presence members that tell another
+        // replica's teardown (a run ending on the durable worker) that a viewer
+        // here still owns the container.
+        this.viewerPresenceCounts = new Map();
+        this.viewerPresenceTimers = new Map();
         this.recoveryTasks = new Map();
         this.recoveryOrphans = new Map();
         // Sweeps left for the empty-inventory case before giving up on a runtime
@@ -394,6 +676,90 @@ export class WorkRuntimeService {
     terminalSessionCount(taskId) {
         return this.terminalHolds.get(taskId) ?? 0;
     }
+    /**
+     * A connected Screen viewer owns the running container the way an
+     * attached terminal does: while someone watches the Work Computer,
+     * workspace-helper teardown and run-end cleanup must not stop the
+     * sandbox out from under the GUI session. Callers hold the returned
+     * release for the lifetime of the viewer connection.
+     */
+    async beginScreenSession(task) {
+        // Deliberately NOT the runtime lease: in team mode the task's run holds
+        // that lease on the durable worker for its whole duration, and a viewer
+        // must neither fail against it nor block the next run by holding it.
+        // Local holds stop this process's teardown; the presence member stops
+        // every other replica's.
+        await this.assertTaskIsActive(task);
+        const releasePresence = await this.acquireViewerPresence(task.id);
+        this.screenHolds.set(task.id, (this.screenHolds.get(task.id) ?? 0) + 1);
+        let released = false;
+        return async () => {
+            if (released)
+                return;
+            released = true;
+            this.noteTaskActivity(task.id);
+            const remaining = (this.screenHolds.get(task.id) ?? 1) - 1;
+            if (remaining <= 0) {
+                this.screenHolds.delete(task.id);
+            }
+            else {
+                this.screenHolds.set(task.id, remaining);
+            }
+            releasePresence();
+            try {
+                if (remaining <= 0 && !this.shuttingDown) {
+                    await this.withLifecycleLock(task.id, (_assertHeld, signal) => this.stopContainerIfIdleWithLock(task, signal));
+                }
+            }
+            catch (error) {
+                logger.warn(`Could not idle Work container ${task.containerName} after a screen session:`, error);
+            }
+        };
+    }
+    /**
+     * Register this process as an active viewer of the task in the shared
+     * presence scope, refreshed for as long as at least one viewer remains.
+     * Solo mode needs no cross-replica signal and returns a no-op.
+     */
+    async acquireViewerPresence(taskId) {
+        if (getPlatformRuntimeConfig().mode !== 'team') {
+            return () => undefined;
+        }
+        const member = `${this.activityMemberId}:viewer`;
+        const refresh = () => withCoordinationTimeout(getCoordinator().setPresence(`work-task-active:${taskId}`, member, 30000), SHARED_COORDINATION_OPERATION_TIMEOUT_MS);
+        await refresh();
+        const count = this.viewerPresenceCounts.get(taskId) ?? 0;
+        if (count === 0) {
+            const timer = setInterval(() => {
+                void refresh().catch(error => logger.warn(`Could not refresh Work viewer presence for ${taskId}:`, error));
+            }, 10000);
+            timer.unref?.();
+            this.viewerPresenceTimers.set(taskId, timer);
+        }
+        this.viewerPresenceCounts.set(taskId, count + 1);
+        let released = false;
+        return () => {
+            if (released)
+                return;
+            released = true;
+            const remaining = (this.viewerPresenceCounts.get(taskId) ?? 1) - 1;
+            if (remaining > 0) {
+                this.viewerPresenceCounts.set(taskId, remaining);
+                return;
+            }
+            this.viewerPresenceCounts.delete(taskId);
+            const timer = this.viewerPresenceTimers.get(taskId);
+            if (timer)
+                clearInterval(timer);
+            this.viewerPresenceTimers.delete(taskId);
+            void getCoordinator()
+                .clearPresence(`work-task-active:${taskId}`, member)
+                .catch(error => logger.warn(`Could not clear Work viewer presence for ${taskId}:`, error));
+        };
+    }
+    screenSessionCount(taskId) {
+        return this.screenHolds.get(taskId) ?? 0;
+    }
     beginShutdown() {
         this.shuttingDown = true;
         if (this.recoveryTimer) {
@@ -574,6 +940,7 @@ export class WorkRuntimeService {
             }
             const busy = this.activeCommands.has(task.id) ||
                 (this.terminalHolds.get(task.id) ?? 0) > 0 ||
+                (this.screenHolds.get(task.id) ?? 0) > 0 ||
                 (this.runtimeLeases.has(task.id) &&
                     !this.previewLeaseReleases.has(task.id));
             const sharedActivity = getPlatformRuntimeConfig().mode === 'team'
@@ -864,26 +1231,60 @@ export class WorkRuntimeService {
             releaseLease();
         }
     }
-    async stopContainerIfIdleWithLock(task, signal) {
-        if (this.activeCommands.has(task.id))
-            return;
+    /** Returns true when the container was actually stopped. */
+    async stopContainerIfIdleWithLock(task, signal, options = {}) {
+        if (!options.ignoreActiveCommands && this.activeCommands.has(task.id)) {
+            return false;
+        }
         // An attached terminal session owns the running container exactly like a
         // ready preview does.
         if ((this.terminalHolds.get(task.id) ?? 0) > 0)
-            return;
+            return false;
+        // So does a watched Work Computer screen: without this, every Files
+        // refresh would destroy the GUI session mid-view.
+        if ((this.screenHolds.get(task.id) ?? 0) > 0)
+            return false;
+        // Holds on other replicas are only visible through the presence scope:
+        // a screen viewer on the app process must survive the durable worker's
+        // run-end teardown, and a run on the worker must survive an app-side
+        // helper's teardown. Own members are excluded — this process's holds
+        // were checked directly above, and a run's own presence must not block
+        // its own cleanup. When coordination is unreachable, keep the container;
+        // the idle sweep is the backstop.
+        if (getPlatformRuntimeConfig().mode === 'team') {
+            try {
+                const members = await withCoordinationTimeout(getCoordinator().listPresence(`work-task-active:${task.id}`), SHARED_COORDINATION_OPERATION_TIMEOUT_MS);
+                if (members.some(member => !member.startsWith(this.activityMemberId))) {
+                    return false;
+                }
+            }
+            catch (error) {
+                logger.warn(`Could not check cross-replica activity before idling Work container ${task.containerName}; keeping it:`, error);
+                return false;
+            }
+        }
         try {
             if ((await this.previewProcessCheckWithLock(task, signal)) === 'ready' &&
                 this.previewLeaseReleases.has(task.id)) {
-                return;
+                return false;
             }
         }
         catch (error) {
             logger.warn(`Could not verify preview state before idling Work container ${task.containerName}; stopping it:`, error);
         }
+        // The preview probe above awaits a container exec; a terminal or screen
+        // hold can land during that window. Re-check synchronously so a viewer
+        // who just attached does not lose the session to a stale decision.
+        if ((!options.ignoreActiveCommands && this.activeCommands.has(task.id)) ||
+            (this.terminalHolds.get(task.id) ?? 0) > 0 ||
+            (this.screenHolds.get(task.id) ?? 0) > 0) {
+            return false;
+        }
         await this.stopContainerWithLock(task, signal);
         this.releasePreviewLease(task.id);
         await this.markPreviewStopped(task.id);
         this.completeRecoveryTask(task.id);
+        return true;
     }
     async readFile(task, requestedPath) {
         const workspacePath = validateWorkspacePath(requestedPath, false);
@@ -1158,9 +1559,11 @@ export class WorkRuntimeService {
                     if (commandRegistered) {
                         // Keep the distributed lifecycle fence through teardown. A
                         // second replica must never stop or recreate this sandbox in
-                        // the gap between preparation and Docker exec.
-                        await this.stopContainerWithLock(task, signal);
-                        containerStopped = true;
+                        // the gap between preparation and Docker exec. The managed
+                        // command script already reaped the command's process group,
+                        // so a container held by a screen viewer, terminal, or ready
+                        // preview may keep running.
+                        containerStopped = await this.stopContainerIfIdleWithLock(task, signal, { ignoreActiveCommands: true });
                     }
                 }
             });
@@ -1179,6 +1582,284 @@ export class WorkRuntimeService {
             }
         }
     }
+    /**
+     * Start (or confirm) the Work Computer GUI session in a task's sandbox:
+     * virtual display, window manager, browser, and the localhost-only
+     * VNC-to-WebSocket bridge. Idempotent — the in-container script exits 0
+     * when a session is already running. Requires a policy with the GUI
+     * enabled and a networked task (the screen is reached over the published
+     * loopback port, and a computer without network is not useful anyway).
+     */
+    async startComputer(task) {
+        await this.withComputerSession(task, async () => undefined);
+    }
+    /**
+     * The teach recorder's anchor probe: which interactive element sits under
+     * a screen coordinate right now, plus the page URL. Read-only, leaseless,
+     * and best-effort — a missing anchor degrades a demonstration to bare
+     * coordinates, never fails the recording.
+     */
+    async computerAnchorAt(task, x, y) {
+        if (!(await this.computerToolsAvailable(task)))
+            return {};
+        if ((await this.driver.runtimeState(task)) !== 'running')
+            return {};
+        const result = await this.driver.exec(task, ['node', '-e', COMPUTER_ANCHOR_SCRIPT, '--', String(x), String(y)], { timeoutMs: 8000, maxOutputChars: 10000, acceptFailure: true });
+        if (result.exitCode !== 0)
+            return {};
+        try {
+            const parsed = JSON.parse(result.stdout.trim() || '{}');
+            return {
+                ...(typeof parsed.anchor === 'string' && parsed.anchor
+                    ? { anchor: parsed.anchor.slice(0, 200) }
+                    : {}),
+                ...(typeof parsed.url === 'string' && parsed.url
+                    ? { url: parsed.url.slice(0, 300) }
+                    : {}),
+            };
+        }
+        catch {
+            return {};
+        }
+    }
+    /** Whether this task may use the agent computer tools. */
+    async computerToolsAvailable(task) {
+        return (task.networkEnabled &&
+            (await workPolicyService.resolve(task.policyId)).guiEnabled === true);
+    }
+    /**
+     * The session's VNC passwords, generated in-container at session start.
+     * `view` goes to every authorized watcher; `control` goes only to the
+     * current takeover-lease holder — the VNC server itself keeps everyone
+     * else's input inert. Undefined on a pre-takeover GUI image (no passwd
+     * file), where the session is view-only for everyone.
+     */
+    async computerCredentials(task) {
+        return this.withComputerSession(task, async (signal) => {
+            const result = await this.driver.exec(task, [
+                '/bin/sh',
+                '-c',
+                'cat "${LIBRE_COMPUTER_STATE_DIR:-/tmp/libre-computer}/passwd"',
+            ], {
+                timeoutMs: 10000,
+                maxOutputChars: 10000,
+                acceptFailure: true,
+                abortSignal: signal,
+            });
+            if (result.exitCode !== 0)
+                return undefined;
+            const lines = result.stdout
+                .split('\n')
+                .map(line => line.trim())
+                .filter(Boolean);
+            const marker = lines.indexOf('__BEGIN_VIEWONLY__');
+            const control = lines[0];
+            const view = marker > 0 ? lines[marker + 1] : undefined;
+            if (!control || control === '__BEGIN_VIEWONLY__' || !view) {
+                return undefined;
+            }
+            return { control, view };
+        });
+    }
+    /**
+     * The agent's eyes: current screenshot plus cursor and window state from
+     * the task's Work Computer session. Starts the session when needed.
+     */
+    async computerObserve(task) {
+        return this.withComputerSession(task, signal => this.runComputerScript(task, COMPUTER_OBSERVE_SCRIPT, [], 30000, signal));
+    }
+    /**
+     * The agent's hands: a validated action batch executed with xdotool, then
+     * a settle-and-observe so the caller sees the resulting screen in the same
+     * round trip.
+     */
+    async computerAct(task, actions, expect) {
+        const validated = validateWorkComputerActions(actions);
+        const expectation = validateWorkComputerExpectation(expect);
+        // Waits, slow synthetic typing, and expectation polling all extend the
+        // exec deadline; the batch must never be killed mid-gesture by a fixed
+        // timeout.
+        const extraBudgetMs = validated.reduce((total, action) => total +
+            (action.type === 'wait' ? action.ms : 0) +
+            (action.type === 'type' ? action.text.length * 15 : 0) +
+            (action.type === 'scroll_until' ? (action.maxAmount ?? 15) * 400 : 0), 0) +
+            (expectation ? (expectation.withinMs ?? 5000) : 0) +
+            // Adaptive settle polling and per-click receipt captures.
+            5000;
+        return this.withComputerSession(task, signal => this.runComputerScript(task, COMPUTER_ACT_SCRIPT, [JSON.stringify(validated), JSON.stringify(expectation ?? null)], 60000 + extraBudgetMs, signal));
+    }
+    async runComputerScript(task, script, args, timeoutMs, signal) {
+        const result = await this.driver.exec(task, ['node', '-e', script, '--', ...args], {
+            timeoutMs,
+            maxOutputChars: 4000000,
+            acceptFailure: true,
+            abortSignal: signal,
+        });
+        if (result.exitCode !== 0) {
+            throw new WorkRuntimeError(`The Work Computer action failed: ${(result.stderr ||
+                result.stdout ||
+                'unknown error')
+                .trim()
+                .slice(0, 300)}`, 500, 'WORK_COMPUTER_ACTION_FAILED');
+        }
+        const parsed = parseJsonOutput(result.stdout);
+        if (typeof parsed.width !== 'number' ||
+            typeof parsed.height !== 'number' ||
+            typeof parsed.cursorX !== 'number' ||
+            typeof parsed.cursorY !== 'number' ||
+            typeof parsed.image !== 'string' ||
+            parsed.image.length === 0) {
+            throw new WorkRuntimeError('The Work Computer returned an invalid observation.', 500, 'WORK_COMPUTER_ACTION_FAILED');
+        }
+        const asRecord = (value) => value && typeof value === 'object' && !Array.isArray(value)
+            ? value
+            : {};
+        const fence = parsed.fence && typeof parsed.fence === 'object'
+            ? parsed.fence
+            : undefined;
+        const expect = parsed.expect && typeof parsed.expect === 'object'
+            ? parsed.expect
+            : undefined;
+        return {
+            width: parsed.width,
+            height: parsed.height,
+            cursorX: parsed.cursorX,
+            cursorY: parsed.cursorY,
+            window: typeof parsed.window === 'string' ? parsed.window : '',
+            ...(typeof parsed.windowId === 'number' &&
+                Number.isFinite(parsed.windowId)
+                ? { windowId: parsed.windowId }
+                : {}),
+            ...(typeof parsed.windowCount === 'number'
+                ? { windowCount: parsed.windowCount }
+                : {}),
+            ...(typeof parsed.url === 'string' && parsed.url
+                ? { url: parsed.url.slice(0, 500) }
+                : {}),
+            ...(typeof parsed.pageFocus === 'boolean'
+                ? { pageFocus: parsed.pageFocus }
+                : {}),
+            ...(typeof parsed.focusedElement === 'string' && parsed.focusedElement
+                ? { focusedElement: parsed.focusedElement.slice(0, 200) }
+                : {}),
+            ...(typeof parsed.screenshotSha256 === 'string' && parsed.screenshotSha256
+                ? { screenshotSha256: parsed.screenshotSha256 }
+                : {}),
+            ...(fence &&
+                typeof fence.afterAction === 'number' &&
+                (fence.reason === 'focus_assertion_failed' ||
+                    fence.reason === 'context_changed') &&
+                typeof fence.detail === 'string'
+                ? {
+                    fence: {
+                        afterAction: fence.afterAction,
+                        reason: fence.reason,
+                        detail: fence.detail.slice(0, 600),
+                    },
+                }
+                : {}),
+            ...(expect &&
+                (expect.outcome === 'passed' || expect.outcome === 'pending')
+                ? {
+                    expect: {
+                        outcome: expect.outcome,
+                        ...(Array.isArray(expect.unmet)
+                            ? { unmet: expect.unmet.map(String).slice(0, 8) }
+                            : {}),
+                    },
+                }
+                : {}),
+            ...(Array.isArray(parsed.clickReceipts)
+                ? {
+                    clickReceipts: parsed.clickReceipts
+                        .slice(0, WORK_COMPUTER_ACTION_LIMIT)
+                        .map(asRecord)
+                        .filter(receipt => typeof receipt.action === 'number' &&
+                        typeof receipt.changed === 'boolean')
+                        .map(receipt => ({
+                        action: receipt.action,
+                        type: String(receipt.type ?? 'click'),
+                        x: Number(receipt.x ?? 0),
+                        y: Number(receipt.y ?? 0),
+                        changed: receipt.changed,
+                    })),
+                }
+                : {}),
+            ...(Array.isArray(parsed.scrollReceipts)
+                ? {
+                    scrollReceipts: parsed.scrollReceipts
+                        .slice(0, WORK_COMPUTER_ACTION_LIMIT)
+                        .map(asRecord)
+                        .filter(receipt => typeof receipt.action === 'number')
+                        .map(receipt => ({
+                        action: receipt.action,
+                        found: typeof receipt.found === 'boolean' ? receipt.found : null,
+                        visible: typeof receipt.visible === 'boolean' ? receipt.visible : null,
+                        scrolledUnits: Number(receipt.scrolledUnits ?? 0),
+                    })),
+                }
+                : {}),
+            screenshotBase64: parsed.image,
+        };
+    }
+    async withComputerSession(task, fn) {
+        if (!task.networkEnabled) {
+            throw new WorkRuntimeError('The Work Computer requires network access. Enable network access for this Work task first.', 409, 'WORK_COMPUTER_REQUIRES_NETWORK');
+        }
+        const policy = await workPolicyService.resolve(task.policyId);
+        if (policy.guiEnabled !== true) {
+            throw new WorkRuntimeError("This task's Work policy does not enable the Work Computer.", 409, 'WORK_COMPUTER_NOT_ENABLED');
+        }
+        let releaseLease;
+        try {
+            releaseLease = await this.acquireRuntimeLease(task);
+        }
+        catch (error) {
+            // In team mode the lease holder is usually this deployment's own
+            // durable worker executing the task's run — exactly when a human
+            // wants to see the screen. When the sandbox is already running,
+            // attach to it the way workspace helpers do: start-computer is
+            // idempotent, and lifecycle transitions stay lease-guarded.
+            if (error instanceof WorkRuntimeError &&
+                error.code === 'WORK_RUNTIME_LEASE_CONFLICT') {
+                await this.assertTaskIsActive(task);
+                if ((await this.driver.runtimeState(task)) === 'running') {
+                    await this.startComputerInContainer(task);
+                    const value = await fn();
+                    this.noteTaskActivity(task.id);
+                    return value;
+                }
+            }
+            throw error;
+        }
+        try {
+            await this.ensureImage(task);
+            await this.assertTaskIsActive(task);
+            return await this.withLifecycleLock(task.id, async (assertHeld, signal) => {
+                await this.assertTaskIsActive(task);
+                this.assertCurrentNetworkPolicy(task);
+                await assertHeld();
+                await this.prepareWithLock(task, signal);
+                await this.startComputerInContainer(task, signal);
+                const value = await fn(signal);
+                this.noteTaskActivity(task.id);
+                return value;
+            });
+        }
+        finally {
+            releaseLease();
+        }
+    }
+    async startComputerInContainer(task, signal) {
+        const result = await this.driver.exec(task, ['/usr/local/bin/start-computer'], { timeoutMs: 60000, ...(signal ? { abortSignal: signal } : {}) });
+        if (result.exitCode !== 0) {
+            const detail = (result.stderr || result.stdout || '')
+                .trim()
+                .slice(0, 300);
+            throw new WorkRuntimeError(`The Work Computer could not start${detail ? `: ${detail}` : '.'} ` +
+                'The policy image must include the Work Computer GUI stack.', 500, 'WORK_COMPUTER_START_FAILED');
+        }
+    }
     async startPreview(task, command, hooks = {}) {
         if (!task.networkEnabled) {
             throw new WorkRuntimeError('Preview requires network access. Enable network access for this Work task first.', 409, 'WORK_PREVIEW_REQUIRES_NETWORK');
@@ -2364,6 +3045,500 @@ const walk = directory => {
 walk(targetReal);
 process.stdout.write(results.join('\\n'));
 `;
+/**
+ * Shared observation core for the Work Computer scripts: cursor, active
+ * window, display geometry, a full-screen PNG captured with ImageMagick from
+ * the session's Xvfb display, plus best-effort semantic context — window
+ * identity and count from xdotool, and the active tab's URL, page focus, and
+ * focused-element descriptor from Chromium's loopback DevTools endpoint.
+ * Every semantic signal degrades to absent rather than failing observation.
+ */
+const COMPUTER_OBSERVE_COMMON = String.raw `
+const {execFileSync} = require('node:child_process');
+const {createHash} = require('node:crypto');
+process.env.DISPLAY = ':' + (process.env.LIBRE_COMPUTER_DISPLAY || '1');
+const CDP_BASE =
+  'http://127.0.0.1:' + (process.env.LIBRE_COMPUTER_CDP_PORT || '9222');
+const out = (cmd, args, timeout = 10000) =>
+  execFileSync(cmd, args, {encoding: 'utf8', timeout});
+const attempt = fn => {
+  try { return fn(); } catch { return undefined; }
+};
+// Cheap synchronous context signals: enough to detect window, modal, and
+// title transitions between actions without capturing a screenshot.
+const frame = () => {
+  const windowId = attempt(() =>
+    Number(out('xdotool', ['getactivewindow']).trim())
+  );
+  const windowName =
+    attempt(() => out('xdotool', ['getactivewindow', 'getwindowname']).trim()) || '';
+  const windowCount = attempt(
+    () =>
+      out('xdotool', ['search', '--onlyvisible', '--name', '.'])
+        .split('\n')
+        .filter(Boolean).length
+  );
+  return {windowId, windowName, windowCount};
+};
+// Never returns page content or field values — only the identity of the
+// focused element and whether the page (vs the browser UI) holds focus.
+const FOCUS_EXPRESSION =
+  '(() => { if (!document.hasFocus()) return {focus: false}; ' +
+  'const e = document.activeElement; ' +
+  'if (!e || e === document.body) return {focus: true, el: ""}; ' +
+  'const a = n => e.getAttribute(n) || ""; ' +
+  'const label = (a("aria-label") || (e.labels && e.labels[0] && e.labels[0].textContent) || a("placeholder") || a("name") || "").trim().slice(0, 80); ' +
+  'let d = e.tagName.toLowerCase(); ' +
+  'if (e.id) d += "#" + e.id; ' +
+  'if (a("type")) d += "[type=" + a("type") + "]"; ' +
+  'if (label) d += " (" + label + ")"; ' +
+  'return {focus: true, el: d}; })()';
+const cdpActiveTarget = async windowName => {
+  const listResponse = await fetch(CDP_BASE + '/json/list', {
+    signal: AbortSignal.timeout(700),
+  });
+  const targets = (await listResponse.json()).filter(
+    t => t.type === 'page' && t.url && !String(t.url).startsWith('devtools:')
+  );
+  if (!targets.length) return undefined;
+  return (
+    targets.find(
+      t => t.title && windowName && windowName.startsWith(String(t.title).slice(0, 80))
+    ) || targets[0]
+  );
+};
+// Evaluate one expression in the active page; undefined on any failure.
+const cdpEvaluate = async (target, expression) => {
+  if (!target || !target.webSocketDebuggerUrl) return undefined;
+  return new Promise(resolve => {
+    const socket = new WebSocket(target.webSocketDebuggerUrl);
+    const timer = setTimeout(() => {
+      try { socket.close(); } catch {}
+      resolve(undefined);
+    }, 900);
+    socket.onerror = () => { clearTimeout(timer); resolve(undefined); };
+    socket.onopen = () =>
+      socket.send(
+        JSON.stringify({
+          id: 1,
+          method: 'Runtime.evaluate',
+          params: {expression, returnByValue: true},
+        })
+      );
+    socket.onmessage = event => {
+      clearTimeout(timer);
+      try { socket.close(); } catch {}
+      try {
+        resolve(JSON.parse(event.data).result.result.value);
+      } catch { resolve(undefined); }
+    };
+  });
+};
+const cdpProbe = async windowName => {
+  const result = {url: '', pageFocus: undefined, focusedElement: ''};
+  try {
+    const active = await cdpActiveTarget(windowName);
+    if (!active) return result;
+    result.url = String(active.url).slice(0, 500);
+    const probe = await cdpEvaluate(active, FOCUS_EXPRESSION);
+    if (probe && typeof probe === 'object') {
+      result.pageFocus = probe.focus === true;
+      result.focusedElement =
+        probe.focus === true ? String(probe.el || '').slice(0, 200) : '';
+    }
+  } catch {}
+  return result;
+};
+const observe = async () => {
+  const cursor = {x: 0, y: 0};
+  for (const line of out('xdotool', ['getmouselocation', '--shell']).split('\n')) {
+    const [key, value] = line.split('=');
+    if (key === 'X') cursor.x = Number(value);
+    if (key === 'Y') cursor.y = Number(value);
+  }
+  const current = frame();
+  const geometry = out('xdotool', ['getdisplaygeometry']).trim().split(' ');
+  const png = execFileSync('import', ['-window', 'root', '-silent', 'png:-'], {
+    timeout: 20000,
+    maxBuffer: 32 * 1024 * 1024,
+  });
+  const cdp = await cdpProbe(current.windowName);
+  return {
+    width: Number(geometry[0]),
+    height: Number(geometry[1]),
+    cursorX: cursor.x,
+    cursorY: cursor.y,
+    window: current.windowName.slice(0, 300),
+    ...(current.windowId !== undefined && Number.isFinite(current.windowId)
+      ? {windowId: current.windowId}
+      : {}),
+    ...(current.windowCount !== undefined
+      ? {windowCount: current.windowCount}
+      : {}),
+    ...(cdp.url ? {url: cdp.url} : {}),
+    ...(cdp.pageFocus !== undefined ? {pageFocus: cdp.pageFocus} : {}),
+    ...(cdp.focusedElement ? {focusedElement: cdp.focusedElement} : {}),
+    screenshotSha256: createHash('sha256').update(png).digest('hex'),
+    image: png.toString('base64'),
+  };
+};
+`;
+export const COMPUTER_OBSERVE_SCRIPT = String.raw `${COMPUTER_OBSERVE_COMMON}
+observe().then(observation => {
+  process.stdout.write(JSON.stringify(observation));
+}).catch(error => {
+  console.error(error && error.message ? error.message : String(error));
+  process.exit(1);
+});
+`;
+/**
+ * Interpreter for a backend-validated computer_act batch. Input is trusted
+ * JSON (validateWorkComputerActions runs first); every gesture goes through
+ * xdotool argv — no shell interpolation anywhere.
+ */
+export const COMPUTER_ACT_SCRIPT = String.raw `${COMPUTER_OBSERVE_COMMON}
+const actions = JSON.parse(process.argv[1] || '[]');
+const expectation = JSON.parse(process.argv[2] || 'null');
+const xdotool = args => out('xdotool', args, 120000);
+const wait = ms =>
+  Atomics.wait(new Int32Array(new SharedArrayBuffer(4)), 0, 0, ms);
+const moveTo = action => {
+  if (action.x !== undefined) {
+    xdotool(['mousemove', '--sync', String(action.x), String(action.y)]);
+  }
+};
+const perform = action => {
+  if (action.type === 'move') {
+    xdotool(['mousemove', '--sync', String(action.x), String(action.y)]);
+  } else if (action.type === 'click') {
+    moveTo(action);
+    xdotool(['click', '1']);
+  } else if (action.type === 'double_click') {
+    moveTo(action);
+    xdotool(['click', '--repeat', '2', '--delay', '150', '1']);
+  } else if (action.type === 'right_click') {
+    moveTo(action);
+    xdotool(['click', '3']);
+  } else if (action.type === 'type') {
+    xdotool(['type', '--clearmodifiers', '--delay', '15', '--', action.text]);
+  } else if (action.type === 'key') {
+    xdotool(['key', '--clearmodifiers', '--', action.keys]);
+  } else if (action.type === 'scroll') {
+    moveTo(action);
+    xdotool([
+      'click',
+      '--repeat',
+      String(action.amount),
+      '--delay',
+      '50',
+      action.direction === 'up' ? '4' : '5',
+    ]);
+  } else if (action.type === 'wait') {
+    wait(action.ms);
+  }
+}
+const regionHash = region =>
+  attempt(() => {
+    const crop =
+      String(region.width) + 'x' + String(region.height) +
+      '+' + String(region.x) + '+' + String(region.y);
+    const png = execFileSync(
+      'import',
+      ['-window', 'root', '-crop', crop, '-silent', 'png:-'],
+      {timeout: 20000, maxBuffer: 32 * 1024 * 1024}
+    );
+    return createHash('sha256').update(png).digest('hex');
+  });
+const contextChanged = (action, before, after) => {
+  const mouse =
+    action.type === 'move' ||
+    action.type === 'click' ||
+    action.type === 'double_click' ||
+    action.type === 'right_click';
+  if (before.windowCount !== after.windowCount) {
+    return 'a window appeared or closed (modal, popup, or dialog)';
+  }
+  if (before.windowId !== after.windowId) {
+    // A mouse action activating the window under the cursor is the action
+    // doing its job, not context loss; anything else changing the active
+    // window is.
+    return mouse ? '' : 'the active window changed';
+  }
+  if (before.windowName !== after.windowName) return 'the window title changed';
+  return '';
+};
+const screenHash = () =>
+  attempt(() => {
+    const png = execFileSync('import', ['-window', 'root', '-silent', 'png:-'], {
+      timeout: 20000,
+      maxBuffer: 32 * 1024 * 1024,
+    });
+    return createHash('sha256').update(png).digest('hex');
+  });
+// Adaptive settle: two identical consecutive captures mean the screen has
+// stopped changing; the deadline bounds pages that never go quiet.
+const settleScreen = () => {
+  const deadline = Date.now() + 2500;
+  let previous = screenHash();
+  wait(250);
+  for (;;) {
+    const current = screenHash();
+    if (
+      (previous && current && previous === current) ||
+      Date.now() >= deadline
+    ) {
+      return;
+    }
+    previous = current;
+    wait(300);
+  }
+};
+const CLICK_RECEIPT_SIZE = 120;
+const clickReceiptRegion = action => ({
+  x: Math.max(0, action.x - CLICK_RECEIPT_SIZE / 2),
+  y: Math.max(0, action.y - CLICK_RECEIPT_SIZE / 2),
+  width: CLICK_RECEIPT_SIZE,
+  height: CLICK_RECEIPT_SIZE,
+});
+// Goal-directed scrolling: advance in small steps until the target text is
+// visible (or the page edge is reached), verified through the page itself.
+// Without a semantic signal it degrades to one bounded plain scroll.
+const scrollUntil = async action => {
+  const receipt = {action: 0, found: null, visible: null, scrolledUnits: 0};
+  const probe = async () => {
+    try {
+      const active = await cdpActiveTarget(frame().windowName);
+      if (!active) return undefined;
+      let expression;
+      if (action.target.text !== undefined) {
+        expression =
+          '(() => { const needle = ' +
+          JSON.stringify(String(action.target.text).toLowerCase()) +
+          '; const walker = document.createTreeWalker(document.body, NodeFilter.SHOW_TEXT); ' +
+          'let node; let host = null; ' +
+          'while ((node = walker.nextNode())) { ' +
+          'if (String(node.nodeValue).toLowerCase().includes(needle)) { host = node.parentElement; break; } } ' +
+          'if (!host) return {found: false, visible: false}; ' +
+          'const r = host.getBoundingClientRect(); ' +
+          'return {found: true, visible: r.top >= 0 && r.bottom <= window.innerHeight && r.height > 0}; })()';
+      } else {
+        expression =
+          '(() => { const el = document.scrollingElement || document.documentElement; ' +
+          'return {found: true, visible: ' +
+          (action.target.edge === 'bottom'
+            ? 'Math.ceil(el.scrollTop + window.innerHeight) >= el.scrollHeight'
+            : 'el.scrollTop <= 0') +
+          '}; })()';
+      }
+      return await cdpEvaluate(active, expression);
+    } catch {
+      return undefined;
+    }
+  };
+  const maxUnits = action.maxAmount || 15;
+  const button = action.direction === 'up' ? '4' : '5';
+  moveTo(action);
+  for (;;) {
+    const state = await probe();
+    if (state === undefined) {
+      const remaining = maxUnits - receipt.scrolledUnits;
+      if (remaining > 0) {
+        xdotool(['click', '--repeat', String(remaining), '--delay', '50', button]);
+        receipt.scrolledUnits += remaining;
+      }
+      return receipt;
+    }
+    receipt.found = state.found === true;
+    receipt.visible = state.visible === true;
+    if (
+      (receipt.found && receipt.visible) ||
+      receipt.scrolledUnits >= maxUnits
+    ) {
+      return receipt;
+    }
+    const units = Math.min(3, maxUnits - receipt.scrolledUnits);
+    xdotool(['click', '--repeat', String(units), '--delay', '50', button]);
+    receipt.scrolledUnits += units;
+    wait(200);
+  }
+};
+const main = async () => {
+  const beforeRegion =
+    expectation && expectation.regionChanged
+      ? regionHash(expectation.regionChanged)
+      : undefined;
+  let fence;
+  const clickReceipts = [];
+  const scrollReceipts = [];
+  for (let index = 0; index < actions.length; index++) {
+    const action = actions[index];
+    if ((action.type === 'type' || action.type === 'key') && action.focus) {
+      const current = frame();
+      const cdp = await cdpProbe(current.windowName);
+      const browserChrome =
+        cdp.pageFocus === false && /chromium/i.test(current.windowName);
+      const haystack = [
+        current.windowName,
+        cdp.url,
+        cdp.focusedElement,
+        browserChrome ? 'browser-chrome' : '',
+      ]
+        .filter(Boolean)
+        .join(' | ');
+      const needle = action.focus.toLowerCase();
+      const matches = haystack.toLowerCase().includes(needle);
+      if (!matches || (browserChrome && needle !== 'browser-chrome')) {
+        fence = {
+          afterAction: index,
+          reason: 'focus_assertion_failed',
+          detail:
+            'Action ' + String(index + 1) + ' required keyboard focus matching "' +
+            action.focus + '" but the current focus is: ' +
+            (haystack || 'unknown') +
+            (browserChrome
+              ? '. The page does NOT hold keyboard focus — typed text would go to the browser UI.'
+              : '') +
+            ' This and the remaining action(s) did not run.',
+        };
+        break;
+      }
+    }
+    const before = frame();
+    const receiptRegion =
+      (action.type === 'click' ||
+        action.type === 'double_click' ||
+        action.type === 'right_click') &&
+      action.x !== undefined
+        ? clickReceiptRegion(action)
+        : undefined;
+    if (action.type === 'scroll_until') {
+      const receipt = await scrollUntil(action);
+      receipt.action = index + 1;
+      scrollReceipts.push(receipt);
+    } else if (receiptRegion) {
+      const beforeHash = regionHash(receiptRegion);
+      perform(action);
+      wait(150);
+      const afterHash = regionHash(receiptRegion);
+      // "Pixels near the click changed" — a signal, not a verdict: a dead
+      // click on empty space reads changed:false even though it delivered.
+      clickReceipts.push({
+        action: index + 1,
+        type: action.type,
+        x: action.x,
+        y: action.y,
+        changed: Boolean(beforeHash && afterHash && beforeHash !== afterHash),
+      });
+    } else {
+      perform(action);
+    }
+    if (index < actions.length - 1) {
+      const changed = contextChanged(action, before, frame());
+      if (changed) {
+        fence = {
+          afterAction: index + 1,
+          reason: 'context_changed',
+          detail:
+            'After action ' + String(index + 1) + ', ' + changed +
+            '; the remaining ' + String(actions.length - index - 1) +
+            ' action(s) did not run because their coordinates targeted the previous screen. Observe before continuing.',
+        };
+        break;
+      }
+    }
+  }
+  settleScreen();
+  let expectResult;
+  if (expectation && !fence) {
+    const deadline = Date.now() + (expectation.withinMs || 5000);
+    let unmet = [];
+    for (;;) {
+      unmet = [];
+      const current = frame();
+      if (
+        expectation.titleContains !== undefined &&
+        !current.windowName.toLowerCase().includes(expectation.titleContains.toLowerCase())
+      ) {
+        unmet.push('titleContains');
+      }
+      if (expectation.urlContains !== undefined) {
+        const cdp = await cdpProbe(current.windowName);
+        if (!cdp.url.toLowerCase().includes(expectation.urlContains.toLowerCase())) {
+          unmet.push('urlContains');
+        }
+      }
+      if (expectation.regionChanged) {
+        const currentRegion = regionHash(expectation.regionChanged);
+        if (!beforeRegion || !currentRegion || currentRegion === beforeRegion) {
+          unmet.push('regionChanged');
+        }
+      }
+      if (!unmet.length || Date.now() >= deadline) break;
+      wait(500);
+    }
+    expectResult = unmet.length
+      ? {outcome: 'pending', unmet}
+      : {outcome: 'passed'};
+  }
+  const observation = await observe();
+  process.stdout.write(
+    JSON.stringify({
+      ...observation,
+      ...(fence ? {fence} : {}),
+      ...(expectResult ? {expect: expectResult} : {}),
+      ...(clickReceipts.length ? {clickReceipts} : {}),
+      ...(scrollReceipts.length ? {scrollReceipts} : {}),
+    })
+  );
+};
+main().catch(error => {
+  console.error(error && error.message ? error.message : String(error));
+  process.exit(1);
+});
+`;
+/**
+ * Resolve the page element under a screen coordinate — the teach recorder's
+ * anchor probe. Runs during a human demonstration, so it must never inject
+ * input or steal focus: it only reads. Returns {} outside the browser
+ * viewport, on non-browser windows, or on pre-CDP GUI images.
+ */
+export const COMPUTER_ANCHOR_SCRIPT = String.raw `${COMPUTER_OBSERVE_COMMON}
+const pointX = Number(process.argv[1]);
+const pointY = Number(process.argv[2]);
+const main = async () => {
+  const result = {};
+  try {
+    const active = await cdpActiveTarget(frame().windowName);
+    if (active) {
+      result.url = String(active.url).slice(0, 300);
+      const expression =
+        '(() => { const sx = ' + String(pointX) + '; const sy = ' + String(pointY) + '; ' +
+        'const px = sx - (window.screenX + (window.outerWidth - window.innerWidth) / 2); ' +
+        'const py = sy - (window.screenY + (window.outerHeight - window.innerHeight)); ' +
+        'if (px < 0 || py < 0 || px > window.innerWidth || py > window.innerHeight) return null; ' +
+        'const el = document.elementFromPoint(px, py); if (!el) return null; ' +
+        'const host = el.closest("button, a, input, select, textarea, label, summary, [role]") || el; ' +
+        'const a = n => host.getAttribute(n) || ""; ' +
+        'const text = (host.innerText || host.value || "").split("\\n").join(" ").split("\\t").join(" ").trim().slice(0, 60); ' +
+        'const label = (a("aria-label") || a("placeholder") || a("name") || text).trim(); ' +
+        'let d = host.tagName.toLowerCase(); ' +
+        'if (host.id) d += "#" + host.id; ' +
+        'if (a("type")) d += "[type=" + a("type") + "]"; ' +
+        'if (label) d += " (" + label + ")"; ' +
+        'return d; })()';
+      const anchor = await cdpEvaluate(active, expression);
+      if (typeof anchor === 'string' && anchor) {
+        result.anchor = anchor.slice(0, 200);
+      }
+    }
+  } catch {}
+  process.stdout.write(JSON.stringify(result));
+};
+main().catch(error => {
+  console.error(error && error.message ? error.message : String(error));
+  process.exit(1);
+});
+`;
 /**
  * Select the runtime backend for this deployment. Docker remains the
  * default; WORK_RUNTIME_BACKEND=kubernetes runs sandboxes as Pods in a