@vosjs/cli 0.40.0 → 0.41.1

package/README.md

@@ -80,7 +80,7 @@ vos plan take --reuse                                   # re-time that cut onto
 
 | Verb     | Flags                                                                                                                                                                                                                                                                                                                                                                                                                                                                     |
 | -------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| `record` | `--actions <file>` (or positional) `--url` `--out take` `--strict` `--dry-run` `--keep-frames` `--storage-state <file>` `--browser-arg=<switch>`... `--max-duration <s>` `--background <slug\|url\|none>`                                                                                                                                                                                                                                                                 |
+| `record` | `--actions <file>` (or positional) `--url` `--out take` `--strict` `--dry-run` `--allow-wall` `--keep-frames` `--storage-state <file>` `--browser-arg=<switch>`... `--max-duration <s>` `--background <slug\|url\|none>`                                                                                                                                                                                                                                                  |
 | `create` | The `record` flags plus the render flags (`--width` `--height` `--fps` `--format` `--parallel` `--draft` `--frame` `--set`), no `--range`. With `--strict` an incomplete recording exits 2 before anything is rendered                                                                                                                                                                                                                                                    |
 | `plan`   | `--fresh` (discard the current plan) `--reuse` `--from <doc.json>` (defaults to `<take>/doc.prev.json`) `--style <doc.json\|take\|vosId>` `--with <doc.json\|take\|vosId>[@end\|@start\|@step:<id>\|@<seconds>]` (a template, repeatable) `--background` `--motion` (re-propose the motion) `--headline` `--kicker` `--launch` `--brand` `--music` `--entrance` `--transitions slide\|fade\|scale\|none` `--end-card on\|none\|<ref>` `--captions` `--clicks` `--release` |
 | `digest` | `--out <take>/digest` `--full 960` `--crop 640` (image long edges, the token budget) `--no-frames` `--transcript <file>` (Whisper-shaped segments merged as `said`) `--style <ref>` (report a reference document's style fields)                                                                                                                                                                                                                                          |
@@ -88,7 +88,9 @@ vos plan take --reuse                                   # re-time that cut onto
 | `render` | `--width` `--height` `--fps` `--format webm\|mp4` `--parallel N` (1..16 sessions) `--range a..b` (output seconds; keeps its audio) `--draft` `--frame <kind>` `--background` `--set …`; `out` defaults to `<take>/out.<format>`                                                                                                                                                                                                                                           |
 | `open`   | `--studio http://localhost:6060` `--print` (print the URL, do not launch a browser)                                                                                                                                                                                                                                                                                                                                                                                       |
 
-**Rehearse before you record.** `vos record … --dry-run` runs every step against the real page, in order, because a later selector usually exists only after an earlier click. Nothing is captured and nothing is written: the pointer lands instead of travelling, every pause is cut to a beat, and the take directory beside it keeps its footage, its cut and its script exactly as they were (a real re-record moves `doc.json` aside; a rehearsal does not). Selector lookups keep their whole timeout, so a miss here is a miss in the take. It prints each step with the rect it resolved, in capture px, which are the rects a pin or `vos callout --step` reads, and exits 2 on any miss or a first load that never settled. Add `--dry-run` to the exact command you were about to run; `--storage-state` and `--browser-arg=` apply to it too.
+**The wall check.** Once the first navigation settles, and before a frame is captured, `record`, `create` and `--dry-run` ask whether the recorder landed where it was sent. A take that met a sign-in instead is refused with exit 4 and a sentence (`asked for /dashboard, landed on /login: no session for app.acme.com`): the asked URL answered 401 or 403, the recorder was sent to an identity provider or a sign-in path, or the page is a sign-in form (one password field, or a one-time-code field) rendered in place. A redirect somewhere else with no sign-in in sight, which is what a site that shows strangers a public page looks like, is refused under `--strict` and in a rehearsal, and said as a warning otherwise. The check runs before a re-record clears anything, so a session that expired since the last take never costs the footage it failed to replace. The way past a wall is a session: `--storage-state <file>`, minted from the test auth the project already has wherever that exists. `--allow-wall` records the page anyway (a video OF a sign-in page is a legitimate take), and the take's `meta.wall` and its digest then say so.
+
+**Rehearse before you record.** `vos record … --dry-run` runs every step against the real page, in order, because a later selector usually exists only after an earlier click. Nothing is captured and nothing is written: the pointer lands instead of travelling, every pause is cut to a beat, and the take directory beside it keeps its footage, its cut and its script exactly as they were (a real re-record moves `doc.json` aside; a rehearsal does not). Selector lookups keep their whole timeout, so a miss here is a miss in the take. It prints each step with the rect it resolved, in capture px, which are the rects a pin or `vos callout --step` reads, and exits 2 on any miss or a first load that never settled. Add `--dry-run` to the exact command you were about to run; `--storage-state` and `--browser-arg=` apply to it too, and the `Next:` line it prints carries them, so the command it hands you records what it rehearsed.
 
 **Digest first.** `vos digest <take>` is how an agent sees a recording without reading the video. It writes `digest/digest.json`: one moment per thing the cursor track says mattered (click clusters, typing sessions, scroll runs, dwells, idle gaps, head, tail, and frame-diff scene changes), each with source and output extents, a normalized `focus` and `rect` you can copy into a zoom span, per-second `activity`, and the planners' `proposed` span ids; plus one footage frame and a crop around the target per moment, and `sheet.png`, the contact sheet. Read the JSON, then the sheet, then a crop only where you must decide. `vos validate` then warns when a zoom does not contain what was clicked under it, and `vos frames --at-moments` renders the composed output at every moment so a still and its footage crop share an id.
 
@@ -254,7 +256,8 @@ vos push /tmp/take --label "$TAG launch" --yes --json       # VOS_API_KEY as a r
 ## For scripts and agents
 
 - **Output.** Logs on stderr, results on stdout. `--json` turns every verb into NDJSON events ending with `{"event":"done",…}`.
-- **Exit codes.** 0 ok, 1 error, 2 usage (including `--strict` failures), 3 no browser found.
+- **`vos <verb> --help`** prints that verb's usage lines and exits 0 (it used to be a usage error).
+- **Exit codes.** 0 ok, 1 error, 2 usage (including `--strict` failures), 3 no browser found, 4 the recorder met a wall (a sign-in, or under `--strict` a redirect away from the asked page) and nothing was recorded or cleared. `--json` carries the verdict as a `wall` event (`kind`, `level`, `asked`, `landed`, `refused`).
 - **`--strict`** on `record` and `create` (agents: always): a skipped selector, a page that never reaches network idle, or a take that hit `--max-duration` exits 2 and lists `skipped[]` (and `capped`) in the done event. The default is lenient (exit 0, `skipped[]` still reported) for exploratory runs.
 - **`--max-duration <s>`** on `record` and `create` defaults to the hosted recording cap, read live from `GET /api/limits` (2 s, fail-open to 30 min when the origin is unreachable): the capture stops there and the done event says so. Cut the flow rather than raising the cap; the platform refuses a longer take.
 - **`create`** is the one-shot verb: record, auto-plan and render in one command and one browser session. The take directory still lands on disk, so the full loop (frames, edit `doc.json`, re-render) stays open afterwards.

package/dist/{chunk-7TDL3N24.js → chunk-4QVEV3HX.js}

@@ -79,6 +79,7 @@ var EXIT_OK = 0;
 var EXIT_ERROR = 1;
 var EXIT_USAGE = 2;
 var EXIT_NO_BROWSER = 3;
+var EXIT_WALL = 4;
 function createReporter(json) {
   return {
     json,
@@ -6628,6 +6629,135 @@ function paceLine(r) {
   return `pace: the script asked ${s(r.askedMs)}, the gestures added ${s(r.gestureMs)}, the take ran ${s(r.wallMs)} (${r.overheadPct} % overhead${slow})`;
 }
 
+// src/plugin/wall.ts
+var IDP_HOSTS = [
+  "accounts.google.com",
+  "login.microsoftonline.com",
+  "login.live.com",
+  "appleid.apple.com",
+  "auth0.com",
+  "okta.com",
+  "onelogin.com",
+  "clerk.accounts.dev",
+  "accounts.dev",
+  "b2clogin.com",
+  "amazoncognito.com",
+  "workos.com",
+  "stytch.com"
+];
+var SIGNIN_SEGMENTS = /* @__PURE__ */ new Set([
+  "login",
+  "log-in",
+  "signin",
+  "sign-in",
+  "sign_in",
+  "sso",
+  "auth",
+  "authenticate",
+  "authorize",
+  "oauth",
+  "oauth2",
+  "saml"
+]);
+function parse(url) {
+  try {
+    return new URL(url);
+  } catch {
+    return null;
+  }
+}
+var bareHost = (h) => h.replace(/^www\./, "").toLowerCase();
+var trimSlash = (p) => p.length > 1 ? p.replace(/\/+$/, "") : p;
+var place = (u) => `${u.origin}${trimSlash(u.pathname)}`;
+function isIdpHost(host) {
+  const h = host.toLowerCase();
+  if (h.startsWith("clerk.")) return true;
+  return IDP_HOSTS.some((idp) => h === idp || h.endsWith(`.${idp}`));
+}
+function isSignInPath(pathname) {
+  const segs = pathname.toLowerCase().split("/").filter(Boolean);
+  return segs.some((s) => SIGNIN_SEGMENTS.has(s));
+}
+function redirectedAway(asked, landed) {
+  if (bareHost(asked.hostname) !== bareHost(landed.hostname)) return true;
+  const a = trimSlash(asked.pathname).toLowerCase();
+  const l = trimSlash(landed.pathname).toLowerCase();
+  if (a === l || a === "/") return false;
+  if (l.startsWith(`${a}/`)) return false;
+  if (l.endsWith(a)) return false;
+  return true;
+}
+var LADDER = 'This is a missing or expired session, not a script bug. Ways past, cheapest first: mint a session from the test auth the project already has; script the sign-in off camera and save the storage state; or have a person sign in once (npx playwright open --channel chrome --save-storage=<file> <url>). Then pass --storage-state <file>. The ladder: https://vos.so/llms-full.txt, "Sessions". A take OF this page is --allow-wall.';
+function wallVerdict(a) {
+  const asked = parse(a.askedUrl);
+  const landed = parse(a.landedUrl);
+  if (!asked || !landed) return null;
+  if (!/^https?:$/.test(asked.protocol)) return null;
+  const away = redirectedAway(asked, landed);
+  const where = { asked: place(asked), landed: place(landed) };
+  const host = bareHost(asked.hostname);
+  if (a.status === 401 || a.status === 403) {
+    return {
+      kind: "status",
+      level: "hard",
+      ...where,
+      message: `asked for ${asked.pathname}, answered ${a.status}: no session for ${host}. ${LADDER}`
+    };
+  }
+  const askedForSignIn = isSignInPath(asked.pathname) || isIdpHost(asked.hostname);
+  if (askedForSignIn && !away) return null;
+  if (away && isIdpHost(landed.hostname) && !isIdpHost(asked.hostname)) {
+    return {
+      kind: "idp",
+      level: "hard",
+      ...where,
+      message: `asked for ${asked.pathname}, landed on ${landed.hostname}: no session for ${host}. ${LADDER}`
+    };
+  }
+  const signInForm = a.passwordFields === 1 && !a.newPasswordField || a.oneTimeCodeField;
+  if (away && isSignInPath(landed.pathname) || signInForm && !askedForSignIn) {
+    const seen = away ? `landed on ${landed.pathname}` : "the page is a sign-in form";
+    return {
+      kind: "signin",
+      level: "hard",
+      ...where,
+      message: `asked for ${asked.pathname}, ${seen}: no session for ${host}. ${LADDER}`
+    };
+  }
+  if (away) {
+    return {
+      kind: "redirect",
+      level: "soft",
+      ...where,
+      message: `asked for ${asked.pathname}, landed on ${landed.pathname}: the site sent the recorder elsewhere, which is what a page behind a login does to a stranger. If that is the page you meant, record it by its own URL. ${LADDER}`
+    };
+  }
+  return null;
+}
+var WallError = class extends Error {
+  constructor(verdict) {
+    super(verdict.message);
+    this.verdict = verdict;
+    this.name = "WallError";
+  }
+  verdict;
+};
+var WALL_PROBE = `(() => {
+  const shown = (el) => {
+    const r = el.getBoundingClientRect()
+    if (r.width < 2 || r.height < 2) return false
+    const s = getComputedStyle(el)
+    return s.visibility !== 'hidden' && s.display !== 'none'
+  }
+  const pw = [...document.querySelectorAll('input[type="password"]')].filter(shown)
+  const otp = [...document.querySelectorAll('input[autocomplete="one-time-code"]')].filter(shown)
+  return {
+    passwordFields: pw.length,
+    newPasswordField: pw.some((el) => (el.getAttribute('autocomplete') || '').includes('new-password')),
+    oneTimeCodeField: otp.length > 0,
+  }
+})()`;
+
 // src/plugin/recorder.ts
 var realSleep = (ms) => new Promise((r) => setTimeout(r, ms));
 var DRY_PAUSE_MS = 120;
@@ -6661,11 +6791,30 @@ async function recordTake(browser, url, actions, paths, log, opts = {}) {
   });
   log(`goto ${url}`);
   let navTimeout = false;
-  await page.goto(url, { waitUntil: "networkidle", timeout: 45e3 }).catch(() => {
+  const response = await page.goto(url, { waitUntil: "networkidle", timeout: 45e3 }).catch(() => {
     navTimeout = true;
     log("   (networkidle timeout \u2014 continuing)");
+    return null;
   });
   await sleep(800);
+  let wall = null;
+  if (opts.onArrival) {
+    const seen = await page.evaluate(WALL_PROBE).catch(() => null);
+    try {
+      wall = await opts.onArrival({
+        askedUrl: url,
+        landedUrl: page.url(),
+        ...response ? { status: response.status() } : {},
+        passwordFields: seen?.passwordFields ?? 0,
+        newPasswordField: seen?.newPasswordField ?? false,
+        oneTimeCodeField: seen?.oneTimeCodeField ?? false
+      }) ?? null;
+    } catch (e) {
+      await context.close().catch(() => {
+      });
+      throw e;
+    }
+  }
   const cdp = await context.newCDPSession(page);
   const frames = [];
   let frameIdx = 0;
@@ -6954,7 +7103,8 @@ async function recordTake(browser, url, actions, paths, log, opts = {}) {
     pageTitle,
     platform: process.platform === "darwin" ? "mac" : process.platform === "win32" ? "windows" : "linux",
     producer: "cli",
-    steps: stepSpans
+    steps: stepSpans,
+    ...wall ? { wall: { kind: wall.kind, asked: wall.asked, landed: wall.landed } } : {}
   };
   const freezes = [];
   for (let i = 1; i < frames.length; i++) {
@@ -6989,6 +7139,7 @@ async function recordTake(browser, url, actions, paths, log, opts = {}) {
     pace,
     skipped,
     navTimeout,
+    wall,
     freezes,
     freezePct,
     capped
@@ -10140,14 +10291,15 @@ var BOOLEAN_FLAGS5 = /* @__PURE__ */ new Set([
   "motion",
   "leader",
   "keep-frames",
-  "dry-run"
+  "dry-run",
+  "allow-wall"
 ]);
 var MULTI_FLAGS2 = /* @__PURE__ */ new Set(["set", "override", "browser-arg"]);
 var HELP = `vos \u2014 record a browser flow, plan effects, render a product video; sync with vos.so
 
 Take pipeline
-  vos create --actions actions.json [--url <url>] [--out take] [out.webm] [--strict] [--keep-frames] [--max-duration <s>] [--storage-state <file>] [--browser-arg=<switch>]... [--background <slug|url|none>] [render flags] [--json]
-  vos record --actions actions.json [--url <url>] [--out take] [--strict] [--dry-run] [--keep-frames] [--max-duration <s>] [--storage-state <file>] [--browser-arg=<switch>]... [--background <slug|url|none>] [--json]
+  vos create --actions actions.json [--url <url>] [--out take] [out.webm] [--strict] [--allow-wall] [--keep-frames] [--max-duration <s>] [--storage-state <file>] [--browser-arg=<switch>]... [--background <slug|url|none>] [render flags] [--json]
+  vos record --actions actions.json [--url <url>] [--out take] [--strict] [--dry-run] [--allow-wall] [--keep-frames] [--max-duration <s>] [--storage-state <file>] [--browser-arg=<switch>]... [--background <slug|url|none>] [--json]
   vos plan <take> [--fresh] [--reuse [--from <doc.json>]] [--style <doc.json|vosId>] [--with <doc.json|vosId>[@end|@start|@step:<id>|@<s>]]... [--background <slug|url|none>] [--motion] [--headline "\u2026"] [--kicker "\u2026"] [--launch LAUNCH.md] [--brand BRAND.md] [--music <slug|mood|none>] [--entrance tilt-in|pull-out|rise|fade|slide|none] [--transitions slide|fade|scale|none] [--end-card on|none|<doc.json|vosId>] [--captions none] [--clicks none] [--still <t>] [--release v2.1] [--json]
   vos render <take> [out.webm] [--width] [--height] [--fps] [--format webm|mp4] [--parallel N] [--range a..b] [--draft] [--frame <kind>] [--background <url|slug>] [--set <path=value>]... [--json]
   vos frames <take> [--times 0,25%,50%,75%,100%] [--frame <t>] [--at-zooms] [--at-moments] [--at-still] [--size WxH] [--out dir] [--background <url|slug>] [--set <path=value>]... [--json]
@@ -10456,6 +10608,24 @@ async function releaseFrames(paths, flags, log) {
       `released ${Math.round(freed / 1e6)} MB of screencast frames (the recording holds them now; --keep-frames keeps them)`
     );
 }
+function wallGate(flags, r, opts) {
+  const allow = flags["allow-wall"] === true;
+  return async (arrival) => {
+    const verdict = wallVerdict(arrival);
+    if (verdict && !allow && (verdict.level === "hard" || opts.strict)) {
+      r.event({ event: "wall", ...verdict, refused: true });
+      throw new WallError(verdict);
+    }
+    if (verdict) {
+      r.event({ event: "wall", ...verdict, refused: false });
+      r.log(
+        allow ? `   note: recording past the wall (--allow-wall): landed on ${verdict.landed}` : `   WARNING: ${verdict.message}`
+      );
+    }
+    await opts.prepare?.();
+    return verdict;
+  };
+}
 async function cmdRecord(argv) {
   const { positionals, flags, multi } = parseArgs(
     argv,
@@ -10491,7 +10661,12 @@ async function cmdRecord(argv) {
         actions,
         takePaths(outDir),
         r.log,
-        { storageState, dryRun: true }
+        {
+          storageState,
+          dryRun: true,
+          // A rehearsal is always strict, and it touches no directory.
+          onArrival: wallGate(flags, r, { strict: true })
+        }
       );
       const steps = rec.meta.steps ?? [];
       const lines = steps.map((s) => {
@@ -10500,6 +10675,12 @@ async function cmdRecord(argv) {
         return `  ${s.skipped ? "\u2717" : "\u2713"} #${s.step}${s.id ? ` (${s.id})` : ""} ${s.do}${what}${s.skipped ? "  NOT FOUND" : rect}${s.navigated ? "  \u2192 navigated" : ""}`;
       });
       const failed2 = rec.skipped.length > 0 || rec.navTimeout;
+      const carried = [
+        ...strFlag(flags, "storage-state") ? [`--storage-state ${strFlag(flags, "storage-state")}`] : [],
+        ...browserArgs.map((a) => `--browser-arg=${a}`),
+        ...flags["allow-wall"] === true ? ["--allow-wall"] : []
+      ].join(" ");
+      const nextOut = strFlag(flags, "out") ?? "take";
       r.done(
         {
           dryRun: true,
@@ -10511,28 +10692,35 @@ async function cmdRecord(argv) {
         },
         `${failed2 ? "REHEARSAL FAILED" : "Rehearsal passed"}: ${steps.length - rec.skipped.length}/${steps.length} steps resolved in ${((Date.now() - started) / 1e3).toFixed(1)}s${rec.navTimeout ? " (the first load never reached networkidle)" : ""}
 ${lines.join("\n")}
-  ${failed2 ? "Fix the script, rehearse again, then record." : `Rects are capture px (the step rects a pin or a callout reads). Next: vos record --actions ${actionsPath} --out ${outDir} --strict`}`
+  ${failed2 ? "Fix the script, rehearse again, then record." : `Rects are capture px (the step rects a pin or a callout reads). Next: vos record --actions ${actionsPath} --out ${nextOut}${carried ? ` ${carried}` : ""} --strict`}`
       );
       return failed2 ? EXIT_USAGE : EXIT_OK;
     } finally {
       await browser2.close();
     }
   }
-  if (existsSync15(join18(outDir, "meta.json"))) {
-    const { prevDoc, kept } = await prepareReRecord(outDir);
-    r.log(
-      `note: re-recording ${outDir} \u2014 kept ${kept.length ? kept.join(", ") : "nothing"}` + (prevDoc ? "; apply the previous cut to the new footage with: vos plan " + outDir + " --reuse" : "")
-    );
-  }
-  await mkdir10(outDir, { recursive: true });
-  const paths = await ensureTakeDir(outDir);
+  const paths = takePaths(outDir);
+  const prepare = async () => {
+    if (existsSync15(join18(outDir, "meta.json"))) {
+      const { prevDoc, kept } = await prepareReRecord(outDir);
+      r.log(
+        `note: re-recording ${outDir} \u2014 kept ${kept.length ? kept.join(", ") : "nothing"}` + (prevDoc ? "; apply the previous cut to the new footage with: vos plan " + outDir + " --reuse" : "")
+      );
+    }
+    await mkdir10(outDir, { recursive: true });
+    await ensureTakeDir(outDir);
+  };
   const browser = await launchBrowser(browserArgs);
   try {
     r.log("recording\u2026");
     r.event({ event: "phase", phase: "record" });
     const rec = await recordTake(browser, url, actions, paths, r.log, {
       maxDurationSeconds,
-      storageState
+      storageState,
+      onArrival: wallGate(flags, r, {
+        strict: flags.strict === true,
+        prepare
+      })
     });
     r.event({ event: "phase", phase: "encode" });
     r.log("encoding\u2026");
@@ -10564,6 +10752,7 @@ ${lines.join("\n")}
         freezePct: rec.freezePct,
         capped: rec.capped,
         pace: rec.pace,
+        ...rec.wall ? { wall: rec.wall } : {},
         ...strictFail ? { strictFailed: true } : {}
       },
       strictFail ? `STRICT: take recorded but incomplete \u2014 ${strictReason(rec)}; fix the flow and re-record.${skippedNote}` : `Take ready: ${outDir}
@@ -10606,21 +10795,28 @@ async function cmdCreate2(argv) {
   const maxDurationSeconds = await maxDuration(flags, r);
   const storageState = takeStorageState(flags);
   const browserArgs = takeBrowserArgs(multi);
-  if (existsSync15(join18(outDir, "meta.json"))) {
-    const { prevDoc, kept } = await prepareReRecord(outDir);
-    r.log(
-      `note: re-recording ${outDir} \u2014 kept ${kept.length ? kept.join(", ") : "nothing"}` + (prevDoc ? "; apply the previous cut to the new footage with: vos plan " + outDir + " --reuse" : "")
-    );
-  }
-  await mkdir10(outDir, { recursive: true });
-  const paths = await ensureTakeDir(outDir);
+  const paths = takePaths(outDir);
+  const prepare = async () => {
+    if (existsSync15(join18(outDir, "meta.json"))) {
+      const { prevDoc, kept } = await prepareReRecord(outDir);
+      r.log(
+        `note: re-recording ${outDir} \u2014 kept ${kept.length ? kept.join(", ") : "nothing"}` + (prevDoc ? "; apply the previous cut to the new footage with: vos plan " + outDir + " --reuse" : "")
+      );
+    }
+    await mkdir10(outDir, { recursive: true });
+    await ensureTakeDir(outDir);
+  };
   const browser = await launchBrowser(browserArgs);
   try {
     r.log("recording\u2026");
     r.event({ event: "phase", phase: "record" });
     const rec = await recordTake(browser, url, actions, paths, r.log, {
       maxDurationSeconds,
-      storageState
+      storageState,
+      onArrival: wallGate(flags, r, {
+        strict: flags.strict === true,
+        prepare
+      })
     });
     r.event({ event: "phase", phase: "encode" });
     r.log("encoding\u2026");
@@ -11243,12 +11439,14 @@ async function cmdDigest(argv) {
         sourceDuration: d.take.sourceDuration,
         outputDuration: d.take.outputDuration,
         hasCursor: d.take.hasCursor,
+        ...d.take.wall ? { wall: d.take.wall } : {},
         tokensEstimate: d.images.tokensEstimate,
         bytes: result.bytes
       },
       `Wrote ${result.file} \u2014 ${d.moments.length} moments (${Object.entries(
         kinds
-      ).map(([k, n]) => `${n} ${k}`).join(", ")}), ${d.images.full} frames + ${d.images.crop} crops` + (d.images.sheet ? `, sheet.png` : "") + ` \u2014 ~${d.images.tokensEstimate} image tokens to read them all` + (d.take.hasCursor ? "" : "\n  no cursor track: moments are head/tail/scenes only \u2014 pace by activity, zoom only where the ask names a place") + `
+      ).map(([k, n]) => `${n} ${k}`).join(", ")}), ${d.images.full} frames + ${d.images.crop} crops` + (d.images.sheet ? `, sheet.png` : "") + ` \u2014 ~${d.images.tokensEstimate} image tokens to read them all` + (d.take.hasCursor ? "" : "\n  no cursor track: moments are head/tail/scenes only \u2014 pace by activity, zoom only where the ask names a place") + (d.take.wall ? `
+  WALL: asked for ${d.take.wall.asked}, recorded ${d.take.wall.landed} \u2014 this footage may be the wrong page; re-record with a session before cutting it` : "") + `
   Read digest.json, then the sheet, then a crop only where you must decide.`
     );
     return EXIT_OK;
@@ -11650,6 +11848,23 @@ async function cmdPull2(argv) {
   );
   return EXIT_OK;
 }
+function verbHelp(verb) {
+  const lines = HELP.split("\n");
+  const out = [];
+  let taking = false;
+  for (const line of lines) {
+    if (/^ {2}vos /.test(line)) taking = line.startsWith(`  vos ${verb} `);
+    else if (taking && !/^ {3,}\S/.test(line)) taking = false;
+    if (taking) out.push(line);
+  }
+  if (out.length === 0) return `vos ${verb}: no such verb here. Run: vos help
+`;
+  return `${out.join("\n")}
+
+The whole reference, with every flag explained: https://vos.so/llms-full.txt
+Exit codes: 0 ok, 1 error, 2 usage or --strict failure, 3 no browser, 4 the recorder met a sign-in instead of the page.
+`;
+}
 async function run(argv) {
   const [cmd, ...rest] = argv;
   try {
@@ -11657,6 +11872,10 @@ async function run(argv) {
       process.stdout.write(HELP);
       return cmd ? EXIT_OK : EXIT_USAGE;
     }
+    if (rest.includes("--help") || rest.includes("-h")) {
+      process.stdout.write(verbHelp(cmd));
+      return EXIT_OK;
+    }
     switch (cmd) {
       case "create":
         return await cmdCreate2(rest);
@@ -11721,6 +11940,11 @@ async function run(argv) {
 `);
       return EXIT_USAGE;
     }
+    if (e instanceof WallError) {
+      process.stderr.write(`wall: ${e.message}
+`);
+      return EXIT_WALL;
+    }
     if (e instanceof BrowserUnavailableError) {
       process.stderr.write(`${e.message}
 `);
@@ -11762,6 +11986,7 @@ export {
   MULTI_FLAGS2 as MULTI_FLAGS,
   HELP,
   takeBrowserArgs,
+  verbHelp,
   run
 };
-//# sourceMappingURL=chunk-7TDL3N24.js.map
+//# sourceMappingURL=chunk-4QVEV3HX.js.map