@vosjs/cli 0.44.0 → 0.45.1

package/dist/{chunk-WCSAECM4.js → chunk-4HW2XR5K.js}

@@ -22,8 +22,8 @@ import {
 
 // src/plugin/run.ts
 import { mkdir as mkdir10, readFile as readFile15, rm as rm5 } from "fs/promises";
-import { existsSync as existsSync15 } from "fs";
-import { join as join18, resolve as resolve9 } from "path";
+import { existsSync as existsSync16 } from "fs";
+import { join as join19, resolve as resolve9 } from "path";
 import {
   END_CARD_FROM as END_CARD_FROM2,
   docOutputDuration as docOutputDuration3,
@@ -7043,12 +7043,14 @@ async function recordTake(browser, url, actions, paths, log, opts = {}) {
   const maxSeconds = dry ? Infinity : opts.maxDurationSeconds ?? Infinity;
   const vw = actions.viewport?.width ?? 1280;
   const vh = actions.viewport?.height ?? 720;
-  const context = await browser.newContext({
+  const context = opts.context ?? await browser.newContext({
     viewport: { width: vw, height: vh },
     deviceScaleFactor: 1,
     ...opts.storageState ? { storageState: opts.storageState } : {},
     ...opts.headers && Object.keys(opts.headers).length ? { extraHTTPHeaders: opts.headers } : {}
   });
+  if (opts.context && opts.headers && Object.keys(opts.headers).length)
+    await context.setExtraHTTPHeaders(opts.headers);
   const masks = actions.mask ?? [];
   if (masks.length) await context.addInitScript(maskInitScript(masks));
   const exposureLog = new ExposureLog(masks);
@@ -7437,6 +7439,149 @@ async function recordTake(browser, url, actions, paths, log, opts = {}) {
   };
 }
 
+// src/plugin/session.ts
+import { spawn } from "child_process";
+import { existsSync as existsSync12, mkdirSync as mkdirSync2, readdirSync as readdirSync2, rmSync, statSync as statSync3 } from "fs";
+import { homedir as homedir2 } from "os";
+import { join as join14 } from "path";
+import { chromium } from "playwright";
+var SESSIONS_DIR = join14(homedir2(), ".config", "vos", "sessions");
+var NAME = /^[a-z0-9][a-z0-9._-]{0,63}$/i;
+function sessionNameVerdict(name) {
+  if (!name) return "a session needs a name: --name <app>";
+  if (!NAME.test(name) || name.includes(".."))
+    return `"${name}" is not a session name: letters, digits, . _ - only, up to 64`;
+  return null;
+}
+function sessionDir(name) {
+  return join14(SESSIONS_DIR, name);
+}
+function systemChromePath() {
+  const explicit = process.env.VOS_BROWSER_PATH;
+  if (explicit) return explicit;
+  const candidates = process.platform === "darwin" ? ["/Applications/Google Chrome.app/Contents/MacOS/Google Chrome"] : process.platform === "win32" ? [
+    join14(
+      process.env["PROGRAMFILES"] ?? "C:\\Program Files",
+      "Google",
+      "Chrome",
+      "Application",
+      "chrome.exe"
+    ),
+    join14(
+      process.env["LOCALAPPDATA"] ?? "",
+      "Google",
+      "Chrome",
+      "Application",
+      "chrome.exe"
+    )
+  ] : [
+    "/usr/bin/google-chrome",
+    "/usr/bin/google-chrome-stable",
+    "/opt/google/chrome/chrome"
+  ];
+  const found = candidates.find((c) => existsSync12(c));
+  if (!found)
+    throw new Error(
+      "no Google Chrome found: a session needs the system Chrome (the bundled Chromium cannot read a profile Chrome wrote). Install Chrome, or set VOS_BROWSER_PATH"
+    );
+  return found;
+}
+async function openSession(name, url, opts = { log: () => {
+} }) {
+  const dir = sessionDir(name);
+  mkdirSync2(dir, { recursive: true, mode: 448 });
+  const exe = systemChromePath();
+  const args = [
+    `--user-data-dir=${dir}`,
+    "--no-first-run",
+    "--no-default-browser-check",
+    "--window-size=1100,800",
+    url
+  ];
+  const leave = process.platform === "darwin" ? "then quit Chrome with \u2318Q (closing the window alone leaves it running, and this waiting)" : "then close the window";
+  opts.log(
+    `a Chrome window opened on session "${name}": sign in to ${new URL(url).host}, ${leave}`
+  );
+  return new Promise((resolve10, reject) => {
+    const child = spawn(exe, args, { stdio: "ignore" });
+    child.on("error", reject);
+    child.on("exit", (code) => resolve10({ code }));
+  });
+}
+async function withSession(name, fn, opts = {}) {
+  const dir = sessionDir(name);
+  if (!existsSync12(dir))
+    throw new Error(`no session "${name}" (vos session list)`);
+  const explicit = process.env.VOS_BROWSER_PATH;
+  const ctx = await chromium.launchPersistentContext(dir, {
+    headless: opts.headless ?? true,
+    ...explicit ? { executablePath: explicit } : { channel: "chrome" },
+    // The real keychain: the whole reason a profile Chrome wrote can be read.
+    ignoreDefaultArgs: ["--use-mock-keychain"],
+    ...opts.viewport ? { viewport: opts.viewport, deviceScaleFactor: 1 } : {}
+  });
+  try {
+    return await fn(ctx);
+  } finally {
+    await ctx.close().catch(() => {
+    });
+  }
+}
+async function summarizeSession(name) {
+  const dir = sessionDir(name);
+  const created = statSync3(dir).birthtimeMs || statSync3(dir).mtimeMs;
+  return withSession(name, async (ctx) => {
+    const cookies = await ctx.cookies();
+    const byHost = /* @__PURE__ */ new Map();
+    let newest = 0;
+    let sessionOnly = 0;
+    for (const c of cookies) {
+      const host = c.domain.replace(/^\./, "");
+      byHost.set(host, (byHost.get(host) ?? 0) + 1);
+      if (c.expires && c.expires > 0) newest = Math.max(newest, c.expires);
+      else sessionOnly++;
+    }
+    return {
+      name,
+      origins: [...byHost.entries()].map(([host, n]) => ({ host, cookies: n })).sort((a, b) => b.cookies - a.cookies),
+      newestExpires: newest ? new Date(newest * 1e3).toISOString() : null,
+      sessionOnly,
+      ageDays: Math.floor((Date.now() - created) / 864e5)
+    };
+  });
+}
+function summaryLine(s) {
+  if (!s.origins.length)
+    return `session "${s.name}" holds no cookies: the window closed before a sign-in landed, or the sign-in never happened`;
+  const hosts = s.origins.slice(0, 4).map((o) => `${o.host} (${o.cookies})`).join(", ");
+  const more = s.origins.length > 4 ? ` and ${s.origins.length - 4} more` : "";
+  const exp = s.newestExpires ? `newest expires in ${Math.max(0, Math.round((new Date(s.newestExpires).getTime() - Date.now()) / 864e5))} days` : "every cookie dies with the window (the app set no expiry), so this session cannot be reused";
+  return `session "${s.name}" holds cookies for ${hosts}${more}; ${exp}`;
+}
+function listSessions() {
+  if (!existsSync12(SESSIONS_DIR)) return [];
+  return readdirSync2(SESSIONS_DIR, { withFileTypes: true }).filter((d) => d.isDirectory() && NAME.test(d.name)).map((d) => {
+    const st = statSync3(join14(SESSIONS_DIR, d.name));
+    return {
+      name: d.name,
+      ageDays: Math.floor(
+        (Date.now() - (st.birthtimeMs || st.mtimeMs)) / 864e5
+      )
+    };
+  }).sort((a, b) => a.name.localeCompare(b.name));
+}
+function removeSession(name) {
+  const dir = sessionDir(name);
+  if (!existsSync12(dir)) return false;
+  rmSync(dir, { recursive: true, force: true });
+  return true;
+}
+function looksLikeStorageState(value) {
+  if (typeof value !== "object" || value === null) return false;
+  const v = value;
+  return Array.isArray(v.cookies) && Array.isArray(v.origins);
+}
+
 // src/plugin/encode.ts
 var MEDIABUNNY_URL2 = "https://esm.sh/mediabunny@1.55.7?target=es2022";
 var ENCODE_HTML = `<!doctype html><html><head><meta charset="utf-8"></head><body>
@@ -7492,9 +7637,9 @@ async function encodeRecording(browser, takeDir, onProgress) {
 }
 
 // src/plugin/plan.ts
-import { existsSync as existsSync12 } from "fs";
+import { existsSync as existsSync13 } from "fs";
 import { readFile as readFile12 } from "fs/promises";
-import { join as join14 } from "path";
+import { join as join15 } from "path";
 import {
   DEFAULT_FRAME_STYLE,
   STYLE_FIELDS,
@@ -7716,8 +7861,8 @@ function retimeCut(prev, newSteps, newDurationMs) {
 // src/plugin/plan.ts
 var overlaps = (a, b) => a.in < b.out && b.in < a.out;
 async function readDigestActivity(dir) {
-  const file = join14(dir, "digest", "digest.json");
-  if (!existsSync12(file)) return null;
+  const file = join15(dir, "digest", "digest.json");
+  if (!existsSync13(file)) return null;
   try {
     const d = JSON.parse(await readFile12(file, "utf8"));
     return Array.isArray(d.activity) && d.activity.every((v) => typeof v === "number") ? d.activity : null;
@@ -7929,15 +8074,15 @@ async function planTake(dir, opts = {}) {
 
 // src/plugin/sync.ts
 import { createHash } from "crypto";
-import { existsSync as existsSync13 } from "fs";
+import { existsSync as existsSync14, readFileSync as readFileSync4, readdirSync as readdirSync3 } from "fs";
 import { readFile as readFile13 } from "fs/promises";
 import { createInterface } from "readline/promises";
-import { basename as basename3, join as join16 } from "path";
+import { basename as basename3, join as join17 } from "path";
 import { lowerToComposition as lowerToComposition3, migrateHostedDoc as migrateHostedDoc3 } from "@vosjs/studio-core";
 
 // src/plugin/folder.ts
 import { mkdir as mkdir8, writeFile as writeFile10 } from "fs/promises";
-import { join as join15 } from "path";
+import { join as join16 } from "path";
 import { recipeHints } from "@vosjs/shared/frontmatter";
 import { migrateHostedDoc as migrateHostedDoc2 } from "@vosjs/studio-core";
 var BOOLEAN_FLAGS = /* @__PURE__ */ new Set(["json", "help", "media"]);
@@ -8113,18 +8258,18 @@ async function cmdPull(argv) {
     throw new Error(apiError(`pull folder ${folder.slug}`, res));
   const payload = res.body;
   const out = strFlag(flags, "out") ?? folder.slug;
-  await mkdir8(join15(out, "recipes"), { recursive: true });
+  await mkdir8(join16(out, "recipes"), { recursive: true });
   const lines = [];
   const recipes = [];
   for (const rec of payload.recipes) {
-    const path = join15(out, "recipes", safeName(rec.filename));
+    const path = join16(out, "recipes", safeName(rec.filename));
     await writeFile10(path, rec.body ?? "");
     recipes.push({ path, line: recipeLine(rec.filename, rec.body ?? "") });
   }
   for (const rec of payload.inheritedRecipes) {
     const from = safeName(rec.folderSlug ?? "inherited");
-    await mkdir8(join15(out, "recipes", "_inherited", from), { recursive: true });
-    const path = join15(
+    await mkdir8(join16(out, "recipes", "_inherited", from), { recursive: true });
+    const path = join16(
       out,
       "recipes",
       "_inherited",
@@ -8139,7 +8284,7 @@ async function cmdPull(argv) {
   }
   const members = [];
   for (const v of payload.voses) {
-    const dir = join15(out, "members", safeName(v.slug || v.title || v.id));
+    const dir = join16(out, "members", safeName(v.slug || v.title || v.id));
     await mkdir8(dir, { recursive: true });
     const cfg = await apiJson(origin, `/api/vos/${v.id}/config`, { key });
     if (cfg.status !== 200) {
@@ -8147,7 +8292,7 @@ async function cmdPull(argv) {
       continue;
     }
     await writeFile10(
-      join15(dir, "config.json"),
+      join16(dir, "config.json"),
       JSON.stringify(cfg.body.config, null, 2)
     );
     let take = false;
@@ -8159,7 +8304,7 @@ async function cmdPull(argv) {
       );
       if (doc.status === 200) {
         await writeFile10(
-          join15(dir, "doc.json"),
+          join16(dir, "doc.json"),
           JSON.stringify(doc.body, null, 2)
         );
         take = true;
@@ -8428,7 +8573,24 @@ function programPushTarget(ask) {
   }
   return { kind: "version", vosId: tracked, tracked: true };
 }
+function storageStateInDir(dir) {
+  for (const f of readdirSync3(dir)) {
+    if (!f.endsWith(".json") || f === "doc.json" || f === "meta.json" || f === "actions.json" || f === "cursor.json" || f === "vos.json" || f === "doc.prev.json")
+      continue;
+    try {
+      const v = JSON.parse(readFileSync4(join17(dir, f), "utf8"));
+      if (looksLikeStorageState(v)) return join17(dir, f);
+    } catch {
+    }
+  }
+  return null;
+}
 async function pushTake(dir, flags, r) {
+  const stateFile = storageStateInDir(dir);
+  if (stateFile)
+    throw new Error(
+      `${stateFile} looks like a Playwright storage state (cookies + origins): a live session in the take directory would be uploaded with it. Move it out of the take (a session belongs under ~/.config/vos/sessions or a temp dir) and push again`
+    );
   const take = await loadTake(dir);
   if (!take.doc) {
     throw new Error("no doc.json in this take \u2014 run `vos plan` first");
@@ -8438,7 +8600,7 @@ async function pushTake(dir, flags, r) {
     throw new Error(`doc.json fails lint:
   ${lint.problems.join("\n  ")}`);
   }
-  if (!existsSync13(take.paths.recording)) {
+  if (!existsSync14(take.paths.recording)) {
     throw new Error(
       "no recording in this take \u2014 record it, or `vos pull --media` to bring it home"
     );
@@ -8530,8 +8692,8 @@ async function pushTake(dir, flags, r) {
     delete docForPush.source.micKey;
   }
   for (const ref of docMediaRefs(docForPush)) {
-    const file = join16(dir, takeRelativeFile(ref.key));
-    if (!existsSync13(file)) {
+    const file = join17(dir, takeRelativeFile(ref.key));
+    if (!existsSync14(file)) {
       r.log(`  ${ref.where}: ${ref.key} is not in the take \u2014 left as is`);
       continue;
     }
@@ -8675,9 +8837,9 @@ async function pullTake(dir, flags, r) {
       };
     }
     let media2;
-    if (flags.media && existsSync13(join16(dir, "doc.json"))) {
+    if (flags.media && existsSync14(join17(dir, "doc.json"))) {
       const local = JSON.parse(
-        await readFile13(join16(dir, "doc.json"), "utf8")
+        await readFile13(join17(dir, "doc.json"), "utf8")
       );
       media2 = await pullMedia(ctx, dir, local, r.log);
     }
@@ -8738,10 +8900,10 @@ async function pullTake(dir, flags, r) {
   const hostedDoc = migrateHostedDoc3(docRes.json);
   const doc = hostedDoc;
   const localRecording = takeMediaFile(dir, "recording", RECORDING_NAME);
-  if (existsSync13(localRecording)) {
+  if (existsSync14(localRecording)) {
     doc.source.videoKey = basename3(localRecording);
   }
-  await writeJson(join16(dir, "doc.json"), doc, true);
+  await writeJson(join17(dir, "doc.json"), doc, true);
   const media = flags.media ? await pullMedia(ctx, dir, doc, r.log) : void 0;
   const versions = await api(ctx, `/vos/${vosId}/versions`);
   const headRow = (versions.json.versions ?? []).find((v) => v.id === head);
@@ -8760,10 +8922,10 @@ async function pullTake(dir, flags, r) {
 }
 
 // src/plugin/program.ts
-import { existsSync as existsSync14 } from "fs";
+import { existsSync as existsSync15 } from "fs";
 import { mkdir as mkdir9, readFile as readFile14, writeFile as writeFile11 } from "fs/promises";
 import { createInterface as createInterface2 } from "readline/promises";
-import { basename as basename4, dirname as dirname4, join as join17 } from "path";
+import { basename as basename4, dirname as dirname4, join as join18 } from "path";
 import {
   CURRENT_CONFIG_VERSION,
   migrateConfig,
@@ -8933,8 +9095,8 @@ function preflightConfig(parsed) {
 }
 function resolveConfigPath(target) {
   if (target.endsWith(".json")) return target;
-  const inDir = join17(target, "config.json");
-  if (existsSync14(inDir)) return inDir;
+  const inDir = join18(target, "config.json");
+  if (existsSync15(inDir)) return inDir;
   throw new UsageError(
     `${target} has no config.json (and is not a take \u2014 no doc.json)`
   );
@@ -8962,7 +9124,7 @@ async function cmdFetch(argv) {
   const out = strFlag(flags, "out") ?? slug;
   await mkdir9(out, { recursive: true });
   await writeFile11(
-    join17(out, "config.json"),
+    join18(out, "config.json"),
     JSON.stringify(cfg.body.config, null, 2)
   );
   const title = typeof vosMeta.title === "string" ? vosMeta.title : "";
@@ -8987,12 +9149,12 @@ async function cmdFetch(argv) {
       const hosted = migrateHostedDoc4(doc.body);
       const { config: own } = await writeProgramDoc(out, hosted);
       if (own) {
-        await writeFile11(join17(out, "config.json"), JSON.stringify(own, null, 2));
+        await writeFile11(join18(out, "config.json"), JSON.stringify(own, null, 2));
       }
     } else if (doc.status === 200) {
       take = true;
       const hosted = migrateHostedDoc4(doc.body);
-      await writeFile11(join17(out, "doc.json"), JSON.stringify(hosted, null, 2));
+      await writeFile11(join18(out, "doc.json"), JSON.stringify(hosted, null, 2));
       if (flags.media === true) {
         const media = await pullMedia({ origin, key }, out, hosted, r.log);
         mediaLine = media.downloaded.length ? ` + ${media.downloaded.map((m) => m.file).join(", ")}` : "";
@@ -9355,10 +9517,10 @@ async function cmdPullProgram(argv) {
   const cfg = await apiJson(origin, `/api/vos/${vosId}/config`, { key });
   if (cfg.status !== 200)
     throw new Error(apiError(`fetch head config for ${vosId}`, cfg));
-  const configPath = join17(dir, "config.json");
+  const configPath = join18(dir, "config.json");
   let backedUp = false;
-  if (existsSync14(configPath)) {
-    await writeFile11(join17(dir, "config.backup.json"), await readFile14(configPath));
+  if (existsSync15(configPath)) {
+    await writeFile11(join18(dir, "config.backup.json"), await readFile14(configPath));
     backedUp = true;
   }
   let headConfig = cfg.body.config;
@@ -9391,7 +9553,7 @@ async function cmdPullProgram(argv) {
       protected: protectedIds,
       changes,
       out: configPath,
-      backup: backedUp ? join17(dir, "config.backup.json") : null
+      backup: backedUp ? join18(dir, "config.backup.json") : null
     },
     `Pulled ${changes.length} version${changes.length === 1 ? "" : "s"} \u2192 ${configPath}` + (backedUp ? ` (previous copy: config.backup.json)` : "") + `
 Re-apply your edit on the new head, then: vos push ${configPath} --vos ${vosId}`
@@ -9453,8 +9615,8 @@ function storedProgramConfig(config, programDoc) {
   return lowerProgramDoc(doc).config;
 }
 async function readProgramDoc(dir, config) {
-  const docPath = join17(dir, "doc.json");
-  if (!existsSync14(docPath)) return null;
+  const docPath = join18(dir, "doc.json");
+  if (!existsSync15(docPath)) return null;
   const parsed = JSON.parse(await readFile14(docPath, "utf8"));
   if (typeof parsed !== "object" || parsed === null || "source" in parsed)
     return null;
@@ -9466,14 +9628,14 @@ async function writeProgramDoc(dir, hosted) {
   const program = hosted.program && typeof hosted.program === "object" ? hosted.program : {};
   const { config, ...rest } = program;
   const onDisk = { ...hosted, program: rest };
-  await writeFile11(join17(dir, "doc.json"), JSON.stringify(onDisk, null, 2));
+  await writeFile11(join18(dir, "doc.json"), JSON.stringify(onDisk, null, 2));
   return {
     config: config && typeof config === "object" ? config : null
   };
 }
 
 // src/plugin/asset.ts
-import { readFileSync as readFileSync4 } from "fs";
+import { readFileSync as readFileSync5 } from "fs";
 import { basename as basename5, extname as extname2 } from "path";
 var BOOLEAN_FLAGS3 = /* @__PURE__ */ new Set(["json", "help"]);
 var MIME_BY_EXT = {
@@ -9527,7 +9689,7 @@ async function cmdPush(argv) {
   for (const file of positionals) {
     const name = basename5(file);
     const mime = MIME_BY_EXT[extname2(name).toLowerCase()] ?? "application/octet-stream";
-    const body = readFileSync4(file);
+    const body = readFileSync5(file);
     const form = new FormData();
     form.set("file", new Blob([body], { type: mime }), name);
     if (folder) form.set("folderId", folder.id);
@@ -9581,7 +9743,7 @@ async function cmdAsset(argv) {
 }
 
 // src/plugin/recipe.ts
-import { readFileSync as readFileSync5 } from "fs";
+import { readFileSync as readFileSync6 } from "fs";
 import { basename as basename6 } from "path";
 var BOOLEAN_FLAGS4 = /* @__PURE__ */ new Set(["json", "help"]);
 var USAGE = "vos recipe push <file.md> (--folder <folderId|slug> | --asset <assetId>)";
@@ -9601,7 +9763,7 @@ async function cmdPush2(argv) {
     throw new UsageError(USAGE);
   }
   const filename = recipeFilename(file);
-  const body = readFileSync5(file);
+  const body = readFileSync6(file);
   const r = createReporter(flags.json === true);
   const origin = platformOrigin({
     origin: strFlag(flags, "origin"),
@@ -10602,8 +10764,8 @@ var MULTI_FLAGS2 = /* @__PURE__ */ new Set(["set", "override", "browser-arg", "h
 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] [--allow-wall] [--keep-frames] [--max-duration <s>] [--storage-state <file>] [--header name=value]... [--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>] [--header name=value]... [--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>|--session <name>] [--header name=value]... [--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>|--session <name>] [--header name=value]... [--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]
@@ -10615,6 +10777,9 @@ Take pipeline
   vos validate <actions.json|take|kit.json> [--picture] [--json]
   vos judge <kit.json> --against <MANIFEST.json> [--out dir] [--json]
   vos actions from-agent-browser <steps.jsonl> [--out actions.json] [--url <url>] [--viewport WxH] [--json]
+  vos session open <url> --name <app>   a plain Chrome window on a vos-owned profile; sign in, close it
+  vos session check <name> [--url <url>]   headless: does the session still open the page? exit 0/4
+  vos session list | rm <name>          what exists and how old; delete one
   vos actions script <actions.json> [--json]
             the flow as numbered beats in words, for a person recording it by hand
 
@@ -10913,10 +11078,35 @@ function takeStorageState(flags) {
   const raw = strFlag(flags, "storage-state");
   if (!raw) return void 0;
   const path = resolve9(raw);
-  if (!existsSync15(path))
+  if (!existsSync16(path))
     throw new UsageError(`--storage-state: no such file: ${path}`);
   return path;
 }
+function takeSessionName(flags, storageState) {
+  const name = strFlag(flags, "session");
+  if (!name) return void 0;
+  const bad = sessionNameVerdict(name);
+  if (bad) throw new UsageError(bad);
+  if (storageState)
+    throw new UsageError(
+      "--session and --storage-state are two doors to one take: a persistent profile cannot take a storage state. Pass one"
+    );
+  if (!existsSync16(sessionDir(name)))
+    throw new UsageError(
+      `no session "${name}". Make one: vos session open <url> --name ${name} (a Chrome window opens; sign in and close it)`
+    );
+  return name;
+}
+async function inSession(name, actions, fn) {
+  if (!name) return fn(void 0);
+  return withSession(name, (ctx) => fn(ctx), {
+    headless: true,
+    viewport: {
+      width: actions.viewport?.width ?? 1280,
+      height: actions.viewport?.height ?? 720
+    }
+  });
+}
 async function takeBackdrop(flags, r) {
   const { backdrop, note } = await openingBackdrop(
     strFlag(flags, "background"),
@@ -10974,6 +11164,7 @@ async function cmdRecord(argv) {
   const backdrop = await takeBackdrop(flags, r);
   const maxDurationSeconds = await maxDuration(flags, r);
   const storageState = takeStorageState(flags);
+  const sessionName = takeSessionName(flags, storageState);
   const browserArgs = takeBrowserArgs(multi);
   const headers = takeHeaders(multi);
   if (flags["dry-run"] === true) {
@@ -10984,19 +11175,17 @@ async function cmdRecord(argv) {
       r.log("rehearsing (nothing is captured or written)\u2026");
       r.event({ event: "phase", phase: "rehearse" });
       const started = Date.now();
-      const rec = await recordTake(
-        browser2,
-        url,
+      const rec = await inSession(
+        sessionName,
         actions,
-        takePaths(outDir),
-        r.log,
-        {
+        (context) => recordTake(browser2, url, actions, takePaths(outDir), r.log, {
           storageState,
           headers,
+          context,
           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) => {
@@ -11009,6 +11198,7 @@ async function cmdRecord(argv) {
         ...strFlag(flags, "storage-state") ? [`--storage-state ${strFlag(flags, "storage-state")}`] : [],
         ...browserArgs.map((a) => `--browser-arg=${a}`),
         ...Object.entries(headers).map(([k, v]) => `--header ${k}=${v}`),
+        ...sessionName ? [`--session ${sessionName}`] : [],
         ...flags["allow-wall"] === true ? ["--allow-wall"] : []
       ].join(" ");
       const nextOut = strFlag(flags, "out") ?? "take";
@@ -11034,7 +11224,7 @@ ${lines.join("\n")}
   }
   const paths = takePaths(outDir);
   const prepare = async () => {
-    if (existsSync15(join18(outDir, "meta.json"))) {
+    if (existsSync16(join19(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" : "")
@@ -11047,15 +11237,20 @@ ${lines.join("\n")}
   try {
     r.log("recording\u2026");
     r.event({ event: "phase", phase: "record" });
-    const rec = await recordTake(browser, url, actions, paths, r.log, {
-      maxDurationSeconds,
-      storageState,
-      headers,
-      onArrival: wallGate(flags, r, {
-        strict: flags.strict === true,
-        prepare
+    const rec = await inSession(
+      sessionName,
+      actions,
+      (context) => recordTake(browser, url, actions, paths, r.log, {
+        maxDurationSeconds,
+        storageState,
+        headers,
+        context,
+        onArrival: wallGate(flags, r, {
+          strict: flags.strict === true,
+          prepare
+        })
       })
-    });
+    );
     r.event({ event: "phase", phase: "encode" });
     r.log("encoding\u2026");
     const enc = await encodeRecording(
@@ -11093,7 +11288,7 @@ ${lines.join("\n")}
       },
       strictFail ? `STRICT: take recorded but incomplete \u2014 ${strictReason(rec)}; fix the flow and re-record.${skippedNote}${exposureNote(rec)}` : `Take ready: ${outDir}
   ${(rec.meta.durationMs / 1e3).toFixed(1)}s \xB7 ${rec.frames.length} frames \xB7 ${rec.events.length} cursor events \xB7 ${clicks} clicks \xB7 ${plan.doc.zoom.length} zoom spans planned \xB7 ${rec.freezePct}% frozen${rec.freezePct >= 25 ? " \u26A0 keep motion in frame or trim" : ""}${skippedNote}
-  Next: edit ${join18(outDir, "doc.json")} (optional), then: vos render ${outDir}${exposureNote(rec)}`
+  Next: edit ${join19(outDir, "doc.json")} (optional), then: vos render ${outDir}${exposureNote(rec)}`
     );
     return strictFail ? EXIT_USAGE : EXIT_OK;
   } finally {
@@ -11122,7 +11317,7 @@ async function cmdCreate2(argv) {
   if (fmtRaw !== "webm" && fmtRaw !== "mp4")
     throw new UsageError("--format must be webm or mp4");
   const format = fmtRaw;
-  const out = positionals[0] ?? join18(outDir, `out.${format}`);
+  const out = positionals[0] ?? join19(outDir, `out.${format}`);
   const parallel = numFlag(flags, "parallel", 1);
   if (!Number.isInteger(parallel) || parallel < 1 || parallel > 16) {
     throw new UsageError("--parallel expects an integer between 1 and 16");
@@ -11130,11 +11325,12 @@ async function cmdCreate2(argv) {
   const backdrop = await takeBackdrop(flags, r);
   const maxDurationSeconds = await maxDuration(flags, r);
   const storageState = takeStorageState(flags);
+  const sessionName = takeSessionName(flags, storageState);
   const browserArgs = takeBrowserArgs(multi);
   const headers = takeHeaders(multi);
   const paths = takePaths(outDir);
   const prepare = async () => {
-    if (existsSync15(join18(outDir, "meta.json"))) {
+    if (existsSync16(join19(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" : "")
@@ -11147,15 +11343,20 @@ async function cmdCreate2(argv) {
   try {
     r.log("recording\u2026");
     r.event({ event: "phase", phase: "record" });
-    const rec = await recordTake(browser, url, actions, paths, r.log, {
-      maxDurationSeconds,
-      storageState,
-      headers,
-      onArrival: wallGate(flags, r, {
-        strict: flags.strict === true,
-        prepare
+    const rec = await inSession(
+      sessionName,
+      actions,
+      (context) => recordTake(browser, url, actions, paths, r.log, {
+        maxDurationSeconds,
+        storageState,
+        headers,
+        context,
+        onArrival: wallGate(flags, r, {
+          strict: flags.strict === true,
+          prepare
+        })
       })
-    });
+    );
     r.event({ event: "phase", phase: "encode" });
     r.log("encoding\u2026");
     await encodeRecording(
@@ -11235,13 +11436,13 @@ async function cmdPlan(argv) {
     );
   const r = createReporter(flags.json === true);
   if (flags.fresh === true) {
-    await rm5(join18(dir, "doc.json"), { force: true });
+    await rm5(join19(dir, "doc.json"), { force: true });
     r.log("note: --fresh discarded the existing doc.json");
   }
   let reuse;
   if (flags.reuse === true) {
-    const from = resolve9(strFlag(flags, "from") ?? join18(dir, PREV_DOC_NAME));
-    if (!existsSync15(from)) {
+    const from = resolve9(strFlag(flags, "from") ?? join19(dir, PREV_DOC_NAME));
+    if (!existsSync16(from)) {
       throw new UsageError(
         `--reuse: ${from} does not exist \u2014 a re-record into this take writes doc.prev.json, or pass --from <doc.json>`
       );
@@ -11252,7 +11453,7 @@ async function cmdPlan(argv) {
     };
   }
   const style = await resolveStyleRef(flags);
-  const hasDoc = existsSync15(join18(dir, "doc.json"));
+  const hasDoc = existsSync16(join19(dir, "doc.json"));
   const backdrop = hasDoc ? null : await takeBackdrop(flags, r);
   const release = await releaseInputs(dir, flags, r, multi.with ?? []);
   const motionWanted = !hasDoc || flags.motion === true || flags.fresh === true;
@@ -11310,7 +11511,7 @@ async function cmdPlan(argv) {
       ...s.motion ? { motion: s.motion } : {},
       ...s.reuse ? { reuse: s.reuse } : {}
     },
-    `${s.reuse ? "Reused" : s.fresh ? "Planned" : "Refreshed"} ${join18(dir, "doc.json")}: ${s.zoomAuto} auto + ${s.zoomManual} manual zoom spans${s.cursorKept ? "" : " (cursor track dropped)"}${layoutLines}${motionLines}${reuseLines}`
+    `${s.reuse ? "Reused" : s.fresh ? "Planned" : "Refreshed"} ${join19(dir, "doc.json")}: ${s.zoomAuto} auto + ${s.zoomManual} manual zoom spans${s.cursorKept ? "" : " (cursor track dropped)"}${layoutLines}${motionLines}${reuseLines}`
   );
   return EXIT_OK;
 }
@@ -11436,7 +11637,7 @@ async function cmdRender(argv) {
   if (fmtRaw !== "webm" && fmtRaw !== "mp4")
     throw new UsageError("--format must be webm or mp4");
   const format = fmtRaw;
-  const out = positionals[1] ?? join18(dir, `out.${format}`);
+  const out = positionals[1] ?? join19(dir, `out.${format}`);
   const parallel = numFlag(flags, "parallel", 1);
   if (!Number.isInteger(parallel) || parallel < 1 || parallel > 16) {
     throw new UsageError("--parallel expects an integer between 1 and 16");
@@ -11683,11 +11884,11 @@ async function resolveStyleRef(flags) {
 }
 async function resolveDocRef(ref, flags, what) {
   const styleRef = ref;
-  const file = existsSync15(styleRef) ? resolve9(
+  const file = existsSync16(styleRef) ? resolve9(
     styleRef,
-    existsSync15(join18(styleRef, "doc.json")) ? "doc.json" : ""
+    existsSync16(join19(styleRef, "doc.json")) ? "doc.json" : ""
   ) : null;
-  if (file && existsSync15(file)) {
+  if (file && existsSync16(file)) {
     return {
       from: file,
       doc: migrateHostedDoc5(
@@ -11774,7 +11975,7 @@ async function cmdDigest(argv) {
         kinds,
         frames: d.images.full,
         crops: d.images.crop,
-        sheet: d.images.sheet ? join18(result.outDir, d.images.sheet) : null,
+        sheet: d.images.sheet ? join19(result.outDir, d.images.sheet) : null,
         scenes: kinds.scene ?? 0,
         sourceDuration: d.take.sourceDuration,
         outputDuration: d.take.outputDuration,
@@ -11802,7 +12003,7 @@ async function cmdOpen(argv) {
   if (!dir) throw new UsageError("vos open <take> [--studio <url>]");
   const r = createReporter(flags.json === true);
   const take = await loadTake(dir);
-  if (!existsSync15(take.paths.recording)) {
+  if (!existsSync16(take.paths.recording)) {
     throw new UsageError(`${dir} has no recording \u2014 re-run record`);
   }
   const studio = (strFlag(flags, "studio") ?? "http://localhost:6060").replace(
@@ -11843,9 +12044,9 @@ async function cmdJudge(argv) {
       "vos judge <kit.json> --against <MANIFEST.json> [--out dir] [--json]\n(the manifest names the reference set: id, file, role, layout, facts, rule per asset)"
     );
   const r = createReporter(flags.json === true);
-  const kitFile = target.endsWith("kit.json") ? target : join18(target, "kit.json");
-  if (!existsSync15(kitFile)) throw new UsageError(`${kitFile}: no kit manifest`);
-  if (!existsSync15(against))
+  const kitFile = target.endsWith("kit.json") ? target : join19(target, "kit.json");
+  if (!existsSync16(kitFile)) throw new UsageError(`${kitFile}: no kit manifest`);
+  if (!existsSync16(against))
     throw new UsageError(`${against}: no reference manifest`);
   const result = await judgeKit(kitFile, against, strFlag(flags, "out"));
   const verdicts = JSON.parse(await readFile15(result.verdictFile, "utf8")).verdicts;
@@ -11967,7 +12168,7 @@ async function cmdValidate(argv) {
   const target = positionals[0];
   if (!target) throw new UsageError("vos validate <actions.json|take>");
   const r = createReporter(flags.json === true);
-  const kitTarget = target.endsWith("kit.json") ? target : existsSync15(join18(target, "kit.json")) && !isTakeDir(target) ? join18(target, "kit.json") : null;
+  const kitTarget = target.endsWith("kit.json") ? target : existsSync16(join19(target, "kit.json")) && !isTakeDir(target) ? join19(target, "kit.json") : null;
   if (kitTarget) {
     const picture = flags.picture === true;
     const verdict = await validateKit(kitTarget, { picture });
@@ -11999,9 +12200,9 @@ async function cmdValidate(argv) {
     r.done({ valid: true, target }, `${target}: valid actions file`);
     return EXIT_OK;
   }
-  if (!isTakeDir(target) && existsSync15(join18(target, "config.json"))) {
+  if (!isTakeDir(target) && existsSync16(join19(target, "config.json"))) {
     const parsed = JSON.parse(
-      await readFile15(join18(target, "config.json"), "utf8")
+      await readFile15(join19(target, "config.json"), "utf8")
     );
     const pre = preflightConfig(parsed);
     const problems2 = pre.ok ? [] : pre.issues.map((i) => `config.json: ${i}`);
@@ -12042,7 +12243,7 @@ async function cmdValidate(argv) {
   const take = await loadTake(target);
   const problems = [];
   const warnings = [];
-  if (!existsSync15(take.paths.recording)) {
+  if (!existsSync16(take.paths.recording)) {
     problems.push("missing recording (re-run record)");
   } else {
     const mismatch = containerMismatch(
@@ -12283,6 +12484,8 @@ async function run(argv) {
         return await cmdRecipe(rest);
       case "brand":
         return await cmdBrand(rest);
+      case "session":
+        return await cmdSession(rest);
       case "actions":
         return await cmdActions(rest);
       default:
@@ -12316,6 +12519,121 @@ async function run(argv) {
     return EXIT_ERROR;
   }
 }
+async function cmdSession(argv) {
+  const { positionals, flags } = parseArgs(argv, BOOLEAN_FLAGS5);
+  const [sub, arg] = positionals;
+  const r = createReporter(flags.json === true);
+  const usage = "vos session open <url> --name <app> | check <name> [--url <url>] | list | rm <name>";
+  switch (sub) {
+    case "open": {
+      if (!arg) throw new UsageError(usage);
+      const name = strFlag(flags, "name");
+      const bad = sessionNameVerdict(name);
+      if (bad) throw new UsageError(bad);
+      let url;
+      try {
+        url = new URL(arg);
+      } catch {
+        throw new UsageError(`vos session open wants a URL, got "${arg}"`);
+      }
+      if (!/^https?:$/.test(url.protocol))
+        throw new UsageError("vos session open wants an http(s) URL");
+      await openSession(name, url.href, { log: r.log });
+      const summary2 = await summarizeSession(name);
+      r.done(
+        {
+          name: summary2.name,
+          origins: summary2.origins,
+          newestExpires: summary2.newestExpires,
+          sessionOnly: summary2.sessionOnly
+        },
+        `${summaryLine(summary2)}
+  Record on it: vos record --actions actions.json --out take --session ${name} --strict`
+      );
+      return summary2.origins.length ? EXIT_OK : EXIT_ERROR;
+    }
+    case "check": {
+      if (!arg) throw new UsageError(usage);
+      const bad = sessionNameVerdict(arg);
+      if (bad) throw new UsageError(bad);
+      if (!existsSync16(sessionDir(arg)))
+        throw new UsageError(`no session "${arg}" (vos session list)`);
+      const summary2 = await summarizeSession(arg);
+      const url = strFlag(flags, "url");
+      if (!url) {
+        r.done(
+          {
+            name: arg,
+            origins: summary2.origins,
+            newestExpires: summary2.newestExpires,
+            sessionOnly: summary2.sessionOnly
+          },
+          summaryLine(summary2)
+        );
+        return summary2.origins.length ? EXIT_OK : EXIT_WALL;
+      }
+      const verdict = await withSession(arg, async (ctx) => {
+        const page = await ctx.newPage();
+        const response = await page.goto(url, { waitUntil: "networkidle", timeout: 3e4 }).catch(() => null);
+        const seen = await page.evaluate(WALL_PROBE).catch(() => null);
+        return wallVerdict({
+          askedUrl: url,
+          landedUrl: page.url(),
+          ...response ? { status: response.status() } : {},
+          passwordFields: seen?.passwordFields ?? 0,
+          newPasswordField: seen?.newPasswordField ?? false,
+          oneTimeCodeField: seen?.oneTimeCodeField ?? false
+        });
+      });
+      if (verdict) {
+        r.done(
+          {
+            name: arg,
+            ok: false,
+            wall: verdict,
+            origins: summary2.origins,
+            newestExpires: summary2.newestExpires
+          },
+          `session "${arg}" no longer opens ${url}: ${verdict.message.split(". ")[0]}. It expired, or the sign-in never landed. Sign in again: vos session open ${url} --name ${arg}`
+        );
+        return EXIT_WALL;
+      }
+      r.done(
+        {
+          name: arg,
+          ok: true,
+          origins: summary2.origins,
+          newestExpires: summary2.newestExpires
+        },
+        `session "${arg}" opens ${url} signed in. ${summaryLine(summary2)}`
+      );
+      return EXIT_OK;
+    }
+    case "list": {
+      const rows = listSessions();
+      r.done(
+        { sessions: rows },
+        rows.length ? rows.map(
+          (x) => `  ${x.name}  ${x.ageDays} day${x.ageDays === 1 ? "" : "s"} old`
+        ).join("\n") : "no sessions. Make one: vos session open <url> --name <app>"
+      );
+      return EXIT_OK;
+    }
+    case "rm": {
+      if (!arg) throw new UsageError(usage);
+      const bad = sessionNameVerdict(arg);
+      if (bad) throw new UsageError(bad);
+      const gone = removeSession(arg);
+      r.done(
+        { name: arg, removed: gone },
+        gone ? `removed session "${arg}"` : `no session "${arg}"`
+      );
+      return gone ? EXIT_OK : EXIT_ERROR;
+    }
+    default:
+      throw new UsageError(usage);
+  }
+}
 
 export {
   validateActions,
@@ -12348,4 +12666,4 @@ export {
   verbHelp,
   run
 };
-//# sourceMappingURL=chunk-WCSAECM4.js.map
+//# sourceMappingURL=chunk-4HW2XR5K.js.map