pw-repl 0.4.0 → 0.4.2

package/README.md

@@ -6,6 +6,36 @@ one shows in the REPL, so each sees what the other does. The REPL inspects the p
 (requests, console, and each step a person takes), fakes, patches or slows responses, and emulates phones,
 dark mode, locales and timezones.
 
+## Why use it
+
+For working on a web page together with an agent, in the browser you already use:
+
+- **Your browser, as it is.** It connects to a running Chromium, with your tabs, sign-ins and state, and
+  leaves it running when it stops; nothing is reset to a fresh profile.
+- **One session, seen by everyone.** You and any number of agents drive the same browser, each with a
+  selected tab of its own, and every command shows in the REPL, whoever sent it.
+- **What you did, for an agent to read.** `watch` records each step you take in a tab, with the requests
+  it caused, so you can reproduce a bug by hand and the agent can see exactly what happened.
+- **Breaking things on purpose.** Fake, patch, delay or fail responses, cut or slow the network, emulate a
+  phone, a locale or a timezone, all per tab, so your other tabs are left alone.
+
+## How it differs from playwright-cli
+
+[playwright-cli](https://github.com/microsoft/playwright-cli) is Microsoft's command line for agents. It
+gives each agent a browser session of its own; pw-repl shares one browser between a person and agents.
+Its command names and most of their options work here too (`help playwright-cli` lists them), and where
+pw-repl differs, it is because someone else may be using the browser:
+
+- `open` and `close` open a tab and turn off your modes; they never start, close or wipe a browser.
+- Routes, network and emulation apply to one tab, not the whole browser.
+- File pickers are not caught, since they may be the person's: `upload` names the input instead.
+- There is no snapshot after every command, since a person reads the REPL too; `snapshot` shows one.
+- Instead of `-s=<session>`, an agent is a client of its own (`send -c <name>`).
+- `watch` records what a person does as steps with their requests, not as generated code.
+
+For a browser of its own per agent, isolated sessions, traces, video, PDFs or generated test code,
+playwright-cli is the better fit.
+
 ## Getting started
 
 ### Prerequisites

package/bin/pw-repl.js

@@ -41,9 +41,10 @@ send exit status: 0 ok, 1 command error, 2 completion not confirmed, 64 usage or
 The browser must be running with --remote-debugging-port (default http://localhost:9222; set $PW_CDP_URL).
 
 --launch is the quick start instead: it starts a Chromium of the REPL's own (headless unless --headed, in
-a temporary profile), prints the command it ran, and stops it with the REPL. Flags after -- go to that
-Chromium; PW_CHROME picks which one. To set a browser up your own way, start it yourself and use
-PW_CDP_URL.
+a temporary profile, on a free port of its own), prints the command it ran, and stops it with the REPL
+(Ctrl-C while it starts too); stop returns once that Chromium has exited. Flags after -- go to it; a
+--user-data-dir=<dir> among them is used instead of the temporary profile, and kept. PW_CHROME picks
+which one. To set a browser up your own way, start it yourself and use PW_CDP_URL.
 
 In a tmux session named playwright-repl, pw-repl send reaches pw-repl run without the server.`;
 
@@ -132,7 +133,7 @@ function help(topic) {
   const helpText = require('../lib/help');
   const text = helpText.render(topic);
   if (text === null) {
-    console.log(`Error: No help for ${topic}. Topics: ${Object.keys(helpText.TOPICS).join(', ')}`);
+    console.log(`Error: ${helpText.notFound(topic)}`);
     process.exit(1);
   }
   console.log(text);

package/lib/background.js

@@ -8,7 +8,13 @@ const client = require('./client');
 
 const BIN = path.join(__dirname, '..', 'bin', 'pw-repl.js');
 const START_TIMEOUT = 20000;
-const STOP_TIMEOUT = 10000;
+// Longer than --launch gives Chromium, twice when it retries without the sandbox, then the connect: its own
+// error, and its cleanup, come first.
+const LAUNCH_START_TIMEOUT = 2 * require('./launch').START_TIMEOUT + 20000;
+// Longer than a REPL can take to stop: its cleanups and letting go of the browser (up to
+// SHUTDOWN_TIMEOUT each), then stopping a Chromium it launched.
+const STOP_TIMEOUT = 2 * require('./state').SHUTDOWN_TIMEOUT + require('./launch').STOP_WORST + 4000;
+const LOG_LIMIT = 5 * 1024 * 1024;
 const FOLLOW_INTERVAL = 150;
 const ATTACH_BACKLOG = 20;
 const ATTACH_COMMAND_TIMEOUT = 3600000;
@@ -47,6 +53,13 @@ function tail(file, lines) {
   try { return fs.readFileSync(file, 'utf8').trimEnd().split('\n').slice(-lines).join('\n'); } catch { return ''; }
 }
 
+// Called in the background REPL as it starts: however it ends, served or not, its log says so.
+function markStopInLog() {
+  process.on('exit', code => {
+    try { fs.writeSync(process.stdout.fd, `--- ${new Date().toISOString()} stopped${code ? ` (exit code ${code})` : ''}\n`); } catch {}
+  });
+}
+
 // Called in the background REPL once it serves: its pid file says it runs, and goes when it exits.
 function claimPidFile(pidFile) {
   fs.writeFileSync(pidFile, String(process.pid), { mode: 0o600 });
@@ -62,8 +75,12 @@ async function start(options) {
   const running = runningPid(pidFile);
   if (running) return fail(`a background REPL is already serving on ${name} (pid ${running}); pw-repl attach uses it, pw-repl stop stops it`);
   if (await client.health(endpoint, 2000)) return fail(`a REPL is already serving on ${name}, in a terminal; pw-repl where says more`);
-  const log = fs.openSync(logFile, 'w', 0o600);
+  // Appended to, so an earlier run's log stays; each run is marked where it starts and stops. One grown
+  // past LOG_LIMIT is moved to <log>.1 first, replacing the one there.
+  try { if (fs.statSync(logFile).size > LOG_LIMIT) fs.renameSync(logFile, `${logFile}.1`); } catch {}
+  const log = fs.openSync(logFile, 'a', 0o600);
   fs.fchmodSync(log, 0o600);
+  fs.writeSync(log, `--- ${new Date().toISOString()} started\n`);
   const args = [BIN, 'serve', ...(options.launch ? ['--launch'] : []), ...(options.headed ? ['--headed'] : []),
     ...(options.endpoint ? [options.endpoint] : []), ...(options.startUrl ? [options.startUrl] : []),
     ...(options.chromeArgs.length ? ['--', ...options.chromeArgs] : [])];
@@ -74,11 +91,26 @@ async function start(options) {
   });
   fs.closeSync(log);
   let exited = false;
-  child.on('exit', () => { exited = true; });
-  const deadline = Date.now() + START_TIMEOUT;
-  while (!exited && Date.now() < deadline && !(await client.health(endpoint, 1000) && runningPid(pidFile))) {
+  const gone = new Promise(resolve => child.on('exit', () => { exited = true; resolve(); }));
+  // Ctrl-C while it waits gives up on the start: the REPL is stopped (and a Chromium it launched with it),
+  // rather than left starting where stop cannot reach it yet.
+  let interrupted = false;
+  const interrupt = () => { interrupted = true; };
+  const signals = ['SIGINT', 'SIGTERM', 'SIGHUP'];
+  for (const signal of signals) process.on(signal, interrupt);
+  const deadline = Date.now() + (options.launch ? LAUNCH_START_TIMEOUT : START_TIMEOUT);
+  while (!exited && !interrupted && Date.now() < deadline && !(await client.health(endpoint, 1000) && runningPid(pidFile))) {
     await new Promise(resolve => setTimeout(resolve, 200));
   }
+  for (const signal of signals) process.removeListener(signal, interrupt);
+  if (interrupted) {
+    if (!exited) child.kill();
+    await Promise.race([gone, new Promise(resolve => setTimeout(resolve, STOP_TIMEOUT))]);
+    try { fs.appendFileSync(logFile, `--- ${new Date().toISOString()} the start was interrupted\n`); } catch {}
+    console.error(`pw-repl: ${exited ? 'interrupted; the background REPL was stopped before it served' : `interrupted; the background REPL (pid ${child.pid}) has not stopped after ${STOP_TIMEOUT / 1000}s`}`);
+    // As a shell reports a command stopped by Ctrl-C.
+    return 130;
+  }
   if (exited || !runningPid(pidFile)) {
     if (!exited) child.kill();
     const last = tail(logFile, 12);
@@ -186,4 +218,4 @@ function describeBackground(endpoint) {
   return `background: pid ${pid}${since}; log ${logFile} (pw-repl attach${e}, pw-repl stop${e})`;
 }
 
-module.exports = { filesFor, endpointFlag, claimPidFile, start, stop, attach, describeBackground };
+module.exports = { filesFor, endpointFlag, markStopInLog, claimPidFile, start, stop, attach, describeBackground };

package/lib/commands.js

@@ -180,6 +180,28 @@ function keptSession(p) {
   return keptSessions.get(p);
 }
 
+// Chrome all but stops drawing a tab that is not in front once it has had
+// input (about a frame a second), and Playwright waits for frames to see an
+// element hold still before acting on it, so each click in a tab opened in the
+// background took 1-2s. A screencast keeps the tab drawing without bringing it
+// to the front, for as long as the REPL runs (the throttle is back within
+// seconds of stopping it). Its frames are tiny and rare; the cost is that the
+// tab renders at full rate, as if in front, an animation or a video included.
+const drawingPages = new WeakSet();
+
+async function keepDrawing(p) {
+  if (drawingPages.has(p)) return;
+  drawingPages.add(p);
+  try {
+    const session = await keptSession(p);
+    session.on('Page.screencastFrame', frame => session.send('Page.screencastFrameAck', { sessionId: frame.sessionId }).catch(() => {}));
+    await session.send('Page.startScreencast', { format: 'jpeg', quality: 1, maxWidth: 8, maxHeight: 8, everyNthFrame: 60 });
+  } catch {
+    // Only slower without it.
+    drawingPages.delete(p);
+  }
+}
+
 const networkEnabled = new WeakSet();
 // page -> how its network is changed: { offline: true }, or slowed { latency, down, up } (ms, kbps).
 const networkChanged = new WeakMap();
@@ -453,6 +475,18 @@ const BODY_TIMEOUT = 15000;
 // Hidden unless asked for: they are rarely what is being checked and crowd out
 // the API calls that are.
 const RECENT_HIDDEN_TYPES = new Set(['image', 'font', 'stylesheet', 'media']);
+// The bodies body prints; any other is binary.
+const TEXT_BODY = /json|^text\/|javascript|xml|html|x-www-form-urlencoded/;
+
+// UTF-8 with no control characters but tabs and line breaks.
+function looksLikeText(buffer) {
+  let text;
+  try { text = new TextDecoder('utf-8', { fatal: true }).decode(buffer); } catch { return false; }
+  return !/[\x00-\x08\x0b\x0c\x0e-\x1f\x7f]/.test(text);
+}
+// A watched tab keeps each body watch shows as it arrives, since the browser
+// drops them once the tab navigates, often before anyone has read them.
+const KEPT_BODY_MAX = 100 * 1024;
 const recentLogs = new WeakMap();
 const consoleLogs = new WeakMap();
 // request -> how a route changed it (faked or patched), shown after its status.
@@ -464,6 +498,8 @@ const loadedAt = new WeakMap();
 const openedTabs = new WeakSet();
 // page -> the client that opened it (null: the prompt, or a sender without a name).
 const tabOwners = new WeakMap();
+// The tab the REPL opened for its start URL, which tab marks: in a kept profile it sits among restored tabs.
+const startTabs = new WeakSet();
 
 function clipText(text) {
   return text.length > MAX_EVENT_TEXT ? `${text.slice(0, MAX_EVENT_TEXT)}…` : text;
@@ -523,6 +559,7 @@ function ensureRecentLog(p) {
       if (res) status = String(res.status());
     } catch {}
     finish(req, changedRequests.has(req) ? `${status} ${changedRequests.get(req)}` : status, res);
+    keepBody(p, requestEntries.get(req), res);
   });
   p.on('requestfailed', req => {
     finish(req, `failed: ${req.failure()?.errorText || 'unknown'}`);
@@ -564,6 +601,38 @@ const WATCH_MAX = 200;
 const WATCH_REQUESTS_SHOWN = 5;
 // Scripts too: a dev server loads dozens per navigation, crowding out the API calls.
 const WATCH_HIDDEN_TYPES = new Set([...RECENT_HIDDEN_TYPES, 'script']);
+
+// Tabs whose watch on --next-tab is still starting: the page can load before it is ready.
+const startingWatches = new WeakSet();
+
+// A page that navigates as soon as a request answers (a login that redirects)
+// takes the body with it before the request is even reported finished; told to
+// in time, the browser keeps them outside the page instead. Once per tab, from
+// its first watch, and never switched off: up to 50 MB of the browser's memory
+// per watched tab, for as long as the REPL runs.
+const DURABLE_TOTAL = 50 * 1024 * 1024;
+const durablePages = new WeakSet();
+
+async function keepBodiesDurable(p) {
+  if (durablePages.has(p)) return;
+  durablePages.add(p);
+  try {
+    const session = await keptSession(p);
+    await session.send('Network.configureDurableMessages', { maxTotalBufferSize: DURABLE_TOTAL, maxResourceBufferSize: KEPT_BODY_MAX });
+  } catch {
+    // An older Chrome: bodies are still kept once their requests finish.
+  }
+}
+
+async function keepBody(p, entry, res) {
+  if (!entry || !res || !(watches.get(p)?.on || startingWatches.has(p)) || WATCH_HIDDEN_TYPES.has(entry.type)) return;
+  const headers = res.headers();
+  if (!TEXT_BODY.test(headers['content-type'] || '') || Number(headers['content-length']) > KEPT_BODY_MAX) return;
+  try {
+    const buffer = await res.body();
+    if (buffer.length <= KEPT_BODY_MAX) entry.kept = buffer;
+  } catch {}
+}
 const TYPING_BACKDATE_MAX = 60000;
 const PAGE_ACTIONS = new Set(['click', 'check', 'uncheck', 'select', 'fill', 'type', 'press', 'submit']);
 // page -> its binding's record function; the binding is added once per tab.
@@ -810,6 +879,7 @@ function printLive(p, watch) {
 }
 
 async function startWatching(p, changes = false, live = false) {
+  await keepBodiesDurable(p);
   let watch = watches.get(p);
   if (!watch) {
     // shownSeq and shownRequestId mark how far watch new has read.
@@ -880,6 +950,11 @@ async function startWatching(p, changes = false, live = false) {
 // new tab is watched from the moment it opens, since its first page may load
 // at once; one that turns out not to be it is left as it was.
 let nextTab = null;
+
+// The sender's own --next-tab is still waiting: the tab will be selected for it.
+function waitingForMe() {
+  return !!nextTab && nextTab.client === state.client;
+}
 const BROWSER_PAGE = /^(?:about|chrome|chrome-search|devtools|edge):/;
 
 function waitingText() {
@@ -888,7 +963,10 @@ function waitingText() {
 
 function watchNewTab(p) {
   const want = nextTab;
+  startingWatches.add(p);
+  keepBodiesDurable(p);
   startWatching(p, want.changes, want.live).then(() => {
+    startingWatches.delete(p);
     watches.get(p).owner = want.client;
     const onNavigate = frame => {
       if (frame !== p.mainFrame() || BROWSER_PAGE.test(frame.url())) return;
@@ -912,12 +990,16 @@ function watchNewTab(p) {
       // Selected for the client that asked, whoever's command runs now.
       const record = clientRecord(want.client);
       if (record.page !== p) { record.previousPage = record.page; record.page = p; }
+      keepDrawing(p);
       out.notice(`Watching the new tab ${url}, now the selected tab (watch on --next-tab)`);
     };
     p.on('framenavigated', onNavigate);
     // Opened on its page already, as a link to a new tab does.
     if (p.url() && !BROWSER_PAGE.test(p.url())) onNavigate(p.mainFrame());
-  }).catch(error => out.notice(`Could not watch the new tab ${p.url()}: ${error.message}`));
+  }).catch(error => {
+    startingWatches.delete(p);
+    out.notice(`Could not watch the new tab ${p.url()}: ${error.message}`);
+  });
 }
 
 // For each step of a watch, the requests made between it and the next step.
@@ -1170,6 +1252,12 @@ async function waitForLoad(timeout) {
     const navigation = (recentLogs.get(p) || []).filter(e => e.navigation && e.t >= since).pop();
     if (navigation && navigation.status.startsWith('failed')) throw new Error(`The page did not load: #${navigation.id} ${navigation.url} ${navigation.status}`);
     const loaded = navigation ? (loadedAt.get(p) || 0) >= navigation.t : await p.evaluate(() => document.readyState === 'complete').catch(() => false);
+    if (loaded && !navigation && (loadedAt.get(p) || 0) < since) {
+      // Nothing loaded since the previous command: a page that changes its URL itself (pushState) does not
+      // load, and may not have changed it yet.
+      out.log(`Loaded before the previous command, nothing since: ${p.url()} — ${await p.title().catch(() => '')}\n(A page that changes its own URL does not load: wait <selector> or wait text waits for its new view.)`);
+      return;
+    }
     if (loaded) { out.log(`Loaded: ${p.url()} — ${await p.title().catch(() => '')}`); return; }
     if (Date.now() >= deadline) throw new Error(`${p.url()} did not finish loading within ${timeout / 1000}s`);
     await new Promise(resolve => setTimeout(resolve, 50));
@@ -1291,6 +1379,7 @@ async function openOwnTab() {
   if (!opened) opened = await ctx.newPage();
   openedTabs.add(opened);
   tabOwners.set(opened, state.client);
+  keepDrawing(opened);
   return opened;
 }
 
@@ -1334,7 +1423,8 @@ async function listTabs() {
     // URL first on its own line: it is what distinguishes otherwise
     // identically titled tabs, and titles wrap less badly when indented.
     if (i) out.log('');
-    out.log(`${marker} [${i}] ${p.url()}${tabOwners.get(p) ? `  (opened by ${tabOwners.get(p)})` : ''}`);
+    const notes = [startTabs.has(p) && 'the start URL', tabOwners.get(p) && `opened by ${tabOwners.get(p)}`].filter(Boolean);
+    out.log(`${marker} [${i}] ${p.url()}${notes.length ? `  (${notes.join(', ')})` : ''}`);
     out.log(`        ${JSON.stringify(title)}`);
   }
 }
@@ -1369,6 +1459,7 @@ const commands = {
       if (p !== state.page) state.previousPage = state.page;
       state.page = p;
       ensureDialogHandler(p);
+      keepDrawing(p);
     };
     const byUrl = part => {
       const matches = all.filter(p => p.url().includes(part));
@@ -1380,8 +1471,15 @@ const commands = {
       if (parts.length) throw new Error(usage);
       const target = state.tabListing[Number(subcommand)];
       if (target && all.includes(target)) { select(target); return commands.info(); }
+      // Not read as part of a URL instead: that could land in someone else's tab without a word.
+      if (target) throw new Error(`Tab [${subcommand}] has closed since the latest listing. Run tab to list them again.`);
       // A number that is not a tab in the listing may be part of a URL (a port).
-      if (!all.some(p => p.url().includes(subcommand))) throw new Error(`No tab [${subcommand}] in the latest listing, and no tab URL contains ${subcommand}. Run tab to list them.`);
+      const containing = all.filter(p => p.url().includes(subcommand)).length;
+      if (!containing) throw new Error(`No tab [${subcommand}] in the latest listing, and no tab URL contains ${subcommand}. Run tab to list them.`);
+      if (containing > 1) {
+        const listing = state.tabListing.length ? 'the latest listing' : 'a listing yet: each client has its own, from tab';
+        throw new Error(`No tab [${subcommand}] in ${listing}. As part of a URL, ${subcommand} is in ${containing} tabs. Run tab, then tab <index>.`);
+      }
     }
     if (subcommand === 'new') {
       select(await openTab());
@@ -1850,7 +1948,8 @@ const commands = {
   async sleep(args) {
     if (!args || !/^\d+$/.test(args) || Number(args) > 3600000) throw new Error('Usage: sleep <ms> (maximum 3600000)');
     await state.page.waitForTimeout(Number(args));
-    out.log(`Slept ${args}ms`);
+    // sleep 3 is easily meant as seconds.
+    out.log(Number(args) < 100 ? `Slept ${args}ms (sleep takes milliseconds: sleep ${args}000 is ${args}s)` : `Slept ${args}ms`);
   },
 
   // A stopped upstream does not reach the browser as a failure: the dev proxy
@@ -1960,19 +2059,22 @@ const commands = {
       await new Promise(resolve => setTimeout(resolve, 50));
     }
     if (!entry.response) throw new Error(`#${id} has no response${entry.status === 'pending' ? ' yet' : ` (${entry.status})`}`);
-    // Not withTimeout: its "timed out" error would disconnect the REPL, and
-    // reading a body cannot have changed anything.
-    let timer;
-    const late = new Promise((_, reject) => { timer = setTimeout(() => reject(new Error(`did not arrive within ${BODY_TIMEOUT / 1000}s`)), BODY_TIMEOUT); });
-    let buffer;
-    try { buffer = await Promise.race([entry.response.body(), late]); }
-    // Playwright's reason ends in advice for its own API ("Read response.body() before..."), so only its first line is kept.
-    catch (error) { throw new Error(`The body of #${id} is not available: ${String(error.message).split('\n')[0]} (the browser drops bodies, e.g. after the tab navigates)`); }
-    finally { clearTimeout(timer); }
+    let buffer = entry.kept;
+    if (!buffer) {
+      // Not withTimeout: its "timed out" error would disconnect the REPL, and
+      // reading a body cannot have changed anything.
+      let timer;
+      const late = new Promise((_, reject) => { timer = setTimeout(() => reject(new Error(`did not arrive within ${BODY_TIMEOUT / 1000}s`)), BODY_TIMEOUT); });
+      try { buffer = await Promise.race([entry.response.body(), late]); }
+      // Playwright's reason ends in advice for its own API ("Read response.body() before..."), so only its first line is kept.
+      catch (error) { throw new Error(`The body of #${id} is not available: ${String(error.message).split('\n')[0]} (the browser drops bodies, e.g. after the tab navigates; a watched tab keeps them as they arrive)`); }
+      finally { clearTimeout(timer); }
+    }
     const type = entry.response.headers()['content-type'] || '';
     out.log(`#${id} ${entry.method} ${entry.status} ${entry.url} (${type || 'no content type'}, ${buffer.length} bytes)`);
     if (!buffer.length) return;
-    if (!/json|^text\/|javascript|xml|html|x-www-form-urlencoded/.test(type)) { out.log('[binary body not shown]'); return; }
+    // With no content type, text is told by its bytes: an error page's "not found" often has none.
+    if (!TEXT_BODY.test(type) && (type || !looksLikeText(buffer))) { out.log('[binary body not shown]'); return; }
     let text = buffer.toString('utf8');
     if (/json/.test(type)) { try { text = JSON.stringify(JSON.parse(text), null, 2); } catch {} }
     printOutput(text, all);
@@ -2012,6 +2114,10 @@ const commands = {
       out.log(`${waitingText()}: it is watched from its first page, and selected. watch off stops waiting.`);
       return;
     }
+    if (sub !== 'on' && arg !== 'off' && waitingForMe() && (!state.page || state.page.isClosed())) {
+      out.log(`${waitingText()} (watch on --next-tab); it is selected once it opens, and watch then shows its steps.`);
+      return;
+    }
     if (sub === 'on' && flags.every(f => f === '--changes' || f === '--live')) {
       if (!state.page || state.page.isClosed()) throw new Error('No tab is selected; select one with tab <index|url-part>, or open one with tab new');
       const changes = flags.includes('--changes');
@@ -2175,7 +2281,7 @@ const commands = {
   async help(args) {
     const topic = (args || '').trim();
     const text = HELP.render(topic);
-    if (text === null) throw new Error(`No help for ${topic}. Topics: ${Object.keys(HELP.TOPICS).join(', ')}`);
+    if (text === null) throw new Error(HELP.notFound(topic));
     out.log(text);
   },
 
@@ -2227,9 +2333,10 @@ function watchPage(p) {
   if (nextTab && !opening) watchNewTab(p);
 }
 
-// watch on --next-tab waits for a tab, and watch off stops waiting, with none selected.
+// watch on --next-tab waits for a tab, and watch off stops waiting, with none selected;
+// watch says it is still waiting.
 function needsTab(cmd, args) {
-  return !(cmd === 'watch' && (/(?:^|\s)--next-tab(?:\s|$)/.test(args) || /^\s*off\s*$/.test(args)));
+  return !(cmd === 'watch' && (/(?:^|\s)--next-tab(?:\s|$)/.test(args) || /^\s*off\s*$/.test(args) || waitingForMe()));
 }
 
 // Tab completion for the prompt: command names first, then the fixed words
@@ -2263,4 +2370,4 @@ function complete(line) {
   return [[], current];
 }
 
-module.exports = { commands, cliCommands, needsTab, dialogCommand, listTabs, openTab, activeModes, watchPage, complete, compactSnapshot, grepSnapshot, summarizeChanges, scrubEditable, clock };
+module.exports = { commands, cliCommands, needsTab, dialogCommand, listTabs, openTab, startTabs, activeModes, watchPage, complete, compactSnapshot, grepSnapshot, summarizeChanges, scrubEditable, clock };

package/lib/help.js

@@ -48,7 +48,7 @@ const TOPICS = {
     commands: ['click', 'dblclick', 'hover', 'fill', 'type', 'press', 'select', 'check', 'uncheck', 'upload'],
   },
   inspect: {
-    intro: 'Output is capped; put --all right after the command for everything (e.g. text --all body).',
+    intro: 'Output is capped; --all right after the command, or at the end, shows everything (text --all body).',
     commands: ['snapshot', 'watch', 'text', 'html', 'attrs', 'listeners', 'count', 'visible', 'links', 'inputs', 'screenshot', 'viewport', 'emulate', 'wait', 'sleep'],
   },
   network: {
@@ -135,7 +135,7 @@ const COMMANDS = {
   watch: {
     usage: 'watch on [--changes] [--live] | off | [n|new]',
     summary: 'record what happens in the tab; show the last n steps',
-    detail: 'Off until watch on; a watch on after watch off starts a new recording. Records clicks, typing (once\nit pauses), Enter and Escape, form changes, submits and navigations, each described by role and name\nlike snapshot, with up to 5 of the requests it caused underneath, each with its status as in requests\n(body <#> for one), leaving out scripts and what requests hides. The REPL\'s own fill is recorded\nas type.\n\nwatch on --next-tab [url-part] returns at once, then waits for the next tab someone opens (tab new,\na client\'s own, does not count), or the next whose URL contains url-part, and watches it from its\nfirst page and selects it for the client that asked: for a tab someone is about to open. It takes\n--changes and --live too; watch off stops waiting, and modes lists it.\n\nwatch on its own says whether it is on and shows the last 20 steps; watch <n> shows the last n.\nwatch new shows only the steps it has not shown yet, and requests that have since arrived for the\nlast one.\n\n--live also prints each step in the REPL window (never in the server\'s answer to a command) once it\nsettles, with its requests and changes, marked [watch], or [watch <url>] for a tab that is not the\nselected one. A step cut short by the next one, or by watch off, prints at once; changes it made\nthen show under the next step.\n\n--changes also shows what each step changed on the page once it settles, in up to 5 lines: + added,\n- removed, ~ changed, each element once with the first names inside it. Not for navigations: what a\npage changes on its own after a step settles (data arriving later) shows under the next step.\n\nA watch belongs to the tab, not to a client: every client sees the same steps, watch new\'s place is\nshared, and anyone\'s watch off stops it.\n\nTyped values are not recorded, and password fields not at all; --changes leaves out field values,\nbut what the page itself shows (e.g. "Hello <name>") is shown. Nothing is replayed.',
+    detail: 'Off until watch on; a watch on after watch off starts a new recording. Records clicks, typing (once\nit pauses), Enter and Escape, form changes, submits and navigations, each described by role and name\nlike snapshot, with up to 5 of the requests it caused underneath, each with its status as in requests\n(body <#> for one), leaving out scripts and what requests hides. The REPL\'s own fill is recorded\nas type.\n\nFrom its first watch on, a tab keeps response bodies of up to 100 KB, so body <#> still shows one\nafter the tab navigates, even when the page navigates as soon as the request answers.\n\nwatch on --next-tab [url-part] returns at once, then waits for the next tab someone opens (tab new,\na client\'s own, does not count), or the next whose URL contains url-part, and watches it from its\nfirst page and selects it for the client that asked: for a tab someone is about to open. It takes\n--changes and --live too; watch off stops waiting, and modes lists it.\n\nwatch on its own says whether it is on and shows the last 20 steps; watch <n> shows the last n.\nwatch new shows only the steps it has not shown yet, and requests that have since arrived for the\nlast one.\n\n--live also prints each step in the REPL window (never in the server\'s answer to a command) once it\nsettles, with its requests and changes, marked [watch], or [watch <url>] for a tab that is not the\nselected one. A step cut short by the next one, or by watch off, prints at once; changes it made\nthen show under the next step.\n\n--changes also shows what each step changed on the page once it settles, in up to 5 lines: + added,\n- removed, ~ changed, each element once with the first names inside it. Not for navigations: what a\npage changes on its own after a step settles (data arriving later) shows under the next step.\n\nA watch belongs to the tab, not to a client: every client sees the same steps, watch new\'s place is\nshared, and anyone\'s watch off stops it.\n\nTyped values are not recorded, and password fields not at all; --changes leaves out field values,\nbut what the page itself shows (e.g. "Hello <name>") is shown. Nothing is replayed.',
   },
   text: { usage: 'text [--all] <selector>', summary: 'visible text of the first match' },
   html: { usage: 'html [--all] <selector>', summary: 'outer HTML of the first match' },
@@ -165,7 +165,7 @@ const COMMANDS = {
     summary: 'wait for an element, text, a response or a load (10s)',
     detail: 'wait <selector> waits for a matching element to be visible, and wait text <text> for text to be;\nwait request <url-part|glob> waits for a matching response, counting one that finished since the\nprevious command began (so click, then wait request, does not miss it).\n\nwait load waits for the page to finish loading (its load event). A navigation that began since the\nprevious command began counts, so click a link, then wait load, waits for the new page. A page\nthat changes its own URL without loading (an app\'s own routing) is not a load: wait for something on\nthe new view instead.\n\nwait text matches any part of an element\'s text, in any case.\n\n--gone waits instead until nothing matching is visible (removed or hidden): wait .spinner --gone.\nIt is done at once if nothing matches yet, so wait for it to appear first if it may not have.\n\nUp to 120s. A wait that times out is an error; the REPL carries on.',
   },
-  sleep: { usage: 'sleep <ms>', summary: 'wait a fixed time (maximum 3600000)' },
+  sleep: { usage: 'sleep <ms>', summary: 'wait a fixed time, in milliseconds (maximum 3600000)' },
   requests: {
     usage: 'requests [--all] [n] [url-filter]',
     summary: 'the selected tab\'s last n requests (default 20)',
@@ -174,7 +174,7 @@ const COMMANDS = {
   body: {
     usage: 'body [--all] <#>|<url-part>',
     summary: 'the response body of request <#>, or of the latest one matching',
-    detail: 'body <url-part> shows the latest finished request whose URL contains url-part (body slots.json).\n\nRead from the browser on demand: JSON is pretty-printed, binary is not shown, output is capped. The\nbrowser may drop a body (e.g. after the tab navigates); then body reports not available.\n\nBodies can contain sensitive data.',
+    detail: 'body <url-part> shows the latest finished request whose URL contains url-part (body slots.json).\n\nRead from the browser on demand: JSON is pretty-printed, binary is not shown, output is capped. The\nbrowser may drop a body (e.g. after the tab navigates); then body reports not available, unless a\nwatch kept it (help watch).\n\nBodies can contain sensitive data.',
   },
   console: {
     usage: 'console [--all] [n] [level|filter]',
@@ -280,4 +280,12 @@ Different on purpose, since the browser may be someone else's too:
   return null;
 }
 
-module.exports = { render, TOPICS, COMMANDS };
+// pw-repl's own commands are run at the shell, so their help is the usage.
+const SHELL_COMMANDS = new Set(['run', 'serve', 'send', 'attach', 'stop', 'where', 'skill']);
+
+function notFound(topic) {
+  if (SHELL_COMMANDS.has(topic)) return `${topic} is run at the shell (pw-repl ${topic}), not in the REPL; pw-repl --help has its options`;
+  return `No help for ${topic}. Topics: ${Object.keys(TOPICS).join(', ')}`;
+}
+
+module.exports = { render, notFound, TOPICS, COMMANDS };

package/lib/launch.js

@@ -1,13 +1,19 @@
 // pw-repl run|serve --launch: a Chromium of the REPL's own, started for it and
 // stopped with it, in a profile that is removed afterwards. It is the quick
 // start; a browser set up any other way is reached with PW_CDP_URL instead.
+// A --user-data-dir among the flags after -- is used instead, and kept.
 const { spawn } = require('child_process');
 const fs = require('fs');
 const os = require('os');
 const path = require('path');
 
 const START_TIMEOUT = 20000;
-const STOP_TIMEOUT = 5000;
+// Stopping: a moment to connect and ask it to close, a few seconds to close, as long again after SIGTERM,
+// and up to 3s to remove a profile its helpers are still writing to. STOP_WORST is what it can take.
+const CLOSE_CONNECT_TIMEOUT = 2000;
+const CLOSE_TIMEOUT = 3000;
+const TERM_TIMEOUT = 3000;
+const STOP_WORST = CLOSE_CONNECT_TIMEOUT + CLOSE_TIMEOUT + TERM_TIMEOUT + 3000;
 const INSTALL = 'npx playwright-core install chromium';
 const ON_PATH = ['google-chrome', 'google-chrome-stable', 'chromium', 'chromium-browser', 'chrome', 'microsoft-edge'];
 const MAC_APPS = [
@@ -48,25 +54,69 @@ function smallShm() {
   try { const shm = fs.statfsSync('/dev/shm'); return shm.blocks * shm.bsize < 1024 ** 3; } catch { return false; }
 }
 
-// Starts it and waits for the port it picked, which it writes into its profile.
-function start(exe, args, profile) {
+const GROUP_GONE_TIMEOUT = 2000;
+
+// A launched Chromium runs in its own process group, so this stops the helper processes it starts too.
+function killGroup(pid) {
+  try { process.kill(-pid, 'SIGKILL'); } catch {}
+}
+
+async function groupGone(pid) {
+  const deadline = Date.now() + GROUP_GONE_TIMEOUT;
+  while (Date.now() < deadline) {
+    try { process.kill(-pid, 0); } catch { return; }
+    await new Promise(resolve => setTimeout(resolve, 50));
+  }
+}
+
+// Starts it and waits for the port it picked, which it prints (as Playwright reads it too): a
+// DevToolsActivePort file in a profile of the caller's can be one an earlier run left behind.
+// One that does not start is stopped, helpers and all, before this returns.
+function start(exe, args, onSpawn) {
   return new Promise(resolve => {
-    // Its own process group, so stopping it also stops the helper processes it starts.
     const proc = spawn(exe, args, { stdio: ['ignore', 'ignore', 'pipe'], detached: true });
+    onSpawn(proc);
     let stderr = '';
+    let partial = '';
     let settled = false;
-    const done = result => { if (!settled) { settled = true; clearInterval(poll); clearTimeout(timer); resolve(result); } };
-    proc.stderr.on('data', d => { if (stderr.length < 20000) stderr += d; });
+    const done = result => {
+      if (settled) return;
+      settled = true; clearTimeout(timer);
+      if (!result.error) return resolve(result);
+      killGroup(proc.pid);
+      // A helper still holding the profile's lock would make a retry in the same profile fail.
+      groupGone(proc.pid).then(() => resolve(result));
+    };
+    proc.stderr.on('data', d => {
+      if (stderr.length < 20000) stderr += d;
+      const text = partial + d;
+      const listening = /^DevTools listening on ws:\/\/[^/\s]+:(\d+)\//m.exec(text);
+      if (listening) done({ proc, port: listening[1] });
+      partial = text.slice(text.lastIndexOf('\n') + 1);
+    });
     proc.on('error', error => done({ error: error.message, stderr }));
     proc.on('exit', code => done({ error: `it exited with code ${code}`, stderr }));
-    const portFile = path.join(profile, 'DevToolsActivePort');
-    const poll = setInterval(() => {
-      try { const port = fs.readFileSync(portFile, 'utf8').split('\n')[0].trim(); if (port) done({ proc, port }); } catch {}
-    }, 100);
-    const timer = setTimeout(() => { proc.kill('SIGKILL'); done({ error: `no debugging port within ${START_TIMEOUT / 1000}s`, stderr }); }, START_TIMEOUT);
+    const timer = setTimeout(() => done({ error: `no debugging port within ${START_TIMEOUT / 1000}s`, stderr }), START_TIMEOUT);
   });
 }
 
+// Chromium takes only --user-data-dir=<dir>, and the last one given.
+function userDataDir(args) {
+  const given = args.filter(a => a.startsWith('--user-data-dir=')).pop();
+  return given ? path.resolve(given.slice('--user-data-dir='.length)) : null;
+}
+
+async function closeBrowser(url) {
+  let browser;
+  try {
+    browser = await require('playwright-core').chromium.connectOverCDP(url, { timeout: CLOSE_CONNECT_TIMEOUT });
+    const session = await browser.newBrowserCDPSession();
+    // It closes before it answers, or as it does.
+    await session.send('Browser.close').catch(() => {});
+  } catch {}
+  try { await browser?.close(); } catch {}
+}
+
 function quoted(args) {
   return args.map(a => (/[\s"'$]/.test(a) ? JSON.stringify(a) : a)).join(' ');
 }
@@ -76,40 +126,60 @@ async function launch({ headed = false, extraArgs = [] }) {
   if (!exe) {
     throw new Error(`No Chromium found to launch. Install Playwright's with:\n  ${INSTALL}\nor set PW_CHROME to one, or start one yourself with --remote-debugging-port and set PW_CDP_URL.`);
   }
-  const profile = fs.mkdtempSync(path.join(os.tmpdir(), 'pw-repl-chrome-'));
-  const ours = [...(headed ? [] : ['--headless=new']), '--remote-debugging-port=0', `--user-data-dir=${profile}`,
+  const given = userDataDir(extraArgs);
+  const profile = given || fs.mkdtempSync(path.join(os.tmpdir(), 'pw-repl-chrome-'));
+  const removeProfile = () => { if (!given) fs.rmSync(profile, { recursive: true, force: true }); };
+  // Registered before Chromium starts, and kept for the REPL's life: a REPL that goes without shutting
+  // down, even while it waits for Chromium, still takes it (and a profile of its own) along.
+  let group = null;
+  const onExit = () => { if (group) killGroup(group); try { removeProfile(); } catch {} };
+  process.on('exit', onExit);
+  const onSpawn = proc => { group = proc.pid; };
+  const ours = [...(headed ? [] : ['--headless=new']), '--remote-debugging-port=0', ...(given ? [] : [`--user-data-dir=${profile}`]),
     '--no-first-run', '--no-default-browser-check', ...(smallShm() ? ['--disable-dev-shm-usage'] : [])];
+  // A profile already used has tabs to restore; a blank tab of its own each time would pile up there.
+  // Local State is written at its root on the first run, whichever --profile-directory is used.
+  const blank = given && fs.existsSync(path.join(given, 'Local State')) ? [] : ['about:blank'];
   // Flags given after -- come after these, so they can override them.
-  let args = [...ours, ...extraArgs, 'about:blank'];
-  let result = await start(exe, args, profile);
+  let args = [...ours, ...extraArgs, ...blank];
+  let result = await start(exe, args, onSpawn);
   let note = null;
   // Tried with the sandbox first; a container often cannot give Chromium one.
   if (result.error && /sandbox/i.test(result.stderr)) {
-    args = [...ours, '--no-sandbox', ...extraArgs, 'about:blank'];
-    result = await start(exe, args, profile);
+    args = [...ours, '--no-sandbox', ...extraArgs, ...blank];
+    result = await start(exe, args, onSpawn);
     note = 'Chromium could not use its sandbox here, so it runs with --no-sandbox.';
   }
   const command = quoted([exe, ...args]);
   if (result.error) {
-    fs.rmSync(profile, { recursive: true, force: true });
+    process.removeListener('exit', onExit);
+    removeProfile();
     const last = result.stderr.trim().split('\n').slice(-5).join('\n');
     throw new Error(`Chromium did not start (${result.error}):\n  ${command}${last ? `\n${last}` : ''}`);
   }
   const { proc, port } = result;
-  const signal = name => { try { process.kill(-proc.pid, name); } catch {} };
+  const url = `http://127.0.0.1:${port}`;
+  const exited = new Promise(resolve => { if (proc.exitCode !== null || proc.signalCode !== null) resolve(); else proc.once('exit', resolve); });
+  const exitsWithin = ms => Promise.race([exited.then(() => true), new Promise(resolve => setTimeout(resolve, ms, false))]);
   const stop = async () => {
-    if (proc.exitCode === null && proc.signalCode === null) {
-      signal('SIGTERM');
-      await new Promise(resolve => { const t = setTimeout(() => { signal('SIGKILL'); resolve(); }, STOP_TIMEOUT); proc.once('exit', () => { clearTimeout(t); resolve(); }); });
+    if (!(await exitsWithin(0))) {
+      // Browser.close shuts it down in order: its helpers save the profile (what pages last wrote to
+      // localStorage) and it removes the profile's lock. SIGTERM to the browser process saves the
+      // profile too but leaves the lock; to the whole group, it loses the last writes.
+      // Not awaited: a browser that hangs may never answer; its exit is what counts.
+      void closeBrowser(url);
+      if (!(await exitsWithin(CLOSE_CONNECT_TIMEOUT + CLOSE_TIMEOUT))) {
+        try { process.kill(proc.pid, 'SIGTERM'); } catch {}
+        await exitsWithin(TERM_TIMEOUT);
+      }
     }
+    killGroup(proc.pid);
     // Its helper processes can still be writing to the profile for a moment.
     for (let tries = 0; tries < 30; tries++) {
-      try { fs.rmSync(profile, { recursive: true, force: true }); return; } catch { await new Promise(resolve => setTimeout(resolve, 100)); }
+      try { removeProfile(); return; } catch { await new Promise(resolve => setTimeout(resolve, 100)); }
     }
   };
-  // If the REPL goes without shutting down, the browser still goes with it.
-  process.on('exit', () => signal('SIGKILL'));
-  return { url: `http://127.0.0.1:${port}`, command, note, headed, stop };
+  return { url, command, note, headed, stop };
 }
 
-module.exports = { findChrome, launch, INSTALL };
+module.exports = { findChrome, launch, INSTALL, START_TIMEOUT, STOP_WORST };

package/lib/output.js

@@ -61,7 +61,7 @@ function printOutput(value, all = false) {
   else text = JSON.stringify(value, null, 2);
   if (text === undefined) text = 'undefined';
   if (!all && text.length > OUTPUT_LIMIT) {
-    log(`${text.slice(0, OUTPUT_LIMIT)}\n[truncated; use --all after the command to show all]`);
+    log(`${text.slice(0, OUTPUT_LIMIT)}\n[truncated; add --all to the command to show all]`);
   } else {
     log(text);
   }

package/lib/runner.js

@@ -30,7 +30,7 @@ const READ_ONLY = new Set(['info', 'listeners', 'text', 'html', 'attrs', 'count'
 // Commands that work with no tab selected.
 const NO_TAB_NEEDED = new Set(['tab', 'modes', 'capture', 'dialog', 'help', 'quit', 'tab-select', 'close']);
 
-// Commands that accept a leading --all to lift the output limit.
+// Commands that accept --all, right after the command or at the end, to lift the output limit.
 const INSPECTION = ['info', 'listeners', 'text', 'html', 'attrs', 'links', 'inputs', 'eval', 'cdp', 'cookies', 'storage', 'capture', 'body', 'console', 'snapshot', 'watch'];
 
 let queue = Promise.resolve();
@@ -85,8 +85,10 @@ async function executeCommand(text) {
   const spaceIdx = text.indexOf(' ');
   const cmd = spaceIdx === -1 ? text : text.slice(0, spaceIdx);
   let args = spaceIdx === -1 ? '' : text.slice(spaceIdx + 1);
-  const all = INSPECTION.includes(cmd) && /^--all(?:\s|$)/.test(args);
-  if (all) args = args.slice(5).trimStart();
+  let all = false;
+  if (INSPECTION.includes(cmd) && /^--all(?:\s|$)/.test(args)) { all = true; args = args.slice(5).trimStart(); }
+  // At the end too, where the truncation note's reader tends to put it (console 200 --all).
+  else if (INSPECTION.includes(cmd) && /(?:^|\s)--all$/.test(args)) { all = true; args = args.slice(0, -5).trimEnd(); }
   // wait request counts responses since the previous command began.
   state.previousCommandAt = state.currentCommandAt;
   state.currentCommandAt = Date.now();

package/lib/start.js

@@ -3,7 +3,7 @@ const { chromium } = require('playwright-core');
 const readline = require('readline');
 const { state, withTimeout, shutdown, onBeforeExit, beforeExit } = require('./state');
 const out = require('./output');
-const { listTabs, openTab, watchPage, complete } = require('./commands');
+const { listTabs, openTab, startTabs, watchPage, complete } = require('./commands');
 const runner = require('./runner');
 
 // A browser --launch starts has its own address instead.
@@ -28,6 +28,7 @@ Or let pw-repl start a private one for this REPL: pw-repl run --launch (or serve
 
 async function start(options) {
   const START_URL = options.startUrl || process.env.PW_START_URL || null;
+  if (options.pidFile) require('./background').markStopInLog();
   if (options.launch) {
     const launched = await require('./launch').launch({ headed: options.headed, extraArgs: options.chromeArgs });
     onBeforeExit(launched.stop);
@@ -72,6 +73,7 @@ async function start(options) {
 
   if (START_URL) {
     state.page = await openTab();
+    startTabs.add(state.page);
     await state.page.goto(START_URL, { waitUntil: 'networkidle', timeout: 15000 });
     out.log(`Opened ${state.page.url()} in a new tab`);
   }
@@ -150,7 +152,11 @@ function stop() {
   shutdown().then(beforeExit).then(() => process.exit(process.exitCode || 0));
 }
 
-// SIGHUP too: closing the terminal must still remove the server's socket.
-for (const signal of ['SIGTERM', 'SIGHUP']) process.on(signal, stop);
+// SIGHUP too: closing the terminal must still remove the server's socket. SIGINT is Ctrl-C before the
+// prompt reads it (while --launch starts Chromium, or while connecting): without this, node exits at
+// once and leaves a launched Chromium running.
+for (const signal of ['SIGTERM', 'SIGHUP', 'SIGINT']) process.on(signal, stop);
 
-module.exports = { start: options => start(options).catch(e => { out.error(e.message); shutdown().then(beforeExit).finally(() => process.exit(1)); }) };
+// Stopped while it starts (Ctrl-C), what was under way fails as the browser goes: stop() says nothing
+// of that, and exits.
+module.exports = { start: options => start(options).catch(e => { if (state.stopping) return; out.error(e.message); shutdown().then(beforeExit).finally(() => process.exit(1)); }) };

package/lib/state.js

@@ -83,4 +83,4 @@ async function shutdown() {
   return shutdownPromise;
 }
 
-module.exports = { state, clientRecord, asClient, withTimeout, onShutdown, onBeforeExit, beforeExit, shutdown };
+module.exports = { state, clientRecord, asClient, withTimeout, onShutdown, onBeforeExit, beforeExit, shutdown, SHUTDOWN_TIMEOUT };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "pw-repl",
-  "version": "0.4.0",
+  "version": "0.4.2",
   "description": "Text REPL for driving an existing Chromium through Playwright over CDP",
   "keywords": [
     "playwright",

package/skill/SKILL.md

@@ -25,12 +25,19 @@ one; each takes an optional start URL, which opens in a new tab.
 
 - `pw-repl serve --background` runs it detached, with a command server on `/tmp/playwright-repl.sock`
   (owner-only) and its output in `/tmp/playwright-repl.log`. `pw-repl attach` shows everything it does
-  and takes commands; `pw-repl stop` stops it.
+  and takes commands; `pw-repl stop` stops it. It returns once the REPL serves; Ctrl-C before then gives
+  up on the start, stops the REPL, exits 130, and says so in the log.
 - `pw-repl serve` runs the same in a terminal, where the pane shows every command. Its prompt is
   `pw[serve]>`.
 - Add `--launch` to `run` or `serve` (with or without `--background`) to have it start a Chromium of its
-  own instead of connecting to one: headless unless `--headed`, in a temporary profile, stopped with the
-  REPL. It prints the command it ran; flags after `--` are passed to that Chromium.
+  own instead of connecting to one: headless unless `--headed`, in a temporary profile, on a free port of
+  its own (never 9222). It stops with the REPL, Ctrl-C while it starts included, and `stop` returns once
+  it has exited. It prints the command it ran; flags after `--` are passed to that Chromium, and a
+  `--user-data-dir=<dir>` among them is used instead of the temporary profile, and kept. Started again in
+  a kept profile, Chromium picks up where it left off, as it would for a person, headless too: its tabs
+  come back, and session cookies with them, so a login stays. They start loading before the REPL is
+  attached, so `requests` and `console` have only what came after, often nothing: `reload` for a full
+  record.
 - `pw-repl run` runs it in a terminal with no server; `send` then reaches it through tmux, if it runs in
   the tmux session `playwright-repl`:
 
@@ -41,9 +48,11 @@ one; each takes an optional start URL, which opens in a new tab.
 
 `serve` and `serve --background` take a socket path of your own instead of the default
 (`pw-repl serve --background /tmp/mine.sock`); `send`, `attach`, `stop` and `where` then need
-`-e /tmp/mine.sock`, or `PW_SOCKET=/tmp/mine.sock`. The log of a background REPL is next to its socket
-(`/tmp/mine.log`); `tail -f` on it follows along without a terminal to attach from. `serve <port>`
-listens on TCP 127.0.0.1 instead of a socket, with no access control.
+`-e /tmp/mine.sock`, or `PW_SOCKET=/tmp/mine.sock`; a socket file left by a REPL that died is replaced
+when the next one starts there. The log of a background REPL is next to its socket
+(`/tmp/mine.log`), appended to run after run, with a line where each starts and stops (past 5 MB, a
+start moves it to `/tmp/mine.log.1`); `tail -f` on it follows along without a terminal to attach from.
+`serve <port>` listens on TCP 127.0.0.1 instead of a socket, with no access control.
 
 ### One REPL, many clients
 
@@ -99,8 +108,9 @@ from its first page.
 
 When watching someone:
 
-- Read `body <#>` for any request that matters as soon as it shows up: the browser drops a body once
-  its tab navigates.
+- A watched tab keeps response bodies of up to 100 KB, so `body <#>` still has them after the tab
+  navigates. Read a bigger one that matters as soon as it shows up in `requests`: the browser drops it
+  once the tab navigates.
 - `watch` leaves out images and other static files, failed ones too; `console error` and
   `requests --all` show what failed.
 - Without a url-part, `--next-tab` takes the first tab anyone opens; check `tab` and `info` once it
@@ -144,8 +154,10 @@ pw-repl send -c <name> close                        # your modes off; tab close
 - The browser may have tabs that are not yours, and someone may be using it. Whether to read or act in
   one of those tabs, or to open your own (`tab new <url>`), depends on the task; when that is not
   clear, ask.
-- No tab is selected when the REPL starts (unless it was given a start URL). Closing a tab the REPL
-  opened goes back to the tab before it, if the REPL opened that one too; otherwise no tab is selected.
+- No tab is selected when the REPL starts. A start URL's tab, marked `(the start URL)` in `tab`, is
+  selected at its prompt and for `send` without a client name; a named client (`-c`) selects it with
+  `tab <index>`. Closing a tab the REPL opened goes back to the tab before it, if the REPL opened that
+  one too; otherwise no tab is selected.
   Tab numbers change when tabs open or close; `tab <url-part>` and `tab close <url-part>` pick a tab by
   its URL and refuse if it is ambiguous.
 - Dialogs are never answered on their own. While one is open, its page and the commands that read it