@dassi_ai/cli 0.1.2 → 0.3.0

package/README.md

@@ -47,6 +47,25 @@ dassi list-tabs --json
 # Use a named session
 dassi list-tabs --session work
 
+# List connected profiles (multiple Chrome profiles can connect at once)
+dassi list-profiles
+
+# 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.
+
 # Show version / help
 dassi --version
 dassi --help

package/dassi-daemon.mjs

@@ -24,6 +24,8 @@ import {
   cleanupDaemonFiles,
   buildReadyPayload,
   createCommandQueue,
+  createConnectionRegistry,
+  getDaemonBridgePort,
 } from './dassi-shared.mjs';
 
 // ─── Constants ────────────────────────────────────────────────────────────────
@@ -31,12 +33,9 @@ import {
 const IDLE_TIMEOUT_MS = 30 * 60 * 1000;
 const IDLE_CHECK_INTERVAL_MS = 5 * 60 * 1000;
 
-// ─── Module-level extension connection state ──────────────────────────────────
-
-/** Active WebSocket connection to the registered Dassi extension. */
-let extensionSocket = null;
-/** Pending response callbacks keyed by request ID. */
-const pendingExtResponses = new Map();
+// Reason: a registry of connected extensions keyed by profile label replaces
+// the old single-socket model so multiple Chrome profiles can connect at once.
+const registry = createConnectionRegistry();
 
 // ─── WebSocket loader helper ──────────────────────────────────────────────────
 
@@ -62,17 +61,16 @@ async function loadWebSocket() {
 // ─── Extension response routing ──────────────────────────────────────────────
 
 /**
- * Sets up the persistent message handler on the extension WebSocket that routes
- * responses back to callers waiting in pendingExtResponses.
- * @param {import('ws').WebSocket} ws
+ * Route responses from one extension connection back to its pending callers.
+ * @param {{ ws: any; pending: Map<string, any> }} entry
  */
-function setupResponseRouter(ws) {
-  ws.on('message', (responseData) => {
+function setupResponseRouter(entry) {
+  entry.ws.on('message', (responseData) => {
     let resp;
     try { resp = JSON.parse(responseData.toString()); } catch { return; }
-    const pending = pendingExtResponses.get(String(resp.id));
+    const pending = entry.pending.get(String(resp.id));
     if (!pending) return;
-    pendingExtResponses.delete(String(resp.id));
+    entry.pending.delete(String(resp.id));
     if (resp.error) {
       pending.reject(new Error(resp.error.message ?? String(resp.error)));
     } else {
@@ -82,38 +80,37 @@ function setupResponseRouter(ws) {
 }
 
 /**
- * Reject all pending extension responses with a disconnection error.
- * Called when the extension WebSocket closes so callers don't hang forever.
+ * Reject all pending responses for one connection (called when it closes).
+ * @param {{ pending: Map<string, any> }} entry
  */
-function drainPendingResponses() {
-  for (const [id, pending] of pendingExtResponses) {
+function drainPendingResponses(entry) {
+  for (const [id, pending] of entry.pending) {
     pending.reject(new Error('Extension disconnected'));
-    pendingExtResponses.delete(id);
+    entry.pending.delete(id);
   }
 }
 
 // ─── Extension server ─────────────────────────────────────────────────────────
 
 /**
- * Accepts a newly registered extension WebSocket: replaces any existing socket,
- * drains pending responses from the old connection, and wires up the new one.
- * @param {import('ws').WebSocket} ws - The new WebSocket connection.
+ * Register a newly connected extension socket into the registry and wire up
+ * its response router + close handler.
+ * @param {any} ws
+ * @param {{ label: string | null; installId: string }} identity
+ * @param {number} port - The port this daemon session listens on.
+ * @returns {object} The registry entry.
  */
-function acceptExtensionSocket(ws) {
-  // Reason: if an old socket exists, close it cleanly before replacing
-  if (extensionSocket && extensionSocket !== ws) {
-    try { extensionSocket.close(); } catch { /* already closed */ }
-  }
-  drainPendingResponses();
-  extensionSocket = ws;
+function acceptExtensionSocket(ws, identity, port) {
+  const key = registry.add({ ws, label: identity.label, installId: identity.installId, port });
+  const entry = registry.getByWs(ws);
   ws.on('close', () => {
-    if (extensionSocket === ws) {
-      extensionSocket = null;
-      drainPendingResponses();
-      console.log('[dassi-daemon] Extension disconnected, waiting for reconnect…');
-    }
+    const removed = registry.remove(ws);
+    drainPendingResponses(entry);
+    if (removed) console.log(`[dassi-daemon] Extension "${removed.label}" disconnected`);
   });
-  setupResponseRouter(ws);
+  setupResponseRouter(entry);
+  console.log(`[dassi-daemon] Extension registered as "${key}"`);
+  return entry;
 }
 
 /**
@@ -123,53 +120,46 @@ function acceptExtensionSocket(ws) {
  * @param {import('ws').WebSocket} ws - The connected WebSocket.
  * @param {Buffer} data - Raw message data.
  * @param {{ resolved: boolean; timeout: ReturnType<typeof setTimeout> }} ctx - Shared state.
- * @param {import('ws').WebSocketServer} wss - The server (closed on fatal error).
  * @param {(value: unknown) => void} resolve - Promise resolve callback.
  * @param {(reason: Error) => void} reject - Promise reject callback.
+ * @param {number} port - The port the WS server is bound to.
  */
-async function handleRegistration(ws, data, ctx, wss, resolve, reject) {
+async function handleRegistration(ws, data, ctx, resolve, reject, port) {
   let msg;
   try { msg = JSON.parse(data.toString()); } catch { return; }
   if (msg.type !== 'register' || msg.client !== 'dassi-extension') return;
 
-  // Reason: only accept a new registration when the current socket is dead.
-  // This prevents a rogue local process from hijacking the extension socket
-  // while a healthy connection exists.
-  if (extensionSocket && extensionSocket.readyState === 1 /* OPEN */) {
-    console.log('[dassi-daemon] Rejected registration — existing socket still healthy');
-    ws.close();
-    return;
-  }
-
-  acceptExtensionSocket(ws);
+  const entry = acceptExtensionSocket(
+    ws,
+    { label: typeof msg.label === 'string' ? msg.label : null, installId: String(msg.installId ?? '') },
+    port,
+  );
 
   if (!ctx.resolved) {
     clearTimeout(ctx.timeout);
     try {
-      const status = await dispatchToExtension({ id: 'init', action: 'status' });
+      // Reason: route the startup status check to the connection that just registered.
+      const status = await dispatchToExtension({ id: 'init', action: 'status', target: entry.label });
       ctx.resolved = true;
       resolve(status);
     } catch (err) {
-      // Reason: don't close WSS — extension may reconnect and retry
+      // Reason: leave ctx.resolved false so a reconnecting extension can retry
+      // the startup status check rather than failing the daemon permanently.
       console.error('[dassi-daemon] Initial status check failed:', err.message);
       reject(err);
     }
   } else {
-    console.log('[dassi-daemon] Extension reconnected');
+    // Reason: daemon already started — this is a reconnect or an additional profile.
+    console.log('[dassi-daemon] Extension registered (daemon already started)');
   }
 }
 
-// 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).
@@ -199,7 +189,7 @@ async function startExtensionServer() {
     });
 
     wss.on('connection', (ws) => {
-      ws.once('message', (data) => handleRegistration(ws, data, ctx, wss, resolve, reject));
+      ws.once('message', (data) => handleRegistration(ws, data, ctx, resolve, reject, BRIDGE_PORT));
     });
   });
 }
@@ -210,34 +200,51 @@ async function startExtensionServer() {
  * Dispatches a single command to the Dassi extension via the persistent WS
  * connection, translating from the daemon's internal format to the extension's
  * JSON-RPC-style protocol.
- * @param {Record<string, unknown>} cmd - Command object with {id, action, ...params}
+ * @param {Record<string, unknown>} cmd - Command object with {id, action, target?, ...params}
  * @returns {Promise<unknown>} The extension's result value (not wrapped in success/data).
  */
 async function dispatchToExtension(cmd) {
-  if (!extensionSocket || extensionSocket.readyState !== 1 /* OPEN */) {
+  const { id, action, target = null, ...params } = cmd;
+  const entry = registry.resolve(target); // throws with a helpful message if ambiguous/unknown/none
+  if (!entry.ws || entry.ws.readyState !== 1 /* OPEN */) {
     throw new Error('Extension not connected');
   }
 
-  const { id, action, ...params } = cmd;
-  // Reason: the extension expects JSON-RPC style {id, method, params}, not {id, action, ...}
+  // Reason: the extension expects JSON-RPC {id, method, params}; `target` is a
+  // daemon-only routing field and must not leak into the extension params.
   const message = { id, method: action ?? String(id), params };
-  extensionSocket.send(JSON.stringify(message));
+  entry.ws.send(JSON.stringify(message));
 
   const timeoutMs = typeof params.timeoutMs === 'number' ? params.timeoutMs + 10_000 : 65_000;
 
   return new Promise((resolve, reject) => {
     const timer = setTimeout(() => {
-      pendingExtResponses.delete(String(id));
+      entry.pending.delete(String(id));
       reject(new Error(`Extension timeout after ${timeoutMs}ms`));
     }, timeoutMs);
 
-    pendingExtResponses.set(String(id), {
+    entry.pending.set(String(id), {
       resolve: (result) => { clearTimeout(timer); resolve(result); },
       reject: (err) => { clearTimeout(timer); reject(err); },
     });
   });
 }
 
+/**
+ * Handle commands the daemon answers itself (no extension round-trip).
+ * Returns a response object, or null if the command should be dispatched to
+ * an extension instead.
+ * @param {Record<string, unknown>} cmd
+ * @param {ReturnType<typeof createConnectionRegistry>} reg
+ * @returns {object | null}
+ */
+export function handleDaemonLocalCommand(cmd, reg) {
+  if (cmd?.action === 'list_profiles') {
+    return { id: String(cmd.id ?? 'unknown'), success: true, data: reg.list() };
+  }
+  return null;
+}
+
 /**
  * Refresh the ready file when the latest dispatched command was a `status` query.
  *
@@ -395,6 +402,10 @@ export async function startDaemon() {
   let lastCommandAt = Date.now();
   const queue = createCommandQueue(async (cmd) => {
     lastCommandAt = Date.now();
+    // Reason: daemon-local commands (e.g. list_profiles) are answered from the
+    // registry and intentionally skip extension dispatch + ready-file refresh.
+    const local = handleDaemonLocalCommand(cmd, registry);
+    if (local) return local;
     try {
       const result = await dispatchToExtension(cmd);
       refreshReadyFileFromStatusResult(readyFile, cmd, result);

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 ───────────────────────────────────────────────────────
 
 /**
@@ -180,3 +214,123 @@ export function createCommandQueue(handler) {
     },
   };
 }
+
+// ─── Connection registry ──────────────────────────────────────────────────────
+
+/**
+ * Creates a registry of connected extension sockets, keyed by a unique label.
+ * Replaces the daemon's old single-socket model so multiple Chrome profiles can
+ * connect at once and commands can be routed to a chosen one by label.
+ *
+ * @returns {{
+ *   add: (conn: { ws: any; label: string | null; installId: string; port: number }) => string;
+ *   remove: (ws: any) => ({ label: string; installId: string } | null);
+ *   getByWs: (ws: any) => (object | null);
+ *   resolve: (target: string | null) => object;
+ *   list: () => Array<{ label: string; port: number }>;
+ *   size: () => number;
+ * }}
+ */
+export function createConnectionRegistry() {
+  /** @type {Map<string, { ws: any; label: string; installId: string; port: number; pending: Map<string, any> }>} */
+  const conns = new Map();
+
+  // Reason: label is the routing key; if two profiles share a label, suffix the
+  // installId so a connection never silently fails to register (suffix > reject).
+  function uniqueKey(label) {
+    if (!conns.has(label)) return label;
+    let i = 2;
+    while (conns.has(`${label}#${i}`)) i++;
+    return `${label}#${i}`;
+  }
+
+  function labels() {
+    return [...conns.values()].map((c) => c.label);
+  }
+
+  return {
+    /**
+     * Register a new extension connection. Returns the unique key (label) assigned.
+     * Duplicate labels are disambiguated by appending a numeric suffix.
+     * @param {{ ws: any; label: string | null; installId: string; port: number }} conn
+     * @returns {string}
+     */
+    add({ ws, label, installId, port }) {
+      // Reason: on reconnect (port/label change) the new TCP connection can register
+      // before the daemon observes the old socket's close. Evict any stale entry for
+      // the same install first, so we don't end up with phantom duplicates (dev +
+      // dev#2) that make resolve(null) wrongly report "multiple profiles".
+      if (installId) {
+        for (const [k, c] of conns) {
+          if (c.installId === installId) { conns.delete(k); break; }
+        }
+      }
+      // Reason: identity fallback chain — label, then installId, then port — so a
+      // connection is always addressable even if a legacy build reports neither.
+      const base =
+        (label && String(label).trim()) || (installId && String(installId).trim()) || String(port);
+      const key = uniqueKey(base);
+      conns.set(key, { ws, label: key, installId, port, pending: new Map() });
+      return key;
+    },
+
+    /**
+     * Remove the connection associated with the given WebSocket.
+     * @param {any} ws
+     * @returns {{ label: string; installId: string } | null}
+     */
+    remove(ws) {
+      for (const [key, c] of conns) {
+        if (c.ws === ws) {
+          conns.delete(key);
+          return { label: c.label, installId: c.installId };
+        }
+      }
+      return null;
+    },
+
+    /**
+     * Look up the registry entry for a given WebSocket (includes its pending map).
+     * @param {any} ws
+     * @returns {object | null}
+     */
+    getByWs(ws) {
+      for (const c of conns.values()) if (c.ws === ws) return c;
+      return null;
+    },
+
+    /**
+     * Resolve a target label to its registry entry.
+     * Passing null auto-resolves when exactly one connection is registered.
+     * Throws descriptive errors for no connections, ambiguity, or unknown label.
+     * @param {string | null} target
+     * @returns {object}
+     */
+    resolve(target) {
+      if (conns.size === 0) throw new Error('No extension connected');
+      if (target == null) {
+        if (conns.size === 1) return [...conns.values()][0];
+        throw new Error(`Multiple profiles connected (${labels().join(', ')}). Specify --profile <label>.`);
+      }
+      const entry = conns.get(String(target));
+      if (!entry) throw new Error(`Unknown profile "${target}". Connected: ${labels().join(', ')}`);
+      return entry;
+    },
+
+    /**
+     * Returns a shallow list of all connected profiles (label + port only).
+     * @returns {Array<{ label: string; port: number }>}
+     */
+    list() {
+      return [...conns.values()].map((c) => ({ label: c.label, port: c.port }));
+    },
+
+    /**
+     * Returns the number of currently connected profiles.
+     * @returns {number}
+     */
+    size() {
+      return conns.size;
+    },
+  };
+}

package/dassi.mjs

@@ -15,10 +15,15 @@ import {
   isDaemonRunning,
   parseReadyPayload,
   validateSession,
+  DASSI_EXTENSION_ID,
+  getAppDir,
+  getLaunchesFile,
 } from './dassi-shared.mjs';
+import { handleLaunch, handleStop } 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 ──────────────────────────────────────────────────────────────
 
@@ -37,7 +42,7 @@ const CHROME_WEB_STORE_URL = 'https://chromewebstore.google.com/detail/dassi-ai-
  * agent commands (run, list-tabs, status, raw), and top-level flags (--version, --help).
  * Run `dassi --help` for the full command reference.
  * @param {string[]} argv  process.argv.slice(2)
- * @returns {{ action: string; params: Record<string, unknown>; session: string; json: boolean }}
+ * @returns {{ action: string; params: Record<string, unknown>; session: string; json: boolean; profile: string | null }}
  */
 export function parseCliArgs(argv) {
   const args = [...argv];
@@ -45,30 +50,71 @@ export function parseCliArgs(argv) {
   // 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')) {
-    return { action: 'version', params: {}, session: 'default', json: false };
+    return { action: 'version', params: {}, session: 'default', json: false, profile: null };
   }
   if (consumeFlag(args, '--help')) {
-    return { action: 'help', params: {}, session: 'default', json: false };
+    return { action: 'help', params: {}, session: 'default', json: false, profile: null };
   }
 
   const session = validateSession(getFlag(args, '--session') ?? process.env.DASSI_SESSION ?? 'default');
   const json = consumeFlag(args, '--json');
+  const profile = getFlag(args, '--profile') ?? getFlag(args, '--label') ?? null;
+
+  // Reason: centralise the return shape so every command branch includes profile
+  // without editing each return individually
+  const finish = (action, params) => ({ action, params, session, json, profile });
 
   const command = args.shift();
   if (!command) throw new Error('No command specified. Run: dassi --help');
 
   if (command === 'list-tabs') {
     const all = consumeFlag(args, '--all');
-    return { action: 'list_tabs', params: all ? { all: true } : {}, session, json };
+    return finish('list_tabs', all ? { all: true } : {});
   }
 
   if (command === 'list-groups') {
     const all = consumeFlag(args, '--all');
-    return { action: 'list_groups', params: all ? { all: true } : {}, session, json };
+    return finish('list_groups', all ? { all: true } : {});
   }
 
   if (command === 'status') {
-    return { action: 'status', params: {}, session, json };
+    return finish('status', {});
+  }
+
+  if (command === 'list-profiles') {
+    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.');
+    }
+    return finish('launch', {
+      label: launchLabel,
+      dist: getFlag(args, '--dist') ?? null,
+      chrome: getFlag(args, '--chrome') ?? null,
+      profileDir: getFlag(args, '--profile-dir') ?? null,
+      timeoutMs: timeoutRaw ? parseStrictInt(timeoutRaw, '--timeout') : 30000,
+    });
   }
 
   if (command === 'run') {
@@ -78,12 +124,12 @@ export function parseCliArgs(argv) {
     const timeoutRaw = getFlag(args, '--timeout');
     const timeoutMs = timeoutRaw ? parseStrictInt(timeoutRaw, '--timeout') : undefined;
     const base = { prompt, ...(timeoutMs !== undefined ? { timeoutMs } : {}) };
-    return { action: 'run', params: { ...base, ...target }, session, json };
+    return finish('run', { ...base, ...target });
   }
 
   if (command === 'bug-report') {
     const output = getFlag(args, '-o') ?? getFlag(args, '--output');
-    return { action: 'export_logs', params: { output }, session, json };
+    return finish('export_logs', { output });
   }
 
   if (command === 'panel-screenshot') {
@@ -95,7 +141,7 @@ export function parseCliArgs(argv) {
     const heightRaw = getFlag(args, '--height');
     const width = widthRaw ? parseStrictInt(widthRaw, '--width') : undefined;
     const height = heightRaw ? parseStrictInt(heightRaw, '--height') : undefined;
-    return { action: 'panel_screenshot', params: { tabId, ...(output ? { _output: output } : {}), ...(width ? { width } : {}), ...(height ? { height } : {}) }, session, json };
+    return finish('panel_screenshot', { tabId, ...(output ? { _output: output } : {}), ...(width ? { width } : {}), ...(height ? { height } : {}) });
   }
 
   if (command === 'raw') {
@@ -104,14 +150,14 @@ export function parseCliArgs(argv) {
     const cmd = JSON.parse(rawArg);
     // Reason: store action='raw' as a sentinel so run() can send the full cmd envelope
     // verbatim, letting the user control every field (including action) without reconstruction
-    return { action: 'raw', params: cmd, session, json };
+    return finish('raw', cmd);
   }
 
   // Reason: Tool commands are extracted to tool-commands.mjs to keep parseCliArgs
   // and dassi.mjs within CLAUDE.md size limits (40 lines / 500 lines).
   const toolParams = parseToolCommand(command, args, getFlag, consumeFlag);
   if (toolParams) {
-    return { action: 'tool_exec', params: toolParams, session, json };
+    return finish('tool_exec', toolParams);
   }
 
   throw new Error(`Unknown command: "${command}". Run: dassi --help`);
@@ -310,42 +356,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' +
-  '  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' +
-  '  --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.
@@ -417,9 +428,18 @@ export async function run() {
     process.exit(1);
   }
 
-  const { action, params, session, json } = parsed;
+  const { action, params, session, json, profile } = parsed;
   handleImmediateAction(action);
 
+  if (action === 'launch') {
+    await handleLaunch(params, { spawn: child_process.spawn, ensureDaemonRunning, getSocketPath, sendCommand, appDir: getAppDir(), launchesFile: getLaunchesFile() });
+    return;
+  }
+  if (action === 'launch_stop') {
+    handleStop(params, { launchesFile: getLaunchesFile() });
+    return;
+  }
+
   const socketPath = await ensureDaemonReady(session);
 
   const id = `cli_${Date.now()}`;
@@ -429,13 +449,16 @@ export async function run() {
     (action === 'run' || action === 'tool_exec') &&
     (params.groupId !== undefined || params.groupTitle !== undefined)
   ) {
-    const allOk = await runWithGroupExpansion(socketPath, action, params, json, sendCommand, formatResponse);
+    const allOk = await runWithGroupExpansion(socketPath, action, params, json, sendCommand, formatResponse, profile);
     if (!allOk) process.exit(1);
     return;
   }
 
-  // Reason: for 'raw' the user controls the full envelope — send params verbatim
-  const command = action === 'raw' ? { id, ...params } : { id, action, ...params };
+  // Reason: for 'raw' the user controls the full envelope — send params verbatim (no target injection).
+  // For all other commands, include target only when --profile/--label was given so back-compat is exact.
+  const command = action === 'raw'
+    ? { id, ...params }
+    : { id, action, ...params, ...(profile ? { target: profile } : {}) };
   const response = await sendCommand(socketPath, command);
 
   console.log(formatResponse(action, response, json, params));

package/format-response.mjs

@@ -95,6 +95,15 @@ function formatExportLogs(response, params) {
   }
 }
 
+/** @param {{ success: boolean; data?: unknown }} response */
+function formatListProfiles(response) {
+  const rows = /** @type {Array<{label:string;port:number}>} */ (response.data ?? []);
+  if (rows.length === 0) return '(no profiles connected)';
+  const header = 'PROFILE                          PORT';
+  const body = rows.map((r) => `${String(r.label).padEnd(32)} ${r.port}`);
+  return [header, ...body].join('\n');
+}
+
 /** @param {{ success: boolean; data?: unknown }} response */
 function formatStatus(response) {
   const d = /** @type {{ authenticated?: boolean; email?: string | null }} */ (response.data ?? {});
@@ -114,6 +123,7 @@ const FORMATTERS = {
   panel_screenshot: (r, p, a) => formatToolExec(r, p, a),
   export_logs: (r, p, _a) => formatExportLogs(r, p),
   status: (r, _p, _a) => formatStatus(r),
+  list_profiles: (r, _p, _a) => formatListProfiles(r),
 };
 
 /**

package/group-expansion.mjs

@@ -39,16 +39,20 @@ export function uniquifyOutputForTab(output, tabId) {
  * @param {string} socketPath  Daemon Unix socket
  * @param {{ groupId?: number; groupTitle?: string }} ref
  * @param {(socketPath: string, command: object) => Promise<{success:boolean,data?:any,error?:string}>} sendFn - send function (required, injectable for tests)
+ * @param {string | null} [target] - Profile label to route the resolving queries to (when --profile is set).
  * @returns {Promise<number[]>}  Member tab IDs (order: ascending)
  */
-export async function expandGroupToTabIds(socketPath, ref, sendFn) {
+export async function expandGroupToTabIds(socketPath, ref, sendFn, target = null) {
+  // Reason: route the group-resolving queries to the same profile the command
+  // targets, so resolution isn't ambiguous when multiple profiles are connected.
+  const targetField = target ? { target } : {};
   // Reason: pass all:true (flat, NOT nested under `params`) so --group /
   // --group-title can resolve against any Chrome tab group, not just groups
   // dassi currently has open. The daemon's dispatchToExtension does
   // `{ id, action, ...rest } = cmd` and forwards `rest` as JSON-RPC params,
   // so nesting under `params` would arrive at the extension as
   // `params.params.all` — and the filter would NOT bypass.
-  const groupsResp = await sendFn(socketPath, { id: `cli_lg_${Date.now()}`, action: 'list_groups', all: true });
+  const groupsResp = await sendFn(socketPath, { id: `cli_lg_${Date.now()}`, action: 'list_groups', all: true, ...targetField });
   if (!groupsResp.success) throw new Error(`Failed to list groups: ${groupsResp.error ?? 'unknown'}`);
   const groups = /** @type {Array<{id:number;title:string;windowId:number}>} */ (groupsResp.data ?? []);
 
@@ -70,7 +74,7 @@ export async function expandGroupToTabIds(socketPath, ref, sendFn) {
     throw new Error('expandGroupToTabIds: pass groupId or groupTitle');
   }
 
-  const tabsResp = await sendFn(socketPath, { id: `cli_lt_${Date.now()}`, action: 'list_tabs', all: true });
+  const tabsResp = await sendFn(socketPath, { id: `cli_lt_${Date.now()}`, action: 'list_tabs', all: true, ...targetField });
   if (!tabsResp.success) throw new Error(`Failed to list tabs: ${tabsResp.error ?? 'unknown'}`);
   const tabs = /** @type {Array<{tabId:number;groupId:number}>} */ (tabsResp.data ?? []);
   const memberIds = tabs.filter((t) => t.groupId === groupId).map((t) => t.tabId);
@@ -100,14 +104,16 @@ export function formatGroupJsonResults(results) {
  * @param {number} tabId
  * @param {boolean} multiTab  True when >1 tab in the expansion (triggers output uniquification)
  * @param {(socketPath: string, command: object) => Promise<{success:boolean,data?:any,error?:string}>} sendFn
+ * @param {string | null} [target] - Profile label to route the child command to (when --profile is set).
  * @returns {Promise<{tabId: number, response: {success:boolean,data?:any,error?:string}, childParams: object}>}
  */
-async function dispatchChildForTab(socketPath, action, childBase, tabId, multiTab, sendFn) {
+async function dispatchChildForTab(socketPath, action, childBase, tabId, multiTab, sendFn, target = null) {
   // Reason: uniquify _output per tab when fanning out so each file write targets a distinct path
   const perTabOutput =
     multiTab && childBase._output ? uniquifyOutputForTab(childBase._output, tabId) : childBase._output;
   const childParams = { ...childBase, tabId, ...(perTabOutput !== childBase._output ? { _output: perTabOutput } : {}) };
-  const response = await sendFn(socketPath, { id: `cli_${Date.now()}_${tabId}`, action, ...childParams });
+  // Reason: include target only when set so the fan-out routes to the chosen profile.
+  const response = await sendFn(socketPath, { id: `cli_${Date.now()}_${tabId}`, action, ...childParams, ...(target ? { target } : {}) });
   return { tabId, response, childParams };
 }
 
@@ -128,13 +134,15 @@ async function dispatchChildForTab(socketPath, action, childBase, tabId, multiTa
  * @param {boolean} json
  * @param {(socketPath: string, command: object) => Promise<{success:boolean,data?:any,error?:string}>} sendFn
  * @param {(action: string, response: object, json: boolean, params: object) => string} formatFn
+ * @param {string | null} [target] - Profile label to route every query/child command to (when --profile is set).
  * @returns {Promise<boolean>}  true if all child calls succeeded, false if any failed
  */
-export async function runWithGroupExpansion(socketPath, action, params, json, sendFn, formatFn) {
+export async function runWithGroupExpansion(socketPath, action, params, json, sendFn, formatFn, target = null) {
   const tabIds = await expandGroupToTabIds(
     socketPath,
     { groupId: params.groupId, groupTitle: params.groupTitle },
     sendFn,
+    target,
   );
   // Reason: always on stderr so it doesn't pollute JSON output on stdout
   console.error(`Running on ${tabIds.length} tab${tabIds.length === 1 ? '' : 's'}: ${tabIds.join(', ')}`);
@@ -146,7 +154,7 @@ export async function runWithGroupExpansion(socketPath, action, params, json, se
   let allOk = true;
 
   for (const tabId of tabIds) {
-    const { response, childParams } = await dispatchChildForTab(socketPath, action, childBase, tabId, multiTab, sendFn);
+    const { response, childParams } = await dispatchChildForTab(socketPath, action, childBase, tabId, multiTab, sendFn, target);
     if (!response.success) allOk = false;
     if (json) {
       // Reason: collect for a single JSON array emission after the loop

package/help-text.mjs

@@ -0,0 +1,46 @@
+/**
+ * `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>]\n' +
+  '                                  Open Chrome with a dev dist loaded\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,273 @@
+/**
+ * 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 * as path from 'path';
+import { DASSI_EXTENSION_ID, getDaemonBridgePort, DEFAULT_BRIDGE_PORT, isDaemonRunning as isDaemonRunningImpl } from './dassi-shared.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 command-line args that load the dev dist into an isolated
+ * profile and open the options page to seed the profile label.
+ * @param {{ distPath: string; profileDir: string; label: string; bridgePort: number }} opts
+ *   bridgePort: the daemon port to seed (use getDaemonBridgePort() — no default
+ *   here, to avoid duplicating its canonical 18790).
+ * @returns {string[]} Chrome args (the final entry is the seed URL to open).
+ */
+export function buildLaunchArgs({ distPath, profileDir, label, bridgePort }) {
+  // Reason: seed BOTH label and bridgePort — the options page persists them so the
+  // launched extension connects to the daemon's actual port (matters when
+  // DASSI_BRIDGE_PORT moves the daemon off the default 18790; without it the
+  // extension falls back to 18790 and the isolated-port launch times out).
+  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}`,
+  ];
+}
+
+/**
+ * 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;
+  }
+}
+
+/**
+ * Launch Chrome (detached) with the dev dist loaded under a dedicated profile,
+ * wait for the extension to register under `label`, then record it.
+ * @param {{label:string; dist:string|null; chrome:string|null; profileDir:string|null; timeoutMs:number}} opts
+ * @param {{ spawn: Function; ensureDaemonRunning: Function; getSocketPath: Function; sendCommand: Function;
+ *          appDir: string; launchesFile: string;
+ *          log?: Function; error?: Function; exit?: Function; mkdir?: Function }} deps
+ */
+export async function handleLaunch(opts, deps) {
+  const {
+    spawn, ensureDaemonRunning, getSocketPath, sendCommand, appDir, launchesFile,
+    isDaemonRunning = isDaemonRunningImpl,
+    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;
+
+  // 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 rather than seed a port the extension can't reach (a silent timeout).
+  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.`);
+    return exit(1);
+  }
+
+  // Reason: only SPAWN the daemon (non-blocking). NOT ensureDaemonReady — that waits
+  // for the ready file the daemon writes only after an extension connects; none is yet.
+  ensureDaemonRunning('default');
+  const socketPath = getSocketPath('default');
+
+  // Reason: a same-label Chrome already running makes waitForProfile falsely succeed
+  // (a second launch with the same --user-data-dir hands off to the existing process).
+  if (await isLabelConnected({ sendCommand, socketPath, label: opts.label })) {
+    error(`❌  A profile labelled "${opts.label}" is already connected. Run \`dassi launch --stop ${opts.label}\` first, or use a different --label.`);
+    return exit(1);
+  }
+
+  const pid = await spawnAndConnect({ spawn, kill, sendCommand, socketPath, chromePath, distPath, profileDir, bridgePort, opts, error });
+  if (pid === null) return exit(1);
+
+  recordLaunch(launchesFile, { label: opts.label, pid, profileDir, startedAt: Date.now() });
+  log(`✅  launched "${opts.label}" (pid ${pid}) — drive it with: dassi run "…" --profile ${opts.label}`);
+}
+
+/**
+ * Spawn the detached Chrome and wait for `label` to register on the daemon.
+ * @returns {Promise<number|null>} the Chrome pid on success, or null (after
+ *   killing any orphan + logging) on a failed spawn or connect-timeout.
+ */
+async function spawnAndConnect({ spawn, kill, sendCommand, socketPath, chromePath, distPath, profileDir, bridgePort, opts, error }) {
+  // Reason: bridgePort (the daemon's actual port) is seeded so the launched extension
+  // connects to it — the daemon inherits DASSI_BRIDGE_PORT via ensureDaemonRunning.
+  const child = spawn(chromePath, buildLaunchArgs({ distPath, profileDir, label: opts.label, bridgePort }), {
+    detached: true,
+    stdio: 'ignore',
+  });
+  // Reason: a missing/invalid binary leaves pid undefined and emits 'error' async —
+  // swallow the event (else it throws) and fast-fail on the synchronous pid check.
+  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;
+
+  // Reason: kill the detached Chrome we started so a connect-timeout never orphans a browser.
+  try { kill(child.pid); } catch { /* already gone */ }
+  error(`❌  "${opts.label}" did not connect within ${opts.timeoutMs}ms (Chrome already using ${profileDir}, bridge disabled, or dist too old).`);
+  return null;
+}
+
+/**
+ * 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.1.2",
+  "version": "0.3.0",
   "description": "CLI for the Dassi Chrome extension — run browser automation from the terminal",
   "type": "module",
   "bin": {
@@ -13,6 +13,8 @@
     "tool-commands.mjs",
     "format-response.mjs",
     "group-expansion.mjs",
+    "launch.mjs",
+    "help-text.mjs",
     ".claude-plugin/",
     "skills/",
     "README.md"
@@ -37,6 +39,11 @@
   "scripts": {
     "test": "vitest run"
   },
-  "keywords": ["dassi", "cli", "browser-automation", "chrome-extension"],
+  "keywords": [
+    "dassi",
+    "cli",
+    "browser-automation",
+    "chrome-extension"
+  ],
   "license": "MIT"
 }