@tokenoftrust/cli 1.3.0 → 1.3.1-rc.2

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@tokenoftrust/cli",
-  "version": "1.3.0",
+  "version": "1.3.1-rc.2",
   "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",

package/src/commands/checkout.mjs

@@ -166,14 +166,15 @@ export async function checkoutTenant(client, { tenant, tag = "main", cloneDir =
   await client.callTool("client_switch", { tenant });
   const checkout = await client.callTool("tenant_checkout", { tenant, tag });
 
-  const gitRemote = checkout?.gitRemote;
-  const cloneUrl = checkout?.cloneUrl ?? null;
-  if (!gitRemote) {
-    throw new CliError(
-      `tenant_checkout returned no gitRemote for ${tenant}: ${redact(JSON.stringify(checkout))}`,
-      { next: "confirm you're entitled to this store — `tot checkout` (lists your stores)" },
-    );
+  // A non-checkout result (not provisioned / not entitled / failed) must surface
+  // the MCP's human message + a concrete next step, NEVER a raw JSON.stringify
+  // dump (James's 2026-07-19 first-experience failure).
+  const err = checkoutError(checkout);
+  if (err) {
+    throw new CliError(redact(err.message), { next: err.next });
   }
+  const gitRemote = checkout.gitRemote;
+  const cloneUrl = checkout.cloneUrl ?? null;
   const u = new URL(gitRemote);
   const publicUrl = `${u.protocol}//${u.host}${u.pathname}`;
 
@@ -200,6 +201,42 @@ function cloneRepo(gitRemote, dir, redact) {
   return { dir, head };
 }
 
+/**
+ * Classify a `tenant_checkout` tool result: null when it's a genuine, usable
+ * checkout (carries a gitRemote), otherwise a human { message, next } pair so
+ * callers surface the MCP's own words + a concrete next step instead of dumping
+ * raw JSON (James's 2026-07-19 first-experience failure: a not-provisioned store
+ * printed JSON.stringify(checkout)). callTool unwraps the tool result to its
+ * structuredContent / parsed text, so a failure surfaces as an error-ish status
+ * ('forbidden' | 'invalid_input' | 'checkout_failed' | 'error'), a `message`, or
+ * simply a missing gitRemote. When the repo isn't provisioned yet we speak to the
+ * INVITED DEVELOPER ("your store isn't set up yet"), not the operator — dropping
+ * the `repo_provision` jargon the MCP aims at whoever provisions. Any other
+ * failure surfaces the MCP's own message. Pure + exported so it's unit-tested
+ * without any I/O.
+ * @param {unknown} checkout
+ * @returns {{ message: string, next: string }|null}
+ */
+export function checkoutError(checkout) {
+  const c = checkout && typeof checkout === "object" && !Array.isArray(checkout) ? checkout : null;
+  if (c && c.gitRemote) return null; // a usable checkout — never an error
+  const msg =
+    (c && (c.message || (typeof c.error === "string" ? c.error : c.error?.message))) ||
+    (c && typeof c.raw === "string" && c.raw.trim() ? c.raw.trim() : null) ||
+    null;
+  // The store's repo isn't provisioned yet — it isn't set up for this developer.
+  if (typeof msg === "string" && /not provisioned/i.test(msg)) {
+    return {
+      message: "your store isn't set up on Token of Trust yet",
+      next: "ask your Token of Trust contact to finish setting up your store, then re-run",
+    };
+  }
+  return {
+    message: msg || "the store checkout couldn't be completed",
+    next: "confirm you're entitled to this store — `tot checkout` (lists your stores)",
+  };
+}
+
 /**
  * Normalize the (shape-varying) `client_list` response into a plain, sorted
  * list of the stores this identity can build on. Shared by `tot checkout`'s

package/src/commands/dev.mjs

@@ -32,14 +32,14 @@
  * either way.
  */
 import { spawn, spawnSync, execFileSync } from "node:child_process";
-import { existsSync, readFileSync, writeFileSync, mkdirSync, renameSync, rmSync, readdirSync, createWriteStream } from "node:fs";
+import { existsSync, readFileSync, writeFileSync, mkdirSync, renameSync, rmSync, readdirSync, createWriteStream, openSync, closeSync } from "node:fs";
 import { homedir, tmpdir } from "node:os";
 import { join, resolve } from "node:path";
 import { createHash } from "node:crypto";
 import { Readable } from "node:stream";
 import { pipeline } from "node:stream/promises";
 import { setTimeout as delay } from "node:timers/promises";
-import { createMcpClient, CLI_VERSION } from "../mcp.mjs";
+import { createMcpClient, CLI_VERSION, setRunnerVersion } from "../mcp.mjs";
 import { establishSession } from "../auth.mjs";
 import { defaultCredentialsPath, readCredentials } from "../token-store.mjs";
 import { CliError, fail, formatError } from "../errors.mjs";
@@ -49,6 +49,7 @@ import {
   scaffoldSample, isSampleCheckout, sampleConfig,
   resolveRendererSource as resolveLocalRendererSource, newestCachedRunner, SAMPLE_DIR_NAME,
 } from "../sample.mjs";
+import { startHeartbeatFromEnv } from "../dev-heartbeat.mjs";
 
 /** The published runner image (--docker fallback). Override with --image / TOT_DEV_IMAGE. */
 const DEFAULT_DEV_IMAGE =
@@ -307,7 +308,14 @@ export function bootNativeEnv(args) {
 }
 
 export function bootNative(runnerDir, workspace, port, url, args) {
-  const handle = spawnNativeDev(runnerDir, workspace, port, { stdio: "inherit", env: bootNativeEnv(args) });
+  const bridgeEnv = bootNativeEnv(args);
+  const handle = spawnNativeDev(runnerDir, workspace, port, { stdio: "inherit", env: bridgeEnv });
+
+  // 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
+  // runner's file-save path uses (no-op in --sample, which threads no credential).
+  const stopHeartbeat = startHeartbeatFromEnv(bridgeEnv, { url });
+  handle.done.finally(() => stopHeartbeat());
 
   // Auto-open the browser the moment the server answers (D). Non-blocking so
   // Ctrl-C / logs are unaffected; --no-open suppresses it.
@@ -418,7 +426,21 @@ export function pickRunnerVersion(meta, { cliVersion, explicitPin }) {
   const distTags = meta?.["dist-tags"] || {};
   const versions = Object.keys(meta?.versions || {});
 
-  // 1) Explicit pin (flag/env): resolve a dist-tag name, else take it verbatim.
+  // INVARIANT: the runner must never run AHEAD of the CLI's major.minor. A runner
+  // published for a newer minor can expect CLI features this CLI doesn't have, so a
+  // too-new runner is a silent-skew bug. `cliMM` is this CLI's ceiling; `withinCeiling`
+  // gates every non-explicit path below. (numeric major.minor compare; a prerelease
+  // suffix on the CLI, e.g. 1.3.0-rc.2, is ignored — 1.3 is still the ceiling.)
+  const cliMM = majorMinor(cliVersion);
+  const withinCeiling = (v) => {
+    if (!cliMM) return true; // unparseable CLI version → don't block resolution
+    const mm = majorMinor(v);
+    return !!mm && (mm.major < cliMM.major || (mm.major === cliMM.major && mm.minor <= cliMM.minor));
+  };
+
+  // 1) Explicit pin (flag/env): the deliberate escape hatch — honored verbatim,
+  // INCLUDING above the ceiling (someone testing a newer runner on purpose). This is
+  // the ONLY way past the ceiling; every automatic path below respects it.
   if (explicitPin) {
     return { version: distTags[explicitPin] || explicitPin, reason: `pinned ${explicitPin}` };
   }
@@ -427,11 +449,13 @@ export function pickRunnerVersion(meta, { cliVersion, explicitPin }) {
   // is published at the SAME version as the CLI (incl. prereleases like 1.3.0-rc.0,
   // which the stable-only minor match below deliberately skips). This is what makes
   // `tot@1.3.0-rc.0` pull `runner@1.3.0-rc.0` instead of falling back to stale latest.
+  // (Same version ⇒ same major.minor ⇒ always within the ceiling.)
   if (versions.includes(cliVersion)) {
     return { version: cliVersion, reason: "exact CLI-version match" };
   }
 
   // 3) CLI-minor match: highest published <major>.<minor>.* (numeric patch order).
+  // Constrained to the CLI's exact minor, so this is within the ceiling by construction.
   const m = /^(\d+)\.(\d+)\./.exec(cliVersion || "");
   if (m) {
     const prefix = `${m[1]}.${m[2]}.`;
@@ -443,9 +467,40 @@ export function pickRunnerVersion(meta, { cliVersion, explicitPin }) {
     }
   }
 
-  // 4) Fallback: the `latest` dist-tag (pre-alignment safety net).
-  if (distTags.latest) return { version: distTags.latest, reason: "fell back to latest (no CLI-minor match)" };
-  throw new Error("no publishable runner version (no CLI-minor match and no `latest` dist-tag)");
+  // 4) Fallback: the highest STABLE version AT OR BELOW the CLI's major.minor ceiling.
+  // This replaces a blind `latest` — `latest` can be a HIGHER minor than this CLI
+  // (e.g. CLI 1.2.x but runner latest 1.3.0), which would run the runner ahead of the
+  // CLI. Running slightly BEHIND (a lower minor) is the safe direction.
+  const capped = versions
+    .filter((v) => /^\d+\.\d+\.\d+$/.test(v) && withinCeiling(v))
+    .sort(compareStableAsc);
+  if (capped.length) {
+    const version = capped[capped.length - 1];
+    return { version, reason: `highest ≤ CLI major.minor ${cliMM ? `${cliMM.major}.${cliMM.minor}` : "?"}` };
+  }
+  // Last resort: `latest`, but ONLY if it doesn't breach the ceiling.
+  if (distTags.latest && withinCeiling(distTags.latest)) {
+    return { version: distTags.latest, reason: "fell back to latest (within CLI ceiling)" };
+  }
+  throw new Error(
+    `no runner version at or below the CLI's major.minor (${cliMM ? `${cliMM.major}.${cliMM.minor}` : cliVersion})`,
+  );
+}
+
+/** Parse the numeric {major, minor} from a semver (prerelease suffix ignored). Null if unparseable. */
+export function majorMinor(v) {
+  const m = /^(\d+)\.(\d+)\./.exec(String(v || ""));
+  return m ? { major: Number(m[1]), minor: Number(m[2]) } : null;
+}
+
+/** Ascending comparator for STABLE x.y.z strings (numeric per segment). */
+function compareStableAsc(a, b) {
+  const pa = a.split(".").map(Number);
+  const pb = b.split(".").map(Number);
+  for (let i = 0; i < 3; i++) {
+    if ((pa[i] || 0) !== (pb[i] || 0)) return (pa[i] || 0) - (pb[i] || 0);
+  }
+  return 0;
 }
 
 /**
@@ -562,7 +617,9 @@ export function pinnedPublicCacheDir(cacheRoot, version) {
 function prunePublicRunnerCache(cacheRoot, keepVersion) {
   try {
     if (!cacheRoot || !existsSync(cacheRoot)) return;
-    const keep = `public-${keepVersion}`;
+    // keepVersion == null → keep NOTHING (drop every public-* dir); used when a
+    // cached runner failed its version probe and none can be trusted.
+    const keep = keepVersion == null ? null : `public-${keepVersion}`;
     for (const name of readdirSync(cacheRoot)) {
       if (!name.startsWith("public-") || name === keep) continue;
       rmSync(join(cacheRoot, name), { recursive: true, force: true });
@@ -572,6 +629,32 @@ function prunePublicRunnerCache(cacheRoot, keepVersion) {
   }
 }
 
+/**
+ * Probe a runner tree for its version by invoking its own `--version` surface
+ * (`node <runner>/scripts/tot-dev.mjs --version`, the net-new rc.2 runner bin).
+ * Returns the trimmed version string, or null when the runner is too OLD to answer
+ * (pre-`--version`, i.e. pre-rc.2), missing, or errors. Never throws. Short timeout
+ * so a hung runner can't stall `tot dev`.
+ *
+ * This is the detector behind "force an upgrade if it can't tell us its version":
+ * a runner that can't report a version is by definition stale and must not be reused.
+ */
+export function probeRunnerVersion(runnerDir, { timeoutMs = 4000 } = {}) {
+  try {
+    const script = join(runnerDir, "scripts", "tot-dev.mjs");
+    if (!existsSync(script)) return null;
+    const out = execFileSync(process.execPath, [script, "--version"], {
+      timeout: timeoutMs,
+      encoding: "utf8",
+      stdio: ["ignore", "pipe", "ignore"],
+    });
+    const v = String(out).trim().split(/\s+/)[0];
+    return /^\d+\.\d+\.\d+/.test(v) ? v : null;
+  } catch {
+    return null; // old runner (no --version), timeout, or spawn failure → treat as unversioned
+  }
+}
+
 /**
  * Resolve the renderer for the ZERO-LOGIN sample / public-fallback path WITHOUT
  * any MCP call — the whole point of the free taste. Resolution order:
@@ -605,6 +688,7 @@ export async function ensureSampleRenderer(args, ctx, { env = process.env, cache
       });
     }
     console.error(`~ renderer: ${src.why} (${src.dir})`);
+    setRunnerVersion(probeRunnerVersion(src.dir)); // telemetry: version of an override/in-tree runner
     return src.dir;
   }
 
@@ -629,9 +713,18 @@ export async function ensureSampleRenderer(args, ctx, { env = process.env, cache
   if (!explicitPin) {
     const exact = pinnedPublicCacheDir(cacheRoot, CLI_VERSION);
     if (exact) {
-      console.error(`~ renderer: cached public runner ${CLI_VERSION} (matches this CLI)`);
-      prunePublicRunnerCache(cacheRoot, CLI_VERSION);
-      return exact;
+      // Trust-but-verify: a `public-<CLI_VERSION>` dir SHOULD be a current runner,
+      // but if it can't report its own version it predates the --version surface
+      // (a corrupt/half-migrated cache) — force a fresh fetch rather than run a
+      // runner we can't identify. When it DOES answer, reuse it (fully offline-safe).
+      if (probeRunnerVersion(exact)) {
+        console.error(`~ renderer: cached public runner ${CLI_VERSION} (matches this CLI)`);
+        setRunnerVersion(CLI_VERSION);
+        prunePublicRunnerCache(cacheRoot, CLI_VERSION);
+        return exact;
+      }
+      console.error(`~ renderer: cached runner at ${exact} can't report a version — refetching (forced upgrade)`);
+      prunePublicRunnerCache(cacheRoot, null); // drop ALL public-* — none is trustworthy
     }
   }
 
@@ -647,6 +740,7 @@ export async function ensureSampleRenderer(args, ctx, { env = process.env, cache
     const cached = newestCachedRunner(cacheRoot);
     if (cached && existsSync(join(cached, "scripts", "tot-dev.mjs"))) {
       console.error(`~ renderer: offline — reusing cached runner ${cached} (couldn't reach npm to pin the version)`);
+      setRunnerVersion(probeRunnerVersion(cached)); // telemetry: best-effort version of the offline reuse
       return cached;
     }
     throw new CliError(
@@ -658,11 +752,13 @@ export async function ensureSampleRenderer(args, ctx, { env = process.env, cache
       },
     );
   }
-  console.error(`~ renderer: public npm ${pub.version} (${PUBLIC_RUNNER_PACKAGE})`);
+  // The store preview engine (public npm ${PUBLIC_RUNNER_PACKAGE}@${pub.version}) — kept
+  // out of the user's way; the setup spinner below is the visible progress.
   const dir = await installRunnerTarball(
     { source: pub.url, version: pub.cacheKey, isUrl: true, strip: pub.strip },
     { log: (m) => console.error(m) },
   );
+  setRunnerVersion(pub.version); // telemetry: the runner version running this session
   // The pinned version is now installed under public-<version> — drop any other
   // public-* dirs (e.g. the stale public-0.1.0) so they can never be reused.
   prunePublicRunnerCache(cacheRoot, pub.version);
@@ -697,14 +793,14 @@ export async function installRunnerTarball({ source, version, isUrl = true, stri
   // First run only — set the expectation so the one-time cost doesn't read as a
   // hang: this downloads + installs the renderer once, then every later run of
   // this version is a no-network cache hit.
-  log(`~ first run: downloading + installing the renderer (~a minute; cached after this)…`);
+  log(`~ first run: setting up your store preview (~a minute, one-time — cached after this)…`);
   const localSource = isUrl ? null : resolveLocalTarball(source);
   const archivePath = isUrl ? join(tmpdir(), `tot-renderer-${process.pid}-${Date.now()}.tar.gz`) : localSource;
   try {
     if (isUrl) {
       // The fetch itself is otherwise silent (no per-byte output) and can run
       // tens of seconds on a cold cache — tick a spinner so it never looks hung.
-      const spin = startProgress("downloading the renderer…");
+      const spin = startProgress("downloading the store preview engine…");
       try {
         await downloadFile(source, archivePath);
       } finally {
@@ -718,8 +814,24 @@ export async function installRunnerTarball({ source, version, isUrl = true, stri
     rmSync(stagingDir, { recursive: true, force: true });
     mkdirSync(stagingDir, { recursive: true });
     extractTarball(archivePath, stagingDir, { strip });
+    // Pin the runner install to PUBLIC npm. The moat-free runner has only public
+    // deps, but the HOST's global ~/.npmrc may point `registry` at a private
+    // mirror (an internal proxy that 502s, or one an invited developer can't
+    // reach) — an invited dev's machine config must never decide where the
+    // runner's public deps come from. A project-level .npmrc wins over the user's.
+    writeFileSync(join(stagingDir, ".npmrc"), "registry=https://registry.npmjs.org/\n");
     ensureCorepackPnpm(stagingDir);
-    runPnpmInstall(stagingDir);
+    // The install is the long, noisy step — tick a spinner while its output goes
+    // to a log, so the terminal shows one clean line instead of the pnpm firehose.
+    const installLog = join(RENDERER_CACHE_ROOT, `${version}.install.log`);
+    const installSpin = startProgress("installing the store preview engine…", {
+      stages: [{ afterMs: 20000, text: "still setting up the preview engine (first run only)…" }],
+    });
+    try {
+      runPnpmInstall(stagingDir, { logPath: installLog });
+    } finally {
+      installSpin.stop();
+    }
     // Atomic-ish: only rename into the final, discoverable path once install
     // succeeded, so a crashed/interrupted run never leaves a half-built cache
     // entry that a later `tot dev` would treat as ready.
@@ -789,14 +901,48 @@ function ensureCorepackPnpm(runnerDir) {
   spawnSync("corepack", ["prepare", pm, "--activate"], { stdio: "ignore" });
 }
 
-function runPnpmInstall(runnerDir) {
-  const r = spawnSync("pnpm", ["install", "--config.dangerouslyAllowAllBuilds=true"], {
-    cwd: runnerDir,
-    stdio: "inherit",
-  });
-  if (r.status !== 0) {
-    throw new Error(`pnpm install failed (exit ${r.status}) — is pnpm/corepack available on this host?`);
+/**
+ * Install the runner's deps QUIETLY: the package manager's raw stdout (dozens of
+ * "Scope: all N workspace projects" lines, registry retry [WARN]s, dep-graph
+ * 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.
+ */
+function runPnpmInstall(runnerDir, { logPath } = {}) {
+  const fd = logPath ? openSync(logPath, "a") : null;
+  try {
+    const r = spawnSync("pnpm", ["install", "--config.dangerouslyAllowAllBuilds=true"], {
+      cwd: runnerDir,
+      // Send both streams to the log fd (or swallow them) — never inherit.
+      stdio: ["ignore", fd ?? "ignore", fd ?? "ignore"],
+    });
+    if (r.status !== 0) {
+      throw new Error(
+        `couldn't set up the store preview engine${pnpmFailureHint(logPath)}` +
+          (logPath ? `\n     details: ${logPath}` : ""),
+      );
+    }
+  } finally {
+    if (fd !== null) closeSync(fd);
+  }
+}
+
+/**
+ * Turn a pnpm-install failure into a human hint by scanning the captured log —
+ * the most common cause is the ToT package registry being unreachable, which the
+ * raw log buries under retry noise. Best-effort; empty string when we can't tell.
+ */
+function pnpmFailureHint(logPath) {
+  if (!logPath) return " — is pnpm/corepack available on this host?";
+  try {
+    const tail = readFileSync(logPath, "utf8").slice(-8000);
+    if (/npm\.tokenoftrust\.com|ERR_PNPM_FETCH|502|ECONNREFUSED|ETIMEDOUT|ENOTFOUND/i.test(tail)) {
+      return " — the Token of Trust package registry looks unreachable right now; check your connection and retry";
+    }
+  } catch {
+    /* ignore — fall through to the generic message */
   }
+  return "";
 }
 
 /**
@@ -848,6 +994,12 @@ async function runContainer(workspace, args, ctx) {
 
   const handle = await spawnDevContainer(plan, args, { stdio: "inherit" });
 
+  // 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
+  // version + live URL. Same bridge credential (activityBridgeEnv), no-op absent.
+  const stopHeartbeat = startHeartbeatFromEnv(activityBridgeEnv(), { url: plan.url });
+  handle.done.finally(() => stopHeartbeat());
+
   // Auto-open the browser the moment the server answers (D). Non-blocking so
   // Ctrl-C / logs are unaffected; --no-open suppresses it.
   if (!args.noOpen) {

package/src/commands/start.mjs

@@ -64,6 +64,7 @@ import {
   activityBridgeEnv, NativeArtifactUnavailableError,
 } from "./dev.mjs";
 import { scaffoldSample, isSampleCheckout, sampleConfig, SAMPLE_DIR_NAME } from "../sample.mjs";
+import { startHeartbeatFromEnv } from "../dev-heartbeat.mjs";
 import { IDEAS } from "./ideas.mjs";
 
 const DEFAULT_MCP_URL = "https://mcp.tokenoftrust.com";
@@ -226,6 +227,7 @@ export async function run(argv, ctx) {
     // above; wait for the server, open the browser (C/D).
     const ctxDev = detectContext(dir);
     let url, handle;
+    const bridgeEnv = activityBridgeEnv(env);
     if (runtime.useDocker) {
       const plan = buildContainerPlan(dir, devArgs, ctxDev);
       url = plan.url;
@@ -234,9 +236,15 @@ export async function run(argv, ctx) {
     } else {
       url = deriveUrl(ctxDev.config || {}, devArgs.port).url;
       console.log(`  → starting dev … ${url}`);
-      handle = spawnNativeDev(runtime.runnerDir, dir, devArgs.port, { stdio: "piped", env: activityBridgeEnv(env) });
+      handle = spawnNativeDev(runtime.runnerDir, dir, devArgs.port, { stdio: "piped", env: bridgeEnv });
     }
 
+    // Heartbeat the hosted cockpit (G1) with the CLI version + this live localhost
+    // URL for the life of the run — CLI-side, using the cached bridge credential
+    // (no-op when none is cached). The runner keeps reporting file-saves itself.
+    const stopHeartbeat = startHeartbeatFromEnv(bridgeEnv, { url });
+    handle.done.finally(() => stopHeartbeat());
+
     // The runner's stdio is "piped" (its logs are held until the aha), so this
     // boot would otherwise be a silent 5–60s gap. Tick a spinner over it.
     const up = await waitForBoot(url, handle);
@@ -257,9 +265,8 @@ export async function run(argv, ctx) {
     printLiveEnding(tenant, url, formatElapsed(Date.now() - startedAt));
 
     // 7. hand the terminal to the running dev server until Ctrl-C.
-    console.log("\n  Streaming dev logs — edit + save to see reloads. Ctrl-C to stop.\n");
-    handle.child.stdout?.pipe(process.stdout);
-    handle.child.stderr?.pipe(process.stderr);
+    console.log("\n  Watching your store — edit content/home.html + save. Ctrl-C to stop.\n");
+    streamDevLogs(handle.child);
     return handle.done;
   } catch (e) {
     console.error(formatError(e));
@@ -323,9 +330,8 @@ async function runSampleStart(args, ctx, env, startedAt) {
     // non-blocking step later (see the run() note above).
     printSampleLiveEnding(url, formatElapsed(Date.now() - startedAt));
 
-    console.log("\n  Streaming preview logs — edit content/*.html + save to see reloads. Ctrl-C to stop.\n");
-    handle.child.stdout?.pipe(process.stdout);
-    handle.child.stderr?.pipe(process.stderr);
+    console.log("\n  Watching your store — edit content/*.html + save. Ctrl-C to stop.\n");
+    streamDevLogs(handle.child);
     return handle.done;
   } catch (e) {
     console.error(formatError(e));
@@ -430,7 +436,9 @@ async function prefetchRuntime(client, devArgs, env, runtime, ctx) {
     if (!(e instanceof NativeArtifactUnavailableError)) throw e;
     // Entitled artifact unavailable — stay native on the public runner (no Docker).
     try {
-      console.log(`  ~ entitled renderer unavailable (${e.message}) — using the public runner (no Docker).`);
+      // Normal path when the entitled artifact isn't configured for this
+      // deployment — use the public preview engine (no Docker). Silent: the
+      // download/install spinner below is the user-facing progress.
       runtime.runnerDir = await ensureSampleRenderer(devArgs, ctx, { env });
     } catch (e2) {
       // Only an actual "can't reach the public runner" failure should fall to
@@ -438,7 +446,7 @@ async function prefetchRuntime(client, devArgs, env, runtime, ctx) {
       // say) would otherwise be silently masked behind a confusing Docker fallback
       // that may not even be installed. Mirrors dev.mjs's runStandalone.
       if (!(e2 instanceof NativeArtifactUnavailableError)) throw e2;
-      console.log(`  ~ public runner unavailable (${e2.message}) — falling back to the Docker runner.`);
+      console.log(`  ~ couldn't fetch the store preview over the network — trying Docker instead.`);
       runtime.useDocker = true;
       await prefetchDockerLogin(client, devArgs, env);
     }
@@ -656,6 +664,59 @@ function connectClaude() {
   spawnSync("claude", [IDEAS[0]], { stdio: "inherit" });
 }
 
+/**
+ * Stream the running dev server's output in BUSINESS terms. The runner + Vite +
+ * Astro emit a lot of internal chatter (dependency optimization, HMR internals,
+ * build banners, "watching for file changes", pnpm tails). A developer cares
+ * about two things: that a save took effect, and any real error. So collapse a
+ * save-reload into one clean "↻ your store reloaded", drop the known internal
+ * noise, and pass anything else through (indented) so nothing important is
+ * hidden. Ctrl-C still tears the server down (the child owns the TTY signals).
+ */
+function streamDevLogs(child) {
+  // Startup churn + tool internals — never user-facing. Matched AFTER stripping
+  // the runner/Vite "HH:MM:SS " timestamp prefix (see `body` below), so a
+  // timestamped internal line like "10:50:17 [vite] connected" is still dropped.
+  const NOISE =
+    /^(\[vite\]|\[types\]|\[@astrojs|\[WARN\]|▲|┃|astro\s+v[\d.]|(Local|Network)\s+http|watching for file changes|Scope: all \d|copy-tenant-assets:|.*dependency optimized|.*optimized dependencies changed|.*program reload|\d+ deprecated|Packages:\s*\+|Progress:\s*resolved|Downloading @|node_modules\/|devDependencies:|\+\s+\w+@|Done in \d)/i;
+  // A real save-triggered reload (not startup "program reload" churn).
+  const RELOAD = /(hmr update|page reload)/i;
+  let reloadPending = null;
+  const emit = (line) => {
+    const t = line.replace(/\s+$/, "");
+    if (!t) return;
+    // The runner/Vite prefix most lines with an "HH:MM:SS " (or ".mmm ")
+    // timestamp — strip it before matching so the filters catch them.
+    const body = t.replace(/^\d{1,2}:\d{2}:\d{2}(\.\d+)?\s+/, "").replace(/^\s+/, "");
+    if (RELOAD.test(body)) {
+      if (reloadPending) return; // debounce a burst into one line
+      reloadPending = setTimeout(() => { reloadPending = null; }, 1000);
+      if (reloadPending.unref) reloadPending.unref();
+      process.stdout.write("  ↻ your store reloaded\n");
+      return;
+    }
+    if (NOISE.test(body)) return;
+    process.stdout.write(`  ${t}\n`);
+  };
+  lineStream(child.stdout, emit);
+  lineStream(child.stderr, emit);
+}
+
+/** Call `cb` once per complete line of `stream` (dependency-free line buffering). */
+function lineStream(stream, cb) {
+  if (!stream) return;
+  let buf = "";
+  stream.on("data", (chunk) => {
+    buf += chunk.toString();
+    let nl;
+    while ((nl = buf.indexOf("\n")) >= 0) {
+      cb(buf.slice(0, nl));
+      buf = buf.slice(nl + 1);
+    }
+  });
+  stream.on("end", () => { if (buf.trim()) cb(buf); });
+}
+
 // ── small prompt helpers (respect non-TTY so nothing hangs in CI) ────────────
 
 function isInteractive() {

package/src/dev-heartbeat.mjs

@@ -0,0 +1,92 @@
+/**
+ * CLI-side heartbeat for the local→hosted activity bridge (G1).
+ *
+ * While `tot dev` / `tot start` is running, the CLI (which knows its own
+ * version, the resolved runner version, the port + tenant, and the cached
+ * activity-bridge credential) POSTs a periodic heartbeat to the hosted
+ * `/api/dev/activity` endpoint. The hosted cockpit turns the latest heartbeat
+ * into a LIVE, clickable local-dev link + the running CLI version.
+ *
+ * It emits CLI-side (not from the runner) because the CLI is the one process
+ * that holds ALL of {version, port, tenant, bridge credential} — the runner
+ * keeps emitting file-save events as before. Same bearer + same endpoint as the
+ * file-save path; no new secret.
+ *
+ * Contract (identical posture to the runner's file-save bridge): best-effort,
+ * NEVER throws or blocks, the interval timer is unref'd so it can't hold the
+ * process open, and with no bridge credential (a bare `tot login`, an older
+ * session, or the zero-login `--sample` path) it's a silent no-op.
+ * Dependency-free (global fetch, Node 20+).
+ */
+import { CLI_VERSION, clientPackages } from "./mcp.mjs";
+
+/** ~10s between beats — frequent enough that the cockpit's ~30s live window
+ * tolerates a missed beat without the badge flapping, cheap enough to ignore. */
+const HEARTBEAT_INTERVAL_MS = 10_000;
+
+/**
+ * POST one heartbeat body, best-effort. No-op (returns undefined) without both
+ * an activity URL and a bearer token. Never throws — a failed/offline hosted
+ * worker just means the cockpit doesn't light up this beat.
+ * @param {{ activityUrl?: string, token?: string, url?: string,
+ *   cliVersion?: string, runnerVersion?: string|null }} args
+ */
+export function postHeartbeat({ activityUrl, token, url, cliVersion, runnerVersion } = {}) {
+  if (!activityUrl || !token) return undefined;
+  /** @type {Record<string, unknown>} */
+  const body = { event: "heartbeat", cliVersion, at: Date.now() };
+  if (runnerVersion) body.runnerVersion = runnerVersion;
+  if (url) body.url = url;
+  return fetch(`${String(activityUrl).replace(/\/+$/, "")}/api/dev/activity`, {
+    method: "POST",
+    headers: { "content-type": "application/json", authorization: `Bearer ${token}` },
+    body: JSON.stringify(body),
+  }).catch(() => {
+    /* best-effort — hosted panel just won't show this beat */
+  });
+}
+
+/**
+ * Start beating every `intervalMs` until the returned stop() is called. Fires
+ * one beat IMMEDIATELY so the cockpit lights up without waiting a full interval.
+ * Returns a no-op stop() when there's no bridge credential (sample / not-signed-
+ * in), so callers can wire it unconditionally.
+ * @param {{ activityUrl?: string, token?: string, url?: string,
+ *   cliVersion?: string, runnerVersion?: string|null, intervalMs?: number }} [opts]
+ * @returns {() => void} stop the heartbeat (idempotent).
+ */
+export function startDevHeartbeat({
+  activityUrl,
+  token,
+  url,
+  cliVersion = CLI_VERSION,
+  runnerVersion,
+  intervalMs = HEARTBEAT_INTERVAL_MS,
+} = {}) {
+  if (!activityUrl || !token) return () => {}; // no bridge / sample mode → no-op
+  const beat = () => postHeartbeat({ activityUrl, token, url, cliVersion, runnerVersion });
+  beat();
+  const timer = setInterval(beat, intervalMs);
+  if (typeof timer.unref === "function") timer.unref();
+  return () => clearInterval(timer);
+}
+
+/**
+ * Convenience wrapper for the runner-spawn sites: start a heartbeat from the
+ * same bridge env that's threaded to the runner ({TOT_DEV_ACTIVITY_URL,
+ * TOT_DEV_ACTIVITY_TOKEN}, or {} for the `--sample` path — which yields a no-op,
+ * exactly the desired "never leak a real credential from sample" behavior). The
+ * runner version defaults to whatever `tot dev` resolved this invocation
+ * (clientPackages().runner — null until the runner is resolved).
+ * @param {{ TOT_DEV_ACTIVITY_URL?: string, TOT_DEV_ACTIVITY_TOKEN?: string }} bridgeEnv
+ * @param {{ url?: string, runnerVersion?: string|null }} [opts]
+ * @returns {() => void} stop the heartbeat.
+ */
+export function startHeartbeatFromEnv(bridgeEnv, { url, runnerVersion } = {}) {
+  return startDevHeartbeat({
+    activityUrl: bridgeEnv?.TOT_DEV_ACTIVITY_URL,
+    token: bridgeEnv?.TOT_DEV_ACTIVITY_TOKEN,
+    url,
+    runnerVersion: runnerVersion ?? clientPackages().runner,
+  });
+}

package/src/mcp.mjs

@@ -23,6 +23,22 @@ export const CLI_VERSION = (() => {
   }
 })();
 
+// The resolved @tokenoftrust/storefront-runner version for THIS invocation, stashed
+// by `tot dev` once it resolves/probes the runner (setRunnerVersion). Null until then
+// — most commands never run the runner. Reported in the handshake (clientInfo.packages)
+// so telemetry sees the version of EVERY package running by default, not just the CLI.
+let RUNNER_VERSION = null;
+
+/** Record the runner version resolved this invocation, so the next MCP handshake reports it. */
+export function setRunnerVersion(v) {
+  RUNNER_VERSION = v || null;
+}
+
+/** The package-version map reported to the server by default: each package + its running version. */
+export function clientPackages() {
+  return { cli: CLI_VERSION, runner: RUNNER_VERSION };
+}
+
 /**
  * @param {string} baseUrl - MCP base URL; `/mcp` is appended if absent.
  * @param {{ token?: string, clientVersion?: string }} [opts] - optional developer OAuth
@@ -105,6 +121,14 @@ export function createMcpClient(baseUrl, opts = {}) {
   async function initialize(
     clientInfo = { name: "tot-cli", version: opts.clientVersion || CLI_VERSION },
   ) {
+    // Report the version of EVERY package running by default (cli + runner), not just
+    // the CLI. `version` stays the CLI version for back-compat with the existing
+    // server-side support-policy check (update-awareness Layer 2); `packages` is the
+    // richer per-package telemetry. Additive: a server that ignores `packages` still
+    // reads `version` exactly as before.
+    if (clientInfo && clientInfo.packages === undefined) {
+      clientInfo = { ...clientInfo, packages: clientPackages() };
+    }
     await callRaw("initialize", {
       protocolVersion: "2025-06-18",
       capabilities: {},

package/src/update-check-worker.mjs

@@ -7,6 +7,9 @@
  * Runs standalone (`node src/update-check-worker.mjs`), inheriting the parent env
  * (TOT_HOME / TOT_NPM_REGISTRY). Best-effort: any failure just exits quietly.
  */
-import { runRefresh } from "./update-check.mjs";
+import { runRefresh, runPolicyRefresh } from "./update-check.mjs";
 
-runRefresh().finally(() => process.exit(0));
+// Both best-effort + independent: the npm `latest` dist-tag (Layer 1) and the
+// storefront-hosted support policy (Layer 2). allSettled so one failing never
+// aborts the other; the process exits regardless.
+Promise.allSettled([runRefresh(), runPolicyRefresh()]).finally(() => process.exit(0));

package/src/update-check.mjs

@@ -35,6 +35,13 @@ export const CHECK_INTERVAL_MS = 24 * 60 * 60 * 1000; // 24h
 
 const PKG = "@tokenoftrust/cli";
 const DEFAULT_NPM_REGISTRY = "https://registry.npmjs.org";
+// Storefront-hosted, KV-dynamic CLI version-support policy (Layer 2 source #2 —
+// see auth.mjs for source #1, the MCP `cliPolicy`). PUBLIC GET returning
+// { minSupported?, recommended?, message? }; overridable like the npm registry.
+// NOTE the TRAILING SLASH: the deployed astro/CF route answers at
+// `/api/cli/policy/` (200 JSON); the slashless form 404s on the Worker. Use the
+// canonical trailing-slash URL so the fetch resolves.
+const DEFAULT_POLICY_URL = "https://storefront.tokenoftrust.workers.dev/api/cli/policy/";
 const FETCH_TIMEOUT_MS = 3000;
 
 /** Absolute path to the update-check cache for this environment. */
@@ -84,6 +91,55 @@ export function isNewer(latest, current) {
   return false;
 }
 
+/**
+ * Full-semver precedence compare for the SERVER-POLICY path only. Unlike isNewer
+ * (which strips the prerelease suffix, so it never nudges a stable user onto a
+ * prerelease), this honors prereleases per semver — so ToT's policy can steer
+ * rc→rc (recommend 1.3.1-rc.5 to someone on 1.3.1-rc.3) and treat a full release
+ * as newer than any of its prereleases (1.3.1 > 1.3.1-rc.5). Returns -1/0/1;
+ * malformed input compares as equal-ish (never throws).
+ */
+export function comparePolicyVersion(a, b) {
+  const parse = (s) => {
+    const [main, pre = ""] = String(s || "").split("-");
+    const nums = main.split(".").map((n) => parseInt(n, 10) || 0);
+    return { nums: [nums[0] || 0, nums[1] || 0, nums[2] || 0], pre: pre ? pre.split(".") : [] };
+  };
+  const x = parse(a);
+  const y = parse(b);
+  for (let i = 0; i < 3; i++) {
+    if (x.nums[i] !== y.nums[i]) return x.nums[i] > y.nums[i] ? 1 : -1;
+  }
+  // Equal main version: a version WITH a prerelease is LOWER than one without.
+  if (x.pre.length === 0 && y.pre.length === 0) return 0;
+  if (x.pre.length === 0) return 1;
+  if (y.pre.length === 0) return -1;
+  // Both prereleases: compare identifier by identifier (semver §11).
+  const n = Math.max(x.pre.length, y.pre.length);
+  for (let i = 0; i < n; i++) {
+    const xi = x.pre[i];
+    const yi = y.pre[i];
+    if (xi === undefined) return -1; // fewer identifiers → lower precedence
+    if (yi === undefined) return 1;
+    const xn = /^\d+$/.test(xi);
+    const yn = /^\d+$/.test(yi);
+    if (xn && yn) {
+      const d = parseInt(xi, 10) - parseInt(yi, 10);
+      if (d !== 0) return d > 0 ? 1 : -1;
+    } else if (xn !== yn) {
+      return xn ? -1 : 1; // numeric identifiers are lower precedence than alphanumeric
+    } else if (xi !== yi) {
+      return xi > yi ? 1 : -1;
+    }
+  }
+  return 0;
+}
+
+/** True if `target` is a strictly higher SEMVER (prerelease-aware) than `current`. */
+export function isNewerPolicy(target, current) {
+  return comparePolicyVersion(target, current) > 0;
+}
+
 /**
  * Decide what (if anything) to tell the user, from the cached state only.
  * Returns null or { level: "required"|"recommended"|"available", latest, message? }.
@@ -95,14 +151,17 @@ export function updateNotice(current, env = process.env) {
 
   const policy = cache.policy;
   if (policy) {
-    if (policy.minSupported && isNewer(policy.minSupported, current)) {
+    // Policy path uses the prerelease-aware compare so ToT can steer rc→rc and
+    // hard-gate a bad rc; the Layer-1 npm compare below deliberately stays on
+    // isNewer (never surfaces a same-release prerelease to a stable user).
+    if (policy.minSupported && isNewerPolicy(policy.minSupported, current)) {
       return {
         level: "required",
         latest: policy.recommended || cache.latest || policy.minSupported,
         message: policy.message,
       };
     }
-    if (policy.recommended && isNewer(policy.recommended, current)) {
+    if (policy.recommended && isNewerPolicy(policy.recommended, current)) {
       return { level: "recommended", latest: policy.recommended, message: policy.message };
     }
   }
@@ -180,6 +239,33 @@ export function recordServerPolicy(policy, env = process.env) {
   if (policy && typeof policy === "object") writeCache({ policy }, env);
 }
 
+/**
+ * Fetch the STOREFRONT-hosted CLI version policy (Layer 2, source #2) and record
+ * it. A dependency-free public GET, best-effort like runRefresh: never throws,
+ * never blocks. URL overridable via TOT_CLI_POLICY_URL (like TOT_NPM_REGISTRY).
+ * Only records when the body carries at least one policy field, so an empty
+ * `{}` (the route's unset default) is a true no-op and can't clobber an
+ * MCP-sourced policy already in the cache.
+ */
+export async function runPolicyRefresh(env = process.env) {
+  try {
+    const url = env.TOT_CLI_POLICY_URL || DEFAULT_POLICY_URL;
+    const res = await fetch(url, {
+      headers: { accept: "application/json" },
+      signal: AbortSignal.timeout(FETCH_TIMEOUT_MS),
+    });
+    if (!res.ok) return;
+    const body = await res.json();
+    if (!body || typeof body !== "object") return;
+    const { minSupported, recommended, message } = body;
+    if (minSupported || recommended || message) {
+      recordServerPolicy({ minSupported, recommended, message }, env);
+    }
+  } catch {
+    /* best-effort: offline / timeout / bad JSON / gated host — just skip */
+  }
+}
+
 /**
  * Spawn the cache refresh in a DETACHED, unref'd child so it never delays this
  * process or holds it open. Skips when the cache is still fresh. Never throws.