demobites 1.4.0 → 1.7.0

package/skill/scripts/batch.mjs

@@ -0,0 +1,328 @@
+#!/usr/bin/env node
+// FILM IN THE BACKGROUND, IN PARALLEL (1.7.0, founder ruling 2026-09-26):
+// after the ONE approval for the batch, the takes of an Update Radar batch
+// are filmed together in a small pool, each in its OWN browser profile
+// directory, and each is delivered as it finishes. A failed take never stops
+// the others. "We will be judged by the outcome: the fewest edits before
+// Export and Go live."
+//
+//   node batch.mjs plan <slug>                         the pool size for this machine and which briefs have a storyboard (films nothing)
+//   node batch.mjs run  <slug> [--concurrency N]       film every brief with a storyboard, N at a time (1..4), deliver each as it lands
+//                      [--only <briefId,...>] [--keep-profiles]
+//
+// Inputs, all under .recorder/radar/<slug>/ (written by `briefs.mjs list --slug`
+// and by the agent's refactor pass):
+//   bundle.json                    the batch (refreshed from the server first; the disk copy is the fallback)
+//   storyboards/<briefId>.json     one approved storyboard per brief (Phase 3 schema); a brief without one is skipped, and said
+// Outputs:
+//   takes/<briefId>/<step>.log     one log per step (claim, prep, record, cleanup, trim, calibrate, manifest, upload)
+//   takes/<briefId>/take.log       every step in order
+//   takes/<briefId>/result.json    what happened to the take
+//   takes/summary.json             the batch's outcome
+//   take-<briefId>-r<revision>/    the take itself, in the project directory as for every claimed brief
+//
+// Per take, in order, as child processes of the existing scripts (nothing is
+// reimplemented here): briefs claim → event recording → cleanup --prep (when
+// declared) → record → cleanup (when declared) → trim → calibrate → manifest →
+// upload --stage-only --no-open (the delivery door). On a failure: event
+// failed --note, keep the take directory, go on with the next brief.
+//
+// THE POOL RULE: 2 concurrent takes on a machine with 8 CPU cores or fewer,
+// or 16 GB of memory or less; 3 above that; --concurrency overrides; never
+// more than 4. Each take films on its own profile directory seeded from
+// .recorder/profile (the signed-in session rides along, the profile lock
+// does not), passed to the children as RECORDER_PROFILE.
+//
+// Never prints the api_key (the children never do either).
+import fs from "node:fs";
+import os from "node:os";
+import path from "node:path";
+import { spawn, spawnSync } from "node:child_process";
+import { fileURLToPath } from "node:url";
+
+const here = path.dirname(fileURLToPath(import.meta.url));
+const [, , cmd, slugArg, ...rest] = process.argv;
+const flag = (name) => rest.includes(name);
+const opt = (name) => { const i = rest.indexOf(name); return i >= 0 ? String(rest[i + 1] ?? "") : null; };
+
+function usage(code = 2) {
+  console.error(`Usage:
+  node batch.mjs plan <slug>
+  node batch.mjs run  <slug> [--concurrency N] [--only <briefId,...>] [--keep-profiles]`);
+  process.exit(code);
+}
+if (!cmd || !["plan", "run"].includes(cmd)) usage();
+const slug = String(slugArg ?? "").trim().toLowerCase();
+if (!/^[a-z0-9-]{1,32}$/.test(slug)) { console.error("The record code is the short code on the Update Radar page, like k3fx9q."); process.exit(2); }
+
+// ── where the scripts are ──────────────────────────────────────────────────
+// Installed, every script sits beside this file. In the package repository
+// record/trim/calibrate live in ../../scripts; both layouts resolve.
+function scriptPath(name) {
+  for (const dir of [here, path.resolve(here, "..", "..", "scripts")]) {
+    const p = path.join(dir, name);
+    if (fs.existsSync(p)) return p;
+  }
+  console.error(`${name} not found beside ${here}. Run \`npx demobite\` to refresh the skill.`);
+  process.exit(1);
+}
+const SCRIPTS = {
+  briefs: scriptPath("briefs.mjs"), cleanup: scriptPath("cleanup.mjs"), record: scriptPath("record.mjs"),
+  trim: scriptPath("trim.mjs"), calibrate: scriptPath("calibrate.mjs"), manifest: scriptPath("manifest.mjs"), upload: scriptPath("upload.mjs"),
+};
+
+// ── the pool rule ──────────────────────────────────────────────────────────
+const MAX_CONCURRENCY = 4;
+function poolSize({ cpus = os.cpus().length, memGiB = os.totalmem() / 2 ** 30, override = null } = {}) {
+  if (override !== null && override !== undefined && override !== "") {
+    const n = Number(override);
+    if (!Number.isInteger(n) || n < 1) { console.error(`--concurrency must be a whole number from 1 to ${MAX_CONCURRENCY}.`); process.exit(2); }
+    return { size: Math.min(n, MAX_CONCURRENCY), why: n > MAX_CONCURRENCY ? `--concurrency ${n}, capped at ${MAX_CONCURRENCY}` : `--concurrency ${n}` };
+  }
+  const small = cpus <= 8 || memGiB <= 16;
+  return { size: small ? 2 : 3, why: `${cpus} CPU cores, ${Math.round(memGiB)} GB memory` };
+}
+
+// ── the batch on disk and on the server ────────────────────────────────────
+const cfgPath = path.resolve(".recorder", "config.json");
+let cfg = {};
+try { cfg = JSON.parse(fs.readFileSync(cfgPath, "utf8")); } catch {}
+if (!cfg.api_key || !cfg.base) { console.error(`Not connected to DemoBites. Run: ${process.env.DEMOBITE_CLI ? "npx demobite login" : "node scripts/login.mjs"}`); process.exit(1); }
+const base = cfg.base.replace(/\/+$/, "");
+
+const radarDir = path.resolve(".recorder", "radar", slug);
+const bundlePath = path.join(radarDir, "bundle.json");
+const storyboardsDir = path.join(radarDir, "storyboards");
+const takesDir = path.join(radarDir, "takes");
+const sharedProfile = path.resolve(".recorder", "profile");
+
+const stamp = () => new Date().toTimeString().slice(0, 8);
+const say = (line) => console.log(`${stamp()}  ${line}`);
+
+function loadBundle() {
+  // The server's view first (revisions move after a refine); the disk copy when it cannot be reached.
+  fs.mkdirSync(takesDir, { recursive: true });
+  const r = spawnSync("node", [SCRIPTS.briefs, "list", "--slug", slug], { cwd: process.cwd(), env: process.env, encoding: "utf8" });
+  fs.writeFileSync(path.join(takesDir, "list.log"), `${r.stdout ?? ""}${r.stderr ?? ""}`);
+  if (r.status !== 0) {
+    const first = (r.stderr || r.stdout || "").trim().split("\n")[0];
+    if (!fs.existsSync(bundlePath)) { console.error(first || "Could not read the batch."); process.exit(1); }
+    console.error(`Could not refresh the batch from DemoBites (${first}); using the bundle on disk.`);
+  }
+  let bundle;
+  try { bundle = JSON.parse(fs.readFileSync(bundlePath, "utf8")); } catch (e) { console.error(`${bundlePath} unreadable: ${e.message}. Run: node scripts/briefs.mjs list --slug ${slug}`); process.exit(1); }
+  if (!bundle.batch?.id || !Array.isArray(bundle.briefs)) { console.error(`${bundlePath} has no batch. Run: node scripts/briefs.mjs list --slug ${slug}`); process.exit(1); }
+  return bundle;
+}
+
+const safeId = (id) => String(id).replace(/[^A-Za-z0-9._-]+/g, "-");
+const storyboardFor = (b) => path.join(storyboardsDir, `${safeId(b.briefId)}.json`);
+
+function planBatch(bundle) {
+  const order = [...bundle.briefs].sort((a, b) => (a.position ?? 0) - (b.position ?? 0));
+  const only = opt("--only") ? new Set(opt("--only").split(",").map((s) => s.trim()).filter(Boolean)) : null;
+  return order.map((b, i) => {
+    const sb = storyboardFor(b);
+    let storyboard = null; let problem = null;
+    if (only && !only.has(String(b.briefId))) problem = "not in --only";
+    else if (!fs.existsSync(sb)) problem = "no storyboard";
+    else {
+      try { storyboard = JSON.parse(fs.readFileSync(sb, "utf8")); } catch (e) { problem = `storyboard unreadable: ${e.message}`; }
+      if (storyboard && (!Array.isArray(storyboard.steps) || storyboard.steps.length === 0)) problem = "storyboard has no steps";
+    }
+    const live = b.attempt && ["planning", "awaiting_storyboard_approval", "recording", "uploading"].includes(b.attempt.state);
+    if (!problem && b.status && !["approved", "refined"].includes(b.status) && !live) problem = `brief is ${b.status}`;
+    return { n: i + 1, brief: b, storyboardPath: sb, storyboard, problem, liveAttempt: live ? b.attempt : null };
+  });
+}
+
+// ── one step = one child process, logged ───────────────────────────────────
+function runStep(take, step, script, args, extraEnv = {}) {
+  return new Promise((resolve) => {
+    const logPath = path.join(take.logDir, `${step}.log`);
+    const out = fs.createWriteStream(logPath);
+    const all = fs.createWriteStream(path.join(take.logDir, "take.log"), { flags: "a" });
+    all.write(`\n── ${step}  ${new Date().toISOString()}\n   node ${path.basename(script)} ${args.join(" ")}\n`);
+    let stdout = ""; let stderr = "";
+    const child = spawn("node", [script, ...args], { cwd: process.cwd(), env: { ...process.env, ...extraEnv }, stdio: ["ignore", "pipe", "pipe"] });
+    take.child = child;
+    child.stdout.on("data", (d) => { stdout += d; out.write(d); all.write(d); });
+    child.stderr.on("data", (d) => { stderr += d; out.write(d); all.write(d); });
+    child.on("close", (code, signal) => {
+      take.child = null;
+      out.end(); all.end();
+      resolve({ code: signal ? 1 : code, stdout, stderr, logPath, signal });
+    });
+    child.on("error", (e) => { take.child = null; stderr += e.message; out.end(); all.end(); resolve({ code: 1, stdout, stderr, logPath }); });
+  });
+}
+const firstLine = (r) => (r.stderr.trim() || r.stdout.trim()).split("\n").filter(Boolean).pop() ?? `exit ${r.code}`;
+const rel = (p) => path.relative(process.cwd(), p) || p;
+
+// ── one profile per take, seeded from the shared one ───────────────────────
+// Chrome refuses a second instance on the same profile (SingletonLock); a
+// COPY carries the signed-in session and nothing that locks. Caches stay
+// behind: they are large and Chrome rebuilds them.
+const SKIP_IN_PROFILE = /^(Singleton|lockfile$|.*Cache$|Crashpad$|BrowserMetrics|Safe Browsing|component_crx_cache|extensions_crx_cache)/i;
+function seedProfile(take) {
+  const dir = path.join(take.logDir, "profile");
+  fs.rmSync(dir, { recursive: true, force: true });
+  fs.mkdirSync(dir, { recursive: true });
+  if (fs.existsSync(sharedProfile)) {
+    fs.cpSync(sharedProfile, dir, { recursive: true, force: true, filter: (src) => !SKIP_IN_PROFILE.test(path.basename(src)) });
+  }
+  return dir;
+}
+
+// ── one take, start to delivery ────────────────────────────────────────────
+const takesInFlight = new Set();
+async function runTake(item, bundle, results) {
+  const b = item.brief;
+  const label = `brief ${item.n}/${bundle.briefs.length} "${b.title}"`;
+  const take = { briefId: b.briefId, title: b.title, n: item.n, logDir: path.join(takesDir, safeId(b.briefId)), child: null };
+  takesInFlight.add(take);
+  try { await filmTake(item, bundle, results, take, label); } finally { takesInFlight.delete(take); }
+}
+
+async function filmTake(item, bundle, results, take, label) {
+  const b = item.brief;
+  fs.mkdirSync(take.logDir, { recursive: true });
+  fs.rmSync(path.join(take.logDir, "take.log"), { force: true });
+  const result = { briefId: b.briefId, title: b.title, n: item.n, startedAt: new Date().toISOString(), takeDir: null, attemptRef: null, outcome: null, step: null, error: null, biteId: null, logDir: rel(take.logDir) };
+  results.push(result);
+  const finish = (outcome, extra = {}) => { Object.assign(result, { outcome, endedAt: new Date().toISOString(), ...extra }); fs.writeFileSync(path.join(take.logDir, "result.json"), JSON.stringify(result, null, 2) + "\n"); };
+  const fail = async (step, r) => {
+    const why = firstLine(r);
+    result.step = step; result.error = why;
+    say(`${label}: failed at ${step} (${why}). Log: ${rel(r.logPath)}`);
+    if (result.attemptRef && result.takeDir) await runStep(take, "event-failed", SCRIPTS.briefs, ["event", result.takeDir, "failed", "--note", `${step}: ${why}`.slice(0, 600)]);
+    finish("failed");
+  };
+
+  // 1. claim → take-<briefId>-r<revision>/brief.json
+  const claim = await runStep(take, "claim", SCRIPTS.briefs, ["claim", String(bundle.batch.id), String(b.briefId)]);
+  if (claim.code !== 0) { result.step = "claim"; result.error = firstLine(claim); say(`${label}: claim refused (${result.error}). Log: ${rel(claim.logPath)}`); finish("claim_refused"); return; }
+  const m = /→ (\S+)\/brief\.json \(attempt ([^,)]+)/.exec(claim.stdout);
+  result.takeDir = m?.[1] ?? `take-${safeId(b.briefId)}-r${b.revision}`;
+  result.attemptRef = m?.[2] ?? null;
+  if (!fs.existsSync(path.join(result.takeDir, "brief.json"))) { result.step = "claim"; result.error = `no brief.json in ${result.takeDir}`; say(`${label}: claim did not write ${result.takeDir}/brief.json`); finish("failed"); return; }
+  say(`${label}: claimed → ${result.takeDir} (attempt ${result.attemptRef ?? "?"})`);
+
+  // 2. the approved storyboard travels with the take (cleanup --prep reads it before record does)
+  fs.copyFileSync(item.storyboardPath, path.join(result.takeDir, "storyboard.json"));
+  const sb = item.storyboard;
+  const hasPrep = (sb.prep?.length ?? 0) > 0 || (sb.checks?.before?.length ?? 0) > 0;
+  const hasCleanup = (sb.cleanup?.length ?? 0) > 0 || (sb.checks?.after?.length ?? 0) > 0;
+
+  // 3. the attempt moves to recording; the take gets its own profile
+  const ev = await runStep(take, "event-recording", SCRIPTS.briefs, ["event", result.takeDir, "recording"]);
+  if (ev.code !== 0) { await fail("event recording", ev); return; }
+  let profile;
+  try { profile = seedProfile(take); } catch (e) { await fail("profile", { stdout: "", stderr: e.message, logPath: path.join(take.logDir, "take.log"), code: 1 }); return; }
+  const env = { RECORDER_PROFILE: profile };
+  say(`${label}: filming on its own profile (${rel(profile)})`);
+
+  try {
+    if (hasPrep) { const r = await runStep(take, "prep", SCRIPTS.cleanup, [result.takeDir, "--prep"], env); if (r.code !== 0) { await fail("prep", r); return; } say(`${label}: prep done (checks before passed)`); }
+    const rec = await runStep(take, "record", SCRIPTS.record, [result.takeDir, item.storyboardPath], env);
+    if (rec.code !== 0) { await fail("record", rec); return; }
+    say(`${label}: filmed`);
+    if (hasCleanup) { const r = await runStep(take, "cleanup", SCRIPTS.cleanup, [result.takeDir], env); if (r.code !== 0) { await fail("cleanup", r); return; } say(`${label}: workspace returned to its initial state (checks after passed)`); }
+  } finally {
+    if (!flag("--keep-profiles")) fs.rmSync(profile, { recursive: true, force: true });
+  }
+
+  // 4. finish the file, then the ONE delivery door
+  for (const [step, script] of [["trim", SCRIPTS.trim], ["calibrate", SCRIPTS.calibrate], ["manifest", SCRIPTS.manifest]]) {
+    const r = await runStep(take, step, script, [result.takeDir]);
+    if (r.code !== 0) { await fail(step, r); return; }
+  }
+  const up = await runStep(take, "upload", SCRIPTS.upload, [result.takeDir, "--stage-only", "--no-open"]);
+  let staged = null;
+  try { staged = JSON.parse(fs.readFileSync(path.join(result.takeDir, "staged.json"), "utf8")); } catch {}
+  if (staged?.delivered && staged.biteId) {
+    result.biteId = staged.biteId;
+    say(`${label}: delivered → bite ${staged.biteId}, becoming a demo by itself`);
+    finish("delivered", { stagingId: staged.stagingId, dashboardUrl: staged.dashboardUrl });
+    return;
+  }
+  if (staged?.waiting) {
+    const kept = up.stdout.split("\n").find((l) => l.startsWith("Kept.")) ?? "Kept. The take is waiting for recording minutes.";
+    say(`${label}: ${kept}`);
+    finish("waiting", { stagingId: staged.stagingId, resetsAt: staged.resetsAt, dashboardUrl: staged.dashboardUrl });
+    return;
+  }
+  if (up.code !== 0 || !staged) { await fail("upload", up); return; }
+  result.step = "upload"; result.error = staged.deliveryError ?? "staged, not delivered";
+  say(`${label}: staged but not delivered (${result.error}). Try again later: node scripts/status.mjs ${result.takeDir}`);
+  finish("staged", { stagingId: staged.stagingId });
+}
+
+// ── the pool ───────────────────────────────────────────────────────────────
+async function runPool(items, size, worker) {
+  const queue = [...items];
+  const active = new Set();
+  const next = async () => {
+    const item = queue.shift();
+    if (!item) return;
+    const p = worker(item).catch((e) => { say(`brief ${item.n} "${item.brief.title}": ${e.message}`); }).finally(() => active.delete(p));
+    active.add(p);
+    await p;
+    await next();
+  };
+  await Promise.all(Array.from({ length: Math.min(size, queue.length) }, () => next()));
+}
+
+// ── main ───────────────────────────────────────────────────────────────────
+const bundle = loadBundle();
+const plan = planBatch(bundle);
+const pool = poolSize({ override: opt("--concurrency") });
+const ready = plan.filter((p) => !p.problem);
+const radarName = bundle.radar?.name ?? slug;
+
+console.log(`Update Radar: ${radarName}  batch ${bundle.batch.id}`);
+console.log(`Pool: ${pool.size} take${pool.size === 1 ? "" : "s"} at a time (${pool.why}), each on its own profile directory; the rest queue.`);
+for (const p of plan) {
+  const tag = p.problem ? `skip, ${p.problem}` : `ready${p.liveAttempt ? `, live attempt ${p.liveAttempt.ref} will be superseded by the claim` : ""}`;
+  console.log(`  ${String(p.n).padStart(2, " ")}. ${p.brief.title}  brief ${p.brief.briefId} r${p.brief.revision}  [${tag}]`);
+}
+if (cmd === "plan") {
+  console.log(`\nStoryboards live in ${rel(storyboardsDir)}/<briefId>.json. Films nothing; run: node scripts/batch.mjs run ${slug}`);
+  process.exit(ready.length ? 0 : 1);
+}
+if (!ready.length) { console.error(`\nNothing to film: no brief has a storyboard in ${rel(storyboardsDir)}/.`); process.exit(1); }
+console.log(`\nFilming ${ready.length} of ${plan.length} in the background. Logs: ${rel(takesDir)}/<briefId>/\n`);
+
+const results = [];
+let interrupted = false;
+process.on("SIGINT", () => {
+  if (interrupted) process.exit(130);
+  interrupted = true;
+  say("interrupted: stopping the takes in flight; claimed briefs are marked failed so they can be filmed again");
+  for (const t of takesInFlight) t.child?.kill("SIGTERM");
+});
+
+await runPool(ready, pool.size, async (item) => {
+  if (interrupted) return;
+  await runTake(item, bundle, results);
+});
+
+// ── the summary ────────────────────────────────────────────────────────────
+const count = (o) => results.filter((r) => r.outcome === o).length;
+const skipped = plan.filter((p) => p.problem);
+console.log(`\nBatch ${bundle.batch.id}: ${count("delivered")} delivered, ${count("waiting")} kept waiting for recording minutes, ${count("failed") + count("claim_refused") + count("staged")} not delivered, ${skipped.length} skipped.`);
+for (const r of results.sort((a, b) => a.n - b.n)) {
+  const line = r.outcome === "delivered" ? `delivered, bite ${r.biteId}`
+    : r.outcome === "waiting" ? "kept, waiting for recording minutes (it waits on the Demos grid)"
+    : r.outcome === "staged" ? `staged, not delivered (${r.error}); node scripts/status.mjs ${r.takeDir}`
+    : r.outcome === "claim_refused" ? `claim refused: ${r.error}`
+    : `failed at ${r.step}: ${r.error} (${r.logDir}/${r.step === "event recording" ? "event-recording" : r.step}.log)`;
+  console.log(`  ${String(r.n).padStart(2, " ")}. ${r.title}: ${line}`);
+}
+for (const p of skipped) console.log(`  ${String(p.n).padStart(2, " ")}. ${p.brief.title}: skipped, ${p.problem}`);
+const summary = { slug, batchId: bundle.batch.id, radar: bundle.radar ?? null, pool, startedAt: results[0]?.startedAt ?? null, endedAt: new Date().toISOString(), results, skipped: skipped.map((p) => ({ briefId: p.brief.briefId, title: p.brief.title, why: p.problem })) };
+fs.writeFileSync(path.join(takesDir, "summary.json"), JSON.stringify(summary, null, 2) + "\n");
+const grid = `${base}/demos`;
+console.log(`\nDemos grid: ${grid}`);
+if (bundle.radar?.workflowUrl) console.log(`Workflow page: ${bundle.radar.workflowUrl}`);
+process.exit(results.every((r) => r.outcome === "delivered" || r.outcome === "waiting") && !interrupted ? 0 : 1);

package/skill/scripts/briefs.mjs

@@ -2,6 +2,13 @@
 // of approved briefs into the agent; this script is the agent's hands:
 //
 //   node briefs.mjs list <batchId> [--paste <file>]     the authenticated truth for the batch (warns when a pasted bundle drifted)
+//   node briefs.mjs list --slug <slug>                  UPDATE RADAR (1.6.0): the batch behind a workflow's record code; writes
+//                                                       .recorder/radar/<slug>/bundle.json (+ briefs/<briefId>.json, one draft
+//                                                       per brief) and prints the briefs in order with their open questions
+//   node briefs.mjs refine <slug> <briefId> [--file <refined.json>] [--note "..."]
+//                                                       REFACTOR PASS (1.7.0): post the brief refined on this machine (default file
+//                                                       .recorder/radar/<slug>/refined/<briefId>.json) → a new revision; the Radar
+//                                                       page shows it as "Refined on your machine"; rewrites the bundle
 //   node briefs.mjs claim <batchId> <briefId> [--force] claim one brief → mints an attempt, creates take-<briefId>-r<revision>/brief.json
 //   node briefs.mjs event <takeDir|attemptRef> <event> [--note "..."]
 //                                                       planning | awaiting_storyboard_approval | recording | uploading | failed | cancelled
@@ -9,15 +16,23 @@
 //
 // Server contract (dbrec_ key, scope record):
 //   GET /api/recorder/briefs?batch=<batchId>
+//   GET /api/recorder/briefs?slug=<slug>      same payload + radar: { slug, name, workflowUrl }
+//                                             404 { error: "unknown_slug" } · 409 { error: "not_approved" }
 //   PUT /api/recorder/briefs/claim { briefId, revision, contentHash, idempotencyKey, force? }
 //   PUT /api/recorder/briefs/attempts/<attemptRef> { event, note? }
+//   PUT /api/recorder/briefs/<briefId>/refine { revision, contentHash, content, note? }
+//                                             -> { revision, contentHash }   (409 hash_mismatch · 410 superseded)
 // The stage call (upload.mjs) sends the attempt from <takeDir>/brief.json, and
 // after the uploads calls the delivery route from the claim's `api.uploaded`
 // (1.3.0): a take filmed from a brief becomes a bite by itself.
 //
-// Laws: one storyboard approval per brief, never one word for the batch.
-// Sequential takes, one Chrome on the profile. A failed brief never stops the
-// others. Never print the api_key.
+// Laws (founder ruling 2026-09-26, "the fewest edits before Export and Go
+// live"): every brief is refined against the repository and the running app
+// BEFORE anything films, and posted back through `refine`; every open
+// question is asked ONCE for the whole batch; the batch gets ONE approval;
+// then batch.mjs films the takes in the background, in parallel, each on its
+// own profile directory. A failed brief never stops the others. Never print
+// the api_key.
 import fs from "node:fs";
 import path from "node:path";
 import crypto from "node:crypto";
@@ -25,22 +40,26 @@ import crypto from "node:crypto";
 const [, , cmd, ...rest] = process.argv;
 const flag = (name) => rest.includes(name);
 const opt = (name) => { const i = rest.indexOf(name); return i >= 0 ? String(rest[i + 1] ?? "") : null; };
-const positional = rest.filter((a, i) => !a.startsWith("--") && !(i > 0 && ["--paste", "--note"].includes(rest[i - 1])));
+const positional = rest.filter((a, i) => !a.startsWith("--") && !(i > 0 && ["--paste", "--note", "--slug", "--file"].includes(rest[i - 1])));
+// `npx demobite record <slug>` runs this script (DEMOBITE_CLI=1); its login hint is the launcher's command.
+const loginHint = process.env.DEMOBITE_CLI ? "npx demobite login" : "node scripts/login.mjs";
 
 function usage(code = 2) {
   console.error(`Usage:
   node briefs.mjs list <batchId> [--paste <file>]
+  node briefs.mjs list --slug <slug>
+  node briefs.mjs refine <slug> <briefId> [--file <refined.json>] [--note "..."]
   node briefs.mjs claim <batchId> <briefId> [--force]
   node briefs.mjs event <takeDir|attemptRef> <event> [--note "..."]
   node briefs.mjs release <takeDir|attemptRef> [--note "..."]`);
   process.exit(code);
 }
-if (!cmd || !["list", "claim", "event", "release"].includes(cmd)) usage();
+if (!cmd || !["list", "claim", "event", "release", "refine"].includes(cmd)) usage();
 
 const cfgPath = path.resolve(".recorder", "config.json");
 let cfg = {};
 try { cfg = JSON.parse(fs.readFileSync(cfgPath, "utf8")); } catch {}
-if (!cfg.api_key || !cfg.base) { console.error("No recorder key. Run: node scripts/login.mjs"); process.exit(1); }
+if (!cfg.api_key || !cfg.base) { console.error(`Not connected to DemoBites. Run: ${loginHint}`); process.exit(1); }
 const base = cfg.base.replace(/\/+$/, "");
 const headers = { Authorization: `Bearer ${cfg.api_key}`, "Content-Type": "application/json" };
 
@@ -50,7 +69,7 @@ async function api(method, p, body) {
     res = await fetch(`${base}${p}`, { method, headers, body: body ? JSON.stringify(body) : undefined });
   } catch (e) { console.error(`DemoBites unreachable (${e.message}).`); process.exit(1); }
   const json = await res.json().catch(() => null);
-  if (res.status === 401) { console.error("The recorder key was refused. Run: node scripts/login.mjs"); process.exit(1); }
+  if (res.status === 401) { console.error(`The recorder key was refused. Run: ${loginHint}`); process.exit(1); }
   return { status: res.status, ok: res.ok, json };
 }
 
@@ -90,14 +109,116 @@ function printBatch(data) {
 async function fetchBatch(batchId) {
   const r = await api("GET", `/api/recorder/briefs?batch=${encodeURIComponent(batchId)}`);
   if (r.status === 403 && r.json?.error === "workspace_mismatch") {
-    console.error("This key's workspace is not the batch's workspace. Log in to the right workspace (node scripts/login.mjs) and try again.");
+    console.error(`This key's workspace is not the batch's workspace. Log in to the right workspace (${loginHint}) and try again.`);
     process.exit(1);
   }
   if (!r.ok || !r.json?.briefs) { console.error(`Could not read batch ${batchId}: ${r.status} ${r.json ? JSON.stringify(r.json).slice(0, 200) : ""}`); process.exit(1); }
   return r.json;
 }
 
-if (cmd === "list") {
+/** UPDATE RADAR (1.6.0): the batch behind a workflow's record code. */
+async function fetchBySlug(slug) {
+  const r = await api("GET", `/api/recorder/briefs?slug=${encodeURIComponent(slug)}`);
+  if (r.status === 404) { console.error("No batch with that code. Check the command on the Update Radar page."); process.exit(1); }
+  if (r.status === 409) { console.error("The briefs are not approved yet. Approve them on the Update Radar page, then run this again."); process.exit(1); }
+  if (r.status === 403 && r.json?.error === "workspace_mismatch") {
+    console.error(`This key's workspace is not the workflow's workspace. Log in to the right workspace (${loginHint}) and try again.`);
+    process.exit(1);
+  }
+  if (r.status === 403 && r.json?.error === "upgrade_required") { console.error("Update Radar is part of Product Awareness. Upgrade the workspace on the Update Radar page, then run this again."); process.exit(1); }
+  if (!r.ok || !r.json?.briefs) { console.error(`Could not read the batch for code ${slug}: ${r.status} ${r.json ? JSON.stringify(r.json).slice(0, 200) : ""}`); process.exit(1); }
+  return r.json;
+}
+
+/** The record-by-code view: the workflow, the batch id, then the briefs in order (position, title, seconds). */
+function printRadar(data, slug) {
+  const { batch, briefs, radar } = data;
+  const order = [...briefs].sort((a, b) => (a.position ?? 0) - (b.position ?? 0));
+  console.log(`Update Radar: ${radar?.name ?? slug}`);
+  // A radar batch has no target address: the agent films where the code
+  // already runs (the Record stage says so); print the target only when set.
+  console.log(`Batch ${batch?.id ?? "?"}${batch?.target?.url ? `  target ${batch.target.url}${batch.target.environment ? ` (${batch.target.environment})` : ""}` : ""}`);
+  console.log(`${briefs.length} brief${briefs.length === 1 ? "" : "s"}, each at most ${batch?.rules?.maxSeconds ?? 90} seconds, in this order:\n`);
+  const questions = [];
+  order.forEach((b, i) => {
+    const pos = String(i + 1).padStart(2, " ");
+    const secs = b.estimatedDurationSec ? `about ${b.estimatedDurationSec}s` : "length open";
+    const state = b.status && b.status !== "approved" ? `  [${b.status}${b.attempt ? `, attempt ${b.attempt.ref}` : ""}]` : "";
+    const refined = b.refinedLocally || b.refined ? "  (refined on this machine)" : "";
+    console.log(`  ${pos}. ${b.title}  (${secs})  brief ${b.briefId} r${b.revision}${state}${refined}`);
+    for (const q of b.questions ?? []) questions.push({ n: i + 1, title: b.title, q: typeof q === "string" ? q : q?.text ?? JSON.stringify(q) });
+  });
+  // QUESTIONS ONCE (2026-09-26): the drafts' open questions, gathered here so
+  // the agent asks them in one message for the whole batch, never mid-filming.
+  if (questions.length) {
+    console.log(`\nOpen questions in the drafts (ask them once, for the whole batch, before anything films):`);
+    for (const { n, title, q } of questions) console.log(`  brief ${n} (${title}): ${q}`);
+  }
+  if (radar?.workflowUrl) console.log(`\nWorkflow page: ${radar.workflowUrl}`);
+}
+
+/** The radar bundle on disk: bundle.json plus one draft file per brief (what
+ * the refactor pass starts from; the refined copy goes to refined/<briefId>.json). */
+function writeRadarBundle(slug, data) {
+  const dir = path.resolve(".recorder", "radar", slug);
+  fs.mkdirSync(path.join(dir, "briefs"), { recursive: true });
+  const bundlePath = path.join(dir, "bundle.json");
+  fs.writeFileSync(bundlePath, JSON.stringify({ slug, fetchedAt: new Date().toISOString(), ...data }, null, 2) + "\n");
+  for (const b of data.briefs) {
+    const safe = String(b.briefId).replace(/[^A-Za-z0-9._-]+/g, "-");
+    fs.writeFileSync(path.join(dir, "briefs", `${safe}.json`), JSON.stringify(b, null, 2) + "\n");
+  }
+  return bundlePath;
+}
+
+/** The brief's content for the refine door: ONLY the seven content fields
+ * the server's strict schema accepts, read from the draft file's top level or
+ * its `content` object; every other key a draft carries (identity, state,
+ * questions, author, attempts) is dropped, so a draft round-trips as is.
+ * The limits are the server's (a refine that breaks one answers 400
+ * invalid_refine): title ≤ 80, audience ≤ 60, outcome ≤ 200, flowIntent 2..8
+ * lines ≤ 120 each, prerequisites/exclusions ≤ 6 lines ≤ 160 each,
+ * estimatedDurationSec 15..90. They are checked here first, with the field
+ * named, so the agent trims before posting instead of reading a 400. */
+const CONTENT_LIMITS = { title: 80, audience: 60, outcome: 200 };
+const LIST_LIMITS = { flowIntent: { min: 2, max: 8, line: 120 }, prerequisites: { min: 0, max: 6, line: 160 }, exclusions: { min: 0, max: 6, line: 160 } };
+function refineContent(obj) {
+  const src = obj && typeof obj === "object" && obj.content && typeof obj.content === "object" ? obj.content : obj ?? {};
+  const pick = (camel, snake) => src[camel] !== undefined ? src[camel] : src[snake];
+  const out = {};
+  for (const k of ["title", "audience", "outcome"]) if (src[k] !== undefined) out[k] = src[k];
+  const fi = pick("flowIntent", "flow_intent"); if (fi !== undefined) out.flowIntent = fi;
+  for (const k of ["prerequisites", "exclusions"]) if (src[k] !== undefined) out[k] = src[k];
+  const d = pick("estimatedDurationSec", "estimated_duration_sec"); if (d !== undefined) out.estimatedDurationSec = d;
+  return out;
+}
+/** The server's limits, checked before the PUT; returns the problems as "field: why" lines. */
+function refineProblems(c) {
+  const out = [];
+  for (const [k, max] of Object.entries(CONTENT_LIMITS)) {
+    if (typeof c[k] !== "string" || !c[k].trim()) out.push(`${k}: required, a non-empty line`);
+    else if (c[k].trim().length > max) out.push(`${k}: ${c[k].trim().length} characters, the limit is ${max}`);
+  }
+  for (const [k, lim] of Object.entries(LIST_LIMITS)) {
+    const v = c[k] ?? [];
+    if (!Array.isArray(v)) { out.push(`${k}: must be a list of lines`); continue; }
+    if (v.length < lim.min || v.length > lim.max) out.push(`${k}: ${v.length} lines, allowed ${lim.min}..${lim.max}`);
+    v.forEach((line, i) => { if (typeof line !== "string" || !line.trim()) out.push(`${k}[${i}]: an empty line`); else if (line.trim().length > lim.line) out.push(`${k}[${i}]: ${line.trim().length} characters, the limit is ${lim.line}`); });
+  }
+  const d = c.estimatedDurationSec;
+  if (!Number.isInteger(d) || d < 15 || d > 90) out.push(`estimatedDurationSec: ${JSON.stringify(d)}, must be a whole number of seconds 15..90`);
+  return out;
+}
+
+if (cmd === "list" && opt("--slug") !== null) {
+  const slug = String(opt("--slug")).trim().toLowerCase();
+  if (!/^[a-z0-9-]{1,32}$/.test(slug)) { console.error("The record code is the short code on the Update Radar page, like k3fx9q."); process.exit(2); }
+  const data = await fetchBySlug(slug);
+  const bundlePath = writeRadarBundle(slug, data);
+  printRadar(data, slug);
+  const rel = path.relative(process.cwd(), bundlePath) || bundlePath;
+  console.log(`Bundle written: ${rel}  (one draft per brief in ${path.dirname(rel)}/briefs/, refined copies go to ${path.dirname(rel)}/refined/)`);
+} else if (cmd === "list") {
   const batchId = positional[0];
   if (!batchId) usage();
   const data = await fetchBatch(batchId);
@@ -120,6 +241,39 @@ if (cmd === "list") {
   }
 }
 
+// REFACTOR PASS (1.7.0): post a brief refined on this machine. The server
+// mints a new revision + contentHash for it and the Radar page shows the
+// refined text ("Refined on your machine"); the claim then takes the new
+// revision, so the bundle is rewritten from the server right after.
+if (cmd === "refine") {
+  const [slugArg, briefId] = positional;
+  const slug = String(slugArg ?? "").trim().toLowerCase();
+  if (!/^[a-z0-9-]{1,32}$/.test(slug) || !briefId) usage();
+  const safe = String(briefId).replace(/[^A-Za-z0-9._-]+/g, "-");
+  const file = opt("--file") ?? path.resolve(".recorder", "radar", slug, "refined", `${safe}.json`);
+  let refined;
+  try { refined = JSON.parse(fs.readFileSync(file, "utf8")); } catch (e) { console.error(`Refined brief not readable at ${file}: ${e.message}\nWrite the refined brief there (copy .recorder/radar/${slug}/briefs/${safe}.json and edit it), or pass --file.`); process.exit(2); }
+  const content = refineContent(refined);
+  const problems = refineProblems(content);
+  if (problems.length) { console.error(`${file}: the refined brief breaks the server's limits — fix these and post again:\n  ${problems.join("\n  ")}`); process.exit(2); }
+  const data = await fetchBySlug(slug);
+  const brief = data.briefs.find((b) => String(b.briefId) === String(briefId));
+  if (!brief) { console.error(`Brief ${briefId} is not in the batch behind code ${slug}.`); process.exit(1); }
+  const note = opt("--note");
+  const r = await api("PUT", `/api/recorder/briefs/${encodeURIComponent(brief.briefId)}/refine`, {
+    revision: brief.revision, contentHash: brief.contentHash, content, ...(note ? { note: note.slice(0, 600) } : {}),
+  });
+  if (r.status === 404 && !r.json?.error) { console.error("This DemoBites has no refine route yet (older server). Film from the refined file on this machine; the Radar page keeps the cloud draft."); process.exit(1); }
+  if (r.status === 409 && (r.json?.error === "hash_mismatch" || r.json?.error === "active_attempt")) { console.error(`Brief ${briefId}: ${r.json.error === "active_attempt" ? "a live attempt holds it; a refine lands before the claim, never after" : "the server's revision moved; run list --slug again and refine from the current draft"}.`); process.exit(1); }
+  if (r.status === 410 && r.json?.error === "take_delivered") { console.error(`Brief ${briefId} is locked: a take was delivered for it, so its text on the Radar page is frozen. Film the re-take from your refined file; the Radar page keeps the delivered wording.`); process.exit(1); }
+  if (r.status === 410) { console.error(`Brief ${briefId} r${brief.revision} was superseded by a newer revision. Run list --slug again.`); process.exit(1); }
+  if (!r.ok || r.json?.revision === undefined) { console.error(`Refine failed: ${r.status} ${r.json ? JSON.stringify(r.json).slice(0, 200) : ""}`); process.exit(1); }
+  console.log(`Refined ${brief.briefId}: r${brief.revision} → r${r.json.revision} (${r.json.contentHash ?? "hash from the server"}). The Radar page shows it as refined on this machine.`);
+  const fresh = await fetchBySlug(slug);
+  writeRadarBundle(slug, fresh);
+  console.log(`Bundle rewritten: .recorder/radar/${slug}/bundle.json`);
+}
+
 if (cmd === "claim") {
   const [batchId, briefId] = positional;
   if (!batchId || !briefId) usage();

package/skill/scripts/cleanup.mjs

@@ -32,7 +32,8 @@ if (steps.length === 0 && checks.length === 0) {
   process.exit(0);
 }
 
-const profileDir = path.resolve(".recorder", "profile");
+// RECORDER_PROFILE (1.7.0): a batch's parallel takes each prep and clean on their own seeded profile.
+const profileDir = path.resolve(process.env.RECORDER_PROFILE || path.join(".recorder", "profile"));
 const ctx = await chromium.launchPersistentContext(profileDir, { channel: "chrome", headless: true, viewport: { width: 1920, height: 1080 } }).catch(async () =>
   chromium.launchPersistentContext(profileDir, { headless: true, viewport: { width: 1920, height: 1080 } }),
 );

package/skill/scripts/manifest.mjs

@@ -194,6 +194,9 @@ const camera = (man.shots ?? [])
     label: s.label ?? undefined,
     ...(s.n != null ? { n: s.n } : {}),
     ...(s.revealed ? { revealed: true } : {}),
+    // WIDE (founder 2026-09-27): the camera at 1.0 for the span — the server
+    // ends the previous zoom at its start and writes no zoom row for it.
+    ...(s.wide ? { wide: true } : {}),
     ...(s.glide ? { glide: { t_start: norm(s.glide.t_start), t_end: norm(s.glide.t_end) } } : {}),
   }))
   .filter((s) => s.t_end > s.t_start && s.t_start < duration && s.w > 0 && s.h > 0)
@@ -238,8 +241,15 @@ if (fs.existsSync(cleanPath)) {
     const changedPx = yavg ? (parseFloat(yavg[1]) / 255) * FW * FH * SS * SS : 0;
     return { x: x / SS, y: y / SS, w: w / SS, h: h / SS, changedPx: changedPx / (SS * SS) };
   };
+  // FRAMING (founder 2026-09-27): a step the director framed `close` keeps its
+  // subject box — the page redrawing after an option pick is the landing, and
+  // the wide beat that follows frames it. The storyboard copy in the take dir
+  // is the recipe, so the frame is read from it by step number.
+  let framedClose = new Set();
+  try { const sb = JSON.parse(fs.readFileSync(path.join(dir, "storyboard.json"), "utf8")); (sb.steps ?? []).forEach((s, i) => { if (s?.frame === "close") framedClose.add(i + 1); }); } catch {}
   for (const st of steps) {
     if (!st.click) continue;
+    if (framedClose.has(st.n)) continue;
     const hasRevealedShot = camera.some((c) => c.n === st.n && c.revealed);
     if (hasRevealedShot) continue;
     const control = camera.find((c) => c.n === st.n && !c.revealed);
@@ -269,7 +279,9 @@ if (fs.existsSync(cleanPath)) {
       const wideStart = round2(st.click.t);
       const wideEnd = round2(Math.min(duration, st.t_end));
       if (wideEnd - wideStart >= 0.6) {
-        camera.push({ t_start: wideStart, t_end: wideEnd, x: 0, y: 0, w: FW, h: FH, n: st.n, label: `${st.label || "click"}, new page` });
+        // `wide: true` so the server frames it at 1.0 (an untagged full frame
+        // used to land on the 1.25 zoom floor — a phantom zoom on the new page).
+        camera.push({ t_start: wideStart, t_end: wideEnd, x: 0, y: 0, w: FW, h: FH, n: st.n, wide: true, label: `${st.label || "click"}, new page` });
         camera.sort((a, b) => a.t_start - b.t_start);
       }
       console.log(`consequence: step ${st.n} navigation — reset to wide at ${wideStart}s`);