@monoes/monobrowse 1.0.3 → 1.0.5

package/src/browser/ref-cache.ts

@@ -16,6 +16,7 @@ import type { ElementRef } from './types.js';
 
 const CACHE_DIR = join(process.cwd(), '.monomind', 'monobrowse');
 const CACHE_FILE = join(CACHE_DIR, 'ax-snapshot.json');
+const PORT_FILE = join(CACHE_DIR, 'active-port.json');
 
 /** Snapshot older than this is flagged as possibly stale (page may have changed). */
 export const REF_CACHE_STALE_MS = 30_000;
@@ -88,3 +89,53 @@ export async function clearRefCache(): Promise<void> {
     // Nothing to clear, or not writable — non-fatal.
   }
 }
+
+/**
+ * Persist the "active" CDP port so a later CLI invocation (each command is a
+ * fresh process — see module header) can find the browser a prior `open
+ * --port N` attached to, instead of every subsequent command silently
+ * falling back to the hardcoded default port and launching/attaching to a
+ * second, unrelated Chrome instance.
+ */
+export async function saveActivePort(port: number, opts?: { launched?: boolean }): Promise<void> {
+  try {
+    await mkdir(CACHE_DIR, { recursive: true });
+    // `launched` records provenance: true = monobrowse spawned this Chrome
+    // (safe to Browser.close later); false = attached to a browser someone
+    // else owns (must never be killed). Absent (old files) reads as launched
+    // — matches pre-flag behavior where every persisted port came from open.
+    await writeFile(PORT_FILE, JSON.stringify({ port, launched: opts?.launched !== false, savedAt: Date.now() }));
+  } catch {
+    // Best-effort — persistence failure just means the next process falls
+    // back to the hardcoded default port, matching prior behavior.
+  }
+}
+
+/** Forget the persisted active port (session closed) so later invocations
+ *  fall back to the default instead of chasing a dead endpoint. */
+export async function clearActivePort(): Promise<void> {
+  try {
+    await rm(PORT_FILE, { force: true });
+  } catch {
+    // Best-effort — a stale port file only costs one failed probe later.
+  }
+}
+
+/** Load the persisted active port, or null if none was ever saved / it's unreadable. */
+export async function loadActivePort(): Promise<number | null> {
+  return (await loadActivePortInfo())?.port ?? null;
+}
+
+/** Load the persisted active port with its provenance flag. */
+export async function loadActivePortInfo(): Promise<{ port: number; launched: boolean } | null> {
+  try {
+    const raw = await readFile(PORT_FILE, 'utf8');
+    const data = JSON.parse(raw) as { port?: unknown; launched?: unknown };
+    if (typeof data.port === 'number' && Number.isInteger(data.port) && data.port >= 1024 && data.port <= 65535) {
+      return { port: data.port, launched: data.launched !== false };
+    }
+    return null;
+  } catch {
+    return null;
+  }
+}

package/src/browser/session.ts

@@ -3,7 +3,13 @@ import { join, dirname } from 'path';
 import { homedir } from 'os';
 import type { SessionState, CdpCookie } from './types.js';
 import type { CdpClient } from './cdp.js';
-import { getCookies, setCookies, getLocalStorage, setLocalStorage, getSessionStorage, setSessionStorage } from './network.js';
+import { getCookiesForUrls, setCookies, getLocalStorage, setLocalStorage, getSessionStorage, setSessionStorage } from './network.js';
+
+// Session state files contain cookies/localStorage — treat as secrets:
+// owner-only read/write on the file (0600) and owner-only access on the
+// containing directory (0700) so other local users can't read session tokens.
+const SESSION_FILE_MODE = 0o600;
+const SESSION_DIR_MODE = 0o700;
 
 const SESSION_DIR = join(homedir(), '.monomind', 'browser-sessions');
 
@@ -31,15 +37,15 @@ export async function saveSession(
   title: string
 ): Promise<string> {
   validateSessionName(name);
-  await mkdir(SESSION_DIR, { recursive: true });
+  await mkdir(SESSION_DIR, { recursive: true, mode: SESSION_DIR_MODE });
 
-  const cookies = await getCookies(client, sessionId);
+  const cookies = await getCookiesForUrls(client, sessionId, [url]);
   const localStorage = await getLocalStorage(client, sessionId);
   const sessionStorage = await getSessionStorage(client, sessionId);
 
   const state: SessionState = { targetId, sessionId, url, title, cookies, localStorage, sessionStorage };
   const filePath = join(SESSION_DIR, `${name}.json`);
-  await writeFile(filePath, JSON.stringify(state, null, 2));
+  await writeFile(filePath, JSON.stringify(state, null, 2), { mode: SESSION_FILE_MODE });
   return filePath;
 }
 
@@ -79,12 +85,12 @@ export async function saveStateFile(
   title: string
 ): Promise<void> {
   validateFilePath(filePath);
-  await mkdir(dirname(filePath), { recursive: true });
-  const cookies = await getCookies(client, sessionId);
+  await mkdir(dirname(filePath), { recursive: true, mode: SESSION_DIR_MODE });
+  const cookies = await getCookiesForUrls(client, sessionId, [url]);
   const localStorage = await getLocalStorage(client, sessionId);
   const sessionStorage = await getSessionStorage(client, sessionId);
   const state: SessionState = { targetId, sessionId, url, title, cookies, localStorage, sessionStorage };
-  await writeFile(filePath, JSON.stringify(state, null, 2));
+  await writeFile(filePath, JSON.stringify(state, null, 2), { mode: SESSION_FILE_MODE });
 }
 
 export async function loadStateFile(

package/src/browser/types.ts

@@ -1,5 +1,10 @@
 export interface BrowserConfig {
   port?: number;
+  /** Fail fast if `port` is occupied by anything other than an attachable
+   *  Chrome, instead of scanning forward to the next free port. Default false
+   *  (scan) — set true for callers that treat the occupied-port error as a
+   *  signal rather than consuming launchBrowser's returned port. */
+  strictPort?: boolean;
   headless?: boolean;
   executablePath?: string;
   userDataDir?: string;

package/src/cli/commands.ts

@@ -10,16 +10,42 @@ import { createPlatformCommand } from './platform.js';
 import type { CdpClient, ElementRef, NetworkRoute, FindAction } from '../index.js';
 
 // Runtime state (single session per CLI process)
+const DEFAULT_PORT = 9222;
 let _client: CdpClient | null = null;
 let _sessionId = '';
 let _targetId = '';
-let _port = 9222;
+let _port = DEFAULT_PORT;
 let _refs: Map<string, ElementRef> = new Map();
 
 async function getBrowser() {
   return import('../index.js');
 }
 
+// Each CLI invocation is a fresh process, so this module's `_port` variable
+// is always freshly initialized to DEFAULT_PORT — a `--port 9333` passed to
+// an earlier `open` command has no effect on this process's own default.
+// Resolve the persisted "active port" (written by `open --port N`, read via
+// ref-cache.ts's saveActivePort/loadActivePort) so subsequent commands
+// attach to the browser the user actually opened instead of silently
+// launching/attaching to a second, unrelated Chrome instance on 9222.
+async function resolveDefaultPort(browser: Awaited<ReturnType<typeof getBrowser>>): Promise<number> {
+  const persisted = await browser.loadActivePortInfo();
+  if (!persisted) return DEFAULT_PORT;
+  if (!persisted.launched) {
+    // connect-origin port: the browser belongs to someone else. If it died,
+    // relaunching our own headless Chrome on that port would squat the
+    // user's debug port and silently swap which browser commands act on —
+    // fail loudly instead.
+    try {
+      await fetch(`http://127.0.0.1:${persisted.port}/json/version`, { signal: AbortSignal.timeout(1500) });
+    } catch {
+      await browser.clearActivePort();
+      throw new Error(`Connected browser on port ${persisted.port} is gone — re-run \`connect\` (or \`open\` to launch a fresh one).`);
+    }
+  }
+  return persisted.port;
+}
+
 async function ensureConnected(port: number, targetId?: string) {
   const browser = await getBrowser();
   if (!_client || !_client.isConnected()) {
@@ -30,13 +56,14 @@ async function ensureConnected(port: number, targetId?: string) {
       browser.teardownConsoleCapture(_sessionId);
       _client.close();
     }
-    _port = await browser.launchBrowser({ port, headless: true });
+    const effectivePort = port === DEFAULT_PORT ? await resolveDefaultPort(browser) : port;
+    _port = await browser.launchBrowser({ port: effectivePort, headless: true });
     const conn = await browser.connectToTarget(_port, targetId);
     _client = conn.client;
     _sessionId = conn.sessionId;
     _targetId = conn.target.id;
     _refs = new Map();
-    await hydrateRefsFromCache(browser, _targetId);
+    await hydrateRefsFromCache(browser, _targetId, conn.target.url);
   }
   return { client: _client!, sessionId: _sessionId, targetId: _targetId };
 }
@@ -46,9 +73,29 @@ async function ensureConnected(port: number, targetId?: string) {
 // command runs. Rehydrate it from the on-disk ref cache (written by
 // captureSnapshot call sites below) so refs resolved by a previous process
 // remain usable. Falls back silently to an empty Map if no cache exists.
-async function hydrateRefsFromCache(browser: Awaited<ReturnType<typeof getBrowser>>, targetId: string): Promise<void> {
+//
+// The cached `url` field (captured at snapshot time) is compared against the
+// browser's CURRENT url (`currentUrl`, from the just-fetched target info).
+// A stale `backendDOMNodeId` can still successfully resolve via
+// DOM.getBoxModel even after a same-tab SPA navigation or DOM mutation
+// changed what's actually at those coordinates — so a mismatch here means
+// EVERY ref in the cache is potentially pointing at the wrong element. We
+// hard-invalidate (skip hydration entirely, so any @eN lookup fails loudly
+// via resolveRef's "not found" error) rather than the weaker 30s time-based
+// staleness check below, which only warns.
+async function hydrateRefsFromCache(
+  browser: Awaited<ReturnType<typeof getBrowser>>,
+  targetId: string,
+  currentUrl: string
+): Promise<void> {
   const cached = await browser.loadRefCache(targetId);
   if (!cached) return;
+  if (currentUrl && cached.url && currentUrl !== cached.url) {
+    output.printError(
+      `Stale references — page has navigated (cache: ${cached.url} → current: ${currentUrl}). Re-run snapshot before using @eN refs.`
+    );
+    return; // leave _refs empty — do not attempt to resolve refs against a different page
+  }
   _refs = cached.refs;
   if (cached.stale) {
     output.printWarning(
@@ -145,11 +192,14 @@ async function switchToHeaded(url: string, port: number): Promise<void> {
   const authCookies = await browser.getCookies(_client, _sessionId).catch(() => [] as unknown[]);
   const authLocalStorage = await browser.getLocalStorage(_client, _sessionId).catch(() => ({}) as Record<string, string>);
 
-  // Close headed session
+  // 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(_sessionId);
   browser.stopRequestCapture(_sessionId);
   browser.teardownDialogHandling(_sessionId);
   browser.teardownConsoleCapture(_sessionId);
+  await browser.closeBrowser(_client, headedPort);
   _client.close();
   _client = null;
   _sessionId = '';
@@ -232,11 +282,18 @@ const openCommand: Command = {
     }
 
     _port = await browser.launchBrowser({ port, headless: !forceHeaded });
+    // Persist the active port so subsequent CLI invocations (each a fresh
+    // process) default to attaching here instead of hardcoded 9222.
+    await browser.saveActivePort(_port);
     const conn = await browser.connectToTarget(_port);
     _client = conn.client;
     _sessionId = conn.sessionId;
     _targetId = conn.target.id;
     _refs = new Map();
+    // A snapshot taken before this navigation is no longer valid for the new
+    // page — drop the persisted ref cache so a stale process's weak
+    // time-based check can't resurrect it before the next explicit snapshot.
+    await browser.clearRefCache();
 
     if (ctx.flags.state && ctx.flags.session) {
       output.printWarning('Both --state and --session provided; --state takes precedence');
@@ -298,11 +355,8 @@ const snapshotCommand: Command = {
     await browser.saveRefCache(_targetId, result.url, _refs);
 
     const applyOutputLimits = (text: string): string => {
-      let out = text;
       const maxOutput = ctx.flags['max-output'] as number | undefined;
-      if (maxOutput && out.length > maxOutput) {
-        out = out.slice(0, maxOutput) + `\n[... truncated at ${maxOutput} chars]`;
-      }
+      let out = maxOutput ? truncateForOutput(text, maxOutput) : text;
       if (ctx.flags['content-boundaries']) {
         const nonce = Math.random().toString(36).slice(2, 10);
         out = `MONOMIND_PAGE_CONTENT nonce=${nonce} origin=${result.url}\n${out}\nEND_MONOMIND_PAGE_CONTENT nonce=${nonce}`;
@@ -500,16 +554,29 @@ const waitCommand: Command = {
       const rawTimeout = Math.min((ctx.flags.timeout as number) ?? 30000, MAX_DOWNLOAD_TIMEOUT);
       const finalPath = await new Promise<string>((resolve, reject) => {
         let guid = '';
+        let settled = false;
         // C2: capture off() functions to avoid listener leaks
         const offBegin = client.on('Browser.downloadWillBegin', (params: Record<string, unknown>) => { guid = params.guid as string; });
         let offProgress: (() => void) | undefined;
         // cleanup defined before setTimeout so the timeout callback can call it
         let tid: ReturnType<typeof setTimeout>;
-        const cleanup = () => { clearTimeout(tid); offBegin?.(); offProgress?.(); };
-        tid = setTimeout(() => { cleanup(); reject(new Error('Download timed out')); }, rawTimeout);
+        let pollTid: ReturnType<typeof setInterval> | undefined;
+        const cleanup = () => { clearTimeout(tid); clearInterval(pollTid); offBegin?.(); offProgress?.(); };
+        const finish = (path: string) => {
+          if (settled) return;
+          settled = true;
+          cleanup();
+          resolve(path);
+        };
+        const fail = (err: Error) => {
+          if (settled) return;
+          settled = true;
+          cleanup();
+          reject(err);
+        };
+        tid = setTimeout(() => fail(new Error('Download timed out')), rawTimeout);
         offProgress = client.on('Browser.downloadProgress', async (params: Record<string, unknown>) => {
           if (params.guid === guid && params.state === 'completed') {
-            cleanup();
             const { readdir, rename, rmdir } = await import('fs/promises');
             const files = await readdir(downloadDir);
             if (files.length > 0) {
@@ -517,16 +584,40 @@ const waitCommand: Command = {
               await mkdir(dirname(savePath), { recursive: true });
               await rename(src, savePath);
               await rmdir(downloadDir).catch(() => {}); // I1: cleanup temp dir
-              resolve(savePath);
+              finish(savePath);
             } else {
               await rmdir(downloadDir).catch(() => {}); // I1: cleanup temp dir
-              reject(new Error('Download completed but no file found'));
+              fail(new Error('Download completed but no file found'));
             }
           } else if (params.guid === guid && params.state === 'canceled') {
-            cleanup();
-            reject(new Error('Download was canceled'));
+            fail(new Error('Download was canceled'));
           }
         });
+
+        // Fallback for the empty-guid race: this process's listener attaches
+        // AFTER a separate `click` process may have already started (and even
+        // finished) the download — so downloadWillBegin/downloadProgress for it
+        // were never observed here. While guid is still empty, poll the expected
+        // output path directly: if it already exists with a stable, non-zero
+        // size across two consecutive checks, treat the download as complete.
+        let lastSize = -1;
+        let stableReads = 0;
+        pollTid = setInterval(async () => {
+          if (settled || guid) return; // a real CDP event has taken over
+          try {
+            const { stat } = await import('fs/promises');
+            const st = await stat(savePath);
+            if (st.isFile() && st.size > 0 && st.size === lastSize) {
+              stableReads++;
+              if (stableReads >= 2) finish(savePath);
+            } else {
+              stableReads = 0;
+            }
+            lastSize = st.size;
+          } catch {
+            // savePath not present yet — keep polling until timeout
+          }
+        }, 300);
       });
       output.printSuccess(`Download saved: ${finalPath}`);
       return { success: true, data: { path: finalPath } };
@@ -802,6 +893,10 @@ const navigateCommand: Command = {
       throw new Error(`Unknown direction: ${direction}. Use: back|forward|reload`);
     }
 
+    // Refs captured before this navigation may now point at different content.
+    _refs = new Map();
+    await browser.clearRefCache();
+
     output.printSuccess(`Navigated: ${direction}`);
     return { success: true };
   },
@@ -1107,12 +1202,26 @@ const networkCommand: Command = {
   },
 };
 
+// Default output cap for eval when --max-output isn't passed explicitly —
+// print(String(result)) had NO limit at all (unlike snapshot's --max-output),
+// so e.g. `eval "document.documentElement.outerHTML"` could dump megabytes
+// straight into an agent's context. An explicit --max-output still overrides
+// this default.
+const DEFAULT_EVAL_MAX_OUTPUT = 50_000;
+
+function truncateForOutput(text: string, maxOutput: number): string {
+  if (!(maxOutput > 0) || text.length <= maxOutput) return text;
+  return text.slice(0, maxOutput) + `\n[... truncated at ${maxOutput} chars]`;
+}
+
 const evalCommand: Command = {
   name: 'eval',
   description: 'Evaluate JavaScript in page context. Usage: monomind browse eval "document.title"',
   options: [
     { name: 'json', type: 'boolean', description: 'Output as JSON', default: false },
     { name: 'stdin', type: 'boolean', description: 'Read JS expression from stdin (heredoc-friendly for multiline scripts)', default: false },
+    { name: 'max-output', type: 'number', description: `Truncate printed output to N characters (default ${DEFAULT_EVAL_MAX_OUTPUT}; 0 disables truncation)` },
+    { name: 'timeout', type: 'number', description: 'Max ms to wait for evaluation to settle (default 30000)' },
   ],
   action: async (ctx: CommandContext): Promise<CommandResult> => {
     const { client, sessionId } = await ensureConnected(_port);
@@ -1126,12 +1235,14 @@ const evalCommand: Command = {
     }
     if (!expr) throw new Error('Usage: monomind browse eval "<expression>" (or pipe with --stdin)');
 
-    const result = await browser.evaluateJs(client, sessionId, expr);
+    const timeoutMs = ctx.flags.timeout as number | undefined;
+    const result = await browser.evaluateJs(client, sessionId, expr, timeoutMs);
 
+    const maxOutput = (ctx.flags['max-output'] as number | undefined) ?? DEFAULT_EVAL_MAX_OUTPUT;
     if (ctx.flags.json) {
-      print(JSON.stringify({ data: result }));
+      print(truncateForOutput(JSON.stringify({ data: result }), maxOutput));
     } else {
-      print(String(result ?? ''));
+      print(truncateForOutput(String(result ?? ''), maxOutput));
     }
 
     return { success: true, data: { result } };
@@ -1165,9 +1276,54 @@ const closeCommand: Command = {
       _sessionId = '';
       _targetId = '';
       _refs = new Map();
+      // Session is gone — forget the persisted port and stale refs so later
+      // invocations don't chase a dead endpoint (or the wrong elements).
+      await browser.clearActivePort();
+      await browser.clearRefCache();
       output.printSuccess('Browser session closed');
     } else {
-      output.printInfo('No active browser session');
+      // Each CLI invocation is a fresh process, so `close` almost always
+      // lands here. The persisted port file is the real session handle:
+      // if monobrowse LAUNCHED that browser (open), gracefully Browser.close
+      // it — otherwise every open→close cycle leaks a headless Chrome. If we
+      // merely ATTACHED to it (connect, launched:false), never kill it: it's
+      // the user's own browser. Either way, forget the port and refs.
+      const browser = await getBrowser();
+      const persisted = await browser.loadActivePortInfo();
+      if (persisted?.launched) {
+        try {
+          const conn = await browser.connectToTarget(persisted.port);
+          try {
+            await browser.closeBrowser(conn.client, persisted.port);
+          } finally {
+            // Always drop our websocket — a hung Browser.close must not keep
+            // this CLI process's event loop alive.
+            try { conn.client.close(); } catch { /* already gone */ }
+          }
+          // closeBrowser has no PID fallback in a fresh process (launchedPids
+          // is per-process) — re-probe so we report what actually happened.
+          // Poll briefly: Browser.close is acknowledged before the process
+          // actually exits, so a single immediate probe false-alarms.
+          let stillUp = true;
+          const probeDeadline = Date.now() + 3000;
+          while (stillUp && Date.now() < probeDeadline) {
+            try {
+              await fetch(`http://127.0.0.1:${persisted.port}/json/version`, { signal: AbortSignal.timeout(800) });
+              await new Promise(r => setTimeout(r, 300));
+            } catch { stillUp = false; }
+          }
+          if (stillUp) output.printWarning(`Browser on port ${persisted.port} did not exit — kill it manually if needed`);
+          else output.printSuccess(`Closed browser on port ${persisted.port}`);
+        } catch {
+          output.printInfo(`No browser answering on port ${persisted.port} — nothing to close`);
+        }
+      } else {
+        output.printInfo(persisted
+          ? `Detached from browser on port ${persisted.port} (attached via connect — left running)`
+          : 'No active browser session');
+      }
+      await browser.clearActivePort();
+      await browser.clearRefCache();
     }
     return { success: true };
   },
@@ -2297,6 +2453,10 @@ const pushstateCommand: Command = {
     const url = ctx.args[0] as string;
     if (!url) throw new Error('Usage: monomind browse pushstate <url>');
     await browser.pushState(client, sessionId, url);
+    // SPA navigation changes what's on the page without a full page load —
+    // refs captured before this pushState call may now resolve to different content.
+    _refs = new Map();
+    await browser.clearRefCache();
     output.printSuccess(`pushState: ${url}`);
     return { success: true };
   },
@@ -2322,6 +2482,54 @@ function tokenizeBatchCommand(input: string): string[] {
   return tokens;
 }
 
+/**
+ * Splits one line of a `batch` command string into a subcommand name, its
+ * args, and any recognized leading flags.
+ *
+ * `eval` is special-cased: its sole argument is a raw JS expression, which
+ * legitimately contains its own string-literal quotes (e.g.
+ * `eval document.querySelector('a')`). tokenizeBatchCommand's shell-style
+ * word-splitting treats `'...'`/`"..."` as grouping delimiters and discards
+ * them — correct for a value like `fill @e1 "some text"`, but for `eval` it
+ * silently deletes the expression's own quotes, turning a string literal
+ * into a bare (undefined) identifier reference and producing a
+ * ReferenceError instead of evaluating the intended expression. For `eval`,
+ * only its own known --flags are consumed from the front; everything after
+ * them is taken verbatim as one argument, untouched by tokenization.
+ *
+ * Exported for direct unit testing — not part of the CLI's public API.
+ */
+export function parseBatchCommandLine(cmdStr: string): { subName: string; subArgs: string[]; flags: Record<string, unknown> } {
+  const trimmed = cmdStr.trim();
+  const evalMatch = trimmed.match(/^eval\b\s*/);
+  if (!evalMatch) {
+    const parts = tokenizeBatchCommand(trimmed);
+    return { subName: parts[0], subArgs: parts.slice(1), flags: {} };
+  }
+
+  let rest = trimmed.slice(evalMatch[0].length);
+  const flags: Record<string, unknown> = {};
+  let consumedAnother = true;
+  while (consumedAnother) {
+    consumedAnother = false;
+    const withValue = rest.match(/^--(max-output|timeout)\s+(-?\d+)\s*/);
+    if (withValue) {
+      flags[withValue[1]] = Number(withValue[2]);
+      rest = rest.slice(withValue[0].length);
+      consumedAnother = true;
+      continue;
+    }
+    const boolFlag = rest.match(/^--(json|stdin)\b\s*/);
+    if (boolFlag) {
+      flags[boolFlag[1]] = true;
+      rest = rest.slice(boolFlag[0].length);
+      consumedAnother = true;
+      continue;
+    }
+  }
+  return { subName: 'eval', subArgs: [rest], flags };
+}
+
 const batchCommand: Command = {
   name: 'batch',
   description: 'Execute multiple commands. Usage: monomind browse batch "open url" "snapshot -i" "click @e1"',
@@ -2335,9 +2543,7 @@ const batchCommand: Command = {
 
     const results: Array<{ command: string; success: boolean; error?: string }> = [];
     for (const cmdStr of commands) {
-      const parts = tokenizeBatchCommand(cmdStr);
-      const subName = parts[0];
-      const subArgs = parts.slice(1);
+      const { subName, subArgs, flags: preParsedFlags } = parseBatchCommandLine(cmdStr);
 
       const subCmd = browseCommand.subcommands?.find((s) => s.name === subName);
       if (!subCmd?.action) {
@@ -2348,7 +2554,7 @@ const batchCommand: Command = {
       }
 
       try {
-        const parsedFlags: CommandContext['flags'] = { _: [] };
+        const parsedFlags: CommandContext['flags'] = { _: [], ...preParsedFlags };
         const consumedIndices = new Set<number>();
         // Parse --flags from subArgs, tracking which indices are flag names/values
         for (let i = 0; i < subArgs.length; i++) {
@@ -2452,7 +2658,7 @@ const removeinitscriptCommand: Command = {
 
 const connectCommand: Command = {
   name: 'connect',
-  description: 'Connect to existing Chrome instance. Usage: monomind browse connect [--port 9222] [--target <id>] [--auto-connect]',
+  description: 'Connect to existing Chrome instance; later commands reuse this session (note: `open` without --port still launches on its own default). Usage: monomind browse connect [--port 9222] [--target <id>] [--auto-connect]',
   options: [
     { name: 'port', short: 'p', type: 'number', description: 'CDP port', default: 9222 },
     { name: 'target', type: 'string', description: 'Target ID to attach to' },
@@ -2504,6 +2710,12 @@ const connectCommand: Command = {
     _targetId = conn.target.id;
     _port = port;
     _refs = new Map();
+    // Persist the port like `open` does — without this, the NEXT CLI process
+    // (each command is a fresh process) resolves the hardcoded default and
+    // tries to launch its own Chrome on 9222 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.saveActivePort(port, { launched: false });
     const url = await browser.getCurrentUrl(_client, _sessionId);
     const title = await browser.getCurrentTitle(_client, _sessionId);
     output.printSuccess(`Connected: ${title} (${url})`);
@@ -2542,7 +2754,7 @@ const recordCommand: Command = {
       case 'restart': {
         const prevStatus = browser.getRecordingStatus(sessionId);
         let prevPath: string | undefined;
-        if (prevStatus.recording) {
+        if (prevStatus.recording || prevStatus.autoStopped) {
           prevPath = await browser.stopRecording(client, sessionId, ctx.args[1] as string);
           output.printInfo(`Previous recording saved: ${prevPath}`);
         }
@@ -2556,7 +2768,7 @@ const recordCommand: Command = {
       case 'status': {
         const status = browser.getRecordingStatus(sessionId);
         if (ctx.flags.json) print(JSON.stringify({ data: status }));
-        else print(`Recording: ${status.recording} | Frames: ${status.frames}`);
+        else print(`Recording: ${status.recording} | Frames: ${status.frames}${status.autoStopped ? ' (auto-stopped: buffer limit reached — run "record stop" to save)' : ''}`);
         return { success: true, data: status };
       }
       default: