dsh-codex-style-computer-use 2.2.5 → 2.2.7

package/README.md

@@ -187,7 +187,7 @@ fields are detected through UI Automation's `IsPassword` and refused by default.
 ## Safety model
 
 - **Shared input** — ordinary user activity is allowed while the agent is thinking, observing or preparing. During actual actuation, typing, scrolling and buttons yield immediately; pointer movement has a 16-pixel displacement tolerance. Continued input or a held key/button for 2 seconds enters automatic waiting. After release and 3 quiet seconds, the agent must inspect the current target and continue the original task, without blindly replaying partial writes. A gentle pale-yellow edge gradient shows human ownership.
-- **Release by the next action, not by task completion** — while a cycle is open, if the next call does not need the mouse, keyboard, UI Automation, a screenshot or the same live clipboard, call `computer_ctrl {action:"release"}` first. A shell/file/network/npm/chat/analysis step is not a desktop action. The lease ends when the desktop artifact is obtained (token/clipboard text, a value, a path, a saved file, a verified field, a captured image), not when the user's whole task ends. Do not hold "in case I need the desktop later"; reacquiring is cheap and a later need starts a fresh cycle. An explicit `hold` is the only exception; `free` then `release` when done.
+- **Release by desktop block, not by every call** — one cycle covers one continuous desktop block, not the whole task. When you leave that block for publish, upload, install, build, test, network, a file write, analysis or chat, call `computer_ctrl {action:"release"}` first. Keep the cycle only while the next call is still in the same block, including one quick readback you type straight back. An artifact in hand (token, clipboard text, value, path, screenshot) is a signal that the block may be ending, not an automatic release point. Do not hold "in case I need the desktop later"; reacquiring the lease is cheap, while a lit border and an exclusive lease during a long command are not. `hold` is only for position-sensitive readback inside the block, never across a build/publish/upload or long command; `free` then `release`. A deterministic **100-second leave backstop** (`leaveDesktopGraceMs`; 0 disables) releases the lease if no `computer_*` call starts within the grace after a non-desktop tool; it is owner-scoped, cancelled by an actual computer start, never releases a newer cycle, and `hold` does not extend it.
 - **Manual pause** — only physical `Ctrl+Esc` raises a persistent input brake; `Ctrl+Alt+R` resumes. Ordinary Esc, typing, scrolling, pointer distance/frequency and the screen corner do not create this pause. Explicit question/diagnostic holds remain separate.
 - **Exit** — `Ctrl+Alt+Q` ends the session: the overlay goes away, its listeners are torn down, and
   further actuation is refused until a later turn opens a new one.
@@ -216,6 +216,7 @@ fields are detected through UI Automation's `IsPassword` and refused by default.
 | `actionFeedbackDetail` | `compact` | `compact`, `full` or `none`; a call's `feedback` overrides this default; uncached evidence falls back to full inline output |
 | `dryRun` | `false` | simulate actuations, log only |
 | `maxActionsPerMinute` | `60` | core-level actuation rate limit |
+| `leaveDesktopGraceMs` | `100000` | grace after leaving the desktop for another tool; automatic lease expiry, `0` disables |
 | `annotateMarks` | `true` | draw Set-of-Marks boxes on screenshots |
 | `workerExe` | `""` | explicit worker path; empty = autodiscover or compile |
 | `snapshotDir` | `""` | screenshot directory; empty = `$DSH_HOME/data/computer-use/shots` |

package/README.zh.md

@@ -178,8 +178,7 @@ ID**：派发输入前会核对窗口身份与采样像素，因此过期的 mar
 ## 安全模型
 
 - **人机共用输入** —— 思考、观察和预告期间允许用户正常操作。实际操控时，键盘、滚轮和按钮立即触发让出；鼠标位移有 16 像素容差。持续输入或按住键/按钮 2 秒进入自动等待；全部松开并静默 3 秒后，agent 必须重新观察并接续原任务，不盲目重放部分写入。人操作时显示温和的淡黄色边缘渐变。
-- **用完即释放（按下一步判断）** —— 只要下一步不需要鼠标、键盘、UIA、截图或同一份剪贴板，就先 `computer_ctrl {action:"release"}`，再去做 shell、文件、网络、npm 或聊天；不要一边处理桌面产物一边持有桌面。拿到 token/值/路径/截图/已保存文件就是本次桌面租约的结束点，不是等整个任务做完；重新获取很便宜。`release` 只结束电脑控制，聊天继续；正常收尾自动释放，不弹确认选项单。暂停和待回答问题不会被自动清除。
-- **不要“等会儿可能还要用”而持有** —— 明确的 `computer_ctrl {action:"hold"}` 是唯一例外；`free` 后立刻 `release`。如果已经调用了非 `computer_*` 工具而 cycle 还开着，说明漏了释放，应立即 release。
+- **按“桌面块”释放，不按每次调用** —— 一个 cycle 覆盖一段连续的桌面工作，不是整个任务。离开这一段去做发布、上传、安装、构建、测试、网络、写文件、分析或聊天时，先 `computer_ctrl {action:"release"}`；只有下一步仍是同一桌面块里的普通点击/输入，或一次很快的读数后马上输入回去，才保留 cycle。拿到的 token/值/路径/截图只是“这块可能快结束了”的信号，不是自动释放点；如果下一步是粘贴/回读/继续点，就保留。不要为了“等会儿可能还要用”而持有；重新获取租约很便宜，长命令期间亮着边框和独占锁并不便宜。`hold` 只用于块内对位置敏感的读数，不能跨 build/publish/upload 或长命令；`free` 后 release。插件另有 **100 秒离开计时兜底**（`leaveDesktopGraceMs`，0 可关）：非桌面工具开始后若 100 秒内没有 `computer_*` 调用，插件会 owner-checked 地自动释放；它会在真实 computer 调用开始时取消、不会释放新 cycle，`hold` 也不延长它。暂停和待回答问题不会被自动清除。
 - **一个操作者** —— 会话／agent 所有权与跨 worker 独占锁覆盖整个控制周期，另一 agent 必须等当前操作者释放。
 - **人工暂停** —— 只有实体 `Ctrl+Esc` 触发持续输入刹车，`Ctrl+Alt+R` 恢复。普通 Esc、打字、滚动、鼠标距离/频率和屏幕左上角不再触发这种暂停；显式提问、诊断暂停保持独立。
 - **退出** —— `Ctrl+Alt+Q` 结束会话：覆盖层消失、监听全部拆除，后续注入被拒，直到之后某一轮重新开启。
@@ -198,6 +197,7 @@ ID**：派发输入前会核对窗口身份与采样像素，因此过期的 mar
 | `actionFeedbackDetail` | `compact` | `compact`、`full` 或 `none`；单次调用的 `feedback` 可覆盖默认值；无法缓存时完整内联返回证据 |
 | `dryRun` | `false` | 只模拟操作并记录 |
 | `maxActionsPerMinute` | `60` | 核心层操作限速 |
+| `leaveDesktopGraceMs` | `100000` | 离开桌面去执行非桌面工具后的租约宽限；超时自动释放，`0` 关闭 |
 | `annotateMarks` | `true` | 在截图上绘制 Set-of-Marks 方框 |
 | `workerExe` | `""` | 显式指定 worker 路径；留空则自动发现或编译 |
 | `snapshotDir` | `""` | 截图目录；留空为 `$DSH_HOME/data/computer-use/shots` |

package/lib/cycle.js

@@ -30,10 +30,12 @@
 // only on EVIDENCE that the identity is over (`forgetIdentity`, wired to agent/session disposal),
 // and a forgotten identity is marked DEAD so a late call from it is refused rather than trusted.
 //
-// NO TIME-BASED POLICY LIVES HERE EITHER. `openedAt`/`lastAt` are diagnostics only; a paused cycle is
-// never transferred to another session because time passed ("暂停只能由人的恢复/终结解除，时间不是授权").
+// NO IDLE-TIME POLICY LIVES HERE. `openedAt`/`lastAt` are diagnostics only; a paused cycle is never
+// transferred to another session because time passed ("暂停只能由人的恢复/终结解除，时间不是授权").
 // Ownership is released by FACTS: the owner's turn completing, its agent going idle, its identity
-// being disposed, or an exit.
+// being disposed, or an exit. The separate leave timer (lib/leave-timer.js) is not an idle timeout:
+// it is armed only when a non-computer tool starts while the cycle is open, cancelled by any actual
+// computer_* start, retries refusals, and releases only the captured cycle id.
 
 /** Session identity without assuming the host's shape (id may be a string, or a field on an object). */
 export function sessionKeyOf (s) {

package/lib/index.js

@@ -39,6 +39,7 @@ import { scopeOf } from '@deepseek-ai/dsh-scope'
 import { createCycleGate, agentKeyOf } from './cycle.js'
 import { recoveryProblem } from './recovery.js'
 import { createCycleLifecycle } from './cycle-lifecycle.js'
+import { createLeaveTimer } from './leave-timer.js'
 import { createTerminalCleanup } from './terminal-cleanup.js'
 import fs from 'node:fs'
 
@@ -402,8 +403,11 @@ export const Config = Schema.object({
   workerExe: Schema.string().default('').description('explicit worker.exe path; empty = autodiscover/compile'),
   snapshotDir: Schema.string().default('').description('screenshot dir; empty = $DSH_HOME/data/computer-use/shots'),
   annotateMarks: Schema.boolean().default(true).description('draw SoM boxes on screenshots'),
-  // Compatibility with saved settings only. Elapsed time never ends a computer-use cycle.
-  calmAfterMs: Schema.number().default(0).description('legacy setting; ignored — computer-use cycles have no idle timeout'),
+  // Compatibility with saved settings only. Silence/elapsed time never ends a computer-use cycle.
+  calmAfterMs: Schema.number().default(0).description('legacy setting; ignored — silence never ends a cycle'),
+  // Narrow, explicit exception to the no-idle-timeout rule: armed by LEAVING the desktop for a
+  // non-computer tool, cancelled by any computer_* call; 0 disables it. See lib/leave-timer.js.
+  leaveDesktopGraceMs: Schema.number().default(100_000).description('release the desktop lease after this long away for another tool; 0 disables'),
   // Compatibility with saved settings; automatic completion has no question or timer.
   turnEndTimeoutAction: Schema.union([
     Schema.const('stop').description('legacy value; ignored'),
@@ -705,8 +709,16 @@ export function apply (ctx, config) {
     paused: pausedOrAsking, inFlight: () => inFlight,
     ownershipOf: exec => exec && typeof exec === 'object' ? callOwners.get(exec) : null,
   })
+  const leaveTimer = createLeaveTimer({
+    gate, claimOf, log,
+    notice: (...args) => notice(...args),
+    graceMs: config.leaveDesktopGraceMs,
+    setTimer: setTimeout, clearTimer: clearTimeout,
+    release: (exec, why, automatic, expected) => lifecycle.release(exec, why, automatic, expected),
+  })
   cu.on('handoff', () => {
     lifecycle.settle()?.catch(error => log.warn(`computer-use handback completion failed: ${error.message}`))
+    leaveTimer.retryNow()
   })
 
   const terminalCleanup = createTerminalCleanup({
@@ -727,9 +739,10 @@ export function apply (ctx, config) {
       }
       gate.assertOwnership(owner.claim, owner.cycleId)
     },
-    releaseCycle: (exec, why) => lifecycle.release(exec, why),
+    releaseCycle: (exec, why) => { leaveTimer.clear(); return lifecycle.release(exec, why) },
     onStart: (exec) => {
       inFlight++
+      leaveTimer.cancel(exec)
       if (isCycleStateOnly(exec?.name, exec?.arguments)) {
         callOwners.set(exec, { claim: claimOf(exec), cycleId: gate.snapshot().id })
       }
@@ -737,6 +750,7 @@ export function apply (ctx, config) {
     onEnd: () => {
       inFlight = Math.max(0, inFlight - 1)
       lifecycle.settle()?.catch(error => log.warn(`computer-use deferred completion failed: ${error.message}`))
+      leaveTimer.retryNow()
     },
     // ---- THE WRAP-UP DIRECTIVE (2026-09-15) --------------------------------------------------------
     // WHAT WENT WRONG. A human brake (ESC, a mouse shake, the wheel, typing outside the host) engaged
@@ -1119,6 +1133,7 @@ export function apply (ctx, config) {
       const whoKey = agentKeyOf(payload && payload.agent)
       if (whoKey && gate.ownsAgent(whoKey)) {
         log.info(`owner agent disposed (${whoKey}) — releasing the machine for the next real call`)
+        leaveTimer.onAgentDisposed(payload.agent)
         terminalCleanup.request('owner agent disposed')
       }
     } catch { /* never break the host */ }
@@ -1169,6 +1184,7 @@ export function apply (ctx, config) {
         log.info(`ignoring ${kind} turn/end from another session (${describeSession(session)})`)
         return
       }
+      leaveTimer.onTurnEnd(session)
       if (kind === 'aborted' || kind === 'interrupted') {
         if (selfAbortUntil && Date.now() < selfAbortUntil) {
           selfAbortUntil = 0
@@ -1195,6 +1211,10 @@ export function apply (ctx, config) {
   // pure function; its {kind: allow|deny|ask} rides the tools/pre-execute
   // waterfall into the harness approval UI (fail-closed, one-shot grants).
   ctx.on('tools/pre-execute', (exec, next) => {
+    // This hook is on the approval path. A timer bug must never deny a non-computer tool, so the
+    // leave timer runs in its own fail-open guard; the policy try/catch below stays fail-closed for
+    // computer_* calls only.
+    try { leaveTimer.observe(exec) } catch (error) { log.warn(`computer-use leave timer observe failed: ${error.message}`) }
     try {
       if (!exec || typeof exec.name !== 'string' || !exec.name.startsWith('computer_')) return next()
       if (exec.name === ACTIVATION_TOOL) return next() // capability discovery does not open a control cycle
@@ -1275,6 +1295,7 @@ export function apply (ctx, config) {
     }
   })
 
+  ctx.effect(() => () => leaveTimer.dispose())
   ctx.effect(() => {
     const disposer = () => { return cu.kill().catch(() => {}).finally(detachAudit) }
     return disposer
@@ -1285,5 +1306,5 @@ export function apply (ctx, config) {
   installToolExposure({ ctx, definitions, defineTool, scopeOf, log, enabled: config.progressiveTools !== false,
     skillPath: fileURLToPath(new URL('SKILL.md', SKILL_DIR_URL)),
     readSkill: () => fs.readFileSync(fileURLToPath(new URL('SKILL.md', SKILL_DIR_URL)), 'utf8') })
-  log.info(`ready (mode=${config.automationMode}${config.dryRun ? ' dry-run' : ''}; cycle idle timeout disabled)`)
+  log.info(`ready (mode=${config.automationMode}${config.dryRun ? ' dry-run' : ''}; cycle idle timeout disabled${config.leaveDesktopGraceMs ? `; leave timer ${config.leaveDesktopGraceMs} ms` : ''})`)
 }

package/lib/leave-timer.js

@@ -0,0 +1,201 @@
+// lib/leave-timer.js — the deterministic backstop for a cycle that is left open.
+//
+// WHY THIS EXISTS (2026-11-08). The skill's cycle-boundary rule is a decision rule, not an
+// enforcement mechanism: an agent can copy a desktop artifact and then run a long shell/network
+// command without releasing. The desktop lease then stays open, the border stays lit and every
+// other agent is blocked. The plugin already sees every top-level tool call, so when the agent
+// stays away from the desktop for long enough we release the lease ourselves.
+//
+// WHAT THIS IS NOT. It is not an idle timeout: mere thinking never arms it, and a paused/asking
+// cycle is never released by time. It is armed only when a tool that is not part of the desktop
+// block starts, then cancelled by any later computer_* call. A quick read → compute → type flow
+// therefore never releases, while a six-minute publish releases after the grace. Ownership is
+// captured at arm time and passed to release as the expected cycle, so a late timer can never
+// release a newer cycle. A refused release (pause/handoff/in-flight) is retried instead of being
+// silently consumed.
+
+/** Local bookkeeping / cheap inspection helpers that must not arm the leave timer. */
+export const LEAVE_TOOL_EXEMPT = new Set([
+  'todo_write',
+  'read',
+  'write',
+  'edit',
+  'glob',
+  'grep',
+  'run_code', // may wrap computer_* calls; the block-boundary skill covers that host shape
+  'ask_user_question',
+  'terminal_read',
+  'terminal_list',
+  'terminal_close',
+])
+
+/** Desktop observation helpers: using one means the agent is still in the desktop block. */
+const DESKTOP_HELPERS = new Set(['see_now', 'read_image'])
+
+export function createLeaveTimer ({
+  gate,
+  claimOf,
+  release,
+  graceMs = 100_000,
+  retryMs = 10_000,
+  setTimer = setTimeout,
+  clearTimer = clearTimeout,
+  log = { info () {}, warn () {} },
+  notice = () => {},
+} = {}) {
+  let timer = null
+  let retryTimer = null
+  let armed = null
+  let pending = null
+  let disposed = false
+
+  const unref = t => { try { t?.unref?.() } catch { /* host timer */ } }
+  const stop = t => { try { if (t) clearTimer(t) } catch { /* already gone */ } }
+  const isLive = () => !disposed && !!gate?.isLive?.()
+  const isOpen = () => isLive() && gate?.state?.() === 'open'
+  const owned = claim => !!claim && (
+    (!!claim.agentKey && !!gate?.ownsAgent?.(claim.agentKey)) ||
+    (!!claim.sessionKey && !!gate?.ownsSession?.(claim.sessionKey))
+  )
+  const dropTimer = () => { stop(timer); timer = null }
+  const dropRetry = () => { stop(retryTimer); retryTimer = null }
+
+  function clear () {
+    dropTimer()
+    dropRetry()
+    armed = null
+    pending = null
+  }
+
+  function cancel (exec) {
+    if (!armed && !pending && !timer && !retryTimer) return
+    if (exec) {
+      let claim
+      try { claim = claimOf(exec) } catch { return }
+      if (!owned(claim)) return // a foreign/denied computer call must not cancel the owner's timer
+    }
+    clear()
+    log.info?.('computer-use: leave timer cancelled by desktop activity')
+  }
+
+  function scheduleRetry () {
+    if (disposed || retryTimer || !pending || !isLive()) return
+    retryTimer = setTimer(() => {
+      retryTimer = null
+      attempt()
+    }, retryMs)
+    unref(retryTimer)
+  }
+
+  function attempt () {
+    if (disposed || !pending || !isLive()) return
+    const p = pending
+    let result
+    try {
+      result = release(p.exec, p.why, true, p.expected)
+    } catch (error) {
+      return failed(error)
+    }
+    if (result && typeof result.then === 'function') result.then(done, failed)
+    else done(result)
+  }
+
+  function done (result) {
+    if (disposed || !pending) return
+    if (result?.released) {
+      const finished = pending
+      pending = null
+      dropRetry()
+      log.info?.('computer-use: leave timer released the desktop lease')
+      try {
+        const out = notice(
+          'computer-use: 桌面租约已自动释放（离开桌面超过 100 秒）。下一次操作会重新观察；旧 mark 已失效。',
+          'computer-use: lease expired',
+          { agent: finished?.exec?.agent },
+        )
+        out?.catch?.(() => {})
+      } catch { /* a notice must never break the timer */ }
+      return
+    }
+    log.info?.(`computer-use: leave timer release refused (${result?.reason || 'no reason'})`)
+    scheduleRetry()
+  }
+
+  function failed (error) {
+    if (disposed) return
+    if (error?.code === 'COMPUTER_OWNER_CHANGED') {
+      // The captured cycle is gone or a newer one exists; this timer must never touch it.
+      pending = null
+      dropRetry()
+      log.info?.('computer-use: leave timer discarded (cycle/owner changed)')
+      return
+    }
+    log.warn?.(`computer-use: leave timer release failed (${error?.message || error})`)
+    scheduleRetry()
+  }
+
+  function fire () {
+    timer = null
+    if (disposed || !armed || !isLive()) { armed = null; return }
+    pending = armed
+    armed = null
+    attempt()
+  }
+
+  function arm (exec) {
+    if (disposed || armed || pending || timer || !graceMs || !isOpen()) return
+    let claim
+    try { claim = claimOf(exec) } catch { return }
+    if (!owned(claim)) return // global hook: only the owner's own leaving starts a timer
+    const cycle = gate?.snapshot?.()
+    if (!cycle || !Number.isInteger(cycle.id)) return
+    armed = {
+      exec,
+      expected: { claim, cycleId: cycle.id },
+      why: `left desktop for ${exec.name}`,
+    }
+    timer = setTimer(fire, graceMs)
+    unref(timer)
+    log.info?.(`computer-use: leave timer armed for ${graceMs} ms (${exec.name})`)
+  }
+
+  function observe (exec) {
+    if (disposed || !exec || typeof exec.name !== 'string') return
+    // A computer_* call — including one waiting in the approval card — means the agent is still on
+    // the desktop, so the leave grace must not fire underneath it. A denied call can cancel too;
+    // the next non-desktop top-level call arms a fresh grace. onStart() also cancels, idempotently,
+    // once the approved tool really begins.
+    if (exec.name.startsWith('computer_') || DESKTOP_HELPERS.has(exec.name)) {
+      cancel(exec)
+      return
+    }
+    if (LEAVE_TOOL_EXEMPT.has(exec.name)) return
+    arm(exec)
+  }
+
+  function retryNow () {
+    if (!pending || retryTimer || disposed || !isLive()) return
+    attempt()
+  }
+
+  function onTurnEnd (session) {
+    if (!isLive()) { clear(); return }
+    let claim
+    try { claim = claimOf({ session }) } catch { return }
+    if (owned(claim)) clear()
+  }
+
+  function onAgentDisposed (agent) {
+    if (!isLive()) { clear(); return }
+    let claim
+    try { claim = claimOf({ agent }) } catch { return }
+    if (owned(claim)) clear()
+  }
+
+  function dispose () {
+    disposed = true
+    clear()
+  }
+
+  return { observe, cancel, clear, retryNow, onTurnEnd, onAgentDisposed, dispose }
+}

package/lib/tools.js

@@ -798,7 +798,7 @@ export function registerTools ({ ctx, cu, config, dataDir, log, snapshotPath, de
   // ---------------- meta ----------------
   reg({
     name: 'computer_ctrl',
-    description: 'hold requests stable page/pointer state between actions (breathing blue); free allows human use while observing (cyan). Neither blocks human takeover. After final verification, release ends desktop control while the conversation continues. stop raises a manual brake, released by human Ctrl+Alt+R; recover checks a temporary diagnostic pause; exit aborts. selftest/calibrate diagnose input; indicator controls the border; acknowledge accepts the skill receipt.',
+    description: 'hold requests stable page/pointer state between actions (breathing blue); free allows human use while observing (cyan). Neither blocks human takeover. After final verification, release ends desktop control while the conversation continues; leaving the desktop for another tool can also trigger an automatic lease expiry after the configured grace, so re-observe after it. stop raises a manual brake, released by human Ctrl+Alt+R; recover checks a temporary diagnostic pause; exit aborts. selftest/calibrate diagnose input; indicator controls the border; acknowledge accepts the skill receipt.',
     parameters: {
       action: P('string', 'hold | free | release | clear_cache | selftest | calibrate | stop | exit | indicator | acknowledge | recover', { required: true }),
       why: P('string', 'reason recorded with a stop'),

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "dsh-codex-style-computer-use",
-  "version": "2.2.5",
+  "version": "2.2.7",
   "description": "Codex-style Computer Use for DeepSeek Harness: Windows desktop control, screenshots, UI Automation, human input handoff, approval gates and prebuilt native workers. Install and update from dsh-market without PowerShell 7 or build steps.",
   "type": "module",
   "main": "lib/index.js",

package/scripts/check-behavior.mjs

@@ -37,7 +37,7 @@ const reviewed = new Set([
   'cycle-no-timeout', 'cycle-open', 'desktop-acceptance-io', 'desktop-ownership', 'drag-options', 'evidence-protocol',
   'exit-coherence', 'feedback-cache-integration', 'feedback-policy', 'glow-pump', 'glow-visual', 'handoff-continuation',
   'handoff-lock', 'handoff-runtime', 'handoff-watchdog', 'host-gate', 'human-handoff', 'indicator-hold', 'input-stamp', 'key-command',
-  'kickoff-focus', 'mcp-contracts', 'mcp-execution', 'modifier-vk', 'monitor-lifetime', 'native-hardening', 'native-respawn',
+  'kickoff-focus', 'leave-timer', 'mcp-contracts', 'mcp-execution', 'modifier-vk', 'monitor-lifetime', 'native-hardening', 'native-respawn',
   'native-runtime', 'native-fault-lifecycle', 'observation-archive', 'observations', 'op-classification', 'pointer-lease', 'policy', 'preparation',
   'release-channel', 'renders', 'root-integration', 'session-identity', 'skill-gate', 'steer-message-shape',
   'task-rules', 'terminal-cleanup', 'timeout-branch', 'turnend-agent', 'turnend-rootagent',

package/skills/computer-use/SKILL.md

@@ -11,24 +11,24 @@ Read this entry before driving. The skill gate requires this receipt once per se
 
 Tools load for the current Agent after a successful `skill` load or this receipt; if invisible, call `computer_use_activate` (opens no cycle, releases no brake). Stop/exit and computer_ask work before activation. Issue real tool calls: a target handle is a string argument to computer_uia_act — tags, examples and prose do not execute; in a run_code-only host, call tools through run_code. Observation and the safety direction (ask, stop, exit) are not gated; a human brake still refuses observation. Read a referenced file only when its condition applies.
 
-## Release gate (applies before EVERY tool call)
+## Cycle boundary (one rule)
 
-A desktop cycle is a lease on the live desktop, not a flag for the whole task. Before every tool call while a cycle is open, ask with the **next-action test**:
+A desktop cycle covers **one continuous desktop block**, not the user's task and not the turn.
 
-> Does my NEXT call need the mouse, keyboard, UI Automation, a screenshot, or this same live clipboard?
+When your next call is not `computer_*`, use this two-part test:
 
-- **NO → call `computer_ctrl {action:"release"}` FIRST**, before that shell/file/network/npm/chat/analysis call. Do not keep the lease while you use the desktop artifact somewhere else.
-- **YES → keep it**, but only for that continuous desktop step.
+1. Can you name the next desktop action in this same block?
+2. Is this non-desktop step a short helper needed for that action, rather than a different work item?
 
-The lease ends when the desktop **artifact** is obtained: clipboard text read, UIA value/control read, screenshot captured, field typed and verified, file saved, or window activated. It does not wait for the user's whole task, the final answer, or a turn boundary. Examples that all require immediate release after the `computer_*` result:
+Keep the cycle only if both answers are yes and the helper is quick. Otherwise release first: `computer_ctrl {action:"release"}`. Publish, upload, install, build, test, network, a file write, analysis and a chat answer are different work items, so release before them. `todo_write` or a quick local read between two desktop actions is a helper, not a block boundary. A `run_code` call that itself dispatches the next desktop action, and an observation helper used for that action, remain part of the block.
 
-- `computer_clip` returned a token/password/text and the next step is `npm publish`, a shell command, or a file write.
-- `computer_shot` returned an image and the next step analyzes or edits it outside the desktop.
-- `computer_uia` / `computer_state` returned a value and the next step is a shell/file/network call.
-- `computer_type` verified a field and the next step is not another `computer_*` call.
-- A save/open dialog returned a path and the next step uses that path in a non-desktop tool.
+An artifact in hand (token, clipboard text, a value, a path, a screenshot) means the desktop block **may** be ending; it is not an automatic release point. If the next call is another desktop action (paste, verify, click), keep the cycle; if it is non-desktop and you cannot name the next desktop action, release.
 
-Holding “because I may need the desktop again later” is not allowed: reacquiring is cheap, and a later need starts a fresh cycle with fresh evidence. Holding while publishing, uploading, running a command, writing a file or composing a chat answer is the exact failure this gate prevents. An explicit `computer_ctrl {action:"hold"}` is the only reason to stay on the desktop across non-desktop work; `free` and then `release` when that readback is done. Human pause/question/exit still take precedence. **Self-audit:** if you have made any non-`computer_*` tool call since your last `computer_*` call and the cycle is still open, you missed this gate — release now before continuing.
+`hold` is only for a position-sensitive readback inside the continuous block — never across a build, publish, upload or long command. `free`, then release when the readback is done. Pauses, questions and human handoffs still own the desktop; release does not override them.
+
+When in doubt, release: reacquiring the lease is cheap, while a lit border and an exclusive lease during long non-desktop work are not.
+
+The plugin also has a deterministic backstop: after a non-desktop top-level tool starts, if no `computer_*` call starts within **100 seconds**, it releases the lease automatically (`leaveDesktopGraceMs`; 0 disables). `hold` does not extend this timer. A release is not an error: call `computer_state` again before driving; old marks and cached observations are stale. A `run_code`-only host is covered by this block rule, not by the timer; if you dispatch desktop work through `run_code`, release at the same boundary yourself.
 
 ## Start, act, verify
 
@@ -38,7 +38,7 @@ Holding “because I may need the desktop again later” is not allowed: reacqui
 4. Otherwise use an observed mark or measured coordinate. A mark is a snapshot ID and does not follow scrolling; each mark action checks window identity, position and sampled pixels, and STALE_MARK means no input was dispatched. Refresh with `computer_marks {refresh:true}` and pick by NEW id (old ids retire); refresh after known scrolling/navigation even if a sample misses it. dx/dy offsets work in direct and batch clicks.
 5. Batch a coherent set to a natural checkpoint — no fixed step count. Steps run serially; failure, failed activation or cancellation stops later ones. Reuse returned evidence; `shot:"auto"` adds at most one observation when needed, `shot:"never"` suits text/readback verification. Batch known inputs rather than paying an intermediate image per keystroke.
 6. Verify the outcome: field value, saved record/document, selected range, app status or image. A provider accepting input proves neither a save nor the business result. Report what was observed and any unresolved uncertainty, then finish.
-7. Release at the boundary defined by the release gate above — when the next action no longer needs the live desktop; do not wait for task completion, a final summary, or the turn end. `computer_ctrl {action:"release"}` closes desktop control only, not the conversation; a later desktop need opens a fresh cycle and requires fresh evidence. If a pause, question or handoff currently owns the desktop, finish that state first. Normal turn completion also releases without a question card; explicit pauses/questions are preserved.
+7. Release at the cycle boundary above — when the next step leaves this continuous desktop block for a different work item, or when you cannot name the next desktop action. Do not wait for task completion, a final summary, or the turn end. `computer_ctrl {action:"release"}` closes desktop control only, not the conversation; a later desktop need opens a fresh cycle and requires fresh evidence. If a pause, question or handoff currently owns the desktop, finish that state first. Normal turn completion also releases without a question card; explicit pauses/questions are preserved.
 
 `since` (same query + previous observation id) returns added/changed/removed elements and order changes; omitted elements keep their state, while no/expired base, changed scope, partial results or an uneconomical diff return full. `snapshot` retrieves a retained observation without capturing — not fresh verification; page it with `offset`/`limit`. `computer_ctrl {action:"clear_cache"}` clears this Agent's cache without a cycle. Caches are bounded and expire; storage failure falls back to bounded memory and memory pressure to inline results without a fake snapshot id. Omit since/snapshot for fresh evidence after losing the baseline. See [progressive-control.md](references/progressive-control.md).
 
@@ -78,7 +78,7 @@ Before replaying a write, inspect whether it already took effect, then focus, mo
 
 **Document editors (Word/WPS/PDF) — destructive selection:** never triple-click, never `ctrl+a`, never select-then-paste as an edit strategy. Triple-click selects an unpredictable scope (measured 2026-11-07: it replaced an entire one-page form in Word). Edit one line at a time: click inside the line, `home`, then `shift+end`, CAPTURE and confirm the selection covers only that line, then type. After any unexpected document change press `ctrl+z` immediately and capture before continuing; never save a document you have not seen in full after the edit. Save As a NEW file and never overwrite the original.
 
-**Downloads:** resolve the real download directory from `HKCU\Software\Microsoft\Windows\CurrentVersion\Explorer\User Shell Folders` (`{374DE290-123F-4565-9164-39C4925E467B}`) — a redirected profile puts it outside `%USERPROFILE%`. Edge refuses some HTTP documents with "无法安全下载" and leaves a small `.crdownload` stub; there may be no Keep option. Attempt the download at most twice, then report the block and use an already-downloaded copy or the site's preview if it exists; do not loop on the security UI. Preserve the breakpoint and live cycle; elapsed time cannot release a human brake. Use computer_wait for transient readiness; selftest/calibration are for observed input-delivery or coordinate problems, not every failure.
+**Downloads:** resolve the real download directory from `HKCU\Software\Microsoft\Windows\CurrentVersion\Explorer\User Shell Folders` (`{374DE290-123F-4565-9164-39C4925E467B}`) — a redirected profile puts it outside `%USERPROFILE%`. Edge refuses some HTTP documents with "无法安全下载" and leaves a small `.crdownload` stub; there may be no Keep option. Attempt the download at most twice, then report the block and use an already-downloaded copy or the site's preview if it exists; do not loop on the security UI. Keep the cycle only for this blocked-download retry; elapsed time cannot release a human brake. Use computer_wait for transient readiness; selftest/calibration are for observed input-delivery or coordinate problems, not every failure.
 
 For pixel waits pass the observed hwnd to `computer_wait` (stable/change) so animation elsewhere does not delay you; the default covers the whole virtual desktop. A caret inside the region can still prevent settling — verify with UIA state instead of spending full timeouts. `lastDiffPct` describes only the final sample pair; a moved/minimized target needs a fresh observation.
 
@@ -101,7 +101,7 @@ A cold tree may expose only window chrome/an ancestor: use a point query and one
 
 ## Human control and permission
 
-Initial observation is free; dispatching input and preserving the scene are the two held states described below. Use `computer_ctrl {action:"hold"}` before a position-sensitive readback and `{action:"free"}` as soon as thinking no longer needs an unchanged desktop; neither creates a cycle nor releases a manual brake. Release the cycle when desktop work is done.
+Initial observation is free; dispatching input and preserving the scene are the two held states described below. Use `computer_ctrl {action:"hold"}` before a position-sensitive readback and `{action:"free"}` as soon as thinking no longer needs an unchanged desktop; neither creates a cycle nor releases a manual brake. Release at the cycle boundary above, not when the user's task or the turn ends.
 
 During acting/holding a compact tilted blue kite temporarily replaces the pointer; its tip is the exact native hotspot and its centre symbol follows recognized native shapes, neutral when unknown. Native cursor handles and visibility are preserved for cursor checks and screenshot burn-in, so tool images intentionally show the application cursor, not the kite. Free, handoff, pause and release restore native presentation; a short-lived visibility lease restores it if rendering or the worker stops. The symbol proves no target or effect.
 

package/skills/computer-use/references/lifecycle.md

@@ -17,9 +17,11 @@ The human's own words are the spec here; this section is what they mean.
   it ("Computer use 周期结束之后, 所有跟 computer use 相关的监听, 全部都要终结").
 - **A pause NEVER ends the cycle.** The cycle stays live while paused. Normal desktop completion can release an unpaused cycle before the chat turn ends; an explicit Q remains a terminal exit for that turn.
 
-## Release as soon as desktop work is done
+## Release at the cycle boundary
 
-Call `computer_ctrl {action:"release"}` immediately after the final desktop action and its verification. This closes the indicator/listeners and releases the exclusive desktop lease while the conversation continues. Subsequent explanation, computation and other tools do not require a computer-use cycle. When new desktop work becomes necessary, a later real tool call can open a new cycle in the same turn.
+Call `computer_ctrl {action:"release"}` when the next step leaves this continuous desktop block for a different work item (publish, upload, install, build, test, network, a file write, analysis or chat), or when you cannot name the next desktop action. This closes the indicator/listeners and releases the exclusive desktop lease while the conversation continues. A quick readback you type straight back, a `run_code`/observation helper that itself continues the desktop action, or a single short helper needed for the next click is still inside the block; keep the cycle. An artifact in hand is a signal that the block may be ending, not an automatic release point. `hold` is only for position-sensitive readback inside the block, never across a long command; `free` then release. When in doubt, release; a later real tool call can open a new cycle in the same turn.
+
+The plugin also enforces a deterministic backstop: after a non-desktop tool starts while the cycle is open, a leave timer releases the lease if no `computer_*` call starts within the configured grace (default 100 s; `leaveDesktopGraceMs: 0` disables it). It is owner-scoped, cancelled by an actual `computer_*` start, retries a release refused by a pause/question/handoff/in-flight call, and passes the cycle id captured when it was armed so it cannot release a newer cycle. `hold` does not extend this timer. After an automatic release, re-observe before driving; old marks and cached observations are stale.
 
 Release is owner-checked and distinct from `exit`: it does not cancel the conversation or write an EXITED latch. It cannot release an explicit human pause or a pending question. Closure is serialized with ownership acquisition so an old owner's delayed release cannot close a new owner's cycle. An explicit Ctrl+Alt+Q still prevents reopening in that same turn.