@foldspace_npm/harness 0.1.33 → 0.1.34

package/src/observe-core.mjs

@@ -20,7 +20,7 @@ export function hostMatchesAny(hostname, hosts = []) {
 // on, never to decide where anything is sent.
 const SECOND_LEVEL_SUFFIXES = new Set(["co", "com", "org", "net", "gov", "ac", "edu"]);
 
-function siteOf(hostname) {
+export function siteOf(hostname) {
   const host = String(hostname || "").toLowerCase();
   if (!host.includes(".") || /^[\d.]+$/.test(host) || host.includes(":")) return host;
   const labels = host.split(".");

package/src/runtime/VERSION

@@ -1 +1 @@
-0.1.30
+0.1.34

package/src/runtime/config.ts

@@ -29,8 +29,21 @@ export interface RuntimeConfig {
   /** Foldspace agent apiName, e.g. `acme-agent`. */
   agentApiName: string;
   /**
-   * Prefix for `apiFetch` / `apiFetchBinary`. Include an explicit port if the
-   * app uses one — omitting `:443` can fail CORS.
+   * Prefix for `apiFetch` / `apiFetchBinary`, in one of three forms:
+   *
+   * - a full address, `https://api.example.com`, when every customer's app
+   *   calls the same backend. Include an explicit port if the app uses one —
+   *   omitting `:443` can fail CORS.
+   * - a path, `/api`, when the backend is on the page's own host. Each user's
+   *   page calls its own host.
+   * - an address with `{subdomain}` in it, `https://{subdomain}.api.example.com`,
+   *   when each customer has their own subdomain (`acme.example.com`) and the
+   *   backend carries it too. `{subdomain}` becomes the first part of the page's
+   *   address at run time, so each customer's agent calls their own backend.
+   *
+   * A product with a subdomain per customer never gets a fixed address here:
+   * that is the one customer the builder was signed in to, for every user.
+   * Read it through `apiBaseUrl()`, never `getConfig().apiBase` directly.
    */
   apiBase?: string;
   /**

package/src/runtime/http.ts

@@ -156,6 +156,34 @@ export type FailureReason =
 /** Discriminated result of a customer-API call. Branch on `ok`. */
 export type ApiResult<T> = ApiSuccess<T> | ApiFailure;
 
+/**
+ * The backend address for this page: `apiBase` as configured, with a path
+ * (`/api`) put on the page's own origin and `{subdomain}` replaced by the
+ * first part of the page's address (`acme` on `acme.example.com`; a leading
+ * `www.` is skipped). Empty when `apiBase` is empty, or when it asks for a
+ * subdomain and the page's address has none.
+ *
+ * A tenant's own `apiFetch` (recipes/swap-the-login-method) builds its URLs
+ * from this, so a product with a subdomain per customer calls each
+ * customer's own backend.
+ *
+ * @returns The address to put in front of a path, or `""`
+ */
+export function apiBaseUrl(): string {
+  const base = getConfig().apiBase ?? "";
+  if (!base) return "";
+  const page = typeof location === "undefined" ? null : location;
+  if (base.startsWith("/")) return page?.origin ? `${page.origin}${base}` : base;
+  if (!base.includes("{subdomain}")) return base;
+  const labels = (page?.hostname ?? "").toLowerCase().split(".").filter(Boolean);
+  if (labels[0] === "www") labels.shift();
+  // A customer subdomain is a part in front of the product's own domain:
+  // acme.example.com has one, example.com and example.co.uk do not.
+  const domainParts = ["co", "com", "org", "net", "gov", "ac", "edu"].includes(labels[labels.length - 2] ?? "") ? 3 : 2;
+  if (labels.length <= domainParts || !/^[a-z0-9-]+$/.test(labels[0])) return "";
+  return base.split("{subdomain}").join(labels[0]);
+}
+
 // What reaches the agent and the card when the build is not configured yet:
 // a state, never a developer instruction. The developer hint is in `detail`,
 // for the console only: nothing shows it unless the handler logs it.
@@ -172,6 +200,15 @@ function missingConfigResult(): ApiResult<never> | null {
       detail: "API_BASE is not set - capture the app's XHR first.",
     };
   }
+  if (!apiBaseUrl()) {
+    return {
+      ok: false,
+      status: 0,
+      reason: "config",
+      error: NOT_SET_UP,
+      detail: "API_BASE uses {subdomain}, but this page's address has no customer subdomain to put in.",
+    };
+  }
   if (!config.authSource) {
     return {
       ok: false,
@@ -251,7 +288,7 @@ const SIGNED_OUT: ApiFailure = {
 };
 
 /**
- * Authenticated JSON request against `apiBase` with `Authorization: Bearer`.
+ * Authenticated JSON request against `apiBaseUrl()` with `Authorization: Bearer`.
  *
  * For an app whose own requests carry `Authorization: Bearer`. If the live
  * page sends something else (a custom header, or cookies with no token),
@@ -283,7 +320,7 @@ export async function apiFetch<T = unknown>(
   );
 
   try {
-    const res = await fetch(`${getConfig().apiBase}${path}`, {
+    const res = await fetch(`${apiBaseUrl()}${path}`, {
       ...init,
       signal: controller.signal,
       headers: {
@@ -370,7 +407,7 @@ export async function apiFetchBinary(
   );
 
   try {
-    const res = await fetch(`${getConfig().apiBase}${path}`, {
+    const res = await fetch(`${apiBaseUrl()}${path}`, {
       ...init,
       signal: controller.signal,
       headers: { Authorization: `Bearer ${token}`, ...(init.headers ?? {}) },

package/src/runtime/index.ts

@@ -17,6 +17,7 @@ export {
   redact,
   getAuthToken,
   parseJwt,
+  apiBaseUrl,
   apiFetch,
   apiFetchBinary,
   publicFetch,

package/src/sync-core.mjs

@@ -0,0 +1,374 @@
+// Keeping this folder's agent/ up to date with the agent's saved code.
+//
+// Several builders - people or machines - can work on one agent. The saved
+// code lives in a code project this harness never reaches itself: the coding
+// agent reads it with the Foldspace tools (repo_read) and writes what it read
+// into a folder here. This module does the rest, so the manual stays short:
+//
+//   check   compares the heads the coding agent just read - develop, and the
+//           line of work saves go to (foldspace/<Agent Key>, once it exists) -
+//           with the ones this folder last pulled, and says which to pull and
+//           where to put them
+//   apply   merges what was pulled into agent/, file by file, keeping a copy
+//           of agent/ aside first, and remembers what it pulled
+//   saved   remembers a save this folder made, so its own save is not taken
+//           for someone else's
+//
+// Saving and publishing follow the code project's own instructions
+// (repo_read command "instructions"); this only keeps agent/ current.
+//
+// Everything lives in .foldspace-dev/saved-code/ (never committed):
+//   state.json            { develop: {sha}, line: {ref, sha}, pending }
+//   base/<ref>/agent/...  the files as this folder last pulled or saved them
+//   incoming/<ref>/...    where the coding agent writes what it reads
+// and the copy of agent/ goes to .foldspace-dev/agent-kept/<time>/.
+//
+// The merge is three-way per file, against what this folder last had from
+// the same ref: a file only one side changed takes that side; a file both
+// changed differently is a conflict - agent/ gets the saved version (as a
+// save refused for an older base would) and this folder's version stays in
+// the kept copy. With nothing remembered for a ref, every difference is a
+// conflict, which is the session-start rule: the saved code wins, and files
+// it lacks are put back.
+
+import fs from "node:fs";
+import path from "node:path";
+
+export const DEVELOP = "develop";
+// The line of work the code project's instructions save to.
+export const LINE_PREFIX = "foldspace/";
+const SHA = /^[0-9a-f]{7,40}$/i;
+const KEEP_COPIES = 10;
+// The build owns agent/runtime/: it puts this harness's copy back, so a
+// difference there is never someone's work to re-apply.
+const BUILD_OWNED = "agent/runtime/";
+const IGNORED = new Set([".DS_Store", "Thumbs.db"]);
+// On a first pull, the only files the saved code lacks that go back.
+const PUT_BACK = ["agent/actions/", "agent/api/", "agent/views/"];
+
+export function syncPaths(projectDir) {
+  const root = path.join(projectDir, ".foldspace-dev", "saved-code");
+  return {
+    root,
+    state: path.join(root, "state.json"),
+    base: (ref) => path.join(root, "base", ...ref.split("/")),
+    incoming: (ref) => path.join(root, "incoming", ...ref.split("/")),
+    kept: path.join(projectDir, ".foldspace-dev", "agent-kept"),
+    agent: path.join(projectDir, "agent"),
+  };
+}
+
+/** foldspace/<Agent Key>, from this project's foldspace.dev.json. */
+export function saveLine(projectDir) {
+  let config;
+  try {
+    config = JSON.parse(fs.readFileSync(path.join(projectDir, "foldspace.dev.json"), "utf8"));
+  } catch {
+    throw new Error("foldspace.dev.json not found or not valid JSON: run this from the project folder");
+  }
+  const key = config?.targets?.[config?.defaultTarget]?.agentApiName;
+  if (typeof key !== "string" || !key) {
+    throw new Error("foldspace.dev.json names no agentApiName for its defaultTarget");
+  }
+  return `${LINE_PREFIX}${key}`;
+}
+
+function requireSha(value, flag) {
+  if (typeof value !== "string" || !SHA.test(value)) {
+    throw new Error(`${flag} needs a commit id (7 to 40 hex characters), got '${value ?? ""}'`);
+  }
+  return value.toLowerCase();
+}
+
+/** Two ids name the same commit when one is a prefix of the other (short and full forms). */
+export function sameCommit(a, b) {
+  if (!a || !b) return false;
+  const x = a.toLowerCase();
+  const y = b.toLowerCase();
+  return x.startsWith(y) || y.startsWith(x);
+}
+
+export function readSyncState(projectDir) {
+  try {
+    const state = JSON.parse(fs.readFileSync(syncPaths(projectDir).state, "utf8"));
+    return { develop: null, line: null, pending: null, ...state };
+  } catch {
+    return { develop: null, line: null, pending: null };
+  }
+}
+
+function writeSyncState(projectDir, state) {
+  const file = syncPaths(projectDir).state;
+  fs.mkdirSync(path.dirname(file), { recursive: true });
+  fs.writeFileSync(file, `${JSON.stringify(state, null, 2)}\n`);
+}
+
+/** { "agent/x.ts": Buffer } for every file under dir/agent, or {} when there is none. */
+export function readTree(dir) {
+  const files = {};
+  const agentDir = path.join(dir, "agent");
+  if (!fs.existsSync(agentDir)) return files;
+  const walk = (relative) => {
+    for (const entry of fs.readdirSync(path.join(dir, relative), { withFileTypes: true })) {
+      if (IGNORED.has(entry.name)) continue;
+      const rel = path.posix.join(relative, entry.name);
+      if (entry.isDirectory()) walk(rel);
+      else if (entry.isFile()) files[rel] = fs.readFileSync(path.join(dir, rel));
+      // apply rewrites agent/ from what it read: a link would be lost.
+      else throw new Error(`${rel} is not a plain file or folder; sync handles only those`);
+    }
+  };
+  walk("agent");
+  return files;
+}
+
+function writeTree(dir, files) {
+  fs.rmSync(path.join(dir, "agent"), { recursive: true, force: true });
+  for (const [rel, content] of Object.entries(files)) {
+    const target = path.join(dir, ...rel.split("/"));
+    fs.mkdirSync(path.dirname(target), { recursive: true });
+    fs.writeFileSync(target, content);
+  }
+}
+
+const same = (a, b) => (a === undefined && b === undefined) || (a !== undefined && b !== undefined && a.equals(b));
+
+/**
+ * Three-way merge of one ref into the local files. base is what this folder
+ * last had from that ref ({} when nothing is remembered).
+ * Returns { files, fromSaved, conflicts, setAside }.
+ */
+export function mergeTrees(local, remote, base) {
+  const files = { ...local };
+  const fromSaved = [];
+  const conflicts = [];
+  const setAside = [];
+  const nothingRemembered = Object.keys(base).length === 0;
+  const paths = new Set([...Object.keys(local), ...Object.keys(remote), ...Object.keys(base)]);
+  for (const rel of [...paths].sort()) {
+    const l = local[rel];
+    const r = remote[rel];
+    const b = base[rel];
+    if (same(l, r)) continue; // nothing to do
+    if (nothingRemembered && r === undefined) {
+      // A file the saved code lacks, on a first pull: work never saved goes
+      // back (actions, their API helpers and cards); anything else - a
+      // scaffold's utils.ts beside the project's utils/ - would win an import.
+      if (!PUT_BACK.some((prefix) => rel.startsWith(prefix))) {
+        delete files[rel];
+        setAside.push(rel);
+      }
+      continue;
+    }
+    if (same(l, b)) {
+      // Only the saved code changed it (or added or deleted it).
+      if (r === undefined) delete files[rel];
+      else files[rel] = r;
+      fromSaved.push(rel);
+      continue;
+    }
+    if (same(r, b)) continue; // only this folder changed it: keep it
+    // Both changed it, differently.
+    if (r === undefined) {
+      // Deleted in the saved code, changed here: keep this folder's, and say so.
+      conflicts.push(rel);
+      continue;
+    }
+    files[rel] = r;
+    if (rel.startsWith(BUILD_OWNED)) {
+      fromSaved.push(rel);
+    } else {
+      conflicts.push(rel);
+    }
+  }
+  return { files, fromSaved, conflicts, setAside };
+}
+
+function requireProject(projectDir) {
+  if (!fs.existsSync(path.join(projectDir, "foldspace.dev.json"))) {
+    throw new Error("foldspace.dev.json not found: run this from the project folder");
+  }
+}
+
+/**
+ * check: the coding agent passes the heads it just read with repo_read -
+ * develop_head from `status`, and the head of the line of work saves go to
+ * (foldspace/<Agent Key>: the sha `tree` prints for that ref), once that line
+ * exists. Returns what to pull, and the base_sha for the next save.
+ */
+export function syncCheck(projectDir, { develop, line } = {}) {
+  requireProject(projectDir);
+  const developSha = requireSha(develop, "--develop");
+  const lineSha = line !== undefined ? requireSha(line, "--line") : null;
+  const lineRef = saveLine(projectDir);
+
+  const paths = syncPaths(projectDir);
+  const state = readSyncState(projectDir);
+  const pull = [];
+  if (!sameCommit(state.develop?.sha, developSha)) {
+    pull.push({ ref: DEVELOP, sha: developSha });
+  }
+  if (lineSha && !sameCommit(state.line?.sha, lineSha)) {
+    pull.push({ ref: lineRef, sha: lineSha });
+  }
+  for (const item of pull) {
+    const into = paths.incoming(item.ref);
+    fs.rmSync(into, { recursive: true, force: true });
+    fs.mkdirSync(into, { recursive: true });
+    item.into = path.relative(projectDir, into);
+  }
+  writeSyncState(projectDir, { ...state, pending: pull.length ? { pull, at: Date.now() } : null });
+
+  // As the code project's instructions say: the head of the ref you read -
+  // the line of work once it exists, develop before (a first save starts the
+  // line from develop's head, and is checked against it).
+  const baseSha = lineSha || developSha;
+  return {
+    kind: "foldspace.sync.check",
+    upToDate: pull.length === 0,
+    pull,
+    line: lineRef,
+    baseSha,
+    next: pull.length
+      ? "For each entry in pull, read agent/ at that ref (repo_read tree and file, ref = the entry's ref) and write each file under the entry's into folder at its project path (into/agent/...). Then run npx foldspace sync apply."
+      : `Up to date. The next save's base_sha is ${baseSha}.`,
+  };
+}
+
+function keepCopy(paths, local) {
+  if (!Object.keys(local).length) return null;
+  const stamp = new Date().toISOString().replace(/[:.]/g, "-");
+  const dir = path.join(paths.kept, stamp);
+  writeTree(dir, local);
+  // Only the latest few: each is a whole agent/.
+  try {
+    const all = fs.readdirSync(paths.kept).filter((name) => /^\d{4}-/.test(name)).sort();
+    for (const old of all.slice(0, Math.max(0, all.length - KEEP_COPIES))) {
+      fs.rmSync(path.join(paths.kept, old), { recursive: true, force: true });
+    }
+  } catch {
+    // keeping fewer copies is not worth failing over
+  }
+  return dir;
+}
+
+/** apply: merge what check asked for, which the coding agent wrote under incoming/. */
+export function syncApply(projectDir) {
+  requireProject(projectDir);
+  const paths = syncPaths(projectDir);
+  const state = readSyncState(projectDir);
+  const pull = state.pending?.pull;
+  if (!pull?.length) {
+    throw new Error("nothing to apply: run npx foldspace sync check first");
+  }
+  const incoming = pull.map((item) => {
+    const files = readTree(paths.incoming(item.ref));
+    if (!Object.keys(files).length) {
+      throw new Error(
+        `nothing was read into ${item.into}/agent/: read agent/ at ${item.ref} there first (repo_read tree and file)`,
+      );
+    }
+    return { ...item, files };
+  });
+
+  const local = readTree(projectDir);
+  const keptDir = keepCopy(paths, local);
+
+  let files = local;
+  const fromSaved = new Set();
+  const conflicts = new Set();
+  const setAside = new Set();
+  let firstPull = false;
+  let developFiles = readTree(paths.base(DEVELOP));
+  for (const item of incoming) {
+    let base = readTree(paths.base(item.ref));
+    // A line of work this folder never pulled or saved started from develop:
+    // compare against that. Known limit: if develop moved after the line
+    // started, the line's older copies of develop's files look like its own
+    // changes here; publishing merges on the server against the true start.
+    if (!Object.keys(base).length && item.ref !== DEVELOP) base = developFiles;
+    if (!Object.keys(base).length) firstPull = true;
+    const merged = mergeTrees(files, item.files, base);
+    files = merged.files;
+    merged.fromSaved.forEach((rel) => fromSaved.add(rel));
+    merged.conflicts.forEach((rel) => conflicts.add(rel));
+    merged.setAside.forEach((rel) => setAside.add(rel));
+    if (item.ref === DEVELOP) developFiles = item.files;
+  }
+  writeTree(projectDir, files);
+
+  // Remember what each ref held, as the base for the next merge.
+  const nextState = { ...state, pending: null };
+  for (const item of incoming) {
+    writeTree(paths.base(item.ref), item.files);
+    fs.rmSync(paths.incoming(item.ref), { recursive: true, force: true });
+    const entry = { sha: item.sha, at: Date.now() };
+    if (item.ref === DEVELOP) nextState.develop = entry;
+    else nextState.line = { ref: item.ref, ...entry };
+  }
+  writeSyncState(projectDir, nextState);
+
+  const keptCopy = keptDir ? path.relative(projectDir, keptDir) : null;
+  const conflictList = [...conflicts].sort();
+  // Conflicts on a ref this folder never pulled are the session-start case:
+  // work on this computer that was never saved.
+  const neverSaved = firstPull;
+  const steps = [];
+  if (conflictList.length) {
+    steps.push(
+      neverSaved
+        ? `These files differed from the saved code, which wins: tell the human in one line which actions had changes on this computer that were never saved. This folder's versions are in ${keptCopy}.`
+        : `These files changed both here and in the saved code since this folder last pulled. agent/ now has the saved version; this folder's is in ${keptCopy}. Put this session's change back on top of each.`,
+    );
+  }
+  if (fromSaved.size && !neverSaved) {
+    steps.push("Someone saved changes since this folder last pulled: tell the human in one plain line that you brought them in.");
+  }
+  steps.push("Then npm run build; if attach is running, npx foldspace attach --stop and attach again with the same flags.");
+  return {
+    kind: "foldspace.sync.apply",
+    pulled: incoming.map(({ ref, sha }) => ({ ref, sha })),
+    fromSaved: [...fromSaved].sort(),
+    conflicts: conflictList,
+    setAside: [...setAside].sort(),
+    keptCopy,
+    next: steps.join(" "),
+  };
+}
+
+/**
+ * saved: after repo_write commit, remember the new head and what was saved,
+ * so the next check does not take this folder's own save for someone else's.
+ */
+export function syncSaved(projectDir, { head, paths: savedPaths } = {}) {
+  requireProject(projectDir);
+  const lineRef = saveLine(projectDir);
+  const sha = requireSha(head, "--head");
+  const list = String(savedPaths || "")
+    .split(",")
+    .map((item) => item.trim())
+    .filter(Boolean);
+  if (!list.length) throw new Error("--paths needs the committed_paths the save returned, comma-separated");
+  for (const rel of list) {
+    if (!rel.startsWith("agent/") || rel.includes("..")) throw new Error(`'${rel}' is not a path under agent/`);
+  }
+
+  const paths = syncPaths(projectDir);
+  const state = readSyncState(projectDir);
+  // The line's first save starts it from develop's head: what this folder
+  // last pulled from develop is what the line held before this save.
+  const base = state.line ? readTree(paths.base(lineRef)) : readTree(paths.base(DEVELOP));
+  const local = readTree(projectDir);
+  for (const rel of list) {
+    if (local[rel] === undefined) delete base[rel];
+    else base[rel] = local[rel];
+  }
+  writeTree(paths.base(lineRef), base);
+  writeSyncState(projectDir, { ...state, line: { ref: lineRef, sha, at: Date.now() } });
+  return {
+    kind: "foldspace.sync.saved",
+    line: lineRef,
+    head: sha,
+    next: `The next save's base_sha is ${sha}.`,
+  };
+}

package/src/upgrade.mjs

@@ -10,6 +10,11 @@ export const INSTRUCTION_IMPORT = `@node_modules/${HARNESS_PACKAGE}/CLAUDE.md`;
 export const CACHE_TTL_MS = 12 * 60 * 60 * 1000;
 export const NPM_VIEW_TIMEOUT_MS = 2000;
 export const UPGRADE_NEXT = "Ask the human, then run npx foldspace upgrade --yes";
+// Within one line (0.1.x to a newer 0.1.y) the newest is always right: several
+// builders can work on one agent, and each session should run the same
+// harness. Crossing a line (0.1 to 0.2, or a major) still asks.
+export const AUTO_UPGRADE_NEXT =
+  "Same line: run npx foldspace upgrade --yes now, without asking, and tell the human in one plain line that you updated the Foldspace tools";
 
 const packageRoot = path.resolve(path.dirname(fileURLToPath(import.meta.url)), "..");
 const instructionTemplatePath = path.join(
@@ -85,6 +90,14 @@ export function isBehind(current, latest) {
   return compareVersions(current, latest) < 0;
 }
 
+/** Same major and minor: 0.1.20 and 0.1.34 are one line, 0.1.34 and 0.2.0 are not. */
+export function isSameLine(left, right) {
+  const a = parseSemver(left);
+  const b = parseSemver(right);
+  if (!a || !b) return false;
+  return a[0] === b[0] && a[1] === b[1];
+}
+
 function readJson(filePath) {
   return JSON.parse(fs.readFileSync(filePath, "utf8"));
 }
@@ -343,9 +356,14 @@ export function fetchDeprecationFromNpm(version, options = {}) {
 
 function nextAction(report) {
   if (report.broken) {
-    return `This harness version was withdrawn: ${report.deprecated}. ${UPGRADE_NEXT}`;
+    return `This harness version was withdrawn: ${report.deprecated}. ${report.autoUpgrade ? AUTO_UPGRADE_NEXT : UPGRADE_NEXT}`;
   }
   if (report.status === "outdated") {
+    if (report.autoUpgrade) {
+      return report.instructionsImport === false
+        ? `${AUTO_UPGRADE_NEXT}. CLAUDE.md does not import the package instructions: ask the human before npx foldspace upgrade --refresh-instructions (the old CLAUDE.md is kept as CLAUDE.md.bak).`
+        : AUTO_UPGRADE_NEXT;
+    }
     return report.instructionsImport === false
       ? "CLAUDE.md does not import the package instructions. Ask the human, then run npx foldspace upgrade --yes --refresh-instructions (the old CLAUDE.md is kept as CLAUDE.md.bak)."
       : UPGRADE_NEXT;
@@ -455,10 +473,18 @@ export function checkForUpdate(projectDir, options = {}) {
     outdated: status === "outdated",
     deprecated,
     broken: Boolean(deprecated),
+    // A newer version in the same line: upgrade without asking (manual, step 1).
+    autoUpgrade: false,
     status,
     instructionsImport,
     next: null,
   };
+  report.autoUpgrade = Boolean(
+    (report.outdated || report.broken) &&
+      latest &&
+      isBehind(running, latest) &&
+      isSameLine(running, latest),
+  );
   report.next = nextAction(report);
   return report;
 }
@@ -466,7 +492,8 @@ export function checkForUpdate(projectDir, options = {}) {
 /**
  * What `build` and `attach` do with an update report before they run:
  * `block: true` stops the command, `message` (if any) is printed to stderr.
- * Never upgrades - that stays the human's decision (CLAUDE.md, step 1).
+ * Never upgrades itself: the coding agent runs upgrade (CLAUDE.md, step 1) -
+ * without asking within a line, after asking across one.
  * The escape hatch is FOLDSPACE_SKIP_UPDATE_CHECK=1: the report comes back
  * check_skipped, so nothing here blocks.
  */
@@ -476,15 +503,16 @@ export function gateForCommand(report) {
   if (report.broken) {
     return {
       block: true,
-      message:
-        `${HARNESS_PACKAGE} ${report.installed || report.pinned} was withdrawn: ${report.deprecated}. ` +
-        `${UPGRADE_NEXT}. If the human declines, rerun with FOLDSPACE_SKIP_UPDATE_CHECK=1 to run this version anyway.`,
+      message: report.autoUpgrade
+        ? `${HARNESS_PACKAGE} ${report.installed || report.pinned} was withdrawn: ${report.deprecated}. ${AUTO_UPGRADE_NEXT}, then run this again.`
+        : `${HARNESS_PACKAGE} ${report.installed || report.pinned} was withdrawn: ${report.deprecated}. ` +
+          `${UPGRADE_NEXT}. If the human declines, rerun with FOLDSPACE_SKIP_UPDATE_CHECK=1 to run this version anyway.`,
     };
   }
   if (report.outdated) {
     return {
       block: false,
-      message: `${HARNESS_PACKAGE} ${report.installed || report.pinned} is behind ${report.latest}. ${UPGRADE_NEXT}.`,
+      message: `${HARNESS_PACKAGE} ${report.installed || report.pinned} is behind ${report.latest}. ${report.autoUpgrade ? AUTO_UPGRADE_NEXT : UPGRADE_NEXT}.`,
     };
   }
   return { block: false, message: null };
@@ -632,6 +660,7 @@ export async function runUpgrade(argv, options = {}) {
     pinned: shouldInstall ? report.latest : report.pinned,
     installed: shouldInstall ? report.latest : report.installed,
     outdated: false,
+    autoUpgrade: false,
     status: shouldInstall ? "upgraded" : refreshed.written ? "instructions_refreshed" : report.status,
     instructionsImport: shouldRefresh ? true : report.instructionsImport,
     refreshed: refreshed.written,
@@ -645,6 +674,6 @@ export async function runUpgrade(argv, options = {}) {
 export function nagIfOutdated(report, write = (message) => console.error(message)) {
   if (!report?.outdated) return;
   write(
-    `foldspace: ${HARNESS_PACKAGE} ${report.pinned || report.installed} is behind ${report.latest}. ${UPGRADE_NEXT}.`,
+    `foldspace: ${HARNESS_PACKAGE} ${report.pinned || report.installed} is behind ${report.latest}. ${report.autoUpgrade ? AUTO_UPGRADE_NEXT : UPGRADE_NEXT}.`,
   );
 }

package/src/video/compose.mjs

@@ -15,7 +15,7 @@ import os from "node:os";
 import path from "node:path";
 import { fileURLToPath } from "node:url";
 
-import { findChrome } from "../chrome-binary.mjs";
+import { KEEP_RUNNING_ARGS, findChrome } from "../chrome-binary.mjs";
 import { scenePlace } from "./scenes.mjs";
 import { TIMING, fitToLength, layoutClips, sceneTimeMap } from "./timeline.mjs";
 
@@ -180,8 +180,7 @@ const HEADLESS_ARGS = [
   "--disable-default-apps",
   "--disable-background-networking",
   "--disable-component-update",
-  "--disable-background-timer-throttling",
-  "--disable-renderer-backgrounding",
+  ...KEEP_RUNNING_ARGS,
   "--mute-audio",
   "--hide-scrollbars",
 ];
@@ -474,3 +473,13 @@ export function needsChrome(chromePath) {
     ? `The video needs Google Chrome: this Chrome (${chromePath}) cannot encode H.264 video, as some Chromium builds cannot. Install Google Chrome, or set CHROME_PATH to it.`
     : "The video needs Google Chrome, and none was found. Install Google Chrome, or set CHROME_PATH to it.";
 }
+
+/** Wider than this many page pixels, the product shrinks to fit a 1920-wide video and its small text gets hard to read on a phone. */
+export const WIDE_WINDOW_PX = 1920;
+
+/** A note when the test window was wider than WIDE_WINDOW_PX while it recorded; null otherwise. */
+export function wideWindowNote(recording) {
+  const widest = Math.max(0, ...recording.scenes.map((scene) => scene.events?.viewport?.width || 0));
+  if (widest <= WIDE_WINDOW_PX) return null;
+  return `The test window was ${widest} px wide, so the product is shrunk to fit the video and small text may be hard to read on a phone. To fix it, make the test window narrower (about 1440-1600 px) and record again - the human decides.`;
+}

package/src/video/recorder.mjs

@@ -39,6 +39,20 @@ export const RECORD_DEFAULTS = Object.freeze({
   typingGapMaxMs: 1000,
 });
 
+// The pictures Chrome sends. It captures at the window's own pixel density -
+// 2x on a Retina screen - and shrinks a picture to fit maxWidth x maxHeight.
+// At maxWidth 1920 a Retina window 2336 CSS px wide came out 1920 px wide:
+// below its own size, so the panel's 12-13px text was soft in the video. Twice
+// the 1920x1080 video is all the composer can use; it downscales from there.
+// The page, its layout and its size are untouched: nothing is zoomed.
+export const SCREENCAST = Object.freeze({
+  format: "jpeg",
+  quality: 92,
+  maxWidth: 3840,
+  maxHeight: 2400,
+  everyNthFrame: 1,
+});
+
 /** Pause between keys: a question types in about 1.6 s, never faster than a quick typist. */
 export function keyDelayMs(question) {
   const length = [...String(question || "")].length || 1;
@@ -161,13 +175,7 @@ function screencastSink(page, sceneDir, { minGapMs }) {
     async start() {
       page.on("Page.screencastFrame", onFrame);
       page.on("Page.screencastVisibilityChanged", onVisibility);
-      await page.send("Page.startScreencast", {
-        format: "jpeg",
-        quality: 85,
-        maxWidth: 1920,
-        maxHeight: 1200,
-        everyNthFrame: 1,
-      });
+      await page.send("Page.startScreencast", { ...SCREENCAST });
     },
     async stop() {
       await page.send("Page.stopScreencast", {}, { timeoutMs: 5000 }).catch(() => {});