@dassi_ai/cli 0.4.0 → 0.7.0

package/.claude-plugin/plugin.json

@@ -1,12 +1,17 @@
 {
   "name": "dassi",
-  "description": "Drive the Dassi Chrome extension from Claude Code. Pick tabs/groups, then run AI agent or browser tools against them.",
-  "version": "0.1.3",
+  "description": "Use Dassi in Chrome: select a browser target, operate pages directly, or delegate a task and retrieve its result.",
+  "version": "0.4.0",
   "author": {
     "name": "Omnify Labs",
     "email": "team@dassi.ai"
   },
   "homepage": "https://dassi.ai",
   "license": "MIT",
-  "keywords": ["browser", "automation", "chrome-extension", "agent"]
+  "keywords": [
+    "browser",
+    "automation",
+    "chrome-extension",
+    "agent"
+  ]
 }

package/README.md

@@ -1,152 +1,163 @@
-# @dassi_ai/cli
+# Dassi CLI
 
-Standalone CLI for the [Dassi](../extension/README.md) Chrome extension — run browser automation from the terminal.
+Control Dassi in Chrome from a terminal or a local agent such as Codex, Claude Code, or OpenCode. Requires Node ≥20.11 with npm, and Google Chrome on the same macOS or Linux machine.
 
-## Quickstart
+## One-command setup
 
-```bash
-# 1. Install the Dassi extension from the Chrome Web Store and sign in.
-# 2. Open the Dassi side panel once — this wakes the extension so the CLI can reach it.
-# 3. Run a command (no install needed):
-npx @dassi_ai/cli@latest list-tabs                 # find a TAB ID
-npx @dassi_ai/cli@latest run "summarize this page" --tab <id>
+```sh
+npx --yes @dassi_ai/cli@latest setup
 ```
 
-Prefer a permanent `dassi` command? `npm install -g @dassi_ai/cli` (Node ≥ 20.11), then drop the `npx @dassi_ai/cli@latest` prefix.
+Setup installs the CLI into npm's global location and registers its bundled skill in `~/.agents/skills/dassi` (Codex/OpenCode) and `~/.claude/skills/dassi` (Claude Code). It honors `CLAUDE_CONFIG_DIR` for Claude's location. The terminal command and agent launcher use that same npm package. An existing global install is reused; an npx invocation copies its package out of the temporary cache using npm's `--install-links`. Existing skills pointing elsewhere are preserved and reported for manual resolution.
 
-Two things that trip people up:
-- **`run` needs a target** — pass `--tab <id>` (or `--group <id>` / `--group-title <name>`). `--profile` only selects *which* connected Chrome, not the tab.
-- **Multiple Chrome windows/profiles connected?** Commands need `--profile <label>`; run `dassi list-profiles` to see the labels (one profile = no flag needed).
+If you prefer installing the command first:
 
-## Installation
+```sh
+npm install -g @dassi_ai/cli@latest
+dassi
+```
+
+Running `dassi` without arguments in an interactive terminal starts the same setup flow. Scripts must request `setup` explicitly; bare noninteractive and JSON invocations return an actionable error. Setup requires a writable npm global location. If npm reports a permissions error, follow its [user-level installation guidance](https://docs.npmjs.com/resolving-eacces-permissions-errors-when-installing-packages-globally/), then rerun setup.
+
+If Dassi is not connected, setup opens its Chrome Web Store listing. In the Chrome profile you want to use, click **Add to Chrome**, then **Add extension**. Chrome downloads and installs the extension. Setup waits for it to connect and verifies live tool discovery and tab access. With multiple connected profiles, an interactive terminal asks which one to use; scripts receive the available profile IDs instead of a guessed selection.
+
+Browser tools work while signed out. Setup finishes after verifying the browser and does not open sign-in settings. Dassi sign-in is needed when you choose task delegation with `run`. JSON reports delegation separately; `data.delegationError` explains an unavailable sign-in check without blocking browser readiness. Setup retries temporary browser connection failures until its deadline. It does not run a model task as its connection check. The Web Store provides extension updates; a connection that lacks tool discovery receives update instructions.
 
-```bash
-# Zero-install
-npx @dassi_ai/cli --help
+Setup waits up to five minutes for Chrome by default. Rerun the same command to resume. For local agents and scripts:
 
-# Or install globally
-npm install -g @dassi_ai/cli
+```sh
+npx --yes @dassi_ai/cli@latest setup --wait 0 --json
+npx --yes @dassi_ai/cli@latest setup --profile '<profile-id>' --wait 30s --json
 ```
 
-Or, for local development from a clone of this repo:
+Read `data.ready`, `data.browserTools`, and `data.delegation`. An incomplete setup exits nonzero and includes the next action; it preserves the installation already completed. `--no-open` prints instructions without opening Chrome. Chrome installation confirmation and account sign-in remain user actions. Setup's observer deadline does not stop browser work.
 
-```bash
-cd cli
-npm install
-npm link    # exposes `dassi` on PATH
+When setup says **“You're ready,”** open your agent and ask **“Use Dassi to show my open browser tabs.”** Restart an already-running agent to load the skill. Its bundled launcher works without PATH configuration. Installation paths and delegation diagnostics remain available in `setup --json`.
+
+## Update and remove
+
+Update the terminal command and its bundled agent skill together:
+
+```sh
+npm install -g @dassi_ai/cli@latest
 ```
 
-## Prerequisites
+You can also rerun `npx --yes @dassi_ai/cli@latest setup` to update and check Chrome. Restart running agents to load updated skill instructions. If you change Node versions or npm prefixes, rerun setup; registrations pointing elsewhere are reported for manual resolution.
 
-- Node.js >= 20.11.1
-- Dassi Chrome extension installed and running
-- **External Bridge** enabled in Dassi Options (`options.html?dev`)
+To remove Dassi from local agents and uninstall the CLI:
 
-## Usage
+```sh
+dassi skill --remove
+npm uninstall -g @dassi_ai/cli
+```
 
-```bash
-# List all open Chrome tabs
-dassi list-tabs
+Skill removal deletes only symlinks to this npm installation, preserving custom skills and other installations. npm owns package removal. Chrome's extension, browser conversations, and runtime files are separate; remove the extension through Chrome if desired.
 
-# Run an agent prompt on a specific tab
-dassi run "summarize the top issues" --tab 456
+## Use from a local agent
 
-# Run with a timeout (ms)
-dassi run "check inbox" --tab 123 --timeout 60000
+The shared skill includes `scripts/dassi.mjs`, a launcher for the matching CLI version:
 
-# Send a raw JSON command
-dassi raw '{"id":"1","action":"list_tabs"}'
+```sh
+node '<installed-skill-directory>/scripts/dassi.mjs' list-tabs --json
+```
+
+Examples below use `dassi` as shorthand for that invocation or the globally installed command. `dassi skill` prints the bundled workflow without requiring Chrome; `dassi skill --path` locates its directory. The skill covers profile selection, tool discovery, delegation, bounded polling and recovery without resubmitting accepted work.
+
+Native registration follows the documented [Codex](https://learn.chatgpt.com/docs/build-skills), [Claude Code](https://code.claude.com/docs/en/skills), and [OpenCode](https://opencode.ai/docs/skills) discovery locations. Other shell agents can load the same skill and launcher. Shell and local browser connectivity remain required.
+
+## Discover and call browser tools
 
-# Output as JSON (for scripting)
+The connected extension owns tool names, instructions and parameter schemas. The CLI has no browser-name translation table or cached catalog.
+
+```sh
 dassi list-tabs --json
+# Copy a target from the intended profile.
+dassi tools --tab '<target>' --json
+dassi tools '<name-from-discovery>' --tab '<target>' --json
+dassi call '<name-from-discovery>' --tab '<target>' --args '{"parameter":"value"}' --json
+```
 
-# Use a named session
-dassi list-tabs --session work
+`tools` lists short descriptions; `tools <name>` returns the full description and JSON schema. Discovery does not group tabs or claim a conversation. You can also use `tools --profile '<profile-id>'` without a tab. It requires one identifiable profile and does not merge catalogs from different installations.
 
-# List connected profiles (multiple Chrome profiles can connect at once)
-dassi list-profiles
+`call` forwards the tool name and JSON object unchanged. The extension applies defaults, validates the parameters, checks its existing direct-call restrictions and executes under the existing CLI ownership rules. It supplies the outer `--tab` target to tools whose schema declares `tabId`, overriding any different tab ID in the JSON. Other schemas receive no added argument. Tools that require agent-run, automation or human-reply context (including `ask_user`) are excluded from both discovery and direct calls.
 
-# Target a specific profile by label when more than one is connected
-dassi list-tabs --profile dev
-dassi run "summarize" --tab 456 --profile dev   # alias: --label
-
-# Launch a fresh Chrome with a locally-built dev dist (for testing extension changes)
-pnpm build                                  # build extension/dist first
-dassi launch                                # loads extension/dist as profile "dev"
-dassi launch --label qa --dist some/dist    # custom label + dist
-# Drive the launched Chrome — run still needs a tab/group target; --profile selects which Chrome:
-dassi list-tabs --profile dev               # find a tab id in the launched profile
-dassi run "summarize this page" --tab <id> --profile dev
-dassi launch --stop                         # close the "dev" Chrome (or --stop-all)
-# Note: launch reuses the default daemon (port 18790). To launch on an isolated
-# port (DASSI_BRIDGE_PORT=18791 dassi launch), no default daemon may be running —
-# it errors clearly otherwise, since it can't confirm the running daemon's port.
-#
-# How the extension is loaded (auto-detected per Chrome binary):
-#  • Branded Google Chrome (137+) disabled the `--load-extension` flag, so launch
-#    installs the dist at runtime via the `Extensions.loadUnpacked` CDP command over
-#    `--remote-debugging-pipe`. Because such an extension lives only as long as the
-#    debugging pipe, launch spawns a detached `__launch-hold` helper that keeps the
-#    pipe open; `--stop` kills the helper, which closes the pipe and its Chrome.
-#  • Chrome for Testing / Chromium still honour `--load-extension` (persistent), so
-#    launch uses that directly there — no helper. Point at one with `--chrome <path>`.
-#  • The mode is auto-detected from the binary; override with `--load-mode auto|pipe|flag`
-#    (e.g. `dassi launch --chrome <cft> --load-mode pipe` to exercise the pipe path on CfT).
-
-# Show version / help
-dassi --version
-dassi --help
+Direct calls wait for the capability's result or error; the CLI and daemon impose no additional execution deadline. Use the timeout parameter from that tool's schema when available. Closing the CLI does not cancel a direct call. A lost connection after submission reports `outcome: "unknown"`; inspect the browser before retrying because the action may still be running. Actual tool errors retain their original meaning.
+
+To save returned images, use `call ... -o /tmp/dassi-page.jpg` without `--json`. JSON returns raw image content. `panel-screenshot` still captures Dassi's own UI, and `open [url] --window <id>` creates an ungrouped background tab (`--foreground` activates it).
+
+CLI 0.7 replaces the handwritten browser aliases (`read-page`, `get-text`, `click`, `fill`, `type`, `navigate`, `screenshot`, `eval`, `tabs`, `close`, and grouped `open`) with `tools` and `call`. Scripts must discover the current tool and use its schema. `list-tabs`, `run`, `status`, `stop`, and the raw bridge interface retain their roles.
+
+## Delegate a task
+
+Copy the `TARGET` from the listing, then start a task:
+
+```sh
+dassi run 'Review these applications' --tab '<target>'
+# Returns a task ID after the browser accepts the work.
+dassi status '<task-id>'
+dassi run 'Now compare the strongest two' --task '<task-id>'
+dassi stop '<task-id>'
 ```
 
-### Tab groups
+A task can run for more than 30 minutes. Closing the terminal, a disconnected CLI, or an expired wait does not cancel it. To wait for a result in the current command:
+
+```sh
+dassi run 'Summarize this page' --tab '<target>' --wait 30s --json
+dassi status '<task-id>' --wait 10m --json
+```
 
-```bash
-# List all tab groups
-dassi list-groups
+Successful `stop` commands exit zero. `run` and task `status` exit nonzero for failed or stopped tasks.
 
-# Run agent against every tab in a group (sequential)
-dassi run "summarize each page" --group 7
+When the wait ends, inspect `data.status`: `running` or `stopping` means check the **same task** again. `completed`, `failed`, and `stopped` are final. Each task is one conversation. A fresh `run --tab` starts a new conversation, even on the same tab. `run --task` explicitly continues that conversation and returns the same ID; status shows its latest reply and run outcome. A follow-up submitted while running uses the native follow-up queue. It has no separate result ID. Status reports persisted messages, so an in-progress model turn may not yet appear. Keep the full opaque task ID; it includes its browser identity. Tasks and their transcripts remain available until their conversation history is deleted. Follow-ups use the original browser tab; if it has closed, start a new task on another tab.
 
-# Use a group title instead of id (errors if title is ambiguous)
-dassi run "extract prices" --group-title "Shopping"
+## Multiple Chrome profiles
 
-# Tool commands also accept --group / --group-title
-dassi screenshot --group-title "Research" -o shot.png
+`list-tabs`, `list-groups`, `list-profiles`, and bare `status` discover all connected profiles. Listings include profile labels, stable installation IDs, and sign-in status. A target combines the installation ID and the Chrome tab/group ID. Always copy it; tab IDs alone do not identify a browser profile.
+
+For an existing numeric tab ID, `--profile <id-or-unique-name>` remains available. Duplicate names produce an ambiguity error. Profile selection does not fall back to another installation after disconnect. Sign-in is checked in the profile receiving a task, and discovery works while signed out.
+
+```sh
+dassi list-profiles
+dassi list-tabs --profile '<profile-id>'
+dassi run 'Summarize' --tab 42 --profile '<profile-id>'
 ```
 
-When `--group`/`--group-title` is used, the CLI expands to member tab ids and runs them sequentially in one daemon session. True parallel execution is not currently supported — the daemon binds a fixed WebSocket port (`18790` by default, override with `DASSI_BRIDGE_PORT`), so multiple daemon processes can't coexist regardless of `--session`. Sequential dispatch is the only supported pattern.
+## Browser groups
 
-## Claude Code Plugin
+`run --group <target>` submits **one prompt for the whole group**, using the group as its browser workspace. `call --group <target>` executes sequentially once per member tab; use a single tab for an action intended to happen once. A fresh `run` on a busy group is refused with the existing task ID. Wait, explicitly continue that task, stop it, or use another tab.
 
-This package also ships as a Claude Code plugin under the `dassi` namespace. After installation (via either `npm install -g @dassi_ai/cli` or `npm link` from this directory), Claude Code auto-discovers two skills:
+## Development and upgrades
 
-- **`dassi:pick-tabs`** — a reusable tab/group picker. Lists open tabs and Chrome tab groups, asks the user to pick, returns the selected Chrome tab IDs.
-- **`dassi:operate`** — main entry point. Translates natural-language browser asks ("summarize my Research group", "screenshot the active tab", etc.) into `dassi` CLI invocations.
+```sh
+# From the repository root:
+pnpm --dir extension build
+dassi launch --label dev
+dassi list-tabs --profile dev
+dassi launch --stop dev
+```
 
-The plugin manifest lives at `.claude-plugin/plugin.json`; skill content is under `skills/<name>/SKILL.md`. No additional configuration is required — installing the CLI is sufficient.
+Launch supports `--dist`, `--chrome`, `--profile-dir`, `--load-mode auto|pipe|flag`, and Chrome arguments after `--`. Branded Chrome uses a detached helper holding a CDP pipe for the unpacked extension; Chromium/Chrome for Testing can use `--load-extension` directly.
 
-## How It Works
+CLI 0.7 requires the current extension with live tool discovery, and CLI protocol 3 for task submission. Incompatible clients, daemons, and extensions fail before a task is submitted, in either upgrade order. After upgrading the CLI, finish any old CLI calls and restart an older daemon if prompted (its PID is in `~/.dassi/default.pid`). Browser conversations survive a daemon restart. This package is not auto-published by a source change.
 
-The CLI (`dassi.mjs`) auto-spawns a background daemon (`dassi-daemon.mjs`) that:
+`run --timeout` is rejected with migration instructions. Use `--wait` to observe and `stop` to cancel. Scripts must check task status and explicitly stop a task if they impose an execution budget. `--session`/`DASSI_SESSION` are retained for development compatibility; they select a daemon socket, not a browser or conversation. Normal use needs neither. `DASSI_BRIDGE_PORT` configures an isolated development bridge.
 
-- Hosts a WebSocket server on port 18790 for the Chrome extension to connect to
-- Exposes a Unix socket (`~/.dassi/<session>.sock`) for CLI commands via NDJSON protocol
-- Serializes concurrent `run` commands via a FIFO queue
-- Handles first-run onboarding (extension install detection, login flow)
-- Shuts down after 30 minutes of idle
+The daemon routes short requests. Native runtime admission controls each conversation; the daemon does not serialize unrelated profiles or hold a connection for a task's lifetime. Startup requires no sign-in. The native conversation owns admission, cancellation, recovery, and transcript. Status reads its transcript and state in one storage transaction; a single last-run summary survives later compaction. There is no per-prompt task ledger.
 
-## Dependencies
+Before promoting a CLI release to npm `latest`, make its compatible extension available in the Chrome Web Store. Check the packed npm artifact in a fresh global prefix, then verify setup against that store installation: extension confirmation, signed-out browser access, profile choice, agent discovery, an initial tab listing, and resume after interruption. Local builds and injected browser responses do not establish that store-to-npm release path.
 
-- [`ws`](https://www.npmjs.com/package/ws) — WebSocket server for extension communication
-- [`open`](https://www.npmjs.com/package/open) — Opens browser for onboarding/install flow
+## Output for scripts
 
-## Development
+Browser and task commands with `--json` write their response to stdout, including argument, setup, and connection failures:
 
-```bash
-# Run tests
-npm test
+```json
+{"success": false, "error": "An older Dassi daemon is running. Finish active tasks, restart the daemon, then retry with this CLI."}
 ```
 
-## License
+Parse stdout even on a nonzero exit. Successful responses contain `data`; failures contain `error`. Direct group tools return an array of `{tabId, response}`. Task status, rather than exit zero alone, tells you whether delegated work finished. `--help`, `--version`, and `skill` also support JSON, with a string in `data`. Development `launch` commands use terminal output.
+
+An error's top-level `taskId` means that submission may have been accepted: check it before retrying. `existingTaskId` refers to other work already using the browser workspace. Do not treat it as permission to cancel that work.
+
+The shared skill ships in `skills/dassi`. It replaces the former `operate` and `pick-tabs` skills. The Claude Code plugin manifest remains at `.claude-plugin/plugin.json`; its skill command is now `/dassi:dassi` when loaded as a plugin. Installing the npm package alone does not register a plugin in an agent.
 
-MIT
+Run CLI tests with `pnpm --dir cli test`.

package/daemon-client.mjs

@@ -0,0 +1,181 @@
+/** CLI transport, daemon startup, and bounded observation of browser-owned tasks. */
+
+import * as net from 'net';
+import * as fs from 'fs';
+import * as path from 'path';
+import * as child_process from 'child_process';
+import { fileURLToPath } from 'url';
+import {
+  getSocketPath,
+  CLI_PROTOCOL_VERSION,
+  getReadyFile,
+  isDaemonRunning,
+  parseReadyPayload,
+  CHROME_WEB_STORE_URL,
+  unknownToolOutcome,
+} from './dassi-shared.mjs';
+
+const __dirname = path.dirname(fileURLToPath(import.meta.url));
+const DAEMON_SCRIPT = path.join(__dirname, 'dassi-daemon.mjs');
+const READY_POLL_MS = 100;
+const READY_TIMEOUT_MS = 30_000;
+
+// ─── Daemon management ────────────────────────────────────────────────────────
+
+/**
+ * Ensures the daemon is running for the given session.
+ * Spawns it as a detached background process if the PID file is missing or stale.
+ * @param {string} session
+ */
+export function ensureDaemonRunning(session) {
+  if (isDaemonRunning(session)) return;
+
+  // Reason: detached + unref means the daemon outlives the CLI process
+  const daemon = child_process.spawn(process.execPath, [DAEMON_SCRIPT], {
+    detached: true,
+    stdio: 'ignore',
+    env: { ...process.env, DASSI_SESSION: session },
+  });
+  daemon.unref();
+}
+
+/**
+ * Polls for the ready file until it appears or the timeout elapses.
+ * Resolves with the parsed ready payload.
+ * @param {string} readyFile
+ * @param {number} [timeoutMs]
+ * @returns {Promise<{ status: string; [key: string]: unknown }>}
+ */
+export function waitForReady(readyFile, timeoutMs = READY_TIMEOUT_MS) {
+  return new Promise((resolve, reject) => {
+    const deadline = Date.now() + timeoutMs;
+    const check = () => {
+      if (fs.existsSync(readyFile)) {
+        try {
+          resolve(parseReadyPayload(fs.readFileSync(readyFile, 'utf8')));
+          return;
+        } catch { /* file may be partially written — keep polling */ }
+      }
+      if (Date.now() >= deadline) {
+        const seconds = Math.round(timeoutMs / 1000);
+        reject(new Error(`Timed out waiting for Dassi daemon to start (${seconds}s)`));
+        return;
+      }
+      setTimeout(check, READY_POLL_MS);
+    };
+    check();
+  });
+}
+
+/**
+ * Connects to the daemon Unix socket, sends one NDJSON command, and reads the response.
+ * @param {string} socketPath - Unix socket path.
+ * @param {object} command - Command object to send (will be JSON-stringified).
+ * @returns {Promise<object>} Parsed response object.
+ */
+export function sendCommand(socketPath, command, {
+  // Direct tools own their deadlines; a plugin need not expose a timeout parameter.
+  timeoutMs = command.action === 'tool_exec' ? null : command.action !== 'run' && Number.isFinite(command.timeoutMs) && command.timeoutMs > 0
+    ? Math.min(command.timeoutMs + 15_000, 2147483647)
+    : 70_000,
+} = {}) {
+  return new Promise((resolve, reject) => {
+    const socket = net.createConnection(socketPath);
+    const timer = timeoutMs == null ? null : setTimeout(() => socket.destroy(new Error('Daemon did not respond. Check the existing task before retrying.')), timeoutMs);
+    let buffer = '';
+    let settled = false;
+    let submitted = false;
+
+    // Reason: guard against double-settlement since 'close' fires after socket.destroy()
+    // in the normal data path, and we don't want the close handler to re-resolve
+    const settle = (fn, val) => {
+      if (settled) return;
+      settled = true;
+      clearTimeout(timer);
+      fn(fn === reject && submitted && command.action === 'tool_exec' ? unknownToolOutcome(val) : val);
+    };
+
+    socket.on('connect', () => {
+      submitted = true;
+      socket.write(JSON.stringify(command) + '\n');
+    });
+
+    socket.on('data', (chunk) => {
+      buffer += chunk.toString();
+      const nl = buffer.indexOf('\n');
+      if (nl !== -1) {
+        const line = buffer.slice(0, nl);
+        socket.destroy();
+        try { settle(resolve, JSON.parse(line)); }
+        catch { settle(reject, new Error(`Invalid JSON from daemon: ${line}`)); }
+      }
+    });
+
+    socket.on('error', (err) => settle(reject, err));
+
+    socket.on('close', () => {
+      if (settled) return;
+      // Reason: attempt to parse whatever arrived before the socket closed unexpectedly
+      if (buffer.trim()) {
+        try { settle(resolve, JSON.parse(buffer.trim())); }
+        catch { settle(reject, new Error(`Invalid JSON from daemon: ${buffer.trim()}`)); }
+      } else {
+        settle(reject, new Error('Daemon closed connection without a response'));
+      }
+    });
+  });
+}
+
+// ─── Daemon readiness ─────────────────────────────────────────────────────────
+
+/**
+ * Ensures the local command transport is ready.
+ * @param {string} session
+ * @returns {Promise<string>} The daemon's Unix socket path.
+ */
+export async function ensureDaemonReady(session) {
+  const socketPath = getSocketPath(session);
+  const readyFile = getReadyFile(session);
+
+  // Reason: delete any stale ready file from a previous run so the new daemon
+  // writes a fresh one. Skip if a daemon is already running to avoid racing.
+  if (!isDaemonRunning(session)) {
+    try { fs.unlinkSync(readyFile); } catch { /* ok if missing */ }
+  }
+
+  ensureDaemonRunning(session);
+
+  const ready = await waitForReady(readyFile);
+
+  if (ready.status === 'extension_not_installed') {
+    throw new Error(
+      `Dassi extension not detected.\n\n` +
+      `   Install it from:\n   ${CHROME_WEB_STORE_URL}\n\n` +
+      `   Then run this command again.`
+    );
+  }
+
+  if (ready.status === 'error') throw new Error(ready.error);
+  if (ready.protocolVersion !== CLI_PROTOCOL_VERSION) throw new Error('An older Dassi daemon is running. Finish active tasks, restart the daemon, then retry with this CLI.');
+
+  return socketPath;
+}
+
+/** Waiting expires locally; it never cancels the browser-owned task. */
+export async function sendAndWait(socketPath, command, send = sendCommand, now = Date.now, sleep = ms => new Promise(resolve => setTimeout(resolve, ms))) {
+  const { waitMs = 0, ...wire } = command;
+  if (['run', 'task_status', 'task_stop'].includes(wire.action)) wire.protocolVersion = CLI_PROTOCOL_VERSION;
+  let response = await send(socketPath, wire);
+  const deadline = now() + waitMs;
+  while (response.success && ['running', 'stopping'].includes(response.data?.status) && now() < deadline) {
+    await sleep(Math.min(1000, deadline - now()));
+    if (now() >= deadline) break;
+    const taskId = response.data.taskId;
+    try {
+      const next = await send(socketPath, { id: `${wire.id}-status-${now()}`, action: 'task_status', taskId, protocolVersion: CLI_PROTOCOL_VERSION }, { timeoutMs: Math.max(1, deadline - now()) });
+      if (!next.success) return { ...next, taskId, error: `${next.error} Check task ${taskId}; do not resubmit.` };
+      response = next;
+    } catch (error) { if (now() >= deadline) return response; return { success: false, taskId, error: `${error.message} Check task ${taskId}; do not resubmit.` }; }
+  }
+  return response;
+}