feat(chrome): ChromeLauncher owns Chrome lifecycle + authenticated-profile mode (#10)

Consolidate Chrome responsibility that was scattered across DynamicCommand,
CdpDriver and Recorder behind ChromeLauncher and a new ChromeSession bridge,
add a persistent-profile launch so a real logged-in session can be traced, and
switch the journey to always open a fresh tab in the target window instead of
reusing an existing one.

- ChromeSession (new): the bridge between a held browser (launched or attached)
  and the CDP transport. Holds the port, knows whether it OWNS the process (so
  teardown is real for a throwaway and a no-op for an attached window), and
  exposes Chrome target discovery (pageTargets/openBlankTab). The raw websocket
  connect stays in CdpDriver (shared with Node).
- ChromeLauncher.acquire(spec): one entry point that decides attach vs throwaway
  headless vs persistent profile and returns a ChromeSession. Spawn is
  parametrized for headless/headed and ephemeral/persistent profiles; a
  user-owned profile dir is never deleted on teardown. DynamicCommand's
  launch-vs-attach branch collapses into a single acquire() + session.kill().
- Authenticated sessions: new --chrome-profile <dir> (headed, persistent
  --user-data-dir, reuses saved logins/cookies) and --headed flags, with
  validation. Recorder's inline /json fetch now goes through the bridge too.
- No tab targeting: JourneyRunner always opens its OWN tab and drives that, so
  an attached real window keeps its existing tabs untouched while our tab rides
  the same profile (same logins). Removed the now-dead urlMatch tab matcher from
  the Chrome path and ChromeSession.

Verified: build clean, 47/48 unit tests pass (1 Postgres skip); end-to-end a
--chrome-profile run traces the React bug and the profile persists across two
separate CLI invocations; an attach run opens one fresh tab and leaves all
pre-existing tabs intact.

Co-authored-by: Claude Opus 4.8 (1M context) <noreply@anthropic.com>

Author: burrows99

skills/trace/SKILL.md

@@ -7,7 +7,7 @@ allowed-tools: Bash(node:*), Bash(trace-cli:*), Read
 # trace-cli — unified execution tracer for Node & Chrome
 
 - Attaches to a running debug target, sets breakpoints, fires a trigger, prints the full execution trace in one shot. One engine, one protocol driver — **CDP** for Node and Chrome. You read the trace; you never drive the debugger by hand.
-- **Chrome can auto-launch:** `--chrome <port>` attaches to a browser you started (a real, logged-in session); bare `--chrome` (no port) launches a throwaway headless Chrome, traces, records, and tears it down — a frontend trace needs only the app running.
+- **Chrome can auto-launch:** `--chrome <port>` attaches to a browser you started (a real, logged-in session); bare `--chrome` (no port) launches a throwaway headless Chrome, traces, records, and tears it down — a frontend trace needs only the app running. `--chrome-profile <dir>` launches a headed browser on a persistent profile, so a saved-login session is reused without a hand-started browser (use a copy of your profile; the dir is never deleted on teardown).
 - **Static analysis needs no running app:** `trace-cli graph` is a call graph (flow tree) via **LSP call hierarchy** — map what a route/function calls, and find breakpoint coordinates before a runtime trace. TS/JS bundled; other languages via `--server` (`gopls` · `pyright --stdio` · `rust-analyzer` · `clangd`, must expose `callHierarchyProvider`). The other analyses are `deps`/`complexity`/`symbols` — run `trace-cli --help`.
 
 ## Invoking (do this first)

src/cli/Cli.ts

@@ -32,10 +32,15 @@ const parseIntArg = (value: string) => parseInt(value, 10);
 const collect = (value: string, accumulator: string[]) => { accumulator.push(value); return accumulator; };
 const usage = (message: string): never => { process.stderr.write(`trace-cli: ${message}\n`); process.exit(2); };
 
-function pickTarget(options: any): { target: DynamicTargetKind; port: number; launch: boolean } {
-  if (options.chrome != null) {
-    const launch = options.chrome === true; // bare `--chrome` (no port) → launch a throwaway headless Chrome
-    return { target: TargetKind.Chrome, port: launch ? 0 : parseIntArg(options.chrome), launch };
+interface PickedTarget { target: DynamicTargetKind; port: number; launch: boolean; profileDir?: string; headed?: boolean; }
+function pickTarget(options: any): PickedTarget {
+  // A named --chrome-profile selects Chrome and implies launching it (a profile can only be grafted onto a
+  // browser we spawn), even without --chrome; bare --chrome (no port) launches a throwaway, a port attaches.
+  if (options.chrome != null || options.chromeProfile) {
+    const profileDir: string | undefined = options.chromeProfile || undefined;
+    const launch = profileDir != null || options.chrome === true;
+    const headed = options.headed === true || profileDir != null; // a logged-in profile is shown so you can watch/intervene
+    return { target: TargetKind.Chrome, port: launch ? 0 : parseIntArg(options.chrome), launch, ...(profileDir ? { profileDir } : {}), headed };
   }
   return { target: TargetKind.Node, port: options.node === undefined || options.node === true ? DEFAULT_NODE_PORT : parseIntArg(options.node), launch: false };
 }
@@ -101,8 +106,12 @@ export class Cli {
 
   async #runDynamic(options: any): Promise<void> {
     if (options.chrome != null && options.node != null) usage("pick one target: --node or --chrome, not both");
+    if (options.chromeProfile && options.node != null) usage("--chrome-profile is a chrome option — don't combine it with --node");
+    // --chrome-profile launches a browser on that profile; an explicit --chrome <port> means attach to a running one.
+    if (options.chromeProfile && typeof options.chrome === "string") usage("pick one: --chrome-profile launches a logged-in browser, or --chrome <port> attaches to a running one — not both");
+    if (options.headed && !(options.chrome != null || options.chromeProfile)) usage("--headed only applies when launching Chrome (use with --chrome or --chrome-profile)");
     if (options.concise && options.detailed) usage("pick one envelope verbosity: --concise or --detailed, not both");
-    const { target, port, launch } = pickTarget(options);
+    const { target, port, launch, profileDir, headed } = pickTarget(options);
     const isChrome = target === TargetKind.Chrome;
     if (!options.breakpoint.length) usage("run needs at least one --breakpoint (file:line or file@substring)");
     // Chrome trigger = an ordered UI journey; --url is shorthand for a leading `goto:`. Node trigger = a curl.
@@ -112,7 +121,7 @@ export class Cli {
     if (!isChrome && options.step.length) usage("--step is a chrome-only trigger (node uses --curl)");
     if (!isChrome && !options.curl) usage(`${target} target needs --curl`);
 
-    const input = new DynamicInput({ target, port, launch, breakpoints: options.breakpoint, exprs: options.expression, steps, curl: options.curl });
+    const input = new DynamicInput({ target, port, launch, profileDir, headed, breakpoints: options.breakpoint, exprs: options.expression, steps, curl: options.curl });
     const badInput = input.validate();
     if (badInput.length) usage(`invalid input — ${badInput.join("; ")}`);
 
@@ -143,12 +152,12 @@ export class Cli {
     let trace: Trace;
     try {
       ({ trace } = await this.#dynamic.run({
-        target, port, launch,
+        target, port, launch, profileDir, headed,
         breakpoints: options.breakpoint, exprs: options.expression,
         steps, curl: options.curl,
         root: options.root, maxHits: options.maxHits,
         recordOut: options.output,
-        args: { target, ...(launch ? { launch: true } : { port }), breakpoints: options.breakpoint, ...(options.root ? { root: options.root } : {}), ...(options.maxHits ? { maxHits: options.maxHits } : {}), ...(steps.length ? { steps: steps.map(redactStep) } : {}), ...(options.curl ? { curl: options.curl } : {}) },
+        args: { target, ...(launch ? { launch: true } : { port }), ...(profileDir ? { profile: profileDir } : {}), ...(headed && !profileDir ? { headed: true } : {}), breakpoints: options.breakpoint, ...(options.root ? { root: options.root } : {}), ...(options.maxHits ? { maxHits: options.maxHits } : {}), ...(steps.length ? { steps: steps.map(redactStep) } : {}), ...(options.curl ? { curl: options.curl } : {}) },
         ...(emitToCollector ? { onProgress: (intermediateTrace: Trace) => emitToCollector(intermediateTrace.toJSON()) } : {}),
       }));
     } catch (error) {
@@ -260,6 +269,8 @@ export class Cli {
       .description("breakpoints + a trigger → a full execution trace. Breakpoints are non-pausing logpoints: each hit ships its stack + in-scope locals + exprs without halting the VM, so the app runs at full speed. Node (CDP): a --curl trigger. Chrome (CDP): a scripted UI journey (--url/--step) recorded as a screen + trace-panel replay — debug and video together.")
       .option("--node [port]", `Node --inspect target (default; port ${DEFAULT_NODE_PORT})`)
       .option("--chrome [port]", "Chrome target: a running browser's --remote-debugging-port, or omit the port to launch a throwaway headless Chrome")
+      .option("--chrome-profile <dir>", "Chrome: launch a (headed) browser on this persistent --user-data-dir so saved logins/cookies carry over — trace a real, authenticated session. Use a COPY of your profile (Chrome 136+ blocks remote-debugging on the default dir; one process per dir). Implies launching, so don't combine with --chrome <port>.")
+      .option("--headed", "Chrome: launch the browser visibly instead of headless (applies to --chrome / --chrome-profile launch modes; implied by --chrome-profile)")
       .option("--breakpoint <file:line>", "breakpoint, repeatable: file:line or file@substring (non-pausing; in-scope locals are captured automatically)", collect, [])
       .option("--expression <js>", "extra expression captured at every hit, repeatable — for computed/derived values beyond the auto-captured locals (e.g. user.id, cart.length)", collect, [])
       .option("--root <dir>", "project root for resolving --breakpoint file paths and source maps (default: cwd) — needed when a file@substring breakpoint or a built app's sources live outside cwd")

src/cli/CommandInputs.ts

@@ -48,6 +48,8 @@ export class DynamicInput {
   // In Chrome launch mode the port isn't known until the browser is spawned, so only range-check a real port.
   @ValidateIf((input) => !input.launch) @IsInt() @Min(1) @Max(MAX_PORT) port: number;
   @IsOptional() @IsBoolean() launch?: boolean;
+  @IsOptional() @IsString() @IsNotEmpty() profileDir?: string; // chrome: persistent --user-data-dir (a logged-in profile)
+  @IsOptional() @IsBoolean() headed?: boolean;                 // chrome: launch the browser visibly
   @IsArray() @ArrayNotEmpty() @IsString({ each: true }) breakpoints: string[];
   @IsArray() @IsString({ each: true }) exprs: string[];
   @IsOptional() @IsArray() @IsString({ each: true }) steps?: string[]; // chrome: the ordered UI journey

src/cli/commands/DynamicCommand.ts

@@ -4,7 +4,8 @@ import { join } from "node:path";
 
 import { Tracer, type CaptureResult, type TraceOptions } from "../../engine/Tracer.js";
 import { Recorder } from "../../engine/Recorder.js";
-import { ChromeLauncher, type LaunchedChrome } from "../../engine/ChromeLauncher.js";
+import { ChromeLauncher } from "../../engine/ChromeLauncher.js";
+import { ChromeSession } from "../../engine/ChromeSession.js";
 import { Renderer } from "../../engine/Renderer.js";
 import { LineageAnalyzer } from "../../analysis/LineageAnalyzer.js";
 import { Trace, TraceData, CurlResponse } from "../../domain/Trace.js";
@@ -23,6 +24,8 @@ export type DynamicTargetKind = TargetKind;
 export interface DynamicRequest extends TraceOptions {
   target: DynamicTargetKind;
   launch?: boolean;            // chrome: spawn a throwaway headless Chrome instead of attaching to `port`
+  profileDir?: string;         // chrome: launch on a persistent --user-data-dir (a real, logged-in profile)
+  headed?: boolean;            // chrome: launch the browser visibly instead of headless
   recordOut?: string;          // explicit output path (else a temp file)
   /**
    * Live progress sink: called with a partial Trace as soon as the run starts (0 events) and again on every
@@ -63,15 +66,19 @@ export class DynamicCommand extends TraceCommand<DynamicRequest, DynamicResult>
     // The session exists in the collector the instant the run begins (0 events), then updates on every hit.
     request.onProgress?.(this.#runningTrace([], context));
 
-    // Chrome launch mode (`--chrome` with no port): spawn a throwaway headless Chrome to BE the trace target,
-    // then tear it down. Attach mode (`--chrome <port>`) uses the running browser as-is.
-    let launched: LaunchedChrome | undefined;
+    // Chrome: acquire the browser through the launcher — it decides attach (`--chrome <port>`, used as-is),
+    // throwaway headless (`--chrome` no port), or a persistent logged-in profile (`--chrome-profile`), and hands
+    // back a session whose kill() tears down only what WE launched. Node needs none of this.
+    let session: ChromeSession | undefined;
     try {
       let options: TraceOptions = {
         ...request, sessionId,
         ...(request.onProgress ? { onEvent: (events) => request.onProgress!(this.#runningTrace(events, context)) } : {}),
       };
-      if (isChrome && request.launch) { launched = await ChromeLauncher.launch(); options = { ...options, port: launched.port }; }
+      if (isChrome) {
+        session = await ChromeLauncher.acquire({ port: request.port, launch: request.launch, profileDir: request.profileDir, headed: request.headed });
+        options = { ...options, port: session.port };
+      }
 
       // Both targets go through the engine the same way: one method, one CaptureResult. Chrome layers on the
       // extra it alone supports — the screen + trace-panel recording.
@@ -88,7 +95,7 @@ export class DynamicCommand extends TraceCommand<DynamicRequest, DynamicResult>
       request.onProgress?.(this.#abortedTrace(error, context));
       throw error;
     } finally {
-      launched?.kill();
+      session?.kill();
     }
   }
 

src/engine/ChromeLauncher.ts

@@ -7,6 +7,7 @@ import { join } from "node:path";
 import { sleep } from "../shared/sleep.js";
 import { logger } from "../shared/logger.js";
 import { Code } from "../shared/codes.js";
+import { ChromeSession } from "./ChromeSession.js";
 
 const log = logger.child({ component: "chrome" });
 
@@ -34,39 +35,98 @@ function freePort(): Promise<number> {
   });
 }
 
-/** A throwaway headless Chrome: its CDP port plus a kill() that stops the process and removes its profile. */
+/** A Chrome process we launched: its CDP port plus a kill() that stops the process and (if ours) removes its profile. */
 export interface LaunchedChrome {
   port: number;
   kill(): void;
 }
 
 /**
- * ChromeLauncher — spawn a throwaway headless Chrome on a free port with a temp profile, wait until its CDP
- * endpoint answers, and hand back the port plus a kill() that also cleans the profile. One launcher, two uses:
- * the live trace target (`trace run --chrome` with no port) and the recording-video renderer — so a Chrome
- * trace is turnkey instead of requiring a hand-started browser. Attach mode (`--chrome <port>`) bypasses this
- * entirely, which is how you trace a real, already-open session.
+ * How to get a Chrome to trace against. Exactly one of three modes, picked by which fields are set:
+ * - attach: a `port` only → use a running browser's `--remote-debugging-port` as-is (a real, logged-in session).
+ * - throwaway: `launch` → spawn a headless Chrome on a fresh temp profile, traced and torn down (the default).
+ * - profile: `profileDir` → launch a (headed) Chrome on a persistent `--user-data-dir`, so saved logins/cookies
+ *   carry over — the authenticated-session path. `launch` is implied. The profile dir is the caller's; we never
+ *   delete it on teardown.
+ */
+export interface AcquireSpec {
+  port?: number;          // attach target — a running --remote-debugging-port
+  launch?: boolean;       // spawn a throwaway headless Chrome instead of attaching
+  profileDir?: string;    // persistent --user-data-dir (a real, logged-in profile); implies a launched, headed Chrome
+  headed?: boolean;       // launch visibly (default: headed when profileDir is set, else headless)
+  extraArgs?: string[];   // extra Chrome flags (e.g. the recorder's --force-device-scale-factor)
+  purpose?: string;       // log label only — distinguishes the trace target from the recorder's render Chrome
+}
+
+/** Internal spawn parameters, after {@link ChromeLauncher.acquire} has resolved a spec into a concrete launch. */
+interface SpawnSpec {
+  headless: boolean;
+  userDataDir?: string;   // explicit, caller-owned profile; when absent a throwaway temp dir is created (and removed on kill)
+  extraArgs: string[];
+  purpose: string;
+}
+
+/**
+ * ChromeLauncher — the single owner of Chrome process lifecycle: resolve the binary, spawn a browser (throwaway
+ * headless on a temp profile, or headed on a persistent logged-in one), wait until its CDP endpoint answers, and
+ * hand back a {@link ChromeSession} that bridges it to the transport. {@link acquire} is the one entry point — it
+ * decides attach vs throwaway vs profile so callers never branch on launch mode themselves; the live trace target
+ * (`trace run --chrome`) and the recorder's video renderer both come through here. Attach mode spawns nothing —
+ * that's how a real, already-open session is traced.
  */
 export class ChromeLauncher {
-  // `purpose` only labels the log line, so a launch is never mistaken for the attached trace target: the
-  // recorder spins up its own throwaway Chrome to render the trace-panel video ("video render"), which is
-  // distinct from the trace target Chrome that bare `--chrome` launches ("trace target").
-  static async launch(extraArgs: string[] = [], opts: { purpose?: string } = {}): Promise<LaunchedChrome> {
-    const purpose = opts.purpose ?? "trace target";
+  /**
+   * Resolve a spec into a {@link ChromeSession}: attach to a running browser, or launch one (throwaway, or on a
+   * persistent profile) and own its teardown. A named `profileDir` implies launching and runs headed by default,
+   * so saved logins are reused in a window you can see; a throwaway runs headless.
+   */
+  static async acquire(spec: AcquireSpec): Promise<ChromeSession> {
+    // A persistent profile only makes sense if we launch the browser ourselves — you can't graft a profile onto
+    // an already-running one — so naming a profileDir implies launch, just like bare `--chrome` does.
+    const shouldLaunch = spec.launch || spec.profileDir != null;
+    if (!shouldLaunch) {
+      if (!spec.port) throw new Error("attach mode needs a Chrome --remote-debugging-port (pass --chrome <port>)");
+      return ChromeLauncher.attach(spec.port);
+    }
+    const headed = spec.headed ?? spec.profileDir != null;
+    const launched = await ChromeLauncher.#spawn({
+      headless: !headed,
+      ...(spec.profileDir != null ? { userDataDir: spec.profileDir } : {}),
+      extraArgs: spec.extraArgs ?? [],
+      purpose: spec.purpose ?? "trace target",
+    });
+    return new ChromeSession(launched.port, launched);
+  }
+
+  /** Wrap a running browser's debug port as a non-owning session (no spawn, kill is a no-op). */
+  static attach(port: number): ChromeSession {
+    return new ChromeSession(port, null);
+  }
+
+  /** Spawn a throwaway headless Chrome (temp profile, removed on kill). The low-level handle the recorder + tests use. */
+  static launch(extraArgs: string[] = [], opts: { purpose?: string } = {}): Promise<LaunchedChrome> {
+    return ChromeLauncher.#spawn({ headless: true, extraArgs, purpose: opts.purpose ?? "trace target" });
+  }
+
+  static async #spawn(spec: SpawnSpec): Promise<LaunchedChrome> {
     const binaryPath = chromeBinary();
     if (!binaryPath) throw new Error("no Chrome found to launch (set CHROME_BIN, or pass --chrome <port> to attach to a running one)");
     const port = await freePort();
-    const profile = mkdtempSync(join(tmpdir(), "trace-chrome-profile-"));
-    const cleanup = () => { try { rmSync(profile, { recursive: true, force: true }); } catch { /* ignore */ } };
+    // A caller-supplied profileDir is the user's (their logins live there) — keep it. A temp profile is ours — sweep it.
+    const ephemeralProfile = spec.userDataDir == null;
+    const profile = spec.userDataDir ?? mkdtempSync(join(tmpdir(), "trace-chrome-profile-"));
+    const cleanup = () => { if (ephemeralProfile) { try { rmSync(profile, { recursive: true, force: true }); } catch { /* ignore */ } } };
     const chromeProcess = spawn(binaryPath, [
-      "--headless=new", `--remote-debugging-port=${port}`, `--user-data-dir=${profile}`,
-      "--no-first-run", "--no-default-browser-check", "--disable-gpu", "--hide-scrollbars",
-      ...extraArgs, "about:blank",
+      ...(spec.headless ? ["--headless=new", "--disable-gpu", "--hide-scrollbars"] : []),
+      `--remote-debugging-port=${port}`, `--user-data-dir=${profile}`,
+      "--no-first-run", "--no-default-browser-check",
+      ...spec.extraArgs, "about:blank",
     ], { stdio: "ignore" });
     chromeProcess.on("error", (error) => log.error("chrome launch failed", { code: Code.CHROME, bin: binaryPath, err: String(error) }));
 
     for (let attempt = 0; attempt < 80; attempt++) {
-      try { await (await fetch(`http://localhost:${port}/json/version`)).json(); log.info(`launched headless chrome (${purpose})`, { port, purpose });
+      try { await (await fetch(`http://localhost:${port}/json/version`)).json();
+        log.info(`launched chrome (${spec.purpose})`, { port, purpose: spec.purpose, headless: spec.headless, profile: ephemeralProfile ? "throwaway" : profile });
         return { port, kill() { try { chromeProcess.kill("SIGKILL"); } catch { /* ignore */ } cleanup(); } };
       } catch { await sleep(100); }
     }