dsh-codex-style-computer-use 1.3.1 → 2.1.0

package/lib/core/index.js

@@ -16,12 +16,15 @@ import { AsyncLocalStorage } from 'node:async_hooks'
 import { existsSync, readFileSync, statSync } from 'node:fs'
 import { join } from 'node:path'
 import { fileURLToPath } from 'node:url'
-import { prepareNativeBinary, workerReferences } from './native-runtime.js'
+import { prepareNativeBinary, workerReferences, nativeRuntimeIdentity } from './native-runtime.js'
+import { parseKeyCommand } from '../key-command.js'
+import { verificationRegion } from '../verification-region.js'
 
 const __dirname = fileURLToPath(new URL('.', import.meta.url))
 
 const DEFAULT_TIMEOUT_MS = 15_000
 const CAPTURE_TIMEOUT_MS = 30_000
+const INPUT_CLEANUP_GRACE_MS = 1500
 // A UIA tree walk can block the resident's synchronous COM thread. Bound the
 // caller's wait separately from recovery of a worker that never returns.
 const UIA_READS = new Set(['uia', 'uiaFromPoint', 'uiaFocused'])
@@ -50,7 +53,7 @@ const ASK_DEADLINE_MS = 15_000
 const END_ASK_DEADLINE_MS = 5_000
 export function workerCallError (message, code, op, requestId, outcome = 'unknown') {
   return Object.assign(new Error(`${message} [${code}; outcome=${outcome}]. ${outcome === 'unknown' ? 'Inspect current state before retrying a write.' : 'No input was dispatched by this operation.'}`),
-    { code, op, requestId, outcome })
+    { code, op, requestId, outcome, detail: message })
 }
 
 /** A handoff interrupts an input operation, never the authorized task. */
@@ -75,6 +78,19 @@ function humanReobserveError (error = {}) {
   { transient: true, taskStatus: 'continuing', continuation })
 }
 
+function workerReobserveError (workerGeneration, interrupted = {}) {
+  const outcome = interrupted.outcome === 'unknown' ? 'unknown' : 'not-dispatched'
+  const continuation = {
+    required: true, taskStatus: 'continuing', reason: 'worker-restarted',
+    nextAction: 'observe-current-target-then-continue-original-task',
+    replayInterruptedInput: false, outcome, workerGeneration,
+    interruptedOperation: interrupted.op || null, requestId: interrupted.requestId ?? null,
+    instruction: 'The native worker restarted and previous desktop evidence is invalid. Obtain fresh target evidence, inspect any interrupted operation, and continue the original authorized task. This is worker recovery, not a human handback or permission to replay a write.',
+  }
+  return Object.assign(workerCallError(continuation.instruction, 'WORKER_REOBSERVE', continuation.interruptedOperation, continuation.requestId, outcome),
+    { transient: true, taskStatus: 'continuing', continuation })
+}
+
 /** Interactive roles that receive Set-of-Marks labels. */
 const SOM_ROLES = new Set([
   'Button', 'MenuItem', 'ListItem', 'TreeItem', 'DataItem', 'TabItem',
@@ -110,6 +126,13 @@ export class ComputerUse extends EventEmitter {
     this.stopped = false         // true while the human's brake is engaged (see 'panic' event)
     this.exited = false          // true once the human ended the session (see 'exit' event)
     this.cooperation = { phase: 'idle', active: false, revision: 0 }
+    this.workerGeneration = null
+    this.nativeStateSeq = -1
+    this.workerStateInvalid = false
+    this.runtime = null
+    this.inputCleanupGraceMs = INPUT_CLEANUP_GRACE_MS
+    this.shutdownGraceMs = INPUT_CLEANUP_GRACE_MS
+    this.activeActions = new Map()
     this.inputContext = new AsyncLocalStorage()
     // Monotonic counter of UNSOLICITED state transitions (panic/ask/resume/exit). Anything that
     // learns the machine's state asynchronously — above all the `ask` op, which can take seconds and
@@ -145,7 +168,10 @@ export class ComputerUse extends EventEmitter {
     // app (main vs renderer/GPU), so the worker is also given the executable path, which
     // recognises every process of the app at once. The worker refuses to drive any window of
     // either; one-shot CLI runs (no env) keep the guard disabled.
-    const env = { ...process.env, DSH_CU_HOST_PID: String(process.pid), DSH_CU_HOST_EXE: process.execPath || '' }
+    this.spawnRuntime = nativeRuntimeIdentity(this.workerExe)
+    const env = { ...process.env, DSH_CU_HOST_PID: String(process.pid), DSH_CU_HOST_EXE: process.execPath || '',
+      DSH_CU_PACKAGE_VERSION: this.spawnRuntime.packageVersion, DSH_CU_BUILD_ID: this.spawnRuntime.buildId,
+      DSH_CU_SOURCE_HASH: this.spawnRuntime.sourceHash || '', DSH_CU_BINARY_HASH: this.spawnRuntime.binaryHash }
     this.log(`[core] host guard armed for pid ${process.pid} (${process.execPath})`)
     this.proc = spawn(this.workerExe, [], { env, windowsHide: true, stdio: ['pipe', 'pipe', 'pipe'] })
     // A CHILD THAT FAILS TO START MUST NAME ITSELF (2026-09-13). Every computer_* tool died with a
@@ -176,22 +202,34 @@ export class ComputerUse extends EventEmitter {
     this.proc.stderr.on('data', (d) => this.log(`[worker:stderr] ${d}`))
     this.proc.on('exit', (code) => { if (this.proc === child) this.onWorkerExit(code) })
     return new Promise((resolve, reject) => {
-      const t = setTimeout(() => reject(new Error('worker ready timeout')), 10_000)
-      // surface the real reason instead of letting the raw emitter error escape
-      this.proc.once('error', (e) => {
+      const finish = (error) => {
         clearTimeout(t)
-        reject(new Error(`worker could not be started: code=${e.code} syscall=${e.syscall} path=${e.path || this.workerExe}`))
-      })
-      this.once('ready', () => { clearTimeout(t); resolve() })
-      this.once('dead', (code) => { clearTimeout(t); reject(new Error(`worker died at startup (code ${code})`)) })
+        this.off('ready', ready); this.off('dead', dead); this.off('worker-incompatible', incompatible)
+        child.off('error', failed)
+        if (error) reject(error); else resolve()
+      }
+      const ready = () => finish()
+      const dead = code => finish(new Error(`worker died at startup (code ${code})`))
+      const incompatible = error => finish(error)
+      const failed = e => finish(new Error(`worker could not be started: code=${e.code} syscall=${e.syscall} path=${e.path || this.workerExe}`))
+      const t = setTimeout(() => {
+        finish(new Error('worker ready timeout'))
+        try { if (this.proc === child) child.kill() } catch { /* already gone */ }
+      }, 10_000)
+      // surface the real reason instead of letting the raw emitter error escape
+      child.once('error', failed)
+      this.once('ready', ready); this.once('dead', dead); this.once('worker-incompatible', incompatible)
     })
   }
 
   onWorkerExit (code) {
     this.ready = false
     this.proc = null
+    this.workerStateInvalid = true
+    this.cooperation = { phase: 'unknown', active: false, revision: 0, valid: false, workerGeneration: this.workerGeneration }
+    this.maps.clear(); this.lastMarks = []; this.lastMarkFrame = null
     this.finishUiaRead(false)
-    for (const [id, p] of this.pending) { clearTimeout(p.timer); p.cleanup?.(); p.reject(workerCallError('worker exited', 'worker-exited', p.op, id)) }
+    for (const [id, p] of this.pending) { clearTimeout(p.timer); p.cleanup?.(); p.reject(Object.assign(workerCallError('worker exited', 'worker-exited', p.op, id), { workerGeneration: p.workerGeneration, cleanup: { cleanupConfirmed: false, cleanupState: 'worker-exited' } })) }
     this.pending.clear()
     this.emit('dead', code)
   }
@@ -200,6 +238,17 @@ export class ComputerUse extends EventEmitter {
     let msg
     try { msg = JSON.parse(line) } catch { this.log(`[worker:badline] ${line.slice(0, 200)}`); return }
     if (msg.event === 'ready') {
+      // Production spawns must speak the ordered protocol. An old custom binary
+      // cannot safely participate in cancellation or generation-aware recovery.
+      if (this.spawnRuntime && (msg.protocolVersion !== 2 || typeof msg.workerGeneration !== 'string' ||
+          !msg.workerGeneration || !Number.isSafeInteger(msg.cooperation?.stateSeq) ||
+          msg.cooperation.workerGeneration !== msg.workerGeneration)) {
+        this.ready = false; this.workerStateInvalid = true
+        this.emit('worker-incompatible', workerCallError('native worker protocol is incompatible; reinstall or rebuild the current helper',
+          'WORKER_PROTOCOL_INCOMPATIBLE', null, null, 'not-dispatched'))
+        try { this.proc?.kill() } catch { /* already gone */ }
+        return
+      }
       this.ready = true
       // COLD-START STATE SYNC (cold-start bug, 2026-09-13): the worker has already adopted any STOP
       // or EXITED record that predates this process, and it reports that state with `ready`. Without
@@ -209,10 +258,20 @@ export class ComputerUse extends EventEmitter {
       // released — the mirror simply starts out agreeing with the machine.
       if (typeof msg.stopped === 'boolean') this.stopped = msg.stopped
       if (typeof msg.exited === 'boolean') this.exited = msg.exited
-      this.cooperation = msg.cooperation || { phase: 'idle', active: false, revision: 0 }
+      this.workerGeneration = msg.workerGeneration || msg.runtime?.workerGeneration || msg.cooperation?.workerGeneration || null
+      this.nativeStateSeq = -1
+      this.runtime = this.spawnRuntime ? { ...this.spawnRuntime, ...msg.runtime, workerGeneration: this.workerGeneration } : msg.runtime || null
+      this.cooperation = { phase: 'idle', active: false, revision: 0 }
+      this.workerStateInvalid = false
+      if (msg.cooperation) this.syncCooperation(msg.cooperation, false)
+      this.maps.clear(); this.lastMarks = []; this.lastMarkFrame = null
       this.emit('ready', msg)
       return
     }
+    // stdout from a replaced child is already filtered; generation also guards
+    // protocol-level delayed events and records restored by an observer.
+    const generation = msg.workerGeneration || msg.cooperation?.workerGeneration || msg.data?.cooperation?.workerGeneration
+    if (generation && this.workerGeneration && generation !== this.workerGeneration) return
     if (msg.event === 'handoff') {
       this.syncCooperation(msg.cooperation)
       return
@@ -262,6 +321,7 @@ export class ComputerUse extends EventEmitter {
       const error = workerCallError(msg.error || 'worker error', msg.code || 'worker-refusal-or-error', p.op, msg.id,
         msg.outcome === 'not-dispatched' ? 'not-dispatched' : 'unknown')
       if (msg.glowHealth) error.glowHealth = msg.glowHealth
+      for (const key of ['dragStarted', 'expectedCursor', 'actualCursor', 'cursorCheck']) if (msg[key] !== undefined) error[key] = msg[key]
       p.reject(error.code === 'HUMAN_REOBSERVE' ? humanReobserveError(error) : error)
     }
   }
@@ -273,13 +333,51 @@ export class ComputerUse extends EventEmitter {
    * @param {boolean} [killOnTimeout] kill a wedged worker when that cap expires (default true)
    * @returns {Promise<any>} worker `data` payload
    */
+  // Cleanup runs under its own explicit authority. A cancelled user context must
+  // not block key release or the closing of a question; ordinary tools never use it.
+  callInternal (op, args = {}, timeoutMs = DEFAULT_TIMEOUT_MS, killOnTimeout = true, beforeDispatch) {
+    if (!['cancelInput', 'calm', 'endAsk', 'abort'].includes(op)) throw new Error('unsupported internal cleanup operation')
+    return this.inputContext.run({ internalCleanup: true }, () => this.call(op, args, timeoutMs, killOnTimeout, beforeDispatch))
+  }
+
+  async cancelRequest (requestId, child, reason, killOnFailure = true) {
+    const cleanup = { requestId, workerGeneration: this.workerGeneration, requested: true,
+      cleanupConfirmed: false, cleanupState: 'unconfirmed', workerKilled: false }
+    const sameWorker = () => {
+      if (this.proc !== child) throw Object.assign(new Error('original worker exited before cleanup'), { code: 'worker-replaced' })
+    }
+    try {
+      sameWorker()
+      const ack = await this.callInternal('cancelInput', { requestId }, this.inputCleanupGraceMs, false, sameWorker)
+      if (ack?.requestId !== undefined && ack.requestId !== requestId) throw new Error('cancellation acknowledgement named another request')
+      if (ack?.workerGeneration && ack.workerGeneration !== cleanup.workerGeneration) throw new Error('cancellation acknowledgement named another worker')
+      cleanup.cancelled = ack?.cancelled === true
+      cleanup.cleanupConfirmed = ack?.cleanupConfirmed === true && ack?.ownedInputCount === 0
+      cleanup.cleanupState = ack?.cleanupState || (cleanup.cleanupConfirmed ? 'released' : 'unconfirmed')
+      if (Number.isInteger(ack?.ownedInputCount)) cleanup.ownedInputCount = ack.ownedInputCount
+    } catch (error) {
+      cleanup.cleanupState = this.proc !== child ? 'worker-exited' : 'ack-failed'
+      cleanup.errorCode = error.code || 'cleanup-error'
+    }
+    if (!cleanup.cleanupConfirmed && killOnFailure && this.proc === child) {
+      cleanup.killReason = reason
+      try { cleanup.workerKilled = child.kill() !== false } catch { cleanup.workerKilled = false }
+    }
+    return cleanup
+  }
+
   async call (op, args = {}, timeoutMs = DEFAULT_TIMEOUT_MS, killOnTimeout = true, beforeDispatch) {
     const input = isInputOp(op, args)
-    const context = input ? this.inputContext.getStore() : undefined
+    const priorGeneration = this.workerGeneration
+    const invalidAtStart = this.workerStateInvalid
+    const context = this.inputContext.getStore()
     const signal = context?.signal
-    if (signal?.aborted) throw workerCallError('owning tool cancelled', 'INPUT_CANCELLED', op, null, 'not-dispatched')
-    beforeDispatch?.()
-    context?.assertOwnership?.()
+    const check = () => {
+      if (signal?.aborted) throw workerCallError('owning tool cancelled', 'INPUT_CANCELLED', op, null, 'not-dispatched')
+      beforeDispatch?.()
+      context?.assertOwnership?.()
+    }
+    check()
     try { await this.ensureWorker() }
     catch (error) { throw workerCallError(error.message || String(error), 'worker-unavailable', op, null, 'not-dispatched') }
     const child = this.proc
@@ -290,71 +388,73 @@ export class ComputerUse extends EventEmitter {
       if (this.proc !== child) throw workerCallError('worker exited before dispatch', 'worker-exited', op, null, 'not-dispatched')
       if (Date.now() >= queueDeadline) throw workerCallError('deadline expired waiting for the UIA read', 'worker-uia-busy', op, null, 'not-dispatched')
     }
-    if (signal?.aborted) throw workerCallError('owning tool cancelled', 'INPUT_CANCELLED', op, null, 'not-dispatched')
-    beforeDispatch?.()
-    context?.assertOwnership?.()
+    check()
+    if (input && (invalidAtStart || (priorGeneration && priorGeneration !== this.workerGeneration))) {
+      if (this.stopped || this.exited) throw workerCallError('manual pause/exit remains authoritative', 'ABORTED', op, null, 'not-dispatched')
+      throw workerReobserveError(this.workerGeneration, { op })
+    }
     const id = ++this.seq
-    // `__cycle` is this layer's SIGNATURE on a call made on the agent's behalf, and the worker
-    // opens (or keeps lit) a computer-use CYCLE only for signed calls. A one-shot
-    // `worker.exe --op click` from a shell script, or a deploy-time health probe, carries no
-    // signature — and so can never resurrect a session the human ended with Ctrl+Alt+Q. Stamped
-    // LAST so an op's own args can never forge it.
-    const signed = { ...args, __cycle: true }
-    signed.__kickoff = this.kickoffRequired
-    // One warning per external call/batch, with a fresh identity for each context.
-    // Never let a caller-supplied argument reuse another tool's announcement.
-    if (input) signed.__inputSeries = this.inputContext.getStore()?.inputSeries || randomUUID()
+    const generation = this.workerGeneration
+    if (input && context?.actionRecord) Object.assign(context.actionRecord, {
+      requestId: id, workerGeneration: generation, runtime: this.runtime,
+    })
+    // __cycle is signed last. A caller cannot forge another input series or turn.
+    const signed = { ...args, __cycle: context?.internalCleanup !== true, __kickoff: this.kickoffRequired }
+    if (input) signed.__inputSeries = context?.inputSeries || randomUUID()
     return new Promise((resolve, reject) => {
       let written = false
       const read = UIA_READS.has(op) && killOnTimeout ? (this.uiaRead = { id, child, timedOut: false }) : null
       const cleanup = () => signal?.removeEventListener('abort', abort)
-      const abort = () => {
+      const deferReadRecovery = () => {
+        if (!read || this.uiaRead !== read) return
+        read.timedOut = true
+        this.emit('uia-read-settled', false)
+        const grace = Math.min(timeoutMs, DEFAULT_TIMEOUT_MS)
+        read.watchdog = setTimeout(() => {
+          if (this.proc !== child || this.uiaRead !== read) return
+          this.log(`[core] UIA read ${id} (${op}) still blocked after ${grace}ms recovery grace; stopping worker pid=${child.pid}`)
+          try { child.kill() } catch { /* already gone */ }
+        }, grace)
+      }
+      const fail = async (code, message, timeout) => {
         if (!this.pending.delete(id)) return
         clearTimeout(timer); cleanup()
-        if (written) void this.call('cancelInput', { requestId: id }, 2000, false).catch(() => {})
-        reject(workerCallError('owning tool cancelled; accepted input must be inspected before any retry',
-          'INPUT_CANCELLED', op, id, written ? 'unknown' : 'not-dispatched'))
+        const error = workerCallError(message, code, op, id, input && written ? 'unknown' : 'not-dispatched')
+        error.operationDispatched = written
+        error.workerGeneration = generation
+        if (input && written) {
+          // Stop the original request out of band, then allow a bounded cleanup
+          // acknowledgement before killing a worker that may still own a key down.
+          error.cleanup = await this.cancelRequest(id, child, timeout ? 'input-timeout' : 'caller-cancelled', killOnTimeout)
+        } else if (read) {
+          deferReadRecovery()
+        } else if (timeout && killOnTimeout) {
+          try { if (this.proc === child) child.kill() } catch { /* already gone */ }
+        }
+        reject(error)
+      }
+      const abort = () => {
+        // beginAsk is a receipt-producing transaction: after dispatch we need
+        // its askId to release the exact brake. ask() checks cancellation before
+        // showing the card and always closes that receipt in its finally.
+        if (op === 'beginAsk' && written) return
+        void fail('INPUT_CANCELLED', 'owning tool cancelled; inspect any accepted input before retrying', false)
       }
       const timer = setTimeout(() => {
-        this.pending.delete(id)
-        cleanup()
-        if (read && this.uiaRead === read) {
-          read.timedOut = true
-          this.emit('uia-read-settled', false)
-          // Drop the response by id when it eventually arrives. A later reply for
-          // this id cancels only this watchdog, never a newer worker's deadline.
-          const grace = Math.min(timeoutMs, DEFAULT_TIMEOUT_MS)
-          read.watchdog = setTimeout(() => {
-            if (this.proc !== child || this.uiaRead !== read) return
-            this.log(`[core] UIA read ${id} (${op}) still blocked after ${grace}ms recovery grace; stopping worker pid=${child.pid}`)
-            try { child.kill() } catch { /* already gone */ }
-          }, grace)
-          reject(workerCallError(`UIA observation timed out: ${op} (${timeoutMs}ms); worker still finishing this read. Narrow the tree or use a point query once it returns.`,
-            'worker-timeout', op, id, 'not-dispatched'))
-          return
-        }
-        // A CALL THAT RELEASES THE BRAKE MUST NOT BE KILLED FOR BEING SLOW. `proc.kill()` deletes no
-        // STOP file (there is no ProcessExit handler in worker.cs; `abort` is Environment.Exit(0) at
-        // worker.cs:3045), so killing here would end a question with the brake still up — the exact
-        // defect this design removes. Without the kill the worker is still alive, so the caller's
-        // retry, or the next op's SyncFromFile, can still finish the release.
-        //
-        // Everything else keeps today's behaviour: a timed-out op means the worker is wedged (a hung
-        // UIA/COM provider call blocks its single-threaded loop forever), so kill it and let the NEXT
-        // call respawn fresh instead of queueing behind a corpse; pending calls are rejected via
-        // onWorkerExit.
-        if (killOnTimeout) { try { if (this.proc === child) child.kill() } catch { /* already gone */ } }
-        reject(workerCallError(`worker timeout: ${op} (${timeoutMs}ms)` +
-          (killOnTimeout
-            ? ' — worker killed, next call respawns'
-            : ' — worker left alive so the brake can still be released'),
-        'worker-timeout', op, id))
+        const message = read
+          ? `UIA observation timed out: ${op} (${timeoutMs}ms); worker still finishing this read. Narrow the tree or use a point query once it returns.`
+          : `worker timeout: ${op} (${timeoutMs}ms)` + (input ? ' — cancellation and owned-input cleanup requested before worker recovery' : killOnTimeout ? ' — worker recovery requested' : ' — worker left alive so cleanup can finish')
+        void fail('worker-timeout', message, true)
       }, Math.max(0, queueDeadline - Date.now()))
-      this.pending.set(id, { resolve, reject, timer, op, input, cleanup, abort })
+      this.pending.set(id, { resolve, reject, timer, op, input, cleanup, abort, child, workerGeneration: generation })
       signal?.addEventListener('abort', abort, { once: true })
       if (signal?.aborted) { abort(); return }
-      written = true
-      child.stdin.write(JSON.stringify({ id, op, args: signed }) + '\r\n')
+      try {
+        written = true // a synchronous pipe failure still leaves dispatch uncertain
+        child.stdin.write(JSON.stringify({ id, op, args: signed }) + '\r\n')
+      } catch (error) {
+        void fail('worker-write-failed', 'worker input pipe rejected the request: ' + error.message, false)
+      }
     })
   }
 
@@ -392,34 +492,101 @@ export class ComputerUse extends EventEmitter {
   }
 
   async kill () {
+    const ownAttempt = this.inputContext.getStore()?.actionRecord?.attemptId
+    const actions = [...this.activeActions.entries()].filter(([id]) => id !== ownAttempt).map(([, settled]) => settled)
     this.emit('input-cancel')
-    if (!this.proc) return
-    try { await this.call('abort', {}, 1000) } catch { /* best effort */ }
-    try { this.proc.kill() } catch { /* already gone */ }
+    const child = this.proc
+    const bounded = async promise => {
+      let timer
+      try { return await Promise.race([promise.then(() => true), new Promise(resolve => { timer = setTimeout(() => resolve(false), this.shutdownGraceMs) })]) }
+      finally { clearTimeout(timer) }
+    }
+    if (child) {
+      let exited, detach
+      const death = new Promise(resolve => {
+        exited = resolve
+        if (typeof child.once === 'function') {
+          child.once('exit', exited); detach = () => child.off('exit', exited)
+        } else {
+          this.once('dead', exited); detach = () => this.off('dead', exited)
+        }
+      })
+      try {
+        const sameWorker = () => { if (this.proc !== child) throw new Error('original worker already exited') }
+        try { await this.callInternal('abort', {}, 1000, false, sameWorker) } catch { /* best effort */ }
+        if (this.proc === child) {
+          try { child.kill() } catch { /* failure is reported as unknown below */ }
+          if (!await bounded(death)) {
+            // Termination itself is uncertain. Settle local callers honestly so
+            // disposal cannot silently discard their final audit records.
+            for (const [id, pending] of this.pending) if (pending.child === child) {
+              this.pending.delete(id); clearTimeout(pending.timer); pending.cleanup?.()
+              pending.reject(Object.assign(workerCallError('worker shutdown did not confirm process exit', 'worker-shutdown-unconfirmed', pending.op, id),
+                { cleanup: { cleanupConfirmed: false, cleanupState: 'shutdown-unconfirmed' } }))
+            }
+          }
+        }
+      } finally { detach() }
+    }
+    // In-flight actuate() finally blocks emit the persistent settlement. Waiting
+    // for process exit alone is too early; never wait for the action invoking us.
+    await bounded(Promise.all(actions))
   }
 
   // ---------------- screen observation ----------------
-  syncCooperation (state) {
-    if (!state || Number(state.revision) < Number(this.cooperation.revision)) return
+  syncCooperation (state, notify = true) {
+    if (!state || this.workerStateInvalid) return false
+    if (state.workerGeneration && this.workerGeneration && state.workerGeneration !== this.workerGeneration) return false
+    if (Number.isSafeInteger(state.stateSeq)) {
+      if (state.stateSeq <= this.nativeStateSeq) return false
+    } else if (this.nativeStateSeq >= 0) return false // never downgrade an ordered worker
+    if (Number(state.revision) < Number(this.cooperation.revision)) return false
     if (Number(state.revision) === Number(this.cooperation.revision) && Number.isFinite(state.inputEpoch) &&
-        state.inputEpoch < (this.cooperation.inputEpoch || 0)) return
+        state.inputEpoch < (this.cooperation.inputEpoch || 0)) return false
+    if (Number.isSafeInteger(state.stateSeq)) this.nativeStateSeq = state.stateSeq
     const inputChanged = Number.isFinite(state.inputEpoch) && state.inputEpoch !== (this.cooperation.inputEpoch || 0)
     this.cooperation = state
     if (state.active || inputChanged) { this.maps.clear(); this.lastMarks = []; this.lastMarkFrame = null }
-    this.emit('handoff', state)
+    if (notify) this.emit('handoff', state)
+    return true
   }
 
   withInputContext (context, fn) {
-    return this.inputContext.run({ signal: context?.signal, assertOwnership: context?.assertOwnership, inputSeries: randomUUID() }, fn)
+    return this.inputContext.run({ signal: context?.signal, assertOwnership: context?.assertOwnership,
+      cycleId: context?.cycleId ?? null, sessionKey: context?.sessionKey ?? null, agentKey: context?.agentKey ?? null,
+      inputSeries: randomUUID() }, fn)
   }
 
   waitForHuman () {
     const signal = this.inputContext.getStore()?.signal
+    const started = performance.now()
+    const state = () => Object.fromEntries(['phase', 'active', 'revision', 'heldCount', 'lastKind', 'quietRemainingMs', 'inputEpoch']
+      .filter(key => this.cooperation[key] !== undefined).map(key => [key, this.cooperation[key]]))
+    const report = (phase, extra = {}) => {
+      const record = { ts: Date.now(), op: 'handoff-wait', phase, waitedMs: Math.round(performance.now() - started), cooperation: state(), ...extra }
+      try { this.emit('handoff-wait', record) } catch { /* diagnostics never own the wait */ }
+      return record
+    }
     return new Promise((resolve, reject) => {
+      let finished = false
       const events = ['handoff', 'panic', 'ask', 'exit', 'dead', 'input-cancel']
       const cleanup = () => { for (const event of events) this.off(event, listeners[event]); signal?.removeEventListener('abort', cancelled) }
-      const finish = (error) => { cleanup(); if (error) reject(error); else resolve() }
-      const cancelled = () => finish(workerCallError('waiting for the human was cancelled', 'INPUT_CANCELLED', null, null, 'not-dispatched'))
+      const finish = (error) => {
+        if (finished) return
+        finished = true
+        cleanup()
+        const record = report(error ? 'ended-with-error' : 'handback', error ? { code: error.code, cancelSource: error.cancelSource || null } : {})
+        if (error) { error.handoffWait = record; reject(error) } else resolve()
+      }
+      const cancelled = () => {
+        const source = signal?.aborted ? 'host-signal' : 'core-input-cancel'
+        const code = signal?.reason?.code || signal?.reason?.name
+        const reasonCode = typeof code === 'string' && /^[A-Za-z0-9_-]{1,64}$/.test(code) ? code : 'unspecified'
+        const snapshot = state()
+        const error = workerCallError(`waiting for the human was cancelled; source=${source}; reasonCode=${reasonCode}; waitedMs=${Math.round(performance.now() - started)}; phase=${snapshot.phase}; heldCount=${snapshot.heldCount ?? 'unknown'}. Cancellation ended the local wait; it does not explain why handback was delayed`, 'INPUT_CANCELLED', null, null, 'not-dispatched')
+        error.cancelSource = source
+        finish(error)
+      }
       const check = () => {
         if (signal?.aborted) return cancelled()
         if (this.stopped || this.exited) return finish(workerCallError('manual pause/exit remains authoritative', 'ABORTED', null, null, 'not-dispatched'))
@@ -430,11 +597,23 @@ export class ComputerUse extends EventEmitter {
         event === 'input-cancel' ? cancelled : check]))
       for (const event of events) this.on(event, listeners[event])
       signal?.addEventListener('abort', cancelled, { once: true })
+      report('started')
       check()
     })
   }
 
   async waitInputReady () {
+    if (this.workerStateInvalid) {
+      const context = this.inputContext.getStore()
+      if (context?.signal?.aborted) throw workerCallError('owning tool cancelled', 'INPUT_CANCELLED', null, null, 'not-dispatched')
+      context?.assertOwnership?.()
+      await this.ensureWorker()
+      if (context?.signal?.aborted) throw workerCallError('owning tool cancelled', 'INPUT_CANCELLED', null, null, 'not-dispatched')
+      context?.assertOwnership?.()
+      if (this.workerStateInvalid) throw workerCallError('native worker has not supplied a fresh ready snapshot', 'WORKER_STATE_UNAVAILABLE', null, null, 'not-dispatched')
+      if (this.stopped || this.exited) throw workerCallError('manual pause/exit remains authoritative', 'ABORTED', null, null, 'not-dispatched')
+      throw workerReobserveError(this.workerGeneration)
+    }
     if (!this.cooperation.active) return
     await this.waitForHuman()
     this.inputContext.getStore()?.assertOwnership?.()
@@ -482,8 +661,10 @@ export class ComputerUse extends EventEmitter {
     const active = (windows.windows || []).find(w => w.active) || null
     return {
       active, windows: windows.windows, cursor,
+      cooperation: windows.cooperation, indicator: windows.indicator, virtualScreen: windows.virtualScreen,
+      runtime: this.runtime, workerGeneration: this.workerGeneration,
       uiaRoot: uia && uia.root, uiaFlat: (uia && uia.flat) || [],
-      uiaCount: uia && uia.count, uiaTruncated: !uia || uia.truncated !== false, ts: Date.now(),
+      uiaCount: uia && uia.count, uiaTruncated: !uia || uia.truncated !== false, uiaBudget: uia?.budget, ts: Date.now(),
     }
   }
 
@@ -493,7 +674,8 @@ export class ComputerUse extends EventEmitter {
    * mark ids refer to the same observed map as the text table.
    */
   async marks (opts = {}) {
-    const map = opts.landmarkMap || await this.landmarks({ hwnd: opts.hwnd, depth: opts.uiaDepth ?? 14, maxNodes: opts.uiaMaxNodes ?? 1500 })
+    const map = opts.landmarkMap || await this.landmarks({ hwnd: opts.hwnd, depth: opts.uiaDepth ?? 6,
+      maxNodes: opts.uiaMaxNodes ?? 300, maxMarks: opts.maxMarks })
     await this.validateMarkFrame()
     const state = { active: { hwnd: map.hwnd }, cursor: await this.call('cursor', {}) }
     // capture FIRST so the visible region drives the ghost-mark filter:
@@ -519,17 +701,29 @@ export class ComputerUse extends EventEmitter {
       }, CAPTURE_TIMEOUT_MS)
       annotated = Buffer.from(res.image, 'base64')
     }
-    return { marks: markList, annotated, raw: opts.raw ? shot.image : undefined, state: { active: state.active, cursor: state.cursor }, ts: Date.now() }
+    return { marks: markList, annotated, raw: opts.raw || !annotated ? shot.image : undefined,
+      mime: annotated ? 'image/jpeg' : shot.mime, rawMime: shot.mime,
+      region: shot.region, imageSize: shot.imageSize, capturedAt: shot.capturedAt,
+      cursorInImage: shot.cursorInImage, scaledTo: shot.scaledTo,
+      settled: shot.settled, settleMs: shot.settleMs,
+      state: { active: state.active, cursor: state.cursor }, ts: shot.ts ?? Date.now() }
   }
 
   // ---------------- actions (all audited) ----------------
   async move (x, y) { return this.actuate('move', { x, y }) }
 
   async click (target, opts = {}) {
+    const witness = verificationRegion(opts.verificationRegion)
     const pt = await this.resolveTarget(target) // {x,y} | {mark:'M3'} | [x,y]
     return this.actuate('click', {
       x: pt.x, y: pt.y, button: opts.button || 'left', clicks: opts.clicks || 1,
       settleMs: opts.settleMs ?? 40,
+      ...(witness ? { verificationRegion: witness } : {}),
+      // Embedded renderers (a WeChat article panel, an Electron child) belong to a DIFFERENT
+      // process than the window that hosts them, so the occlusion check reads them as "covered"
+      // even though the pixel is inside the app the caller activated. The worker already
+      // implements the escape hatch; forward it, or a whole class of real apps is unclickable.
+      ...(opts.allowCovered ? { allowCovered: true } : {}),
       ...((pt.expectHwnd || opts.expectHwnd) ? { expectHwnd: pt.expectHwnd || opts.expectHwnd } : {}),
     })
   }
@@ -537,7 +731,8 @@ export class ComputerUse extends EventEmitter {
   async drag (from, to, opts = {}) {
     const a = await this.resolveTarget(from)
     const b = await this.resolveTarget(to)
-    return this.actuate('drag', { fromX: a.x, fromY: a.y, toX: b.x, toY: b.y, ...opts })
+    return this.actuate('drag', { fromX: a.x, fromY: a.y, toX: b.x, toY: b.y, ...opts,
+      ...((a.expectHwnd || opts.expectHwnd) ? { expectHwnd: a.expectHwnd || opts.expectHwnd } : {}) })
   }
 
   async scroll (direction, lines, opts = {}) {
@@ -554,7 +749,9 @@ export class ComputerUse extends EventEmitter {
   // Anchor-based selection: click the START, scroll freely, then shift+click the END.
   // Replaces drag-select, whose end point depends on drag duration and auto-scroll speed.
   async shiftClick (x, y, opts = {}) {
+    const witness = verificationRegion(opts.verificationRegion)
     return this.actuate('shiftClick', { x, y, clicks: opts.clicks || 1, settleMs: opts.settleMs ?? 90,
+      ...(witness ? { verificationRegion: witness } : {}),
       ...(opts.expectHwnd ? { expectHwnd: opts.expectHwnd } : {}) })
   }
 
@@ -576,7 +773,7 @@ export class ComputerUse extends EventEmitter {
    * emergency brake. Called when the agent's turn ends, so a lingering blue border can never
    * claim the machine is still under control after control actually stopped.
    */
-  async calm ({ beforeDispatch } = {}) { return this.call('calm', {}, DEFAULT_TIMEOUT_MS, true, beforeDispatch) }
+  async calm ({ beforeDispatch } = {}) { return this.callInternal('calm', {}, DEFAULT_TIMEOUT_MS, true, beforeDispatch) }
 
   /// **Ask the human one question, machine paused — the ONE question path.**
   ///
@@ -621,10 +818,17 @@ export class ComputerUse extends EventEmitter {
       this._askOpen = null
     }
     const askId = b && b.askId
+    const askWorker = this.proc
+    const sameAskWorker = () => {
+      if (this.proc !== askWorker) throw Object.assign(new Error('question worker exited; its askId cannot release a replacement worker'), { code: 'worker-replaced' })
+    }
     let answer = null
     let rel = null
     let via = 'ok'
     try {
+      const context = this.inputContext.getStore()
+      if (context?.signal?.aborted) throw workerCallError('owning tool cancelled after the ask brake was engaged', 'INPUT_CANCELLED', 'beginAsk', null, 'unknown')
+      context?.assertOwnership?.()
       answer = await opts.onAsk({ askId, hostRaised: !!(b && b.hostRaised), caretPlaced: !!(b && b.caretPlaced) })
       // `via` is an AUDIT LABEL ONLY — it decides nothing. The pause decision is `keepPause`, and it
       // comes from the human: ①让你停 keeps the brake, and every other ending (②放你走, a typed custom
@@ -649,14 +853,14 @@ export class ComputerUse extends EventEmitter {
       // reply describes a machine that no longer exists and must not be applied on top of it.
       const beforeRelease = this.stateSeq
       try {
-        rel = await this.call('endAsk', { askId, via, keepPause }, END_ASK_DEADLINE_MS, /* killOnTimeout */ false)
+        rel = await this.callInternal('endAsk', { askId, via, keepPause }, END_ASK_DEADLINE_MS, /* killOnTimeout */ false, sameAskWorker)
       } catch (e) {
         // ONE retry: the first attempt may have timed out against a briefly busy worker. A second
         // failure is not swallowed — the audit pair (ENGAGE-ASK with no ASK-RELEASE) is the signal,
         // and the orphan sweep is the backstop. NEVER a kill here (killOnTimeout:false above): the
         // dead worker's STOP file would outlive every waiter, which is the defect being removed.
         try {
-          rel = await this.call('endAsk', { askId, via: via + '+retry', keepPause }, END_ASK_DEADLINE_MS, false)
+          rel = await this.callInternal('endAsk', { askId, via: via + '+retry', keepPause }, END_ASK_DEADLINE_MS, false, sameAskWorker)
         } catch (e2) {
           this.log(`[ask] endAsk failed twice: ${e2.message} — the brake may need the orphan sweep (the next worker call sweeps it, or the human's Ctrl+Alt+R)`)
         }
@@ -726,7 +930,7 @@ export class ComputerUse extends EventEmitter {
     const hwnd = fs.hwnd
     if (!hwnd || (!fs.sig && !uiaOnly)) throw staleMark('window snapshot unavailable')
     const cached = this.maps.get(String(hwnd))
-    const key = JSON.stringify([opts.depth ?? 14, opts.maxNodes ?? 1500, opts.maxMarks ?? 80, opts.minSize ?? 8, opts.role, opts.nameContains, uiaOnly])
+    const key = JSON.stringify([opts.depth ?? 6, opts.maxNodes ?? 300, opts.maxMarks ?? 80, opts.minSize ?? 8, opts.role, opts.nameContains, uiaOnly])
     if (cached && sameMarkFrame(cached.frame, fs) && cached.key === key && !opts.refresh) {
       this.lastMarks = cached.marks
       this.lastMarkFrame = { ...fs, step, insetPct }
@@ -734,8 +938,8 @@ export class ComputerUse extends EventEmitter {
     }
     const uia = await this.call('uia', {
       hwnd: hwnd || undefined,
-      depth: opts.depth ?? 14,
-      maxNodes: opts.maxNodes ?? 1500,
+      depth: opts.depth ?? 6,
+      maxNodes: opts.maxNodes ?? 300,
       role: opts.role,
       nameContains: opts.nameContains,
     })
@@ -796,7 +1000,7 @@ export class ComputerUse extends EventEmitter {
   async calibrate (opts = {}) { return this.actuate('calibrate', opts) }
 
   async key (combo, opts = {}) {
-    return this.actuate('key', { combo, holdMs: opts.holdMs ?? 60, ...(opts.expectHwnd ? { expectHwnd: opts.expectHwnd } : {}) })
+    return this.actuate('key', { combo: parseKeyCommand(combo).combo, holdMs: opts.holdMs ?? 60, ...(opts.expectHwnd ? { expectHwnd: opts.expectHwnd } : {}) })
   }
 
   async type (text, opts = {}) {
@@ -832,6 +1036,32 @@ export class ComputerUse extends EventEmitter {
   async ocr (region) { return this.call('ocr', region ? { ...region } : {}) }
   async clipWrite (text) { return this.actuate('clipWrite', { text }) }
 
+  /** Open an app/URL/folder/document through ShellExecute, as a real actuation: the halo,
+   *  the brake checks, the audit trail and the rate window all come from actuate() — which
+   *  is exactly why this is an op and not a Node-side spawn (see worker.cs Launch). */
+  async launch (target, opts = {}) {
+    // `args` is an ARRAY of argument values (quoted once, in the worker). Passing a ready-made
+    // command line would make the launcher parse our boundaries differently than the caller meant.
+    return this.actuate('launch', {
+      target,
+      ...(opts.args !== undefined ? { args: opts.args } : {}),
+      ...(opts.tailMs !== undefined ? { tailMs: opts.tailMs } : {}),
+    })
+  }
+
+  /** Put keyboard focus on a FIELD and prove it: clicks (x,y), then reports the UIA focused
+   *  element and whether a caret is provable there (OS caret, else a two-frame blink check).
+   *  Refuse to type when `verified` is false — typing follows the focused control, not the
+   *  window, and a document that kept focus silently swallows the text. */
+  async focusField (opts = {}) {
+    return this.actuate('focusField', {
+      x: opts.x,
+      y: opts.y,
+      ...(opts.hwnd !== undefined ? { hwnd: opts.hwnd } : {}),
+      ...(opts.verifyCaret !== undefined ? { verifyCaret: opts.verifyCaret } : {}),
+    })
+  }
+
   async activateWindow (sel) { return this.actuate('activate', sel) }
   async windowOp (sel, op, opts = {}) { return this.actuate('windowOp', { ...sel, op, ...opts }) }
   /** Deterministic placement (no mouse): move/resize a window to an arbitrary rect. */
@@ -865,52 +1095,73 @@ export class ComputerUse extends EventEmitter {
 
   /** Every state-changing op funnels through here for the audit trail. */
   async actuate (op, args) {
-    await this.waitInputReady()
-    if (this.dryRun) {
-      const rec = { op, args: redact(args), ts: Date.now(), dryRun: true }
-      this.emit('action', rec)
-      return { dryRun: true, op }
-    }
-    const now = Date.now()
-    this.rateWindow = this.rateWindow.filter(t => now - t < this.rateLimit.windowMs)
-    if (this.rateWindow.length >= this.rateLimit.max) {
-      throw new Error(`rate limit: ${this.rateLimit.max} actuations/${this.rateLimit.windowMs}ms exceeded`)
-    }
-    this.rateWindow.push(now)
-    const rec = { op, args: redact(args), ts: Date.now() }
-    this.emit('action', rec)
-    try {
-      const data = await this.call(op, args)
-      rec.result = data
-      return data
-    } catch (err) {
-      if (err.code === 'HUMAN_YIELD') {
-        // The hook's event can arrive just after its operation refusal. One cheap local
-        // status read closes that race; waiting spends no model requests and never replays input.
-        try {
-          await this.call('ping', {})
-          await this.waitForHuman()
-          this.inputContext.getStore()?.assertOwnership?.()
-          err = humanReobserveError({ ...err, op })
-        } catch (waitError) {
-          // Cancelling the local wait cannot erase input already accepted before handoff.
-          err = workerCallError(waitError.message || String(waitError), waitError.code || 'handoff-wait-failed',
-            op, err.requestId ?? null, err.outcome === 'not-dispatched' ? 'not-dispatched' : 'unknown')
+    const parent = this.inputContext.getStore() || {}
+    const rec = { attemptId: randomUUID(), requestId: null, op, args: redact(args),
+      phase: 'started', ts: Date.now(), cycleId: parent.cycleId ?? null,
+      sessionKey: parent.sessionKey ?? null, agentKey: parent.agentKey ?? null,
+      workerGeneration: this.workerGeneration, runtime: this.runtime }
+    this.emit('action', { ...rec })
+    let settleAction
+    this.activeActions.set(rec.attemptId, new Promise(resolve => { settleAction = resolve }))
+    return this.inputContext.run({ ...parent, inputSeries: parent.inputSeries || randomUUID(), actionRecord: rec }, async () => {
+      try {
+        await this.waitInputReady()
+        if (this.dryRun) {
+          rec.dryRun = true; rec.outcome = 'not-dispatched'
+          return { dryRun: true, op }
         }
-      }
-      if (err.code === 'HUMAN_REOBSERVE') {
-        try { this.inputContext.getStore()?.assertOwnership?.() }
-        catch (ownerError) {
-          err = workerCallError(ownerError.message, ownerError.code || 'COMPUTER_OWNER_CHANGED', op,
-            err.requestId ?? null, err.outcome)
+        const now = Date.now()
+        this.rateWindow = this.rateWindow.filter(t => now - t < this.rateLimit.windowMs)
+        if (this.rateWindow.length >= this.rateLimit.max) {
+          throw workerCallError(`rate limit: ${this.rateLimit.max} actuations/${this.rateLimit.windowMs}ms exceeded`,
+            'RATE_LIMITED', op, null, 'not-dispatched')
+        }
+        this.rateWindow.push(now)
+        const data = await this.call(op, args)
+        rec.result = auditReceipt(data); rec.outcome = 'delivered'
+        return data
+      } catch (initial) {
+        let err = initial
+        if (err.code === 'HUMAN_YIELD') {
+          try {
+            await this.call('ping', {})
+            if (rec.workerGeneration && rec.workerGeneration !== this.workerGeneration) {
+              throw workerReobserveError(this.workerGeneration, { ...err, op })
+            }
+            await this.waitForHuman()
+            this.inputContext.getStore()?.assertOwnership?.()
+            err = humanReobserveError({ ...err, op })
+          } catch (waitError) {
+            err = waitError.code === 'WORKER_REOBSERVE' ? waitError : Object.assign(workerCallError(waitError.detail || waitError.message || String(waitError), waitError.code || 'handoff-wait-failed',
+              op, err.requestId ?? null, err.outcome === 'not-dispatched' ? 'not-dispatched' : 'unknown'),
+            { ...(waitError.handoffWait ? { handoffWait: waitError.handoffWait } : {}),
+              ...(waitError.cancelSource ? { cancelSource: waitError.cancelSource } : {}),
+              ...(waitError.cleanup ? { cleanup: waitError.cleanup } : {}) })
+          }
         }
+        if (err.code === 'HUMAN_REOBSERVE' || err.code === 'WORKER_REOBSERVE') {
+          try { this.inputContext.getStore()?.assertOwnership?.() }
+          catch (ownerError) {
+            err = workerCallError(ownerError.message, ownerError.code || 'COMPUTER_OWNER_CHANGED', op,
+              err.requestId ?? null, err.outcome)
+          }
+        }
+        // UIA/native errors may echo names, values or typed text. The caller gets
+        // the original exception; the persistent audit records a bounded code.
+        rec.code = auditCode(err.code); rec.error = rec.code
+        rec.outcome = err.outcome || 'unknown'
+        if (err.requestId != null) rec.requestId = err.requestId
+        if (err.cleanup) rec.cleanup = err.cleanup
+        if (err.handoffWait) rec.handoffWait = err.handoffWait
+        throw err
+      } finally {
+        rec.phase = 'settled'; rec.settledAt = Date.now(); rec.elapsedMs = rec.settledAt - rec.ts
+        try { this.emit('action:settled', { ...rec }) }
+        finally { this.activeActions.delete(rec.attemptId); settleAction() }
       }
-      rec.error = String(err.message || err)
-      throw err
-    } finally {
-      this.emit('action:settled', rec)
-    }
+    })
   }
+
 }
 
 function staleMark (reason) {
@@ -930,10 +1181,25 @@ function sameMarkFrame (a, b) {
 
 /** Keep secrets out of the audit log. */
 function redact (args) {
-  if (args && typeof args.text === 'string' && args.text.length > 0) {
-    return { ...args, text: `<${args.text.length} chars>` }
-  }
-  return args
+  if (!args || typeof args !== 'object') return {}
+  const safeStrings = new Set(['combo', 'button', 'direction', 'action', 'mode', 'preset', 'property'])
+  return Object.fromEntries(Object.entries(args).map(([key, value]) => [key,
+    typeof value === 'string' ? safeStrings.has(key) ? value.slice(0, 128) : `<${value.length} chars>` :
+      typeof value === 'number' || typeof value === 'boolean' || value === null ? value : '<structured value>']))
+}
+
+function auditCode (code) {
+  return typeof code === 'string' && /^[A-Za-z0-9_-]{1,64}$/.test(code) ? code : 'action-error'
+}
+
+// Explicit receipt allowlist: never persist screenshots, focus/UIA objects,
+// clipboard content, passwords, arbitrary strings or provider result trees.
+function auditReceipt (data) {
+  if (!data || typeof data !== 'object') return {}
+  const keys = ['ok', 'delivered', 'count', 'chars', 'typed', 'clicked', 'moved', 'settled',
+    'elapsedMs', 'durationMs', 'hwnd', 'x', 'y', 'width', 'height', 'dryRun']
+  return Object.fromEntries(keys.filter(key => typeof data[key] === 'boolean' ||
+    (typeof data[key] === 'number' && Number.isFinite(data[key]))).map(key => [key, data[key]]))
 }
 
 /**
@@ -946,6 +1212,7 @@ function buildMarks (flat, maxMarks = 60, minSize = 8) {
   const interactive = []
   for (const e of flat) {
     if (interactive.length >= maxMarks) break
+    if (e.isOffscreen === true || e.intersectsVirtualScreen === false) continue
     const r = e.rect || {}
     const name = (e.name || '').replace(/\s*\r\n\s*/g, ' | ').trim()
     const key = `${e.role}|${name}|${r.x},${r.y}`