@foldspace_npm/harness 0.1.20 → 0.1.22

package/CLAUDE.md

@@ -13,7 +13,11 @@ something they can **see on their own page** — not at "it builds".
    `npx --yes @foldspace_npm/harness@latest upgrade --check`). If
    `update.outdated` is true, say the pinned and latest versions and **ask
    before upgrading**; then `foldspace upgrade --yes` and `npm run build`. Never
-   upgrade as a side effect of build, attach or implementing an action. If the
+   upgrade as a side effect of build, attach or implementing an action.
+   `build` and `attach` check too: behind prints one line and carries on; a
+   version Foldspace **withdrew** refuses to run and says why. Tell the user
+   the reason and ask to upgrade. Only if they decide not to, rerun with
+   `FOLDSPACE_SKIP_UPDATE_CHECK=1` - never set it on your own. If the
    project `CLAUDE.md` does not contain
    `@node_modules/@foldspace_npm/harness/CLAUDE.md`, ask before
    `foldspace upgrade --refresh-instructions`.
@@ -77,8 +81,9 @@ at the app or testing in it, run `npx foldspace badge working` (a bar across
 the top of the window says Foldspace is building here, leave it alone) and say
 so in chat: *"I'm going to work in that Chrome window for a few minutes -
 please leave it alone until I tell you it's ready."* When it is their turn,
-`npx foldspace badge ready --text "<the question this experience answers>"` -
-the bar adds "Try asking:" and a Copy button itself - and say the same in chat. `foldspace badge label` puts the small
+`npx foldspace badge ready` takes the pill away (the small corner tag comes
+back) and in chat you say what to try. No bar for their turn: they may type
+whatever, whenever; the pill only ever asks them to wait. `foldspace badge label` puts the small
 corner tag back; `off` removes it, for a screenshot they will share.
 
 Navigation, uploads, extraction and anything that writes are a later session.

package/README.md

@@ -151,6 +151,55 @@ foldspace upgrade --yes   # only after the user agrees
 `--yes` rewrites the exact pin and runs `npm install --ignore-scripts`. Rebuild
 afterward; that is still not a deploy.
 
+`foldspace build` and `foldspace attach` run the same check before they start
+(`attach --status` and `--stop` do not). A project that is behind gets one line
+on stderr and carries on. A project on a **withdrawn** version (below) refuses
+to run and prints the reason. To build on it anyway, once the user has declined
+the upgrade:
+
+```bash
+FOLDSPACE_SKIP_UPDATE_CHECK=1 npm run build
+```
+
+That turns the check off entirely; it does not fix the withdrawn version.
+
+### Withdrawing a release (maintainers)
+
+When a published version is broken badly enough that nobody should build on
+it, withdraw it with `npm deprecate`. The registry is the list of withdrawn
+versions, so projects already installed on it see the withdrawal without
+installing anything new. Only owners of `@foldspace_npm/harness` on npm can
+run it.
+
+1. **Publish the fix first.** If the withdrawn version is also `latest`, the
+   message tells users to upgrade to a version that is itself withdrawn.
+2. **Withdraw the broken version**, with a message that says what is wrong and
+   which version to move to. That message is exactly what users, and the coding
+   agent working for them, see when `build` or `attach` refuses to run:
+
+   ```bash
+   npm deprecate @foldspace_npm/harness@0.1.14 "attach loads the wrong bundle; upgrade to 0.1.15"
+   ```
+
+   A range works too: `npm deprecate "@foldspace_npm/harness@<0.1.15" "…"`.
+3. **Check it took:**
+
+   ```bash
+   npm view @foldspace_npm/harness@0.1.14 deprecated
+   ```
+
+To undo a withdrawal, deprecate with an empty message:
+
+```bash
+npm deprecate @foldspace_npm/harness@0.1.14 ""
+```
+
+**It is not instant.** Each project caches the registry's answer for 12 hours
+in `.foldspace-dev/harness-update.json`. A project that checked recently keeps
+its "fine" answer until that expires, so a withdrawal reaches every project
+within 12 hours. It only reaches projects on a harness version that has this
+check.
+
 ### Lint handlers before they ship
 
 `foldspace build` runs `foldspace lint` first. Errors skip bundling; warnings

package/bin/attach.mjs

@@ -225,7 +225,8 @@ const SDK_PATTERNS = [
 //   label   - the small corner tag (default): who is attached, which mode
 //   working - a pill at the foot of the window: the agent is building in this
 //             window, please leave it alone
-//   ready   - the same pill: it is the human's turn, with the question to try
+//   ready   - the pill goes away and the small tag comes back: their turn.
+//             No bar for that - they may type whatever, whenever
 // The pill sits bottom-left, never across the top: a bar there covered the
 // app's own header and menu (seen on a CRM, 2026-09-22). The agent's panel
 // is on the right, so bottom-left is the corner nothing else uses.
@@ -252,34 +253,18 @@ const badgeSrc = `(() => {
     if (s.state === "working") {
       // Attention, not decoration: a pulsing marker, the ask in bold, and an
       // animated line underneath so it reads as "in progress" at a glance.
-      b.style.cssText = base + "top:auto;bottom:16px;left:16px;right:auto;max-width:min(560px,calc(100vw - 32px));border-radius:8px;overflow:hidden;background:#1F2A8A;padding:10px 14px 13px;font-size:13px;letter-spacing:.02em;text-align:left;line-height:1.3;";
+      b.style.cssText = base + "top:auto;bottom:16px;left:16px;right:auto;max-width:min(560px,calc(100vw - 32px));border-radius:8px;overflow:hidden;background:#3247F2;padding:10px 14px 13px;font-size:13px;letter-spacing:.02em;text-align:left;line-height:1.3;";
       b.innerHTML =
         '<style>@keyframes fsPulse{0%,100%{opacity:1}50%{opacity:.25}}@keyframes fsSweep{0%{left:-30%}100%{left:100%}}' +
-        '#foldspace-dev-badge .fs-dot{display:inline-block;width:10px;height:10px;border-radius:50%;background:#FFB300;margin-right:10px;vertical-align:middle;animation:fsPulse 1s ease-in-out infinite}' +
+        '#foldspace-dev-badge .fs-dot{display:inline-block;width:10px;height:10px;border-radius:50%;background:#FFD314;margin-right:10px;vertical-align:middle;animation:fsPulse 1s ease-in-out infinite}' +
         '#foldspace-dev-badge .fs-line{position:absolute;left:0;right:0;bottom:0;height:3px;background:rgba(255,255,255,.15);overflow:hidden}' +
-        '#foldspace-dev-badge .fs-line::after{content:"";position:absolute;top:0;width:30%;height:100%;background:#FFB300;animation:fsSweep 1.4s linear infinite}</style>' +
-        '<span class="fs-dot"></span>Foldspace is building your agent on this page. <b style="color:#FFD54F">Please leave this window alone</b> until Claude says it is ready.' +
+        '#foldspace-dev-badge .fs-line::after{content:"";position:absolute;top:0;width:30%;height:100%;background:#FFD314;animation:fsSweep 1.4s linear infinite}</style>' +
+        '<span class="fs-dot"></span>Foldspace is building your agent on this page. <b style="color:#FFD314">Please leave this window alone</b> until the agent says it is ready.' +
         (s.text ? " " + s.text.replace(/[<>&]/g, (c) => ({ "<": "&lt;", ">": "&gt;", "&": "&amp;" })[c]) : "") +
         '<span class="fs-line"></span>';
-    } else if (s.state === "ready") {
-      // Calm, and useful: the question to try, with a Copy button so nobody
-      // retypes it into the panel. The bar accepts clicks only on that button.
-      const esc = (t) => String(t).replace(/[<>&"]/g, (c) => ({ "<": "&lt;", ">": "&gt;", "&": "&amp;", '"': "&quot;" })[c]);
-      const question = s.text ? esc(s.text) : "";
-      b.style.cssText = base + "top:auto;bottom:16px;left:16px;right:auto;max-width:min(560px,calc(100vw - 32px));border-radius:8px;overflow:hidden;background:#0F9D58;padding:10px 14px;font-size:13px;letter-spacing:.02em;text-align:left;line-height:1.3;pointer-events:none;";
-      b.innerHTML =
-        '<style>#foldspace-dev-badge .fs-copy{pointer-events:auto;margin-left:12px;padding:4px 10px;border:1px solid rgba(255,255,255,.7);border-radius:4px;background:transparent;color:#fff;font:inherit;font-size:12px;cursor:pointer;letter-spacing:0}' +
-        '#foldspace-dev-badge .fs-copy:hover{background:rgba(255,255,255,.15)}</style>' +
-        '<b>Ready - your turn.</b> ' +
-        (question ? 'Try asking: <span class="fs-q">' + question + '</span><button class="fs-copy" type="button">Copy</button>' : "Open your agent and try it.");
-      const btn = b.querySelector(".fs-copy");
-      if (btn) btn.addEventListener("click", () => {
-        const q = b.querySelector(".fs-q")?.textContent || "";
-        const done = () => { btn.textContent = "Copied"; setTimeout(() => { btn.textContent = "Copy"; }, 1500); };
-        if (navigator.clipboard?.writeText) navigator.clipboard.writeText(q).then(done, done);
-        else { const ta = document.createElement("textarea"); ta.value = q; document.body.appendChild(ta); ta.select(); try { document.execCommand("copy"); } catch (e) {} ta.remove(); done(); }
-      });
     } else {
+      // "ready" and "label" both draw the small tag: their turn needs no bar -
+      // they may type whatever, whenever. Only the wait ever gets a pill.
       b.style.cssText = base + "background:#3247F2;padding:5px 10px;border-bottom-right-radius:4px;";
       b.textContent = LABEL;
     }

package/bin/badge.mjs

@@ -2,14 +2,14 @@
 /**
  * foldspace badge <working|ready|label|off> [--text "<what to show>"]
  *
- * Sets the banner the attach badge draws across the top of the test window.
- * The agent and the human share that one Chrome window, so the banner says
- * whose turn it is:
+ * Sets the pill the attach badge draws at the foot of the test window.
+ * The agent and the human share that one Chrome window, so the pill says
+ * when to wait:
  *   working - "Foldspace is building your agent on this page. Please leave
- *             this window alone until Claude says it is ready."
- *   ready   - "Ready - your turn. Open your agent and try it." (pass --text
- *             with the question to try)
- *   label   - back to the small corner tag
+ *             this window alone until the agent says it is ready."
+ *   ready   - the pill goes away, the small corner tag comes back: their
+ *             turn. No bar for that - they may type whatever, whenever.
+ *   label   - the small corner tag
  *   off     - remove it
  * The state is kept in the page's sessionStorage, so it survives navigation;
  * attach's badge script redraws within a second. Nothing else on the page is

package/bin/cli.mjs

@@ -7,6 +7,7 @@ import { fileURLToPath } from "node:url";
 import { runInit } from "../src/init.mjs";
 import {
   checkForUpdate,
+  gateForCommand,
   nagIfOutdated,
   resolveProjectDir,
   runUpgrade,
@@ -54,6 +55,18 @@ function runScript(scriptName, args) {
   });
 }
 
+// build and attach are where a stale or withdrawn harness does its damage, so
+// they check before running. Returns false when the command must not run.
+function passesVersionGate() {
+  const gate = gateForCommand(checkForUpdate(resolveProjectDir())) || {};
+  if (gate.message) console.error(`foldspace: ${gate.message}`);
+  if (gate.block) {
+    process.exitCode = 1;
+    return false;
+  }
+  return true;
+}
+
 function printHelp(topic, json) {
   const document = helpDocument(registry, topic);
   if (!document) {
@@ -184,8 +197,14 @@ if (!command || command === "--help" || command === "-h") {
     try {
       const definition = commandByName(command);
       const normalized = normalizeCommandArgs(definition, args);
-      if (command === "attach") {
-        const control = classifyAttachControl(normalized);
+      const control =
+        command === "attach" ? classifyAttachControl(normalized) : null;
+      const gated =
+        command === "build" ||
+        (command === "attach" && (!control || control === "daemon"));
+      if (gated && !passesVersionGate()) {
+        // gate already reported why
+      } else if (command === "attach") {
         if (control) {
           Promise.resolve()
             .then(() =>

package/package.json

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

package/src/badge-core.mjs

@@ -10,8 +10,8 @@ export function badgePayload(state, text) {
   }
   const payload = { state: wanted };
   if (text !== undefined) {
-    if (wanted !== "working" && wanted !== "ready") {
-      throw new Error(`--text only applies to working or ready (got ${wanted}).`);
+    if (wanted !== "working") {
+      throw new Error(`--text only applies to working (got ${wanted}); their turn needs no bar.`);
     }
     const clean = String(text).replace(/\s+/g, " ").trim();
     if (!clean) throw new Error("--text is empty.");

package/src/cli-registry.mjs

@@ -112,12 +112,13 @@ export const CLI_COMMANDS = Object.freeze([
     usage: "foldspace build [--watch]",
     risk: "local-write",
     environment: "node",
-    environmentVariables: ["FOLDSPACE_PROJECT_DIR"],
+    environmentVariables: ["FOLDSPACE_PROJECT_DIR", "FOLDSPACE_SKIP_UPDATE_CHECK"],
     capabilities: ["artifact.build"],
     positionals: [],
     options: [flag("--watch", "Rebuild when action source changes")],
     prerequisites: ["agent/actions/index.ts"],
     effects: [
+      "Checks the harness version first: behind prints one line, a withdrawn version refuses to run (FOLDSPACE_SKIP_UPDATE_CHECK=1 skips the check)",
       "Runs foldspace lint first; errors skip bundling",
       "Writes dist/index.js when lint has no errors",
     ],
@@ -201,6 +202,7 @@ export const CLI_COMMANDS = Object.freeze([
       "FOLDSPACE_PROJECT_DIR",
       "CDP_PORT",
       "AGENT_API_NAME",
+      "FOLDSPACE_SKIP_UPDATE_CHECK",
     ],
     capabilities: [
       "browser.cdp",
@@ -260,6 +262,7 @@ export const CLI_COMMANDS = Object.freeze([
       "sdkUrl in foldspace.dev.json when using --bootstrap",
     ],
     effects: [
+      "Checks the harness version first, except --status and --stop: behind prints one line, a withdrawn version refuses to run (FOLDSPACE_SKIP_UPDATE_CHECK=1 skips the check)",
       "May reload and instrument matching target pages",
       "Refuses a Chrome that is not the profile inject launched",
       "Test mode is off unless --test-mode is passed: conversations appear in the dashboard",
@@ -321,7 +324,7 @@ export const CLI_COMMANDS = Object.freeze([
     name: "badge",
     entry: "badge.mjs",
     group: "verify",
-    summary: "Set the banner across the top of the test window: working, ready, label or off",
+    summary: "Set the pill at the foot of the test window: working (leave it alone), ready (pill away), label or off",
     usage: 'foldspace badge <working|ready|label|off> [--text "<what to show>"]',
     risk: "browser-session",
     environment: "local-chrome",
@@ -332,18 +335,18 @@ export const CLI_COMMANDS = Object.freeze([
         name: "state",
         required: true,
         description:
-          "working: the agent is building here, leave the window alone | ready: the human's turn | label: the small corner tag | off: remove it",
+          "working: the agent is building here, leave the window alone | ready: the pill goes away, their turn | label: the small corner tag | off: remove it",
       }),
     ],
     options: [
-      value("--text", "text", "working/ready: the line to show, e.g. the question to try (one line, up to 160 characters)"),
+      value("--text", "text", "working only: one extra line under the ask (up to 160 characters)"),
     ],
     prerequisites: ["foldspace attach is running (it draws the badge)"],
     effects: [
       "Writes one key to the test window's sessionStorage; touches nothing else on the page",
-      "The banner survives navigation inside the test window",
+      "The pill survives navigation inside the test window",
     ],
-    next: ["Tell the human in chat what the banner says"],
+    next: ["Say in chat whose turn it is and what to try"],
   }),
   Object.freeze({
     name: "deploy",
@@ -464,6 +467,7 @@ export function createCliRegistry({ packageName, packageVersion, env = process.e
       "attach diagnostics are attach-internal; interpret them from the lifecycle log, not as CLI commands.",
       "Coding agents should run attach --daemon; foreground attach is for humans watching the terminal.",
       "If update.outdated is true, ask the user before foldspace upgrade --yes.",
+      "If update.broken is true, this version was withdrawn and build and attach refuse to run. Ask the user to upgrade; set FOLDSPACE_SKIP_UPDATE_CHECK=1 only if they decline.",
       "observe, ask and run are read-only second clients on the test window and work while attach runs.",
       "There is no customer-run publication step: putting actions in front of end users is done with Foldspace's team.",
     ],

package/src/upgrade.mjs

@@ -227,10 +227,10 @@ function readCache(projectDir, now) {
   }
 }
 
-function writeCache(projectDir, latest, now) {
+function writeCache(projectDir, entry, now) {
   const dir = path.dirname(cachePath(projectDir));
   fs.mkdirSync(dir, { recursive: true });
-  writeJson(cachePath(projectDir), { checkedAt: now, latest });
+  writeJson(cachePath(projectDir), { checkedAt: now, ...entry });
 }
 
 export function fetchLatestFromNpm(options = {}) {
@@ -244,7 +244,27 @@ export function fetchLatestFromNpm(options = {}) {
   return normalizeVersion(result.stdout);
 }
 
+/**
+ * A version we have withdrawn is marked with `npm deprecate`, so the registry
+ * is the list of known-broken versions and an old install can still read it.
+ * Returns the deprecation message, "" when the version is not deprecated, or
+ * null when the registry could not be asked.
+ */
+export function fetchDeprecationFromNpm(version, options = {}) {
+  const spawn = options.spawnSyncFn || spawnSync;
+  const result = spawn("npm", ["view", `${HARNESS_PACKAGE}@${version}`, "deprecated"], {
+    encoding: "utf8",
+    timeout: options.timeoutMs ?? NPM_VIEW_TIMEOUT_MS,
+    env: options.env || process.env,
+  });
+  if (result.error || result.status !== 0) return null;
+  return String(result.stdout || "").trim();
+}
+
 function nextAction(report) {
+  if (report.broken) {
+    return `This harness version was withdrawn: ${report.deprecated}. ${UPGRADE_NEXT}`;
+  }
   if (report.status === "outdated") {
     return report.instructionsImport === false
       ? `${UPGRADE_NEXT}. If CLAUDE.md is still a snapshot, also pass --refresh-instructions`
@@ -275,7 +295,11 @@ export function checkForUpdate(projectDir, options = {}) {
     (options.skipCheck !== false && env.FOLDSPACE_SKIP_UPDATE_CHECK === "1");
   const consumer = !harnessSource && Boolean(pinned || installed);
 
+  // The version that actually runs is the installed one; the pin is a fallback
+  // for a project that has not been installed yet.
+  const running = installed || pinned;
   let latest = null;
+  let deprecated = null;
   let status = "current";
 
   if (!consumer) {
@@ -284,16 +308,30 @@ export function checkForUpdate(projectDir, options = {}) {
     status = "check_skipped";
   } else {
     const cached = options.cache === false ? null : readCache(projectDir, now);
-    if (cached?.latest) {
+    const cachedDeprecation =
+      cached?.deprecation?.version === running ? cached.deprecation : null;
+    if (cached?.latest && cachedDeprecation) {
       latest = cached.latest;
+      deprecated = cachedDeprecation.message || null;
     } else {
       const fetched =
         typeof options.fetchLatest === "function"
           ? options.fetchLatest()
           : fetchLatestFromNpm(options);
       latest = normalizeVersion(fetched);
+      const message =
+        typeof options.fetchDeprecation === "function"
+          ? options.fetchDeprecation(running)
+          : fetchDeprecationFromNpm(running, options);
+      deprecated = message || null;
       if (latest && options.cache !== false) {
-        writeCache(projectDir, latest, now);
+        const entry = { latest };
+        // Only cache an answer the registry actually gave, so an offline
+        // run is asked again next time instead of remembered as "fine".
+        if (typeof message === "string") {
+          entry.deprecation = { version: running, message };
+        }
+        writeCache(projectDir, entry, now);
       }
     }
     if (!latest) {
@@ -311,6 +349,8 @@ export function checkForUpdate(projectDir, options = {}) {
     installed,
     latest,
     outdated: status === "outdated",
+    deprecated,
+    broken: Boolean(deprecated),
     status,
     instructionsImport,
     next: null,
@@ -319,6 +359,33 @@ export function checkForUpdate(projectDir, options = {}) {
   return report;
 }
 
+/**
+ * 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 user's decision (CLAUDE.md, step 1).
+ * The escape hatch is FOLDSPACE_SKIP_UPDATE_CHECK=1: the report comes back
+ * check_skipped, so nothing here blocks.
+ */
+export function gateForCommand(report) {
+  // A check that could not run never stops a build.
+  if (!report) return { block: false, message: null };
+  if (report.broken) {
+    return {
+      block: true,
+      message:
+        `${HARNESS_PACKAGE} ${report.installed || report.pinned} was withdrawn: ${report.deprecated}. ` +
+        `${UPGRADE_NEXT}. If the user declines, rerun with FOLDSPACE_SKIP_UPDATE_CHECK=1 to build on this version anyway.`,
+    };
+  }
+  if (report.outdated) {
+    return {
+      block: false,
+      message: `${HARNESS_PACKAGE} ${report.installed || report.pinned} is behind ${report.latest}. ${UPGRADE_NEXT}.`,
+    };
+  }
+  return { block: false, message: null };
+}
+
 export function writeExactPin(projectDir, version) {
   const manifestPath = path.join(projectDir, "package.json");
   const manifest = readPackageManifest(projectDir);

package/templates/agent-starter/docs/app-profile.md

@@ -14,8 +14,10 @@ How to re-run any probe below:
 
 ```bash
 npm run inject
-# Sign in. Capture from chrome-devtools MCP, or a page-context fetch,
-# before foldspace attach owns the debug port.
+# Sign in, then read the running app with foldspace observe. It reads the
+# window you signed in to, and works while foldspace attach runs.
+npx foldspace observe screen --click "<a label from observe menu>" --match "<words for the data>"
+npx foldspace observe read "<the GET path screen returned>"
 ```
 
 Start URL: `{{START_URL}}`