@bastani/atomic 0.9.56-alpha.1 → 0.9.57-alpha.1

package/CHANGELOG.md

@@ -2,6 +2,18 @@
 
 ## [Unreleased]
 
+## [0.9.57] - 2026-10-31
+
+### Changed
+
+- Atomic's computer-use guidance now routes native desktop apps, menus, OS dialogs and non-Chromium desktop browsers to `agent-desktop` instead of Cua Driver; websites, Mobile Safari and CDP-exposing apps stay with `agent-browser`. Workflow code that owns a desktop scenario calls the `agent-desktop` CLI from `ctx.tool` (it has no TypeScript SDK), with a readiness preflight that ends the run as `blocked` when a permission or the Linux accessibility bus is missing. The [Computer use](https://github.com/bastani-inc/atomic/blob/main/packages/coding-agent/docs/computer-use.md) guide covers installing it, permissions on each OS, and what it cannot cover: apps with no accessibility tree, and native iOS and Android apps, which need native mobile tooling.
+
+## [0.9.57-alpha.1] - 2026-10-31
+
+### Changed
+
+- Atomic's computer-use guidance now routes native desktop apps, menus, OS dialogs and non-Chromium desktop browsers to `agent-desktop` instead of Cua Driver; websites, Mobile Safari and CDP-exposing apps stay with `agent-browser`. Workflow code that owns a desktop scenario calls the `agent-desktop` CLI from `ctx.tool` (it has no TypeScript SDK), with a readiness preflight that ends the run as `blocked` when a permission or the Linux accessibility bus is missing. The [Computer use](https://github.com/bastani-inc/atomic/blob/main/packages/coding-agent/docs/computer-use.md) guide covers installing it, permissions on each OS, and what it cannot cover: apps with no accessibility tree, and native iOS and Android apps, which need native mobile tooling.
+
 ## [0.9.56] - 2026-10-30
 
 The newest fixes from upstream pi: tool search, WSL, updates and MCP.

package/dist/builtin/intercom/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@bastani/intercom",
-  "version": "0.9.56-alpha.1",
+  "version": "0.9.57-alpha.1",
   "private": true,
   "description": "Atomic extension providing a private coordination channel between parent and child agent sessions. Fork of: https://github.com/nicobailon/pi-intercom",
   "contributors": [

package/dist/builtin/mcp/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@bastani/mcp",
-  "version": "0.9.56-alpha.1",
+  "version": "0.9.57-alpha.1",
   "private": true,
   "description": "Atomic's pi-compatible MCP integration for server connections, OAuth, tools, resources, and terminal management.",
   "contributors": [

package/dist/builtin/subagents/CHANGELOG.md

@@ -2,6 +2,30 @@
 
 ## [Unreleased]
 
+## [0.9.57] - 2026-10-31
+
+Desktop computer use moves from Cua Driver to agent-desktop.
+
+- **agent-desktop for native apps:** the bundled computer-use skill is now `agent-desktop`, which drives native desktop apps, menus and OS dialogs on macOS, Windows and Linux through their accessibility trees. Install it with `npm install -g agent-desktop`; the skill loads guides that match the installed version ([#4134](https://github.com/bastani-inc/atomic/pull/4134))
+- **Workflow code:** a workflow that owns a desktop scenario calls the `agent-desktop` CLI from `ctx.tool`, checks readiness first, and ends the run as `blocked` when a permission or the Linux accessibility bus is missing ([#4134](https://github.com/bastani-inc/atomic/pull/4134))
+- **Coverage that changed:** agent-desktop reads accessibility trees, not pixels, and has no native iOS or Android support; use `xcrun simctl`, Appium or `adb` for native mobile apps. `ATOMIC_CUA_AUTO_APPROVE` no longer has any effect ([#4134](https://github.com/bastani-inc/atomic/pull/4134))
+
+### Changed
+
+- The bundled computer-use skill is now `agent-desktop` (vercel-labs/agent-desktop v1.0.2) instead of `cua-driver`. It drives native desktop apps on macOS, Windows and Linux through their accessibility trees. Install the CLI with `npm install -g agent-desktop`; check readiness with `agent-desktop status`, and on macOS grant Accessibility with `agent-desktop permissions --guide`. The skill tells the agent to load `agent-desktop skills get desktop` and `agent-desktop skills get platform`, which always match the installed CLI. agent-desktop does not match pixels, so apps that expose no accessibility tree, native iOS apps in the Simulator and Android emulators no longer have a bundled route; use `xcrun simctl`, Appium or `adb` for native mobile apps. `ATOMIC_CUA_AUTO_APPROVE` no longer has any effect.
+
+## [0.9.57-alpha.1] - 2026-10-31
+
+Desktop computer use moves from Cua Driver to agent-desktop.
+
+- **agent-desktop for native apps:** the bundled computer-use skill is now `agent-desktop`, which drives native desktop apps, menus and OS dialogs on macOS, Windows and Linux through their accessibility trees. Install it with `npm install -g agent-desktop`; the skill loads guides that match the installed version ([#4134](https://github.com/bastani-inc/atomic/pull/4134))
+- **Workflow code:** a workflow that owns a desktop scenario calls the `agent-desktop` CLI from `ctx.tool`, checks readiness first, and ends the run as `blocked` when a permission or the Linux accessibility bus is missing ([#4134](https://github.com/bastani-inc/atomic/pull/4134))
+- **Coverage that changed:** agent-desktop reads accessibility trees, not pixels, and has no native iOS or Android support; use `xcrun simctl`, Appium or `adb` for native mobile apps. `ATOMIC_CUA_AUTO_APPROVE` no longer has any effect ([#4134](https://github.com/bastani-inc/atomic/pull/4134))
+
+### Changed
+
+- The bundled computer-use skill is now `agent-desktop` (vercel-labs/agent-desktop v1.0.2) instead of `cua-driver`. It drives native desktop apps on macOS, Windows and Linux through their accessibility trees. Install the CLI with `npm install -g agent-desktop`; check readiness with `agent-desktop status`, and on macOS grant Accessibility with `agent-desktop permissions --guide`. The skill tells the agent to load `agent-desktop skills get desktop` and `agent-desktop skills get platform`, which always match the installed CLI. agent-desktop does not match pixels, so apps that expose no accessibility tree, native iOS apps in the Simulator and Android emulators no longer have a bundled route; use `xcrun simctl`, Appium or `adb` for native mobile apps. `ATOMIC_CUA_AUTO_APPROVE` no longer has any effect.
+
 ## [0.9.46] - 2026-10-27
 
 ### Fixed

package/dist/builtin/subagents/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@bastani/subagents",
-  "version": "0.9.56-alpha.1",
+  "version": "0.9.57-alpha.1",
   "private": true,
   "description": "Atomic extension for delegating tasks to subagents with parallel execution. Fork of: https://github.com/nicobailon/pi-subagents",
   "contributors": [

package/dist/builtin/subagents/skills/agent-desktop/SKILL.md

@@ -0,0 +1,83 @@
+---
+allowed-tools: Bash(agent-desktop:*), Bash(npx agent-desktop:*)
+description: Operate native desktop applications on macOS, Windows and Linux through accessibility trees with the agent-desktop CLI. Use when an AI agent must see or act on a desktop GUI, such as clicking buttons, filling forms, reading UI state, navigating menus, toggling checkboxes, scrolling, dragging, typing text, pressing shortcuts, taking screenshots, managing windows, using the clipboard, launching or closing apps, handling OS dialogs and permission prompts, or reading notifications. Triggers include requests to "operate the desktop", "computer use", "click a button in an app", "fill a native form", "read the UI", "open an app", "snapshot an app" or any native desktop GUI task. For websites and web apps use agent-browser instead.
+hidden: true
+metadata:
+    github-path: skills/agent-desktop
+    github-ref: refs/tags/v1.0.2
+    github-repo: https://github.com/vercel-labs/agent-desktop
+    github-tree-sha: 08884bafcd7a8d0a9a3757a7ab2ba238e1d5bf2a
+name: agent-desktop
+---
+
+# agent-desktop
+
+agent-desktop is a CLI that lets an AI agent observe and operate desktop apps through the OS accessibility tree. It is a tool, not an agent. Every command prints one JSON envelope (`ok`, `data` or `error`). The observe, act and verify loop runs in you.
+
+## Install and permissions
+
+If `agent-desktop` is not on `PATH`, make one bounded attempt to install it: `npm install -g agent-desktop` (Node 18 or later; macOS 13+, Windows 10 1809+ or Ubuntu 24.04+, on x64 or arm64), then `agent-desktop version`. If npm blocks install scripts, approve them (`npm install-scripts approve agent-desktop` on npm 12, `npm install -g agent-desktop --allow-scripts=agent-desktop` on npm 11) so each call does not start Node first. Report what the install did. If it fails, report the command and the error instead of switching to another tool. Atomic bundles this skill, so do not run `npx skills add` for it.
+
+`agent-desktop status` is the readiness check. On macOS, `permissions.accessibility` must be `granted`, and `screen_recording` too for `screenshot`: run `agent-desktop permissions --guide` and let the user approve it. Windows needs no grant for apps at the terminal's integrity level. On Linux, run inside the user's graphical session; an empty `supported_surfaces` means the AT-SPI bus did not answer. Never script around a consent dialog.
+
+For web pages use `agent-browser`. For the web contents of a Chromium or Electron app you launch, `agent-desktop launch <app> --cdp` opens a debugging port that `agent-browser connect <port>` drives (see `commands-system`).
+
+## Shell syntax
+
+Examples use a POSIX shell. In PowerShell, quote every ref (`'@s8f3k2p9:e1'`), because a bare `@token` is the splatting operator. Use `$env:NAME = 'value'` instead of `export`, and `| ConvertFrom-Json` instead of `$(...)` and `jq`. The Windows skill has the PowerShell forms.
+
+## First run
+
+1. Run `agent-desktop status`. It reports the platform, permissions and `supported_surfaces`.
+2. Run `agent-desktop skills get platform`. It loads the skill for the OS the binary runs on (macOS, Windows or Linux).
+3. For flags and syntax, run `agent-desktop <command> --help`. This skill does not repeat flag lists.
+
+## The loop
+
+Use `find` when you know the role or exact name. Otherwise map the app first and drill into one region.
+
+```
+agent-desktop snapshot --skeleton --app "Notes" -i --compact   # shallow map, children_count on cut branches
+agent-desktop snapshot --root @s8f3k2p9:e3 -i --compact        # drill into one region
+agent-desktop click @s8f3k2p9:e12                              # act on a qualified ref
+agent-desktop snapshot --root @s8f3k2p9:e3 -i --compact        # verify: re-read the same region
+```
+
+- A small app needs no skeleton. Take a full `snapshot -i`.
+- Never skeleton a surface (`--surface menu`, `sheet`, `alert`). A surface is already focused.
+- An action that opens a menu, sheet or alert lists it in `data.surfaces`. Target that overlay next.
+- After an async step, use `wait` (see `commands-system.md`). A fixed sleep is a race.
+
+## Refs
+
+- Output refs are qualified: `@<snapshot_id>:e<N>`, for example `@s8f3k2p9:e1`. Pass them to later commands as they are.
+- Refs are valid for one snapshot. After any UI change, re-drill the affected region or take a new snapshot.
+- Only addressable elements get refs. Static text and inert containers do not.
+- `STALE_REF`: the ref no longer matches the live UI. Take a fresh snapshot and use the new ref.
+- `AMBIGUOUS_TARGET`: more than one live element matches. Narrow the target with `find --role --name --exact` or `--root`, then use the new ref.
+- `SNAPSHOT_NOT_FOUND`: the snapshot id expired. Snapshot again.
+
+## Delivery and retry
+
+Action results carry `data.disposition` and errors carry `error.disposition`, each with `delivery` and `retry`. Observation commands such as `snapshot` have none on success; their errors, and every `INVALID_ARGS` refusal, carry `not_delivered` and `retry: safe`.
+
+- Retry or substitute an action only when `disposition.retry` is `safe`. Only `not_delivered` is safe.
+- Any other delivery value means the action may have landed. A repeat can click, type or submit twice, and `toggle` can undo itself.
+- On a result that is not safe, read the live state (`get`, `is`, or a fresh snapshot) and decide from that. `details.post_state` helps when present.
+- Branch on `error.code` and `error.disposition`. Message and suggestion text can change.
+- `details.retryable: false` means waiting cannot change the outcome. Try a different approach.
+
+## Headless and headed
+
+Ref actions are headless by default. They use semantic accessibility calls and do not take focus, move the cursor, synthesize keys or use the clipboard. If no semantic path exists, the action fails closed. Use the global `--headed` flag only when the user explicitly permits physical input, such as double-click, hover, drag, or focus. Never switch to headed mode to recover from a headless failure. Raw coordinates (`--xy`) never imply focus. Which actions need `--headed` differs by OS: read the platform skill.
+
+## References
+
+Load one only when you need it: `agent-desktop skills get desktop <reference>`.
+
+| Reference | Open it when |
+|-----------|--------------|
+| `commands-observation` | You need `snapshot`, `find`, `get`, `is`, `screenshot`, `list-surfaces` semantics, partial trees, or the `--root` rules |
+| `commands-interaction` | You choose between click, type, set-value, select, toggle, scroll, press and mouse commands, or you debug an action error |
+| `commands-system` | You launch or close apps, manage windows, use the clipboard, `wait`, `batch`, sessions, multi-agent cursors, tracing, or load skills |
+| `workflows` | You want worked patterns (forms, menus, dialogs, waiting for a new window, scroll-find, drag) and the anti-patterns list |

package/dist/builtin/web-access/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@bastani/web-access",
-  "version": "0.9.56-alpha.1",
+  "version": "0.9.57-alpha.1",
   "private": true,
   "description": "Atomic extension for web search, URL fetching, GitHub repo cloning, PDF/video extraction. Fork of: https://github.com/nicobailon/pi-web-access",
   "contributors": [

package/dist/builtin/workflows/CHANGELOG.md

@@ -6,6 +6,18 @@ The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
 
 ## [Unreleased]
 
+## [0.9.57] - 2026-10-31
+
+### Changed
+
+- Builtin workflow stages verify native desktop changes with `agent-desktop` instead of Cua Driver, and report a missing install, macOS permission or Linux accessibility bus as `blocked`.
+
+## [0.9.57-alpha.1] - 2026-10-31
+
+### Changed
+
+- Builtin workflow stages verify native desktop changes with `agent-desktop` instead of Cua Driver, and report a missing install, macOS permission or Linux accessibility bus as `blocked`.
+
 ## [0.9.55] - 2026-10-30
 
 Local worker pools on remote databases, and sturdier start-up on busy and Windows machines.

package/dist/builtin/workflows/builtin/adversarial-verification.js

@@ -1,10 +1,10 @@
 import {
   adversarial_verification_default
-} from "./chunk-apagcs4r.js";
+} from "./chunk-xqcy5nve.js";
 import"./chunk-2377r57g.js";
 import"./chunk-n1910xc4.js";
-import"./chunk-2jfst7e4.js";
-import"./chunk-9cm2ckq2.js";
+import"./chunk-45fn5q5p.js";
+import"./chunk-x25rjw4y.js";
 export {
   adversarial_verification_default as default
 };

package/dist/builtin/workflows/builtin/{chunk-49kkbdpr.js → chunk-2f1shjah.js}

@@ -1,7 +1,7 @@
 import {
   workflow,
   withBuiltinContext
-} from "./chunk-2jfst7e4.js";
+} from "./chunk-45fn5q5p.js";
 import {
   parse_rubric,
   normalize_criteria,

package/dist/builtin/workflows/builtin/{chunk-dcxscfnb.js → chunk-37gm3bzk.js}

@@ -1,7 +1,7 @@
 import {
   workflow,
   withBuiltinContext
-} from "./chunk-2jfst7e4.js";
+} from "./chunk-45fn5q5p.js";
 import {
   score_progress,
   classify_trend

package/dist/builtin/workflows/builtin/{chunk-2jfst7e4.js → chunk-45fn5q5p.js}

@@ -1,6 +1,6 @@
 import {
   withSteeringPropagationContext2
-} from "./chunk-9cm2ckq2.js";
+} from "./chunk-x25rjw4y.js";
 
 // dist/builtin/workflows/src/authoring/workflow.ts
 import { basename } from "node:path";

package/dist/builtin/workflows/builtin/{chunk-hx8v4p97.js → chunk-4ek3v2wm.js}

@@ -1,7 +1,7 @@
 import {
   workflow,
   withBuiltinContext
-} from "./chunk-2jfst7e4.js";
+} from "./chunk-45fn5q5p.js";
 import {
   stableArtifactRoot
 } from "./chunk-rc5ec5xx.js";

package/dist/builtin/workflows/builtin/{chunk-z3pajrfs.js → chunk-8d40nyz9.js}

@@ -1,7 +1,7 @@
 import {
   workflow,
   withBuiltinContext
-} from "./chunk-2jfst7e4.js";
+} from "./chunk-45fn5q5p.js";
 import {
   scoring_prompt_reads,
   build_scoring_prompt

package/dist/builtin/workflows/builtin/{chunk-qhm35ntx.js → chunk-g3b2zf8r.js}

@@ -1,7 +1,7 @@
 import {
   workflow,
   withBuiltinContext
-} from "./chunk-2jfst7e4.js";
+} from "./chunk-45fn5q5p.js";
 import {
   keepContext,
   REVIEWER_CALIBRATION_RULES,
@@ -24,7 +24,7 @@ import {
   EVIDENCE_CLOSURE_POLICY,
   WORKTREE_DISCIPLINE_CONTRACT,
   REVIEW_CODE_DELTA_CONTRACT
-} from "./chunk-9cm2ckq2.js";
+} from "./chunk-x25rjw4y.js";
 import {
   workflowArtifactDirectoryPath,
   ensureWorkflowArtifactDirectory,

package/dist/builtin/workflows/builtin/{chunk-6jpwc09k.js → chunk-h6bt0r0g.js}

@@ -1,7 +1,7 @@
 import {
   workflow,
   withBuiltinContext
-} from "./chunk-2jfst7e4.js";
+} from "./chunk-45fn5q5p.js";
 import {
   keepContext,
   REVIEWER_CALIBRATION_RULES,
@@ -24,7 +24,7 @@ import {
   EVIDENCE_CLOSURE_POLICY,
   WORKTREE_DISCIPLINE_CONTRACT,
   REVIEW_CODE_DELTA_CONTRACT
-} from "./chunk-9cm2ckq2.js";
+} from "./chunk-x25rjw4y.js";
 import {
   VERIFICATION_SCALE
 } from "./chunk-n1910xc4.js";

package/dist/builtin/workflows/builtin/{chunk-9cm2ckq2.js → chunk-x25rjw4y.js}

@@ -63,10 +63,10 @@ var WORKER_PREFLIGHT_CONTRACT = [
 `);
 var E2E_VERIFICATION_GUIDANCE = [
   "Verify correctness end-to-end whenever practical for user-visible behavior; an executable scenario is stronger proof than code inspection, unit tests, or stage summaries alone.",
-  'For web or frontend flows, including frontend changes whose correctness depends on backend/API behavior, use the agent-browser skill or delegate with `skill: "agent-browser"`; capture snapshot, screenshot, DOM, or network evidence suited to the objective. Prefer agent-browser for what its skill covers, because its text snapshots cost far fewer tokens than screenshot-driven CUA (websites and web apps in Chrome/Chromium, Mobile Safari in the iOS Simulator via `agent-browser -p ios`, Electron desktop apps and other CDP-exposing apps, Slack, cloud browsers); use Cua Driver for anything else, including native iOS apps in the iOS Simulator, Android emulators, OS dialogs, desktop Safari and other non-Chromium browsers, and whenever agent-browser hits a limitation.',
+  'For web or frontend flows, including frontend changes whose correctness depends on backend/API behavior, use the agent-browser skill or delegate with `skill: "agent-browser"`; capture snapshot, screenshot, DOM, or network evidence suited to the objective. Prefer agent-browser for what its skill covers, because its text snapshots cost far fewer tokens than screenshot-driven computer use (websites and web apps in Chrome/Chromium, Mobile Safari in the iOS Simulator via `agent-browser -p ios`, Electron desktop apps and other CDP-exposing apps, Slack, cloud browsers); use agent-desktop for native desktop apps, OS dialogs and browser chrome outside the page, and whenever agent-browser hits a limitation. Native iOS apps in the iOS Simulator and Android emulators are outside agent-desktop: use `xcrun simctl`, Appium/XCUITest or `adb`/UI Automator, and report the gap when none is available.',
   "For TUI/terminal automation/testing, prefer the herdr skill on macOS, Linux and Windows. Install Herdr if missing when network access and permissions permit; fall back to the tmux skill or native Windows psmux if installation or use is not possible. Preserve the pinned herdr skill's explicit-request and HERDR_ENV=1 requirements; never control a focused session from outside Herdr. Check installed help: psmux uses tmux-style commands, while herdr has its own CLI, not interchangeable flags. Exercise the actual interactive flow and retain pane/text or terminal recording evidence.",
-  "For desktop and accessible simulator/emulator windows, use Cua Driver: when a model chooses the next action, as in this stage, use the `cua-driver` CLI; when workflow TypeScript code owns the sequence and the postcondition, the @trycua/cua-driver TypeScript SDK inside `ctx.tool` is the face instead. Here, load Atomic's bundled cua-driver skill and drive the exact window with one-shot `cua-driver call <tool>` commands, following the skill's snapshot -> act -> fresh snapshot -> verify loop. Before the first action, ensure the executable (`cua-driver --version`; if missing, one bounded attempt with upstream's one-line executable installer, reporting its side effects; that installer does not install an agent skill). Ignore upstream README's optional skill-install steps: never `cua-driver skills install` or `clawhub install @cua/driver`, and do not link or copy a skill into `~/.agents/skills/cua-driver`; leave any existing user-level skill alone. Ensure telemetry off (run every command with CUA_DRIVER_RS_TELEMETRY_ENABLED=false, and `cua-driver telemetry disable` once after an executable install) and readiness (`cua-driver status`, `cua-driver doctor`, `cua-driver call list_apps`; on macOS also `cua-driver permissions status`, starting a stopped daemon with `open -n -g -a CuaDriver --args serve`) with bounded attempts per docs/computer-use.md. Save each `get_window_state` JSON result and `screenshot_out_file` image to the artifacts directory as evidence. Report a missing macOS Accessibility or Screen Recording grant, a non-interactive Windows session, no graphical Linux session, or a refused/failed install as the stage's blocked/needs_human finding with the exact fix (for macOS: `cua-driver permissions grant`, then toggle CuaDriver on under System Settings -> Privacy & Security -> Accessibility and Screen & System Audio Recording, then relaunch the daemon; for an install: the exact installer command), and re-run the readiness check on resume. Use a dedicated desktop/session and controlled fixtures, inspect snapshots for other windows, and stop before destructive actions. Do not automate an arbitrary physical iPhone without an accessible simulator/emulator/mirroring or native automation setup, or label a Chrome recording as terminal or native iOS proof; an agent-browser `-p ios` session proves Mobile Safari behavior, not a native iOS app.",
-  "Also skip `cua-driver skills update` and any skill installation into other agent directories such as `~/.claude/skills`; updating the executable is separate from installing or updating a skill.",
+  "For native desktop apps and OS dialogs, use agent-desktop: when a model chooses the next action, as in this stage, load Atomic's bundled agent-desktop skill and run one-shot `agent-desktop` commands, following its snapshot -> act -> wait or fresh read -> verify loop; when workflow TypeScript code owns the sequence and the postcondition, call the `agent-desktop` CLI from inside `ctx.tool(name, args, fn, { timeoutMs })` instead, spawning one process per command, parsing its JSON envelope and forwarding `signal`. Before the first action, run `agent-desktop status`, `agent-desktop skills get desktop` and `agent-desktop skills get platform` and follow them; they are compiled into the binary, so they match the installed version. Ensure the executable (`agent-desktop version`; if missing, one bounded attempt with `npm install -g agent-desktop`, approving its install script if npm blocks it, and report its side effects). Atomic bundles the skill: never `npx skills add` it, and do not link or copy a skill into `~/.agents/skills` or other agent directories; leave any existing user-level skill alone. agent-desktop documents no telemetry, so no opt-out setting is needed. Ensure readiness with bounded attempts per docs/computer-use.md: on macOS `permissions.accessibility` granted (and `screen_recording` for screenshots), on Linux a non-empty `supported_surfaces`. Save the snapshot JSON, `screenshot` PNGs and, when a session traces, the `trace export` HTML to the artifacts directory as evidence. Verify each postcondition with `wait --element <ref> --predicate value --value <text>` or a fresh read, never a sleep; a successful action proves delivery, not the effect, and an action is retried only when `disposition.retry` is `safe`. Report a missing macOS permission, a Windows session that is not the interactive desktop, no graphical Linux session or AT-SPI bus, or a refused or failed install as the stage's blocked/needs_human finding with the exact fix (for macOS: `agent-desktop permissions --guide`, then the user approves it; for an install: `npm install -g agent-desktop`), and re-run `agent-desktop status` on resume. Use a dedicated desktop/session and controlled fixtures, inspect snapshots for other windows, and stop before destructive actions. agent-desktop reads accessibility trees and does not match pixels: for a UI that publishes none, a screenshot with `--headed` coordinate input is the only route and needs the user's permission, so say what stayed unverified. It does not drive native iOS or Android apps inside a simulator or emulator: use `xcrun simctl`, Appium/XCUITest or `adb`/UI Automator. Do not automate an arbitrary physical iPhone without an accessible simulator/emulator/mirroring or native automation setup, or label a Chrome recording as terminal or native iOS proof; an agent-browser `-p ios` session proves Mobile Safari behavior, not a native iOS app.",
+  "Also never run `npx skills add` for agent-desktop or install a skill into other agent directories such as `~/.claude/skills`; updating the executable is separate from installing or updating a skill.",
   "Choose tools from observed environment capabilities. Prefer installed/cached tools; install missing tools, runtimes or plugins when online access and permissions permit. Known offline/restricted installation is sufficient evidence not to attempt prohibited downloads; otherwise check capabilities or make one bounded setup attempt. Do not loop on blocked downloads, require production credentials, or take unsafe actions.",
   "When execution or installation is unavailable, continue available authoritative repository checks and retain useful local evidence. Report the constraint or attempted command with observed output, what could not run, and the narrower validation performed. For non-UI tasks, use relevant executable checks rather than manufacturing a UI scenario. An unavailable optional mechanism is not itself failed implementation or permission to relax required project checks."
 ].join(`
@@ -80,7 +80,7 @@ var CODE_QUALITY_VERIFICATION_GUIDANCE = [
 `);
 var MEDIA_PUBLICATION_GUIDANCE = [
   "Detect the repository provider and authorized PR/MR/issue/comment target before publishing media. Inspect and redact screenshots/video for secrets, personal information and unrelated windows; tie evidence to the verified commit and scenario. Local evidence collection does not authorize uploads.",
-  "When creating the PR/MR, gather the image and video evidence the verification stages produced and attach it to the PR body when the provider supports uploads: cua-driver `screenshot_out_file` before/after PNGs from `get_window_state`, agent-browser `screenshot` PNGs and `record` recordings, and any QA proof video. Reference each file in the body next to the scenario it proves (a before/after pair per verified postcondition, one recording per interaction) and keep the window-state JSON as a local artifact the body cites by name. On supported GitHub, pass them at creation: gh pr create --body-file <body.md> --attach 'before.png#State before the action' --attach 'after.png#State after the action' --attach flow.webm; use gh pr edit/comment --attach for evidence produced later.",
+  "When creating the PR/MR, gather the image and video evidence the verification stages produced and attach it to the PR body when the provider supports uploads: agent-desktop `screenshot` before/after PNGs, agent-browser `screenshot` PNGs and `record` recordings, and any QA proof video. Reference each file in the body next to the scenario it proves (a before/after pair per verified postcondition, one recording per interaction) and keep the snapshot JSON as a local artifact the body cites by name. On supported GitHub, pass them at creation: gh pr create --body-file <body.md> --attach 'before.png#State before the action' --attach 'after.png#State after the action' --attach flow.webm; use gh pr edit/comment --attach for evidence produced later.",
   "On GitHub, check gh --version and the chosen command's --help. GitHub CLI >=2.99.0 supports repeatable --attach on gh issue create/edit/comment and gh pr create/edit/comment. Use native attachments when supported, for example gh pr comment <number> --repo <owner/repo> --body-file <body.md> --attach <proof.mp4>. Attach each file once. Body-local path references are rewritten to hosted URLs; otherwise attachments append in flag order. Image path#alt text is supported; video alt text is not. A standalone ![](<local-video-path>) paragraph becomes an embedded player.",
   "Check current GitHub limits: PNG/JPEG/GIF/WebP/SVG images and MP4/MOV/WebM videos; images/GIFs up to 10 MB, video 10 MB on Free or 100 MB paid. Native attachment upload requires repository write access and supported OAuth/classic PAT auth; GitHub Enterprise Server is unsupported in this release. See https://docs.github.com/en/github-cli/github-cli/attaching-files-with-github-cli.",
   "Read back the returned PR/issue/comment and confirm usable GitHub-hosted links before claiming attachment success. Unsupported CLI versions, hosts, providers, auth or sizes require a truthful fallback: retain the local artifact and explain authorized manual attachment or supported provider options. Never claim file:// links are uploaded evidence, expose secrets, or upload automatically to unrelated third-party hosts."

package/dist/builtin/workflows/builtin/{chunk-apagcs4r.js → chunk-xqcy5nve.js}

@@ -1,7 +1,7 @@
 import {
   workflow,
   withBuiltinContext
-} from "./chunk-2jfst7e4.js";
+} from "./chunk-45fn5q5p.js";
 import {
   parse_rubric,
   normalize_criteria,

package/dist/builtin/workflows/builtin/{chunk-w4xp1w1f.js → chunk-yb55w6me.js}

@@ -1,7 +1,7 @@
 import {
   workflow,
   withBuiltinContext
-} from "./chunk-2jfst7e4.js";
+} from "./chunk-45fn5q5p.js";
 import {
   stableArtifactRoot
 } from "./chunk-rc5ec5xx.js";

package/dist/builtin/workflows/builtin/{chunk-k5q3t7je.js → chunk-yjgfnbgd.js}

@@ -1,7 +1,7 @@
 import {
   workflow,
   withBuiltinContext
-} from "./chunk-2jfst7e4.js";
+} from "./chunk-45fn5q5p.js";
 
 // dist/builtin/workflows/builtin/open-claude-design.ts
 import { Type as Type2 } from "typebox";

package/dist/builtin/workflows/builtin/classify-and-act.js

@@ -1,9 +1,9 @@
 import {
   DEFAULT_ACTION_CATEGORIES2,
   classify_and_act_default
-} from "./chunk-hx8v4p97.js";
-import"./chunk-2jfst7e4.js";
-import"./chunk-9cm2ckq2.js";
+} from "./chunk-4ek3v2wm.js";
+import"./chunk-45fn5q5p.js";
+import"./chunk-x25rjw4y.js";
 export {
   DEFAULT_ACTION_CATEGORIES2 as DEFAULT_ACTION_CATEGORIES,
   classify_and_act_default as default

package/dist/builtin/workflows/builtin/fan-out-and-synthesize.js

@@ -1,8 +1,8 @@
 import {
   fan_out_and_synthesize_default
-} from "./chunk-w4xp1w1f.js";
-import"./chunk-2jfst7e4.js";
-import"./chunk-9cm2ckq2.js";
+} from "./chunk-yb55w6me.js";
+import"./chunk-45fn5q5p.js";
+import"./chunk-x25rjw4y.js";
 export {
   fan_out_and_synthesize_default as default
 };

package/dist/builtin/workflows/builtin/generate-and-filter.js

@@ -1,10 +1,10 @@
 import {
   generate_and_filter_default
-} from "./chunk-z3pajrfs.js";
+} from "./chunk-8d40nyz9.js";
 import"./chunk-2377r57g.js";
 import"./chunk-n1910xc4.js";
-import"./chunk-2jfst7e4.js";
-import"./chunk-9cm2ckq2.js";
+import"./chunk-45fn5q5p.js";
+import"./chunk-x25rjw4y.js";
 export {
   generate_and_filter_default as default
 };

package/dist/builtin/workflows/builtin/goal.js

@@ -1,12 +1,12 @@
 import {
   goal_default
-} from "./chunk-qhm35ntx.js";
+} from "./chunk-g3b2zf8r.js";
 import"./chunk-zhyqnf5g.js";
 import"./chunk-2377r57g.js";
 import"./chunk-z0d03ktm.js";
 import"./chunk-n1910xc4.js";
-import"./chunk-2jfst7e4.js";
-import"./chunk-9cm2ckq2.js";
+import"./chunk-45fn5q5p.js";
+import"./chunk-x25rjw4y.js";
 export {
   goal_default as default
 };

package/dist/builtin/workflows/builtin/index.js

@@ -1,36 +1,36 @@
-import"./chunk-2jfst7e4.js";
-import"./chunk-9cm2ckq2.js";
+import"./chunk-45fn5q5p.js";
+import"./chunk-x25rjw4y.js";
 import"./chunk-n1910xc4.js";
 import"./chunk-2377r57g.js";
 import {
   adversarial_verification_default
-} from "./chunk-apagcs4r.js";
+} from "./chunk-xqcy5nve.js";
 import {
   classify_and_act_default
-} from "./chunk-hx8v4p97.js";
+} from "./chunk-4ek3v2wm.js";
 import {
   fan_out_and_synthesize_default
-} from "./chunk-w4xp1w1f.js";
+} from "./chunk-yb55w6me.js";
 import {
   generate_and_filter_default
-} from "./chunk-z3pajrfs.js";
+} from "./chunk-8d40nyz9.js";
 import {
   goal_default
-} from "./chunk-qhm35ntx.js";
+} from "./chunk-g3b2zf8r.js";
 import"./chunk-zhyqnf5g.js";
 import"./chunk-z0d03ktm.js";
 import {
   open_claude_design_default
-} from "./chunk-k5q3t7je.js";
+} from "./chunk-yjgfnbgd.js";
 import {
   loop_until_done_default
-} from "./chunk-dcxscfnb.js";
+} from "./chunk-37gm3bzk.js";
 import {
   ralph_default
-} from "./chunk-6jpwc09k.js";
+} from "./chunk-h6bt0r0g.js";
 import {
   tournament_default
-} from "./chunk-49kkbdpr.js";
+} from "./chunk-2f1shjah.js";
 export {
   adversarial_verification_default as adversarialVerification,
   classify_and_act_default as classifyAndAct,

package/dist/builtin/workflows/builtin/loop-until-done.js

@@ -1,10 +1,10 @@
 import {
   loop_until_done_default
-} from "./chunk-dcxscfnb.js";
+} from "./chunk-37gm3bzk.js";
 import"./chunk-z0d03ktm.js";
 import"./chunk-n1910xc4.js";
-import"./chunk-2jfst7e4.js";
-import"./chunk-9cm2ckq2.js";
+import"./chunk-45fn5q5p.js";
+import"./chunk-x25rjw4y.js";
 export {
   loop_until_done_default as default
 };

package/dist/builtin/workflows/builtin/open-claude-design.js

@@ -1,8 +1,8 @@
 import {
   open_claude_design_default
-} from "./chunk-k5q3t7je.js";
-import"./chunk-2jfst7e4.js";
-import"./chunk-9cm2ckq2.js";
+} from "./chunk-yjgfnbgd.js";
+import"./chunk-45fn5q5p.js";
+import"./chunk-x25rjw4y.js";
 export {
   open_claude_design_default as default
 };

package/dist/builtin/workflows/builtin/ralph.js

@@ -1,12 +1,12 @@
 import {
   ralph_default
-} from "./chunk-6jpwc09k.js";
+} from "./chunk-h6bt0r0g.js";
 import"./chunk-zhyqnf5g.js";
 import"./chunk-2377r57g.js";
 import"./chunk-z0d03ktm.js";
 import"./chunk-n1910xc4.js";
-import"./chunk-2jfst7e4.js";
-import"./chunk-9cm2ckq2.js";
+import"./chunk-45fn5q5p.js";
+import"./chunk-x25rjw4y.js";
 export {
   ralph_default as default
 };

package/dist/builtin/workflows/builtin/steering-context.js

@@ -1,6 +1,6 @@
 import {
   withSteeringPropagationContext2
-} from "./chunk-9cm2ckq2.js";
+} from "./chunk-x25rjw4y.js";
 export {
   withSteeringPropagationContext2 as withSteeringPropagationContext
 };

package/dist/builtin/workflows/builtin/tournament.js

@@ -1,10 +1,10 @@
 import {
   tournament_default
-} from "./chunk-49kkbdpr.js";
+} from "./chunk-2f1shjah.js";
 import"./chunk-2377r57g.js";
 import"./chunk-n1910xc4.js";
-import"./chunk-2jfst7e4.js";
-import"./chunk-9cm2ckq2.js";
+import"./chunk-45fn5q5p.js";
+import"./chunk-x25rjw4y.js";
 export {
   tournament_default as default
 };

package/dist/builtin/workflows/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@bastani/workflows",
-  "version": "0.9.56-alpha.1",
+  "version": "0.9.57-alpha.1",
   "private": true,
   "description": "Atomic extension for multi-stage workflow authoring and execution.",
   "contributors": [