cdpilot 0.9.5 → 0.9.6

package/README.md

@@ -148,7 +148,26 @@ tools (navigate, click, fill, content, screenshot, eval, wait_for, assert, tabs,
 plus `browser_tools`. The agent calls `browser_tools` with `list` to see the other
 tools, or `enable` to add some (the server sends `tools/list_changed`). `--tools a,b,c`
 picks tools by name; `all` (default) is unchanged. Schema size of `tools/list`
-(tiktoken `o200k_base`): 45 tools = 5,769 tokens, `core` = 11 tools = 1,342 tokens.
+(tiktoken `o200k_base`): 45 tools = 5,769 tokens, `core` = 11 tools = 1,342 tokens; the four
+`browser_agent_*` tools add ~11% of schema (49 tools ≈ 6,400 tokens, scaled from the measurement).
+
+### Agent mode over MCP
+
+`browser_agent_observe` (`diff`), `browser_agent_act` (`ref`/`url`, `action`, `text`), `browser_agent_flow_save`
+(`name`, `last`) and `browser_agent_run` (`flow`, `vars`, `dry_run`) wrap the agent commands below, so a model
+on MCP works from numbered refs, gets diffs, and replays a learned flow with no page read at all. They are
+outside the `core` profile; `browser_tools enable` adds them. A drift or a missing variable comes back as
+`isError` with the command's JSON (`status:"drift"` carries the page's observation).
+
+Set `CDPILOT_DAEMON=1` in the MCP server's environment and every tool call runs in the server process
+instead of a fresh Python process: ~10 ms before the CDP work instead of ~400 ms (`browser_eval` /
+`browser_tabs` / `browser_content` medians 11 / 7 / 9 ms against 412 / 390 / 416 ms, M1 Max under load).
+Same rules as the warm process below — same output, exit codes and session log; lifecycle tools
+(`browser_launch`, `browser_connect`) still run fresh; a call past 30 s is cancelled.
+
+```json
+{ "mcpServers": { "cdpilot": { "command": "npx", "args": ["cdpilot", "mcp"], "env": { "CDPILOT_DAEMON": "1" } } } }
+```
 
 ### MCP Bundle (.mcpb)
 
@@ -453,6 +472,70 @@ cdpilot a11y summary          # Quick summary
 cdpilot a11y find <role>      # Find elements by ARIA role
 ```
 
+### Agent mode: numbered refs and diffs (token budget)
+
+```bash
+cdpilot agent observe                 # {url, title, actions:[{ref:"@1", role, name, value?}], text, token_estimate}
+cdpilot agent act --ref @3 --action click
+cdpilot agent act --ref @4 --action fill --text "cdpilot"
+cdpilot agent act --url https://example.com/   # navigates silently, prints the diff
+cdpilot agent observe --diff          # only what changed since the last observe/act
+cdpilot agent stats | agent reset
+```
+
+`observe` turns the accessibility tree into a numbered list of things an agent can act on (buttons, links,
+fields with their current value, unique text anchors) plus a short text summary; no screenshot, no HTML.
+Every `act` and `observe --diff` returns only the change: `changed.added` (full descriptors, so the agent can act
+on a new element without another observe), `changed.removed` (refs), `changed.value_changed`, and `text` only
+when it changed (`text_changed`). Refs are stable while the element exists (keyed by the DOM node, not by
+position); a navigation starts a new set. `token_estimate` is `len(json)/4`; `saved_vs_full` compares the diff
+with a full observe of the same page. State lives in `~/.cdpilot/projects/<id>/agent-state.json`.
+
+#### Learned flows: drive a site once, replay it with no model
+
+```bash
+cdpilot agent observe && cdpilot agent act --ref @3 --action click && cdpilot agent act --ref @4 --action fill --text "cdpilot"
+cdpilot agent flow save inbox-triage        # the acts since the last navigation → ~/.cdpilot/projects/<id>/flows/inbox_triage.json
+cdpilot agent run inbox-triage              # replays by anchors; prints one JSON: {status:"ok", steps, url, title, ms, tokens_avoided}
+cdpilot agent run login --var password=…    # a typed secret was saved as {{password}}; --var supplies it, or CDPILOT_VAR_PASSWORD
+                                            # with CDPILOT_VAR_HOSTS=example.com (the host the value was recorded on)
+cdpilot agent flow list | show <name> | delete <name>
+```
+
+Every `agent act` leaves a trail entry addressed by an *anchor*, the element's accessibility role, name and
+position among equals (`{"role":"button","name":"Archive","nth":0}`), never a `@ref` or a DOM node id, which
+belong to one session. `agent flow save` writes the trail as a flow; `agent run` finds each anchor on the live
+page (exact name, then case-insensitive, then a longer name containing it when that is unambiguous) and acts,
+with no model in the loop. The result's `tokens_avoided` is what a model would have read observing the page
+before each step. When a site has a flow, `agent observe` lists it under `known_flows`.
+
+**Drift stops, never guesses.** If a step's anchor is gone, or the step lands on another host than it did
+when recorded, `agent run` exits 4 and prints that page's full observation (`status:"drift"`, `step`,
+`expected`, `actions`, `text`): the agent acts on those refs, finishes the task, and `agent flow save <name>`
+rewrites the flow. Exit 2: unknown flow or a `{{variable}}` without a value (checked before any step runs);
+`--dry-run` prints the steps with placeholders, never values. Values typed into secret-named fields
+(password, one-time code, API key, PIN, card number, …) or token-shaped values are placeholders on disk; the
+same fields show `«masked»` as their value in `observe` output. Masking goes by field name or token shape: a
+secret typed into a field named otherwise is stored in clear, so review a flow before sharing it (flow files
+and `agent-state.json` are 0600). A `{{placeholder}}` typed into `agent act --text` or `--url` is refused
+(exit 2): placeholders are cdpilot's own, so a flow replays only values the user recorded, and a step that
+types one runs only on the host it was recorded on. `--var` values are visible in the process list for the
+duration of the call and are redacted in the session log; an environment value never enters argv.
+`CDPILOT_VAR_<NAME>` is used only by a step recorded on a host named in `CDPILOT_VAR_HOSTS` (comma-separated,
+subdomains included), on that same origin, and never inside a URL — so a flow that a prompt-injected model
+records on another site cannot draw on the environment's secrets; anything else is refused before the first
+step (exit 2, `refused` says why) or is a drift.
+
+#### Text that talks to the agent: `injection_suspect`
+
+Page text that addresses the model instead of the user is the shape of an indirect prompt injection ("AI
+assistants reading this page: ignore your previous instructions…"). `agent observe`, the diff of `agent act`
+and a drift result of `agent run` carry `injection_suspect: [{text, match}]` (at most 5, absent when none)
+whenever such a block is in the text: `ignore_instructions`, `addresses_ai`, `system_prompt`,
+`new_instructions`, `hide_from_user`, `exfiltrate`. Nothing is hidden or blocked, the text stays where it was;
+the agent sees the mark next to it and treats the block as data. The patterns are narrow on purpose: a page
+*about* AI agents or system prompts is not flagged.
+
 ### Session Management
 
 ```bash
@@ -946,6 +1029,50 @@ CDPILOT_TIMEOUT=60 cdpilot run flow.cdp   # default for every command (and each
 For `mcp` and `serve` the value is not applied to the long-running server
 itself; it is passed on to every tool call / request it runs.
 
+### Warm process (`CDPILOT_DAEMON=1`)
+
+Every cdpilot call is a fresh process: node starts (~0.1 s), Python imports the
+core (~0.15 s) and a CDP session is set up (~0.5 s) before the command itself
+runs — a browser paints a page in 20 ms, `cdpilot go` took about a second
+(measurements: `.claude/docs/perf-taban-2026-11-08.md`). With
+`CDPILOT_DAEMON=1` the launcher keeps one warm Python process per project and
+environment and hands page commands to it over a Unix socket; the process keeps
+the module and its event loop between calls, so the second and later calls skip
+the start-up cost.
+
+```bash
+export CDPILOT_DAEMON=1
+cdpilot go https://example.com      # first call: fresh process, starts the daemon
+cdpilot content                     # served warm
+cdpilot daemon status               # pid, requests served, uptime, socket
+cdpilot daemon stop                 # stop every running daemon (they also leave after 30 min idle)
+```
+
+Output, exit codes, the session log and recordings are the same either way:
+each request runs as its own process would (the caller's argv, cwd,
+environment and stdin; module state reset between requests; exit-time hooks
+run at request end; the CDP connections a command opened are closed at request
+end, as a process exit closed them, so no viewport, throttle or event state
+leaks into the next command). Closing the client (Ctrl+C) cancels the running
+command. The launcher runs a fresh process instead whenever the daemon is
+missing, busy with another call, of another version (that one is asked to
+leave), set up for a port or profile the registry no longer names, or the
+command is not a page command: `launch`, `stop`, `connect`, `mcp`, `serve`,
+`watch`, `replay`, `run`, `captcha-wait` and the other lifecycle commands, and
+anything with `--timeout`. Nothing is ever executed twice. POSIX only for now;
+the socket lives in `$CDPILOT_HOME/daemon/` (or `$XDG_RUNTIME_DIR` / a private
+temp directory when that path is too long for a Unix socket), 0600, and is used
+only when it and its directory belong to you. `CDPILOT_DAEMON_IDLE=<seconds>`
+sets the idle exit (default 1800). Opt-in in this release; the default may
+change once two weeks of use show no difference in error rates.
+
+The MCP server (`cdpilot mcp`) reads the same variable: with `CDPILOT_DAEMON=1`
+in its environment it runs each tool call in the server process the same way (the
+same executor, no socket involved) instead of starting a Python process per
+call — ~400 ms → ~10 ms before the CDP work. Lifecycle tools and a project
+configuration that moved since the server started still run fresh; a call past
+30 s is cancelled at its next async step. See "Agent mode over MCP" above.
+
 ### Session log
 
 Every command (and every MCP tool call) appends one JSON line to a local,

package/bin/cdpilot.js

@@ -19,6 +19,309 @@ const os = require('os');
 
 const SCRIPT = path.join(__dirname, '..', 'src', 'cdpilot.py');
 const VERSION = require('../package.json').version;
+const SRC_DIR = path.join(__dirname, '..', 'src');
+
+// Python runs src/cdpilot.py through the import system (runpy) instead of as a
+// script: a script named on the command line is recompiled on every call —
+// 0.15 s of the ~0.3 s Python start-up measured on 2026-11-08 for the 23k-line
+// file — while an imported module keeps its bytecode in src/__pycache__/.
+// sys.argv ends up exactly as for `python cdpilot.py <args>` (alter_sys), and
+// an unwritable src/ only means Python skips the cache, never an error.
+// An interpreter started with -c puts '' (the working directory) first on
+// sys.path, so a runpy.py or json.py planted in an untrusted checkout would run
+// before cdpilot does (2026-11-10 review); the loader drops that entry before
+// any other import. `python src/cdpilot.py` had src/ there instead.
+const PY_LOADER = "import sys; sys.path[:] = [p for p in sys.path if p]; sys.path.insert(0, sys.argv[1]); del sys.argv[1]; "
+  + "import runpy; runpy.run_module('cdpilot', run_name='__main__', alter_sys=True)";
+function pyArgs(...args) {
+  return ['-c', PY_LOADER, SRC_DIR, ...args];
+}
+
+// The interpreter choice is remembered in CDPILOT_HOME/python.json for a day:
+// probing candidates with `--version` cost 50-150 ms per command (a shell and
+// a Python start per candidate tried). CDPILOT_PYTHON is part of the key, an
+// absolute path that vanished is re-probed, and a failed spawn clears the entry.
+const PYTHON_CACHE_TTL_MS = 24 * 3600 * 1000;
+function pythonCachePath() {
+  return path.join(cdpilotHome(), 'python.json');
+}
+function readPythonCache() {
+  try {
+    const c = JSON.parse(fs.readFileSync(pythonCachePath(), 'utf8'));
+    if (c.python && c.key === (process.env.CDPILOT_PYTHON || '')
+        && Date.now() - c.at < PYTHON_CACHE_TTL_MS
+        && (!path.isAbsolute(c.python) || fs.existsSync(c.python))) {
+      return c.python;
+    }
+  } catch {}
+  return null;
+}
+function writePythonCache(python) {
+  try {
+    fs.mkdirSync(cdpilotHome(), { recursive: true });
+    fs.writeFileSync(pythonCachePath(),
+      JSON.stringify({ python, key: process.env.CDPILOT_PYTHON || '', at: Date.now() }));
+  } catch {}
+}
+function clearPythonCache() {
+  try { fs.unlinkSync(pythonCachePath()); } catch {}
+}
+
+// ── Warm process (daemon) ──
+// CDPILOT_DAEMON=1: page commands go to one warm Python process per project
+// (src/cdpilot.py --_daemon-serve) over a Unix socket; it keeps the module and
+// the asyncio loop between calls — the CDP connections a request opened are
+// closed at its end, as a process exit closed them (2026-11-08: a
+// fresh process spent ~110 ms in node, ~140 ms starting Python and ~500 ms
+// setting the CDP session up before `go` even began). The client falls back
+// to a fresh process whenever the daemon is missing, busy (no hello within
+// DAEMON_HELLO_MS), of another version, or refuses the command — always before
+// anything ran, so a command never runs twice. POSIX only for now.
+const net = require('net');
+const DAEMON_SERVE_FLAG = '--_daemon-serve';
+const DAEMON_HELLO_MS = 150;
+// Mirrors DAEMON_SPAWN_CMDS in src/cdpilot.py (a test keeps them identical):
+// lifecycle, servers and forks, long-running loops, the daemon itself.
+const DAEMON_SPAWN_CMDS = new Set([
+  'launch', 'stop', 'stop-all', 'project-stop', 'connect', 'disconnect',
+  'serve', 'mcp', 'watch', 'setup', 'status', 'daemon', 'replay', 'run',
+  'blog', 'bot-auth', 'browser', 'test', 'trace', 'heal', 'health',
+  'session', 'sessions', 'session-close', 'projects', 'proxy', 'extensions',
+  'tls-proxy', 'captcha-wait', 'help', '--help', '-h']);
+// "cmd sub" pairs that run fresh while the command itself is served warm
+// (agent observe/act are page steps; agent twitter logs in and posts).
+const DAEMON_SPAWN_SUBCMDS = new Set(['agent twitter']);
+
+function daemonEnabled() {
+  return process.env.CDPILOT_DAEMON === '1' && process.platform !== 'win32';
+}
+
+function daemonEligible(cmd, args) {
+  if (!daemonEnabled() || !cmd || DAEMON_SPAWN_CMDS.has(cmd) || cmd.startsWith('--_')) return false;
+  if (DAEMON_SPAWN_SUBCMDS.has(`${cmd} ${args[1] || ''}`)) return false;
+  // --timeout ends its process with os._exit: a fresh process for it.
+  if (commandIndex(args) !== 0 || process.env.CDPILOT_TIMEOUT) return false;
+  return true;
+}
+
+// stdin a command reads (cmd_batch: always; cmd_check: without an argument)
+// travels inside the request; the daemon has no terminal.
+function daemonStdin(cmd, args) {
+  if (process.stdin.isTTY) return undefined;
+  if (cmd !== 'batch' && !(cmd === 'check' && args.length === 1)) return undefined;
+  try { return fs.readFileSync(0, 'utf8'); } catch { return ''; }
+}
+
+// The daemon is keyed by everything src/cdpilot.py reads at import time, so a
+// request never meets a process set up for another project, port, browser,
+// home or interpreter: a different key is a different socket and daemon.
+function daemonKey(env, python) {
+  const parts = { python, version: VERSION, src: SRC_DIR, home: env.HOME || '' };
+  for (const k of Object.keys(env).sort()) {
+    if (k.startsWith('CDPILOT_') || k.startsWith('CDP_') || k === 'CHROME_BIN') parts[k] = env[k];
+  }
+  return require('crypto').createHash('sha1').update(JSON.stringify(parts)).digest('hex').slice(0, 16);
+}
+
+// sun_path holds 104 bytes on macOS: a long CDPILOT_HOME moves the socket to
+// a private per-user directory — $XDG_RUNTIME_DIR when set (Linux desktops),
+// else one under the temp dir (the key still includes the home).
+function daemonDirs() {
+  const uid = typeof process.getuid === 'function' ? process.getuid() : 0;
+  const runtime = process.env.XDG_RUNTIME_DIR
+    ? path.join(process.env.XDG_RUNTIME_DIR, 'cdpilot-daemon')
+    : path.join(os.tmpdir(), `cdpilot-${uid}-daemon`);
+  return [path.join(cdpilotHome(), 'daemon'), runtime];
+}
+
+function daemonSockPath(key) {
+  const [home, runtime] = daemonDirs();
+  const p = path.join(home, `${key}.sock`);
+  return Buffer.byteLength(p) <= 100 ? p : path.join(runtime, `${key}.sock`);
+}
+
+// A socket is only used when its directory and the socket itself belong to
+// this user and nobody else may write there: in a shared temp dir another
+// user could otherwise plant a fake daemon and receive argv, cwd and stdin.
+function daemonPathSafe(sockPath) {
+  if (typeof process.getuid !== 'function') return true;
+  const uid = process.getuid();
+  try {
+    const dir = fs.lstatSync(path.dirname(sockPath));
+    if (!dir.isDirectory() || dir.uid !== uid || (dir.mode & 0o077) !== 0) return false;
+  } catch (e) {
+    return e.code === 'ENOENT';  // no directory yet: startDaemon creates it 0700
+  }
+  try {
+    const st = fs.lstatSync(sockPath);
+    return st.isSocket() && st.uid === uid;
+  } catch (e) {
+    return e.code === 'ENOENT';  // no socket yet: the daemon may be started here
+  }
+}
+
+// One request on one connection. Resolves {handled: true, code} when the
+// daemon ran the command (every output frame went through onFrame), or
+// {handled: false, reason} when nothing ran and the caller must spawn.
+function daemonRequest(sockPath, payload, onFrame) {
+  return new Promise((resolve) => {
+    let settled = false, hello = false, buf = '', scanFrom = 0, exitCode = null;
+    const done = (v) => { if (!settled) { settled = true; resolve(v); } };
+    if (!daemonPathSafe(sockPath)) { done({ handled: false, reason: 'unsafe' }); return; }
+    const sock = net.createConnection(sockPath);
+    sock.setEncoding('utf8');
+    const timer = setTimeout(() => {
+      if (!hello) { sock.destroy(); done({ handled: false, reason: 'busy' }); }
+    }, DAEMON_HELLO_MS);
+    sock.on('error', (e) => {
+      clearTimeout(timer);
+      done(hello ? { handled: true, code: 1, error: `daemon connection failed: ${e.message}` }
+                 : { handled: false, reason: e.code || 'error' });
+    });
+    sock.on('data', (chunk) => {
+      buf += chunk;
+      let nl;
+      while ((nl = buf.indexOf('\n', scanFrom)) >= 0) {
+        const line = buf.slice(0, nl);
+        buf = buf.slice(nl + 1);
+        scanFrom = 0;
+        let msg;
+        try { msg = JSON.parse(line); } catch { continue; }
+        if (!hello) {
+          hello = true;
+          clearTimeout(timer);
+          if (msg.version !== VERSION) {
+            // An older install's daemon: ask it to leave, run this call fresh.
+            sock.end(JSON.stringify({ op: 'shutdown' }) + '\n');
+            done({ handled: false, reason: 'version' });
+            return;
+          }
+          sock.write(JSON.stringify(payload) + '\n');
+          continue;
+        }
+        if (msg.fallback !== undefined) {
+          done({ handled: false, reason: String(msg.fallback) });
+          sock.destroy();
+          return;
+        }
+        if (msg.exit !== undefined) { exitCode = msg.exit; continue; }
+        onFrame(msg);
+      }
+      scanFrom = buf.length;  // a frame longer than one chunk: do not rescan it
+    });
+    sock.on('close', () => {
+      clearTimeout(timer);
+      if (exitCode !== null) done({ handled: true, code: exitCode });
+      else done(hello ? { handled: true, code: 1, error: 'connection to the daemon was lost' }
+                      : { handled: false, reason: 'closed' });
+    });
+  });
+}
+
+// Fork the warm process for this key, detached; at most once per 5 s. The
+// stamp is created exclusively (no symlink following, no second starter).
+function startDaemon(sockPath, python, env) {
+  if (!daemonPathSafe(sockPath)) return false;
+  const stamp = `${sockPath}.starting`;
+  try {
+    fs.mkdirSync(path.dirname(sockPath), { recursive: true, mode: 0o700 });
+    let fd;
+    try {
+      fd = fs.openSync(stamp, 'wx', 0o600);
+    } catch (e) {
+      if (e.code !== 'EEXIST') return false;
+      try { if (Date.now() - fs.lstatSync(stamp).mtimeMs < 5000) return false; } catch { return false; }
+      fs.unlinkSync(stamp);  // a starter that never got to bind: try once more
+      fd = fs.openSync(stamp, 'wx', 0o600);
+    }
+    fs.writeSync(fd, String(process.pid));
+    fs.closeSync(fd);
+    const child = spawn(python, pyArgs(DAEMON_SERVE_FLAG, sockPath),
+      { detached: true, stdio: 'ignore', env });
+    child.on('error', () => {});
+    child.unref();
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+function daemonPing(sockPath) {
+  return new Promise((resolve) => {
+    let pong = null;
+    daemonRequest(sockPath, { op: 'ping' }, (m) => { if (m.pong) pong = m; })
+      .then(() => resolve(pong));
+  });
+}
+
+function listDaemonSockets() {
+  const out = [];
+  for (const dir of daemonDirs()) {
+    let names = [];
+    try { names = fs.readdirSync(dir); } catch { continue; }
+    for (const n of names) if (n.endsWith('.sock')) out.push(path.join(dir, n));
+  }
+  return out;
+}
+
+// `cdpilot daemon start|stop|status`
+async function daemonCommand(sub, python, env) {
+  const what = sub[0] || 'status';
+  const mine = daemonSockPath(daemonKey(env, python));
+  if (what === 'start') {
+    if (process.platform === 'win32') {
+      console.error('cdpilot daemon: not available on Windows yet');
+      return 1;
+    }
+    let pong = await daemonPing(mine);
+    if (!pong) {
+      startDaemon(mine, python, env);
+      for (let i = 0; i < 30 && !pong; i++) {
+        await new Promise((r) => setTimeout(r, 100));
+        pong = await daemonPing(mine);
+      }
+    }
+    if (!pong) {
+      console.error('cdpilot daemon: did not start (see `cdpilot daemon status`)');
+      return 1;
+    }
+    console.log(`daemon running: pid ${pong.pid}, socket ${mine}`);
+    if (!daemonEnabled()) console.log('set CDPILOT_DAEMON=1 to send commands to it');
+    return 0;
+  }
+  if (what === 'stop') {
+    let n = 0;
+    for (const sock of listDaemonSockets()) {
+      const r = await daemonRequest(sock, { op: 'shutdown' }, () => {});
+      if (r.handled) n++;
+      else if (r.reason === 'ECONNREFUSED' || r.reason === 'ENOENT') {
+        try { fs.unlinkSync(sock); } catch {}  // nobody listens: a leftover of a crash
+      }  // busy (no hello in time): leave it, it is serving a command
+    }
+    console.log(n ? `stopped ${n} daemon${n === 1 ? '' : 's'}` : 'no daemon running');
+    return 0;
+  }
+  if (what === 'status') {
+    const socks = listDaemonSockets();
+    let live = 0;
+    for (const sock of socks) {
+      const pong = await daemonPing(sock);
+      if (!pong) continue;
+      live++;
+      const up = Math.max(0, Math.round(Date.now() / 1000 - pong.started));
+      console.log(`${sock === mine ? '*' : ' '} pid ${pong.pid}  served ${pong.served}  up ${up}s  idle-exit ${pong.idle}s  ${sock}`);
+    }
+    if (!live) {
+      console.log('no daemon running' + (daemonEnabled() ? '' : ' (CDPILOT_DAEMON=1 starts one on the next command)'));
+      console.log(`  socket: ${mine}`);
+    } else if (socks.includes(mine)) {
+      console.log('* = this project and environment');
+    }
+    return 0;
+  }
+  console.error(`cdpilot daemon: unknown subcommand '${what}' (start | stop | status)`);
+  return 2;
+}
 
 // CDPILOT_HOME resolution — must match src/cdpilot.py exactly:
 //   CDPILOT_HOME = os.environ.get("CDPILOT_HOME") or os.path.expanduser("~/.cdpilot")
@@ -86,6 +389,8 @@ function findBrowser() {
 // ── Python Detection ──
 
 function findPython() {
+  const cached = readPythonCache();
+  if (cached) return cached;
   // cdpilot.py uses PEP 604 unions (dict | None) → requires Python 3.10+.
   // Prefer version-specific + Homebrew interpreters so a stale default python3
   // (e.g. macOS 3.9) is skipped instead of selected and crashing at runtime.
@@ -100,6 +405,7 @@ function findPython() {
       const ver = execSync(`${cmd} --version 2>&1`, { stdio: 'pipe' }).toString().trim();
       const match = ver.match(/(\d+)\.(\d+)/);
       if (match && (parseInt(match[1]) > 3 || (parseInt(match[1]) === 3 && parseInt(match[2]) >= 10))) {
+        writePythonCache(cmd);
         return cmd;
       }
     } catch {}
@@ -374,7 +680,7 @@ function botAuthLabel(port) {
   if (!signer) return fs.existsSync(path.join(home, 'bot-auth', 'config.json')) ? 'bot-auth: off' : null;
   const python = findPython();
   if (!python) return 'bot-auth: off';
-  const r = spawnSync(python, [SCRIPT, '--_bot-auth-label'], {
+  const r = spawnSync(python, pyArgs('--_bot-auth-label'), {
     encoding: 'utf-8', timeout: 20000,
     env: { ...process.env, CDP_PORT: String(port), CDPILOT_LOG: '0' },
   });
@@ -453,6 +759,12 @@ function showHelp() {
     An auto-launched (or MCP-launched) browser closes after 15 min without a
                        cdpilot command or page change (CDPILOT_IDLE_CLOSE=<minutes>,
                        0 = never); an explicit launch stays open unless asked (below).
+    CDPILOT_DAEMON=1   Keep one warm Python process per project and send page
+                       commands to it over a local socket (browser-free command
+                       ~270 -> ~140 ms, content/eval ~360 -> ~110 ms, M1 Max;
+                       a fresh process when it is missing or busy; not with
+                       --timeout; 'daemon status|stop'; idle exit after
+                       CDPILOT_DAEMON_IDLE seconds, default 1800).
 
   SETUP
     setup              Auto-detect browser, create isolated profile
@@ -590,6 +902,10 @@ function showHelp() {
                        --load-extension, CfT does not. Used instead of Chrome
                        while dev extensions are registered. Not for stealth.
     health             JSON status: alive, port, tabs, browser, today's crashes
+    daemon start|stop|status
+                       The warm process behind CDPILOT_DAEMON=1: start it ahead
+                       of time, stop every running one, or list them (pid,
+                       requests served, uptime, socket).
 
   PROJECTS
     projects           List all project browser instances
@@ -821,22 +1137,7 @@ if (cmd === 'setup') {
   process.exit(0);
 }
 
-if (cmd === 'status') {
-  runStatus();
-  // Don't exit immediately — let http callback complete
-} else {
-  // Pre-flight check on first run or 'launch' command
-  if (cmd === 'launch') {
-    preflight();
-  }
-
-  // Delegate to Python
-  const python = findPython();
-  if (!python) {
-    console.error('Error: Python 3.10+ required. Install: https://www.python.org/downloads/');
-    process.exit(1);
-  }
-
+function pythonEnv() {
   const browser = findBrowser();
   const config = resolveProjectConfig();
 
@@ -861,11 +1162,20 @@ if (cmd === 'status') {
     // (Chrome -> Chrome for Testing) on top of it.
     env.CDPILOT_CHROME_BIN_AUTO = '1';
   }
+  return env;
+}
 
-  const child = spawn(python, [SCRIPT, ...args], {
+function spawnPython(python, args, env) {
+  const child = spawn(python, pyArgs(...args), {
     stdio: 'inherit',
     env,
   });
+  child.on('error', (err) => {
+    // A remembered interpreter that is gone: forget it so the next call probes again.
+    clearPythonCache();
+    console.error(`cdpilot: could not start ${python}: ${err.message}`);
+    process.exit(1);
+  });
 
   // A child killed by a signal reports code === null. `code || 0` turned that
   // into success, so an OOM-killed or SIGKILLed run looked fine to scripts
@@ -878,3 +1188,50 @@ if (cmd === 'status') {
     process.exit(code ?? 0);
   });
 }
+
+if (cmd === 'status') {
+  runStatus();
+  // Don't exit immediately — let http callback complete
+} else {
+  // Pre-flight check on first run or 'launch' command
+  if (cmd === 'launch') {
+    preflight();
+  }
+
+  // Delegate to Python
+  const python = findPython();
+  if (!python) {
+    console.error('Error: Python 3.10+ required. Install: https://www.python.org/downloads/');
+    process.exit(1);
+  }
+
+  const env = pythonEnv();
+
+  if (cmd === 'daemon') {
+    daemonCommand(args.slice(1), python, env).then((code) => { process.exitCode = code; });
+  } else if (daemonEligible(cmd, args)) {
+    const sockPath = daemonSockPath(daemonKey(env, python));
+    // env: the daemon applies the caller's environment to the request (proxy
+    // and solver keys, PATH, TZ … are read when a command runs, not at import).
+    const payload = { argv: args, cwd: process.cwd(), env };
+    const stdin = daemonStdin(cmd, args);
+    if (stdin !== undefined) payload.stdin = stdin;
+    daemonRequest(sockPath, payload, (m) => {
+      if (m.o !== undefined) process.stdout.write(m.o);
+      if (m.e !== undefined) process.stderr.write(m.e);
+    }).then((r) => {
+      if (r.handled) {
+        if (r.error) console.error(`cdpilot: ${r.error}`);
+        process.exitCode = r.code;
+        return;
+      }
+      // No daemon (yet): start one for the next call; this call runs fresh.
+      if (['ENOENT', 'ECONNREFUSED', 'version', 'closed', 'stale'].includes(r.reason)) {
+        startDaemon(sockPath, python, env);
+      }
+      spawnPython(python, args, env);
+    });
+  } else {
+    spawnPython(python, args, env);
+  }
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "cdpilot",
-  "version": "0.9.5",
+  "version": "0.9.6",
   "mcpName": "io.github.mehmetnadir/cdpilot",
   "description": "Zero-dependency browser automation CLI. Raw CDP, 70+ commands, friction ladder, 3-tier stealth, CAPTCHA + press-and-hold solvers, proxy pools, MCP server. No Puppeteer/Playwright/Selenium.",
   "bin": {