@foldspace_npm/harness 0.1.33 → 0.1.35

package/bin/record.mjs

@@ -37,6 +37,7 @@ import {
   checkRecordingMatches,
   closeAllHeadless,
   loadRecording,
+  wideWindowNote,
   needsChrome,
   probeEncoder,
   renderInChrome,
@@ -337,6 +338,7 @@ async function compose(config, recordDir, chromePath) {
           note: `${Math.round(plan.fit.totalS)} s, longer than the ${TIMING.maxTotalS} s it should be at most, with the waits already shortened: drop a scene, or pick questions with shorter answers.`,
         }
       : {}),
+    ...(wideWindowNote(recording) ? { wideWindow: wideWindowNote(recording) } : {}),
     sceneSeconds: plan.clips.filter((clip) => clip.kind === "scene").map((clip) => Math.round(clip.durationS * 10) / 10),
     lastFrames: lastFrames(recording),
   };

package/bin/sync.mjs

@@ -0,0 +1,48 @@
+#!/usr/bin/env node
+/**
+ * foldspace sync <check|apply|saved> [options]
+ *
+ * Keeps this folder's agent/ up to date with the agent's saved code, which
+ * several builders can work on. The coding agent reads the saved code with the
+ * Foldspace tools and passes the heads it read; this command remembers what
+ * this folder last pulled (.foldspace-dev/saved-code/) and merges.
+ *
+ *   check --develop <sha> [--line <sha>]
+ *   apply
+ *   saved --head <commit_sha> --paths <a,b,...>
+ *
+ * Saving and publishing follow the code project's own instructions.
+ */
+import { resolveProjectDir } from "../src/upgrade.mjs";
+import { syncApply, syncCheck, syncSaved } from "../src/sync-core.mjs";
+
+const VALUE_FLAGS = new Set(["--develop", "--line", "--head", "--paths"]);
+
+function parse(argv) {
+  const flags = {};
+  const rest = [];
+  for (let index = 0; index < argv.length; index++) {
+    const arg = argv[index];
+    if (VALUE_FLAGS.has(arg)) flags[arg.slice(2)] = argv[++index];
+    else if (arg.startsWith("--")) throw new Error(`unknown option '${arg}'`);
+    else rest.push(arg);
+  }
+  return { flags, rest };
+}
+
+try {
+  const projectDir = resolveProjectDir();
+  const { flags, rest } = parse(process.argv.slice(2));
+  const [verb, extra] = rest;
+  if (extra) throw new Error(`unexpected argument '${extra}'`);
+  const allowed = { check: ["develop", "line"], apply: [], saved: ["head", "paths"] }[verb];
+  if (!allowed) throw new Error("usage: foldspace sync <check|apply|saved> - see foldspace help sync");
+  const stray = Object.keys(flags).find((name) => !allowed.includes(name));
+  if (stray) throw new Error(`option '--${stray}' does not go with sync ${verb}`);
+  const report =
+    verb === "check" ? syncCheck(projectDir, flags) : verb === "apply" ? syncApply(projectDir) : syncSaved(projectDir, flags);
+  process.stdout.write(`${JSON.stringify(report, null, 2)}\n`);
+} catch (error) {
+  console.error(`sync: ${error instanceof Error ? error.message : String(error)}`);
+  process.exitCode = 1;
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@foldspace_npm/harness",
-  "version": "0.1.33",
+  "version": "0.1.35",
   "description": "Build and verify portable Foldspace action artifacts against a live app.",
   "type": "module",
   "bin": {

package/recipes/INDEX.md

@@ -8,7 +8,7 @@ Read this whole table, then open the recipe closest to the outcome.
 | [`find-by-name`](find-by-name/) | **L2** | The agent turns a name the user said into the id the next action needs; a count when no name is given; every tie when the name is ambiguous; near-misses when nothing matches | A data action. **No card** | 3 production builds |
 | [`lookup-then-view`](lookup-then-view/) | **L2** | Show one account the user names - **start here**. One clear match: its card, no question. Several or none: the **pick-one** list - search, pages, one click - then the card: who it is, the money, open deals, people, open cases. The card action's **required** `accountId`, described as coming from the lookup, makes the agent call the lookup first. The app already hands over the id → `account-overview` | Two actions - an input card (`find_account`) and a view card (`show_account_overview`) - with their Agent Studio definitions word for word | 1 production build |
 | [`pick-from-a-list`](pick-from-a-list/) | **L2** | A clickable list, shown **only** when the user has to choose — with "none of these" and cancel | An input card: the agent waits for the user's answer | 1 production build |
-| [`bottom-bar`](bottom-bar/) | **L0** | The agent's resting entry point is a bar at the foot of the page whose starters change with the screen the user is on - configured from code, the way customers do it | Page set-up, runs once at start-up | 2 production builds |
+| [`bottom-bar`](bottom-bar/) | **L0** | The agent's resting entry point is a bar at the foot of the page (Foldspace turns it on) whose starters - at most 3 - change with the screen the user is on, set from code | Page set-up, runs once at start-up | 2 production builds |
 | [`swap-the-login-method`](swap-the-login-method/) | any | `apiFetch` for an app that authenticates with a custom header, or with cookies, instead of a bearer token | A replacement `agent/utils.ts` | 2 production builds (a third uses the default bearer token) |
 | [`account-overview`](account-overview/) | **L2** | One account on a card, when the app already hands over its id: identity, pipeline total, contacts, cases, meetings. The agent gets what the card shows. An account the user names → `lookup-then-view` | A view card: no `callback`, no `awaitUserInput` | 1 production build |
 | [`upload-contacts`](upload-contacts/) | **L4** | A CSV is previewed, then written only after the user chooses Import | An input card: the agent waits for the user's answer | 1 production build |

package/recipes/bottom-bar/README.md

@@ -5,17 +5,19 @@ page that shows a few starters and opens the agent when one is clicked. Its
 starters change with the screen the user is on, so an agent with two actions
 still looks useful everywhere.
 
-It is configured **from code** — Agent Studio has no UI for it today, and this
-is how customers set it. **Proven by 2 production builds** (one in the
-product's own source, one from the agent project behind a feature flag).
+**Foldspace turns the bar on** from its own settings - this code does not.
+What the code does is pick each page's starters.
+**Proven by 2 production builds** (one in the product's own source, one from
+the agent project behind a feature flag).
 
 ## Adapt it
 
 | In `agent/bottomBar.ts` | Change |
 |---|---|
-| `PAGE_STARTERS` | This product's screens (path prefixes) and, for each, two or three questions **its actions can answer**. A starter for something the agent cannot do is worse than none |
-| `DEFAULT_STARTERS` | What to show on any other page. It replaces the agent-wide starters there |
-| `BOTTOM_BAR_SETTINGS` | The docs' settings, except two: `enabled: true` (the docs default it to `false`, and the bar then never renders) and `maxVisibleStarters: 3` (the docs default 5). Change any of them only if the human asks |
+| `PAGE_STARTERS` | The product's main-menu screens (`npx foldspace observe menu`: path prefixes) and, for each, **at most 3 starters** the agent can answer today. A starter for something the agent cannot do is worse than none: leave that page out |
+| `ACTION` or `KNOWLEDGE` | `ACTION` when clicking it runs one of the agent's actions - the bar shows the action icon. `KNOWLEDGE` when the answer comes from what the agent knows (its knowledge base) |
+
+A page that is not listed shows Agent Studio's starters (`setConversationStarters(null)`).
 
 Then call it from the bundle's entry point:
 
@@ -30,14 +32,25 @@ installBottomBar();
 - **`setConversationStarters` replaces the whole set for the page** — both
   groups. `null` restores Agent Studio's. So always pass the full list you
   want shown.
+- **It also sets the agent panel's opening screen**, not only the bar. One
+  customer's list had 7 there. At most 3 per page, both groups together:
+  `npx foldspace lint` refuses more. `maxVisibleStarters` caps the bar only.
+- **Route changes in a single-page app don't reload**, so the starters must be
+  re-applied on navigation. The recipe uses the browser's own page-change
+  event (`navigation`'s `currententrychange`); where a browser has no
+  Navigation API (⚠️ some Safari and Firefox versions, not tried live) it
+  wraps `pushState` / `replaceState` and listens to `popstate`. It brings the
+  bar back to full only when the starters change; a navigation that keeps the
+  same starters leaves a bar that has folded to compact as it is.
+- **An older SDK may lack these calls.** The recipe then logs once in the
+  console and leaves Agent Studio's starters.
+- **No `bottomBarSettings`.** Send one only if the human asks for a setting
+  that differs from the default (the fields are on the Bottom Bar page), and
+  send `enabled: true` in the same group. ⚠️ Whether a partial group merges
+  with Foldspace's own settings is not verified.
 - **In embedded mode the bar needs `openEmbeddedCallback`**, or the bar does
   not render at all. This recipe is for the overlay agent; see the docs for
   embedded.
-- **Route changes in a single-page app don't reload**, so the starters must be
-  re-applied on navigation - this recipe wraps `pushState` / `replaceState`
-  and listens to `popstate`. It brings the bar back to full only when the
-  starters change; a navigation that keeps the same starters leaves a bar
-  that has folded to compact (after `idleTimeoutMs`) as it is.
 - **Dark mode**: the SDK's default colours do not follow a dark theme yet
   (PLG-5891, in the backlog); a product in dark mode may need `theme` /
   `darkModeSettings` set.

package/recipes/bottom-bar/agent/bottomBar.ts

@@ -1,52 +1,64 @@
 // The bottom bar: the agent's resting entry point at the foot of the page,
-// cycling starters that fit the screen the user is on. Configured from code -
-// Agent Studio has no UI for it today, and this is how customers set it.
+// showing starters that fit the screen the user is on.
 // https://docs.foldspace.ai/customize/bottom-bar/
 // https://docs.foldspace.ai/customize/conversation-starters/
 //
+// Foldspace turns the bar on from its own settings, so this code never sends
+// `bottomBarSettings`: it only picks each page's starters.
+//
 // Product-neutral: the paths and starters below are placeholders. Replace them
-// with this product's own screens and with questions its actions can answer.
+// with this product's main-menu screens (`npx foldspace observe menu`) and,
+// for each, starters the agent can answer today.
 
 import { getAgent } from "./utils";
 
-/** Starters per screen. Paths are matched as prefixes, first match wins. */
-export const PAGE_STARTERS: Array<{ match: RegExp; starters: string[] }> = [
-  { match: /^\/dashboard/, starters: ["<A question about what this screen shows>", "<Another one>"] },
-  { match: /^\/<records>/, starters: ["Find <a record> by name", "Show me <a record>'s details"] },
-];
+/**
+ * The most starters one page shows, both groups together. The same call sets
+ * the agent panel's opening screen, and a long list there buries the one
+ * that matters. `npx foldspace lint` refuses more.
+ */
+export const MAX_STARTERS_PER_PAGE = 3;
 
-/** Shown on any page not listed above. */
-export const DEFAULT_STARTERS: string[] = ["What can you do?", "<A question one of its actions can answer>"];
+/**
+ * Starters per screen. Paths are matched as prefixes, first match wins.
+ * - `ACTION`: clicking it runs one of the agent's actions (the bar shows the
+ *   action icon), e.g. "Show my open invoices".
+ * - `KNOWLEDGE`: a question answered from what the agent knows (its knowledge
+ *   base), e.g. "How do I add a teammate?".
+ * A page that is not listed shows Agent Studio's starters.
+ */
+export const PAGE_STARTERS: Array<{ match: RegExp; KNOWLEDGE: string[]; ACTION: string[] }> = [
+  { match: /^\/dashboard/, KNOWLEDGE: [], ACTION: ["<Something an action shows about this screen>"] },
+  { match: /^\/<records>/, KNOWLEDGE: ["<A how-to question about this screen>"], ACTION: ["Find <a record> by name"] },
+];
 
-// The docs' settings, except two: `enabled: true` (the docs default it to
-// `false`, and the bar then never renders) and `maxVisibleStarters: 3` (the
-// docs default 5). Change any of them only if the human asks: every field is
-// documented on the Bottom Bar page.
-export const BOTTOM_BAR_SETTINGS = {
-  enabled: true,
-  maxVisibleStarters: 3,
-  reopenFrequency: "EVERY_LOAD",
-  starterClickBehavior: "OPEN_AGENT",
-  idleTimeoutMs: 5000,
-  initialBehaviorMode: "FULL",
-} as const;
+export type PageStarters = (typeof PAGE_STARTERS)[number];
 
-export function startersForPath(pathname: string): string[] {
-  const hit = PAGE_STARTERS.find((entry) => entry.match.test(pathname));
-  return hit ? hit.starters : DEFAULT_STARTERS;
+/** This page's starters, or null for a page that keeps Agent Studio's. */
+export function startersForPath(pathname: string): PageStarters | null {
+  return PAGE_STARTERS.find((entry) => entry.match.test(pathname)) ?? null;
 }
 
 // On window, not in module scope: a bundle evaluated twice on one page must
 // not install two route listeners.
 const INSTALLED_FLAG = "__foldspace_bottom_bar__";
 
+const warned = new Set<string>();
+function warnOnce(method: string): void {
+  if (warned.has(method)) return;
+  warned.add(method);
+  console.warn(
+    `[foldspace] This page's Foldspace SDK has no ${method}(), so the bottom bar keeps Agent Studio's starters. Load a newer SDK to get page starters.`,
+  );
+}
+
 /**
- * Set up the bar and keep its starters matched to the page. Call once from
- * the bundle's entry point; safe to call again.
+ * Keep the bar's starters matched to the page. Call once from the bundle's
+ * entry point; safe to call again.
  *
  * `setConversationStarters` REPLACES the whole set for this page view (both
- * groups); passing `null` restores what Agent Studio has. Starters go in the
- * KNOWLEDGE group so the bar shows them as plain questions.
+ * groups) and also sets the panel's opening screen; `null` restores what
+ * Agent Studio has.
  */
 export function installBottomBar(): void {
   const foldspace = (window as any).foldspace;
@@ -57,7 +69,12 @@ export function installBottomBar(): void {
   foldspace("when", "ready", () => {
     const agent = getAgent();
     if (!agent) return;
-    let current: string[] = [];
+    if (typeof agent.setConversationStarters !== "function") {
+      warnOnce("setConversationStarters");
+      return;
+    }
+    // Agent Studio's starters are what the page starts with.
+    let current: PageStarters | null = null;
 
     // On a navigation, the bar is brought back to full only when its starters
     // changed, so the new ones are seen. Same starters: nothing is sent, and a
@@ -66,19 +83,40 @@ export function installBottomBar(): void {
       const next = startersForPath(window.location.pathname);
       if (next === current) return;
       current = next;
-      agent.setConversationStarters?.(
-        { KNOWLEDGE: next.map((title) => ({ title })), ACTION: [] },
-        "KNOWLEDGE",
-      );
-      if (reopen) agent.openBottomBar?.({ mode: "FULL" });
+      if (next) {
+        agent.setConversationStarters(
+          {
+            KNOWLEDGE: next.KNOWLEDGE.map((title) => ({ title })),
+            ACTION: next.ACTION.map((title) => ({ title })),
+          },
+          // The group shown first. Not documented: which group the bar itself
+          // shows when a page has both - check it on the page.
+          next.ACTION.length ? "ACTION" : "KNOWLEDGE",
+        );
+      } else {
+        agent.setConversationStarters(null);
+      }
+      if (!reopen) return;
+      if (typeof agent.openBottomBar === "function") agent.openBottomBar({ mode: "FULL" });
+      else warnOnce("openBottomBar");
     };
 
-    // One whole settings group per call, as the docs do.
-    agent.setConfiguration?.({ bottomBarSettings: BOTTOM_BAR_SETTINGS });
     apply(false);
 
-    // Single-page apps change the URL without a load: re-apply on navigation.
+    // Single-page apps change the address without a page load: re-apply on
+    // each navigation. The browser's own page-change event where it has one:
+    // `currententrychange` fires once the address has changed - router links,
+    // pushState, replaceState, back and forward. (`navigate` fires before the
+    // address changes, so the page it would read is the old one.)
     const onRouteChange = () => apply(true);
+    const navigation = (window as any).navigation;
+    if (navigation && typeof navigation.addEventListener === "function") {
+      navigation.addEventListener("currententrychange", onRouteChange);
+      return;
+    }
+    // Browsers without the Navigation API (some Safari and Firefox versions;
+    // not tried live): listen for back/forward and wrap pushState /
+    // replaceState.
     window.addEventListener("popstate", onRouteChange);
     const history = window.history as any;
     for (const method of ["pushState", "replaceState"] as const) {

package/recipes/bottom-bar/fixtures/configuration.sent.json

@@ -1,17 +1,18 @@
 {
-  "note": "This recipe makes no network calls. What it sends to the SDK on /dashboard:",
-  "setConfiguration": {
-    "bottomBarSettings": {
-      "enabled": true,
-      "maxVisibleStarters": 3,
-      "reopenFrequency": "EVERY_LOAD",
-      "starterClickBehavior": "OPEN_AGENT",
-      "idleTimeoutMs": 5000,
-      "initialBehaviorMode": "FULL"
+  "note": "This recipe makes no network calls and sends no bottomBarSettings (Foldspace turns the bar on). What it sends to the SDK on each page:",
+  "/dashboard": {
+    "setConversationStarters": {
+      "starters": { "KNOWLEDGE": [], "ACTION": [{ "title": "<Something an action shows about this screen>" }] },
+      "defaultStarterType": "ACTION"
     }
   },
-  "setConversationStarters": {
-    "starters": { "KNOWLEDGE": [{ "title": "<A question about what this screen shows>" }, { "title": "<Another one>" }], "ACTION": [] },
-    "defaultStarterType": "KNOWLEDGE"
+  "/<records>/42": {
+    "setConversationStarters": {
+      "starters": { "KNOWLEDGE": [{ "title": "<A how-to question about this screen>" }], "ACTION": [{ "title": "Find <a record> by name" }] },
+      "defaultStarterType": "ACTION"
+    }
+  },
+  "a page with no starters of its own, after one that had them": {
+    "setConversationStarters": { "starters": null }
   }
 }

package/recipes/swap-the-login-method/README.md

@@ -31,7 +31,7 @@ says). If you observed neither, leave the user anonymous.
 |---|---|
 | `SESSION_STORAGE_KEY`, `SESSION_HEADER` | The key and header name you **observed** |
 | `EXTRA_HEADERS` in the cookies variant | What you **observed** the app sending besides the cookies; most apps send none |
-| `API_BASE` in `constants.ts` | For a same-origin app, the app's own origin. Empty stays a failure on purpose, so a guessed host cannot look like success |
+| `API_BASE` in `constants.ts` | For a same-origin app, `"/api"` (the path), so each user's page calls its own host - on a product with a subdomain per customer, never the address you observed (the manual's **Each customer on their own subdomain**). Empty stays a failure on purpose, so a guessed host cannot look like success. Both files build their URLs with `apiBaseUrl()`, never `API_BASE` directly |
 
 ## What those builds learned the hard way
 

package/recipes/swap-the-login-method/agent/utils.ts

@@ -4,7 +4,7 @@
 // Only the transport is replaced. What a 401, a 404 or a 429 means still comes
 // from the harness, so actions and renderFailure behave exactly the same.
 
-import { configure, httpFailure, networkFailure, type ApiResult } from "@foldspace_npm/harness/runtime";
+import { apiBaseUrl, configure, httpFailure, networkFailure, type ApiResult } from "@foldspace_npm/harness/runtime";
 import { AGENT_API_NAME, API_BASE } from "./constants";
 
 configure({ agentApiName: AGENT_API_NAME, apiBase: API_BASE });
@@ -27,13 +27,13 @@ export async function apiFetch<T = unknown>(
   // Empty API_BASE is a failure on purpose: a guessed host cannot look like
   // success. `error` is drawn on the card and read by the agent - it says what
   // is true; the builder's hint goes in `detail`, which only the console sees.
-  if (!API_BASE) {
+  if (!apiBaseUrl()) {
     return {
       ok: false,
       status: 0,
       reason: "config",
       error: "This is not set up yet.",
-      detail: "API_BASE is not set - capture the app's XHR first.",
+      detail: "API_BASE is not set, or names a {subdomain} this page does not have.",
     };
   }
   const session = readSession();
@@ -42,7 +42,7 @@ export async function apiFetch<T = unknown>(
   const controller = new AbortController();
   const timer = setTimeout(() => controller.abort(), timeoutMs);
   try {
-    const res = await fetch(`${API_BASE}${path}`, {
+    const res = await fetch(`${apiBaseUrl()}${path}`, {
       ...init,
       signal: controller.signal,
       headers: { "Content-Type": "application/json", [SESSION_HEADER]: session, ...(init.headers ?? {}) },
@@ -69,13 +69,13 @@ export async function apiFetchBinary(
   init: RequestInit = {},
   timeoutMs = 15_000,
 ): Promise<ApiResult<Uint8Array>> {
-  if (!API_BASE) {
+  if (!apiBaseUrl()) {
     return {
       ok: false,
       status: 0,
       reason: "config",
       error: "This is not set up yet.",
-      detail: "API_BASE is not set - capture the app's XHR first.",
+      detail: "API_BASE is not set, or names a {subdomain} this page does not have.",
     };
   }
   const session = readSession();
@@ -84,7 +84,7 @@ export async function apiFetchBinary(
   const controller = new AbortController();
   const timer = setTimeout(() => controller.abort(), timeoutMs);
   try {
-    const res = await fetch(`${API_BASE}${path}`, {
+    const res = await fetch(`${apiBaseUrl()}${path}`, {
       ...init,
       signal: controller.signal,
       headers: { [SESSION_HEADER]: session, ...(init.headers ?? {}) },
@@ -103,6 +103,7 @@ export async function apiFetchBinary(
 // the harness's returns a config failure here, because this file sets no
 // `authSource`. For the same reason getAuthToken returns null (see the README).
 export {
+  apiBaseUrl,
   getAgent,
   armAllInstances,
   rankBy,

package/recipes/swap-the-login-method/variants/utils.cookies.ts

@@ -4,7 +4,7 @@
 // There is nothing to check before the request, so "signed out" is only known
 // from the 401. It comes back as `signed_out` like any other.
 
-import { configure, httpFailure, networkFailure, type ApiResult } from "@foldspace_npm/harness/runtime";
+import { apiBaseUrl, configure, httpFailure, networkFailure, type ApiResult } from "@foldspace_npm/harness/runtime";
 import { AGENT_API_NAME, API_BASE } from "./constants";
 
 configure({ agentApiName: AGENT_API_NAME, apiBase: API_BASE });
@@ -24,20 +24,20 @@ export async function apiFetch<T = unknown>(
   // Empty API_BASE is a failure on purpose: a guessed host cannot look like
   // success. `error` is drawn on the card and read by the agent - it says what
   // is true; the builder's hint goes in `detail`, which only the console sees.
-  if (!API_BASE) {
+  if (!apiBaseUrl()) {
     return {
       ok: false,
       status: 0,
       reason: "config",
       error: "This is not set up yet.",
-      detail: "API_BASE is not set - capture the app's XHR first.",
+      detail: "API_BASE is not set, or names a {subdomain} this page does not have.",
     };
   }
 
   const controller = new AbortController();
   const timer = setTimeout(() => controller.abort(), timeoutMs);
   try {
-    const res = await fetch(`${API_BASE}${path}`, {
+    const res = await fetch(`${apiBaseUrl()}${path}`, {
       ...init,
       credentials: "include",
       signal: controller.signal,
@@ -65,20 +65,20 @@ export async function apiFetchBinary(
   init: RequestInit = {},
   timeoutMs = 15_000,
 ): Promise<ApiResult<Uint8Array>> {
-  if (!API_BASE) {
+  if (!apiBaseUrl()) {
     return {
       ok: false,
       status: 0,
       reason: "config",
       error: "This is not set up yet.",
-      detail: "API_BASE is not set - capture the app's XHR first.",
+      detail: "API_BASE is not set, or names a {subdomain} this page does not have.",
     };
   }
 
   const controller = new AbortController();
   const timer = setTimeout(() => controller.abort(), timeoutMs);
   try {
-    const res = await fetch(`${API_BASE}${path}`, {
+    const res = await fetch(`${apiBaseUrl()}${path}`, {
       ...init,
       credentials: "include",
       signal: controller.signal,
@@ -98,6 +98,7 @@ export async function apiFetchBinary(
 // the harness's returns a config failure here, because this file sets no
 // `authSource`. For the same reason getAuthToken returns null (see the README).
 export {
+  apiBaseUrl,
   getAgent,
   armAllInstances,
   rankBy,

package/src/chrome-binary.mjs

@@ -26,3 +26,36 @@ export function chromeCandidates(platform = os.platform(), env = process.env) {
 export function findChrome({ env = process.env, platform = os.platform(), exists = fs.existsSync } = {}) {
   return env.CHROME_PATH || chromeCandidates(platform, env).find((candidate) => exists(candidate)) || null;
 }
+
+// Chrome slows a page whose window is hidden, covered or minimized - timers
+// throttled, the renderer moved to the background - and the build in it stalls.
+// These keep the test window working while the builder looks at another app
+// or another macOS user's session (⚠️ not tried live with a user switch).
+// The hidden Chrome that makes the video uses them too.
+export const KEEP_RUNNING_ARGS = Object.freeze([
+  "--disable-background-timer-throttling",
+  "--disable-renderer-backgrounding",
+  "--disable-backgrounding-occluded-windows",
+]);
+
+/** How `inject` starts the test window. */
+export function testWindowArgs({ profileDir, debugPort, themeDir, startUrl }) {
+  return [
+    `--user-data-dir=${profileDir}`,
+    `--remote-debugging-port=${debugPort}`,
+    // The theme only paints the isolated window Foldspace blue. SDK and action
+    // code are loaded later by attach over CDP.
+    `--load-extension=${themeDir}`,
+    `--disable-extensions-except=${themeDir}`,
+    // Chrome 136+ dropped --load-extension. Keep the legacy switch for older
+    // builds, and enable the CDP Extensions domain so we can load it at runtime.
+    "--disable-features=DisableLoadExtensionCommandLineSwitch",
+    "--enable-unsafe-extension-debugging",
+    "--no-first-run",
+    "--no-default-browser-check",
+    "--test-type",
+    "--remote-allow-origins=*",
+    ...KEEP_RUNNING_ARGS,
+    startUrl,
+  ];
+}

package/src/cli-registry.mjs

@@ -76,7 +76,7 @@ export const CLI_COMMANDS = Object.freeze([
     name: "upgrade",
     entry: null,
     group: "start",
-    summary: "Check for a newer harness and, after asking, update the version this project uses",
+    summary: "Check for a newer harness and update the version this project uses",
     usage:
       "foldspace upgrade [--check | --yes] [--refresh-instructions]",
     risk: "local-write",
@@ -91,7 +91,7 @@ export const CLI_COMMANDS = Object.freeze([
       flag("--check", "Compare versions and print JSON; never install"),
       flag(
         "--yes",
-        "Install the latest version after the human has agreed",
+        "Install the latest version: within the same line (update.autoUpgrade) without asking; across a line, after the human has agreed",
       ),
       flag(
         "--refresh-instructions",
@@ -111,11 +111,56 @@ export const CLI_COMMANDS = Object.freeze([
       "Any foldspace command writes a harness skill the project is missing, so the first upgrade from a harness older than the skill still gets it",
     ],
     next: [
-      "If outdated, ask the human, then run npx foldspace upgrade --yes",
+      "If update.autoUpgrade (a newer version in the same line, such as 0.1.x): run npx foldspace upgrade --yes without asking, and tell the human in one plain line",
+      "If outdated across a line (0.1 to 0.2): ask the human, then run npx foldspace upgrade --yes",
       "Run npm run build after an upgrade",
       "If attach is running: `npx foldspace attach --stop`, then `npx foldspace attach --daemon` with the flags it ran with, to load the rebuild",
     ],
   }),
+  Object.freeze({
+    name: "sync",
+    entry: "sync.mjs",
+    group: "start",
+    summary: "Keep agent/ up to date with the agent's saved code: what to pull, then merge it in",
+    usage:
+      "foldspace sync <check|apply|saved> [--develop <sha>] [--line <sha>] [--head <sha>] [--paths <a,b>]",
+    risk: "local-write",
+    environment: "node",
+    environmentVariables: ["FOLDSPACE_PROJECT_DIR"],
+    capabilities: ["project.sync"],
+    positionals: [
+      Object.freeze({
+        name: "verb",
+        required: true,
+        description:
+          "check: compare the heads you just read with what this folder last pulled, and say what to pull | apply: merge what you pulled into agent/ | saved: remember a save this folder made",
+      }),
+    ],
+    options: [
+      value("--develop", "sha", "check: develop_head from repo_read status"),
+      value("--line", "sha", "check: the head of foldspace/<Agent Key>, the line of work saves go to (the sha repo_read tree prints for that ref); leave it out while that line does not exist"),
+      value("--head", "sha", "saved: the commit_sha the save returned"),
+      value("--paths", "a,b", "saved: the committed_paths the save returned, comma-separated"),
+    ],
+    prerequisites: [
+      "foldspace.dev.json",
+      "A code project (repo_read status), read with the Foldspace tools: this command never reaches Foldspace itself",
+    ],
+    effects: [
+      "Writes only under .foldspace-dev/ (saved-code/ and agent-kept/) and, for apply, agent/",
+      "Changes nothing about saving or publishing: those follow repo_read command instructions",
+      "check names each ref to pull and the folder to write it into (pull[].into); it pulls nothing itself",
+      "apply copies agent/ to .foldspace-dev/agent-kept/<time>/ first, then merges file by file against what this folder last pulled: a file only one side changed takes that side; one both changed takes the saved version and is listed in conflicts",
+      "On a first pull (nothing remembered), the saved code wins every difference, and of the files it lacks only agent/actions/, agent/api/ and agent/views/ go back",
+      "agent/runtime/ is the build's: differences there are never conflicts",
+    ],
+    next: [
+      "check with pull: read agent/ at each ref into its into folder (repo_read tree and file), then npx foldspace sync apply",
+      "check up to date: save as repo_read command instructions says, with base_sha = baseSha",
+      "apply: follow its next - conflicts mean putting this session's change back on top; then npm run build",
+      "After each save: npx foldspace sync saved with the commit_sha and committed_paths it returned",
+    ],
+  }),
   Object.freeze({
     name: "build",
     entry: "build-cli.mjs",
@@ -326,6 +371,7 @@ export const CLI_COMMANDS = Object.freeze([
     ],
     options: [
       value("--click", "label", "screen: reach the screen by a navigation label, as a person would"),
+      flag("--human-said-yes", "screen --click: the human said yes in chat to clicking this one plain button; a label that reads like an action is still refused"),
       value("--goto", "path", "screen: a path on this host, or a full https address on a host this project names"),
       value("--match", "words", "screen: rank the requests seen by these words"),
       value("--wait", "ms", "screen/auth: how long to keep listening"),
@@ -577,6 +623,7 @@ export const CLI_COMMANDS = Object.freeze([
 export const CAPABILITY_CATALOGUE = Object.freeze([
   ["project.scaffold", "Create a new configured project on local disk"],
   ["project.upgrade", "Update the harness version the consuming project uses"],
+  ["project.sync", "Merge the agent's saved code, read with the Foldspace tools, into agent/"],
   ["artifact.build", "Build the portable dist/index.js action artifact"],
   ["browser.launch", "Launch an isolated local Chrome profile"],
   ["browser.cdp", "Connect to local Chrome through CDP"],
@@ -656,9 +703,10 @@ export function createCliRegistry({ packageName, packageVersion, env = process.e
       "The harness bin alias is equivalent to foldspace.",
       "attach diagnostics are attach-internal; interpret them from the lifecycle log, not as CLI commands.",
       "Coding agents run attach --daemon; foreground attach is for someone watching the terminal.",
-      "If update.outdated is true, ask the human before npx foldspace upgrade --yes.",
-      "If update.broken is true, this version was withdrawn and build and attach refuse to run. Ask the human to agree to the upgrade; set FOLDSPACE_SKIP_UPDATE_CHECK=1 only if they decline.",
+      "If update.autoUpgrade is true (a newer version in the same line), run npx foldspace upgrade --yes without asking and tell the human in one plain line; if update.outdated is true across a line, ask the human first.",
+      "If update.broken is true, this version was withdrawn and build and attach refuse to run. Within the same line, upgrade without asking; across a line, ask the human to agree to the upgrade, and set FOLDSPACE_SKIP_UPDATE_CHECK=1 only if they decline.",
       "observe looks at the app, and ask tests the agent through its panel; both work while attach runs.",
+      "With a code project, pull the saved code with `npx foldspace sync` at session start, before each new experience and before each save or publish (manual: \"Several builders, one agent\"); saving and publishing follow repo_read command instructions.",
       "`foldspace deploy` is for Foldspace staff only: never run or offer it - it is not the `deploy` tool. With a code project, putting the agent's code in front of their users is yours, as the manual's \"Done, and what you say at the end\" says: save with `repo_write`; publish to dev with the `deploy` tool (say you are doing it, then do it - unless its dev preview comes back with no warnings, which means this agent loads dev for its users: then ask first, as for production); check dev with `npx foldspace attach --stop`, `npx foldspace published dev` and `npx foldspace ask \"<question>\" --retry 2`; and publish to production only once that check passed and the human says yes. The dev check and production need a site that loads the agent by itself: after `attach --bootstrap` or `--replace`, publish to dev only, keep attach running, and the rest is a step the Foldspace team does with the human. If `published` says this window cannot show dev, say so in one sentence, attach again, and stop after dev. Without a code project, or when a Foldspace tool refuses (except a save refused because someone saved after you read: redo it as `repo_read` command `instructions` says), the Foldspace team does it with the human (https://foldspace.ai/demo, support@foldspace.ai).",
     ],
   };