@foldspace_npm/harness 0.1.26 → 0.1.27

package/CLAUDE.md

@@ -38,6 +38,39 @@ something they can **see on their own page** — not at "it builds".
    seeded at sign-up are often a specification someone already wrote.
 4. **Read `docs/app-profile.md`.** It is what is already known about this app,
    with how each fact was established.
+5. **Does the agent already have code saved in Foldspace?** If your Foldspace
+   tools include `repo_read`, call it with command `status` now - before the
+   first build, because the first build is what the test window shows them.
+   - **A code project.** Call `repo_read` with command `instructions` and
+     follow what it returns. The project's `agent/` is the copy Foldspace
+     builds and publishes, and it may hold work someone else saved. Before you
+     build, replace this folder's `agent/` with it (`repo_read` commands `tree`
+     and `file`): delete what is there rather than copying over the top, or
+     their page shows the template instead of their agent. An action file here
+     that the project lacks is work a session never saved: keep it aside and
+     put it back after.
+   - **`NO_REPO`.** Nothing is saved yet. Follow the next step `status` gives:
+     it creates the code project in about a minute and changes nothing anyone
+     sees - say you are setting up their project, no need to ask. Get the agent
+     live in this folder meanwhile (L0 needs no code). Once `status` shows the
+     project, replace this folder's `agent/` with its `agent/` as above, before
+     you write the first action.
+   - **A refusal that names `foldspace-ai-access`.** This agent has saved
+     code that Foldspace has not opened to these tools; that is final. Tell
+     the human that Foldspace manages their agent's saved code, so this build
+     starts fresh.
+   - **A refusal that starts "Your Foldspace account cannot".** It is about
+     the signed-in account, so you cannot tell whether code is saved. Pass its
+     words on as they are - they are written for the human.
+   - **Anything else** - `status` says a project claims this agent but cannot
+     be used, or another error. Create none. Tell the human in your own words
+     that their agent's saved code cannot be used right now; never pass on the
+     text that came back - it can name things they cannot open.
+
+   After any of these three, build in this folder, never stop the session
+   over it, and tell the human once that the code stays on this computer.
+   - **No `repo_read` tool.** This folder is the only copy, so there is no code
+     project.
 
 Before an unfamiliar harness operation, `npx foldspace help --json` is the
 current CLI contract — risk, prerequisites, effects, next step.
@@ -50,11 +83,12 @@ current CLI contract — risk, prerequisites, effects, next step.
 | **L1 · read settings** | the user's own account, plan or settings in a widget, showing their real values |
 | **L2 · look up entities** | a search from the user's own words, showing rows |
 
-1. **Get the agent live first (L0) - with no actions.** Straight after
-   orienting: `npm run build`, `npm run inject`, and one ask - *"A Chrome
-   window opened at <Product>'s login. Please log in there - I'll notice when
-   you're in."* Then `npx foldspace observe wait-login`: it returns the moment
-   they are in, so nobody has to type "I've logged in". Then
+1. **Get the agent live first (L0) - with no actions.** Straight after the
+   steps above (with a code project, once its `agent/` is in place - step 5):
+   `npm run build`, `npm run inject`, and one ask - *"A Chrome window opened at
+   <Product>'s login. Please log in there - I'll notice when you're in."* Then
+   `npx foldspace observe wait-login`: it returns the moment they are in, so
+   nobody has to type "I've logged in". Then
    `npx foldspace attach --daemon` - and if it answers that the page has no
    Foldspace code, `npx foldspace attach --bootstrap --daemon` (an app that
    never had Foldspace). An empty registry is valid. L0 is
@@ -311,7 +345,8 @@ SDK without the configured agent.
 read `npx foldspace help attach --json` and map `missingActionNames`,
 `unexpectedActionNames`, `diagnosticError`. A running attach keeps the actions
 it loaded: after a rebuild, `attach --stop` and attach again to load the new
-ones. That is the only reason to stop it.
+ones. That, and checking published code on dev (**Done, and what you say at
+the end**), are the only reasons to stop it.
 
 Prove a named action through the visible agent: after the human talks to the
 copilot, read the daemon log for `[actions]` SDK callback and local
@@ -324,7 +359,44 @@ A first session is done when the customer has seen one experience answer from
 their own data, in the test window, and been invited to try it. Not when the
 gates pass, and not when there is nothing left to improve.
 
-If they ask *"how do I put this in front of my users?"*, the honest answer is:
+**With a code project** (step 5 found or created one), putting it in front of
+their users is yours to do. Once they have tried it in the test window, before
+you offer the second wave:
+
+1. Say *"I'm saving your changes and publishing them to dev"* - no need to
+   ask - then save with `repo_write` and publish with the `deploy` tool, the
+   way `repo_read` command `instructions` says. One exception: a dev preview
+   that comes back with no warnings means this agent loads dev for its users -
+   then ask first, as for production. In chat it is "saving your changes",
+   "publishing to dev" and "publishing for your users" - never GitHub,
+   branches, commits or tool names.
+2. Check dev yourself. Say in chat that you are checking it in that window
+   and to leave it alone until you say it is ready: with attach stopped the
+   page draws no pill. Then `npx foldspace attach --stop` (while attach runs,
+   the page serves your local build), `npx foldspace published dev`, and
+   `npx foldspace ask "<the question>" --retry 2`. Without attach, `ask`
+   cannot see `execute` and `render`: the reply, the card text and the
+   screenshot are the proof - look at the screenshot. If it fails, go no
+   further: attach again, fix it here, then save, publish to dev and check
+   again. If it works, invite them to try it in that window (a reload takes
+   it off dev), and run `npx foldspace attach --daemon` before you build
+   anything else. If `published` says this window cannot show dev, say so in
+   one sentence, attach again, and stop at step 1.
+3. Once the dev check passed, ask before publishing for their users:
+   *"Shall I publish it for your users?"* On a yes, publish to production. On a not yet, it stays on dev:
+   say so in one line and carry on.
+
+Steps 2 and 3 need a site that loads this agent by itself. If you attached
+with `--bootstrap` or `--replace`, it does not yet: do step 1, keep attach
+running, and give the answer below for the rest - their site loading the agent
+is the step the Foldspace team does with them.
+
+A save refused because someone saved after you read is not final: the
+instructions say how to redo it. Any other refusal from the Foldspace tools
+here is final: then the answer below.
+
+**Without a code project**, the answer to *"how do I put this in front of my
+users?"* is:
 
 > What you've seen runs in a test window on your machine. Putting it in front
 > of your users is a separate step, and the Foldspace team does it with you.
@@ -332,8 +404,9 @@ If they ask *"how do I put this in front of my users?"*, the honest answer is:
 > <support@foldspace.ai>. Everything built today carries over: the actions are
 > already in your Foldspace account, and the code is in this folder.
 
-Never run `foldspace deploy`, never install cloud tooling, never ask them for
-cloud credentials: `deploy` is Foldspace-internal and no customer can run it.
+Never run `npx foldspace deploy` - that command is for Foldspace staff only,
+and it is not the `deploy` tool you publish a code project with. Never install
+cloud tooling, and never ask them for cloud credentials.
 
 ## Verification gates
 
@@ -395,7 +468,9 @@ Do not report success without all six:
    --test-mode` keeps your conversations out of their data. It is not a safety
    net: publishing still changes the live agent. Working on an agent in
    production - test mode, pinned action versions, what may be published - is
-   a separate playbook, not this one.
+   a separate playbook, not this one. Publishing its code with the `deploy`
+   tool is the exception: it takes the same dev-then-production path as a new
+   agent (**Done, and what you say at the end**).
 6. **The human is not necessarily a developer.** Never hand over a terminal
    line, a stack trace, or a choice between flags. Name experiences by outcome
    — *"show my plan and credits"*, not `get_account_status`. Their two jobs:
@@ -571,13 +646,20 @@ building is not the session at run time: **expect `signed_out`** and let
 `renderFailure` show it. `not_found` and zero rows are both `renderEmpty` with
 the query named — never an error, never a blank card.
 
-If the observed auth is not Bearer + `localStorage`/`cookie`, stop re-exporting
-that one function and keep the rest:
-
-```ts
-export { getAgent, rankBy, renderEmpty } from "@foldspace_npm/harness/runtime";
-export { apiFetch } from "./api";
-```
+If the observed auth is not Bearer + `localStorage`/`cookie`, copy
+`node_modules/@foldspace_npm/harness/recipes/swap-the-login-method/agent/utils.ts`
+over `agent/utils.ts` - or, when the browser's own cookies carry the sign-in and
+there is no token, that recipe's `variants/utils.cookies.ts` - and set what its
+README's **Adapt it** table lists to what you observed.
+
+**If `agent/` came from a code project** (step 5), nothing in it may import a
+package: Foldspace builds the published bundle with no `node_modules`, so a
+package import passes every gate in this manual and then fails on publish.
+Import the helpers the way the project's own `agent/utils.ts` does - from
+`./runtime` - in a recipe file you copy too. A project with an `agent/utils/`
+folder has its own helpers instead: change the sign-in there, and never add an
+`agent/utils.ts` beside it, which would win the import. Without a code project,
+the package import is right.
 
 ## Safety
 
@@ -597,5 +679,8 @@ export { apiFetch } from "./api";
 - Do not commit secrets, cookies, HAR files, browser storage, or
   `.foldspace-dev/`. Nothing transient goes in `docs/`.
 - Local handler changes are not cloud publication.
-- Creating or publishing Foldspace resources requires explicit approval.
+- Creating or publishing Foldspace resources needs the human's yes - except
+  the agent's code: creating its code project, saving to it and publishing it
+  to dev, unless the dev preview comes back with no warnings (this agent then
+  loads dev for its users). Say you are doing it, then do it.
 - Action keys and parameter names must match the published schema.

package/README.md

@@ -269,6 +269,36 @@ parameter values, results, and error messages are not. On detach, repeated page
 failures and bounded action observations are summarized. The observer and
 diagnostics are injected by the harness, so `dist/index.js` is not rewritten.
 
+### Check the published code
+
+After the `deploy` tool in the Foldspace tools - not `foldspace deploy`, which
+is for Foldspace staff only - publishes the code project to dev (or, with the
+human's yes, to production), check it in the same test window. This needs a
+site that loads this agent by itself: after `attach --bootstrap` or
+`--replace` there is nothing to check yet.
+
+```bash
+npx foldspace attach --stop          # while attach runs the page serves your local build
+npx foldspace published dev          # this page's agent now loads the published dev code
+npx foldspace ask "<the question>" --retry 2
+npx foldspace attach --daemon        # back to your local build before you build anything else
+```
+
+`published` refuses while attach runs. It also refuses unless the page's own
+Foldspace agent is this project's agent - the same product and Agent Key as
+`foldspace.dev.json`, checked the way attach checks it. It changes only this
+page's agent, through the SDK's `setConfiguration({ enableDebugLogs: true,
+remoteActionsSettings: { enabled: true, environment: "DEV" | "PROD" } })`; a
+reload puts the page back on what the agent loads normally. When code loads,
+the SDK keeps any handler the agent already has over a new one of the same
+name, so once the published code has loaded, its handlers are set over the
+page's for every action it defines; the page keeps its own handlers for the
+rest. An agent pinned to one version of its code, or loading code from its
+own address, is refused: the window would not show what was published last.
+Without attach, `ask` still reports the reply, the card text and a
+screenshot; `handler.execute` and `handler.render` read "not tracked here
+(published code)".
+
 ### Add the harness to an existing project
 
 ```bash

package/bin/ask.mjs

@@ -12,6 +12,12 @@
 // it opens the panel, types into the composer, presses Enter and reads the
 // screen. --retry re-asks when no action fired, which covers the platform
 // taking up to a minute to pick up a newly published action; lagMs is that cost.
+//
+// What the handlers did comes from the attach daemon's log. Without a daemon
+// (after `foldspace published`, the page runs published code) execute and
+// render read "not tracked here (published code)", so only a card shows that
+// an action fired: --retry re-asks whenever no card came back, even when an
+// action that draws no card ran.
 
 import fs from "node:fs";
 import path from "node:path";
@@ -23,8 +29,9 @@ import {
   shouldRetry,
   squash,
   summarizeHandlerLog,
+  untrackedHandler,
 } from "../src/ask-core.mjs";
-import { ATTACH_DAEMON_LOG_FILE } from "../src/attach-daemon.mjs";
+import { ATTACH_DAEMON_LOG_FILE, liveDaemon } from "../src/attach-daemon.mjs";
 import { CdpPage, parseArgs, printJson, sleep } from "../src/cdp-client.mjs";
 import { recordEvent } from "../src/session-events.mjs";
 import { withWorkingBadge } from "../src/badge-auto.mjs";
@@ -44,6 +51,7 @@ const outDir = flags.out
   ? path.resolve(projectDir, String(flags.out))
   : path.join(projectDir, ".foldspace-dev", "ask");
 const logFile = path.join(projectDir, ".foldspace-dev", ATTACH_DAEMON_LOG_FILE);
+const tracked = Boolean(liveDaemon(projectDir));
 
 let page = null;
 
@@ -223,7 +231,7 @@ async function askOnce() {
     reply: reply.slice(0, 2000),
     cards: seen.cards.map((card) => card.slice(0, 2000)),
     hasCard: seen.cards.length > 0 || seen.newCardFrames > 0,
-    handler: summarizeHandlerLog(logSince(logOffset)),
+    handler: tracked ? summarizeHandlerLog(logSince(logOffset)) : untrackedHandler(),
   };
 }
 

package/bin/attach.mjs

@@ -297,9 +297,11 @@ const badgeSrc = `(() => {
 // the real conversations untagged — the failure that actually leaks. Enumerate
 // foldspace.agentIds() — each id is shaped "<mode>-<apiName>" — and arm every
 // one. See the playbook's test-mode rule.
-const testModeSrc = `(() => {
+const testModeScript = (enable) => `(() => {
   if (window.top !== window.self) return;
   const AGENT = ${JSON.stringify(agentApiName)};
+  const WANT = ${enable};
+  const WORD = ${JSON.stringify(enable ? "ON" : "OFF")};
   // Log once per instance; setTestMode itself is re-applied on every pass so an
   // instance that is torn down and rebuilt gets re-armed.
   const logged = new Set();
@@ -316,10 +318,10 @@ const testModeSrc = `(() => {
     // Older SDK with no agentIds(): the unscoped handle is all there is.
     if (!ids) {
       try {
-        fs.agent({ apiName: AGENT }).setTestMode(true);
+        fs.agent({ apiName: AGENT }).setTestMode(WANT);
         if (!logged.has(AGENT)) {
           logged.add(AGENT);
-          console.log("[foldspace-dev] test mode ON (" + AGENT + " — SDK has no agentIds(), overlay handle only)");
+          console.log("[foldspace-dev] test mode " + WORD + " (" + AGENT + " — SDK has no agentIds(), overlay handle only)");
         }
       } catch (e) {
         console.warn("[foldspace-dev] setTestMode failed:", e && e.message);
@@ -332,10 +334,10 @@ const testModeSrc = `(() => {
       if (cut < 1) continue;
       try {
         fs.agent({ apiName: id.slice(cut + 1), mode: id.slice(0, cut).toUpperCase() })
-          .setTestMode(true);
+          .setTestMode(WANT);
         if (!logged.has(id)) {
           logged.add(id);
-          console.log("[foldspace-dev] test mode ON (" + id + ")");
+          console.log("[foldspace-dev] test mode " + WORD + " (" + id + ")");
         }
       } catch (e) {
         console.warn("[foldspace-dev] setTestMode failed for " + id + ":", e && e.message);
@@ -713,7 +715,11 @@ async function prepare(ws, sessionId, url) {
     const scripts = [];
     scripts.push(fs.readFileSync(bundlePath, "utf8"));
     if (!noBadge) scripts.push(badgeSrc);
-    if (!noTestMode) scripts.push(testModeSrc);
+    // Test mode is armed when --test-mode is set, and actively CLEARED otherwise:
+    // it is page-session state that only a reload or setTestMode(false) undoes,
+    // so a page left in test mode by an earlier attach would keep the striped
+    // banner under a LIVE badge until reload (seen on RoofSnap, 2026-09-30).
+    scripts.push(testModeScript(!noTestMode));
     if (bootstrap) {
       scripts.push(
         buildBootstrapScript({

package/bin/published.mjs

@@ -0,0 +1,141 @@
+#!/usr/bin/env node
+/**
+ * foldspace published <dev|prod>
+ *
+ * Points the test window's agent at the code published to dev or prod, so
+ * `foldspace ask` checks what the `deploy` tool published instead of the
+ * local build. Only this page's agent changes, in this test window; a reload
+ * puts the page back on what the agent loads normally. Nothing is published
+ * and nothing changes in Foldspace.
+ *
+ * Refuses while attach runs (the page then serves the local build), and on a
+ * page whose own Foldspace agent is not this project's agent - attach's swap
+ * preflight decides that, so both read the page the same way.
+ */
+import { liveDaemon } from "../src/attach-daemon.mjs";
+import { CdpPage, parseArgs, printJson, sleep } from "../src/cdp-client.mjs";
+import { withoutStealingFocus } from "../src/keep-focus.mjs";
+import { readProjectConfig, resolveConfiguredTarget } from "../src/project-config.mjs";
+import {
+  ATTACH_RUNNING,
+  FOREGROUND_ATTACH,
+  buildPageReadScript,
+  buildPublishedScript,
+  checkPublishedPage,
+  foregroundAttachNext,
+  LOAD_TIMEOUT_MS,
+  pageSettled,
+  projectAgent,
+  publishedEnvironment,
+  publishedReport,
+} from "../src/published-core.mjs";
+import { recordEvent } from "../src/session-events.mjs";
+import { resolveProjectDir } from "../src/upgrade.mjs";
+
+const PAGE_WAIT_MS = 20_000;
+const POLL_MS = 250;
+// A page younger than this may not have started loading what its agent loads
+// normally; once that load is in flight, pageSettled waits for it to land.
+const SETTLE_AGE_MS = 5_000;
+
+const projectDir = resolveProjectDir();
+const { flags, rest } = parseArgs(process.argv.slice(2));
+
+let environment;
+try {
+  const unknown = Object.keys(flags);
+  if (unknown.length) throw new Error(`unknown option '--${unknown[0]}'`);
+  if (rest.length > 1) throw new Error(`unexpected argument '${rest[1]}'`);
+  environment = publishedEnvironment(rest[0]);
+} catch (error) {
+  console.error(`published: ${error instanceof Error ? error.message : String(error)}`);
+  process.exit(1);
+}
+
+let page = null;
+
+function finish(result, code) {
+  recordEvent(projectDir, "published", { ok: result.ok, environment: environment.name });
+  printJson(result);
+  page?.close();
+  process.exit(code);
+}
+
+function configTarget(targetName) {
+  try {
+    return resolveConfiguredTarget(readProjectConfig(projectDir), targetName).target;
+  } catch {
+    return {};
+  }
+}
+
+/** Read the page until it has settled, or the wait runs out. */
+async function readPage(agent) {
+  const deadline = Date.now() + PAGE_WAIT_MS;
+  let last = null;
+  while (Date.now() < deadline) {
+    // A reload briefly destroys the page's context; read again.
+    last = await page.evaluate(buildPageReadScript(agent)).catch(() => last);
+    if (pageSettled(last) && (last.attachPrepared || last.ageMs >= SETTLE_AGE_MS)) break;
+    await sleep(POLL_MS);
+  }
+  return last;
+}
+
+async function main() {
+  // While the attach daemon runs it serves the local build to every page load,
+  // so whatever this command loads would be replaced on the next one.
+  if (liveDaemon(projectDir)) {
+    finish({ ok: false, environment: environment.name, reason: ATTACH_RUNNING }, 1);
+  }
+
+  page = await CdpPage.open({ projectDir });
+  const agent = projectAgent(page.info.target, configTarget(page.info.targetName));
+
+  let seen = await readPage(agent);
+  if (seen?.attachPrepared) {
+    // No daemon, yet this document still carries the local build: an attach
+    // that ended without cleaning up. A reload is what attach does to clean up.
+    await withoutStealingFocus(() => page.send("Page.reload", { ignoreCache: true }));
+    await sleep(1000);
+    seen = await readPage(agent);
+    if (seen?.attachPrepared) {
+      finish(
+        {
+          ok: false,
+          environment: environment.name,
+          reason: FOREGROUND_ATTACH,
+          next: foregroundAttachNext(environment.name),
+        },
+        1,
+      );
+    }
+  }
+
+  const check = checkPublishedPage({ state: seen?.state, agent });
+  if (!check.ok) {
+    finish(
+      {
+        ok: false,
+        environment: environment.name,
+        agent: agent.apiName,
+        reason: check.reason,
+        next: check.next,
+        page: check.page,
+        url: page.info.url,
+      },
+      1,
+    );
+  }
+
+  const outcome = await page.evaluate(
+    buildPublishedScript({ apiName: agent.apiName, mode: check.mode, environment }),
+    { timeoutMs: LOAD_TIMEOUT_MS + 15_000 },
+  );
+  const report = publishedReport({ outcome, environment, agent });
+  finish(report, report.ok ? 0 : 1);
+}
+
+main().catch((error) => {
+  finish({ ok: false, environment: environment.name, error: String(error?.message || error) }, 1);
+});

package/package.json

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

package/src/ask-core.mjs

@@ -109,8 +109,20 @@ export function summarizeHandlerLog(logText) {
   };
 }
 
+// execute/render come from the log the attach daemon writes. With no daemon
+// running - the page runs published code, see `foldspace published` - there is
+// no log to read, so they are reported as not tracked rather than as absent.
+export const NOT_TRACKED = "not tracked here (published code)";
+
+export function untrackedHandler() {
+  return { execute: NOT_TRACKED, render: NOT_TRACKED, actions: [], lines: [] };
+}
+
+// Without the log only a card counts: an action that answers with data and
+// draws no card reads as not fired, and --retry asks again.
 export function actionFired(handler, hasCard) {
-  return Boolean(hasCard) || handler?.execute !== "absent" || handler?.render !== "absent";
+  const ran = (status) => status !== "absent" && status !== NOT_TRACKED;
+  return Boolean(hasCard) || ran(handler?.execute) || ran(handler?.render);
 }
 
 /**

package/src/cdp-client.mjs

@@ -33,6 +33,7 @@ export function readLaunchState(projectDir = resolveProjectDir()) {
     projectDir,
     port: String(port),
     hosts,
+    targetName: state.target || null,
     target: state.resolvedTarget || {},
     sentinel: state.sentinel,
     profileDir: chromeProfileDir(projectDir),

package/src/cli-registry.mjs

@@ -344,19 +344,22 @@ export const CLI_COMMANDS = Object.freeze([
       Object.freeze({ name: "question", required: true, description: "What an end user would type" }),
     ],
     options: [
-      value("--retry", "n", "Ask again when no action fired (a newly published action can take a minute to be picked up)", { default: "0" }),
+      value("--retry", "n", "Ask again when no action fired - without attach, whenever no card came back, even if an action without a card ran (a newly published action can take a minute to be picked up)", { default: "0" }),
       value("--every", "seconds", "Pause between retries", { default: "20" }),
       value("--timeout", "seconds", "Wait this long for a reply", { default: "90" }),
     ],
-    prerequisites: ["foldspace attach is running, so the handlers on the page are this project's build"],
+    prerequisites: [
+      "foldspace attach --daemon is running, so the handlers on the page are this project's build - or foldspace published pointed the page at the published code",
+    ],
     effects: [
       "Types into the panel the way a person does; touches nothing inside the SDK",
+      "handler.execute / handler.render come from the attach daemon's log; without the daemon they read \"not tracked here (published code)\" and the reply, cards and screenshot still come back",
       "Creates a real conversation: it appears in the customer's Foldspace dashboard (test traffic only under attach --test-mode)",
       "Saves panel and full-page screenshots under .foldspace-dev/ask/",
     ],
     next: [
-      "Read reply, cards and handler.execute / handler.render; look at the screenshot",
-      "Only then: foldspace badge ready, and invite the customer to try it",
+      "Read reply, cards and handler.execute / handler.render, and look at the screenshot; after foldspace published, the reply, cards and screenshot are the proof",
+      "Only then invite the human to try it: with attach running, foldspace badge ready first; after foldspace published there is no pill - say in chat it is ready (a reload takes it off the published code), then npx foldspace attach --daemon before you build anything else",
     ],
   }),
   Object.freeze({
@@ -387,6 +390,39 @@ export const CLI_COMMANDS = Object.freeze([
     ],
     next: ["Say in chat whose turn it is and what to try"],
   }),
+  Object.freeze({
+    name: "published",
+    entry: "published.mjs",
+    group: "verify",
+    summary: "Point the test window's agent at its published dev or prod code, so foldspace ask checks that code",
+    usage: "foldspace published <dev|prod>",
+    risk: "browser-session",
+    environment: "local-chrome",
+    environmentVariables: ["FOLDSPACE_PROJECT_DIR", "CDP_PORT"],
+    capabilities: ["browser.cdp", "page.evaluate", "page.mutate"],
+    positionals: [
+      Object.freeze({
+        name: "environment",
+        required: true,
+        description:
+          "dev: the code the `deploy` tool published to dev | prod: the code their users get",
+      }),
+    ],
+    options: [],
+    prerequisites: [
+      "attach is not running: npx foldspace attach --stop (while it runs the page serves your local build)",
+      "The page loads this project's agent by itself: the same product and Agent Key as foldspace.dev.json",
+    ],
+    effects: [
+      "Points this page's agent, in this test window, at the code published to the environment you name; the actions that code defines answer from it, the others keep the page's own handlers",
+      "A reload puts the page back on what the agent loads normally",
+      "Publishes nothing and changes nothing in Foldspace",
+    ],
+    next: [
+      'Prove it: npx foldspace ask "<question>" --retry 2',
+      "To go back to the local build: npx foldspace attach --daemon",
+    ],
+  }),
   Object.freeze({
     name: "deploy",
     // Foldspace-internal: it uploads to Foldspace's own storage, which no
@@ -508,7 +544,7 @@ export function createCliRegistry({ packageName, packageVersion, env = process.e
       "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.",
+      "A session publishes code with the `deploy` tool in the Foldspace tools, the way `repo_read` command `instructions` says - never with `foldspace deploy`, which is for Foldspace staff only. Where the site loads this agent by itself, check dev with `npx foldspace attach --stop`, `npx foldspace published dev` and `npx foldspace ask \"<question>\" --retry 2`. Where it does not, without a code project, or after a final refusal from the Foldspace tools, putting it in front of their users is a step the Foldspace team does with the human (https://foldspace.ai/demo, support@foldspace.ai).",
     ],
   };
 }

package/src/keep-focus.mjs

@@ -3,18 +3,19 @@
 // then types into their live product (seen 2026-09-22). Nothing in CDP stops
 // that; on macOS the fix is to hand focus straight back to whatever app the
 // human was using. Elsewhere this is a no-op.
+//
+// Done with Launch Services (`lsappinfo`, `open -b`), not AppleScript: asking
+// "System Events" which app is in front makes macOS show the customer a
+// permission dialog - "claude wants access to control System Events" - in
+// the middle of their first session (seen 2026-09-30). Launch Services
+// answers the same question, and brings an app forward, with no dialog.
 
 import { execFile } from "node:child_process";
 
-const FRONT_APP_SCRIPT =
-  'tell application "System Events" to get bundle identifier of first application process whose frontmost is true';
-
-function osascript(script) {
+function run(command, args, timeout = 4000) {
   return new Promise((resolve) => {
-    // 4s, not less: the first call wakes System Events, which alone can take
-    // over a second, and a timeout here silently leaves focus on Chrome.
-    execFile("osascript", ["-e", script], { timeout: 4000 }, (error, stdout) => {
-      resolve(error ? null : String(stdout).trim());
+    execFile(command, args, { timeout }, (error, stdout) => {
+      resolve(error ? null : String(stdout));
     });
   });
 }
@@ -22,7 +23,11 @@ function osascript(script) {
 /** Bundle id of the app in front right now, or null (not macOS, or unknown). */
 export async function frontApp() {
   if (process.platform !== "darwin") return null;
-  return osascript(FRONT_APP_SCRIPT);
+  const asn = (await run("lsappinfo", ["front"]))?.trim();
+  if (!asn) return null;
+  const info = await run("lsappinfo", ["info", "-only", "bundleid", asn]);
+  const match = /"CFBundleIdentifier"="([^"]+)"/.exec(info || "");
+  return match ? match[1] : null;
 }
 
 /**
@@ -39,11 +44,10 @@ export async function withoutStealingFocus(action, { front = frontApp, restore =
 }
 
 export async function restoreFront(bundleId) {
-  if (process.platform !== "darwin" || !bundleId) return;
+  if (process.platform !== "darwin" || !bundleId || !/^[\w.-]+$/.test(bundleId)) return;
   // Twice, a beat apart: Chrome's activation lands after the navigation
   // settles, so one immediate restore can be overtaken.
-  const script = `tell application id "${bundleId.replace(/"/g, "")}" to activate`;
-  await osascript(script);
+  await run("open", ["-b", bundleId]);
   await new Promise((resolve) => setTimeout(resolve, 400));
-  await osascript(script);
+  await run("open", ["-b", bundleId]);
 }

package/src/published-core.mjs

@@ -0,0 +1,392 @@
+// Pure logic behind `foldspace published <dev|prod>`, unit-tested.
+//
+// The command points the test window's agent at the code published to dev or
+// prod, so `foldspace ask` checks that code instead of the local build. Each
+// refusal here keeps that check honest: while attach runs the page serves the
+// local build, and a page whose agent is not this project's would load another
+// agent's code.
+
+import { ACTION_OBSERVER_GLOBAL } from "./action-observer.mjs";
+import { ATTACH_MODES, characterizePageAgents, parseAgentId } from "./attach-helpers.mjs";
+import { detectedProductIds, guardAttachMode } from "./attach-preflight.mjs";
+import { serializeDiagnostic } from "./diagnostics.mjs";
+
+export const PUBLISHED_USAGE = "usage: foldspace published <dev|prod>";
+
+// The public SDK's values for remoteActionsSettings.environment: "DEV" loads
+// /agent/actions/dev/<product>/<agent>/index.js, anything else - "PROD" is
+// the default - /agent/actions/prod/... (checked against script.eucerahive.io
+// /web/sdk/foldspace.js, built 2026-10-04).
+export const ENVIRONMENTS = Object.freeze({ dev: "DEV", prod: "PROD" });
+
+export const ATTACH_RUNNING =
+  "Stop attach first: `npx foldspace attach --stop` - while it runs the page serves your local build.";
+
+// No daemon runs, yet the page carries the local build again after a reload:
+// an attach started without --daemon is connected, and `attach --stop` (which
+// stops only the daemon) does not reach it.
+export const FOREGROUND_ATTACH =
+  "This page still runs a local build after a reload, but no attach daemon runs for this project: an attach started without --daemon is still connected to the test window.";
+
+export function foregroundAttachNext(env) {
+  return `Stop the attach that was started without --daemon - \`attach --stop\` stops only the daemon - then run \`npx foldspace published ${env}\` again.`;
+}
+
+export const RELOAD_NOTE = "A reload puts the page back on what the agent loads normally.";
+
+// Every published bundle assigns its handlers here; the SDK reads and deletes it.
+export const REMOTE_ACTIONS_GLOBAL = "__FOLDSPACE_REMOTE_ACTIONS__";
+
+// Every refusal below comes after `attach --stop`, so each next step starts by
+// putting the local build back. A platform gap never stops the session.
+const word = (env) => (env === "prod" ? "production" : "dev");
+const lower = (text) => `${text.charAt(0).toLowerCase()}${text.slice(1)}`;
+
+/** The page is this project's agent, but this window cannot show the published code. */
+export function notHere(env) {
+  return `Run \`npx foldspace attach --daemon\` to put your local build back in the test window, and tell the human in one sentence that the test window cannot show ${word(env)} yet - do not invite them to try ${word(env)} there.`;
+}
+
+/** Worth one more run; then the window cannot show it. */
+function again(env) {
+  return `Run \`npx foldspace published ${env}\` once more. If it fails again: ${lower(notHere(env))}`;
+}
+
+/**
+ * The page needs --bootstrap or --replace to attach, which is not a site that
+ * loads this agent by itself: the manual sends the rest to the Foldspace team.
+ */
+function attachAgain(flag) {
+  return `Run \`npx foldspace attach --daemon ${flag}\` to put your local build back in the test window. A page that needs \`${flag}\` cannot show the published code, and production waits until their site loads this agent by itself: for the rest, give the human the Foldspace team answer (CLAUDE.md, "Done, and what you say at the end").`;
+}
+
+// How long the agent gets to load the published code. The SDK gives up on the
+// script itself after 10s.
+export const LOAD_TIMEOUT_MS = 20_000;
+
+/** "dev" | "prod" (any case) -> { name, sdkValue }, or throws the usage line. */
+export function publishedEnvironment(value) {
+  const name = String(value ?? "").trim().toLowerCase();
+  if (!Object.hasOwn(ENVIRONMENTS, name)) throw new Error(PUBLISHED_USAGE);
+  return { name, sdkValue: ENVIRONMENTS[name] };
+}
+
+/** The agent foldspace.dev.json names, as inject recorded it. */
+export function projectAgent(launchTarget = {}, configTarget = {}) {
+  const target = { ...configTarget, ...launchTarget };
+  if (!target.productId || !target.agentApiName) {
+    throw new Error("foldspace.dev.json must define productId and agentApiName.");
+  }
+  return {
+    productId: String(target.productId),
+    apiName: String(target.agentApiName),
+    mode: String(target.mode || "OVERLAY").toUpperCase(),
+  };
+}
+
+/**
+ * Page body: what attach's own preflight reads (inspectSdkState), whether
+ * attach prepared this document, and how long ago the document loaded.
+ */
+export function buildPageReadScript(agent) {
+  return `const state = await ${serializeDiagnostic("inspectSdkState", {
+    expectedApiName: agent.apiName,
+  })};
+    return {
+      state,
+      attachPrepared: Boolean(window[${JSON.stringify(ACTION_OBSERVER_GLOBAL)}] || window.__FOLDSPACE_DEV_REPLACE__),
+      ageMs: Math.round(performance.now()),
+    };`;
+}
+
+/**
+ * Enough of the page has loaded to judge it: its agent is there, and no load
+ * of remote actions is in flight (the SDK removes that script once it lands).
+ */
+export function pageSettled(read) {
+  const state = read?.state;
+  if (!state) return false;
+  if (read.attachPrepared) return true;
+  const ready = state.documentReadyState === "interactive" || state.documentReadyState === "complete";
+  const loading = (state.scripts || []).some((source) => String(source).includes("/agent/actions/"));
+  return ready && state.sdkReady === true && (state.agentIds || []).length > 0 && !loading;
+}
+
+/** The mode the page created this agent in, when it has exactly one instance of it. */
+export function modeOnPage(agentIds = [], apiName) {
+  const mine = agentIds.map(parseAgentId).filter((agent) => agent && agent.apiName === apiName);
+  return mine.length === 1 ? mine[0].mode : null;
+}
+
+/**
+ * Is the page's own Foldspace agent this project's agent - same Agent Key, same
+ * product? Attach's swap-mode preflight answers exactly that, so it is reused.
+ */
+export function checkPublishedPage({ state, agent }) {
+  const mode = modeOnPage(state?.agentIds, agent.apiName) || agent.mode;
+  const characterization = characterizePageAgents({
+    sdkPresent: state?.sdkPresent === true,
+    agentIds: state?.agentIds || [],
+    expectedApiName: agent.apiName,
+    expectedMode: mode,
+  });
+  const pageProductIds = detectedProductIds(state);
+  const guard = guardAttachMode({
+    mode: ATTACH_MODES.SWAP,
+    characterization,
+    expectedProductId: agent.productId,
+    pageProductIds,
+  });
+  if (guard.ok) return { ok: true, mode };
+
+  const status = characterization.status;
+  const next = attachAgain(status === "no-sdk" ? "--bootstrap" : "--replace");
+  let reason;
+  if (status === "no-sdk") {
+    reason = "This page has no Foldspace agent of its own, so there is nothing to load the published code into.";
+  } else if (status === "sdk-without-agent") {
+    reason = "This page loads Foldspace but has no agent on it.";
+  } else if (status === "different-agent") {
+    reason = `This page's Foldspace agent is not ${agent.apiName}, the Agent Key in foldspace.dev.json, so foldspace ask would talk to another agent and the check would prove nothing.`;
+  } else if (status === "multiple-agents") {
+    reason = "This page has more than one Foldspace agent, so it is not clear which one foldspace ask would talk to.";
+  } else if (!pageProductIds.length) {
+    reason = `The page's agent is ${agent.apiName}, but its product cannot be read from the page, so it is not proven to be this project's agent.`;
+  } else {
+    reason = `The page's agent is ${agent.apiName} of another product (${pageProductIds.join(", ")}), not ${agent.productId} in foldspace.dev.json: it would load that product's code, and the check would prove nothing.`;
+  }
+  return {
+    ok: false,
+    reason,
+    next,
+    page: { agents: state?.agentIds || [], products: pageProductIds },
+  };
+}
+
+/**
+ * Page body that points the agent instance at its published code and reports
+ * what loaded. It calls only the instance's public methods, and watches the
+ * one global every published bundle assigns itself to.
+ *
+ * What in the SDK shapes it:
+ * - A published bundle assigns its handlers to window.__FOLDSPACE_REMOTE_ACTIONS__;
+ *   the SDK reads that global when the script loads, deletes it, and then
+ *   reports remoteActions.loaded. Watching the global is how this knows the
+ *   exact handlers the published code brought.
+ * - When remote actions load, a handler the instance already has wins over a
+ *   loaded one of the same name - the page's own, or what its normal load
+ *   brought, even when that load lands late. So once the published code has
+ *   loaded, its handlers are set over every one of the same name, and the
+ *   check counts only the names that answer from the published code.
+ * - An agent created late queues these calls until it is ready, and its
+ *   getAvailableActions() reads {} until then. Nothing is taken from the page
+ *   before the load: what it had is read only after the load reported.
+ * - setConfiguration loads nothing when the settings equal the current ones
+ *   (the page may already load prod, or ran this before). Turning remote
+ *   actions off first makes the second call a change.
+ * The page remembers what an earlier run brought and what it covered, so dev's
+ * handlers do not linger into a prod check.
+ */
+export function buildPublishedScript({ apiName, mode, environment, timeoutMs = LOAD_TIMEOUT_MS }) {
+  return `
+    const NS = typeof window.__FOLD_SPACE__ === "string" && window.__FOLD_SPACE__ ? window.__FOLD_SPACE__ : "foldspace";
+    const sdk = window[NS];
+    if (typeof sdk?.agent !== "function") return { switched: false, reason: "no-sdk" };
+    const agent = sdk.agent({ apiName: ${JSON.stringify(apiName)}, mode: ${JSON.stringify(mode)} });
+    const needed = ["getAvailableActions", "removeAiActions", "setAiActions", "setConfiguration", "on", "off"];
+    const missing = needed.filter((name) => typeof agent?.[name] !== "function");
+    if (missing.length) return { switched: false, reason: "sdk-too-old", missing };
+
+    const ENV = ${JSON.stringify(environment.name)};
+    const store = window.__FOLDSPACE_PUBLISHED__ || (window.__FOLDSPACE_PUBLISHED__ = {});
+    const ID = ${JSON.stringify(`${mode.toLowerCase()}-${apiName}`)};
+    // own: the page's handler for a name the published code covered, before
+    // any run covered it. brought: what the last run set.
+    const memo = store[ID]?.brought ? store[ID] : (store[ID] = { own: {}, brought: {} });
+
+    const GLOBAL = ${JSON.stringify(REMOTE_ACTIONS_GLOBAL)};
+    let held = window[GLOBAL];
+    let lastRead;
+    let watching = true;
+    const watch = {
+      configurable: true,
+      enumerable: true,
+      get() {
+        lastRead = held;
+        queueMicrotask(rearm);
+        return held;
+      },
+      set(value) { held = value; },
+    };
+    const armed = () => Object.getOwnPropertyDescriptor(window, GLOBAL)?.get === watch.get;
+    // The SDK deletes the global right after reading it; watch for the next load.
+    function rearm() {
+      if (!watching || armed()) return;
+      held = undefined;
+      try { Object.defineProperty(window, GLOBAL, watch); } catch {}
+    }
+    try { Object.defineProperty(window, GLOBAL, watch); } catch {}
+
+    let settle;
+    const outcome = new Promise((resolve) => { settle = resolve; });
+    const onLoaded = (event) => {
+      // The read that just happened belongs to this load, whichever load it is.
+      const bundle = lastRead;
+      lastRead = undefined;
+      if (event?.environment === ENV) {
+        settle({ loaded: true, actionCount: Number(event.actionCount) || 0, source: event.source || null, bundle });
+      }
+    };
+    const onFailed = (event) => {
+      if (event?.environment === ENV) settle({ loaded: false, source: event.source || null });
+    };
+    agent.on("remoteActions.loaded", onLoaded);
+    agent.on("remoteActions.failed", onFailed);
+    let result;
+    let timer;
+    try {
+      agent.setConfiguration({ remoteActionsSettings: { enabled: false } });
+      agent.setConfiguration({
+        enableDebugLogs: true,
+        remoteActionsSettings: { enabled: true, environment: ${JSON.stringify(environment.sdkValue)} },
+      });
+      result = await Promise.race([
+        outcome,
+        new Promise((resolve) => { timer = setTimeout(() => resolve({ loaded: null }), ${Number(timeoutMs)}); }),
+      ]);
+    } catch (error) {
+      result = { loaded: false, error: String(error?.message || error).slice(0, 300) };
+    } finally {
+      clearTimeout(timer);
+      agent.off("remoteActions.loaded", onLoaded);
+      agent.off("remoteActions.failed", onFailed);
+      watching = false;
+      if (armed()) {
+        delete window[GLOBAL];
+        if (held !== undefined) window[GLOBAL] = held;
+      }
+    }
+
+    const { bundle, ...report } = result;
+    if (result.loaded !== true) return { switched: true, ...report };
+    if (!bundle || typeof bundle !== "object") {
+      return { switched: true, ...report, published: report.actionCount ? null : [], kept: [] };
+    }
+
+    // The SDK takes only entries with an execute function.
+    const names = Object.keys(bundle).filter((name) => typeof bundle[name]?.execute === "function");
+    const now = agent.getAvailableActions() || {};
+    for (const name of names) {
+      const current = now[name];
+      if (current && current !== bundle[name] && current !== memo.brought[name] && !(name in memo.own)) {
+        memo.own[name] = current;
+      }
+    }
+    // What an earlier run brought that this code does not define goes; the
+    // page's own handler for that name comes back.
+    for (const name of Object.keys(memo.brought)) {
+      if (names.includes(name) || now[name] !== memo.brought[name]) continue;
+      if (name in memo.own) agent.setAiActions({ [name]: memo.own[name] });
+      else agent.removeAiActions([name]);
+    }
+    const over = {};
+    for (const name of names) if (now[name] !== bundle[name]) over[name] = bundle[name];
+    if (Object.keys(over).length) agent.setAiActions(over);
+    memo.brought = Object.fromEntries(names.map((name) => [name, bundle[name]]));
+
+    const after = agent.getAvailableActions() || {};
+    const published = names.filter((name) => after[name] === bundle[name]).sort();
+    const kept = names.filter((name) => after[name] !== bundle[name]).sort();
+    return { switched: true, ...report, published, kept };`;
+}
+
+/**
+ * The published code of an environment is /agent/actions/<env>/<product>/<agent>/index.js.
+ * Anything else the agent loaded is not what was published last: an agent
+ * pinned to one version loads index.<version>.js (the SDK reports that name
+ * even when it falls back to index.js), and a host override loads from
+ * elsewhere entirely.
+ */
+export function publishedSourceProblem({ source, env, agent }) {
+  if (!source) return null;
+  const path = `/agent/actions/${env}/${agent.productId}/${agent.apiName}/`;
+  if (source.endsWith(`${path}index.js`)) return null;
+  if (!source.includes(`/agent/actions/${env}/`)) {
+    return `The agent loaded ${source}, not the published ${word(env)} code: its configuration names its own address for actions.`;
+  }
+  if (source.includes(path) && /\/index\.[^/]+\.js$/.test(source)) {
+    return `The agent loaded ${source}: it is pinned to one version of its code, so this window keeps loading that version, not what was published last.`;
+  }
+  return `The agent loaded ${source}, not the published ${word(env)} code of ${agent.apiName}.`;
+}
+
+/** The JSON the command prints, from what the page reported. */
+export function publishedReport({ outcome, environment, agent, timeoutMs = LOAD_TIMEOUT_MS }) {
+  const env = environment.name;
+  const base = { environment: env, agent: agent.apiName };
+  if (!outcome?.switched) {
+    return {
+      ok: false,
+      ...base,
+      reason:
+        outcome?.reason === "sdk-too-old"
+          ? `This page's Foldspace SDK cannot load published code on request: its agent has no ${outcome.missing.join(", ")}.`
+          : "This page has no Foldspace agent to point at the published code.",
+      next: notHere(env),
+    };
+  }
+  if (outcome.loaded === null) {
+    return {
+      ok: false,
+      ...base,
+      reason: `The agent did not report loading the published ${word(env)} code within ${Math.round(timeoutMs / 1000)}s. Its own handlers are untouched; ${lower(RELOAD_NOTE)}`,
+      next: again(env),
+    };
+  }
+  if (outcome.error) {
+    return {
+      ok: false,
+      ...base,
+      reason: `This page's agent failed while switching to the published ${word(env)} code: ${outcome.error}. Its own handlers are untouched; ${lower(RELOAD_NOTE)}`,
+      next: notHere(env),
+    };
+  }
+  if (outcome.loaded === false) {
+    return {
+      ok: false,
+      ...base,
+      reason: `The page could not load the published ${word(env)} code${outcome.source ? ` (${outcome.source})` : ""}. Its own handlers are untouched; ${lower(RELOAD_NOTE)}`,
+      next:
+        env === "dev"
+          ? `If you have not published to dev with the \`deploy\` tool yet, do that, then run \`npx foldspace published dev\` again. If you have, run it again in a minute; if it fails again: ${lower(notHere(env))}`
+          : `If you have published to production with the \`deploy\` tool, run \`npx foldspace published prod\` again in a minute. If you have not (production gets code only with the human's yes), or it fails again: ${lower(notHere(env))}`,
+    };
+  }
+  const sourceProblem = publishedSourceProblem({ source: outcome.source, env, agent });
+  if (sourceProblem) return { ok: false, ...base, reason: sourceProblem, next: notHere(env) };
+  if (!Array.isArray(outcome.published)) {
+    return {
+      ok: false,
+      ...base,
+      reason: `The agent loaded the published ${word(env)} code, but the page did not show which handlers it brought, so it is not proven that foldspace ask would test that code.`,
+      next: notHere(env),
+    };
+  }
+  const kept = outcome.kept || [];
+  if (kept.length) {
+    const count = outcome.published.length + kept.length;
+    return {
+      ok: false,
+      ...base,
+      reason: `The published ${word(env)} code has ${count} ${count === 1 ? "action" : "actions"}, but the page kept its own handler for ${kept.length} of them (${kept.join(", ")}), so foldspace ask would not test that code.`,
+      next: again(env),
+    };
+  }
+  return {
+    ok: true,
+    ...base,
+    actions: outcome.published,
+    ...(outcome.source ? { source: outcome.source } : {}),
+    note: RELOAD_NOTE,
+  };
+}

package/templates/agent-starter/claude-settings.json

@@ -10,6 +10,7 @@
       "Bash(npx foldspace observe:*)",
       "Bash(npx foldspace ask:*)",
       "Bash(npx foldspace badge:*)",
+      "Bash(npx foldspace published:*)",
       "Bash(npm install:*)",
       "Bash(npm run build:*)",
       "Bash(npm run typecheck:*)",