mixdog 1.0.7 → 1.0.9

package/src/runtime/agent/orchestrator/tools/builtin/bash-tool/deadline-plan.mjs

@@ -1,8 +1,12 @@
 // Commands start in the foreground. Only work still running after the
-// 10 s coordination budget is promoted to a tracked background task.
+// 15 s coordination budget is promoted to a tracked background task.
 // Short commands therefore complete in the original tool turn, while longer
 // work returns partial output plus task_id and finishes by notification.
-export const DEFAULT_SHELL_AUTO_BACKGROUND_MS = 10_000;
+// 15 s because a command promoted moments before it ends costs a whole
+// follow-up request on `task wait`. Session logs (2026-09-30..10-05), the 260
+// promoted commands with a recorded duration: 108 had ended within 10 s, 144
+// within 15 s and only 152 within 20 s.
+export const DEFAULT_SHELL_AUTO_BACKGROUND_MS = 15_000;
 
 // JS timers (setTimeout) and PS WaitForExit(ms) are 32-bit: a delay above
 // 2^31-1 wraps to a tiny/negative value and fires immediately. Clamp the
@@ -13,12 +17,17 @@ const TIMER_MAX_MS = 2_147_483_647;
 
 // Main-agent blocking budget. A timeout is the command's total deadline, not
 // permission to hold the conversation open for that whole duration: after
-// 10 s a still-running command becomes a tracked background task and
+// 15 s a still-running command becomes a tracked background task and
 // completion is pushed to the owner. MIXDOG_SHELL_AUTO_BACKGROUND_MS
 // overrides; an explicit 0 disables. Gated on backgroundOnTimeout so
 // disabled background tasks remain foreground.
-// A per-call wait_ms replaces that default for the call, capped by the
-// foreground maximum.
+// A per-call wait_ms extends that default for the call, capped by the
+// foreground maximum; it never shortens it. A shorter window promotes a
+// command that would have returned its result in the starting call and spends
+// a whole follow-up request on `task wait`. Session logs (2026-09-30..10-05,
+// 3062 shell calls): 329 passed a wait_ms under the default (53% of one model
+// family's calls), 256 of those were promoted, and 108 of the 192 with a
+// recorded duration had finished inside the default window (10 s then).
 function autoBackgroundBudget(backgroundOnTimeout, timeout, waitMs, maxForegroundMs) {
   const raw = process.env.MIXDOG_SHELL_AUTO_BACKGROUND_MS;
   const parsed = Number(raw);
@@ -26,7 +35,7 @@ function autoBackgroundBudget(backgroundOnTimeout, timeout, waitMs, maxForegroun
     raw != null && String(raw).trim() !== '' && Number.isFinite(parsed) && parsed >= 0
       ? Math.floor(parsed)
       : DEFAULT_SHELL_AUTO_BACKGROUND_MS;
-  if (waitMs > 0) defaultMs = Math.min(waitMs, maxForegroundMs);
+  if (waitMs > 0) defaultMs = Math.max(defaultMs, Math.min(waitMs, maxForegroundMs));
   if (!backgroundOnTimeout || defaultMs <= 0) return 0;
   return timeout > 0 ? Math.min(defaultMs, timeout) : defaultMs;
 }

package/src/runtime/agent/orchestrator/tools/builtin/builtin-tools.mjs

@@ -146,7 +146,7 @@ export const BUILTIN_TOOLS = [
       openWorldHint: true,
       compressible: true,
     },
-    description: `Run programs, builds, tests and computation. Never use shell commands or scripts for work covered by dedicated tools: cat/head/tail→read, ls→list, find→glob, filename lookup→find, grep/rg→grep, code structure→code_graph, file edits/writes (sed/awk/redirection)→edit/apply_patch, Git→git when that tool is on the surface. Tool names are not shell commands. ${_shellBackgroundDisabled ? 'Commands run in the foreground until completion.' : 'After a 10s foreground window (not a timeout; wait_ms extends it up to 120s for one call, e.g. a test suite), unfinished work continues under task_id; use task wait, not read polling. If no execution slot frees within the admission wait, the command is queued as a background task with a task_id.'}`,
+    description: `Run programs, builds, tests and computation. Never use shell commands or scripts for work covered by dedicated tools: cat/head/tail→read, ls→list, find→glob, filename lookup→find, grep/rg→grep, code structure→code_graph, file edits/writes (sed/awk/redirection)→edit/apply_patch, Git→git when that tool is on the surface. Tool names are not shell commands. ${_shellBackgroundDisabled ? 'Commands run in the foreground until completion.' : 'After a 15s foreground window (not a timeout; wait_ms extends it up to 120s for one call, e.g. a test suite), unfinished work continues under task_id; use task wait, not read polling. If no execution slot frees within the admission wait, the command is queued as a background task with a task_id.'}`,
     inputSchema: {
       type: 'object',
       properties: {
@@ -155,14 +155,14 @@ export const BUILTIN_TOOLS = [
           type: 'integer',
           minimum: 0,
           description:
-            'Hard kill deadline in ms (omit or 0 = none), separate from the 10s foreground window; set one for throwaway probes so a slow check fails fast.',
+            'Hard kill deadline in ms (omit or 0 = none), separate from the 15s foreground window; set one for throwaway probes so a slow check fails fast.',
         },
         wait_ms: {
           type: 'integer',
-          minimum: 1000,
+          minimum: 15000,
           maximum: 120000,
           description:
-            'Foreground wait in ms before unfinished work continues as a background task (default 10000); raise it for a command that should return its result in this call.',
+            'Foreground wait in ms before unfinished work continues as a background task (default 15000); raise it for a command that should return its result in this call.',
         },
       },
       required: ['command'],

package/src/runtime/agent/orchestrator/tools/patch/native-server.mjs

@@ -484,6 +484,13 @@ class NativePatchServer {
     this.#child.stdin.on('error', (err) => {
       this.failTransport(err);
     });
+    // A spawn that fails outright (an artifact without the execute bit, or one
+    // removed between the gate's read and the spawn) reports only through the
+    // child's own 'error' event; unheard, it crashed the host instead of
+    // failing the handshake closed.
+    this.#child.on('error', (err) => {
+      this.failTransport(err);
+    });
     this.#child.on('exit', (code, signal) => {
       this.exited = true;
       const err = new Error(`native patch server exited code=${code} signal=${signal} stderr=${this.stderr}`);

package/src/runtime/channels/lib/voice-transcription.mjs

@@ -98,6 +98,35 @@ async function probeAudioDurationSec(filePath) {
   }
 }
 
+// Leading silence so a clipped onset still decodes as the first word. The
+// bundled ffmpeg carries only aformat/anull/aresample
+// (scripts/build-ffmpeg-runtime.sh), so the pad is spliced into the converted
+// wav here: zero samples in front of its PCM data.
+const ONSET_SILENCE_SECONDS = 0.3;
+
+export function prependWavSilence(wavPath, seconds = ONSET_SILENCE_SECONDS) {
+  const wav = fs.readFileSync(wavPath);
+  let sampleRate = 0;
+  let blockAlign = 0;
+  for (let offset = 12; offset + 8 <= wav.length; ) {
+    const id = wav.toString('ascii', offset, offset + 4);
+    const size = wav.readUInt32LE(offset + 4);
+    if (id === 'fmt ') {
+      sampleRate = wav.readUInt32LE(offset + 12);
+      blockAlign = wav.readUInt16LE(offset + 20);
+    } else if (id === 'data') {
+      const silence = Buffer.alloc(Math.round(sampleRate * seconds) * blockAlign);
+      const out = Buffer.concat([wav.subarray(0, offset + 8), silence, wav.subarray(offset + 8)]);
+      out.writeUInt32LE(size + silence.length, offset + 4);
+      out.writeUInt32LE(out.length - 8, 4);
+      fs.writeFileSync(wavPath, out);
+      return;
+    }
+    offset += 8 + size + (size % 2);
+  }
+  throw new Error(`no PCM data chunk in ${wavPath}`);
+}
+
 // One whisper-ready wav per attachment: a cached conversion is reused while its
 // file still exists, and parallel callers for the same key share a single
 // ffmpeg spawn instead of racing two conversions onto the same output path.
@@ -126,9 +155,6 @@ function createVoiceWavCache() {
           const _ffmpegPromise = runCmd(ffmpegPath, [
             '-i',
             audioPath,
-            // Leading silence so a clipped onset still decodes as the first word.
-            '-af',
-            'adelay=300:all=1',
             '-ar',
             String(sampleRate),
             '-ac',
@@ -137,7 +163,7 @@ function createVoiceWavCache() {
             String(threadCount),
             '-y',
             wavPath,
-          ]);
+          ]).then(() => prependWavSilence(wavPath));
           ffmpegInflight.set(_ffmpegKey, _ffmpegPromise);
           try {
             await _ffmpegPromise;

package/src/runtime/computer-bridge/action-schema.mjs

@@ -118,11 +118,11 @@ const captureProperties = {
   include_ocr: {
     type: 'boolean',
     description:
-      'State/SOM automatically use offline Windows OCR when semantic targets are absent; true always runs OCR even when semantic targets exist. OCR shares max_elements. Zoom recognizes the crop itself, which is how enlarged text becomes readable.',
+      'State/SOM automatically use offline OS OCR when semantic targets are absent; true always runs OCR even when semantic targets exist. OCR shares max_elements. Zoom recognizes the crop itself, which is how enlarged text becomes readable.',
   },
   ocr_language: {
     ...ocrLanguage,
-    description: 'Installed Windows OCR language tag, e.g. ko or en-US.',
+    description: 'Installed OS OCR language tag, e.g. ko or en-US.',
   },
   // Image encoding (JPEG quality, downscale width) and the OCR word cap are
   // host defaults: the element budget already bounds OCR, and a frame the
@@ -213,7 +213,7 @@ export const COMPUTER_INPUT_SCHEMA = {
         ...windowTarget,
         ocr_language: {
           ...ocrLanguage,
-          description: 'Optional Windows OCR language tag to verify, e.g. ko or en-US.',
+          description: 'Optional OS OCR language tag to verify, e.g. ko or en-US.',
         },
       }),
       false

package/src/runtime/computer-bridge/actions.mjs

@@ -31,6 +31,10 @@ action('ocr_image', nativeRead);
 action('ocr_status', nativeRead);
 action('release_session', { retainNativeRefs: true });
 action('release_cursor_theme', { retainNativeRefs: true });
+// Handing held input, focus and pointer back changes no target's content, so a
+// turn's end keeps the refs of its last observation for a follow-up turn.
+action('release_held_input', { retainNativeRefs: true });
+action('restore_input_state', { retainNativeRefs: true });
 action('list_apps', { ...hostRead, ...replay, policy: 'list' });
 action('list_installed_apps', { ...nativeRead, ...replay, policy: 'list' });
 action('list_history', { ...hostRead, ...replay, policy: 'list' });

package/src/runtime/computer-bridge/bridge-env.test-support.mjs

@@ -0,0 +1,22 @@
+import { mkdtemp, rm, writeFile } from 'node:fs/promises';
+import { tmpdir } from 'node:os';
+import { join } from 'node:path';
+
+// Creates a temp directory and points the env var `name` at it until `cleanup()`.
+export async function makeTempEnvDir(name, prefix) {
+  const directory = await mkdtemp(join(tmpdir(), prefix));
+  const previous = process.env[name];
+  process.env[name] = directory;
+  return {
+    directory,
+    async cleanup() {
+      if (previous === undefined) delete process.env[name];
+      else process.env[name] = previous;
+      await rm(directory, { recursive: true, force: true });
+    },
+  };
+}
+
+export function writeBridgeDiscovery(directory, fields) {
+  return writeFile(join(directory, 'computer-bridge.json'), JSON.stringify({ version: 1, ...fields }));
+}

package/src/runtime/computer-bridge/client.mjs

@@ -13,13 +13,20 @@ import {
   toComputerHostCommand,
   validateComputerToolArgs,
 } from './action-schema.mjs';
-import { computerResultRecovery, formatComputerToolError } from './error-recovery.mjs';
+import { formatComputerToolError } from './error-recovery.mjs';
+import {
+  canonicalComputerResultIsError,
+  canonicalComputerResultText,
+  computerImageDimensions,
+} from './result-canonical.mjs';
 import { computerErrorCode } from './error-code.mjs';
 import { bridgeDiscoveryChanged, readBridgeDiscovery } from '../bridge-discovery.mjs';
 import { MAX_COMPUTER_REQUEST_BYTES, readComputerBridgeJson, validateComputerReply } from './limits.mjs';
 import { computerActionHas } from './actions.mjs';
 import { continuePendingComputerWork, isPendingComputerWork } from './pending-continuation.mjs';
 
+export { canonicalComputerResultText };
+
 const DISCOVERY_FILE = 'computer-bridge.json';
 // Desktop UI Automation queries and input dispatch can be slow; sit above the
 // bridge's own per-action timeouts so its specific error wins over a bare abort.
@@ -48,186 +55,6 @@ const activeComputerExecutions = new Set();
 const BRIDGE_UNAVAILABLE_MESSAGE =
   'computer use is unavailable; open the Mixdog desktop app and enable Computer Use in settings';
 
-const ACT_STEP_STATUSES = new Set(['succeeded', 'failed', 'skipped', 'pending', 'uncertain']);
-
-function canonicalizeActResult(value, args) {
-  value.completed_actions = value.completed_steps;
-  value.total_actions = value.total_steps;
-  const canonicalStep = (row, index) => {
-    const normalized = { ...row };
-    normalized.type = args.input?.actions?.[index]?.type || normalized.action;
-    if (!ACT_STEP_STATUSES.has(normalized.status)) {
-      normalized.status = normalized.ok === false ? 'failed' : 'succeeded';
-    }
-    delete normalized.action;
-    delete normalized.ok;
-    return normalized;
-  };
-  value.actions = Array.isArray(value.steps) ? value.steps.map(canonicalStep) : value.steps;
-  // A single-window act reports the same transition on the act and its step.
-  const transition = JSON.stringify(value.window_transition);
-  for (const row of Array.isArray(value.actions) ? value.actions : []) {
-    if (transition && JSON.stringify(row?.window_transition) === transition) delete row.window_transition;
-  }
-  delete value.completed_steps;
-  delete value.total_steps;
-  delete value.steps;
-}
-
-// Host diagnostics stay in the host's run record; the model acts on none of them.
-const HOST_DIAGNOSTIC_FIELDS = ['timings_ms', 'capture_attempts'];
-
-function dropHostDiagnostics(value) {
-  if (!value || typeof value !== 'object') return;
-  if (Array.isArray(value)) {
-    for (const item of value) dropHostDiagnostics(item);
-    return;
-  }
-  for (const field of HOST_DIAGNOSTIC_FIELDS) delete value[field];
-  for (const item of Object.values(value)) dropHostDiagnostics(item);
-}
-
-// Elements and OCR text reach the model one line each, the shape browser
-// snapshots use, because a field name costs more than the value it labels:
-// `#mark [ref] Role "name" value="…" state=… source=… disabled focused
-// @x,y,width,height actions`. Flags appear only when they differ from the
-// common case the capture description states (an enabled UIA element), and
-// the geometry a som frame repeats as x/y/width/height, center and
-// screen_bounds collapses into its one bounds box.
-const DERIVED_GEOMETRY_FIELDS = new Set([
-  'x',
-  'y',
-  'width',
-  'height',
-  'center_x',
-  'center_y',
-  'center',
-  'screen_bounds',
-]);
-
-const quotedText = (text) => JSON.stringify(String(text));
-const bareText = (text) => (/^[^\s"]+$/.test(String(text)) ? String(text) : quotedText(text));
-const isUnsetField = (field) =>
-  field === undefined || field === null || field === '' || field === false || (Array.isArray(field) && !field.length);
-
-function boundsText(box) {
-  return box.length === 4 && box.every((edge) => Number.isFinite(edge)) ? `@${box.join(',')}` : null;
-}
-
-function extraFieldTexts(rest) {
-  return Object.entries(rest)
-    .filter(([key, field]) => !DERIVED_GEOMETRY_FIELDS.has(key) && !isUnsetField(field))
-    .map(([key, field]) => `${key}=${typeof field === 'string' ? bareText(field) : JSON.stringify(field)}`);
-}
-
-function elementLine(element) {
-  if (!element || typeof element !== 'object') return element;
-  const { mark, ref, role, name, value, state, source, enabled, has_keyboard_focus, bounds, actions, ...rest } =
-    element;
-  return [
-    isUnsetField(mark) ? null : `#${mark}`,
-    isUnsetField(ref) ? null : `[${ref}]`,
-    bareText(role || 'Unknown'),
-    quotedText(name ?? ''),
-    isUnsetField(value) ? null : `value=${quotedText(value)}`,
-    isUnsetField(state) || state === source ? null : `state=${bareText(state)}`,
-    isUnsetField(source) || source === 'uia' ? null : `source=${bareText(source)}`,
-    enabled === false ? 'disabled' : null,
-    has_keyboard_focus === true ? 'focused' : null,
-    boundsText(Array.isArray(bounds) ? bounds : [rest.x, rest.y, rest.width, rest.height]),
-    Array.isArray(actions) && actions.length ? actions.join(',') : null,
-    ...extraFieldTexts(rest),
-  ]
-    .filter(Boolean)
-    .join(' ');
-}
-
-function ocrTextLine(row) {
-  if (!row || typeof row !== 'object') return row;
-  const { mark, text, line, x, y, width, height, ...rest } = row;
-  return [
-    isUnsetField(mark) ? null : `#${mark}`,
-    quotedText(text ?? ''),
-    boundsText([x, y, width, height]),
-    isUnsetField(line) ? null : `line=${line}`,
-    ...extraFieldTexts(rest),
-  ]
-    .filter(Boolean)
-    .join(' ');
-}
-
-function renderObservationLines(frame) {
-  if (!frame || typeof frame !== 'object') return;
-  if (Array.isArray(frame.elements)) frame.elements = frame.elements.map(elementLine);
-  for (const key of ['lines', 'words']) {
-    if (Array.isArray(frame.ocr?.[key])) frame.ocr[key] = frame.ocr[key].map(ocrTextLine);
-  }
-}
-
-export function canonicalComputerResultText(text, args) {
-  if (args.action === 'clipboard' && args.input?.operation === 'read') return text;
-  let value;
-  try {
-    value = JSON.parse(text);
-  } catch {
-    return text;
-  }
-  if (!value || typeof value !== 'object' || Array.isArray(value) || typeof value.action !== 'string') {
-    return text;
-  }
-  value.action = args.action;
-  if (args.action === 'list') value.kind = args.input?.kind;
-  if (args.action === 'capture') value.mode = args.input?.mode || 'state';
-  if (args.action === 'window') value.operation = args.input?.operation;
-  if (args.action === 'clipboard') value.operation = args.input?.operation;
-  if (args.action === 'act') canonicalizeActResult(value, args);
-  if (value.capture_after && value.observation === undefined) {
-    value.observation = value.capture_after;
-    delete value.capture_after;
-  }
-  dropHostDiagnostics(value);
-  renderObservationLines(value);
-  renderObservationLines(value.observation);
-  if (value.ok === false && value.recovery === undefined) {
-    const recovery = computerResultRecovery(value, args);
-    if (recovery) value.recovery = recovery;
-  }
-  return JSON.stringify(value);
-}
-
-// A capture payload reports the frame's real pixel size (`width`/`height`,
-// nested under `observation` for action replies). Carrying it on the image
-// block lets the context estimator bill a screenshot at its true vision cost
-// instead of the flat unknown-image allowance. Provider normalizers rebuild
-// the wire block from `type`/`source` alone, so these fields never reach an
-// API and never shift the cached prefix.
-function computerImageDimensions(text) {
-  let value;
-  try {
-    value = JSON.parse(text);
-  } catch {
-    return null;
-  }
-  for (const frame of [value, value?.observation]) {
-    const width = Number(frame?.width);
-    const height = Number(frame?.height);
-    if (width > 0 && height > 0 && Number.isFinite(width) && Number.isFinite(height)) return { width, height };
-  }
-  return null;
-}
-
-function canonicalComputerResultIsError(text, args) {
-  if (args.action === 'clipboard' && args.input?.operation === 'read') return false;
-  try {
-    const value = JSON.parse(text);
-    return Boolean(
-      value && typeof value === 'object' && !Array.isArray(value) && value.action === args.action && value.ok === false
-    );
-  } catch {
-    return false;
-  }
-}
-
 /** Sync gate for the session tool surface (featureDisallowedTools). */
 export function computerBridgeAvailableSync() {
   return readBridgeDiscovery(DISCOVERY_FILE) !== null;
@@ -541,8 +368,8 @@ async function abortComputerSession(sessionId) {
   return aborted;
 }
 
-/** End the visible Computer Use execution at agent-turn settlement without
- * dropping the warm worker and observation refs kept for a possible follow-up. */
+/** End the visible Computer Use execution at agent-turn settlement and hand the
+ * desktop back, keeping the warm worker and observation refs for a possible follow-up. */
 export async function endComputerExecution(sessionId) {
   const id = String(sessionId || '').trim();
   if (!id || !activeComputerExecutions.has(id)) return false;

package/src/runtime/computer-bridge/core-actions.mjs

@@ -276,7 +276,8 @@ function actionArgumentsError(action, type, label, frameId) {
     if (hasOwn(action, 'ref') && hasOwn(action, 'element')) return `${label} accepts only one of ref or element`;
     return typeof action.value === 'string' ? null : `${label} requires value`;
   }
-  if (type === 'key' || type === 'key_down' || type === 'key_up') return typeof action.keys === 'string' ? null : `${label} requires keys`;
+  if (type === 'key' || type === 'key_down' || type === 'key_up')
+    return typeof action.keys === 'string' ? null : `${label} requires keys`;
   if (type === 'wait') {
     const { duration } = action;
     const valid = typeof duration === 'number' && Number.isFinite(duration) && duration >= 0 && duration <= 5;

package/src/runtime/computer-bridge/error-recovery.mjs

@@ -21,11 +21,7 @@ function targetLabel(args) {
 const LIST_WINDOW_CODES = new Set(['ambiguous_window_target', 'window_stale', 'window_target_not_found']);
 const STALE_TARGET_CODES = new Set(['stale_frame', 'stale_target', 'target_mismatch']);
 const USER_YIELD_CODES = new Set(['computer_user_control_active', 'computer_user_takeover', 'user_input_active']);
-const DIAGNOSE_CODES = new Set([
-  'input_observation_unavailable',
-  'input_recovery_unconfirmed',
-  'computer_cursor_unavailable',
-]);
+const DIAGNOSE_CODES = new Set(['input_observation_unavailable', 'computer_cursor_unavailable']);
 const CLEANUP_CODES = new Set([
   'computer_cleanup_pending',
   'computer_abort_cleanup_unconfirmed',
@@ -47,6 +43,40 @@ function recaptureLeaseGuidance(code, target) {
   return `The target lease is now available. Capture ${target} again before issuing any input.`;
 }
 
+function timeoutRecovery(code, args, target) {
+  if (READ_ONLY_ACTIONS.has(String(args?.action || ''))) {
+    return {
+      code,
+      next: 'capture',
+      guidance: `The read exceeded its bounded budget and sent no input, so no cleanup or user-control guard applies. Capture ${target} with mode="state" or "som": pixels and OCR stay usable while that window's accessibility provider is slow.`,
+    };
+  }
+  return {
+    code,
+    next: 'diagnose',
+    guidance: `The command may have executed before timing out. Do not repeat it or switch delivery modes. Diagnose the host first; cleanup and user-control guards must clear through verified recovery. Then capture ${target} and inspect the effect before issuing any new input.`,
+  };
+}
+
+function foregroundRecovery(code, target) {
+  if (code === 'foreground_changed') {
+    return {
+      code,
+      next: 'user',
+      guidance:
+        'Focus changed during dispatch. Do not pull it back or retry input automatically. Check user control, then obtain fresh state when control is available.',
+    };
+  }
+  if (code === 'foreground_unavailable') {
+    return {
+      code,
+      next: 'user',
+      guidance: `The system did not grant foreground focus (macOS refuses it while another app is active). Ask the user to activate ${target}, or use a foreground click on the window, which activates it; then capture fresh state. Do not substitute background input or repeat the failed gesture.`,
+    };
+  }
+  return undefined;
+}
+
 function recoveryForCode(code, args) {
   const target = targetLabel(args);
   if (code === 'computer_background_cleanup_unconfirmed') {
@@ -82,6 +112,14 @@ function recoveryForCode(code, args) {
         "Computer Use yielded to the user. Call wait_for_user for bounded waiting. The user's Resume on the overlay continues the pause, and ordinary physical input may also resume after the host-configured quiet interval (default 5 seconds); explicit stops and uncertain cleanup/observation require the user. Stop cancels the task. Timeout does not authorize input. After resumed, capture fresh state; never replay interrupted input.",
     };
   }
+  if (code === 'input_recovery_unconfirmed') {
+    return {
+      code,
+      next: 'wait_for_user',
+      guidance:
+        'The desktop state after the action could not be verified, so Computer Use stopped the session and handed the desktop to the user. Do not repeat the mutation. Call wait_for_user: the host resumes by itself once the desktop has been quiet for its interval, or when the user presses Resume. After resumed, capture fresh state and inspect the effect before any new input.',
+    };
+  }
   if (DIAGNOSE_CODES.has(code)) {
     return {
       code,
@@ -105,20 +143,7 @@ function recoveryForCode(code, args) {
       guidance: `No input was sent. Foreground delivery needs an observation taken while the user's own input was idle. Let their input settle and capture ${target} again, or send this action through background delivery when it supports one.`,
     };
   }
-  if (code === 'computer_command_timeout') {
-    if (READ_ONLY_ACTIONS.has(String(args?.action || ''))) {
-      return {
-        code,
-        next: 'capture',
-        guidance: `The read exceeded its bounded budget and sent no input, so no cleanup or user-control guard applies. Capture ${target} with mode="state" or "som": pixels and OCR stay usable while that window's accessibility provider is slow.`,
-      };
-    }
-    return {
-      code,
-      next: 'diagnose',
-      guidance: `The command may have executed before timing out. Do not repeat it or switch delivery modes. Diagnose the host first; cleanup and user-control guards must clear through verified recovery. Then capture ${target} and inspect the effect before issuing any new input.`,
-    };
-  }
+  if (code === 'computer_command_timeout') return timeoutRecovery(code, args, target);
   if (code.startsWith('menu_')) {
     return {
       code,
@@ -126,21 +151,8 @@ function recoveryForCode(code, args) {
       guidance: `Capture ${target} again; empty accessibility automatically uses OCR. Use a fresh OCR mark or frame point and do not retry the same menu path unchanged.`,
     };
   }
-  if (code === 'foreground_changed') {
-    return {
-      code,
-      next: 'user',
-      guidance:
-        'Focus changed during dispatch. Do not pull it back or retry input automatically. Check user control, then obtain fresh state when control is available.',
-    };
-  }
-  if (code === 'foreground_unavailable') {
-    return {
-      code,
-      next: 'user',
-      guidance: `Windows did not grant foreground focus. Ask the user to activate ${target}, then capture fresh state. Do not substitute background input or repeat the failed gesture.`,
-    };
-  }
+  const foreground = foregroundRecovery(code, target);
+  if (foreground) return foreground;
   if (code.startsWith('background_')) {
     return {
       code,