muse-crew 0.14.9 → 0.14.11

package/lib/see-act.js

@@ -1,9 +1,46 @@
 #!/usr/bin/env node
 // see-act.js — single-step browser driver for experiential QA.
 //
-// The agent closes the OODA loop: run one step, READ the screenshot or aria
-// output, decide the next step. Each invocation launches a fresh browser,
-// performs exactly one action, prints one JSON line to stdout, and exits.
+// ONE-SHOT (the original contract, frozen): the agent closes the OODA loop:
+// run one step, READ the screenshot or aria output, decide the next step.
+// Each invocation launches a fresh browser, performs exactly one action,
+// prints one JSON line to stdout, and exits.
+//
+// SESSION PROTOCOL (blocker 41, 2026-09-22): the one-shot driver's fresh
+// browser per invocation cannot drive multi-step in-page flows (open a deck,
+// then click Study — the second step needs the first step's page state).
+// The session protocol keeps ONE Chromium + page alive across invocations:
+//
+//   node see-act.js session-start --name <name> --url <url> [--session-dir <dir>]
+//       [--log <ooda-log.jsonl>] [--viewport desktop|mobile] [--timeout-ms <n>]
+//       [--idle-ttl-ms <n>]
+//     Launches Chromium once (same loopback-proxy stack as one-shot),
+//     navigates to --url, and spawns a detached daemon holding the browser.
+//     Prints one JSON line {ok:true, session, session_dir, control_port}.
+//     The daemon exits after --idle-ttl-ms (default 10 min) with no act.
+//
+//   node see-act.js session-act --name <name> --attempt <id> [--session-dir <dir>]
+//       [--timeout-ms <n>] <aria|shot|click|scroll|type> [args]
+//     Performs ONE action inside the living page state, appends one JSON
+//     line to the session's ooda-log (the --log path from session-start,
+//     default <session-dir>/<name>/ooda-log.jsonl) in the exact
+//     append-ooda-step.js schema {step, attempt, action, args, exit,
+//     screenshot, observation}, prints the action's JSON result, and exits
+//     with the action's exit code (0/2/3, same meanings as one-shot).
+//
+//   node see-act.js session-end --name <name> [--session-dir <dir>]
+//     Closes the browser, prints the session summary {ok:true, session,
+//     log, steps}. The session dir (and its ooda-log) is kept as evidence.
+//
+// The one-shot invocation shape is untouched by the session protocol: same
+// flags, same JSON, same exit codes, same archive behavior. The session
+// daemon duplicates the action implementations deliberately — the one-shot
+// code path is frozen and never refactored under a live contract.
+//
+// Session state lives in <session-dir>/<name>/session.json (control port,
+// daemon pid, status). <session-dir> defaults to SEE_ACT_SESSION_DIR or
+// ./.see-act-sessions. Session names are [A-Za-z0-9_-]+. The control server
+// binds 127.0.0.1 only.
 //
 // Self-contained: spawns its own loopback forward proxy on an ephemeral port
 // (Chromium's Local Network Access checks block direct loopback navigation),
@@ -34,9 +71,10 @@
 
 import { createServer, request as httpRequest } from "node:http";
 import { request as httpsRequest } from "node:https";
-import { existsSync, mkdirSync, readFileSync, writeFileSync, copyFileSync } from "node:fs";
+import { existsSync, mkdirSync, readFileSync, writeFileSync, copyFileSync, renameSync, appendFileSync } from "node:fs";
 import { join, dirname, resolve } from "node:path";
 import { createRequire } from "node:module";
+import { spawn } from "node:child_process";
 
 const cjsRequire = createRequire(import.meta.url);
 
@@ -65,6 +103,11 @@ function parseArgs(argv) {
     else if (a === "--y") out.y = argv[++i];
     else if (a === "--text") out.text = argv[++i];
     else if (a === "--full") out.full = true;
+    else if (a === "--name") out.name = argv[++i];
+    else if (a === "--session-dir") out.sessionDir = argv[++i];
+    else if (a === "--attempt") out.attempt = argv[++i];
+    else if (a === "--log") out.log = argv[++i];
+    else if (a === "--idle-ttl-ms") out.idleTtlMs = parseInt(argv[++i], 10);
     else if (!a.startsWith("--") && out.action === null) out.action = a;
     else rest.push(a);
   }
@@ -190,13 +233,580 @@ function startProxy() {
   });
 }
 
+// === Session protocol (blocker 41, 2026-09-22) ===
+// A session is one Chromium + page held alive by a detached daemon process.
+// The daemon owns a loopback control server (127.0.0.1 only); session-act
+// POSTs one action at a time and the daemon performs it on the living page.
+// The one-shot code path above is frozen — the daemon duplicates the action
+// implementations deliberately rather than refactoring a live contract.
+
+const SESSION_NAME_RE = /^[A-Za-z0-9][A-Za-z0-9_-]*$/;
+const DEFAULT_IDLE_TTL_MS = 600000; // 10 min with no act -> daemon exits
+const SESSION_START_POLLS = 120; // 120 x 250ms = 30s for the daemon to bind
+const SESSION_ACTIONS = { aria: 1, shot: 1, click: 1, scroll: 1, type: 1 };
+
+const sleep = (ms) => new Promise((r) => setTimeout(r, ms));
+
+function resolveSessionDir(explicit) {
+  const d = ((explicit || process.env.SEE_ACT_SESSION_DIR || "").trim());
+  return resolve(d || join(process.cwd(), ".see-act-sessions"));
+}
+
+function readSessionJson(p) {
+  try {
+    return JSON.parse(readFileSync(p, "utf8"));
+  } catch (e) {
+    return null;
+  }
+}
+
+// Atomic state write: the session-start poller and the daemon never see a
+// torn session.json.
+function writeSessionJson(p, obj) {
+  const tmp = p + ".tmp";
+  writeFileSync(tmp, JSON.stringify(obj) + "\n");
+  renameSync(tmp, p);
+}
+
+function httpJson(options, body, timeoutMs) {
+  return new Promise((resolve, reject) => {
+    const req = httpRequest(options, (res) => {
+      let b = "";
+      res.on("data", (c) => { b += c; });
+      res.on("end", () => {
+        try {
+          resolve({ status: res.statusCode, body: JSON.parse(b) });
+        } catch (e) {
+          reject(new Error("unparseable daemon response"));
+        }
+      });
+    });
+    req.on("error", reject);
+    req.setTimeout(timeoutMs, () => { req.destroy(new Error("daemon request timed out")); });
+    if (body !== undefined) {
+      const s = JSON.stringify(body);
+      req.setHeader("content-type", "application/json");
+      req.setHeader("content-length", Buffer.byteLength(s));
+      req.write(s);
+    }
+    req.end();
+  });
+}
+
+function daemonPing(port) {
+  return httpJson({ hostname: "127.0.0.1", port: port, path: "/ping", method: "GET" }, undefined, 2000)
+    .then((r) => r.status === 200 && r.body === "pong");
+}
+
+// Session-start preflights the environment in THIS process (same env the
+// daemon inherits) so a missing playwright-core/Chromium reports exit 3
+// NOT POSSIBLE immediately instead of dying inside the detached daemon.
+function sessionStartPreflight() {
+  try { cjsRequire("playwright-core"); }
+  catch (e) {
+    const envDir = (process.env.PLAYWRIGHT_CORE_DIR || "").trim();
+    let okp = false;
+    if (envDir) {
+      try { cjsRequire(join(envDir, "playwright-core")); okp = true; } catch (e2) { /* fall through */ }
+      if (!okp) { try { cjsRequire(envDir); okp = true; } catch (e3) { /* fall through */ } }
+    }
+    if (!okp) {
+      fail(3, {
+        ok: false,
+        not_possible: "NOT POSSIBLE: playwright-core is not installed or not resolvable. " +
+          "Install it (npm install playwright-core) or set PLAYWRIGHT_CORE_DIR.",
+      });
+    }
+  }
+  const envPath = (process.env.CHROME_PATH || "").trim();
+  if (!((envPath && existsSync(envPath)) || existsSync("/opt/meta-chromium/chrome"))) {
+    fail(3, {
+      ok: false,
+      not_possible: "NOT POSSIBLE: no Chromium binary found. " +
+        "Set CHROME_PATH to a Chromium/Chrome executable.",
+    });
+  }
+}
+
+async function runSessionStart(args) {
+  if (!args.name || !SESSION_NAME_RE.test(args.name)) {
+    fail(2, { ok: false, error: "session-start requires --name <letters, digits, _-> (got: " + (args.name || "none") + ")" });
+  }
+  if (!args.url) {
+    fail(2, { ok: false, error: "session-start requires --url <url>" });
+  }
+  if (!VIEWPORTS[args.viewport]) {
+    fail(2, { ok: false, error: "unknown viewport: " + args.viewport + " (desktop|mobile)" });
+  }
+  sessionStartPreflight();
+  const sessionDir = resolveSessionDir(args.sessionDir);
+  const sessPath = join(sessionDir, args.name);
+  const statePath = join(sessPath, "session.json");
+  const existing = readSessionJson(statePath);
+  if (existing && existing.status === "running" && existing.controlPort) {
+    const alive = await daemonPing(existing.controlPort).catch(() => false);
+    if (alive) {
+      fail(2, { ok: false, error: "session already running: " + args.name });
+    }
+    // Stale state (daemon died without session-end): fall through and replace.
+  }
+  mkdirSync(sessPath, { recursive: true });
+  const logPath = args.log ? resolve(args.log) : join(sessPath, "ooda-log.jsonl");
+  try {
+    mkdirSync(dirname(logPath), { recursive: true });
+  } catch (e) {
+    fail(2, { ok: false, error: "cannot create ooda-log dir: " + dirname(logPath) });
+  }
+  const idleTtlMs = (Number.isFinite(args.idleTtlMs) && args.idleTtlMs > 0) ? args.idleTtlMs : DEFAULT_IDLE_TTL_MS;
+  const state = {
+    name: args.name, url: args.url, viewport: args.viewport, timeoutMs: args.timeoutMs,
+    log: logPath, idleTtlMs: idleTtlMs, status: "starting", pid: null, controlPort: null,
+  };
+  writeSessionJson(statePath, state);
+  const child = spawn(process.execPath, [process.argv[1], "--daemon", statePath], {
+    detached: true, stdio: "ignore",
+  });
+  child.unref();
+  let running = null;
+  for (let i = 0; i < SESSION_START_POLLS; i++) {
+    await sleep(250);
+    const st = readSessionJson(statePath);
+    if (st && st.status === "running" && st.controlPort) { running = st; break; }
+    if (st && st.status === "failed") {
+      fail(3, { ok: false, not_possible: st.error || "NOT POSSIBLE: session daemon failed to start" });
+    }
+  }
+  if (!running) {
+    const st = readSessionJson(statePath);
+    if (st && st.pid) { try { process.kill(st.pid, "SIGKILL"); } catch (e) { /* already gone */ } }
+    fail(2, { ok: false, error: "session daemon did not become ready in time: " + args.name });
+  }
+  const pong = await daemonPing(running.controlPort).catch(() => false);
+  if (!pong) {
+    fail(2, { ok: false, error: "session daemon not answering: " + args.name });
+  }
+  process.stdout.write(JSON.stringify({
+    ok: true, session: args.name, session_dir: sessPath,
+    url: args.url, viewport: args.viewport, control_port: running.controlPort,
+  }) + "\n");
+  process.exit(0);
+}
+
+async function runSessionAct(args) {
+  if (!args.name || !SESSION_NAME_RE.test(args.name)) {
+    fail(2, { ok: false, error: "session-act requires --name <session>" });
+  }
+  if (!args.attempt) {
+    fail(2, { ok: false, error: "session-act requires --attempt <id> (the ooda-log attempt identity)" });
+  }
+  if (!SESSION_ACTIONS[args.action]) {
+    fail(2, { ok: false, error: "unknown action: " + args.action + " (aria|shot|click|scroll|type)" });
+  }
+  const needsShot = args.action !== "aria";
+  const archiveDir = resolveArchiveDir();
+  if (needsShot && !args.out && !archiveDir) {
+    fail(2, { ok: false, error: "action " + args.action + " requires --out <png> (or set SEE_ACT_ARCHIVE_DIR to archive automatically)" });
+  }
+  if (args.action === "click" && !args.selector) {
+    fail(2, { ok: false, error: "click requires --selector <css>" });
+  }
+  if (args.action === "type" && (!args.selector || args.text === undefined)) {
+    fail(2, { ok: false, error: "type requires --selector <css> --text <text>" });
+  }
+  const statePath = join(resolveSessionDir(args.sessionDir), args.name, "session.json");
+  const st = readSessionJson(statePath);
+  if (!st) {
+    fail(2, { ok: false, error: "no such session: " + args.name });
+  }
+  if (st.status !== "running" || !st.controlPort) {
+    fail(2, { ok: false, error: "session not running: " + args.name + " (status: " + (st.status || "unknown") + ")" });
+  }
+  const actTimeoutMs = Number.isFinite(args.timeoutMs) ? args.timeoutMs : st.timeoutMs;
+  let resp;
+  try {
+    resp = await httpJson(
+      { hostname: "127.0.0.1", port: st.controlPort, path: "/act", method: "POST" },
+      {
+        action: args.action,
+        args: {
+          out: args.out || null, selector: args.selector || null, y: args.y || null,
+          text: args.text, full: !!args.full, viewport: st.viewport, timeoutMs: actTimeoutMs,
+        },
+        attempt: args.attempt,
+        archiveDir: archiveDir,
+      },
+      actTimeoutMs + 30000
+    );
+  } catch (e) {
+    fail(2, { ok: false, error: "session unreachable: " + args.name + " (" + ((e && e.message) || String(e)) + ")" });
+  }
+  process.stdout.write(JSON.stringify(resp.body.result) + "\n");
+  process.exit(resp.body.exit || 0);
+}
+
+async function runSessionEnd(args) {
+  if (!args.name || !SESSION_NAME_RE.test(args.name)) {
+    fail(2, { ok: false, error: "session-end requires --name <session>" });
+  }
+  const statePath = join(resolveSessionDir(args.sessionDir), args.name, "session.json");
+  const st = readSessionJson(statePath);
+  if (!st) {
+    fail(2, { ok: false, error: "no such session: " + args.name });
+  }
+  let summary = null;
+  if (st.status === "running" && st.controlPort) {
+    try {
+      const resp = await httpJson(
+        { hostname: "127.0.0.1", port: st.controlPort, path: "/end", method: "POST" },
+        undefined, 30000
+      );
+      summary = resp.body;
+    } catch (e) { /* daemon already gone — mark ended below */ }
+  }
+  // The session dir (and its ooda-log) is kept as evidence; only the state
+  // is marked ended so the name can be reused.
+  try {
+    writeSessionJson(statePath, Object.assign({}, st, { status: "ended", controlPort: null }));
+  } catch (e) { /* best effort */ }
+  if (summary && summary.ok) {
+    process.stdout.write(JSON.stringify(summary) + "\n");
+  } else {
+    process.stdout.write(JSON.stringify({
+      ok: true, session: args.name, ended: "daemon-unreachable",
+      note: "marked ended; the session dir and its ooda-log are preserved",
+    }) + "\n");
+  }
+  process.exit(0);
+}
+
+// Read the tail of a session ooda-log: the next step number, or the corruption
+// that must fail the act loudly BEFORE it performs (lost evidence fails loud).
+function readSessionLogTail(logPath) {
+  let raw;
+  try {
+    raw = readFileSync(logPath, "utf8");
+  } catch (e) {
+    return { corrupt: false, lastStep: 0 };
+  }
+  const lines = raw.split("\n").filter((l) => l.trim().length > 0);
+  if (lines.length === 0) return { corrupt: false, lastStep: 0 };
+  let last;
+  try {
+    last = JSON.parse(lines[lines.length - 1]);
+  } catch (e) {
+    return { corrupt: true, reason: "unparseable last line" };
+  }
+  if (!last || typeof last.step !== "number" || !Number.isFinite(last.step)) {
+    return { corrupt: true, reason: "last line carries no numeric step" };
+  }
+  return { corrupt: false, lastStep: last.step };
+}
+
+// The machine observation on a session ooda-log line: what the driver itself
+// saw, never agent prose. Same schema as append-ooda-step.js lines.
+function sessionMachineObservation(action, result) {
+  const parts = [];
+  if (action === "aria" && Array.isArray(result.aria)) parts.push("elements:" + result.aria.length);
+  if (result.console_error_count) parts.push("console_errors:" + result.console_error_count);
+  return parts.join(" ");
+}
+
+// Daemon-side action implementations. Deliberately duplicated from the
+// one-shot path (which is frozen): the daemon acts on the LIVING page — no
+// navigation, no fresh proxy — and drains the console-error buffer per act.
+async function daemonPerformAction(page, action, a, ctx) {
+  const result = { ok: true, action: action, viewport: a.viewport };
+  async function capture(opts) {
+    const archivePath = ctx.archiveDir ? nextArchivePath(ctx.archiveDir, action, a.viewport) : null;
+    const dest = a.out || archivePath;
+    await page.screenshot(Object.assign({ path: dest }, opts));
+    if (a.out) result.out = a.out;
+    result.screenshot = dest;
+    if (archivePath && resolve(dest) !== archivePath) {
+      copyFileSync(dest, archivePath);
+      result.archived = archivePath;
+    } else if (archivePath) {
+      result.archived = archivePath;
+    }
+  }
+  if (action === "aria") {
+    const els = await page.evaluate(() => {
+      const out = [];
+      document.querySelectorAll("button, a, [role=button], [role=tab], input, select, textarea, h1, h2").forEach((el) => {
+        const t = (el.innerText || el.value || el.getAttribute("aria-label") || "").trim().slice(0, 80).replace(/\s+/g, " ");
+        if (t) out.push(el.tagName.toLowerCase() + ": " + t);
+      });
+      document.querySelectorAll("footer").forEach((el) => {
+        const t = (el.innerText || "").trim().slice(0, 300).replace(/\s+/g, " ");
+        if (t) out.push("footer: " + t);
+      });
+      return out.slice(0, 60);
+    });
+    result.aria = els;
+  } else if (action === "shot") {
+    await capture({ fullPage: !!a.full });
+    result.full_page = !!a.full;
+  } else if (action === "click") {
+    await page.click(a.selector, { timeout: a.timeoutMs });
+    await page.waitForTimeout(SETTLE_MS);
+    await capture({});
+    result.selector = a.selector;
+  } else if (action === "scroll") {
+    const y = a.y === undefined || a.y === null || a.y === "bottom" ? "bottom" : String(parseInt(a.y, 10));
+    await page.evaluate((yy) => {
+      const wantBottom = yy === "bottom";
+      const px = wantBottom ? 0 : parseInt(yy, 10);
+      let el = document.scrollingElement || document.body;
+      if (el.scrollHeight <= el.clientHeight + 1) {
+        let best = null, bestH = 0;
+        document.querySelectorAll("*").forEach((e) => {
+          if (e.scrollHeight > e.clientHeight + 50 && e.scrollHeight > bestH) { best = e; bestH = e.scrollHeight; }
+        });
+        if (best) el = best;
+      }
+      el.scrollTo(0, wantBottom ? el.scrollHeight : px);
+    }, y);
+    await page.waitForTimeout(1000);
+    await capture({});
+    result.y = y;
+  } else if (action === "type") {
+    await page.fill(a.selector, a.text, { timeout: a.timeoutMs });
+    await page.waitForTimeout(800);
+    await capture({});
+    result.selector = a.selector;
+  }
+  const errs = ctx.drainConsoleErrors();
+  result.console_errors = errs.slice(0, 10);
+  result.console_error_count = errs.length;
+  return result;
+}
+
+function readDaemonJsonBody(req) {
+  return new Promise((resolve, reject) => {
+    let b = "";
+    req.on("data", (c) => { b += c; });
+    req.on("end", () => {
+      try { resolve(JSON.parse(b)); }
+      catch (e) { reject(new Error("bad json body")); }
+    });
+    req.on("error", reject);
+  });
+}
+
+// The daemon: holds one Chromium + page, serves the control protocol on
+// 127.0.0.1, appends every act to the session ooda-log. Never returns;
+// exits 0 on session-end / idle timeout, 1 on startup failure (the state
+// file carries status:"failed" so session-start can report it).
+async function runDaemon(statePath) {
+  const st = readSessionJson(statePath);
+  if (!st || !st.url) {
+    process.stderr.write("see-act daemon: unreadable session state\n");
+    process.exit(1);
+  }
+  const daemonFail = (notPossible) => {
+    try {
+      writeSessionJson(statePath, Object.assign({}, st, { status: "failed", error: notPossible }));
+    } catch (e) { /* best effort */ }
+    process.exit(1);
+  };
+  try {
+    writeSessionJson(statePath, Object.assign({}, st, { pid: process.pid, status: "starting" }));
+  } catch (e) {
+    process.exit(1);
+  }
+  // Daemon-side environment resolution (mirrors loadPlaywright/findChromium,
+  // but reports through the state file instead of exiting with a JSON line
+  // on an ignored stdout).
+  let playwright = null;
+  try { playwright = cjsRequire("playwright-core"); } catch (e) { /* fall through */ }
+  if (!playwright) {
+    const envDir = (process.env.PLAYWRIGHT_CORE_DIR || "").trim();
+    if (envDir) {
+      try { playwright = cjsRequire(join(envDir, "playwright-core")); } catch (e) { /* fall through */ }
+      if (!playwright) { try { playwright = cjsRequire(envDir); } catch (e2) { /* fall through */ } }
+    }
+  }
+  if (!playwright) {
+    daemonFail("NOT POSSIBLE: playwright-core is not installed or not resolvable. " +
+      "Install it (npm install playwright-core) or set PLAYWRIGHT_CORE_DIR.");
+  }
+  const envPath = (process.env.CHROME_PATH || "").trim();
+  const exePath = (envPath && existsSync(envPath)) ? envPath
+    : existsSync("/opt/meta-chromium/chrome") ? "/opt/meta-chromium/chrome" : null;
+  if (!exePath) {
+    daemonFail("NOT POSSIBLE: no Chromium binary found. " +
+      "Set CHROME_PATH to a Chromium/Chrome executable.");
+  }
+
+  let proxy = null;
+  try {
+    proxy = await startProxy();
+  } catch (e) {
+    daemonFail("NOT POSSIBLE: could not start the loopback proxy: " + ((e && e.message) || String(e)));
+  }
+  let browser = null;
+  try {
+    browser = await playwright.chromium.launch({
+      executablePath: exePath,
+      args: ["--no-sandbox"],
+      proxy: { server: "http://127.0.0.1:" + proxy.port },
+    });
+  } catch (e) {
+    proxy.server.close();
+    daemonFail("NOT POSSIBLE: Chromium launch failed: " + ((e && e.message) || String(e)).slice(0, 300));
+  }
+  const page = await browser.newPage({ viewport: VIEWPORTS[st.viewport] || VIEWPORTS.desktop });
+  const consoleBuffer = [];
+  page.on("console", (msg) => {
+    if (msg.type() === "error") consoleBuffer.push(msg.text().slice(0, 300));
+  });
+  page.on("pageerror", (err) => {
+    consoleBuffer.push(String((err && err.message) || err).slice(0, 300));
+  });
+  const drainConsoleErrors = () => consoleBuffer.splice(0, consoleBuffer.length);
+  try {
+    await page.goto(st.url, { waitUntil: "domcontentloaded", timeout: st.timeoutMs });
+    await page.waitForLoadState("networkidle", { timeout: 15000 }).catch(() => {});
+    await page.waitForTimeout(SETTLE_MS);
+  } catch (e) {
+    await browser.close().catch(() => {});
+    proxy.server.close();
+    daemonFail("NOT POSSIBLE: session-start navigation failed: " + ((e && e.message) || String(e)).slice(0, 300));
+  }
+
+  let idleTimer = null;
+  let ended = false;
+  const server = createServer();
+  async function cleanup(reason) {
+    if (ended) return;
+    ended = true;
+    if (idleTimer) clearTimeout(idleTimer);
+    try {
+      const cur = readSessionJson(statePath) || st;
+      writeSessionJson(statePath, Object.assign({}, cur, { status: "ended", controlPort: null, ended_reason: reason }));
+    } catch (e) { /* best effort */ }
+    server.close();
+    await browser.close().catch(() => {});
+    proxy.server.close();
+  }
+  function armIdle() {
+    if (idleTimer) clearTimeout(idleTimer);
+    idleTimer = setTimeout(() => {
+      cleanup("idle-timeout").then(() => process.exit(0));
+    }, st.idleTtlMs);
+    if (idleTimer.unref) idleTimer.unref();
+  }
+  async function handleAct(body) {
+    if (!body || !SESSION_ACTIONS[body.action]) {
+      return { exit: 2, result: { ok: false, error: "unknown action: " + ((body && body.action) || "none") } };
+    }
+    const a = body.args || {};
+    // The log tail is validated BEFORE the act: corrupt evidence fails loud,
+    // never silently.
+    const tail = readSessionLogTail(st.log);
+    if (tail.corrupt) {
+      return { exit: 2, result: { ok: false, error: "session ooda-log corrupt (" + tail.reason + "): " + st.log } };
+    }
+    const step = tail.lastStep + 1;
+    let result, exit;
+    try {
+      result = await daemonPerformAction(page, body.action, a, {
+        archiveDir: body.archiveDir || null,
+        drainConsoleErrors: drainConsoleErrors,
+      });
+      exit = 0;
+    } catch (e) {
+      result = { ok: false, error: "action failed: " + ((e && e.message) || String(e)).slice(0, 500) };
+      exit = 2;
+    }
+    const line = {
+      step: step,
+      attempt: body.attempt || null,
+      action: body.action,
+      args: { selector: a.selector || undefined, y: a.y || undefined, text: a.text, full: !!a.full },
+      exit: exit,
+      screenshot: result.screenshot || null,
+      observation: exit === 0 ? sessionMachineObservation(body.action, result) : (result.error || ""),
+    };
+    try {
+      appendFileSync(st.log, JSON.stringify(line) + "\n");
+    } catch (e) {
+      return { exit: 2, result: { ok: false, error: "session ooda-log not writable: " + st.log } };
+    }
+    return { exit: exit, result: result };
+  }
+  server.on("request", async (req, res) => {
+    armIdle();
+    if (req.method === "GET" && req.url === "/ping") {
+      res.writeHead(200, { "content-type": "application/json" }); res.end(JSON.stringify("pong")); return;
+    }
+    if (req.method === "POST" && req.url === "/act") {
+      let body;
+      try { body = await readDaemonJsonBody(req); }
+      catch (e) { res.writeHead(400); res.end("bad json body"); return; }
+      const handled = await handleAct(body);
+      res.writeHead(200, { "content-type": "application/json" });
+      res.end(JSON.stringify(handled));
+      return;
+    }
+    if (req.method === "POST" && req.url === "/end") {
+      const tail = readSessionLogTail(st.log);
+      const summary = {
+        ok: true, session: st.name, log: st.log,
+        steps: tail.corrupt ? null : tail.lastStep, ended: "client-request",
+      };
+      res.writeHead(200, { "content-type": "application/json" });
+      res.end(JSON.stringify(summary), () => {
+        cleanup("client-request").then(() => process.exit(0));
+      });
+      return;
+    }
+    res.writeHead(404); res.end("unknown control path");
+  });
+  const onSignal = () => { cleanup("signal").then(() => process.exit(0)); };
+  process.on("SIGTERM", onSignal);
+  process.on("SIGINT", onSignal);
+  await new Promise((resolve, reject) => {
+    server.on("error", reject);
+    server.listen(0, "127.0.0.1", resolve);
+  });
+  const controlPort = server.address().port;
+  writeSessionJson(statePath, Object.assign({}, st, { status: "running", pid: process.pid, controlPort: controlPort }));
+  armIdle();
+  // The daemon lives until session-end, the idle timeout, or a signal.
+}
+
 async function main() {
+  const argv = process.argv.slice(2);
+  // Internal daemon entry (spawned by session-start, detached).
+  if (argv[0] === "--daemon") {
+    await runDaemon(argv[1]);
+    return;
+  }
   // --help: before required-arg parsing (shebang⇔CLI contract).
-  if (process.argv.slice(2).includes("--help")) {
+  if (argv.includes("--help")) {
     console.log("usage: node see-act.js --url <url> [--viewport desktop|mobile] [--timeout-ms <n>] <action> [args]\n" +
-      "actions: aria | shot --out <png> [--full] | click --out <png> --selector <css> | scroll --out <png> --y <px|bottom> | type --out <png> --selector <css> --text <text>");
+      "actions: aria | shot --out <png> [--full] | click --out <png> --selector <css> | scroll --out <png> --y <px|bottom> | type --out <png> --selector <css> --text <text>\n" +
+      "session protocol (one browser held alive across invocations):\n" +
+      "  session-start --name <name> --url <url> [--session-dir <dir>] [--log <ooda-log.jsonl>]\n" +
+      "      [--viewport desktop|mobile] [--timeout-ms <n>] [--idle-ttl-ms <n>]\n" +
+      "  session-act --name <name> --attempt <id> [--session-dir <dir>] [--timeout-ms <n>] <action> [args]\n" +
+      "  session-end --name <name> [--session-dir <dir>]");
     process.exit(0);
   }
+  // Session subcommands dispatch before the one-shot path (which is frozen).
+  if (argv[0] === "session-start") {
+    await runSessionStart(parseArgs(argv.slice(1)));
+    return;
+  }
+  if (argv[0] === "session-act") {
+    await runSessionAct(parseArgs(argv.slice(1)));
+    return;
+  }
+  if (argv[0] === "session-end") {
+    await runSessionEnd(parseArgs(argv.slice(1)));
+    return;
+  }
   const args = parseArgs(process.argv.slice(2));
   if (!args.url) {
     fail(2, { ok: false, error: "usage: node see-act.js --url <url> [--viewport desktop|mobile] <aria|shot|click|scroll|type> [args]" });