@lovrozagar/grunt 0.5.2 → 0.6.0

package/cli/init.test.ts

@@ -15,6 +15,12 @@ import {
   guardedMarkdownDrift,
   healGuardedRootFile,
   init,
+  pruneRetired,
+  RETIRED_SKILLS,
+  RETIRED_AGENTS,
+  RETIRED_SCRIPTS,
+  RETIRED_PATHS,
+  RESERVED_SKILLS,
   LAUNCH_SCRIPTS,
   mergeClaudeSettings,
   mergeGitignore,
@@ -30,7 +36,6 @@ import {
   writeMergedGuardedFile,
 } from "./init.mjs";
 import { runGuardedRoots } from "../scripts/guarded-roots.mjs";
-import { stripJsonc } from "../scripts/grunt-config.mjs";
 
 const tmpDirs: string[] = [];
 afterEach(() => {
@@ -46,12 +51,6 @@ function tmp(prefix: string) {
 }
 
 const COPY_DIRS = [".rulesync", ".grok", ".codex", ".claude", ".agents"];
-const GRUNT_CONFIG_REL = path.join(".rulesync", "grunt.config.jsonc");
-const GRUNT_CONFIG_DEFAULTS = {
-  version: 1,
-  leftoverGate: "ask",
-  spawnMode: "cascade",
-};
 const GUARDED_MD_FILES = ["AGENTS.md", "CLAUDE.md"];
 const PRODUCT_FILES = [
   "check-globals.mjs",
@@ -64,9 +63,9 @@ const PRODUCT_FILES = [
   "hooks-union.mjs",
   "pipeline.mjs",
   "grunt-job.mjs",
-  "grunt-config.mjs",
   "parse-need.mjs",
   "persist-handoff.mjs",
+  "persist-implementation.mjs",
   "persist-tmp.mjs",
   "persist-plan.mjs",
   "purge-global-mcps.mjs",
@@ -74,6 +73,10 @@ const PRODUCT_FILES = [
   "scrub-text-lib.mjs",
   "sync-global-settings.mjs",
   "browser.mjs",
+  "speak.mjs",
+  "listen.mjs",
+  "google-workspace.mjs",
+  "setup.mjs",
   "doctor.mjs",
   "skill-conflicts.mjs",
 ];
@@ -118,12 +121,6 @@ const SRC_CLAUDE_SETTINGS = {
   enabledMcpjsonServers: [],
 };
 
-function readGruntConfig(root: string) {
-  const p = path.join(root, GRUNT_CONFIG_REL);
-  expect(fs.existsSync(p)).toBe(true);
-  return JSON.parse(stripJsonc(fs.readFileSync(p, "utf8")));
-}
-
 function stubPkgRoot(pkg: Record<string, unknown> = {
   name: "fixture-pkg",
   scripts: {
@@ -143,10 +140,6 @@ function stubPkgRoot(pkg: Record<string, unknown> = {
     fs.mkdirSync(path.join(root, d));
     fs.writeFileSync(path.join(root, d, "marker"), d);
   }
-  fs.writeFileSync(
-    path.join(root, GRUNT_CONFIG_REL),
-    `${JSON.stringify(GRUNT_CONFIG_DEFAULTS, null, 2)}\n`,
-  );
   fs.writeFileSync(
     path.join(root, ".claude", "settings.json"),
     `${JSON.stringify(SRC_CLAUDE_SETTINGS, null, 2)}\n`,
@@ -179,18 +172,22 @@ describe("samePath", () => {
   });
 });
 
+const GI_TMP = ".tmp/\n";
+
 describe("mergeGitignore", () => {
   it("creates .tmp/ when missing", () => {
     const dest = tmp("gi-miss-");
     mergeGitignore(dest);
-    expect(fs.readFileSync(path.join(dest, ".gitignore"), "utf8")).toBe(".tmp/\n");
+    expect(fs.readFileSync(path.join(dest, ".gitignore"), "utf8")).toBe(GI_TMP);
   });
 
-  it("noop when .tmp/ present", () => {
+  it("noop when .tmp/ already present", () => {
     const dest = tmp("gi-slash-");
     fs.writeFileSync(path.join(dest, ".gitignore"), "foo\n.tmp/\nbar\n");
     mergeGitignore(dest);
-    expect(fs.readFileSync(path.join(dest, ".gitignore"), "utf8")).toBe("foo\n.tmp/\nbar\n");
+    expect(fs.readFileSync(path.join(dest, ".gitignore"), "utf8")).toBe(
+      "foo\n.tmp/\nbar\n",
+    );
   });
 
   it("noop when .tmp present", () => {
@@ -200,12 +197,21 @@ describe("mergeGitignore", () => {
     expect(fs.readFileSync(path.join(dest, ".gitignore"), "utf8")).toBe(".tmp\n");
   });
 
+  it("noop when .tmp/ present in mixed file", () => {
+    const dest = tmp("gi-both-");
+    fs.writeFileSync(path.join(dest, ".gitignore"), `foo\n${GI_TMP}bar\n`);
+    mergeGitignore(dest);
+    expect(fs.readFileSync(path.join(dest, ".gitignore"), "utf8")).toBe(
+      `foo\n${GI_TMP}bar\n`,
+    );
+  });
+
   it("appends after trailing newline", () => {
     const dest = tmp("gi-nl-");
     fs.writeFileSync(path.join(dest, ".gitignore"), "node_modules/\n");
     mergeGitignore(dest);
     expect(fs.readFileSync(path.join(dest, ".gitignore"), "utf8")).toBe(
-      "node_modules/\n.tmp/\n",
+      `node_modules/\n${GI_TMP}`,
     );
   });
 
@@ -214,7 +220,7 @@ describe("mergeGitignore", () => {
     fs.writeFileSync(path.join(dest, ".gitignore"), "node_modules/");
     mergeGitignore(dest);
     expect(fs.readFileSync(path.join(dest, ".gitignore"), "utf8")).toBe(
-      "node_modules/\n.tmp/\n",
+      `node_modules/\n${GI_TMP}`,
     );
   });
 
@@ -222,7 +228,7 @@ describe("mergeGitignore", () => {
     const dest = tmp("gi-empty-");
     fs.writeFileSync(path.join(dest, ".gitignore"), "");
     mergeGitignore(dest);
-    expect(fs.readFileSync(path.join(dest, ".gitignore"), "utf8")).toBe(".tmp/\n");
+    expect(fs.readFileSync(path.join(dest, ".gitignore"), "utf8")).toBe(GI_TMP);
   });
 });
 
@@ -1550,9 +1556,9 @@ describe("init", () => {
       if (d === ".claude") continue;
       expect(fs.readFileSync(path.join(dest, d, "marker"), "utf8")).toBe(d);
     }
-    expect(readGruntConfig(dest)).toEqual(GRUNT_CONFIG_DEFAULTS);
-    expect(PRODUCT_FILES).toContain("grunt-config.mjs");
-    expect(fs.statSync(path.join(dest, "scripts", "grunt-config.mjs")).isFile()).toBe(true);
+    expect(fs.existsSync(path.join(dest, ".rulesync", "grunt.config.jsonc"))).toBe(false);
+    expect(PRODUCT_FILES).not.toContain("grunt-config.mjs");
+    expect(fs.existsSync(path.join(dest, "scripts", "grunt-config.mjs"))).toBe(false);
     expect(fs.readFileSync(path.join(dest, ".claude", "marker"), "utf8")).toBe(".claude");
     const settings = JSON.parse(
       fs.readFileSync(path.join(dest, ".claude", "settings.json"), "utf8"),
@@ -1626,6 +1632,109 @@ describe("init", () => {
     expect(fs.readFileSync(path.join(pkgRoot, ".gitignore"), "utf8")).toBe(".tmp/\n");
   });
 
+  it("prunes retired 0.5 skills and agents on dest", () => {
+    const pkgRoot = stubPkgRoot();
+    const dest = tmp("grunt-prune-");
+    fs.mkdirSync(path.join(dest, ".rulesync", "skills", "solo"), { recursive: true });
+    fs.writeFileSync(path.join(dest, ".rulesync", "skills", "solo", "SKILL.md"), "old");
+    fs.mkdirSync(path.join(dest, ".rulesync", "skills", "parent"), { recursive: true });
+    fs.mkdirSync(path.join(dest, ".rulesync", "skills", "cascade"), { recursive: true });
+    fs.mkdirSync(path.join(dest, ".claude", "agents"), { recursive: true });
+    fs.writeFileSync(path.join(dest, ".claude", "agents", "implementer.md"), "old");
+    fs.writeFileSync(path.join(dest, ".claude", "agents", "thinker.md"), "old");
+    expect(RETIRED_SKILLS).toEqual(["parent", "solo", "cascade"]);
+    expect(RETIRED_AGENTS).toEqual(["implementer", "thinker"]);
+    expect(RETIRED_SCRIPTS).toEqual(["telemetry.mjs", "grunt-config.mjs"]);
+    expect(RETIRED_PATHS).toEqual([
+      ".grok/parent.md",
+      ".grok/skills/shared",
+      ".rulesync/grunt.config.jsonc",
+      ".rulesync/grunt.config.local.jsonc",
+      ".rulesync/grunt.config.local.jsonc.example",
+    ]);
+    expect(RESERVED_SKILLS).toEqual([
+      "ask",
+      "auto",
+      "browser",
+      "clasp",
+      "commit",
+      "commit-and-push",
+      "commit-push",
+      "commit-push-deploy",
+      "commit-push-release",
+      "explain",
+      "google-workspace",
+      "handoff",
+      "implement-plan",
+      "listen",
+      "pickup",
+      "speak",
+      "tmp",
+      "write-plan",
+    ]);
+    expect(RESERVED_SKILLS).not.toEqual(expect.arrayContaining(RETIRED_SKILLS));
+    init(dest, { pkgRoot, execFileSync: vi.fn() });
+    expect(fs.existsSync(path.join(dest, ".rulesync", "skills", "solo"))).toBe(false);
+    expect(fs.existsSync(path.join(dest, ".rulesync", "skills", "parent"))).toBe(false);
+    expect(fs.existsSync(path.join(dest, ".rulesync", "skills", "cascade"))).toBe(false);
+    expect(fs.existsSync(path.join(dest, ".claude", "agents", "implementer.md"))).toBe(
+      false,
+    );
+    expect(fs.existsSync(path.join(dest, ".claude", "agents", "thinker.md"))).toBe(false);
+    pruneRetired(dest, { pkgRoot });
+  });
+
+  it("prunes retired scripts/paths, reserved-not-packaged skills, and grok roles; keeps consumer extras", () => {
+    const pkgRoot = stubPkgRoot();
+    fs.mkdirSync(path.join(pkgRoot, ".rulesync", "skills", "tmp"), { recursive: true });
+    fs.writeFileSync(path.join(pkgRoot, ".rulesync", "skills", "tmp", "SKILL.md"), "pkg tmp");
+    const dest = tmp("grunt-prune-extra-");
+    fs.mkdirSync(path.join(dest, ".rulesync", "skills", "tmp"), { recursive: true });
+    fs.writeFileSync(path.join(dest, ".rulesync", "skills", "tmp", "SKILL.md"), "old tmp");
+    fs.mkdirSync(path.join(dest, ".rulesync", "skills", "browser"), { recursive: true });
+    fs.writeFileSync(path.join(dest, ".rulesync", "skills", "browser", "SKILL.md"), "stale reserved");
+    fs.mkdirSync(path.join(dest, ".rulesync", "skills", "acme"), { recursive: true });
+    fs.writeFileSync(path.join(dest, ".rulesync", "skills", "acme", "SKILL.md"), "consumer");
+    fs.mkdirSync(path.join(dest, ".grok", "roles"), { recursive: true });
+    fs.writeFileSync(path.join(dest, ".grok", "roles", "implementer.toml"), "old");
+    fs.writeFileSync(path.join(dest, ".grok", "roles", "thinker.toml"), "old");
+    fs.writeFileSync(path.join(dest, ".grok", "parent.md"), "pointer");
+    fs.mkdirSync(path.join(dest, ".grok", "skills", "shared"), { recursive: true });
+    fs.mkdirSync(path.join(dest, "scripts"), { recursive: true });
+    fs.writeFileSync(path.join(dest, "scripts", "telemetry.mjs"), "old telemetry");
+    fs.writeFileSync(path.join(dest, "scripts", "grunt-config.mjs"), "old config");
+    fs.writeFileSync(path.join(dest, "scripts", "mine.mjs"), "keep");
+    fs.writeFileSync(path.join(dest, ".rulesync", "grunt.config.jsonc"), '{"version":1}\n');
+    fs.writeFileSync(path.join(dest, ".rulesync", "grunt.config.local.jsonc"), '{"sessionGate":"ask"}\n');
+    fs.writeFileSync(
+      path.join(dest, ".rulesync", "grunt.config.local.jsonc.example"),
+      '{"sessionGate":"ask"}\n',
+    );
+    fs.mkdirSync(path.join(dest, ".gemini", "agents", "implementer"), { recursive: true });
+    fs.writeFileSync(path.join(dest, ".gemini", "agents", "implementer", "agent.md"), "old");
+    init(dest, { pkgRoot, execFileSync: vi.fn() });
+    expect(fs.readFileSync(path.join(dest, ".rulesync", "skills", "tmp", "SKILL.md"), "utf8")).toBe(
+      "pkg tmp",
+    );
+    expect(fs.existsSync(path.join(dest, ".rulesync", "skills", "browser"))).toBe(false);
+    expect(fs.readFileSync(path.join(dest, ".rulesync", "skills", "acme", "SKILL.md"), "utf8")).toBe(
+      "consumer",
+    );
+    expect(fs.existsSync(path.join(dest, ".grok", "roles", "implementer.toml"))).toBe(false);
+    expect(fs.existsSync(path.join(dest, ".grok", "roles", "thinker.toml"))).toBe(false);
+    expect(fs.existsSync(path.join(dest, ".grok", "parent.md"))).toBe(false);
+    expect(fs.existsSync(path.join(dest, ".grok", "skills", "shared"))).toBe(false);
+    expect(fs.existsSync(path.join(dest, "scripts", "telemetry.mjs"))).toBe(false);
+    expect(fs.existsSync(path.join(dest, "scripts", "grunt-config.mjs"))).toBe(false);
+    expect(fs.existsSync(path.join(dest, ".rulesync", "grunt.config.jsonc"))).toBe(false);
+    expect(fs.existsSync(path.join(dest, ".rulesync", "grunt.config.local.jsonc"))).toBe(false);
+    expect(
+      fs.existsSync(path.join(dest, ".rulesync", "grunt.config.local.jsonc.example")),
+    ).toBe(false);
+    expect(fs.readFileSync(path.join(dest, "scripts", "mine.mjs"), "utf8")).toBe("keep");
+    expect(fs.existsSync(path.join(dest, ".gemini", "agents", "implementer"))).toBe(false);
+  });
+
   it("omitted pkgRoot uses built-in PKG_ROOT; exec mocked", () => {
     const dest = tmp("grunt-realroot-");
     const exec = vi.fn();
@@ -1638,9 +1747,12 @@ describe("init", () => {
     expect(claude.split("<!-- grunt:begin -->")).toHaveLength(2);
     expect(claude.split("<!-- grunt:end -->")).toHaveLength(2);
     expect(fs.existsSync(path.join(dest, "scripts", "scrub-text"))).toBe(true);
-    expect(fs.existsSync(path.join(dest, "scripts", "grunt-config.mjs"))).toBe(true);
+    expect(fs.existsSync(path.join(dest, "scripts", "grunt-config.mjs"))).toBe(false);
+    expect(fs.existsSync(path.join(dest, "scripts", "speak.mjs"))).toBe(true);
+    expect(fs.existsSync(path.join(dest, "scripts", "listen.mjs"))).toBe(true);
+    expect(fs.existsSync(path.join(dest, "scripts", "google-workspace.mjs"))).toBe(true);
     expect(fs.existsSync(path.join(dest, ".claude", "settings.json"))).toBe(true);
-    expect(readGruntConfig(dest)).toEqual(GRUNT_CONFIG_DEFAULTS);
+    expect(fs.existsSync(path.join(dest, ".rulesync", "grunt.config.jsonc"))).toBe(false);
     expect(exec.mock.calls.map((c) => c[1])).toEqual([
       ["install"],
       ["run", "grunt:rulesync:generate"],
@@ -1829,25 +1941,25 @@ describe("init", () => {
 
   it("warns when dest skill differs from packaged then force-overwrites; keeps extras", () => {
     const pkgRoot = stubPkgRoot();
-    const pkgSkill = path.join(pkgRoot, ".rulesync", "skills", "parent");
+    const pkgSkill = path.join(pkgRoot, ".rulesync", "skills", "explain");
     fs.mkdirSync(pkgSkill, { recursive: true });
-    fs.writeFileSync(path.join(pkgSkill, "SKILL.md"), "grunt-parent\n");
+    fs.writeFileSync(path.join(pkgSkill, "SKILL.md"), "grunt-explain\n");
     const dest = tmp("grunt-sk-conflict-");
-    const destSkill = path.join(dest, ".rulesync", "skills", "parent");
+    const destSkill = path.join(dest, ".rulesync", "skills", "explain");
     const destExtra = path.join(dest, ".rulesync", "skills", "my-extra");
     fs.mkdirSync(destSkill, { recursive: true });
     fs.mkdirSync(destExtra, { recursive: true });
-    fs.writeFileSync(path.join(destSkill, "SKILL.md"), "custom-parent\n");
+    fs.writeFileSync(path.join(destSkill, "SKILL.md"), "custom-explain\n");
     fs.writeFileSync(path.join(destExtra, "SKILL.md"), "keep-me\n");
     const warnSpy = vi.spyOn(console, "warn").mockImplementation(() => {});
     init(dest, { pkgRoot, execFileSync: vi.fn(), skipGlobals: true });
     expect(
       warnSpy.mock.calls.some(
-        (c) => String(c[0]).includes("parent") && String(c[0]).includes("re-init overwrites"),
+        (c) => String(c[0]).includes("explain") && String(c[0]).includes("re-init overwrites"),
       ),
     ).toBe(true);
     warnSpy.mockRestore();
-    expect(fs.readFileSync(path.join(destSkill, "SKILL.md"), "utf8")).toBe("grunt-parent\n");
+    expect(fs.readFileSync(path.join(destSkill, "SKILL.md"), "utf8")).toBe("grunt-explain\n");
     expect(fs.readFileSync(path.join(destExtra, "SKILL.md"), "utf8")).toBe("keep-me\n");
   });
 });

package/cli/prompt.mjs

@@ -31,6 +31,14 @@ export async function confirm(opts) {
   return bailIfCancel(await clack.confirm(opts))
 }
 
+export async function text(opts) {
+  return bailIfCancel(await clack.text(opts))
+}
+
+export async function password(opts) {
+  return bailIfCancel(await clack.password(opts))
+}
+
 export function spinner() {
   return clack.spinner()
 }

package/cli/prompt.test.ts

@@ -2,6 +2,8 @@ import { afterEach, describe, expect, it, vi } from "vitest";
 
 const clackSelect = vi.hoisted(() => vi.fn());
 const clackConfirm = vi.hoisted(() => vi.fn());
+const clackText = vi.hoisted(() => vi.fn());
+const clackPassword = vi.hoisted(() => vi.fn());
 const clackSpinner = vi.hoisted(() => vi.fn());
 const clackIsCancel = vi.hoisted(() => vi.fn());
 const clackCancel = vi.hoisted(() => vi.fn());
@@ -9,6 +11,8 @@ const clackCancel = vi.hoisted(() => vi.fn());
 vi.mock("@clack/prompts", () => ({
   select: clackSelect,
   confirm: clackConfirm,
+  text: clackText,
+  password: clackPassword,
   spinner: clackSpinner,
   isCancel: clackIsCancel,
   cancel: clackCancel,
@@ -18,8 +22,10 @@ import {
   bailIfCancel,
   confirm,
   isInteractive,
+  password,
   select,
   spinner,
+  text,
 } from "./prompt.mjs";
 
 function tty(isTTY: boolean) {
@@ -196,4 +202,12 @@ describe("clack wrappers", () => {
     expect(spinner()).toBe(s);
     expect(clackSpinner).toHaveBeenCalledOnce();
   });
+
+  it("text and password bail then return", async () => {
+    clackText.mockResolvedValue("proj");
+    clackPassword.mockResolvedValue("sk_x");
+    clackIsCancel.mockReturnValue(false);
+    await expect(text({ message: "Project ID" })).resolves.toBe("proj");
+    await expect(password({ message: "API key" })).resolves.toBe("sk_x");
+  });
 });

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@lovrozagar/grunt",
-  "version": "0.5.2",
+  "version": "0.6.0",
   "description": "Multi-agent orchestrator SoT — deep-merge rulesync trees, product scripts, and generate pipeline into a consumer repo",
   "keywords": [
     "agents",
@@ -34,9 +34,9 @@
     "scripts/hooks-union.mjs",
     "scripts/pipeline.mjs",
     "scripts/grunt-job.mjs",
-    "scripts/grunt-config.mjs",
     "scripts/parse-need.mjs",
     "scripts/persist-handoff.mjs",
+    "scripts/persist-implementation.mjs",
     "scripts/persist-tmp.mjs",
     "scripts/persist-plan.mjs",
     "scripts/purge-global-mcps.mjs",
@@ -44,6 +44,10 @@
     "scripts/scrub-text-lib.mjs",
     "scripts/sync-global-settings.mjs",
     "scripts/browser.mjs",
+    "scripts/speak.mjs",
+    "scripts/listen.mjs",
+    "scripts/google-workspace.mjs",
+    "scripts/setup.mjs",
     "scripts/doctor.mjs",
     "scripts/skill-conflicts.mjs",
     "scripts/scrub-text",
@@ -73,6 +77,7 @@
     "hooks:union": "node scripts/hooks-union.mjs",
     "hooks:check": "node scripts/hooks-union.mjs --check",
     "doctor": "node ./scripts/doctor.mjs",
+    "setup": "node ./scripts/setup.mjs",
     "rulesync:doctor": "rulesync doctor",
     "sync:globals": "node scripts/sync-global-settings.mjs",
     "sync:globals:check": "node scripts/check-globals.mjs",

package/scripts/browser.mjs

@@ -1,5 +1,5 @@
 #!/usr/bin/env node
-/** Session browser rail: nav|snap|click|fill|shot|pdf|stop|doctor|ensure. Lightpanda default. */
+/** Session browser rail: nav|snap|click|fill|scroll|wait|hover|select|shot|pdf|stop|doctor|ensure. Lightpanda default. */
 import { spawn } from "node:child_process";
 import crypto from "node:crypto";
 import fs from "node:fs";
@@ -7,6 +7,7 @@ import http from "node:http";
 import net from "node:net";
 import path from "node:path";
 import { fileURLToPath, pathToFileURL } from "node:url";
+import { writeStash } from "./grunt-job.mjs";
 import {
   CHROMIUM_BINS,
   LIGHTPANDA_REPO as DOCTOR_LP_REPO,
@@ -64,9 +65,21 @@ export function isPaintHost(url) {
   if ((h === "google.com" || h.endsWith(".google.com")) && u.pathname.startsWith("/earth")) {
     return true;
   }
+  if (/(^|\.)amazon\./.test(h)) return true;
   return false;
 }
 
+const BLOCKED_SNAP_RE =
+  /enable javascript|javascript (is )?(required|disabled)|checking your browser|just a moment|captcha|access denied|sorry.*robot|continue shopping|attention required|cf-browser-verification|verify you are a human/i;
+
+export function isBlockedSnap(markdown, lines) {
+  const refs = Array.isArray(lines) ? lines.length : 0;
+  const md = String(markdown || "").trim();
+  if (BLOCKED_SNAP_RE.test(md)) return true;
+  const body = md.replace(/^#\s+\S+\s*$/m, "").trim();
+  return refs === 0 && body.length < 80;
+}
+
 export function lookupBins(pathEnv, platform = process.platform) {
   const lightpanda = whichBin("lightpanda", pathEnv, platform);
   let chromium = "";
@@ -348,8 +361,10 @@ async function handleCdp(state, method, params = {}) {
       state.markdown = `# ${state.url}\n\nhello`;
       return { frameId: "f1" };
     case "LP.getMarkdown":
+      if (state.thinSnap) return { markdown: `# ${state.url || ""}\n` };
       return { markdown: state.markdown || `# ${state.url || ""}\n\nhello` };
     case "Accessibility.getFullAXTree":
+      if (state.thinSnap) return { nodes: [] };
       return { nodes: state.axNodes || defaultAx(state.url) };
     case "DOM.resolveNode": {
       const id = params.backendNodeId;
@@ -378,6 +393,7 @@ export async function serveCdp(state = {}, { port = 0 } = {}) {
     url: "about:blank",
     markdown: "",
     failProbe: false,
+    thinSnap: false,
     engine: "lightpanda",
     ...state,
   };
@@ -606,7 +622,7 @@ export async function runBrowser(argv, opts = {}) {
   const verb = String(argv[0] || "").toLowerCase();
   try {
     if (!verb || verb === "help" || verb === "-h" || verb === "--help") {
-      return ok("nav|snap|click|fill|shot|pdf|stop|doctor|ensure");
+      return ok("nav|snap|click|fill|scroll|wait|hover|select|shot|pdf|stop|doctor|ensure");
     }
     if (verb === "doctor" || verb === "ensure") {
       return runDoctor({ pathEnv: env.PATH, platform, cwd });
@@ -650,16 +666,79 @@ export async function runBrowser(argv, opts = {}) {
       return ok(`engine: ${session.engine}\nurl: ${session.lastURL}`);
     }
     if (verb === "snap") {
-      const session = readSession(cwd);
+      let session = readSession(cwd);
       if (!session || !alive(session.pid)) return fail("no browser session; run nav");
-      const { markdown, lines } = await snapshot(session);
+      let { markdown, lines } = await snapshot(session);
+      if (
+        session.engine === "lightpanda" &&
+        (session.swapCount || 0) < 1 &&
+        bins.chromium &&
+        isBlockedSnap(markdown, lines)
+      ) {
+        session = await swapToChromium(session, ctx);
+        ({ markdown, lines } = await snapshot(session));
+      }
       writeSession(cwd, session);
+      const raw = [markdown.trim(), "", ...lines].join("\n");
+      const headings = String(markdown || "")
+        .split(/\n/)
+        .filter((l) => /^#{1,6}\s/.test(l));
+      const shown = [...headings.slice(0, 6), ...lines.slice(0, 24)];
+      if (raw.length > 32 * 1024 || lines.length > 6) {
+        const stash = writeStash(cwd, "snap", raw);
+        return ok(
+          `engine: ${session.engine}\nurl: ${session.lastURL}\n${shown.length} shown. stash=${stash}\n${shown.join("\n")}`,
+        );
+      }
       const body = [markdown.trim(), "", ...lines].filter((x, i, a) => x !== "" || a[i - 1] !== "").join("\n");
       return ok(`engine: ${session.engine}\nurl: ${session.lastURL}\n\n${body}`);
     }
-    if (verb === "click" || verb === "fill") {
+    if (verb === "wait") {
       const session = readSession(cwd);
       if (!session || !alive(session.pid)) return fail("no browser session; run nav");
+      const raw = String(argv[1] || "1000");
+      const ms = Math.min(15000, Math.max(0, Number(raw) || 0));
+      await sleep(ms);
+      return ok(`wait: ${ms}`);
+    }
+    if (verb === "scroll") {
+      let session = readSession(cwd);
+      if (!session || !alive(session.pid)) return fail("no browser session; run nav");
+      const arg = String(argv[1] || "down");
+      const refs = session.lastRefs || {};
+      const rec = refs[arg];
+      const act = async (sess) =>
+        withCdp(sess, async (cdp) => {
+          if (rec) {
+            const resolved = await cdp.send("DOM.resolveNode", { backendNodeId: rec.backendNodeId });
+            const objectId = resolved.object && resolved.object.objectId;
+            if (!objectId) throw new Error("stale");
+            await cdp.send("Runtime.callFunctionOn", {
+              objectId,
+              functionDeclaration: "function() { this.scrollIntoView({ block: 'center' }); }",
+            });
+            return;
+          }
+          let dy = 600;
+          if (arg === "up") dy = -600;
+          else if (/^-?\d+$/.test(arg)) dy = Number(arg);
+          await cdp.send("Runtime.evaluate", {
+            expression: `window.scrollBy(0, ${dy})`,
+          });
+        });
+      try {
+        await act(session);
+      } catch (err) {
+        const msg = String(err && err.message ? err.message : err);
+        if (/stale|missing/i.test(msg)) return fail(`stale ref: ${arg}`);
+        return fail(msg);
+      }
+      writeSession(cwd, session);
+      return ok(`scroll: ${arg}`);
+    }
+    if (verb === "click" || verb === "fill" || verb === "hover" || verb === "select") {
+      let session = readSession(cwd);
+      if (!session || !alive(session.pid)) return fail("no browser session; run nav");
       const refs = session.lastRefs || {};
       if (!Object.keys(refs).length) return fail("no snap refs; run snap");
       const refId = String(argv[1] || "");
@@ -667,6 +746,7 @@ export async function runBrowser(argv, opts = {}) {
       if (!rec) return fail(`missing ref: ${refId}`);
       const text = argv.slice(2).join(" ");
       if (verb === "fill" && !text) return fail("fill <ref> <text>");
+      if (verb === "select" && !text) return fail("select <ref> <value>");
       const act = async (sess) =>
         withCdp(sess, async (cdp) => {
           const resolved = await cdp.send("DOM.resolveNode", { backendNodeId: rec.backendNodeId });
@@ -677,6 +757,19 @@ export async function runBrowser(argv, opts = {}) {
               objectId,
               functionDeclaration: "function() { this.click(); }",
             });
+          } else if (verb === "hover") {
+            await cdp.send("Runtime.callFunctionOn", {
+              objectId,
+              functionDeclaration:
+                "function() { this.dispatchEvent(new MouseEvent('mouseover', { bubbles: true })); }",
+            });
+          } else if (verb === "select") {
+            await cdp.send("Runtime.callFunctionOn", {
+              objectId,
+              arguments: [{ value: text }],
+              functionDeclaration:
+                "function(v) { this.value = v; this.dispatchEvent(new Event('change', { bubbles: true })); }",
+            });
           } else {
             await cdp.send("Runtime.callFunctionOn", {
               objectId,