@monoes/monobrowse 1.0.21 → 1.0.24

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@monoes/monobrowse",
-  "version": "1.0.21",
+  "version": "1.0.24",
   "description": "Native browser automation via Chrome DevTools Protocol — the engine powering monomind browse",
   "type": "module",
   "bin": {

package/src/__tests__/browse-concurrency.test.ts

@@ -18,7 +18,7 @@ import { mkdir, mkdtemp, readFile, rm, writeFile } from 'node:fs/promises';
 import { tmpdir } from 'node:os';
 import { dirname, join } from 'node:path';
 import { fileURLToPath } from 'node:url';
-import { afterEach, describe, expect, it } from 'vitest';
+import { afterEach, beforeAll, describe, expect, it } from 'vitest';
 import { CHROME_EXECUTABLES } from '../browser/types.js';
 
 const here = dirname(fileURLToPath(import.meta.url));
@@ -100,7 +100,51 @@ afterEach(async () => {
   }
 });
 
+/**
+ * Start Chrome once, outside any trial, and let it finish. A runner's first
+ * Chrome start pays for paging the binary and its libraries in and building
+ * the font cache; two of them at once in trial 1 took longer than `open`'s
+ * 10 s CDP wait on CI, while every later trial passed. `--dump-dom` exits on
+ * its own once the page loads, so this has no timeout of `open`'s to beat.
+ */
+async function warmUpChrome(): Promise<void> {
+  let found: string;
+  try {
+    found = execFileSync('which', ['google-chrome', 'chromium-browser', 'chromium'], {
+      encoding: 'utf8',
+      stdio: ['ignore', 'pipe', 'ignore'],
+    });
+  } catch (err) {
+    // `which` exits non-zero when any one name is missing; the rest still print.
+    found = String((err as { stdout?: string }).stdout ?? '');
+  }
+  const chrome = CHROME_EXECUTABLES.find((p) => existsSync(p)) ?? found.split('\n')[0];
+  if (!chrome) return;
+  const profile = await mkdtemp(join(process.env.TMPDIR ?? tmpdir(), 'monobrowse-warmup-'));
+  try {
+    await new Promise<void>((resolve) => {
+      execFile(
+        chrome,
+        [
+          '--headless=new',
+          `--user-data-dir=${profile}`,
+          '--no-first-run',
+          ...(process.env.CI ? ['--no-sandbox', '--disable-dev-shm-usage'] : []),
+          '--dump-dom',
+          'about:blank',
+        ],
+        { timeout: 60_000 },
+        () => resolve(),
+      );
+    });
+  } finally {
+    await rm(profile, { recursive: true, force: true, maxRetries: 10, retryDelay: 200 });
+  }
+}
+
 describe.skipIf(!runnable)('#318 concurrent browse sessions (real processes)', () => {
+  beforeAll(warmUpChrome, 90_000);
+
   for (const trial of [1, 2, 3, 4, 5]) {
     it(`trial ${trial}: two bare \`open\` calls each get their own browser, and each close kills only its own`, async () => {
       const root = await mkdtemp(join(process.env.TMPDIR ?? tmpdir(), 'monobrowse-318-'));
@@ -231,3 +275,64 @@ describe.skipIf(!runnable)('#318 adoption of a pre-#318 session (real processes)
     expect(await cdpAlive(legacyPort)).toBe(false);
   }, 90_000);
 });
+
+/**
+ * `--session <name>` is documented (browse-qa, browse-electron skills) as a
+ * way to drive several browsers side by side. It used to be a no-op outside
+ * `open`, where it only restored saved state and failed when none existed —
+ * AFTER launching a browser — so every later command silently acted on
+ * whichever session was newest. Real processes, because the bug is in what a
+ * later, separate CLI invocation resolves.
+ */
+describe.skipIf(!runnable)('--session named sessions (real processes)', () => {
+  beforeAll(warmUpChrome, 90_000);
+
+  it('two named sessions stay apart, a bare command never lands on them, and an unknown name fails', async () => {
+    const root = await mkdtemp(join(process.env.TMPDIR ?? tmpdir(), 'monobrowse-named-'));
+    dirs.push(root);
+    const pageA = join(root, 'a.html');
+    const pageB = join(root, 'b.html');
+    await writeFile(pageA, '<!doctype html><title>Page A</title><h1>a</h1>');
+    await writeFile(pageB, '<!doctype html><title>Page B</title><h1>b</h1>');
+
+    const openA = await runCli(['open', `file://${pageA}`, '--session', 'ref'], root, root);
+    expect(openA.code, `open ref failed: ${openA.stdout}${openA.stderr}`).toBe(0);
+    const openB = await runCli(['open', `file://${pageB}`, '--session', 'build'], root, root);
+    expect(openB.code, `open build failed: ${openB.stdout}${openB.stderr}`).toBe(0);
+    const portA = reportedPort(openA);
+    const portB = reportedPort(openB);
+    expect(portA).not.toBeNull();
+    expect(portA).not.toBe(portB);
+
+    // 'build' is the newest session, yet --session ref reaches 'ref'.
+    const titleA = await runCli(['get', 'title', '--session', 'ref'], root, root);
+    expect(titleA.code, `get title ref failed: ${titleA.stdout}${titleA.stderr}`).toBe(0);
+    expect(titleA.stdout).toContain('Page A');
+    const titleB = await runCli(['get', 'title', '--session', 'build'], root, root);
+    expect(titleB.stdout).toContain('Page B');
+
+    // Re-opening a name navigates that session's own browser.
+    const reopen = await runCli(['open', `file://${pageB}`, '--session', 'ref'], root, root);
+    expect(reopen.code, `re-open ref failed: ${reopen.stdout}${reopen.stderr}`).toBe(0);
+    expect(reportedPort(reopen)).toBe(portA);
+
+    // An unknown name is an error, not a silent fallback to the newest session.
+    const unknown = await runCli(['get', 'title', '--session', 'nope'], root, root);
+    expect(unknown.code).not.toBe(0);
+    expect(`${unknown.stdout}${unknown.stderr}`).toMatch(/No live browse session named "nope"/);
+
+    // A bare command starts its own browser instead of joining a named one.
+    const bare = await runCli(['get', 'title'], root, root);
+    expect(bare.code, `bare get title failed: ${bare.stdout}${bare.stderr}`).toBe(0);
+    expect(bare.stdout).not.toContain('Page');
+
+    // close --session ends exactly that session.
+    const closeA = await runCli(['close', '--session', 'ref'], root, root);
+    expect(closeA.code, `close ref failed: ${closeA.stdout}${closeA.stderr}`).toBe(0);
+    expect(await cdpAlive(portA!)).toBe(false);
+    expect(await cdpAlive(portB!)).toBe(true);
+    await runCli(['close', '--session', 'build'], root, root);
+    expect(await cdpAlive(portB!)).toBe(false);
+    await runCli(['close'], root, root);
+  }, 120_000);
+});

package/src/__tests__/cli-version.test.ts

@@ -0,0 +1,50 @@
+/**
+ * `monobrowse --version` crashed instead of printing a version. (#320)
+ *
+ * `src/cli.ts` read the manifest with `_require('../package.json')`. That path
+ * is right for the SOURCE file — `src/cli.ts` sits one level under the package
+ * root — and wrong for the only file that ever runs it. The package compiles
+ * with `rootDir: "."`, so `src/cli.ts` emits to `dist/src/cli.js`, and
+ * `createRequire(import.meta.url)` resolves relative to THAT file: `../` is
+ * `dist/`, which holds no package.json. Every invocation of the standalone
+ * binary died with `Cannot find module '../package.json'`, in the repo and
+ * from a clean install alike.
+ *
+ * WHY THIS IS A SUBPROCESS TEST. The bug lives entirely in the emitted file's
+ * position on disk. Importing anything from `src/` re-resolves the path from
+ * the source tree, where the broken version was already correct — an in-process
+ * test would have passed against the bug. Only spawning the built `dist/src/
+ * cli.js`, the exact file `bin.monobrowse` points at, can observe it.
+ */
+
+import { execFileSync } from 'node:child_process';
+import { existsSync, readFileSync } from 'node:fs';
+import { dirname, join } from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { describe, expect, it } from 'vitest';
+
+const here = dirname(fileURLToPath(import.meta.url));
+const pkgRoot = join(here, '..', '..');
+const distCli = join(pkgRoot, 'dist', 'src', 'cli.js');
+const hasBuild = existsSync(distCli);
+
+describe.skipIf(!hasBuild)('the built monobrowse binary reports its version', () => {
+  const declared = JSON.parse(readFileSync(join(pkgRoot, 'package.json'), 'utf8'))
+    .version as string;
+
+  for (const flag of ['--version', '-V']) {
+    it(`\`monobrowse ${flag}\` exits 0 and prints the package version`, () => {
+      // THE BUG: this threw — exit 1, `✗ Cannot find module '../package.json'`.
+      const out = execFileSync('node', [distCli, flag], { encoding: 'utf8', stdio: 'pipe' });
+
+      expect(out.trim()).toBe(declared);
+      expect(out.trim()).toMatch(/^\d+\.\d+\.\d+/);
+    }, 15_000);
+  }
+});
+
+describe.skipIf(hasBuild)('monobrowse --version subprocess test', () => {
+  it('is skipped because dist/ is not built (run `npm run build`)', () => {
+    expect(hasBuild).toBe(false);
+  });
+});

package/src/__tests__/session-discovery.test.ts

@@ -30,8 +30,14 @@ afterEach(async () => {
 async function load() {
   vi.resetModules();
   const store = await import('../browser/ref-cache.js');
-  const { resolveLiveSession, adoptLegacySession, pinnedPort, applySessionPortFlag, session } =
-    await import('../cli/session.js');
+  const {
+    resolveLiveSession,
+    adoptLegacySession,
+    pinnedPort,
+    applySessionPortFlag,
+    applySessionNameFlag,
+    session,
+  } = await import('../cli/session.js');
   // The slice of the browser namespace resolveLiveSession uses.
   const browser = {
     listSessionRecords: store.listSessionRecords,
@@ -49,6 +55,7 @@ async function load() {
     adoptLegacySession,
     pinnedPort,
     applySessionPortFlag,
+    applySessionNameFlag,
     session,
   };
 }
@@ -257,3 +264,106 @@ describe('#318 --port session selector', () => {
     expect(session.port).toBe(41111);
   });
 });
+
+describe('--session names a live session', () => {
+  /** Record sessions oldest → newest, so newest-first order is deterministic. */
+  async function recordInOrder(
+    store: Awaited<ReturnType<typeof load>>['store'],
+    ...records: Array<{ port: number; name?: string }>
+  ) {
+    const now = Date.now();
+    const clock = vi.spyOn(Date, 'now');
+    for (const [i, r] of records.entries()) {
+      clock.mockReturnValue(now - (records.length - i) * 1_000);
+      await store.saveSessionRecord(r.port, { pid: 10 + i, name: r.name });
+    }
+    clock.mockRestore();
+  }
+
+  it('the record keeps its name', async () => {
+    const { store } = await load();
+    await store.saveSessionRecord(41111, { pid: 11, name: 'ref' });
+    expect((await store.loadSessionRecord(41111))?.name).toBe('ref');
+  });
+
+  it('resolves the live session with that name, not the newest one', async () => {
+    const { store, browser, resolveLiveSession } = await load();
+    await recordInOrder(
+      store,
+      { port: 41111, name: 'ref' },
+      { port: 42222, name: 'build' },
+      { port: 43333 },
+    );
+    onlyLive(41111, 42222, 43333);
+
+    expect((await resolveLiveSession(browser, { name: 'ref' }))?.port).toBe(41111);
+    expect((await resolveLiveSession(browser, { name: 'build' }))?.port).toBe(42222);
+  });
+
+  it('an unknown name resolves to none instead of falling back to another session', async () => {
+    const { store, browser, resolveLiveSession } = await load();
+    await recordInOrder(store, { port: 41111 }, { port: 42222, name: 'build' });
+    onlyLive(41111, 42222);
+
+    expect(await resolveLiveSession(browser, { name: 'ref' })).toBeNull();
+  });
+
+  it('a command with no name never lands on a named session', async () => {
+    const { store, browser, resolveLiveSession } = await load();
+    await recordInOrder(store, { port: 41111 }, { port: 42222, name: 'ref' });
+    onlyLive(41111, 42222);
+
+    expect((await resolveLiveSession(browser))?.port).toBe(41111);
+  });
+
+  it('a dead named session is dropped, and the name resolves to none', async () => {
+    const { store, browser, resolveLiveSession } = await load();
+    await recordInOrder(store, { port: 41111, name: 'ref' });
+    onlyLive();
+
+    expect(await resolveLiveSession(browser, { name: 'ref' })).toBeNull();
+    expect(await store.loadSessionRecord(41111)).toBeNull();
+  });
+
+  // Regression: a command whose flags never set `session.name` (e.g.
+  // `snapshot -s <name>` — `-s` is `--selector` on snapshot, not
+  // `--session`, see withSessionSelector in cli/commands.ts) used to find
+  // NO live session at all once the only live session was named, so
+  // ensureConnected silently launched a brand-new, unrelated headless
+  // Chrome — its blank "New Tab" is what a following snapshot showed
+  // instead of the page the named session had actually opened. With only
+  // one live session, named or not, a nameless lookup must still resolve to
+  // it: there is nothing else it could mean.
+  it('a command with no name resolves the sole live session even if it is named', async () => {
+    const { store, browser, resolveLiveSession } = await load();
+    await recordInOrder(store, { port: 41111, name: 'ctrl' });
+    onlyLive(41111);
+
+    expect((await resolveLiveSession(browser))?.port).toBe(41111);
+  });
+
+  // But guessing between two DIFFERENT named sessions would reintroduce the
+  // exact cross-session bleed #318 fixed — refuse instead of picking one.
+  it('a command with no name refuses to guess between two live named sessions', async () => {
+    const { store, browser, resolveLiveSession } = await load();
+    await recordInOrder(store, { port: 41111, name: 'alpha' }, { port: 42222, name: 'beta' });
+    onlyLive(41111, 42222);
+
+    expect(await resolveLiveSession(browser)).toBeNull();
+  });
+
+  it('--session sets the process session name; a missing flag leaves it alone', async () => {
+    const { applySessionNameFlag, session } = await load();
+    applySessionNameFlag({ _: [], session: 'ref' });
+    expect(session.name).toBe('ref');
+    applySessionNameFlag({ _: [] });
+    expect(session.name).toBe('ref');
+  });
+
+  it('rejects a session name that is not a plain identifier', async () => {
+    const { applySessionNameFlag } = await load();
+    for (const bad of ['', '../x', 'a b', 'x'.repeat(65)]) {
+      expect(() => applySessionNameFlag({ _: [], session: bad })).toThrow(/Invalid session name/);
+    }
+  });
+});

package/src/browser/ref-cache.ts

@@ -119,8 +119,14 @@ export interface SessionRecord {
   pid?: number;
   userDataDir?: string;
   savedAt?: number;
+  /** Set by `--session <name>`: only commands naming it resolve this session,
+   *  and commands naming none never land on it. */
+  name?: string;
 }
 
+/** A `--session` name: a plain identifier, safe as a label and in messages. */
+export const SESSION_NAME_RE = /^[A-Za-z0-9._-]{1,64}$/;
+
 /**
  * Record a browse session under its own port, so concurrent sessions in the
  * same working directory coexist instead of overwriting one shared handle.
@@ -132,7 +138,13 @@ export interface SessionRecord {
  */
 export async function saveSessionRecord(
   port: number,
-  opts?: { launched?: boolean; pid?: number; userDataDir?: string; savedAt?: number },
+  opts?: {
+    launched?: boolean;
+    pid?: number;
+    userDataDir?: string;
+    savedAt?: number;
+    name?: string;
+  },
 ): Promise<void> {
   try {
     await mkdir(SESSIONS_DIR, { recursive: true });
@@ -150,6 +162,7 @@ export async function saveSessionRecord(
         pid: opts?.pid,
         userDataDir: opts?.userDataDir,
         savedAt: opts?.savedAt ?? Date.now(),
+        name: opts?.name,
       }),
     );
   } catch {
@@ -235,6 +248,7 @@ function parseSessionRecord(raw: string): SessionRecord | null {
     pid?: unknown;
     userDataDir?: unknown;
     savedAt?: unknown;
+    name?: unknown;
   };
   if (
     typeof data.port !== 'number' ||
@@ -253,5 +267,6 @@ function parseSessionRecord(raw: string): SessionRecord | null {
         : undefined,
     userDataDir: typeof data.userDataDir === 'string' ? data.userDataDir : undefined,
     savedAt: typeof data.savedAt === 'number' ? data.savedAt : undefined,
+    name: typeof data.name === 'string' && SESSION_NAME_RE.test(data.name) ? data.name : undefined,
   };
 }

package/src/cli/attention-wall.ts

@@ -0,0 +1,202 @@
+/**
+ * Login / CAPTCHA walls — how `open` notices one, and the round trip to a
+ * visible browser window that lets a person get past it before the session
+ * carries on headless with the cookies and localStorage they earned.
+ *
+ * Split out of session.ts, which keeps the session runtime itself.
+ */
+
+import { randomUUID } from 'node:crypto';
+import { tmpdir } from 'node:os';
+import { join } from 'node:path';
+import type { CdpClient } from '../index.js';
+import { output } from './output.js';
+import { getBrowser, session } from './session.js';
+
+// URL patterns that signal an unambiguous login/auth wall.
+// Excludes 'auth', 'oauth', 'sso', 'saml' — their callback/ACS/token paths
+// (/auth/callback, /sso/callback, /saml/acs) are completion endpoints, not walls.
+// DOM detection (password field, CAPTCHA widgets) handles SSO/SAML login pages.
+const ATTENTION_URL_RE =
+  /\/(login|log-in|signin|sign-in|captcha|mfa|2fa|account\/login|accounts\/login|session\/new|users\/sign_in)(?:[/?#]|$)/i;
+
+export async function detectAttentionNeeded(
+  client: CdpClient,
+  sessionId: string,
+  url: string,
+): Promise<'login' | 'captcha' | null> {
+  if (ATTENTION_URL_RE.test(url)) return 'login';
+  try {
+    const hasPassword = await client
+      .send<{ result: { value: boolean } }>(
+        'Runtime.evaluate',
+        {
+          expression: '!!document.querySelector("input[type=password]")',
+          returnByValue: true,
+        },
+        sessionId,
+      )
+      .then((r) => r.result?.value === true)
+      .catch(() => false);
+    if (hasPassword) return 'login';
+
+    const hasCaptcha = await client
+      .send<{ result: { value: boolean } }>(
+        'Runtime.evaluate',
+        {
+          expression:
+            '!!(document.querySelector("iframe[src*=recaptcha]") || document.querySelector("iframe[src*=hcaptcha]") || document.querySelector(".g-recaptcha") || document.querySelector(".h-captcha") || document.querySelector("[data-sitekey]"))',
+          returnByValue: true,
+        },
+        sessionId,
+      )
+      .then((r) => r.result?.value === true)
+      .catch(() => false);
+    if (hasCaptcha) return 'captcha';
+  } catch {
+    /* ignore CDP errors */
+  }
+  return null;
+}
+
+export function waitForEnter(): Promise<void> {
+  if (!process.stdin.isTTY) {
+    // Non-interactive context (MCP server, piped input, CI) — cannot safely read stdin.
+    // Auto-continue after a short grace period so automation isn't blocked.
+    output.printWarning(
+      'Non-interactive mode: auto-continuing in 30s. Switch to headed manually if needed.',
+    );
+    return new Promise((resolve) => setTimeout(resolve, 30_000));
+  }
+  return new Promise((resolve) => {
+    process.stdin.resume();
+    process.stdin.setEncoding('utf8');
+    const onData = () => {
+      process.stdin.pause();
+      process.stdin.off('data', onData);
+      resolve();
+    };
+    process.stdin.once('data', onData);
+  });
+}
+
+export async function switchToHeaded(url: string, port: number): Promise<void> {
+  const browser = await getBrowser();
+
+  // Snapshot cookies from current headless session before closing
+  let savedCookies: unknown[] = [];
+  if (session.client && session.sessionId) {
+    try {
+      savedCookies = await browser.getCookies(session.client, session.sessionId);
+    } catch {
+      /* ignore */
+    }
+    browser.teardownRouteInterception(session.sessionId);
+    browser.stopRequestCapture(session.sessionId);
+    browser.teardownDialogHandling(session.sessionId);
+    browser.teardownConsoleCapture(session.sessionId);
+    session.client.close();
+    session.client = null;
+    session.sessionId = '';
+    session.parentSessionId = '';
+    session.targetId = '';
+  }
+
+  // Kernel-assigned free port and a profile of its own, so this temporary
+  // headed window cannot collide with any other session (#318) — a
+  // neighbouring port (port + 10) could well be another session's.
+  let headedPort = 0;
+  try {
+    headedPort = await browser.launchBrowser({
+      port: 0,
+      headless: false,
+      userDataDir: join(
+        tmpdir(),
+        `monomind-browse-headed-${process.pid}-${randomUUID().slice(0, 8)}`,
+      ),
+    });
+  } catch (err) {
+    // Headed launch failed (no display, locked down env). Restore headless and rethrow.
+    session.port = await browser.launchBrowser({ port, headless: true });
+    const fallback = await browser.connectToTarget(session.port);
+    session.client = fallback.client;
+    session.sessionId = fallback.sessionId;
+    session.targetId = fallback.target.id;
+    session.refs = new Map();
+    throw new Error(
+      `Cannot open headed browser: ${err instanceof Error ? err.message : String(err)}`,
+    );
+  }
+  const conn = await browser.connectToTarget(headedPort);
+  session.client = conn.client;
+  session.sessionId = conn.sessionId;
+  session.targetId = conn.target.id;
+  session.refs = new Map();
+
+  if (savedCookies.length) {
+    try {
+      await browser.setCookies(
+        session.client,
+        session.sessionId,
+        savedCookies as Parameters<typeof browser.setCookies>[2],
+      );
+    } catch {
+      /* ignore */
+    }
+  }
+  await browser.openUrl(session.client, session.sessionId, url);
+
+  output.printInfo(
+    'Browser window opened. Complete the required action (login / CAPTCHA), then press Enter to continue in headless mode...',
+  );
+  await waitForEnter();
+
+  // Capture post-auth cookies
+  const authCookies = await browser
+    .getCookies(session.client, session.sessionId)
+    .catch(() => [] as unknown[]);
+  const authLocalStorage = await browser
+    .getLocalStorage(session.client, session.sessionId)
+    .catch(() => ({}) as Record<string, string>);
+
+  // Close headed session — actually terminate the underlying Chrome process
+  // (Browser.close CDP command, PID-kill fallback), not just our CDP client
+  // connection, so the visible authenticated window doesn't linger forever.
+  browser.teardownRouteInterception(session.sessionId);
+  browser.stopRequestCapture(session.sessionId);
+  browser.teardownDialogHandling(session.sessionId);
+  browser.teardownConsoleCapture(session.sessionId);
+  await browser.closeBrowser(session.client, headedPort);
+  session.client.close();
+  session.client = null;
+  session.sessionId = '';
+  session.parentSessionId = '';
+  session.targetId = '';
+
+  // Relaunch headless and restore session
+  session.port = await browser.launchBrowser({ port, headless: true });
+  const headlessConn = await browser.connectToTarget(session.port);
+  session.client = headlessConn.client;
+  session.sessionId = headlessConn.sessionId;
+  session.targetId = headlessConn.target.id;
+  session.refs = new Map();
+
+  if (authCookies.length) {
+    try {
+      await browser.setCookies(
+        session.client,
+        session.sessionId,
+        authCookies as Parameters<typeof browser.setCookies>[2],
+      );
+    } catch {
+      /* ignore */
+    }
+  }
+  if (authLocalStorage && Object.keys(authLocalStorage).length) {
+    try {
+      await browser.setLocalStorage(session.client, session.sessionId, authLocalStorage);
+    } catch {
+      /* ignore */
+    }
+  }
+}

package/src/cli/commands-session.ts

@@ -8,17 +8,16 @@
  * differently: it must never kill a Chrome it did not launch.
  */
 
+import { detectAttentionNeeded, switchToHeaded } from './attention-wall.js';
 import { output } from './output.js';
 import {
   adoptLegacySession,
-  detectAttentionNeeded,
   ensureConnected,
   getBrowser,
   launchSessionBrowser,
   pinnedPort,
   resolveLiveSession,
   session,
-  switchToHeaded,
 } from './session.js';
 import type { Command, CommandContext, CommandResult } from './types.js';
 
@@ -39,7 +38,13 @@ export const openCommand: Command = {
       description: 'Force visible browser window',
       default: false,
     },
-    { name: 'session', short: 's', type: 'string', description: 'Session name to restore' },
+    {
+      name: 'session',
+      short: 's',
+      type: 'string',
+      description:
+        'Named session: re-open the live one with this name or start it, and restore saved state of that name if any',
+    },
     { name: 'state', type: 'string', description: 'State file to load' },
   ],
   action: async (ctx: CommandContext): Promise<CommandResult> => {
@@ -48,10 +53,14 @@ export const openCommand: Command = {
 
     // No --port means "start a session of my own on a free port" (#318) —
     // never "join whatever is on 9222", which is what made two uncoordinated
-    // `open` calls race for one browser and one profile directory.
-    const port = pinnedPort(ctx.flags);
-    const forceHeaded = ctx.flags.headed as boolean;
+    // `open` calls race for one browser and one profile directory. A
+    // --session name re-opens the live session of that name, if there is one.
     const browser = await getBrowser();
+    const name = session.name || undefined;
+    const port =
+      pinnedPort(ctx.flags) ??
+      (name ? (await resolveLiveSession(browser, { name }))?.port : undefined);
+    const forceHeaded = ctx.flags.headed as boolean;
 
     if (session.client) {
       const prevSid = session.sessionId;
@@ -91,7 +100,7 @@ export const openCommand: Command = {
 
     // Starts this session's own browser (and records it) unless --port named
     // one to attach to — see the session rule in session.ts.
-    session.port = await launchSessionBrowser(browser, { port, headless: !forceHeaded });
+    session.port = await launchSessionBrowser(browser, { port, headless: !forceHeaded, name });
     const conn = await browser.connectToTarget(session.port);
     session.client = conn.client;
     session.sessionId = conn.sessionId;
@@ -107,8 +116,10 @@ export const openCommand: Command = {
     }
     if (ctx.flags.state) {
       await browser.loadStateFile(session.client, session.sessionId, ctx.flags.state as string);
-    } else if (ctx.flags.session) {
-      await browser.loadSession(session.client, session.sessionId, ctx.flags.session as string);
+    } else if (name && (await browser.listSessions()).includes(name)) {
+      // Saved state of the same name (`state save <name>`) is restored; a
+      // name with none is simply a fresh named session.
+      await browser.loadSession(session.client, session.sessionId, name);
     }
 
     await browser.openUrl(session.client, session.sessionId, url);
@@ -228,7 +239,7 @@ export const closeCommand: Command = {
             port: pinned,
             launched: true,
           })
-        : await resolveLiveSession(browser, { strict: false });
+        : await resolveLiveSession(browser, { strict: false, name: session.name || undefined });
       if (persisted?.launched) {
         try {
           const conn = await browser.connectToTarget(persisted.port);
@@ -271,7 +282,9 @@ export const closeCommand: Command = {
         output.printInfo(
           persisted
             ? `Detached from browser on port ${persisted.port} (attached via connect — left running)`
-            : 'No active browser session',
+            : session.name
+              ? `No live browse session named "${session.name}"`
+              : 'No active browser session',
         );
       }
       if (persisted) {
@@ -370,7 +383,7 @@ export const connectCommand: Command = {
     // launches a browser of its own instead of reusing this session.
     // launched:false marks this browser as someone else's — close must never
     // kill it, and a dead endpoint must not be silently relaunched.
-    await browser.saveSessionRecord(port, { launched: false });
+    await browser.saveSessionRecord(port, { launched: false, name: session.name || undefined });
     const url = await browser.getCurrentUrl(session.client, session.sessionId);
     const title = await browser.getCurrentTitle(session.client, session.sessionId);
     output.printSuccess(`Connected: ${title} (${url})`);