qz-browser-agent 0.1.1 → 0.1.3

package/README.md

@@ -1,467 +1,132 @@
-# qz command line and MCP
+# qz
 
-Run browser tasks, manage results, and connect external agents to qz through CLI or MCP.
-Requires Node.js 24 or later and Chrome. CLI and MCP share the same browser connection.
+An open-source browser agent for humans and coding agents.
 
-## Quick start
-
-Install [qz from the Chrome Web Store](https://chromewebstore.google.com/detail/dknbdgkgoinlgjpfebapkklbmjjgdblm)
-with **Add to Chrome**. Open the qz side panel, complete its first-use data notice, and configure
-your provider and model in Settings.
-
-Run the published package with npx:
-
-```bash
-npx qz-browser-agent@latest connect
-npx qz-browser-agent@latest create "Summarize the current page." --stream
-```
-
-`npx qz-browser-agent@latest install` opens the same Chrome Web Store page. For a manual ZIP
-installation, download the [latest GitHub release](https://github.com/alibaba/qz-browser-agent/releases/latest)
-and follow the [manual installation steps](https://github.com/alibaba/qz-browser-agent/blob/main/README.md#manual-installation).
-
-`connect` starts the local MCP service and opens its connection page for first pairing. Use the
-Chrome profile where qz is installed. The first new profile is named `default`;
-accepting the data notice alone does not enable the local connection. Repeating `connect` reuses
-an online browser. Add further profiles with a [pairing URL](#pair-a-selected-browser-from-the-shell)
-or from their own qz Settings.
-
-The examples and suggested next commands use `qz`. Replace it with
-`npx qz-browser-agent@latest`, or install the command globally:
-
-```sh
-npm install --global qz-browser-agent@latest
-qz --version
-```
-
-On Windows, use PowerShell 7.3 or newer with its default native argument passing. After a global
-install, use `qz.ps1` for commands containing JSON or quoted names; Windows command suggestions
-use that wrapper. For automation, pin a compatible release version verified with your extension.
+qz is a local-first extension for Chrome and Edge.
+People use it from the side panel; agents such as Claude Code, Codex, and pi hand it web tasks
+through this CLI or MCP. qz works in your own browser, with your existing logins, and returns
+tables, files, or reports with sources. Everything runs locally, and your data goes only to the
+model you choose.
 
-## Connect and stop
-
-```bash
-qz connect
-qz status
-qz browsers
-qz mcp
-qz stop
-```
+[Website](https://alibaba.github.io/qz-browser-agent/) ·
+[GitHub](https://github.com/alibaba/qz-browser-agent) ·
+[Chrome Web Store](https://chromewebstore.google.com/detail/dknbdgkgoinlgjpfebapkklbmjjgdblm) ·
+[Full CLI and MCP reference](https://github.com/alibaba/qz-browser-agent/blob/main/docs/cli.md)
 
-`connect` reuses the healthy service already running for this installation. It prefers port 18765;
-if that port belongs to another program, the service chooses a free port. `status` shows the actual
-service address, and `mcp` prints its MCP URL. Both commands are read-only. To request a custom port,
-run `qz connect --port 18766`; an existing service on another port remains running and the command
-reports its address. The extension connects only to its configured address.
+![A coding agent handing a GitHub research task to qz](https://raw.githubusercontent.com/alibaba/qz-browser-agent/main/docs/images/examples/en/pi-delegate-en.gif)
 
-The connection page can be closed once `qz browsers` shows the profile online. Connections start
-only through `qz connect` or **qz Settings → Advanced → CLI → Connect CLI**. For ordinary connection
-failures, the extension makes at most three recovery attempts, 30 seconds apart, then pauses.
-After a browser or background restart, it may first wait once for the previous connection to expire.
-The saved retry budget survives worker restarts. Click **Connect CLI** in that browser's settings to retry.
-
-To disconnect one browser, click **Disconnect: NAME** in its qz Settings. `qz stop` stops the local
-service and disconnects every browser and MCP client using it. Browser tasks already running
-remain in the extension; stopping the service does not cancel them. Use `qz cancel TASK_ID` to stop
-a task, adding `--client NAME|UUID` when needed.
-
-### Pair a selected browser from the shell
-
-Get a pairing URL without opening the default browser or waiting for a connection:
-
-```bash
-qz connect --no-open --json
-qz connect --no-open --name work --json
-```
-
-The JSON envelope contains `result.endpoint`, `result.url`, `result.mcpUrl`, and
-`result.opened: false`. The command starts or reuses the service even when other browsers are
-already connected. Open the exact returned URL in the intended browser Profile with qz installed.
-
-Set `QZ_PAIRING_URL` to that URL and `QZ_PROFILE_DIRECTORY` to the selected profile's directory
-name, such as `Default` or `Profile 2`. These are directory names, not Chrome's display labels.
-Use a Profile already chosen by the user. On macOS:
-
-```sh
-open -na "Google Chrome" --args --profile-directory="$QZ_PROFILE_DIRECTORY" "$QZ_PAIRING_URL"
-```
-
-For Chrome on Linux:
+## Quick start
 
-```sh
-google-chrome --profile-directory="$QZ_PROFILE_DIRECTORY" "$QZ_PAIRING_URL"
-```
+Requires Node.js 22 or later.
 
-For Chrome installed under Program Files on Windows, set `$QzProfileDirectory` and
-`$QzPairingUrl` to those same values in PowerShell:
+1. **Install the extension.** Click **Add to Chrome** on the
+   [Chrome Web Store](https://chromewebstore.google.com/detail/dknbdgkgoinlgjpfebapkklbmjjgdblm),
+   open the qz side panel, and choose a provider and model in **Settings**.
+2. **Connect.** This starts the local service and pairs automatically with your default browser.
 
-```powershell
-& "$env:ProgramFiles\Google\Chrome\Application\chrome.exe" "--profile-directory=$QzProfileDirectory" $QzPairingUrl
-```
+   ```bash
+   npx qz-browser-agent@latest connect
+   ```
 
-Use the installed browser's executable or app name. For an existing custom data directory, also
-pass `--user-data-dir` with its exact path; for example on macOS:
+3. **Run your first task.**
 
-```sh
-open -na "Google Chrome" --args --user-data-dir="$QZ_USER_DATA_DIR" --profile-directory="$QZ_PROFILE_DIRECTORY" "$QZ_PAIRING_URL"
-```
+   ```bash
+   npx qz-browser-agent@latest create "Find this year's Nobel Prize winners in every category and put them in a table with source links." --stream
+   ```
 
-The [Chrome profile documentation](https://chromium.googlesource.com/chromium/src/+/master/docs/user_data_dir.md)
-distinguishes the data directory from the Profile inside it. A new data directory needs its own
-extension installation and first-use setup.
+   `--stream` shows progress, any questions qz needs you to answer, and the final result.
 
-`--name work` adds `?name=work` to the URL. The Profile opening it receives that identifier,
-including when it already has a connection. Without `--name`, a registered Profile keeps its name;
-a new Profile receives the next available name: `default`, `browser-2`, and so on. A name conflict
-requires another name. `qz connect --name work` opens the URL automatically and returns immediately.
-These URL-returning commands do not confirm that a browser connected. Verify it with:
+For regular use, install the `qz` command globally and use it in place of
+`npx qz-browser-agent@latest`:
 
 ```bash
-qz browsers --json
-qz create "Summarize the current page." --client UUID --stream
+npm install --global qz-browser-agent@latest
+qz --version
 ```
 
-Read `result.browsers`, then use the intended online entry's `clientId` UUID. `--client` selects an
-existing connection and cannot be combined with `--no-open` or `--name`. `--port` works with either
-pairing mode and follows the existing-service behavior above.
-
-### Add and select browsers
-
-You can also pair from **qz Settings → Advanced → CLI** in the intended Profile. Enter a distinct
-browser identifier and connect. Use the service address printed by `qz status` in **Local service address** if
-its port differs from 18765. Names use 1–64 letters, digits, underscores, or hyphens, beginning with
-a letter or digit; names are case-sensitive. UUID-shaped names are reserved for profile IDs.
-
-```bash
-qz browsers
-qz create "Summarize the current page." --client work --stream
-qz show TASK_ID --client work
-qz data --client work
-```
+To let your agent learn when and how to use qz, install the Skill with
+`npx skills add alibaba/qz-browser-agent -g`.
 
-`--client NAME|UUID` and `-c NAME|UUID` select a profile. With exactly one online browser, the CLI
-selects it automatically. With several online browsers, a selection is required; `default` is a
-name, not a routing preference. An unknown or offline selection fails without opening or using
-another browser. Each command resolves its name once and carries the UUID through subsequent
-requests. JSON task results and suggested next commands include that UUID.
+## Connect an MCP client
 
-Names remain registered while their browsers are offline and across service restarts. To release
-an offline name, remove its registration explicitly:
+After `connect`, print the MCP URL:
 
 ```bash
-qz browsers forget work
+npx qz-browser-agent@latest mcp
 ```
 
-An online browser must first disconnect in its settings. Forgetting a registration leaves the
-browser's tasks and data intact. A browser can then explicitly pair using the released name.
-
-### Update the connection
+The default is `http://127.0.0.1:18765/mcp`; use the URL your command prints if the port differs.
 
-Use the current CLI and extension together. Source edits and a newer npm package leave a healthy
-running service in place; `qz status` reports an available update. An incompatible service returns
-an update instruction instead of being stopped automatically.
-
-1. Use the latest CLI and let current tasks finish.
-2. Run `npx --yes qz-browser-agent@latest stop`. This disconnects all browsers using that service.
-3. Update qz from the [Chrome Web Store](https://chromewebstore.google.com/detail/dknbdgkgoinlgjpfebapkklbmjjgdblm).
-   For a manual ZIP installation, replace its extracted files with the
-   [latest release](https://github.com/alibaba/qz-browser-agent/releases/latest) and reload it at `chrome://extensions`.
-4. Run `npx --yes qz-browser-agent@latest connect`, then reconnect additional profiles using their
-   pairing URL or settings.
-
-## Connect an MCP client
-
-Run `qz connect`, then `qz mcp`. Copy the returned URL into your MCP client's HTTP configuration:
+**Codex** (`~/.codex/config.toml`):
 
 ```toml
 [mcp_servers.qz]
 url = "http://127.0.0.1:18765/mcp"
 ```
 
-Use the URL printed by your command if its port differs. `qz mcp --json` returns the URL as JSON
-for scripts. The `qingzhou_*` MCP tool names and extension protocol remain available. Responses
-to pending input bind to an explicit `waitId`. Use `qingzhou_bridge_status` to list browser names
-and UUIDs, then pass `clientId: "work"` or a UUID to browser tools. Selection is required with
-multiple online browsers. Task results include the resolved `clientId`. MCP initialization and streaming are handled by your
-client's MCP implementation.
-
-### Task and resource operations
-
-CLI and MCP use the same task observer and browser operations. The task and resource commands map to these MCP operations:
-
-| CLI | MCP tool |
-| --- | --- |
-| `browsers`, `browsers forget` | `qingzhou_bridge_status`, `qingzhou_forget_browser` |
-| `create`, `send`, `cancel` | `qingzhou_create_session`, `qingzhou_send_message`, `qingzhou_stop_session` |
-| `tasks`, `show`, `watch` | `qingzhou_list_sessions`, `qingzhou_get_session_snapshot`, `qingzhou_watch_task` |
-| `show`, `submit` / `approve` / `reject` | `qingzhou_get_session_snapshot`, `qingzhou_respond_to_user_input` |
-| `data list` / `delete` / `export` | `qingzhou_list_data_tables`, `qingzhou_delete_data_table`, `qingzhou_export_data_table` |
-| `images list` / `delete` / `export` | `qingzhou_list_image_collections`, `qingzhou_delete_image_collection`, `qingzhou_export_image_collection` |
-| `skills list` / `show` / `read` / `tools` / `export` | `qingzhou_list_skills`, `qingzhou_get_skill`, `qingzhou_get_skill_resource`, `qingzhou_list_plugins`, `qingzhou_export_skill` |
-| `settings get` / `set` | `qingzhou_get_settings`, `qingzhou_update_settings` |
-| `automations list` / `run` | `qingzhou_list_automations`, `qingzhou_run_automation` |
-
-MCP creation, message submission, and input responses accept `wait: true` to wait for completion;
-`stream: true` also sends assistant text through standard MCP progress notifications. A watch call
-always waits. For example, call `qingzhou_create_session` with:
-
-```json
-{"firstMessage":"Summarize the current page.","stream":true}
-```
-
-Supply `_meta.progressToken` on the MCP request to receive progress. Each notification includes a
-readable `message` and its structured event in `params._meta["qz/task-event"]`. Events include
-`created`, `status`, `text`, `replace`, and `input`. Input events include the current form, exact
-field IDs, option values, and `responseTemplate`. Fill that template and pass it to
-`qingzhou_respond_to_user_input`; another CLI or MCP connection can answer while the original call
-keeps waiting. Native Chrome permissions still require the user's click in the side panel.
-
-MCP `timeoutSeconds` bounds each browser request (180 seconds by default).
-`waitTimeoutSeconds` bounds the whole observation; omit it for no overall deadline. Configure your
-MCP client's own request deadline for long tasks. On timeout or cancellation, the browser task
-continues; error details include the task ID and a recovery tool call. `send_message` supports
-`steer: true` and follows its returned `clientMessageId`, including when steering stays in the same
-run. A long observation stays bound to the browser selected when it started.
-
-## Run a task
-
-```bash
-qz create "Compare these two laptops."
-qz create "Summarize the current page." --title "Research" --wait
-qz create "Find the main differences between these pages." --stream
-qz send TASK_ID "Add the source links." --stream
-qz send TASK_ID "Focus on open-source options." --steer --stream
-qz tasks
-qz show TASK_ID
-qz cancel TASK_ID
-```
-
-`create` starts a task and returns its ID. The title is optional. `--wait` waits for the result;
-`--stream` also displays progress as it arrives. Both stay connected while the task waits for user
-input and continue automatically after you respond. Task observation has no default time limit.
-Add `--timeout SECONDS` to set a total deadline, including time spent waiting for input. Each
-individual connection request remains bounded (180 seconds by default). A timeout or Ctrl-C ends
-watching; `qz watch TASK_ID --stream` resumes observation and `qz cancel TASK_ID` stops the task.
-Each CLI command initializes one MCP connection on its first tool call and reuses it for subsequent
-reads and responses. Completion, errors, and Ctrl-C close that connection. Transport failures are
-reported without automatically repeating browser actions.
-
-Provide the task text directly after `create`, or read it from stdin with `qz create -`.
-Use `--parent TASK_ID` to create a child task, and `qz tasks --limit N` to limit the task list.
-`send TASK_ID MESSAGE` sends a follow-up to the specified task; `qz send TASK_ID -` reads the message
-from stdin. A busy task queues a follow-up for its next run. Add `--steer` to deliver the message
-to the current run at its next safe boundary. Both start a new run when the task is idle. Pending
-questions and permissions still require a response.
-
-`--wait` and `--stream` track the submitted message. Streaming starts after that message, including
-when steering continues the same run. Pending questions from the preceding run remain visible so
-you can answer them and let a queued follow-up proceed. A connection failure never resends a message
-automatically.
-
-## Respond to a task
-
-```bash
-qz show TASK_ID
-qz submit TASK_ID '{"selectedIds":["option-a"]}' --stream
-qz approve TASK_ID --wait
-qz reject TASK_ID
-qz watch TASK_ID --stream
-```
-
-`show` and pending-input notices include the current question, labeled field IDs,
-option values, descriptions, image URLs, and a submission template with the actual field IDs.
-Edit its placeholder values and run the displayed command to respond. `submit` takes a JSON object
-keyed by field IDs; use option values for choices and arrays for multiple choices. Use
-`qz submit TASK_ID -` to read answers from stdin. Invalid or stale submissions return the current
-input and its template so you can correct the response directly.
-`approve` continues a confirmation after you finish the requested action. `reject` declines the
-current request; `cancel` stops the whole task.
-
-Each response reads the current wait ID before sending. To answer a specific request you already
-read, pass `--wait-id WAIT_ID` to `submit`, `approve`, or `reject`. A stale or invalid response
-leaves the request pending. Review the application consent notice included in the pending input,
-such as location sharing, before approving. Native Chrome permissions require a click in the qz side panel; CLI
-approval reports that action is needed and preserves the wait without opening a browser page.
-With `--wait` or `--stream`, the command stays connected while you grant permission in Chrome.
-Location approval reads the current disclosure version and includes it in the response. Human
-terminal output shows the notice before submitting the explicit approval; JSON output remains a
-single final result. MCP callers should show the notice to the user before sending approval with
-the returned `consentVersion`.
-
-`submit`, `approve`, and `reject` accept `--wait` and `--stream` to follow the task until it finishes, including
-further questions and permission requests. Each new request is shown once. Respond in the side
-panel or another terminal; the original command continues automatically. `watch` follows an
-existing task without resubmitting anything. Timeouts and Ctrl-C stop watching, while the task
-continues in the browser.
-
-## Browser selection and MCP tools
-
-Use `--client NAME|UUID` or `-c NAME|UUID` to select a browser. `qz browsers` lists registered names,
-UUIDs, and online status. See [browser selection](#add-and-select-browsers) for pairing and name reuse.
-Use `-t` for `--title`. Run `qz help COMMAND` or `qz COMMAND --help` for command-specific options.
-
-MCP clients can inspect browser tool schemas with `qingzhou_list_tools` and `qingzhou_get_tool`,
-then call `qingzhou_execute_tool` in a task. Set `wait: false` to receive a job ID and read the result
-with `qingzhou_get_tool_job`. Pass `runId` to bind execution to a particular task run. MCP also
-provides `qingzhou_get_trace` and `qingzhou_clear_trace` for diagnostics.
-
-If a request times out or its connection is interrupted, an operation already started in the
-browser may still be running. Check the task before repeating it. Disconnected MCP requests are
-cancelled in the service, and reconnecting does not replay their browser actions.
-
-## Data, images, and Skills
-
-```bash
-qz data
-qz data export TABLE
-qz data export TABLE --format csv
-qz data delete TABLE
-qz images
-qz images export COLLECTION
-qz images delete COLLECTION
-qz skills --query research
-qz skills show NAME
-qz skills read NAME scripts/run.js --limit 20000
-qz skills tools --session TASK_ID
-qz skills export NAME
-```
-
-Use the exact names printed by each list; quote names containing spaces. Data exports default to
-Excel (`xlsx`); `--format csv` selects CSV. Image collections export as a ZIP containing available
-image files and metadata. Missing local images are reported in the result. Skill exports contain
-one user-installed Skill and its resources; built-in Skills require the extension and cannot be
-exported independently.
-
-`skills show` includes the resource paths. `skills read NAME PATH` reads one resource, with a
-default limit of 20,000 characters. Use `--start` and `--limit` to select a chunk; truncated text
-includes the command for the next chunk. `skills tools` lists contributed tools and whether they
-are active in the selected task's context.
-`skills --scope all|global|site|resident` filters by activation scope. Exports accept `--filename NAME`.
-`automations --limit N` limits the automation list.
-
-Exports use Chrome downloads. The result includes the download status, ID, filename, and path when
-Chrome provides it. Check pending downloads in `chrome://downloads`. `delete` removes the named table
-or image collection and its rows. Image blobs shared by other collections or task history remain
-in the asset store.
-
-## Settings and automations
+**Claude Code**:
 
 ```bash
-qz settings
-qz settings get model
-qz settings set model MODEL_ID
-qz settings set vision true
-qz settings set '{"modelParameters":{"temperature":0.5}}'
-qz settings set - < settings.json
-qz automations
-qz automations run AUTOMATION_ID
+claude mcp add --transport http qz http://127.0.0.1:18765/mcp
 ```
 
-`settings` returns current values, editable fields, provider IDs, and protocol IDs. Credentials are
-redacted; `qz settings get apiKey` reports whether a key is configured. `set KEY VALUE` parses JSON
-values such as booleans, numbers, objects, and arrays; other values are strings. `set JSON` applies
-a patch containing the supplied top-level fields. Follow the field descriptions for values that
-replace an entire object, such as `modelParameters`.
-
-Read credential patches from stdin to keep them out of shell history. JSON is validated before
-connecting. The extension validates field names and values before saving. Browser commands accept
-`--client NAME|UUID` to select a profile. `automations run` starts an existing automation and
-returns its task ID.
-
-The CLI uses the same browser operations as MCP. Its commands correspond to tasks, data,
-images, Skills, settings, and automations. `qz mcp` only returns the connection URL for MCP
-clients.
-
-## Terminal output
-
-Interactive terminals show readable text; pipes and redirected output receive JSON. Use `--json`
-to request JSON explicitly or `--plain` to keep text when redirecting output. `--no-color` or the
-`NO_COLOR` environment variable disables color. `qz mcp` prints only the MCP URL by default;
-`qz mcp --json` returns a JSON result.
-
-In JSON mode, `--wait` and `--stream` emit one final JSON result on stdout. Complete pending-input
-notices and submission templates appear on stderr so you can respond while preserving
-machine-readable output. MCP snapshots and rejected responses include `input`, with a
-`responseTemplate` that binds answers to the current session and wait. Chrome-native permission
-requests provide user instructions instead of an approval template.
-Exit codes are `0` for success (including reading pending input), `1` for an operation or
-task failure or a rejected submission, `2` for invalid arguments, and `130` for Ctrl-C.
-Connection errors include the GitHub setup guide and installation link.
-
-## Local access
-
-The service listens on loopback. It validates Host and Origin, rejects redirects, and accepts
-extension polling only from extension origins or local clients. Ordinary websites cannot send
-requests through the MCP endpoint. Local programs can control connected qz tasks while the
-service is running. Run `qz stop` to disconnect.
-
-Connection metadata and browser registrations are stored in `~/.qz-browser-agent/run/`;
-`QZ_STATE_DIR` selects another local directory for isolated tests. Registration writes are atomic;
-a failed write leaves the previous registration active. Private pairing proofs stay in local storage
-and are omitted from status output. Atomic startup locks prevent duplicate services. Development copies
-and published installations use separate identities. The client verifies the service identity,
-protocol version, instance, and process before reusing or stopping it. Editing source files or
-running a newer package keeps the healthy service and its connections alive. `status` reports
-when a different build is available. To load the new service code, finish active work, run
-`qz stop`, then `qz connect`.
-
-## Package development
-
-The npm package name is `qz-browser-agent`; the executable name is `qz`. Local development uses
-this same package name. The repository root stays private, and this service directory is the
-publishable package. Publishing requires separate authorization and ownership of the npm name.
-
-From the repository root, install the locked dependencies and run the local source:
+**Clients with an `mcpServers` JSON config**, such as Cursor:
 
-```bash
-npm ci
-npm run qz -- --version
-npm run qz -- connect
-npm run qz -- create "Summarize the current page." --stream
-```
-
-Keep the `--` separator when forwarding options through npm. For a local `qz` executable,
-run `npm link` in `services/mcp-bridge`. JavaScript runs directly on Node.js. The published
-package contains the runtime files, tool catalog, README, and license.
-
-```bash
-npm test -- services --match node
-node tests/release/npm-package.mjs
+```json
+{
+  "mcpServers": {
+    "qz": { "url": "http://127.0.0.1:18765/mcp" }
+  }
+}
 ```
 
-The package check packs the service and installs that tarball in two clean temporary directories
-using the public npm registry. It checks the installed command, versions, MCP tools, service reuse,
-and shutdown on an isolated port. The test owns its npm configuration, cache, connection state,
-and service process. It requires network access to download dependencies.
-
-Use `--output tests/results/npm/qz-browser-agent-0.1.1.tgz` to retain the verified tarball.
-Use `--tarball PATH` to check an existing tarball. The check also runs through
-`npm test -- release --match npm-package`.
-
-## Publish to npm
-
-Choose the package version in `services/mcp-bridge/package.json`, complete the repository checks,
-and commit the intended source before publishing. CLI and MCP report that same package version.
-Each published version identifies immutable package contents; use a new version for updates.
-
-The **npm package** GitHub Actions workflow tests the CLI and the installed package on Linux,
-macOS, and Windows. On a manual run, provide the expected version. With **publish** left unchecked,
-it only validates the package and retains the tested tarball. Publishing requires a manual run
-from `main` with **publish** checked; all three platforms must pass first.
+CLI and MCP share the same browser connection. The MCP tool list is in the
+[reference](https://github.com/alibaba/qz-browser-agent/blob/main/docs/cli.md#task-and-resource-operations).
 
-Configure the npm package's trusted publisher for the `alibaba/qz-browser-agent` repository,
-workflow `npm-package.yml`, and GitHub environment `npm`. Enable direct publishing in that
-trusted publisher configuration. The publish job uses OIDC and uploads the exact Linux-tested
-tarball. The npm package must be created under an account with publishing rights before this
-trusted publisher can be configured. See [npm trusted publishing](https://docs.npmjs.com/trusted-publishers/).
+## Common commands
 
-For the first manual release, log in with npm, verify the saved tarball, and publish it:
-
-```bash
-npm login --registry=https://registry.npmjs.org
-node tests/release/npm-package.mjs --output tests/results/npm/qz-browser-agent-0.1.1.tgz
-npm publish tests/results/npm/qz-browser-agent-0.1.1.tgz --access public --registry=https://registry.npmjs.org
-```
-
-The root package stays private. Publishing the service does not publish the Chrome extension.
-After publication, check `npx qz-browser-agent@0.1.1 --version` from a directory outside the repository.
+| Command | What it does |
+| --- | --- |
+| `qz connect` | Start the local service and pair a browser |
+| `qz status` | Check the connection and service address |
+| `qz browsers` | List paired browsers, or `forget` an offline one |
+| `qz create "PROMPT"` | Start a task; add `--stream` or `--wait` to follow it |
+| `qz send TASK_ID "MESSAGE"` | Send a follow-up, or `--steer` the current run |
+| `qz tasks` | List tasks |
+| `qz show TASK_ID` | Read a task's status, response, or pending question |
+| `qz watch TASK_ID` | Follow a task until its work and queued messages finish |
+| `qz submit` / `approve` / `reject` | Answer a question or permission request |
+| `qz cancel TASK_ID` | Stop a task |
+| `qz data` | List, export, or delete data tables |
+| `qz images` | List, export, or delete image collections |
+| `qz skills` | Find, read, or export Skills |
+| `qz settings` | Read or update settings |
+| `qz automations` | List or run automations |
+| `qz stop` | Stop the local service and disconnect all browsers |
+
+With several browser profiles connected, choose one with `--client NAME|UUID` (or `-c`).
+Run `qz COMMAND --help` for options. Interactive terminals show readable text; pipes receive JSON.
+
+`watch`, `--wait`, and `--stream` follow the same task across runs until its current work and
+accepted follow-ups and steering messages have completed and its queues are empty. Questions
+and permission requests keep observation open. Task failure or stopping ends observation.
+Timeout or Ctrl-C ends observation while the browser task continues; execute the returned
+`watch` command with the same task ID and browser UUID to resume. Observation never resends messages.
+
+## Privacy and local access
+
+The service accepts connections only on your computer, and ordinary websites cannot use its MCP
+endpoint. Local programs can control connected qz tasks while the service is running. `qz stop`
+disconnects all browsers and MCP clients; tasks already running in the browser keep going.
+Connection settings are stored in `~/.qz-browser-agent/run/`, and pairing credentials never
+leave your computer.
+
+## Reference
+
+See the [qz CLI and MCP reference](https://github.com/alibaba/qz-browser-agent/blob/main/docs/cli.md)
+for pairing a specific browser profile, Windows PowerShell notes, updates, task responses,
+exports, output formats, exit codes, and the MCP tool mapping.
+
+## License
+
+[Apache-2.0](https://github.com/alibaba/qz-browser-agent/blob/main/LICENSE)

package/package.json

@@ -1,9 +1,9 @@
 {
   "name": "qz-browser-agent",
-  "version": "0.1.1",
+  "version": "0.1.3",
   "description": "Local browser tools and MCP access for the qz extension",
   "type": "module",
-  "engines": { "node": ">=24" },
+  "engines": { "node": ">=22" },
   "bin": { "qz": "src/bin.mjs" },
   "files": ["src/*.mjs", "src/catalog.json", "README.md", "LICENSE"],
   "license": "Apache-2.0",

package/src/bin.mjs

@@ -7,19 +7,17 @@ let isEntry = false;
 try { isEntry = realpathSync(process.argv[1]) === fileURLToPath(import.meta.url); } catch {}
 if (isEntry) {
   const argv = process.argv.slice(2);
-  if (Number(process.versions.node.split(".")[0]) < 24) {
+  if (Number(process.versions.node.split(".")[0]) < 22) {
     const error = {
       code: "unsupported_node_version",
-      message: `qz requires Node.js 24 or later. Current version: ${process.versions.node}.`,
-      hint: "Install Node.js 24 or later, then run qz again.",
+      message: `qz requires Node.js 22 or later. Current version: ${process.versions.node}.`,
+      hint: "Install Node.js 22 or later, then run qz again.",
     };
     if (argv.includes("--json")) process.stdout.write(`${JSON.stringify({ ok: false, error })}\n`);
     else process.stderr.write(`${error.message}\n${error.hint}\n`);
     process.exitCode = 1;
   } else {
-    const { main } = await import("./cli.mjs");
-    const controller = new AbortController();
-    process.once("SIGINT", () => controller.abort());
-    process.exitCode = await main(argv, { signal: controller.signal });
+    const { runMain } = await import("./cli.mjs");
+    process.exitCode = await runMain(argv);
   }
 }

package/src/catalog.json

@@ -62,10 +62,10 @@
   },
   {
     "name": "qingzhou_create_session",
-    "description": "Create a task with an optional first message. Set wait=true to return its completed snapshot, or stream=true for progress events. User-input waits keep observation open. Cancellation stops observing; the browser task continues.",
+    "description": "Create a task with an optional first message. Set wait=true to follow the same task across runs until its current work and accepted follow-ups and steering messages have completed and its queues are empty. stream=true adds progress events. User-input waits keep observation open. Task failure or stopping ends observation. Timeout or cancellation ends observation while the browser task continues; use the returned watch recovery call without resubmitting.",
     "inputSchema": {
       "properties": {
-        "wait": {"type": "boolean", "default": false, "description": "Keep observing until the task finishes, including user-input waits."},
+        "wait": {"type": "boolean", "default": false, "description": "Follow the same task across runs until its work completes and its accepted follow-up and steering queues are empty. User-input waits keep observation open; task failure or stopping ends it."},
         "stream": {"type": "boolean", "default": false, "description": "Implies wait. Send task text, status, and input events through MCP progress notifications when a progressToken is supplied."},
         "waitTimeoutSeconds": {"type": ["number", "null"], "exclusiveMinimum": 0, "maximum": 86400, "default": null, "description": "Optional total observation deadline; null waits indefinitely. timeoutSeconds bounds each browser request."},
         "title": {"default": "", "title": "Title", "type": "string"},
@@ -80,10 +80,10 @@
   },
   {
     "name": "qingzhou_send_message",
-    "description": "Send a message to the specified task. By default, a busy task queues a follow-up for its next run. Set steer=true to guide its current run at the next safe boundary. An idle task starts with either mode. Returns deliveryMode, disposition, and clientMessageId for tracking. Set wait=true to observe the submitted message through completion, including queued follow-ups and user-input waits. stream=true also emits text through MCP progress notifications.",
+    "description": "Send a message to the specified task. By default, a busy task queues a follow-up for its next run. Set steer=true to guide its current run at the next safe boundary. An idle task starts with either mode. Returns deliveryMode, disposition, and clientMessageId to confirm acceptance. Set wait=true to follow the same task across runs until its work completes and its follow-up and steering queues are empty. A queued message removed before execution no longer blocks completion. stream=true emits text from the submitted message onward through MCP progress notifications. Timeout or cancellation ends observation; use the returned watch recovery call without resubmitting.",
     "inputSchema": {
       "properties": {
-        "wait": {"type": "boolean", "default": false, "description": "Keep observing until the task finishes, including user-input waits."},
+        "wait": {"type": "boolean", "default": false, "description": "Follow the same task across runs until its work completes and its accepted follow-up and steering queues are empty. User-input waits keep observation open; task failure or stopping ends it."},
         "stream": {"type": "boolean", "default": false, "description": "Implies wait. Send task text, status, and input events through MCP progress notifications when a progressToken is supplied."},
         "waitTimeoutSeconds": {"type": ["number", "null"], "exclusiveMinimum": 0, "maximum": 86400, "default": null, "description": "Optional total observation deadline; null waits indefinitely. timeoutSeconds bounds each browser request."},
         "text": {"title": "Text", "type": "string"},
@@ -150,7 +150,7 @@
     "description": "Respond using the pending input's responseTemplate: fill answers keyed by field IDs with option values for choices (arrays for multi_choice), then submit; approve a completed action or application consent, or reject. Show location disclosures and obtain explicit user consent before approving with consentVersion. Native Chrome permissions require the user's click in qz. Invalid or stale replies return the current input for correction and keep the request pending.",
     "inputSchema": {
       "properties": {
-        "wait": {"type": "boolean", "default": false, "description": "Keep observing until the task finishes, including user-input waits."},
+        "wait": {"type": "boolean", "default": false, "description": "Follow the same task across runs until its work completes and its accepted follow-up and steering queues are empty. User-input waits keep observation open; task failure or stopping ends it."},
         "stream": {"type": "boolean", "default": false, "description": "Implies wait. Send task text, status, and input events through MCP progress notifications when a progressToken is supplied."},
         "waitTimeoutSeconds": {"type": ["number", "null"], "exclusiveMinimum": 0, "maximum": 86400, "default": null, "description": "Optional total observation deadline; null waits indefinitely. timeoutSeconds bounds each browser request."},
         "sessionId": {"type": "string", "minLength": 1},
@@ -357,7 +357,7 @@
   },
   {
     "name": "qingzhou_watch_task",
-    "description": "Observe an existing task until it finishes without resubmitting it. Questions and Chrome permission requests keep observation open; MCP progress notifications include their full input and responseTemplate. stream=true includes text updates. Cancellation stops observing while the task continues.",
+    "description": "Observe an existing task across runs until its current work and accepted follow-ups and steering messages have completed and its queues are empty, without resubmitting anything. Questions and Chrome permission requests keep observation open; MCP progress notifications include their full input and responseTemplate. stream=true includes text updates. Task failure or stopping ends observation. Timeout or cancellation ends observation while the browser task continues; resume with the returned recovery call using the same sessionId and clientId.",
     "inputSchema": {
       "type": "object",
       "properties": {

package/src/cli.mjs

@@ -7,7 +7,7 @@ import { ensureDaemon, findDaemon, stopDaemon } from "./daemon.mjs";
 import { openBrowser } from "./open-browser.mjs";
 import { parseCommand } from "./args.mjs";
 import { renderError, renderHelp, renderResult, renderInputNotice, sanitizeTerminalText } from "./terminal.mjs";
-import { waitForTask } from "./task-stream.mjs";
+import { TASK_NOT_FOUND_MESSAGE, waitForTask } from "./task-stream.mjs";
 import { createLiveOutput, outputMode } from "./output.mjs";
 import { resourceRequest, settingsPatch } from "./cli-resources.mjs";
 import { PACKAGE_NAME, PACKAGE_VERSION } from "./package-info.mjs";
@@ -73,11 +73,18 @@ function recoveryCommand(command, sessionId, clientId, stream = false) {
   if (clientId && sanitizeTerminalText(clientId) !== String(clientId)) clientId = "CLIENT_ID";
   const client = clientId ? ` --client${String(clientId).startsWith("-") ? "=" : " "}${shellArgument(clientId)}` : "";
   const options = `${client}${stream ? " --stream" : ""}`;
+  if (!sessionId) return `qz ${command}${options}`;
   return String(sessionId).startsWith("-")
     ? `qz ${command}${options} ${optionTerminator()} ${shellArgument(sessionId)}`
     : `qz ${command} ${shellArgument(sessionId)}${options}`;
 }
 
+function missingTaskDetails(sessionId, clientId) {
+  return { sessionId, ...(clientId ? { clientId } : {}),
+    hint: "Check the task ID and selected browser. Run qz browsers to inspect browser names and UUIDs. List tasks in the selected browser:",
+    command: recoveryCommand("tasks", "", clientId) };
+}
+
 export async function runCli(argv, dependencies = {}) {
   return executeCommand(parseCommand(argv), dependencies);
 }
@@ -206,19 +213,20 @@ async function dispatchCommand(parsed, dependencies) {
       throw error;
     }
   };
-  const observe = async (sessionId, { runId = "", expectedMessageId = "", previousRunId = "", ignoreWaitId = "", allowIdle = false } = {}) => {
+  const observe = async (sessionId, { runId = "", expectedMessageId = "", messageWasQueued = false, ignoreWaitId = "", allowIdle = false } = {}) => {
     try {
       const remaining = waitTimeoutSeconds == null ? null : waitTimeoutSeconds - (Date.now() - startedAt) / 1000;
       if (remaining !== null && remaining <= 0) throw new DOMException("Stopped watching after the configured --timeout. The browser task may still be running.", "TimeoutError");
       return await waitForTask({
         sessionId, clientId: common.clientId, timeoutSeconds: remaining, signal: dependencies.signal,
         requestTimeoutSeconds: timeoutSeconds,
-        expectedRunId: runId, expectedMessageId, previousRunId, ignoreWaitId, allowIdle,
+        expectedRunId: runId, expectedMessageId, messageWasQueued, ignoreWaitId, allowIdle,
         onUpdate: dependencies.onTaskUpdate,
         getSnapshot: ({ timeoutSeconds: seconds, signal }) => readSnapshot(sessionId, seconds, signal),
       });
     } catch (error) {
       const code = error.name === "TimeoutError" ? "timeout" : error.name === "AbortError" ? "interrupted" : error.code || "task_wait_failed";
+      if (code === "task_deleted") throw new QzError(code, error.message, { ...error.details, ...missingTaskDetails(sessionId, clientId) });
       const changed = code === "task_changed";
       throw new QzError(code, code === "timeout"
         ? "Stopped watching after the configured --timeout. The browser task may still be running." : error.message,
@@ -237,7 +245,9 @@ async function dispatchCommand(parsed, dependencies) {
           sessionId: id, hint: "Continue watching the same task:", command: recoveryCommand("watch", id, clientId, true),
         });
       }
-      result = { ...result, snapshot: await observe(id, { expectedMessageId: result.clientMessageId }) };
+      result = { ...result, snapshot: await observe(id, {
+        expectedMessageId: result.clientMessageId, messageWasQueued: result.disposition === "queued",
+      }) };
     }
     return { result };
   }
@@ -283,6 +293,9 @@ async function dispatchCommand(parsed, dependencies) {
       ...(action === "list" && options.limit !== undefined ? { limit: Number(options.limit) } : {}) };
   }
   let result = await call(running.endpoint, name, parameters, requestOptions);
+  if (command === "tasks" && action === "get" && result?.session === null) {
+    throw new QzError("task_not_found", TASK_NOT_FOUND_MESSAGE, missingTaskDetails(id, clientId));
+  }
   if (command === "tasks" && action === "create" && options.wait) {
     const sessionId = result?.session?.id || result?.sessionId;
     if (!sessionId) throw new QzError("invalid_response", "The task was created without an ID. Run qz tasks to find it before retrying.");
@@ -351,10 +364,30 @@ export async function main(argv = process.argv.slice(2), dependencies = {}) {
   }
 }
 
+/** Keep handlers installed while npm forwards duplicate signals and MCP closes. */
+export async function runMain(argv = process.argv.slice(2), dependencies = {}) {
+  const controller = new AbortController();
+  let interruptedExitCode;
+  const interrupt = code => {
+    if (controller.signal.aborted) return;
+    interruptedExitCode = code;
+    controller.abort();
+  };
+  const onSigint = () => interrupt(130);
+  const onSigterm = () => interrupt(143);
+  process.on("SIGINT", onSigint);
+  process.on("SIGTERM", onSigterm);
+  try {
+    const code = await main(argv, { ...dependencies, signal: controller.signal });
+    return interruptedExitCode ?? code;
+  } finally {
+    process.removeListener("SIGINT", onSigint);
+    process.removeListener("SIGTERM", onSigterm);
+  }
+}
+
 let isEntry = false;
 try { isEntry = realpathSync(process.argv[1]) === fileURLToPath(import.meta.url); } catch {}
 if (isEntry) {
-  const controller = new AbortController();
-  process.once("SIGINT", () => controller.abort());
-  process.exitCode = await main(process.argv.slice(2), { signal: controller.signal });
+  process.exitCode = await runMain();
 }

package/src/client.mjs

@@ -1,5 +1,4 @@
 import { request } from "node:http";
-import { Readable } from "node:stream";
 import { Client } from "@modelcontextprotocol/sdk/client/index.js";
 import { StreamableHTTPClientTransport } from "@modelcontextprotocol/sdk/client/streamableHttp.js";
 import { PACKAGE_VERSION } from "./package-info.mjs";
@@ -27,6 +26,19 @@ export function localUrl(value) {
   return url;
 }
 
+function responseBody(response) {
+  const iterator = response[Symbol.asyncIterator]();
+  return {
+    [Symbol.asyncIterator]() { return this; },
+    next: () => iterator.next(),
+    return() {
+      // An iterator return waits behind a pending read. Destroy the HTTP stream first.
+      response.destroy();
+      return iterator.return();
+    },
+  };
+}
+
 // node:http does not inherit proxy environment settings. Every MCP request stays on loopback.
 export async function localFetch(input, init) {
   const prepared = new Request(input, init);
@@ -42,7 +54,7 @@ export async function localFetch(input, init) {
         return;
       }
       try {
-        resolve(new Response([204, 304].includes(res.statusCode) ? null : Readable.toWeb(res), {
+        resolve(new Response([204, 304].includes(res.statusCode) ? null : responseBody(res), {
           status: res.statusCode, headers: new Headers(Object.entries(res.headers)
             .flatMap(([key, value]) => Array.isArray(value) ? value.map(item => [key, item]) : value === undefined ? [] : [[key, value]])),
         }));

package/src/commands.mjs

@@ -14,7 +14,7 @@ export const COMMANDS = {
   create: { options: [...waiting, "title", "parent"], summary: "Start a task",
     help: ['qz create "PROMPT" [--title TITLE] [--wait | --stream]', "Start a browser task. The title is optional.",
       "--title, -t  Set the task title. --parent TASK_ID creates a child task.",
-      "--wait    Wait for completion, including pauses for user input.", "--stream  Show responses as they arrive; also wait.",
+      "--wait    Follow the task across runs until its work completes and accepted message queues are empty; user-input pauses keep waiting.", "--stream  Show responses as they arrive; also wait.",
       "Use - as the prompt to read stdin.",
       'qz create "Compare these two pages." --stream', 'qz create "Summarize this page." --title Research --wait'],
   },
@@ -22,7 +22,8 @@ export const COMMANDS = {
     help: ['qz send TASK_ID "MESSAGE" [--steer] [--wait | --stream]', "Send a follow-up or steer a specific task.",
       "A busy task queues a follow-up for its next run. --steer delivers the message to the current run at its next safe boundary.",
       "Both start a new run when the task is idle. Pending questions and permissions still require a response.",
-      "Use - as the message to read stdin. --wait follows the submitted message; --stream also shows its responses.",
+      "Use - as the message to read stdin. --wait follows the task until its work completes and queues are empty; removed queued messages no longer block completion.",
+      "--stream also shows responses from this message onward, including later runs.",
       'qz send TASK_ID "Add the source links." --stream', 'qz send TASK_ID "Focus on open-source options." --steer --stream'],
   },
   tasks: { options: [...request, "limit"], summary: "List tasks",
@@ -32,19 +33,20 @@ export const COMMANDS = {
     help: ["qz show TASK_ID", "Show task status, the latest response, and any pending form or permission request.", "Pending input includes field IDs, option values, and a submission template. Use --json for the complete snapshot.", "qz show TASK_ID --json"],
   },
   watch: { options: [...request, "stream"], summary: "Wait for a task",
-    help: ["qz watch TASK_ID [--stream]", "Wait for an existing task to finish, including pauses for user input.", "--stream  Show assistant responses as they arrive.", "Timeout or Ctrl-C ends watching without cancelling the task."],
+    help: ["qz watch TASK_ID [--stream]", "Follow an existing task across runs until its work completes and accepted message queues are empty; user-input pauses keep waiting.", "--stream  Show assistant responses as they arrive.", "Task failure or stopping ends observation. Timeout or Ctrl-C ends watching without cancelling the task.", "Resume with the returned watch command for the same task and browser; observation never resends messages."],
   },
   submit: { options: [...waiting, "wait-id"], summary: "Answer a form",
     help: ["qz submit TASK_ID JSON [--wait | --stream]", "Submit answers to the current form. Use - to read JSON from stdin.",
       "--wait-id ID  Bind the response to a previously read wait. Otherwise qz reads the current wait before submitting.",
+      "--wait and --stream follow the task across runs until its work completes and accepted message queues are empty.",
       'qz submit TASK_ID \'{"selectedIds":["option-a"]}\' --stream'],
   },
   approve: { options: [...waiting, "wait-id"], summary: "Continue a waiting task",
     help: ["qz approve TASK_ID [--wait | --stream]", "Continue after completing a requested action.",
-      "Review app consent notices with qz show before approving. Native browser permissions require a click in the qz side panel.", "--wait-id ID  Respond only to this wait."],
+      "Review app consent notices with qz show before approving. Native browser permissions require a click in the qz side panel.", "--wait-id ID  Respond only to this wait.", "--wait and --stream follow the task across runs until its work completes and accepted message queues are empty."],
   },
   reject: { options: [...waiting, "wait-id"], summary: "Decline a pending request",
-    help: ["qz reject TASK_ID [--wait-id ID] [--wait | --stream]", "Decline the pending request and optionally follow the task's next step. Use qz cancel TASK_ID to stop the whole task."],
+    help: ["qz reject TASK_ID [--wait-id ID] [--wait | --stream]", "Decline the pending request. --wait and --stream follow the task across runs until its work completes and accepted message queues are empty. Use qz cancel TASK_ID to stop the whole task."],
   },
   cancel: { options: request, summary: "Stop a task",
     help: ["qz cancel TASK_ID", "Stop a task's active run.", "qz stop stops the local service instead."],

package/src/task-stream.mjs

@@ -1,16 +1,24 @@
 import { setTimeout as delay } from "node:timers/promises";
 
-const STOP_STATUSES = new Set(["completed", "error", "failed", "aborted", "cancelled", "interrupted"]);
+const FAILURE_STATUSES = new Set(["error", "failed", "aborted", "cancelled", "interrupted"]);
 const ACTIVE_STATUSES = new Set(["pending", "running", "waiting_user", "paused"]);
 const INPUT_STATUSES = new Set(["waiting_user", "paused"]);
+const QUEUE_FIELDS = ["pendingFollowUps", "pendingFollowUpMessages", "pendingSteerings", "pendingSteeringMessages"];
 const record = value => value && typeof value === "object" && !Array.isArray(value) ? value : {};
 
+export const TASK_NOT_FOUND_MESSAGE = "The task was not found in the selected browser. It may have been deleted, the task ID may be incorrect, or a different browser may be selected.";
+
 function taskStatus(snapshot) {
   const status = String(snapshot.status || snapshot.runtime?.status || snapshot.state?.status || "").trim();
   if (status === "waitingUser") return "waiting_user";
   return status.toLowerCase() === "canceled" ? "cancelled" : status.toLowerCase();
 }
 
+function hasPendingWork(runtime) {
+  return runtime.running === true || runtime.pendingStart === true
+    || QUEUE_FIELDS.some(key => Array.isArray(runtime[key]) && runtime[key].length > 0);
+}
+
 function assistantText(content) {
   if (typeof content === "string") return content;
   return Array.isArray(content) ? content.filter(part => part?.type === "text")
@@ -35,12 +43,13 @@ function abortable(operation, signal) {
 }
 
 /** Observe snapshots only: timeout, interruption, and polling failures never cancel or restart a browser task.
+ * Follow one Session across runs until execution and its accepted queues are finished.
  * User input pauses execution, not observation; input events expose each pending request.
  * Total observation is unlimited by default; each snapshot request has its own finite deadline.
  * getSnapshot must request compact:false and tail:false so transcript identities and streaming text survive.
  */
 export async function waitForTask({ sessionId, clientId, timeoutSeconds = null, requestTimeoutSeconds = 180, signal, getSnapshot, onUpdate,
-  pollIntervalMs = 750, expectedRunId = "", expectedMessageId = "", previousRunId = "", ignoreWaitId = "", allowIdle = false } = {}) {
+  pollIntervalMs = 750, expectedRunId = "", expectedMessageId = "", messageWasQueued = false, ignoreWaitId = "", allowIdle = false } = {}) {
   if (!String(sessionId || "").trim()) throw new TypeError("sessionId is required");
   if (typeof getSnapshot !== "function") throw new TypeError("getSnapshot is required");
   if (timeoutSeconds !== null && (!Number.isFinite(timeoutSeconds) || timeoutSeconds <= 0)) throw new TypeError("timeoutSeconds must be positive or null");
@@ -55,8 +64,8 @@ export async function waitForTask({ sessionId, clientId, timeoutSeconds = null,
     if (deadline !== null && Date.now() >= deadline) controller.abort(timeout);
     activeSignal.throwIfAborted();
   };
-  const pollingDelay = () => delay(deadline === null ? pollIntervalMs : Math.min(pollIntervalMs, Math.max(0, deadline - Date.now())),
-    undefined, { signal: activeSignal });
+  // The total deadline cancels this sleep; shortening it can wake before that deadline.
+  const pollingDelay = () => delay(pollIntervalMs, undefined, { signal: activeSignal });
   const readSnapshot = async () => {
     checkActive();
     const milliseconds = Math.max(1, Math.ceil(requestTimeoutSeconds * 1000));
@@ -84,12 +93,11 @@ export async function waitForTask({ sessionId, clientId, timeoutSeconds = null,
     }
   };
   const messages = new Map();
-  let selectedRunId = String(expectedRunId || "");
-  let observedRun = false;
+  let firstRunId = String(expectedRunId || "");
+  let trackingReady = false;
   let observedActivity = false;
   let awaitingMessage = Boolean(expectedMessageId);
-  let messageRunId = "";
-  let awaitingResume = Boolean(ignoreWaitId);
+  let observedQueuedMessage = messageWasQueued;
   let lastStatus = "";
   let lastInput = "";
   const emit = async update => {
@@ -122,7 +130,7 @@ export async function waitForTask({ sessionId, clientId, timeoutSeconds = null,
         throw Object.assign(new Error("The task snapshot belongs to a different session."), { code: "task_changed" });
       }
       if (Object.hasOwn(snapshot, "session") && snapshot.session === null) {
-        throw Object.assign(new Error("The task was deleted while waiting for its result."), { code: "task_deleted" });
+        throw Object.assign(new Error(TASK_NOT_FOUND_MESSAGE), { code: "task_deleted" });
       }
       const runtime = record(snapshot.runtime);
       const canonicalInput = Object.hasOwn(snapshot, "input") ? record(snapshot.input) : null;
@@ -135,67 +143,63 @@ export async function waitForTask({ sessionId, clientId, timeoutSeconds = null,
       const transcript = Array.isArray(snapshot.transcript) ? snapshot.transcript : Array.isArray(snapshot.tail) ? snapshot.tail : [];
       const submittedMessageIndex = expectedMessageId
         ? transcript.findIndex(entry => entry?.type === "user" && entry.clientMessageId === expectedMessageId) : -1;
-      if (awaitingMessage) {
-        const message = transcript[submittedMessageIndex];
-        if (message?.runId) {
-          messageRunId = String(message.runId);
-          selectedRunId = messageRunId;
-          awaitingMessage = false;
-        } else {
-          // A queued message may wait behind an earlier run's question or permission.
-          // Keep that input actionable, but never mistake its answer for this message's result.
-          if (status !== "completed") await emitStatus(status, runId, runtime);
-          await emitInput(status, runId, runtime, canonicalInput);
-          if (STOP_STATUSES.has(status) && status !== "completed") return snapshot;
-          await pollingDelay();
-          continue;
-        }
+      if (awaitingMessage && QUEUE_FIELDS.some(key => Array.isArray(runtime[key])
+        && runtime[key].some(message => message?.clientMessageId === expectedMessageId))) observedQueuedMessage = true;
+      const submittedMessage = transcript[submittedMessageIndex];
+      if (awaitingMessage && submittedMessage?.runId) {
+        firstRunId = String(submittedMessage.runId);
+        awaitingMessage = false;
       }
-      const previous = previousRunId && (!runId || runId === previousRunId);
-      const awaitedRunId = messageRunId || expectedRunId;
-      const awaitingExpected = awaitedRunId && runId !== awaitedRunId;
       const targetIndex = submittedMessageIndex >= 0 ? submittedMessageIndex
-        : awaitedRunId ? transcript.findIndex(entry => entry?.runId === awaitedRunId) : -1;
-      // A fast queued run can finish before the first poll. A later accepted user message
-      // distinguishes that replacement from an older runtime snapshot still catching up.
-      const passedTarget = awaitingExpected && runId && targetIndex >= 0
+        : firstRunId ? transcript.findIndex(entry => entry?.runId === firstRunId) : -1;
+      // The runtime can lag the transcript or skip whole runs between polls. Admit the
+      // target run or a proven successor once, then follow the Session without a run fence.
+      const passedTarget = runId && targetIndex >= 0
         && transcript.slice(targetIndex + 1).some(entry => entry?.type === "user" && entry.runId === runId);
-      if ((observedRun && runId && selectedRunId !== runId) || passedTarget) {
-        throw Object.assign(new Error("A different run replaced the task being watched. Use qz show to inspect its conversation."), {
-          code: "task_changed", details: { expectedRunId: selectedRunId || awaitedRunId, actualRunId: runId },
-        });
+      // Resolving a wait and persisting its updated snapshot are separate operations.
+      // Ignore that exact old wait even while its runtime lags the acknowledged run.
+      const oldWait = !trackingReady && ignoreWaitId && status === "waiting_user" && String(canonicalInput?.waitId || runtime.waitId || "") === ignoreWaitId;
+      if (oldWait) {
+        await pollingDelay();
+        continue;
       }
-      if (!previous && !awaitingExpected) {
-        if (runId) { selectedRunId = runId; observedRun = true; }
-        // Resolving a wait and persisting its updated snapshot are separate operations.
-        // Ignore that exact old wait until the resumed run or its next wait is visible.
-        const oldWait = awaitingResume && status === "waiting_user" && String(canonicalInput?.waitId || runtime.waitId || "") === ignoreWaitId;
-        if (oldWait) {
-          await pollingDelay();
-          continue;
-        }
-        awaitingResume = false;
-        if (ACTIVE_STATUSES.has(status)) observedActivity = true;
-        await emitStatus(status, runId, runtime);
-        for (const [index, entry] of transcript.entries()) {
-          // Steering can continue the same run. Only stream responses after this submitted message.
-          if (expectedMessageId && (submittedMessageIndex < 0 || index <= submittedMessageIndex)) continue;
-          if (entry?.type !== "assistant" || (entry.runId && selectedRunId && entry.runId !== selectedRunId)) continue;
-          const messageId = messageIdentity(entry, index, selectedRunId);
-          const fullText = assistantText(entry.content);
-          const seen = messages.has(messageId);
-          const previousText = messages.get(messageId) || "";
-          if (fullText === previousText) continue;
-          messages.set(messageId, fullText);
-          const append = fullText.startsWith(previousText);
-          await emit({ type: append ? "text" : "replace", sessionId, runId: String(entry.runId || runId), messageId,
-            text: append ? fullText.slice(previousText.length) : fullText, fullText,
-            newMessage: !seen, streaming: entry.streaming === true });
-        }
+      if (!trackingReady && (awaitingMessage || (firstRunId && runId !== firstRunId && !passedTarget))) {
+        // Queue acceptance precedes these reads; pending precedes dequeue. A settled
+        // task with no trace of an accepted queued message means it was removed.
+        const removedMessage = awaitingMessage && observedQueuedMessage && submittedMessageIndex < 0
+          && status === "completed" && !hasPendingWork(runtime);
+        // A queued message can wait behind another run's question. Keep it actionable,
+        // but do not emit its earlier answer or accept its successful completion.
+        if (status !== "completed" || removedMessage) await emitStatus(status, runId, runtime);
         await emitInput(status, runId, runtime, canonicalInput);
-        // A newly created session can report idle before its first run starts.
-        if (STOP_STATUSES.has(status) || (status === "idle" && (observedActivity || allowIdle))) return snapshot;
+        if (FAILURE_STATUSES.has(status) || removedMessage) return snapshot;
+        await pollingDelay();
+        continue;
+      }
+      trackingReady = true;
+      if (!firstRunId && runId) firstRunId = runId;
+      if (ACTIVE_STATUSES.has(status)) observedActivity = true;
+      await emitStatus(status, runId, runtime);
+      for (const [index, entry] of transcript.entries()) {
+        // Steering can continue the same run. Only stream responses after this submitted message.
+        if (expectedMessageId && (submittedMessageIndex < 0 || index <= submittedMessageIndex)) continue;
+        if (entry?.type !== "assistant") continue;
+        if (!expectedMessageId && (targetIndex >= 0 ? index < targetIndex : entry.runId && entry.runId !== runId)) continue;
+        const messageId = messageIdentity(entry, index, firstRunId);
+        const fullText = assistantText(entry.content);
+        const seen = messages.has(messageId);
+        const previousText = messages.get(messageId) || "";
+        if (fullText === previousText) continue;
+        messages.set(messageId, fullText);
+        const append = fullText.startsWith(previousText);
+        await emit({ type: append ? "text" : "replace", sessionId, runId: String(entry.runId || runId), messageId,
+          text: append ? fullText.slice(previousText.length) : fullText, fullText,
+          newMessage: !seen, streaming: entry.streaming === true });
       }
+      await emitInput(status, runId, runtime, canonicalInput);
+      // A newly created session can report idle before its first run starts.
+      if (FAILURE_STATUSES.has(status) || (!hasPendingWork(runtime)
+        && (status === "completed" || (status === "idle" && (observedActivity || allowIdle))))) return snapshot;
       await pollingDelay();
     }
   } catch (error) {

package/src/terminal.mjs

@@ -7,7 +7,9 @@ const palette = { accent: 36, muted: 90, error: 31, waiting: 33 };
 
 // Remote pages and model responses are text, never terminal instructions.
 export function sanitizeTerminalText(value) {
-  return stripVTControlCharacters(String(value ?? ""))
+  // Early Node 22 versions do not strip OSC strings terminated by ESC + backslash.
+  const text = String(value ?? "").replace(/(?:\u001b\]|\u009d)[\s\S]*?(?:\u0007|\u001b\\|\u009c|$)/g, "");
+  return stripVTControlCharacters(text)
     .replace(/\r\n?/g, "\n")
     .replace(/[\u0000-\u0008\u000b-\u001f\u007f-\u009f]/g, "")
     .replace(/[\u061c\u200e\u200f\u202a-\u202e\u2066-\u2069]/g, "")

package/src/tools.mjs

@@ -78,7 +78,7 @@ async function executeBrowserTool(state, name, args, { signal, connectionSignal,
       if (remaining !== null && remaining <= 0) throw new DOMException("Stopped watching after waitTimeoutSeconds. The browser task may still be running.", "TimeoutError");
       return await waitForTask({ sessionId, clientId: args.clientId, signal, timeoutSeconds: remaining,
         requestTimeoutSeconds: args.timeoutSeconds || state.requestTimeoutSeconds || 180,
-        expectedRunId: tracking.runId, expectedMessageId: tracking.clientMessageId,
+        expectedRunId: tracking.runId, expectedMessageId: tracking.clientMessageId, messageWasQueued: tracking.disposition === "queued",
         ignoreWaitId: tracking.ignoreWaitId, allowIdle: tracking.allowIdle,
         onUpdate: onTaskUpdate && (event => args.stream || !["text", "replace"].includes(event.type) ? onTaskUpdate(event) : undefined),
         getSnapshot: async ({ signal: requestSignal, timeoutSeconds }) => bindInputClient("qingzhou_get_session_snapshot",
@@ -91,8 +91,10 @@ async function executeBrowserTool(state, name, args, { signal, connectionSignal,
         : cause.name === "TimeoutError" ? "timeout" : cause.name === "AbortError" ? "interrupted" : "task_wait_failed";
       const error = Object.assign(new Error(cause.message, { cause }), { code });
       error.details = { ...cause.details, sessionId, clientId: args.clientId,
-        recovery: { tool: code === "task_changed" ? "qingzhou_get_session_snapshot" : "qingzhou_watch_task",
-          arguments: { sessionId, clientId: args.clientId } } };
+        recovery: code === "task_deleted"
+          ? { tool: "qingzhou_list_sessions", arguments: { clientId: args.clientId } }
+          : { tool: code === "task_changed" ? "qingzhou_get_session_snapshot" : "qingzhou_watch_task",
+            arguments: { sessionId, clientId: args.clientId } } };
       throw error;
     }
   };
@@ -138,9 +140,11 @@ async function executeBrowserTool(state, name, args, { signal, connectionSignal,
       result = { ...result, snapshot: await watch(sessionId, { allowIdle: !args.firstMessage.trim() }) };
     } else if (name === "qingzhou_send_message" && result?.accepted === true) {
       if (typeof result.clientMessageId !== "string" || !result.clientMessageId.trim()) {
-        throw new BridgeError("invalid_response", "The message was accepted without a tracking ID. Inspect the task before sending it again.");
+        throw Object.assign(new BridgeError("invalid_response", "The message was accepted without a tracking ID. Continue watching the same task before sending it again."), {
+          details: { sessionId, clientId, recovery: { tool: "qingzhou_watch_task", arguments: { sessionId, clientId } } },
+        });
       }
-      result = { ...result, snapshot: await watch(sessionId, { clientMessageId: result.clientMessageId }) };
+      result = { ...result, snapshot: await watch(sessionId, { clientMessageId: result.clientMessageId, disposition: result.disposition }) };
     } else if (name === "qingzhou_respond_to_user_input" && (result?.accepted === true || result?.requiresUserAction)) {
       const snapshot = await watch(sessionId, { runId: result.runId || "", ignoreWaitId: result.requiresUserAction ? "" : args.waitId });
       result = result.requiresUserAction ? { sessionId, waitId: args.waitId, snapshot } : { ...result, snapshot };