@dassi_ai/cli 0.2.0 → 0.4.0

package/.claude-plugin/plugin.json

@@ -1,7 +1,7 @@
 {
   "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.0",
+  "version": "0.1.3",
   "author": {
     "name": "Omnify Labs",
     "email": "team@dassi.ai"

package/README.md

@@ -2,6 +2,22 @@
 
 Standalone CLI for the [Dassi](../extension/README.md) Chrome extension — run browser automation from the terminal.
 
+## Quickstart
+
+```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>
+```
+
+Prefer a permanent `dassi` command? `npm install -g @dassi_ai/cli` (Node ≥ 20.11), then drop the `npx @dassi_ai/cli@latest` prefix.
+
+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).
+
 ## Installation
 
 ```bash
@@ -54,6 +70,29 @@ dassi list-profiles
 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

package/_launch-pipe.mjs

@@ -0,0 +1,102 @@
+/**
+ * CDP-over-pipe transport for `dassi launch`. Chrome 137+ branded builds disabled the
+ * `--load-extension` flag, so the dist is installed at runtime via the
+ * `Extensions.loadUnpacked` CDP command over `--remote-debugging-pipe`. This module is
+ * the minimal, dependency-free client for that exchange.
+ *
+ * PRIVATE (underscore-prefixed): import these symbols from `launch.mjs`, which re-exports
+ * them. `launch.mjs` is the single public gateway for the launch module.
+ */
+
+/**
+ * Minimal CDP client over Chrome's `--remote-debugging-pipe` transport. Messages are
+ * JSON framed with a trailing NUL (`\0`) byte; replies are matched back by `id`.
+ * No external deps — the CLI only needs to issue a couple of commands at launch.
+ * @param {{ writable: import('stream').Writable; readable: import('stream').Readable }} pipe
+ *   `writable` = Chrome's CDP input (fd 3); `readable` = Chrome's CDP output (fd 4).
+ * @returns {{ send: (method: string, params?: object) => Promise<object>; dispose: () => void }}
+ */
+export function cdpPipeClient({ writable, readable }) {
+  let nextId = 1;
+  const pending = new Map();
+  let buf = Buffer.alloc(0);
+  const onData = (chunk) => {
+    buf = Buffer.concat([buf, chunk]);
+    let nul;
+    // Reason: a single chunk may carry several NUL-delimited frames, or a partial one —
+    // drain every complete frame and keep the remainder buffered for the next chunk.
+    while ((nul = buf.indexOf(0)) !== -1) {
+      const frame = buf.subarray(0, nul).toString('utf8');
+      buf = buf.subarray(nul + 1);
+      if (!frame) continue;
+      let msg;
+      try { msg = JSON.parse(frame); } catch { continue; }
+      const entry = msg.id != null ? pending.get(msg.id) : undefined;
+      if (!entry) continue; // an event, or a reply we're not waiting on
+      pending.delete(msg.id);
+      if (msg.error) entry.reject(new Error(msg.error.message || `CDP error ${msg.error.code ?? ''}`));
+      else entry.resolve(msg.result ?? {});
+    }
+  };
+  readable.on('data', onData);
+  return {
+    send(method, params = {}) {
+      const id = nextId++;
+      return new Promise((resolve, reject) => {
+        pending.set(id, { resolve, reject });
+        writable.write(`${JSON.stringify({ id, method, params })}\0`);
+      });
+    },
+    dispose() {
+      readable.off('data', onData);
+      for (const { reject } of pending.values()) reject(new Error('CDP pipe disposed'));
+      pending.clear();
+    },
+  };
+}
+
+/**
+ * Install the unpacked dist into the just-launched Chrome over the CDP pipe, then
+ * open the seed options page (so the extension persists label+bridgePort and dials
+ * the daemon). This is the runtime replacement for the disabled `--load-extension`.
+ *
+ * On success the pipe is left OPEN (still draining Chrome's CDP output so its buffer
+ * can't fill) and a `dispose()` is returned — the caller MUST call it once the
+ * profile has registered. Reason: branded Chrome discards an automation-created tab
+ * (the seed page) if the debugging pipe closes before it finishes loading; keeping
+ * the pipe alive until the bridge registers lets the seed run.
+ * @param {{ child: import('child_process').ChildProcess; distPath: string; label: string; bridgePort: number; timeoutMs?: number }} opts
+ * @returns {Promise<{ id: string; dispose: () => void }>} the loaded extension id + a pipe closer.
+ * @throws if the pipe fds are missing or a CDP command errors/times out.
+ */
+export async function loadExtensionOverPipe({ child, distPath, label, bridgePort, timeoutMs = 15000 }) {
+  const writable = child.stdio?.[3];
+  const readable = child.stdio?.[4];
+  if (!writable || !readable) {
+    throw new Error('Chrome was not spawned with a CDP pipe (fds 3/4 missing).');
+  }
+  const cdp = cdpPipeClient({ writable, readable });
+  // Reason: capture + clear the timer so a fast-resolving CDP command doesn't leave a
+  // pending setTimeout keeping the event loop alive for the full timeoutMs.
+  const withTimeout = (p, what) => {
+    let timer;
+    const timeout = new Promise((_, r) => {
+      timer = setTimeout(() => r(new Error(`CDP ${what} timed out after ${timeoutMs}ms`)), timeoutMs);
+    });
+    return Promise.race([p, timeout]).finally(() => clearTimeout(timer));
+  };
+  try {
+    const loaded = await withTimeout(cdp.send('Extensions.loadUnpacked', { path: distPath }), 'Extensions.loadUnpacked');
+    const id = loaded.id;
+    if (!id) throw new Error('Extensions.loadUnpacked returned no extension id.');
+    // Reason: open the seed page AFTER the extension exists (it isn't loaded at
+    // startup anymore), so the options page persists label+bridgePort and the
+    // extension's bridge connects to the daemon's actual port.
+    const seed = `chrome-extension://${id}/options.html?label=${encodeURIComponent(label)}&bridgePort=${bridgePort}`;
+    await withTimeout(cdp.send('Target.createTarget', { url: seed }), 'Target.createTarget');
+    return { id, dispose: () => cdp.dispose() };
+  } catch (err) {
+    cdp.dispose();
+    throw err;
+  }
+}

package/dassi-daemon.mjs

@@ -25,6 +25,7 @@ import {
   buildReadyPayload,
   createCommandQueue,
   createConnectionRegistry,
+  getDaemonBridgePort,
 } from './dassi-shared.mjs';
 
 // ─── Constants ────────────────────────────────────────────────────────────────
@@ -153,17 +154,12 @@ async function handleRegistration(ws, data, ctx, resolve, reject, port) {
   }
 }
 
-// Reason: Port is configurable via DASSI_BRIDGE_PORT so the benchmark harness
-// can run a daemon that doesn't conflict with the developer's real Chrome
-// daemon. Defaults to 18790 — the production port that the prod extension
-// SW connects to.
-// Validate so an empty/garbage env var (DASSI_BRIDGE_PORT="") doesn't yield NaN,
-// which `new WSServer({ port: NaN })` would silently accept and bind to a random
-// ephemeral port — leaving the extension's known-port connect attempt hanging.
-const _rawPort = parseInt(process.env.DASSI_BRIDGE_PORT ?? '', 10);
-const BRIDGE_PORT = Number.isInteger(_rawPort) && _rawPort > 0 && _rawPort <= 65535
-  ? _rawPort
-  : 18790;
+// Reason: Port is configurable via DASSI_BRIDGE_PORT (single source of truth in
+// getDaemonBridgePort — also seeded into launched extensions by `dassi launch`).
+// Defaults to 18790, the production port. The validation guards against an
+// empty/garbage env var yielding NaN, which `new WSServer({ port: NaN })` would
+// silently accept and bind to a random ephemeral port.
+const BRIDGE_PORT = getDaemonBridgePort();
 
 /**
  * Starts a WebSocket server on the configured bridge port (default 18790).

package/dassi-shared.mjs

@@ -11,6 +11,15 @@ import * as fs from 'fs';
 import * as path from 'path';
 import * as os from 'os';
 
+// ─── Extension identity ───────────────────────────────────────────────────────
+
+/**
+ * Stable Dassi extension ID. The extension manifest ships a fixed `key`, so the
+ * unpacked dev build gets the SAME id as the Web Store build regardless of load
+ * path — letting `dassi launch` open the extension's options page directly.
+ */
+export const DASSI_EXTENSION_ID = 'bjcngahpcjeililljmfegmlanlpgibdi';
+
 // ─── Path helpers ─────────────────────────────────────────────────────────────
 
 /**
@@ -53,6 +62,31 @@ export function getReadyFile(session) {
   return path.join(getAppDir(), `${session}.ready`);
 }
 
+/**
+ * Resolve the bridge (WebSocket) port the daemon listens on. Configurable via
+ * DASSI_BRIDGE_PORT (e.g. the benchmark harness uses 18791 to isolate from a
+ * developer's real Chrome on 18790); falls back to 18790 on empty/invalid input.
+ * Single source of truth shared by the daemon (which binds it) and `dassi launch`
+ * (which seeds it into the launched extension so it connects to the same port).
+ * @param {Record<string, string|undefined>} [env]
+ * @returns {number} A valid TCP port (1–65535).
+ */
+export const DEFAULT_BRIDGE_PORT = 18790;
+
+export function getDaemonBridgePort(env = process.env) {
+  const p = parseInt(env.DASSI_BRIDGE_PORT ?? '', 10);
+  return Number.isInteger(p) && p > 0 && p <= 65535 ? p : DEFAULT_BRIDGE_PORT;
+}
+
+/**
+ * Path to the JSON file tracking Chrome instances started by `dassi launch`,
+ * so `dassi launch --stop` can find and kill them.
+ * @returns {string} Absolute path to launches.json under the app dir.
+ */
+export function getLaunchesFile() {
+  return path.join(getAppDir(), 'launches.json');
+}
+
 // ─── Session validation ───────────────────────────────────────────────────────
 
 /**

package/dassi.mjs

@@ -15,10 +15,15 @@ import {
   isDaemonRunning,
   parseReadyPayload,
   validateSession,
+  DASSI_EXTENSION_ID,
+  getAppDir,
+  getLaunchesFile,
 } from './dassi-shared.mjs';
+import { dispatchLaunch } from './launch.mjs';
 import { parseToolCommand, requireTarget, parseStrictInt } from './tool-commands.mjs';
 import { runWithGroupExpansion } from './group-expansion.mjs';
 import { formatResponse } from './format-response.mjs';
+import { HELP_TEXT } from './help-text.mjs';
 
 const __dirname = path.dirname(fileURLToPath(import.meta.url));
 const DAEMON_SCRIPT = path.join(__dirname, 'dassi-daemon.mjs');
@@ -27,7 +32,7 @@ const READY_POLL_MS = 100;
 const READY_TIMEOUT_MS = 30_000;
 const LOGIN_POLL_MS = 2_000;
 const LOGIN_TIMEOUT_MS = 5 * 60_000;
-const CHROME_WEB_STORE_URL = 'https://chromewebstore.google.com/detail/dassi-ai-browser-agent-fo/bjcngahpcjeililljmfegmlanlpgibdi';
+const CHROME_WEB_STORE_URL = `https://chromewebstore.google.com/detail/dassi-ai-browser-agent-fo/${DASSI_EXTENSION_ID}`;
 
 // ─── Arg parsing ──────────────────────────────────────────────────────────────
 
@@ -80,6 +85,44 @@ export function parseCliArgs(argv) {
     return finish('list_profiles', {});
   }
 
+  if (command === 'launch') {
+    if (consumeFlag(args, '--stop-all')) return finish('launch_stop', { all: true });
+    const stopIdx = args.indexOf('--stop');
+    if (stopIdx !== -1) {
+      args.splice(stopIdx, 1);
+      // Reason: resolve the stop label like the start path does — a positional
+      // token after --stop wins, else the global --label/--profile (parsed into
+      // `profile` before this branch), else the default. Keeps `--stop --label qa`
+      // symmetric with `launch --label qa` instead of silently targeting "dev".
+      const positional = args[0] && !args[0].startsWith('--') ? args.shift() : null;
+      return finish('launch_stop', { label: positional ?? profile ?? 'dev', all: false });
+    }
+    const timeoutRaw = getFlag(args, '--timeout');
+    // Reason: --label is consumed early as a global flag (aliased to --profile).
+    // The launch branch reads it from `profile` as the canonical source; any
+    // remaining --label token in args is a second occurrence and takes precedence.
+    const launchLabel = getFlag(args, '--label') ?? profile ?? 'dev';
+    // Reason: the label becomes a path segment (per-label profile dir) + the seed URL,
+    // so restrict to a path-safe token (blocks "x/../../.ssh" traversal) within the
+    // extension's 64-char cap — same character set as validateSession.
+    if (!/^[a-zA-Z0-9_-]{1,64}$/.test(launchLabel)) {
+      throw new Error('--label must be 1–64 characters of letters, digits, hyphen, or underscore.');
+    }
+    const loadMode = getFlag(args, '--load-mode') ?? 'auto'; // auto (detect) | pipe | flag
+    if (!['auto', 'pipe', 'flag'].includes(loadMode)) throw new Error('--load-mode must be one of: auto, pipe, flag.');
+    return finish('launch', {
+      label: launchLabel,
+      dist: getFlag(args, '--dist') ?? null,
+      chrome: getFlag(args, '--chrome') ?? null,
+      profileDir: getFlag(args, '--profile-dir') ?? null,
+      loadMode,
+      timeoutMs: timeoutRaw ? parseStrictInt(timeoutRaw, '--timeout') : 30000,
+    });
+  }
+
+  // Hidden helper command (detached child of `dassi launch` pipe mode); config via DASSI_HOLD_* env.
+  if (command === '__launch-hold') return finish('launch_hold', {});
+
   if (command === 'run') {
     const prompt = args.shift();
     if (!prompt) throw new Error('run requires a prompt argument');
@@ -319,44 +362,7 @@ export async function waitForLogin(socketPath, optionsUrl) {
 
 // ─── Immediate actions ────────────────────────────────────────────────────────
 
-const HELP_TEXT =
-  'Usage: dassi [options] <command>\n\n' +
-  'Browser commands (each accepts --tab <id> | --group <id> | --group-title <name>):\n' +
-  '  navigate <url> --tab <id>       Navigate to URL\n' +
-  '  click <ref> --tab <id>          Click element by ref\n' +
-  '  fill <ref> <text> --tab <id>    Fill input with text (instant)\n' +
-  '  type <ref> <text> --tab <id>    Type text with keyboard events\n' +
-  '  read-page --tab <id>            Read page accessibility tree\n' +
-  '  get-text --tab <id>             Extract page text\n' +
-  '  screenshot --tab <id> [-o file]  Capture viewport screenshot\n' +
-  '  panel-screenshot --tab <id> [-o f] [--width W] [--height H]\n' +
-  '                                     Capture side panel UI (default 360x800)\n' +
-  '  eval <code> --tab <id>          Execute JavaScript\n' +
-  '  tabs --tab <id>                 List tabs in same group\n' +
-  '  open [url] --tab <id>           Open new tab in group\n' +
-  '  close --tab <id>                Close tab\n\n' +
-  'Agent commands:\n' +
-  '  run <prompt> --tab <id> | --group <id> | --group-title <name>\n' +
-  '                                  Run AI agent on a tab or group (group = sequential)\n' +
-  '  list-tabs [--all]               List tabs in groups dassi has open (--all = every Chrome tab)\n' +
-  '  list-groups [--all]             List dassi-open tab groups (--all = every Chrome group)\n' +
-  '  list-profiles                   List connected profiles (Chrome instances)\n' +
-  '  status                          Check extension status\n' +
-  '  bug-report [-o file]             Export debug logs from all contexts\n' +
-  '  raw <json>                      Send raw JSON command\n\n' +
-  'Options:\n' +
-  '  --tab <id>        Chrome tab ID (use list-tabs to find)\n' +
-  '  --all             list-tabs/list-groups: include every Chrome tab/group\n' +
-  '  --timeout <ms>    Timeout for run command (default: 300000)\n' +
-  '  --session <name>  Daemon session name (default: "default")\n' +
-  '  --profile <label> Target a specific connected profile (alias: --label)\n' +
-  '  --json            Output raw JSON\n' +
-  '  --filter <type>   Filter for read-page (interactive|all)\n' +
-  '  --depth <n>       Depth for read-page tree\n' +
-  '  --await           Await promise in eval\n' +
-  '  -o, --output <f>  Output file for screenshot\n' +
-  '  --version         Show version\n' +
-  '  --help            Show help';
+// HELP_TEXT lives in ./help-text.mjs (extracted to keep this file within the size limit).
 
 /**
  * Handles --version and --help, which don't need a daemon. Returns true if handled.
@@ -431,6 +437,9 @@ export async function run() {
   const { action, params, session, json, profile } = parsed;
   handleImmediateAction(action);
 
+  // Launch family (launch / --stop / __launch-hold) → launch.mjs.
+  if (await dispatchLaunch(action, params, { spawn: child_process.spawn, ensureDaemonRunning, getSocketPath, sendCommand, appDir: getAppDir(), launchesFile: getLaunchesFile() })) return;
+
   const socketPath = await ensureDaemonReady(session);
 
   const id = `cli_${Date.now()}`;

package/help-text.mjs

@@ -0,0 +1,48 @@
+/**
+ * `dassi --help` output. Extracted from dassi.mjs to keep that file within the
+ * CLAUDE.md size limit; this is pure presentation with no runtime dependencies.
+ */
+export const HELP_TEXT =
+  'Usage: dassi [options] <command>\n\n' +
+  'Browser commands (each accepts --tab <id> | --group <id> | --group-title <name>):\n' +
+  '  navigate <url> --tab <id>       Navigate to URL\n' +
+  '  click <ref> --tab <id>          Click element by ref\n' +
+  '  fill <ref> <text> --tab <id>    Fill input with text (instant)\n' +
+  '  type <ref> <text> --tab <id>    Type text with keyboard events\n' +
+  '  read-page --tab <id>            Read page accessibility tree\n' +
+  '  get-text --tab <id>             Extract page text\n' +
+  '  screenshot --tab <id> [-o file]  Capture viewport screenshot\n' +
+  '  panel-screenshot --tab <id> [-o f] [--width W] [--height H]\n' +
+  '                                     Capture side panel UI (default 360x800)\n' +
+  '  eval <code> --tab <id>          Execute JavaScript\n' +
+  '  tabs --tab <id>                 List tabs in same group\n' +
+  '  open [url] --tab <id>           Open new tab in group\n' +
+  '  close --tab <id>                Close tab\n\n' +
+  'Agent commands:\n' +
+  '  run <prompt> --tab <id> | --group <id> | --group-title <name>\n' +
+  '                                  Run AI agent on a tab or group (group = sequential)\n' +
+  '  list-tabs [--all]               List tabs in groups dassi has open (--all = every Chrome tab)\n' +
+  '  list-groups [--all]             List dassi-open tab groups (--all = every Chrome group)\n' +
+  '  list-profiles                   List connected profiles (Chrome instances)\n' +
+  '  status                          Check extension status\n' +
+  '  bug-report [-o file]             Export debug logs from all contexts\n' +
+  '  raw <json>                      Send raw JSON command\n' +
+  '  launch [--label <name>] [--dist <path>] [--chrome <path>] [--load-mode auto|pipe|flag]\n' +
+  '                                  Open Chrome with a dev dist loaded. --load-mode\n' +
+  '                                  defaults to auto (pipe for branded Chrome 137+,\n' +
+  '                                  --load-extension for Chrome for Testing/Chromium).\n' +
+  '  launch --stop [label] | --stop-all\n' +
+  '                                  Stop a launched Chrome\n\n' +
+  'Options:\n' +
+  '  --tab <id>        Chrome tab ID (use list-tabs to find)\n' +
+  '  --all             list-tabs/list-groups: include every Chrome tab/group\n' +
+  '  --timeout <ms>    Timeout for run command (default: 300000)\n' +
+  '  --session <name>  Daemon session name (default: "default")\n' +
+  '  --profile <label> Target a specific connected profile (alias: --label)\n' +
+  '  --json            Output raw JSON\n' +
+  '  --filter <type>   Filter for read-page (interactive|all)\n' +
+  '  --depth <n>       Depth for read-page tree\n' +
+  '  --await           Await promise in eval\n' +
+  '  -o, --output <f>  Output file for screenshot\n' +
+  '  --version         Show version\n' +
+  '  --help            Show help';

package/launch.mjs

@@ -0,0 +1,441 @@
+/**
+ * Pure helpers for `dassi launch` — locating Chrome, resolving the dist,
+ * building Chrome launch args, and tracking launched instances.
+ */
+import { existsSync, mkdirSync, readFileSync, writeFileSync } from 'fs';
+import { execFileSync, spawn as childSpawn } from 'child_process';
+import * as path from 'path';
+import { DASSI_EXTENSION_ID, getDaemonBridgePort, DEFAULT_BRIDGE_PORT, isDaemonRunning as isDaemonRunningImpl } from './dassi-shared.mjs';
+import { loadExtensionOverPipe } from './_launch-pipe.mjs';
+// `_launch-pipe.mjs` is private (underscore-prefixed): `launch.mjs` is the SINGLE public
+// gateway for the launch module. Re-export the pipe transport here so every consumer
+// (including the unit tests) imports it from this one surface, never from the private file.
+export { cdpPipeClient, loadExtensionOverPipe } from './_launch-pipe.mjs';
+
+/**
+ * Resolve the path to an installed Chrome binary.
+ * @param {{ platform?: string; env?: Record<string,string|undefined>; override?: string|null; exists?: (p: string) => boolean }} [opts]
+ * @returns {string | null} The first existing Chrome path, the override, or null.
+ */
+export function resolveChromePath({ platform = process.platform, env = process.env, override = null, exists = existsSync } = {}) {
+  if (override) return override;
+  const candidates = [];
+  if (platform === 'darwin') {
+    candidates.push('/Applications/Google Chrome.app/Contents/MacOS/Google Chrome');
+  } else if (platform === 'win32') {
+    const pf = env['ProgramFiles'] ?? 'C:\\Program Files';
+    const pf86 = env['ProgramFiles(x86)'] ?? 'C:\\Program Files (x86)';
+    candidates.push(`${pf}\\Google\\Chrome\\Application\\chrome.exe`, `${pf86}\\Google\\Chrome\\Application\\chrome.exe`);
+    if (env['LOCALAPPDATA']) candidates.push(`${env['LOCALAPPDATA']}\\Google\\Chrome\\Application\\chrome.exe`);
+  } else {
+    candidates.push('/opt/google/chrome/chrome', '/usr/bin/google-chrome', '/usr/bin/google-chrome-stable', '/usr/bin/chromium', '/usr/bin/chromium-browser');
+  }
+  return candidates.find((p) => exists(p)) ?? null;
+}
+
+/**
+ * Resolve and validate the extension dist directory to load.
+ * @param {{ dist?: string|null; cwd?: string; exists?: (p: string) => boolean }} [opts]
+ * @returns {string} Absolute path to the dist directory.
+ * @throws if the directory has no manifest.json.
+ */
+export function resolveDistPath({ dist = null, cwd = process.cwd(), exists = existsSync } = {}) {
+  const base = dist ? path.resolve(cwd, dist) : path.resolve(cwd, 'extension/dist');
+  if (!exists(path.join(base, 'manifest.json'))) {
+    throw new Error(`No built extension at ${base} (manifest.json missing). Run \`pnpm build\`, or pass --dist <path>.`);
+  }
+  return base;
+}
+
+/**
+ * Build the Chrome args for a pipe-driven launch.
+ *
+ * The extension is NOT loaded via the `--load-extension` flag: Chrome 137+ branded
+ * builds reject it (`ERR_BLOCKED_BY_CLIENT`), and the `--disable-features=
+ * DisableLoadExtensionCommandLineSwitch` escape hatch is gone in Chrome 149. Instead
+ * the dist is installed at runtime over the CDP pipe via `Extensions.loadUnpacked`
+ * (see {@link loadExtensionOverPipe}). That command is only accepted over the
+ * `--remote-debugging-pipe` transport (fds 3/4) — not `--remote-debugging-port` —
+ * and requires `--enable-unsafe-extension-debugging`. Works on branded Chrome,
+ * Chrome for Testing, and Chromium alike.
+ * @param {{ profileDir: string }} opts
+ * @returns {string[]} Chrome args.
+ */
+export function buildLaunchArgs({ profileDir }) {
+  return [
+    '--remote-debugging-pipe',
+    '--enable-unsafe-extension-debugging',
+    `--user-data-dir=${profileDir}`,
+    '--no-first-run',
+    '--no-default-browser-check',
+  ];
+}
+
+/**
+ * Build Chrome args for the legacy `--load-extension` path (Chrome for Testing /
+ * Chromium, which still honour it and load the extension *persistently*). The dist
+ * is loaded at startup, so the seed options URL can ride along as the startup tab.
+ * @param {{ distPath: string; profileDir: string; label: string; bridgePort: number }} opts
+ * @returns {string[]} Chrome args (the final entry is the seed URL to open).
+ */
+export function buildFlagArgs({ distPath, profileDir, label, bridgePort }) {
+  const seed = `options.html?label=${encodeURIComponent(label)}&bridgePort=${bridgePort}`;
+  return [
+    `--load-extension=${distPath}`,
+    `--disable-extensions-except=${distPath}`,
+    `--user-data-dir=${profileDir}`,
+    '--no-first-run',
+    '--no-default-browser-check',
+    `chrome-extension://${DASSI_EXTENSION_ID}/${seed}`,
+  ];
+}
+
+/**
+ * Does this Chrome binary still support a *persistent* `--load-extension`?
+ * Branded Google Chrome 137+ disabled it (ERR_BLOCKED_BY_CLIENT); Chrome for Testing
+ * and Chromium still honour it. Detected from `--version` output. Defaults to false
+ * (→ pipe path) on any error — the pipe path works everywhere, so it's the safe
+ * fallback.
+ * @param {string} chromePath
+ * @param {(p: string) => string} [runVersion] inject for tests
+ * @returns {boolean} true → use `--load-extension`; false → use the CDP pipe.
+ */
+export function chromeSupportsLoadFlag(chromePath, runVersion = (p) => execFileSync(p, ['--version'], { encoding: 'utf8' })) {
+  try {
+    return /for testing|chromium/i.test(runVersion(chromePath));
+  } catch {
+    return false;
+  }
+}
+
+/**
+ * Read the launches registry. Returns [] if the file is missing or unparseable.
+ * @param {string} file
+ * @returns {Array<{label: string; pid: number; profileDir: string; startedAt: number}>}
+ */
+export function readLaunches(file) {
+  try {
+    const parsed = JSON.parse(readFileSync(file, 'utf8'));
+    return Array.isArray(parsed) ? parsed : [];
+  } catch {
+    return [];
+  }
+}
+
+/**
+ * Record a launched Chrome, replacing any prior entry for the same label.
+ *
+ * Reason: read-modify-write is not cross-process locked. For this dev-only CLI
+ * that's acceptable — concurrent `dassi launch`/`--stop` of *different* labels is
+ * rare, and the worst case (a lost entry) is recoverable via `--stop-all` + a
+ * manual Chrome close. A lock is intentionally omitted (YAGNI for a dev tool).
+ * @param {string} file
+ * @param {{label: string; pid: number; profileDir: string; startedAt: number}} entry
+ */
+export function recordLaunch(file, entry) {
+  const list = readLaunches(file).filter((e) => e.label !== entry.label);
+  list.push(entry);
+  // Reason: ensure the dir exists so the write can't ENOENT after Chrome is already
+  // spawned+connected (which would orphan it with nothing recorded to --stop).
+  mkdirSync(path.dirname(file), { recursive: true });
+  writeFileSync(file, JSON.stringify(list, null, 2), { mode: 0o600 });
+}
+
+/**
+ * Remove the entry for a label. Returns the removed entry, or null if absent.
+ * @param {string} file
+ * @param {string} label
+ * @returns {object | null}
+ */
+export function removeLaunch(file, label) {
+  const list = readLaunches(file);
+  const found = list.find((e) => e.label === label) ?? null;
+  if (found) writeFileSync(file, JSON.stringify(list.filter((e) => e.label !== label), null, 2), { mode: 0o600 });
+  return found;
+}
+
+// ─── Launch orchestrators (exported for testability; deps-injected to avoid circular imports) ───
+
+/**
+ * Poll the daemon's list_profiles until `label` registers or the timeout elapses.
+ * @param {{ sendCommand: Function; socketPath: string; label: string; timeoutMs: number; sleep?: (ms:number)=>Promise<void> }} deps
+ * @returns {Promise<boolean>} true if the label connected in time.
+ */
+export async function waitForProfile({ sendCommand, socketPath, label, timeoutMs, sleep = (ms) => new Promise((r) => setTimeout(r, ms)) }) {
+  const deadline = Date.now() + timeoutMs;
+  while (Date.now() < deadline) {
+    try {
+      const resp = await sendCommand(socketPath, { id: `cli_lp_${Date.now()}`, action: 'list_profiles' });
+      if (resp.success && Array.isArray(resp.data) && resp.data.some((p) => p.label === label)) return true;
+    } catch { /* daemon still coming up — keep polling */ }
+    await sleep(500);
+  }
+  return false;
+}
+
+/**
+ * One-shot check: is a profile with `label` already connected to the daemon?
+ * Tolerates the daemon/socket not being up yet (returns false).
+ * @param {{ sendCommand: Function; socketPath: string; label: string }} deps
+ * @returns {Promise<boolean>}
+ */
+async function isLabelConnected({ sendCommand, socketPath, label }) {
+  try {
+    const resp = await sendCommand(socketPath, { id: `cli_pre_${Date.now()}`, action: 'list_profiles' });
+    return resp.success && Array.isArray(resp.data) && resp.data.some((p) => p.label === label);
+  } catch {
+    return false;
+  }
+}
+
+/**
+ * Daemon pre-flight for a launch: validate the bridge port, spawn the (non-blocking)
+ * daemon, and refuse a duplicate label. Calls `exit(1)` + returns null on failure.
+ * @returns {Promise<{ bridgePort: number; socketPath: string } | null>}
+ */
+async function preflightLaunch({ ensureDaemonRunning, getSocketPath, sendCommand, isDaemonRunning, label, error, exit }) {
+  // Reason: `dassi launch` reuses the 'default' daemon session, but the session PID
+  // doesn't tell us its port. If a non-default DASSI_BRIDGE_PORT is requested while a
+  // default daemon is already running, we can't confirm it's on that port — fail clearly.
+  const bridgePort = getDaemonBridgePort();
+  if (bridgePort !== DEFAULT_BRIDGE_PORT && isDaemonRunning('default')) {
+    error(`❌  DASSI_BRIDGE_PORT=${bridgePort} is set, but a daemon is already running for the default session (it may be on a different port). Stop it first, or omit DASSI_BRIDGE_PORT to use the running daemon.`);
+    exit(1);
+    return null;
+  }
+  // Reason: only SPAWN the daemon (non-blocking) — none has connected yet.
+  ensureDaemonRunning('default');
+  const socketPath = getSocketPath('default');
+  // Reason: a same-label Chrome already running makes waitForProfile falsely succeed.
+  if (await isLabelConnected({ sendCommand, socketPath, label })) {
+    error(`❌  A profile labelled "${label}" is already connected. Run \`dassi launch --stop ${label}\` first, or use a different --label.`);
+    exit(1);
+    return null;
+  }
+  return { bridgePort, socketPath };
+}
+
+/**
+ * Launch Chrome with the dev dist loaded under a dedicated profile, wait for the
+ * extension to register under `label`, then record it. Auto-detects the load mode
+ * (pipe helper for branded Chrome / `--load-extension` for CfT/Chromium).
+ * @param {{label:string; dist:string|null; chrome:string|null; profileDir:string|null; loadMode?:string; timeoutMs:number}} opts
+ * @param {{ spawn: Function; ensureDaemonRunning: Function; getSocketPath: Function; sendCommand: Function; appDir: string; launchesFile: string; isDaemonRunning?: Function; detectLoadFlag?: Function; helperCommand?: string[]; log?: Function; error?: Function; exit?: Function; mkdir?: Function; kill?: Function }} deps
+ *   `detectLoadFlag` chooses pipe-vs-flag mode; `helperCommand` is the argv used to spawn the detached pipe-hold helper (both injectable for tests).
+ * @returns {Promise<void>} resolves once the launch is recorded (or `deps.exit` is called on failure).
+ */
+export async function handleLaunch(opts, deps) {
+  const {
+    spawn, ensureDaemonRunning, getSocketPath, sendCommand, appDir, launchesFile,
+    isDaemonRunning = isDaemonRunningImpl,
+    detectLoadFlag = chromeSupportsLoadFlag,
+    helperCommand = [process.execPath, process.argv[1]],
+    log = console.log, error = console.error, exit = process.exit,
+    mkdir = (d) => mkdirSync(d, { recursive: true }), kill = (pid) => process.kill(pid),
+  } = deps;
+
+  const target = resolveLaunchTarget(opts, { error, exit, appDir, mkdir });
+  if (!target) return; // resolution failed (exit already called)
+  const { distPath, chromePath, profileDir } = target;
+
+  const pre = await preflightLaunch({ ensureDaemonRunning, getSocketPath, sendCommand, isDaemonRunning, label: opts.label, error, exit });
+  if (!pre) return; // a guard failed (exit already called)
+  const { bridgePort, socketPath } = pre;
+
+  // Reason: branded Chrome 137+ disabled --load-extension, so install over the CDP pipe via
+  // a persistent helper. CfT/Chromium still honour --load-extension. --load-mode forces it;
+  // 'auto' (default) detects from the binary's --version.
+  const useFlag = opts.loadMode === 'flag' ? true : opts.loadMode === 'pipe' ? false : detectLoadFlag(chromePath);
+  const common = { spawn, kill, sendCommand, socketPath, chromePath, distPath, profileDir, bridgePort, opts, error };
+  const pid = useFlag ? await spawnFlagAndConnect(common) : await spawnHelperAndConnect({ ...common, helperCommand });
+  if (pid === null) return exit(1);
+
+  recordLaunch(launchesFile, { label: opts.label, pid, profileDir, mode: useFlag ? 'flag' : 'pipe', startedAt: Date.now() });
+  log(`✅  launched "${opts.label}" (pid ${pid}) — drive it with: dassi run "…" --profile ${opts.label}`);
+}
+
+/**
+ * Entry for the hidden `dassi __launch-hold` subcommand: reads the DASSI_HOLD_* env vars
+ * (set by spawnHelperAndConnect) and runs the pipe-holding helper. Never returns.
+ * @param {Record<string,string|undefined>} [env] Environment variables; defaults to process.env.
+ * @param {Function} [run] Pipe-hold runner; defaults to runPipeHoldHelper (injectable for tests).
+ * @returns {Promise<void>}
+ */
+export async function handleLaunchHold(env = process.env, run = runPipeHoldHelper) {
+  await run({
+    label: env.DASSI_HOLD_LABEL,
+    distPath: env.DASSI_HOLD_DIST,
+    profileDir: env.DASSI_HOLD_PROFILE_DIR,
+    bridgePort: Number(env.DASSI_HOLD_BRIDGE_PORT),
+    chromePath: env.DASSI_HOLD_CHROME,
+  });
+}
+
+/**
+ * Route a `launch*` CLI action to its handler. Returns true if it was a launch action
+ * (so the caller can `return`), false otherwise. Keeps the launch surface out of dassi.mjs.
+ * @param {string} action
+ * @param {object} params
+ * @param {{ spawn:Function; ensureDaemonRunning:Function; getSocketPath:Function; sendCommand:Function; appDir:string; launchesFile:string; kill?:Function; handleHold?:Function }} deps
+ *   `handleHold` overrides the `__launch-hold` runner (injectable for tests; defaults to handleLaunchHold).
+ * @returns {Promise<boolean>}
+ */
+export async function dispatchLaunch(action, params, deps) {
+  if (action === 'launch') { await handleLaunch(params, deps); return true; }
+  if (action === 'launch_stop') { handleStop(params, { launchesFile: deps.launchesFile, kill: deps.kill }); return true; }
+  if (action === 'launch_hold') { await (deps.handleHold ?? handleLaunchHold)(); return true; }
+  return false;
+}
+
+/**
+ * Flag mode (Chrome for Testing / Chromium): detached Chrome with a persistent
+ * `--load-extension`. The browser keeps the extension after this CLI exits.
+ * @returns {Promise<number|null>} the Chrome pid, or null on spawn/connect failure.
+ */
+async function spawnFlagAndConnect({ spawn, kill, sendCommand, socketPath, chromePath, distPath, profileDir, bridgePort, opts, error }) {
+  const child = spawn(chromePath, buildFlagArgs({ distPath, profileDir, label: opts.label, bridgePort }), { detached: true, stdio: 'ignore' });
+  child.on('error', () => {});
+  child.unref();
+  if (typeof child.pid !== 'number') {
+    error('❌  Failed to launch Chrome — check the Chrome path (--chrome).');
+    return null;
+  }
+  error(`Launching Chrome (pid ${child.pid}) with ${distPath} — waiting for "${opts.label}" to connect…`);
+  if (await waitForProfile({ sendCommand, socketPath, label: opts.label, timeoutMs: opts.timeoutMs })) return child.pid;
+  try { kill(child.pid); } catch { /* already gone */ }
+  error(`❌  "${opts.label}" did not connect within ${opts.timeoutMs}ms (Chrome already using ${profileDir}, or a stale profile).`);
+  return null;
+}
+
+/**
+ * Pipe mode (branded Chrome): spawn a detached `dassi __launch-hold` helper that holds the
+ * CDP pipe open so the loadUnpacked extension persists. The recorded pid is the HELPER's —
+ * `dassi launch --stop` SIGTERMs it, and it closes the pipe + kills its Chrome child.
+ * @returns {Promise<number|null>} the helper pid, or null on spawn/connect failure.
+ */
+async function spawnHelperAndConnect({ spawn, kill, sendCommand, socketPath, chromePath, distPath, profileDir, bridgePort, opts, error, helperCommand }) {
+  const [node, cli] = helperCommand;
+  // Reason: pass the helper's config via env (not flags) so it can't collide with the
+  // CLI's global --label/--profile parsing.
+  const helper = spawn(node, [cli, '__launch-hold'], {
+    detached: true,
+    stdio: 'ignore',
+    env: {
+      ...process.env,
+      DASSI_HOLD_LABEL: opts.label,
+      DASSI_HOLD_DIST: distPath,
+      DASSI_HOLD_PROFILE_DIR: profileDir,
+      DASSI_HOLD_BRIDGE_PORT: String(bridgePort),
+      DASSI_HOLD_CHROME: chromePath,
+    },
+  });
+  helper.on('error', () => {});
+  helper.unref();
+  if (typeof helper.pid !== 'number') {
+    error('❌  Failed to start the launch helper.');
+    return null;
+  }
+  error(`Launching Chrome via pipe helper (pid ${helper.pid}) with ${distPath} — waiting for "${opts.label}" to connect…`);
+  if (await waitForProfile({ sendCommand, socketPath, label: opts.label, timeoutMs: opts.timeoutMs })) return helper.pid;
+  try { kill(helper.pid); } catch { /* already gone */ }
+  error(`❌  "${opts.label}" did not connect within ${opts.timeoutMs}ms (extension installed but the bridge didn't register — daemon port mismatch or a stale profile).`);
+  return null;
+}
+
+/**
+ * Long-lived `dassi __launch-hold` helper (a detached child of `dassi launch` on branded
+ * Chrome): spawns Chrome with the CDP pipe, installs the dist, signals readiness, then
+ * HOLDS the pipe open until killed — a loadUnpacked extension lives only as long as its
+ * debugging session. On SIGTERM/SIGINT (from `dassi launch --stop`) or if Chrome exits, it
+ * tears down and exits.
+ * @param {{ distPath:string; profileDir:string; label:string; bridgePort:number; chromePath:string;
+ *          spawn?:Function; loadExtension?:Function; onReady?:Function; hold?:()=>Promise<void>;
+ *          error?:Function; exit?:Function }} o
+ * @returns {Promise<void>} In production never resolves (hold() is infinite until killed);
+ *   resolves after calling exit(1) on extension-install failure.
+ */
+export async function runPipeHoldHelper(o) {
+  const {
+    distPath, profileDir, label, bridgePort, chromePath,
+    spawn = childSpawn, loadExtension = loadExtensionOverPipe,
+    onReady = () => {}, hold = () => new Promise(() => {}),
+    error = (m) => process.stderr.write(`${m}\n`), exit = process.exit,
+  } = o;
+  const child = spawn(chromePath, buildLaunchArgs({ profileDir }), { stdio: ['ignore', 'ignore', 'ignore', 'pipe', 'pipe'] });
+  let dispose = () => {};
+  let shuttingDown = false;
+  const shutdown = () => {
+    if (shuttingDown) return;
+    shuttingDown = true;
+    try { dispose(); } catch { /* ignore */ }
+    try { child.kill('SIGTERM'); } catch { /* already gone */ }
+    exit(0);
+  };
+  // Reason: this helper runs as a detached process whose whole job is to hold the CDP
+  // pipe open. SIGTERM is how `dassi launch --stop` tears it down; SIGINT covers Ctrl-C.
+  // Without these handlers the Chrome child (and its loaded extension) would be orphaned.
+  process.on('SIGTERM', shutdown);
+  process.on('SIGINT', shutdown);
+  child.on('error', () => {});
+  child.on('exit', () => { if (!shuttingDown) exit(0); }); // Chrome died → stop holding
+  try {
+    ({ dispose } = await loadExtension({ child, distPath, label, bridgePort }));
+  } catch (err) {
+    // Reason: set shuttingDown FIRST so the child.on('exit') guard above can't win the
+    // race and call exit(0) — a failed install must surface as exit(1), not false success.
+    shuttingDown = true;
+    error(`launch-hold: failed to install extension: ${err.message}`);
+    try { child.kill('SIGTERM'); } catch { /* already gone */ }
+    return exit(1);
+  }
+  onReady();
+  await hold(); // hold the pipe open (draining) until killed
+}
+
+/**
+ * Resolve the dist dir, Chrome binary, and profile dir for a launch.
+ * Calls `exit(1)` and returns null on any failure (extracted to keep
+ * handleLaunch within the function-length limit).
+ * @param {{label:string; dist:string|null; chrome:string|null; profileDir:string|null}} opts
+ * @param {{ error: Function; exit: Function; appDir: string; mkdir: Function }} deps
+ * @returns {{distPath:string; chromePath:string; profileDir:string} | null}
+ */
+function resolveLaunchTarget(opts, { error, exit, appDir, mkdir }) {
+  let distPath;
+  try { distPath = resolveDistPath({ dist: opts.dist }); }
+  catch (err) { error(`❌  ${err.message}`); exit(1); return null; }
+
+  const chromePath = resolveChromePath({ override: opts.chrome });
+  if (!chromePath) {
+    error('❌  Could not find Chrome. Pass --chrome <path> to the Chrome/Chromium binary.');
+    exit(1);
+    return null;
+  }
+
+  const profileDir = opts.profileDir ?? path.join(appDir, `launch-${opts.label}`);
+  mkdir(profileDir);
+  return { distPath, chromePath, profileDir };
+}
+
+/**
+ * Kill the Chrome instance(s) recorded by `dassi launch`.
+ * @param {{label?: string; all?: boolean}} opts
+ * @param {{ launchesFile: string; kill?: (pid:number)=>void; log?: Function }} deps
+ */
+export function handleStop(opts, deps) {
+  const { launchesFile, kill = (pid) => process.kill(pid), log = console.log } = deps;
+  const list = readLaunches(launchesFile);
+  const targets = opts.all ? list : list.filter((e) => e.label === opts.label);
+  if (targets.length === 0) {
+    log(opts.all ? 'No launched Chrome instances to stop.' : `Nothing to stop for "${opts.label}".`);
+    return;
+  }
+  for (const e of targets) {
+    // Reason: guard against corrupt launches.json entries with non-number pids, which
+    // would cause process.kill to throw a misleading TypeError instead of a clear skip.
+    if (typeof e.pid !== 'number') { log(`Skipping "${e.label}" — corrupt record (no pid).`); removeLaunch(launchesFile, e.label); continue; }
+    try { kill(e.pid); log(`Stopped "${e.label}" (pid ${e.pid}).`); }
+    catch { log(`"${e.label}" (pid ${e.pid}) was already gone.`); }
+    removeLaunch(launchesFile, e.label);
+  }
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@dassi_ai/cli",
-  "version": "0.2.0",
+  "version": "0.4.0",
   "description": "CLI for the Dassi Chrome extension — run browser automation from the terminal",
   "type": "module",
   "bin": {
@@ -13,6 +13,9 @@
     "tool-commands.mjs",
     "format-response.mjs",
     "group-expansion.mjs",
+    "launch.mjs",
+    "_launch-pipe.mjs",
+    "help-text.mjs",
     ".claude-plugin/",
     "skills/",
     "README.md"

package/skills/operate/command-reference.md

@@ -32,11 +32,26 @@ Each accepts `--tab <id>` OR `--group <id>` OR `--group-title <name>`, except wh
 | `open [url]` | url? | **Single-target only** (`--tab` required). Opens new tab in current group. |
 | `close` | — | Close tab. Fans out across a group = close all member tabs. |
 
+## Dev launch commands (loading a local build for testing)
+
+| Command | Args | Notes |
+|---|---|---|
+| `dassi launch` | `--label <name>` (default `dev`), `--dist <path>` (default `extension/dist`), `--chrome <path>`, `--load-mode auto\|pipe\|flag`, `--timeout <ms>` | Open a dedicated Chrome with a locally-built dev dist loaded, registered under `--label`. Then drive it by adding `--profile <label>` to any command. |
+| `dassi launch --stop [label]` / `--stop-all` | label? | Close a launched Chrome (default label `dev`). |
+| `dassi list-profiles` | `--json` | List connected Chrome instances (profiles), by `label`/id. |
+
+**How the extension is loaded** (`--load-mode`, default `auto`):
+- **Branded Google Chrome 137+** disabled the `--load-extension` flag (`ERR_BLOCKED_BY_CLIENT`), so launch installs the dist at runtime via the `Extensions.loadUnpacked` CDP command over `--remote-debugging-pipe`. Such an extension is tied to the debugging session, so launch spawns a detached helper that holds the pipe open; `--stop` kills the helper (which closes the pipe + its Chrome).
+- **Chrome for Testing / Chromium** still honour `--load-extension` (persistent) → used directly, no helper.
+- `--load-mode pipe|flag` forces a mode (e.g. `--chrome <cft> --load-mode pipe` exercises the pipe path on Chrome for Testing); `auto` detects from the binary's `--version`.
+- A freshly launched profile is **signed out** — sign in to that Chrome before `dassi run`/agent commands work in it.
+
 ## Global options
 
 | Flag | Effect |
 |---|---|
 | `--session <name>` | Daemon session name (default `default`). Selects which per-session daemon process and Unix socket the CLI connects to. Each distinct `--session` value spawns its own daemon; only one can be running at a time because they all bind the same WebSocket port (see the "Multi-tab dispatch is sequential" note below). |
+| `--profile <label>` (alias `--label`) | Target a specific connected Chrome instance (e.g. one started by `dassi launch --label qa`). Required when multiple profiles are connected. |
 | `--json` | Raw JSON output (in group fan-out: single JSON array of `{tabId, response}` entries). |
 | `--version`, `--help` | Self-explanatory. |