@dassi_ai/cli 0.4.0 → 0.5.0

package/README.md

@@ -78,6 +78,9 @@ dassi launch --label qa --dist some/dist    # custom label + dist
 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)
+# Pass extra args to Chrome by appending `-- <args>` after all CLI flags
+# (forwarded verbatim in both load modes; rejected on non-launch commands):
+dassi launch -- --headless=new --remote-debugging-port=9222
 # 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.

package/daemon-client.mjs

@@ -0,0 +1,227 @@
+/**
+ * Daemon client — the CLI side of the daemon protocol. Extracted from
+ * dassi.mjs to keep that file within the CLAUDE.md 500-line limit.
+ *
+ * Covers spawning the daemon, waiting for its ready file, the Unix-socket
+ * NDJSON transport, and the interactive onboarding flow (install prompt +
+ * sign-in poll loop).
+ */
+
+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,
+  getReadyFile,
+  isDaemonRunning,
+  parseReadyPayload,
+  DASSI_EXTENSION_ID,
+} 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;
+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/${DASSI_EXTENSION_ID}`;
+
+// ─── 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) {
+  return new Promise((resolve, reject) => {
+    const socket = net.createConnection(socketPath);
+    let buffer = '';
+    let settled = 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;
+      fn(val);
+    };
+
+    socket.on('connect', () => {
+      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'));
+      }
+    });
+  });
+}
+
+// ─── Login helpers ────────────────────────────────────────────────────────────
+
+/**
+ * Defense-in-depth check for `optionsUrl` before handing it to the `open`
+ * package. Legit URLs always come from `chrome.runtime.getURL('options.html')`
+ * → `chrome-extension://<id>/options.html`. Anything else is unexpected and
+ * we should not auto-launch it (the `open` package shells out to the OS URL
+ * handler).
+ * @param {unknown} optionsUrl
+ * @returns {boolean}
+ */
+export function isValidOptionsUrl(optionsUrl) {
+  return typeof optionsUrl === 'string' && /^chrome-extension:\/\/[a-z]{32}\//.test(optionsUrl);
+}
+
+/**
+ * Polls the daemon's status until the user signs in (extension reports
+ * authenticated=true) or the LOGIN_TIMEOUT_MS deadline elapses. On entry,
+ * best-effort auto-opens the extension's options page (subject to the
+ * isValidOptionsUrl guard above).
+ * @param {string} socketPath - Path to the daemon Unix socket.
+ * @param {string | undefined} optionsUrl - URL of the Dassi options page.
+ * @returns {Promise<void>} Resolves on successful login; throws on timeout.
+ */
+export async function waitForLogin(socketPath, optionsUrl) {
+  console.error(`⚠️  Dassi is installed but you're not signed in.\n    Opening the Dassi settings page...\n`);
+
+  // Auto-open the options page — best-effort (package may not be installed).
+  // Reason: only open URLs the extension would legitimately produce
+  // (chrome.runtime.getURL → `chrome-extension://<id>/options.html`).
+  // Defense-in-depth: even though optionsUrl is sourced from the daemon's
+  // ready file (which lives in our owner-only ~/.dassi/ dir), validating the
+  // protocol prevents `open` from launching arbitrary URIs/shell-handlers if
+  // the file is ever tampered with.
+  if (isValidOptionsUrl(optionsUrl)) {
+    try {
+      const { default: open } = await import('open');
+      await open(String(optionsUrl));
+    } catch {
+      console.error(`    Please open: ${optionsUrl}`);
+    }
+  } else if (optionsUrl) {
+    console.error(`    Refusing to auto-open unexpected URL: ${optionsUrl}\n    Please open the Dassi settings page manually.`);
+  }
+
+  // Poll the daemon socket every LOGIN_POLL_MS until authenticated
+  console.error('    Waiting for sign-in... (Ctrl+C to cancel)');
+  const deadline = Date.now() + LOGIN_TIMEOUT_MS;
+  let pollIndex = 0;
+  while (Date.now() < deadline) {
+    await new Promise((r) => setTimeout(r, LOGIN_POLL_MS));
+    try {
+      // Reason: increment poll index so each status request has a unique id for tracing
+      const resp = await sendCommand(socketPath, { id: `poll-auth-${pollIndex++}`, action: 'status' });
+      if (resp.success && resp.data?.authenticated) {
+        console.error(`    ✓  Signed in as ${resp.data.email}\n    ✓  Ready\n`);
+        return;
+      }
+    } catch { /* daemon may not be socket-ready yet — keep polling */ }
+  }
+
+  throw new Error('Login timed out. Please sign in and try again.');
+}
+
+// ─── Daemon readiness ─────────────────────────────────────────────────────────
+
+/**
+ * Ensures the daemon is running and ready, handling onboarding if needed.
+ * @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') {
+    console.error(
+      `❌  Dassi extension not detected.\n\n` +
+      `   Install it from:\n   ${CHROME_WEB_STORE_URL}\n\n` +
+      `   Then run this command again.`
+    );
+    process.exit(1);
+  }
+
+  if (ready.status === 'needs_login') {
+    await waitForLogin(socketPath, ready.optionsUrl ? String(ready.optionsUrl) : undefined);
+  }
+
+  return socketPath;
+}

package/dassi.mjs

@@ -4,21 +4,12 @@
  * Protocol-compatible with agent-browser: {id, action, ...} → {id, success, data/error}
  */
 
-import * as net from 'net';
 import * as fs from 'fs';
 import * as path from 'path';
 import * as child_process from 'child_process';
 import { fileURLToPath, pathToFileURL } from 'url';
-import {
-  getSocketPath,
-  getReadyFile,
-  isDaemonRunning,
-  parseReadyPayload,
-  validateSession,
-  DASSI_EXTENSION_ID,
-  getAppDir,
-  getLaunchesFile,
-} from './dassi-shared.mjs';
+import { getSocketPath, validateSession, getAppDir, getLaunchesFile } from './dassi-shared.mjs';
+import { ensureDaemonRunning, sendCommand, ensureDaemonReady } from './daemon-client.mjs';
 import { dispatchLaunch } from './launch.mjs';
 import { parseToolCommand, requireTarget, parseStrictInt } from './tool-commands.mjs';
 import { runWithGroupExpansion } from './group-expansion.mjs';
@@ -26,13 +17,12 @@ 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');
 const VERSION = JSON.parse(fs.readFileSync(path.join(__dirname, 'package.json'), 'utf8')).version;
-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/${DASSI_EXTENSION_ID}`;
+
+// Reason: tests import isValidOptionsUrl from this module (it moved to
+// daemon-client.mjs with the rest of the daemon-client unit) — re-export to
+// keep the public surface and the tests unchanged.
+export { isValidOptionsUrl } from './daemon-client.mjs';
 
 // ─── Arg parsing ──────────────────────────────────────────────────────────────
 
@@ -47,6 +37,16 @@ const CHROME_WEB_STORE_URL = `https://chromewebstore.google.com/detail/dassi-ai-
 export function parseCliArgs(argv) {
   const args = [...argv];
 
+  // Reason: hoist the `--` split to BEFORE global flag parsing so that Chrome
+  // passthrough tokens like --json, --label, --profile, or --stop can never be
+  // mistakenly consumed as CLI flags. Everything after the first `--` token is
+  // sliced out here and stored verbatim in `chromeArgs`; the remaining `args`
+  // array is then parsed as usual with no risk of collision. Non-launch commands
+  // that supply a `--` separator are rejected loudly below (after the action is
+  // known) so callers get a clear error instead of silent data loss.
+  const sepIdx = args.indexOf('--');
+  const chromeArgs = sepIdx === -1 ? [] : args.splice(sepIdx).slice(1);
+
   // Reason: handle --version and --help before any flag parsing so they work
   // even when other flags like --session are incomplete (e.g. `dassi --version --session`)
   if (consumeFlag(args, '--version')) {
@@ -67,6 +67,13 @@ export function parseCliArgs(argv) {
   const command = args.shift();
   if (!command) throw new Error('No command specified. Run: dassi --help');
 
+  // Reason: chromeArgs (tokens after `--`) are only meaningful for the `launch`
+  // command. Any other command that supplies `--` tokens would have them silently
+  // dropped — fail loudly instead so the caller knows their intent was not honoured.
+  if (chromeArgs.length > 0 && command !== 'launch') {
+    throw new Error("'--' is only valid with the launch command");
+  }
+
   if (command === 'list-tabs') {
     const all = consumeFlag(args, '--all');
     return finish('list_tabs', all ? { all: true } : {});
@@ -86,10 +93,16 @@ export function parseCliArgs(argv) {
   }
 
   if (command === 'launch') {
-    if (consumeFlag(args, '--stop-all')) return finish('launch_stop', { all: true });
+    if (consumeFlag(args, '--stop-all')) {
+      // Reason: chromeArgs with --stop-all makes no sense — reject to prevent confusion.
+      if (chromeArgs.length > 0) throw new Error("'--' chrome args cannot be combined with launch --stop-all");
+      return finish('launch_stop', { all: true });
+    }
     const stopIdx = args.indexOf('--stop');
     if (stopIdx !== -1) {
       args.splice(stopIdx, 1);
+      // Reason: chromeArgs with --stop makes no sense — reject to prevent confusion.
+      if (chromeArgs.length > 0) throw new Error("'--' chrome args cannot be combined with launch --stop");
       // 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`
@@ -117,6 +130,7 @@ export function parseCliArgs(argv) {
       profileDir: getFlag(args, '--profile-dir') ?? null,
       loadMode,
       timeoutMs: timeoutRaw ? parseStrictInt(timeoutRaw, '--timeout') : 30000,
+      chromeArgs,
     });
   }
 
@@ -199,167 +213,6 @@ function consumeFlag(args, flag) {
   return true;
 }
 
-// ─── 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) {
-  return new Promise((resolve, reject) => {
-    const socket = net.createConnection(socketPath);
-    let buffer = '';
-    let settled = 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;
-      fn(val);
-    };
-
-    socket.on('connect', () => {
-      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'));
-      }
-    });
-  });
-}
-
-// ─── Login helpers ────────────────────────────────────────────────────────────
-
-/**
- * Defense-in-depth check for `optionsUrl` before handing it to the `open`
- * package. Legit URLs always come from `chrome.runtime.getURL('options.html')`
- * → `chrome-extension://<id>/options.html`. Anything else is unexpected and
- * we should not auto-launch it (the `open` package shells out to the OS URL
- * handler).
- * @param {unknown} optionsUrl
- * @returns {boolean}
- */
-export function isValidOptionsUrl(optionsUrl) {
-  return typeof optionsUrl === 'string' && /^chrome-extension:\/\/[a-z]{32}\//.test(optionsUrl);
-}
-
-/**
- * Polls the daemon's status until the user signs in (extension reports
- * authenticated=true) or the LOGIN_TIMEOUT_MS deadline elapses. On entry,
- * best-effort auto-opens the extension's options page (subject to the
- * isValidOptionsUrl guard above).
- * @param {string} socketPath - Path to the daemon Unix socket.
- * @param {string | undefined} optionsUrl - URL of the Dassi options page.
- * @returns {Promise<void>} Resolves on successful login; throws on timeout.
- */
-export async function waitForLogin(socketPath, optionsUrl) {
-  console.error(`⚠️  Dassi is installed but you're not signed in.\n    Opening the Dassi settings page...\n`);
-
-  // Auto-open the options page — best-effort (package may not be installed).
-  // Reason: only open URLs the extension would legitimately produce
-  // (chrome.runtime.getURL → `chrome-extension://<id>/options.html`).
-  // Defense-in-depth: even though optionsUrl is sourced from the daemon's
-  // ready file (which lives in our owner-only ~/.dassi/ dir), validating the
-  // protocol prevents `open` from launching arbitrary URIs/shell-handlers if
-  // the file is ever tampered with.
-  if (isValidOptionsUrl(optionsUrl)) {
-    try {
-      const { default: open } = await import('open');
-      await open(String(optionsUrl));
-    } catch {
-      console.error(`    Please open: ${optionsUrl}`);
-    }
-  } else if (optionsUrl) {
-    console.error(`    Refusing to auto-open unexpected URL: ${optionsUrl}\n    Please open the Dassi settings page manually.`);
-  }
-
-  // Poll the daemon socket every LOGIN_POLL_MS until authenticated
-  console.error('    Waiting for sign-in... (Ctrl+C to cancel)');
-  const deadline = Date.now() + LOGIN_TIMEOUT_MS;
-  let pollIndex = 0;
-  while (Date.now() < deadline) {
-    await new Promise((r) => setTimeout(r, LOGIN_POLL_MS));
-    try {
-      // Reason: increment poll index so each status request has a unique id for tracing
-      const resp = await sendCommand(socketPath, { id: `poll-auth-${pollIndex++}`, action: 'status' });
-      if (resp.success && resp.data?.authenticated) {
-        console.error(`    ✓  Signed in as ${resp.data.email}\n    ✓  Ready\n`);
-        return;
-      }
-    } catch { /* daemon may not be socket-ready yet — keep polling */ }
-  }
-
-  throw new Error('Login timed out. Please sign in and try again.');
-}
-
 // ─── Immediate actions ────────────────────────────────────────────────────────
 
 // HELP_TEXT lives in ./help-text.mjs (extracted to keep this file within the size limit).
@@ -381,43 +234,6 @@ function handleImmediateAction(action) {
   return false;
 }
 
-// ─── Daemon readiness ─────────────────────────────────────────────────────────
-
-/**
- * Ensures the daemon is running and ready, handling onboarding if needed.
- * @param {string} session
- * @returns {Promise<string>} The daemon's Unix socket path.
- */
-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') {
-    console.error(
-      `❌  Dassi extension not detected.\n\n` +
-      `   Install it from:\n   ${CHROME_WEB_STORE_URL}\n\n` +
-      `   Then run this command again.`
-    );
-    process.exit(1);
-  }
-
-  if (ready.status === 'needs_login') {
-    await waitForLogin(socketPath, ready.optionsUrl ? String(ready.optionsUrl) : undefined);
-  }
-
-  return socketPath;
-}
-
 // ─── Entry point ──────────────────────────────────────────────────────────────
 
 /**

package/help-text.mjs

@@ -27,10 +27,10 @@ export const HELP_TEXT =
   '  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 [--label <name>] [--dist <path>] [--chrome <path>]\n' +
+  '         [--load-mode auto|pipe|flag] [-- <chrome args…>]\n' +
+  '                                  Open Chrome with a dev dist loaded\n' +
+  '                                  (args after -- go to Chrome, e.g. --headless=new)\n' +
   '  launch --stop [label] | --stop-all\n' +
   '                                  Stop a launched Chrome\n\n' +
   'Options:\n' +

package/launch.mjs

@@ -58,16 +58,17 @@ export function resolveDistPath({ dist = null, cwd = process.cwd(), exists = exi
  * `--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
+ * @param {{ profileDir: string; chromeArgs?: string[] }} opts
  * @returns {string[]} Chrome args.
  */
-export function buildLaunchArgs({ profileDir }) {
+export function buildLaunchArgs({ profileDir, chromeArgs = [] }) {
   return [
     '--remote-debugging-pipe',
     '--enable-unsafe-extension-debugging',
     `--user-data-dir=${profileDir}`,
     '--no-first-run',
     '--no-default-browser-check',
+    ...chromeArgs,
   ];
 }
 
@@ -75,10 +76,10 @@ export function buildLaunchArgs({ profileDir }) {
  * 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
+ * @param {{ distPath: string; profileDir: string; label: string; bridgePort: number; chromeArgs?: string[] }} opts
  * @returns {string[]} Chrome args (the final entry is the seed URL to open).
  */
-export function buildFlagArgs({ distPath, profileDir, label, bridgePort }) {
+export function buildFlagArgs({ distPath, profileDir, label, bridgePort, chromeArgs = [] }) {
   const seed = `options.html?label=${encodeURIComponent(label)}&bridgePort=${bridgePort}`;
   return [
     `--load-extension=${distPath}`,
@@ -86,6 +87,9 @@ export function buildFlagArgs({ distPath, profileDir, label, bridgePort }) {
     `--user-data-dir=${profileDir}`,
     '--no-first-run',
     '--no-default-browser-check',
+    // Reason: extra args must precede the positional seed URL — Chrome treats
+    // everything after the first positional as URLs to open.
+    ...chromeArgs,
     `chrome-extension://${DASSI_EXTENSION_ID}/${seed}`,
   ];
 }
@@ -219,7 +223,7 @@ async function preflightLaunch({ ensureDaemonRunning, getSocketPath, sendCommand
  * 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 {{label:string; dist:string|null; chrome:string|null; profileDir:string|null; loadMode?:string; timeoutMs:number; chromeArgs?:string[]}} 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).
@@ -262,12 +266,17 @@ export async function handleLaunch(opts, deps) {
  * @returns {Promise<void>}
  */
 export async function handleLaunchHold(env = process.env, run = runPipeHoldHelper) {
+  let chromeArgs = [];
+  // Reason: fail-open to [] — a malformed env var must not strand the helper.
+  try { chromeArgs = JSON.parse(env.DASSI_HOLD_CHROME_ARGS ?? '[]'); } catch { process.stderr.write('⚠️  Ignoring malformed DASSI_HOLD_CHROME_ARGS (expected JSON array).\n'); }
+  if (!Array.isArray(chromeArgs)) chromeArgs = [];
   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,
+    chromeArgs,
   });
 }
 
@@ -293,7 +302,7 @@ export async function dispatchLaunch(action, params, deps) {
  * @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' });
+  const child = spawn(chromePath, buildFlagArgs({ distPath, profileDir, label: opts.label, bridgePort, chromeArgs: opts.chromeArgs ?? [] }), { detached: true, stdio: 'ignore' });
   child.on('error', () => {});
   child.unref();
   if (typeof child.pid !== 'number') {
@@ -327,6 +336,8 @@ async function spawnHelperAndConnect({ spawn, kill, sendCommand, socketPath, chr
       DASSI_HOLD_PROFILE_DIR: profileDir,
       DASSI_HOLD_BRIDGE_PORT: String(bridgePort),
       DASSI_HOLD_CHROME: chromePath,
+      // Reason: JSON, not space-joined — Chrome args may contain spaces.
+      DASSI_HOLD_CHROME_ARGS: JSON.stringify(opts.chromeArgs ?? []),
     },
   });
   helper.on('error', () => {});
@@ -349,6 +360,7 @@ async function spawnHelperAndConnect({ spawn, kill, sendCommand, socketPath, chr
  * 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;
+ *          chromeArgs?: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);
@@ -357,11 +369,12 @@ async function spawnHelperAndConnect({ spawn, kill, sendCommand, socketPath, chr
 export async function runPipeHoldHelper(o) {
   const {
     distPath, profileDir, label, bridgePort, chromePath,
+    chromeArgs = [],
     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'] });
+  const child = spawn(chromePath, buildLaunchArgs({ profileDir, chromeArgs }), { stdio: ['ignore', 'ignore', 'ignore', 'pipe', 'pipe'] });
   let dispose = () => {};
   let shuttingDown = false;
   const shutdown = () => {

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@dassi_ai/cli",
-  "version": "0.4.0",
-  "description": "CLI for the Dassi Chrome extension — run browser automation from the terminal",
+  "version": "0.5.0",
+  "description": "CLI for the Dassi Chrome extension \u2014 run browser automation from the terminal",
   "type": "module",
   "bin": {
     "dassi": "./dassi.mjs"
@@ -9,6 +9,7 @@
   "files": [
     "dassi.mjs",
     "dassi-daemon.mjs",
+    "daemon-client.mjs",
     "dassi-shared.mjs",
     "tool-commands.mjs",
     "format-response.mjs",