@tokenoftrust/cli 1.3.0-rc.4 → 1.3.1-rc.1

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@tokenoftrust/cli",
-  "version": "1.3.0-rc.4",
+  "version": "1.3.1-rc.1",
   "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,18 +32,19 @@
  * 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";
 import { openBrowser, waitForServer, firstFreePort } from "../open.mjs";
+import { startProgress } from "../progress.mjs";
 import {
   scaffoldSample, isSampleCheckout, sampleConfig,
   resolveRendererSource as resolveLocalRendererSource, newestCachedRunner, SAMPLE_DIR_NAME,
@@ -417,7 +418,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}` };
   }
@@ -426,11 +441,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]}.`;
@@ -442,9 +459,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;
 }
 
 /**
@@ -561,7 +609,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 });
@@ -571,6 +621,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:
@@ -604,6 +680,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;
   }
 
@@ -628,9 +705,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
     }
   }
 
@@ -646,6 +732,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(
@@ -657,11 +744,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);
@@ -693,11 +782,23 @@ export async function installRunnerTarball({ source, version, isUrl = true, stri
   const marker = join(runnerDir, ".tot-cache-complete");
   if (existsSync(marker)) return runnerDir; // already downloaded + installed
 
-  log(`~ preparing the native renderer (version ${version}, first run only)...`);
+  // 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: 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) await downloadFile(source, archivePath);
+    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 store preview engine…");
+      try {
+        await downloadFile(source, archivePath);
+      } finally {
+        spin.stop();
+      }
+    }
     if (!existsSync(archivePath)) {
       throw new Error(`renderer tarball not found: ${archivePath}`);
     }
@@ -705,8 +806,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.
@@ -776,14 +893,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 "";
 }
 
 /**

package/src/commands/start.mjs

@@ -53,6 +53,7 @@ import { createMcpClient } from "../mcp.mjs";
 import { establishSession, AuthUnavailableError } from "../auth.mjs";
 import { CliError, fail, formatError, exitCodeFor } from "../errors.mjs";
 import { openBrowser, waitForServer, firstFreePort } from "../open.mjs";
+import { startProgress } from "../progress.mjs";
 import { defaultLastTenantPath, readLastTenant, writeLastTenant } from "../last-tenant.mjs";
 import { collectChecks } from "./doctor.mjs";
 import { normalizeStores, storeListError, checkoutTenant } from "./checkout.mjs";
@@ -236,10 +237,9 @@ export async function run(argv, ctx) {
       handle = spawnNativeDev(runtime.runnerDir, dir, devArgs.port, { stdio: "piped", env: activityBridgeEnv(env) });
     }
 
-    const up = await Promise.race([
-      waitForServer(url, { until: () => handle.exited }),
-      handle.done.then(() => "exited"),
-    ]);
+    // 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);
     if (up !== true) {
       throw new CliError("the dev server didn't come up", {
         next: `cd ${tenant} && tot dev   (to watch the runner logs)`,
@@ -257,9 +257,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));
@@ -307,10 +306,7 @@ async function runSampleStart(args, ctx, env, startedAt) {
     console.log(`  → starting the free local preview … ${url}`);
     const handle = spawnNativeDev(runnerDir, workspace, devArgs.port, { stdio: "piped" });
 
-    const up = await Promise.race([
-      waitForServer(url, { until: () => handle.exited }),
-      handle.done.then(() => "exited"),
-    ]);
+    const up = await waitForBoot(url, handle);
     if (up !== true) {
       throw new CliError("the local preview server didn't come up", {
         next: `cd ${SAMPLE_DIR_NAME} && tot dev --sample   (to watch the runner logs)`,
@@ -326,9 +322,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));
@@ -433,7 +428,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
@@ -441,7 +438,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);
     }
@@ -569,6 +566,30 @@ async function ensureCheckout(client, tenant, dir, env) {
   console.log(`  ✓ checked out ./${tenant}`);
 }
 
+/**
+ * Wait for the dev server to answer while showing progress, then return the
+ * `waitForServer` result ("exited" if the runner died first). Both the runner
+ * (native or Docker) runs with "piped" stdio here, so its boot logs are withheld
+ * until the aha — without this the terminal is a silent 5–60s gap that reads as
+ * hung (the D1 "perceived speed" problem). The spinner keeps the interval well
+ * under 5s and, once past the warm-boot window, explains the first-render cost.
+ */
+async function waitForBoot(url, handle) {
+  const spin = startProgress("starting the dev server…", {
+    stages: [
+      { afterMs: 6000, text: "compiling your store — first render can take a moment…" },
+    ],
+  });
+  try {
+    return await Promise.race([
+      waitForServer(url, { until: () => handle.exited }),
+      handle.done.then(() => "exited"),
+    ]);
+  } finally {
+    spin.stop();
+  }
+}
+
 /**
  * Format elapsed milliseconds as a short human string for the "you're live"
  * ending (A3 — measure, don't just claim, "instant"). Pure + exported so it's
@@ -635,6 +656,54 @@ 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.
+  const NOISE =
+    /^\s*(\[@astrojs|astro\s+v[\d.]|┃|▲|watching for file changes|Scope: all \d|copy-tenant-assets:|.*dependency optimized|.*optimized dependencies changed|.*program reload|\[vite\] connected|\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;
+    if (RELOAD.test(t)) {
+      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(t)) 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/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/progress.mjs

@@ -0,0 +1,101 @@
+/**
+ * A dependency-free, non-blocking progress indicator for the "and then it just
+ * runs" waits — the first-run renderer download and the dev server's cold boot,
+ * where the CLI would otherwise sit SILENT for tens of seconds (piped runner
+ * logs, a background fetch) and read as hung. Node built-ins only.
+ *
+ * Two behaviours, chosen from whether stderr is a TTY:
+ *   - TTY   → an in-place braille spinner rewritten with \r, showing an elapsed
+ *             seconds counter, so the terminal visibly ticks.
+ *   - non-TTY (CI, piped) → NO \r animation (that spams a log with control
+ *             chars); instead one line at start and then a heartbeat line every
+ *             ~10s, so a CI log shows liveness without a wall of frames.
+ *
+ * Both surface staged labels: pass `stages: [{ afterMs, text }]` and the label
+ * advances as the wait crosses each threshold (e.g. "starting…" → "compiling
+ * your store (first render)…"), so a long wait explains itself instead of
+ * staring back blankly.
+ */
+
+const FRAMES = ["⠋", "⠙", "⠹", "⠸", "⠼", "⠴", "⠦", "⠧", "⠇", "⠏"];
+const CLEAR_LINE = "\r\x1b[K";
+
+/**
+ * Given the elapsed ms and the (optionally staged) labels, return the label to
+ * show right now: the last stage whose `afterMs` has passed, else `initial`.
+ * Pure + exported so the staging is unit-tested without any timers or TTY.
+ * @param {string} initial
+ * @param {Array<{afterMs:number,text:string}>} stages
+ * @param {number} elapsedMs
+ * @returns {string}
+ */
+export function stageLabel(initial, stages, elapsedMs) {
+  let label = initial;
+  for (const s of stages || []) {
+    if (elapsedMs >= s.afterMs) label = s.text;
+  }
+  return label;
+}
+
+/**
+ * Start a progress indicator. Returns a handle with `stop(finalText?)` — always
+ * call it (a `finally` is ideal) so the interval clears and, on a TTY, the
+ * spinner line is erased. Safe to call `stop` more than once.
+ *
+ * @param {string} initialText the label shown until the first stage (if any).
+ * @param {{ stream?: NodeJS.WriteStream, stages?: Array<{afterMs:number,text:string}>,
+ *   isTTY?: boolean, intervalMs?: number, heartbeatMs?: number, now?: () => number }} [opts]
+ * @returns {{ stop: (finalText?: string) => void }}
+ */
+export function startProgress(initialText, opts = {}) {
+  const {
+    stream = process.stderr,
+    stages = [],
+    isTTY = Boolean(stream.isTTY),
+    intervalMs = isTTY ? 90 : 1000,
+    heartbeatMs = 10000,
+    now = Date.now,
+  } = opts;
+
+  const startedAt = now();
+  let frame = 0;
+  let lastHeartbeat = startedAt;
+  let stopped = false;
+
+  const secs = () => Math.floor((now() - startedAt) / 1000);
+  const label = () => stageLabel(initialText, stages, now() - startedAt);
+
+  function tick() {
+    if (stopped) return;
+    if (isTTY) {
+      frame = (frame + 1) % FRAMES.length;
+      stream.write(`${CLEAR_LINE}  ${FRAMES[frame]} ${label()} (${secs()}s)`);
+    } else if (now() - lastHeartbeat >= heartbeatMs) {
+      lastHeartbeat = now();
+      stream.write(`  … ${label()} (${secs()}s)\n`);
+    }
+  }
+
+  // Announce immediately so there's never a silent lead-in, then tick.
+  if (isTTY) {
+    stream.write(`  ${FRAMES[0]} ${initialText} (0s)`);
+  } else {
+    stream.write(`  … ${initialText}\n`);
+  }
+  const timer = setInterval(tick, intervalMs);
+  if (typeof timer.unref === "function") timer.unref(); // never keep the process alive
+
+  return {
+    stop(finalText) {
+      if (stopped) return;
+      stopped = true;
+      clearInterval(timer);
+      if (isTTY) {
+        stream.write(CLEAR_LINE); // erase the spinner line
+        if (finalText) stream.write(`  ${finalText}\n`);
+      } else if (finalText) {
+        stream.write(`  ${finalText}\n`);
+      }
+    },
+  };
+}

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.