@tokenoftrust/cli 1.3.4-rc.4 → 1.3.4

package/bin/tot.mjs

@@ -15,6 +15,7 @@
  *   tot doctor                check this machine is ready
  *   tot ideas                 copy-paste AI prompts that reliably wow
  *   tot feedback              send a note to ToT + your recent CLI activity  ← built (activity-log.mjs → feedback_submit MCP tool)
+ *   tot app scaffold/dev      build + locally exercise a Private App        ← built (offline; see src/commands/app/)
  *   tot help                  this help
  *
  * Context-aware (see src/context.mjs): the same `tot` does the right thing from
@@ -58,6 +59,8 @@ tot — Token of Trust developer CLI
   tot doctor                check this machine is ready
   tot ideas                 copy-paste AI prompts that reliably wow
   tot feedback "<msg>"      send feedback to Token of Trust (attaches recent activity)
+  tot app scaffold <name>   scaffold a Storefront Private App
+  tot app dev ...           local, offline Private App webhook/manifest/JWT harness
   tot help                  show this help
   tot --version             print the CLI version
 
@@ -134,6 +137,11 @@ async function dispatch(cmd, rest, ctx) {
     return run(rest, ctx);
   }
 
+  if (cmd === "app") {
+    const { run } = await import("../src/commands/app/index.mjs");
+    return run(rest, ctx);
+  }
+
   if (BUILD_ORDER.includes(cmd)) {
     console.error(
       `\`tot ${cmd}\` isn't built yet.\n\n` +

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@tokenoftrust/cli",
-  "version": "1.3.4-rc.4",
+  "version": "1.3.4",
   "description": "Token of Trust developer CLI — check out a tenant store, run it locally with save→reload, and submit it for preview. Installs the `tot` command.",
   "license": "Apache-2.0",
   "author": "Token of Trust",
@@ -25,6 +25,7 @@
   "files": [
     "bin",
     "src",
+    "template",
     "README.md",
     "LICENSE"
   ],

package/src/app-scaffold.mjs

@@ -0,0 +1,84 @@
+/**
+ * Private App scaffolding — `tot app scaffold <name>` (PrivateApps epic D6
+ * Chunk C). Mirrors `sample.mjs`'s `scaffoldSample`: materialize a bundled
+ * template onto disk, idempotently, fully offline. No login, no MCP, no
+ * network — a developer building a Storefront Private App gets a runnable
+ * skeleton before they've registered anything with Token of Trust.
+ *
+ * The scaffolded tree also gets its own copy of `src/vendor/private-apps-devkit.mjs`
+ * (as `lib/private-apps-devkit.mjs`) so the stub `server.js` can verify webhook
+ * signatures with zero runtime dependencies — see that file's module doc for
+ * why this is a vendored copy rather than a package.json dependency.
+ */
+import { cpSync, existsSync, mkdirSync, readdirSync } from "node:fs";
+import { fileURLToPath } from "node:url";
+import { dirname, join, resolve } from "node:path";
+
+const here = dirname(fileURLToPath(import.meta.url)); // packages/cli/src
+
+/** Absolute path to the bundled private-app template (ships via package.json `files`). */
+export function appTemplateDir() {
+  return resolve(here, "..", "template", "private-app");
+}
+
+/** Absolute path to the vendored devkit copied into every scaffolded app. */
+export function vendoredDevkitPath() {
+  return resolve(here, "vendor", "private-apps-devkit.mjs");
+}
+
+/** A directory carries a scaffolded app if it has a `tot-app.json` manifest. */
+export function isAppScaffold(dir) {
+  return existsSync(join(dir, "tot-app.json"));
+}
+
+/** A directory is "empty enough" to scaffold into if it's absent or has no entries. */
+function isEmptyDir(dir) {
+  if (!existsSync(dir)) return true;
+  try {
+    return readdirSync(dir).length === 0;
+  } catch {
+    return false;
+  }
+}
+
+/**
+ * Materialize a Private App skeleton at `destDir`: copy the bundled template
+ * (`tot-app.json`, `fixtures/`, `README.md`, `Dockerfile`, `.env.example`,
+ * `server.js`) in, then drop this package's vendored devkit at `lib/`.
+ * Idempotent — re-running against an already-scaffolded directory is a no-op
+ * that returns it. Refuses to clobber a non-scaffold, non-empty directory.
+ *
+ * @param {string} destDir
+ * @param {{ force?: boolean, log?: (m: string) => void }} [opts]
+ * @returns {{ dir: string, created: boolean }}
+ */
+export function scaffoldApp(destDir, { force = false, log = () => {} } = {}) {
+  const dir = resolve(destDir);
+
+  if (isAppScaffold(dir) && !force) {
+    log(`  ✓ reusing existing app scaffold ${dir}`);
+    return { dir, created: false };
+  }
+  if (!force && !isEmptyDir(dir)) {
+    const err = new Error(
+      `${dir} isn't empty and isn't an app scaffold — scaffold into an empty directory (or pass a new name)`,
+    );
+    err.code = "ENOTEMPTY_APP";
+    throw err;
+  }
+
+  const template = appTemplateDir();
+  if (!existsSync(template)) {
+    const err = new Error("the private-app template isn't available in this release yet — it's coming soon.");
+    err.code = "TEMPLATE_UNAVAILABLE";
+    throw err;
+  }
+
+  mkdirSync(dir, { recursive: true });
+  cpSync(template, dir, { recursive: true });
+  mkdirSync(join(dir, "lib"), { recursive: true });
+  cpSync(vendoredDevkitPath(), join(dir, "lib", "private-apps-devkit.mjs"));
+
+  log(`  ✓ scaffolded a private app → ${dir}`);
+  return { dir, created: true };
+}

package/src/banner.mjs

@@ -0,0 +1,46 @@
+/**
+ * Shared, dependency-free milestone banners — the emphasized, rule-delimited
+ * blocks for the first-run "look back at your Developer Cockpit" moments:
+ * "You're live" (start.mjs) and the first save→reload beat (dev-logs.mjs).
+ *
+ * Deliberately NO figlet/ASCII-art dependency — a horizontal rule frames the
+ * block so the moment reads as a distinct milestone (not another log line),
+ * while staying consistent with printSampleBanner/printDevBanner's indented,
+ * business voice — just louder. Node built-ins only (URL).
+ */
+
+/** The product name every terminal milestone points the developer back to. */
+export const DEVELOPER_COCKPIT = "Developer Cockpit";
+
+const RULE = "━".repeat(56);
+
+/**
+ * Render an emphasized milestone banner as a single string (leading + trailing
+ * blank line included). Each line is indented two spaces and framed by a heavy
+ * horizontal rule top and bottom — no side borders, so emoji/Unicode content
+ * never mis-aligns a right edge. Pure + exported so it's unit-tested.
+ * @param {string[]} lines content lines (already free of the two-space indent)
+ * @returns {string}
+ */
+export function milestoneBanner(lines) {
+  const body = (lines || []).map((l) => `  ${l}`).join("\n");
+  return `\n  ${RULE}\n${body}\n  ${RULE}\n`;
+}
+
+/**
+ * Derive the hosted Developer Cockpit URL (`<origin>/cockpit`) from the cached
+ * activity-bridge URL (creds.activityUrl / TOT_DEV_ACTIVITY_URL). Returns null
+ * when there's no bridge URL (a bare `tot login`, an older session, or the
+ * zero-login `--sample` path) so callers cleanly omit the cockpit line.
+ * Pure + exported so it's unit-tested.
+ * @param {string|null|undefined} activityUrl
+ * @returns {string|null}
+ */
+export function cockpitUrlFrom(activityUrl) {
+  if (!activityUrl) return null;
+  try {
+    return new URL("/cockpit", String(activityUrl)).toString();
+  } catch {
+    return null;
+  }
+}

package/src/commands/app/dev.mjs

@@ -0,0 +1,268 @@
+/**
+ * `tot app dev` — the local Private App harness (PrivateApps epic D6 Chunk D).
+ * Everything here is OFFLINE: no network beyond the localhost URL you point
+ * it at, no MCP, no real ToT credentials. It generates and reuses its own
+ * throwaway RS256 keypair per app directory (`.tot/dev-keys.json`) so signing
+ * and verifying webhook deliveries — and minting widget-launch JWTs — works
+ * before you've registered anything with Token of Trust.
+ *
+ *   tot app dev validate [<manifest>]     lint tot-app.json against the contract
+ *   tot app dev emit <topic>              sign a fixture CloudEvent and POST it
+ *   tot app dev verify --url ... --body ...   verify a captured webhook delivery
+ *   tot app dev mint                      mint a dev widget-launch JWT
+ *
+ * Uses this package's vendored copy of `@tokenoftrust/private-apps-devkit`
+ * (../../vendor/private-apps-devkit.mjs — see that file for why it's vendored
+ * rather than a dependency) for every crypto operation, so a scaffolded app's
+ * own `server.js` (which imports the SAME functions from its copy at
+ * `lib/private-apps-devkit.mjs`) verifies exactly what this harness signs.
+ */
+import { existsSync, mkdirSync, readFileSync, writeFileSync } from "node:fs";
+import { dirname, join, resolve } from "node:path";
+import { fail } from "../../errors.mjs";
+import {
+  signWebhookRequest,
+  verifyWebhookSignature,
+  mintJwt,
+  generateDevRs256KeyPair,
+  validateManifest,
+} from "../../vendor/private-apps-devkit.mjs";
+
+const USAGE = `tot app dev — run your Private App's webhook loop locally, offline
+
+  tot app dev validate [<manifest>]        lint tot-app.json (default ./tot-app.json)
+  tot app dev emit <topic> [--url <url>]   sign a fixtures/<topic>.cloudevent.json and POST it
+    [--fixture <path>] [--app <dir>]
+  tot app dev verify --url <url> --body <file>   verify a captured webhook delivery
+    --content-digest <v> --signature-input <v> --signature <v> [--key <jwk-file>]
+  tot app dev mint [--claims <json>] [--exp <secs>] [--app <dir>]   mint a dev widget-launch JWT
+
+All subcommands accept --app <dir> (default: cwd) to point at a scaffolded app.`;
+
+export function makeRequestId() {
+  return `req_${randHex(6)}`;
+}
+export function makeTraceparent() {
+  return `00-${randHex(16)}-${randHex(8)}-01`;
+}
+function randHex(bytes) {
+  return Buffer.from(crypto.getRandomValues(new Uint8Array(bytes))).toString("hex");
+}
+
+/** Load or create the app's throwaway RS256 keypair at `<appDir>/.tot/dev-keys.json`. */
+export async function ensureDevKeys(appDir, { kid } = {}) {
+  const keysPath = join(appDir, ".tot", "dev-keys.json");
+  const alg = { name: "RSASSA-PKCS1-v1_5", hash: "SHA-256" };
+
+  if (existsSync(keysPath)) {
+    const stored = JSON.parse(readFileSync(keysPath, "utf8"));
+    const privateKey = await crypto.subtle.importKey("jwk", stored.privateKeyJwk, alg, true, ["sign"]);
+    const publicKey = await crypto.subtle.importKey("jwk", stored.publicKeyJwk, alg, true, ["verify"]);
+    return { ...stored, privateKey, publicKey, keysPath };
+  }
+
+  const { publicKey, privateKey } = await generateDevRs256KeyPair();
+  const publicKeyJwk = await crypto.subtle.exportKey("jwk", publicKey);
+  const privateKeyJwk = await crypto.subtle.exportKey("jwk", privateKey);
+  const record = { kid: kid || "dev-key-1", publicKeyJwk, privateKeyJwk };
+  mkdirSync(dirname(keysPath), { recursive: true });
+  writeFileSync(keysPath, JSON.stringify(record, null, 2) + "\n");
+  return { ...record, privateKey, publicKey, keysPath };
+}
+
+/** The manifest's declared signatureKeyId, if any — used as the kid for freshly-generated keys. */
+export function manifestKeyId(appDir) {
+  try {
+    const manifest = JSON.parse(readFileSync(join(appDir, "tot-app.json"), "utf8"));
+    return manifest?.webhooks?.signatureKeyId || null;
+  } catch {
+    return null;
+  }
+}
+
+function readInput(pathOrDash) {
+  if (pathOrDash === "-") {
+    return readFileSync(0, "utf8"); // stdin
+  }
+  return readFileSync(resolve(pathOrDash), "utf8");
+}
+
+// ── validate ─────────────────────────────────────────────────────────────
+
+function runValidate(argv, { appDir }) {
+  const manifestPath = resolve(argv[0] || join(appDir, "tot-app.json"));
+  if (!existsSync(manifestPath)) {
+    console.error(fail(`no manifest at ${manifestPath}`, "tot app scaffold <name>, or pass a path"));
+    return 2;
+  }
+  let parsed;
+  try {
+    parsed = JSON.parse(readFileSync(manifestPath, "utf8"));
+  } catch (e) {
+    console.error(fail(`${manifestPath} is not valid JSON: ${e.message}`));
+    return 1;
+  }
+  const result = validateManifest(parsed);
+  if (result.ok) {
+    console.log(`✔ ${manifestPath} is a valid tot-app.json (contract v${result.manifest.contractVersion})`);
+    return 0;
+  }
+  console.log(`✖ ${manifestPath} — ${result.errors.length} error(s):`);
+  for (const e of result.errors) console.log(`  - ${e}`);
+  return 1;
+}
+
+// ── emit ─────────────────────────────────────────────────────────────────
+
+export function parseEmitArgs(argv) {
+  const a = { topic: null, url: "http://localhost:8787/webhooks", fixture: null };
+  for (let i = 0; i < argv.length; i++) {
+    const t = argv[i];
+    if (t === "--url") a.url = argv[++i];
+    else if (t === "--fixture") a.fixture = argv[++i];
+    else if (!t.startsWith("--") && !a.topic) a.topic = t;
+  }
+  return a;
+}
+
+async function runEmit(argv, { appDir }) {
+  const args = parseEmitArgs(argv);
+  if (!args.topic) {
+    console.error(fail("tot app dev emit needs a topic", "tot app dev emit order.created"));
+    return 2;
+  }
+  const fixturePath = resolve(args.fixture || join(appDir, "fixtures", `${args.topic}.cloudevent.json`));
+  if (!existsSync(fixturePath)) {
+    console.error(fail(`no fixture at ${fixturePath}`, "pass --fixture <path>, or add one under fixtures/"));
+    return 2;
+  }
+  const body = readFileSync(fixturePath, "utf8");
+
+  const keys = await ensureDevKeys(appDir, { kid: manifestKeyId(appDir) });
+  const { headers } = await signWebhookRequest({ method: "POST", url: args.url, body, key: keys.privateKey, kid: keys.kid });
+
+  const requestId = makeRequestId();
+  const traceparent = makeTraceparent();
+  console.log(`→ POST ${args.url}  (topic: ${args.topic}, keyid: ${keys.kid})`);
+  console.log(`  tot-request-id: ${requestId}`);
+  console.log(`  traceparent:    ${traceparent}`);
+
+  let response;
+  try {
+    response = await fetch(args.url, {
+      method: "POST",
+      headers: { ...headers, "content-type": "application/json", "tot-request-id": requestId, traceparent },
+      body,
+    });
+  } catch (e) {
+    console.error(fail(`could not reach ${args.url}: ${e.message}`, "start your receiver first (e.g. `node server.js`)"));
+    return 1;
+  }
+  const text = await response.text();
+  console.log(`← ${response.status} ${text}`);
+  return response.ok ? 0 : 1;
+}
+
+// ── verify ───────────────────────────────────────────────────────────────
+
+export function parseVerifyArgs(argv) {
+  const a = { method: "POST", url: null, body: null, contentDigest: null, signatureInput: null, signature: null, key: null };
+  for (let i = 0; i < argv.length; i++) {
+    const t = argv[i];
+    if (t === "--method") a.method = argv[++i];
+    else if (t === "--url") a.url = argv[++i];
+    else if (t === "--body") a.body = argv[++i];
+    else if (t === "--content-digest") a.contentDigest = argv[++i];
+    else if (t === "--signature-input") a.signatureInput = argv[++i];
+    else if (t === "--signature") a.signature = argv[++i];
+    else if (t === "--key") a.key = argv[++i];
+  }
+  return a;
+}
+
+async function runVerify(argv, { appDir }) {
+  const args = parseVerifyArgs(argv);
+  if (!args.url || !args.body || !args.contentDigest || !args.signatureInput || !args.signature) {
+    console.error(
+      fail(
+        "tot app dev verify needs --url --body --content-digest --signature-input --signature",
+        "tot app dev verify --help",
+      ),
+    );
+    return 2;
+  }
+  const body = readInput(args.body);
+  const keyJwk = args.key
+    ? JSON.parse(readInput(args.key)).publicKeyJwk ?? JSON.parse(readInput(args.key))
+    : JSON.parse(readFileSync(join(appDir, ".tot", "dev-keys.json"), "utf8")).publicKeyJwk;
+  const publicKey = await crypto.subtle.importKey("jwk", keyJwk, { name: "RSASSA-PKCS1-v1_5", hash: "SHA-256" }, true, [
+    "verify",
+  ]);
+
+  const result = await verifyWebhookSignature({
+    method: args.method,
+    url: args.url,
+    body,
+    headers: { "content-digest": args.contentDigest, "signature-input": args.signatureInput, signature: args.signature },
+    publicKey,
+  });
+
+  if (result.ok) {
+    console.log(`✔ signature verified (keyid: ${result.keyid}, created: ${result.created})`);
+    return 0;
+  }
+  console.log(`✖ signature verification failed: ${result.code} — ${result.reason}`);
+  return 1;
+}
+
+// ── mint ─────────────────────────────────────────────────────────────────
+
+export function parseMintArgs(argv) {
+  const a = { claims: null, exp: 300 };
+  for (let i = 0; i < argv.length; i++) {
+    const t = argv[i];
+    if (t === "--claims") a.claims = argv[++i];
+    else if (t === "--exp") a.exp = Number(argv[++i]);
+  }
+  return a;
+}
+
+async function runMint(argv, { appDir }) {
+  const args = parseMintArgs(argv);
+  const claims = args.claims ? JSON.parse(args.claims) : { scope: "widgets:launch", tenant: "example", env: "dev" };
+  const keys = await ensureDevKeys(appDir, { kid: manifestKeyId(appDir) });
+  const expiresAt = Math.floor(Date.now() / 1000) + args.exp;
+  const token = await mintJwt({ claims, privateKey: keys.privateKey, kid: keys.kid, expiresAt });
+
+  console.log(token);
+  console.log(`\n(dev-only — signed with the throwaway key at ${keys.keysPath}, kid: ${keys.kid}, expires in ${args.exp}s)`);
+  return 0;
+}
+
+// ── dispatch ─────────────────────────────────────────────────────────────
+
+export function parseTopArgs(argv) {
+  const appIdx = argv.indexOf("--app");
+  const appDir = appIdx >= 0 ? resolve(argv[appIdx + 1]) : resolve(process.cwd());
+  const rest = appIdx >= 0 ? [...argv.slice(0, appIdx), ...argv.slice(appIdx + 2)] : argv;
+  return { appDir, rest };
+}
+
+/** @param {string[]} argv */
+export async function run(argv) {
+  const [sub, ...subArgv] = argv;
+  if (!sub || sub === "--help" || sub === "-h" || sub === "help") {
+    console.log(USAGE);
+    return sub ? 0 : 2;
+  }
+
+  const { appDir, rest } = parseTopArgs(subArgv);
+
+  if (sub === "validate") return runValidate(rest, { appDir });
+  if (sub === "emit") return runEmit(rest, { appDir });
+  if (sub === "verify") return runVerify(rest, { appDir });
+  if (sub === "mint") return runMint(rest, { appDir });
+
+  console.error(fail(`unknown \`tot app dev\` subcommand: ${sub}`, "tot app dev --help"));
+  return 2;
+}

package/src/commands/app/index.mjs

@@ -0,0 +1,35 @@
+/**
+ * `tot app` — the Storefront Private App developer subcommand group
+ * (PrivateApps epic D6 Chunks C+D): scaffold a new app, then exercise its
+ * webhook/manifest/widget-launch loop entirely offline.
+ *
+ *   tot app scaffold <name>   materialize a runnable Private App skeleton
+ *   tot app dev ...           local, offline webhook/manifest/JWT harness
+ */
+import { fail } from "../../errors.mjs";
+
+const USAGE = `tot app — build a Storefront Private App
+
+  tot app scaffold <name>   scaffold a runnable Private App skeleton
+  tot app dev ...           local, offline webhook/manifest/JWT harness (see \`tot app dev --help\`)`;
+
+/** @param {string[]} argv @param {any} ctx */
+export async function run(argv, ctx) {
+  const [sub, ...rest] = argv;
+  if (!sub || sub === "--help" || sub === "-h" || sub === "help") {
+    console.log(USAGE);
+    return sub ? 0 : 2;
+  }
+
+  if (sub === "scaffold") {
+    const { run: runScaffold } = await import("./scaffold.mjs");
+    return runScaffold(rest, ctx);
+  }
+  if (sub === "dev") {
+    const { run: runDev } = await import("./dev.mjs");
+    return runDev(rest, ctx);
+  }
+
+  console.error(fail(`unknown \`tot app\` subcommand: ${sub}`, "tot app --help"));
+  return 2;
+}

package/src/commands/app/scaffold.mjs

@@ -0,0 +1,57 @@
+/**
+ * `tot app scaffold <name>` — materialize a runnable Storefront Private App
+ * skeleton on disk (PrivateApps epic D6 Chunk C). See ../../app-scaffold.mjs
+ * for the offline, idempotent copy logic this wraps.
+ *
+ *   tot app scaffold <name>          scaffold ./<name>
+ *   tot app scaffold <name> --force  overwrite a non-empty, non-scaffold dir
+ *
+ * Exit 0 = scaffolded (or already scaffolded); 2 = usage / refused.
+ */
+import { resolve } from "node:path";
+import { scaffoldApp } from "../../app-scaffold.mjs";
+import { fail } from "../../errors.mjs";
+
+function parseArgs(argv) {
+  const a = { name: null, force: false, help: false };
+  for (const t of argv) {
+    if (t === "--force") a.force = true;
+    else if (t === "--help" || t === "-h") a.help = true;
+    else if (!t.startsWith("--") && !a.name) a.name = t;
+  }
+  return a;
+}
+
+const USAGE = `tot app scaffold <name> — scaffold a Storefront Private App
+
+  tot app scaffold <name>          scaffold ./<name>
+  tot app scaffold <name> --force  overwrite a non-empty, non-scaffold directory`;
+
+/** @param {string[]} argv */
+export function run(argv) {
+  const args = parseArgs(argv);
+  if (args.help) {
+    console.log(USAGE);
+    return 0;
+  }
+  if (!args.name) {
+    console.error(fail("tot app scaffold needs a directory name", "tot app scaffold <name>"));
+    return 2;
+  }
+
+  try {
+    const { dir, created } = scaffoldApp(resolve(process.cwd(), args.name), {
+      force: args.force,
+      log: (m) => console.log(m),
+    });
+    console.log(
+      created
+        ? `\nNext:\n  cd ${args.name}\n  tot app dev validate\n  tot app dev --help\n`
+        : `\n${dir} is already scaffolded.\n`,
+    );
+    return 0;
+  } catch (e) {
+    console.error(fail(e.message));
+    return 2;
+  }
+}

package/src/commands/dev.mjs

@@ -52,6 +52,7 @@ import {
 } from "../sample.mjs";
 import { startHeartbeatFromEnv } from "../dev-heartbeat.mjs";
 import { streamDevLogs } from "../dev-logs.mjs";
+import { cockpitUrlFrom } from "../banner.mjs";
 
 /** The published runner image (--docker fallback). Override with --image / TOT_DEV_IMAGE. */
 const DEFAULT_DEV_IMAGE =
@@ -252,7 +253,7 @@ function runMonorepo(ctx, argv) {
     // still tears the runner down — the child stays in our process group and
     // owns the TTY signal.
     const child = spawn(process.execPath, [script, ...argv], { stdio: ["ignore", "pipe", "pipe"], env });
-    streamDevLogs(child);
+    streamDevLogs(child, { cockpitUrl: cockpitUrlFrom(env.TOT_DEV_ACTIVITY_URL) });
     child.on("exit", (code) => resolvePromise(code ?? 0));
     child.on("error", (e) => {
       console.error(`✗ could not start the dev runner: ${e.message}`);
@@ -323,7 +324,7 @@ export function bootNative(runnerDir, workspace, port, url, args) {
   // dropped, real errors pass through. Ctrl-C still tears the server down — the
   // child stays in our process group and owns the TTY signals.
   const handle = spawnNativeDev(runnerDir, workspace, port, { stdio: "piped", env: bridgeEnv });
-  streamDevLogs(handle.child);
+  streamDevLogs(handle.child, { cockpitUrl: cockpitUrlFrom(bridgeEnv.TOT_DEV_ACTIVITY_URL) });
 
   // Heartbeat the hosted cockpit (G1) with the CLI version + this live localhost
   // URL while the runner runs — CLI-side, using the SAME bridge credential the
@@ -983,12 +984,15 @@ function extractTarball(archivePath, destDir, { strip = 0 } = {}) {
 
 /**
  * Activate the exact package manager the runner's package.json pins
- * (packageManager: "pnpm@x.y.z"), via corepack — Node 20+ ships corepack, so
- * this needs no separate pnpm install on the host. Best-effort: if corepack
- * itself is missing (very old Node), pnpm install below will surface that
- * clearly instead.
+ * (packageManager: "pnpm@x.y.z"), via corepack — Node 22.12+ (the CLI's floor)
+ * always bundles corepack, so this PINS a real pnpm without any global `npm i -g
+ * pnpm` (which floats whatever's latest). Best-effort: if corepack itself is
+ * missing or disabled (a locked-down host), pnpm install below falls through to
+ * the pnpm-missing obstacle instead of failing here.
+ * @param {string} runnerDir
+ * @param {{ logPath?: string, spawnFn?: typeof spawnSync }} [opts]
  */
-function ensureCorepackPnpm(runnerDir, { logPath } = {}) {
+export function ensureCorepackPnpm(runnerDir, { logPath, spawnFn = spawnSync } = {}) {
   const pkgPath = join(runnerDir, "package.json");
   if (!existsSync(pkgPath)) return;
   let pm;
@@ -1006,7 +1010,7 @@ function ensureCorepackPnpm(runnerDir, { logPath } = {}) {
     // WITHOUT the global shim (see runPnpmInstall's fallback). Capture both to the
     // log — a silent corepack failure was why the install error carried no cause.
     for (const args of [["enable"], ["prepare", pm, "--activate"]]) {
-      const r = spawnSync("corepack", args, { stdio: ["ignore", fd ?? "ignore", fd ?? "ignore"] });
+      const r = spawnFn("corepack", args, { stdio: ["ignore", fd ?? "ignore", fd ?? "ignore"] });
       if (fd !== null && (r.error || r.status !== 0)) {
         writeSync(fd, `[tot] corepack ${args.join(" ")} → ${r.error?.code || r.error?.message || `exit ${r.status}`}\n`);
       }
@@ -1022,8 +1026,37 @@ function ensureCorepackPnpm(runnerDir, { logPath } = {}) {
  * churn) is captured to a log file instead of flooding the terminal, so the
  * caller's spinner owns the screen. On failure we surface a clean, business-
  * readable message + the log path — never the raw node/pnpm firehose.
+ * @param {string} runnerDir
+ * @param {{ logPath?: string, spawnFn?: typeof spawnSync }} [opts]
  */
-async function runPnpmInstall(runnerDir, { logPath } = {}) {
+/**
+ * Run a child process to completion WITHOUT blocking the event loop, resolving
+ * the SAME `{ status, error }` shape spawnSync returns so runPnpmInstall's
+ * launcher-fallback logic reads it unchanged. This non-blocking spawn is what
+ * lets the "installing the store preview engine…" spinner keep ticking during
+ * the long npm install (spawnSync would freeze it at "(0s)"). An ENOENT (launcher
+ * not on PATH) surfaces via the async 'error' event as `{ status: null, error }`,
+ * matching what spawnSync produced for the same case.
+ * @param {string} cmd @param {string[]} args @param {object} opts
+ * @returns {Promise<{ status: number|null, error: Error|null, signal?: string|null }>}
+ */
+function spawnAsyncResult(cmd, args, opts = {}) {
+  return new Promise((resolvePromise) => {
+    let settled = false;
+    const settle = (v) => { if (!settled) { settled = true; resolvePromise(v); } };
+    let child;
+    try {
+      child = spawn(cmd, args, opts);
+    } catch (error) {
+      settle({ status: null, error });
+      return;
+    }
+    child.on("error", (error) => settle({ status: null, error }));
+    child.on("close", (status, signal) => settle({ status, error: null, signal }));
+  });
+}
+
+export async function runPnpmInstall(runnerDir, { logPath, spawnFn = spawnAsyncResult } = {}) {
   const fd = logPath ? openSync(logPath, "a") : null;
   const installArgs = ["install", "--config.dangerouslyAllowAllBuilds=true"];
   // npm FIRST: it ships with EVERY Node (including 25+, where corepack is no
@@ -1044,7 +1077,13 @@ async function runPnpmInstall(runnerDir, { logPath } = {}) {
   ];
   try {
     for (const { cmd, args } of attempts) {
-      const r = spawnSync(cmd, args, {
+      // Awaited: the default spawnFn (spawnAsyncResult) runs the launcher
+      // NON-BLOCKING so the caller's "installing…" spinner keeps ticking during
+      // the (long, one-time) npm install instead of freezing at "(0s)" — a
+      // synchronous spawnSync would hold the event loop and starve the interval.
+      // Tests inject a synchronous stub returning { status, error }; awaiting a
+      // plain (non-thenable) value is a no-op, so that contract is unchanged.
+      const r = await spawnFn(cmd, args, {
         cwd: runnerDir,
         // Send both streams to the log fd (or swallow them) — never inherit.
         stdio: ["ignore", fd ?? "ignore", fd ?? "ignore"],
@@ -1110,11 +1149,16 @@ export function spawnNativeDev(runnerDir, workspace, port, { stdio = "inherit",
   // doesn't understand the bare string "piped", so map it to the array here.
   const stdioArr = stdio === "piped" ? ["ignore", "pipe", "pipe"] : stdio;
   // `env` (e.g. activityBridgeEnv()) merges OVER process.env — {} is a pure
-  // passthrough, identical to the old no-env-key behavior.
+  // passthrough, identical to the old no-env-key behavior. Append `--no-warnings`
+  // to NODE_OPTIONS so the runner's Node process never emits the scary
+  // `(node:NNNN) ExperimentalWarning: …` boot noise to the developer (b4);
+  // appended (not replaced) so any host-set NODE_OPTIONS is preserved.
+  const mergedEnv = { ...process.env, ...env };
+  mergedEnv.NODE_OPTIONS = `${mergedEnv.NODE_OPTIONS ? `${mergedEnv.NODE_OPTIONS} ` : ""}--no-warnings`;
   const child = spawn(
     process.execPath,
     [script, "--workspace", workspace, "--port", port],
-    { cwd: runnerDir, stdio: stdioArr, env: { ...process.env, ...env } },
+    { cwd: runnerDir, stdio: stdioArr, env: mergedEnv },
   );
   const handle = { child, exited: false, done: null };
   handle.done = new Promise((resolvePromise) => {
@@ -1148,7 +1192,7 @@ async function runContainer(workspace, args, ctx) {
   // piping is safe; Ctrl-C still stops the container (docker stays in our
   // process group and forwards the signal, with `--init` reaping it inside).
   const handle = await spawnDevContainer(plan, args, { stdio: "piped" });
-  streamDevLogs(handle.child);
+  streamDevLogs(handle.child, { cockpitUrl: cockpitUrlFrom(activityBridgeEnv().TOT_DEV_ACTIVITY_URL) });
 
   // Heartbeat the hosted cockpit (G1) CLI-side while the container runs — the
   // container reports file-saves via the threaded env, but the CLI owns the