@tokenoftrust/cli 1.3.3-rc.0 → 1.3.3

package/package.json

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

@@ -18,11 +18,14 @@
  *
  * Dependency-free (global fetch + `git` via child_process).
  */
-import { execFileSync } from "node:child_process";
+import { execFile } from "node:child_process";
+import { promisify } from "node:util";
 import { createMcpClient } from "../mcp.mjs";
 import { establishSession, AuthUnavailableError } from "../auth.mjs";
 import { CliError, fail, formatError } from "../errors.mjs";
 
+const execFileP = promisify(execFile);
+
 const DEFAULT_MCP_URL = "https://mcp.tokenoftrust.com";
 
 function parseArgs(argv) {
@@ -181,23 +184,28 @@ export async function checkoutTenant(client, { tenant, tag = "main", cloneDir =
   if (!cloneDir) {
     return { gitRemote, cloneUrl, publicUrl, cloned: false, dir: null, head: null };
   }
-  const { dir, head } = cloneRepo(gitRemote, cloneDir, redact);
+  const { dir, head } = await cloneRepo(gitRemote, cloneDir, redact);
   return { gitRemote, cloneUrl, publicUrl, cloned: true, dir, head };
 }
 
-/** git clone the authenticated remote into `dir`. Throws CliError on failure. */
-function cloneRepo(gitRemote, dir, redact) {
-  const git = (cargs) =>
-    execFileSync("git", cargs, { stdio: ["ignore", "pipe", "pipe"] }).toString();
+/**
+ * git clone the authenticated remote into `dir`. Throws CliError on failure.
+ * Runs git as a NON-BLOCKING child process (promisified execFile) so the clone
+ * doesn't stall the Node event loop — `tot start` runs this inside a
+ * `Promise.all([...])` alongside the renderer prefetch, and a synchronous clone
+ * would serialize what's meant to overlap.
+ */
+async function cloneRepo(gitRemote, dir, redact) {
+  const git = async (cargs) => (await execFileP("git", cargs)).stdout.toString();
   console.log(`+ git clone → ${dir}`);
   try {
-    git(["clone", gitRemote, dir]);
+    await git(["clone", gitRemote, dir]);
   } catch (e) {
     throw new CliError(`clone failed: ${redact(String(e.stderr || e.message || e))}`, {
       next: `check the target dir is empty and you can reach the remote, then re-run`,
     });
   }
-  const head = git(["-C", dir, "log", "-1", "--oneline"]).trim();
+  const head = (await git(["-C", dir, "log", "-1", "--oneline"])).trim();
   return { dir, head };
 }
 

package/src/commands/dev.mjs

@@ -39,7 +39,7 @@ 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, setRunnerVersion } from "../mcp.mjs";
+import { createMcpClient, CLI_VERSION, setRunnerVersion, versionStamp } from "../mcp.mjs";
 import { establishSession } from "../auth.mjs";
 import { defaultCredentialsPath, readCredentials } from "../token-store.mjs";
 import { CliError, fail, formatError } from "../errors.mjs";
@@ -50,6 +50,7 @@ import {
   resolveRendererSource as resolveLocalRendererSource, newestCachedRunner, SAMPLE_DIR_NAME,
 } from "../sample.mjs";
 import { startHeartbeatFromEnv } from "../dev-heartbeat.mjs";
+import { streamDevLogs } from "../dev-logs.mjs";
 
 /** The published runner image (--docker fallback). Override with --image / TOT_DEV_IMAGE. */
 const DEFAULT_DEV_IMAGE =
@@ -162,11 +163,11 @@ async function runStandalone(workspace, args, ctx) {
       // configured. Docker is the last resort only if the public runner is also
       // unreachable (offline).
       try {
-        console.error(`~ entitled renderer unavailable (${e.message}) — using the public runner (no Docker).`);
+        console.error(`~ couldn't set up your store preview the usual way (${e.message}) — using the fallback preview engine instead (no Docker needed).`);
         return await runNativePublic(workspace, args, ctx);
       } catch (e2) {
         if (e2 instanceof NativeArtifactUnavailableError) {
-          console.error(`~ public runner unavailable (${e2.message}) — falling back to the Docker runner.`);
+          console.error(`~ couldn't reach the fallback preview engine either (${e2.message}) — switching to the Docker runner.`);
           return runContainer(workspace, args, ctx);
         }
         console.error(formatError(e2));
@@ -203,7 +204,7 @@ async function runNativePublic(workspace, args, ctx) {
   } catch (e) {
     throw new NativeArtifactUnavailableError(String(e?.message || e));
   }
-  printDevBanner({ tenant: cfg.tenant || null, url });
+  printDevBanner({ tenant: cfg.tenant || null, url }, "native (public)");
   return bootNative(runnerDir, workspace, port, url, args);
 }
 
@@ -244,7 +245,13 @@ function runMonorepo(ctx, argv) {
   }
   const env = { ...process.env, ...activityBridgeEnv(process.env) };
   return new Promise((resolvePromise) => {
-    const child = spawn(process.execPath, [script, ...argv], { stdio: "inherit", env });
+    // Pipe + stream the runner's output in the same quiet, business voice
+    // `tot start` uses (save→reload collapsed, vite/astro noise dropped, real
+    // errors passed through) instead of inheriting the raw firehose. Ctrl-C
+    // 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);
     child.on("exit", (code) => resolvePromise(code ?? 0));
     child.on("error", (e) => {
       console.error(`✗ could not start the dev runner: ${e.message}`);
@@ -280,7 +287,7 @@ async function runNative(workspace, args, ctx) {
 
   const runnerDir = await ensureRendererArtifact(args);
 
-  printDevBanner({ tenant: cfg.tenant || null, url });
+  printDevBanner({ tenant: cfg.tenant || null, url }, "native");
 
   return bootNative(runnerDir, workspace, port, url, args);
 }
@@ -309,7 +316,13 @@ export function bootNativeEnv(args) {
 
 export function bootNative(runnerDir, workspace, port, url, args) {
   const bridgeEnv = bootNativeEnv(args);
-  const handle = spawnNativeDev(runnerDir, workspace, port, { stdio: "inherit", env: bridgeEnv });
+  // Pipe the runner's stdio and stream it in the same quiet, business voice
+  // `tot start` uses (spawnNativeDev(..., { stdio: "piped" }) + streamDevLogs):
+  // save→reload collapses to "↻ your store reloaded", vite/astro noise is
+  // 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);
 
   // 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
@@ -369,12 +382,13 @@ async function runSample(args, ctx) {
 }
 
 /** The free-taste banner — honest about what this is, and what unlocks the real thing. */
-export function printSampleBanner({ url }) {
+export function printSampleBanner({ url }, mode = "sample") {
   console.error(`\n  tot dev --sample — free local preview (sample vape store)`);
   console.error(`  ➜  Local:    ${url}`);
   console.error(`  ➜  Edit:     content/home.html or theme.json + save → the browser reloads`);
   console.error(`  ➜  FREE local preview — no login, no ToT account, nothing published. Ctrl-C to stop.`);
-  console.error(`     Connect the ToT MCP for your REAL store, AI editing & compliance previews.\n`);
+  console.error(`     Connect the ToT MCP for your REAL store, AI editing & compliance previews.`);
+  console.error("  " + versionStamp(mode) + "\n");
 }
 
 /**
@@ -583,10 +597,12 @@ export async function ensureRendererArtifact(args, { client: providedClient } =
   }
 
   try {
-    return await installRunnerTarball(
+    const runnerDir = await installRunnerTarball(
       { source: credential.url, version: credential.version, isUrl: true },
       { log: (m) => console.error(m) },
     );
+    setRunnerVersion(credential.version); // telemetry: stamp the entitled runner version, like ensureSampleRenderer
+    return runnerDir;
   } catch (e) {
     throw new NativeArtifactUnavailableError(String(e?.message || e));
   }
@@ -991,9 +1007,15 @@ async function runContainer(workspace, args, ctx) {
     return e instanceof CliError ? (e.exitCode ?? 2) : 2;
   }
 
-  printDevBanner(plan);
+  printDevBanner(plan, "docker");
 
-  const handle = await spawnDevContainer(plan, args, { stdio: "inherit" });
+  // Pipe + stream the container's output in the same quiet, business voice
+  // `tot start` uses for the Docker path (spawnDevContainer(..., { stdio:
+  // "piped" }) + streamDevLogs). Not an interactive attach (no `-it`), so
+  // 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);
 
   // 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
@@ -1088,11 +1110,12 @@ export function buildContainerPlan(workspace, args, _ctx) {
 }
 
 /** The crafted "here's your running store" block (Vite/`vercel dev`-grade). */
-export function printDevBanner(plan) {
+export function printDevBanner(plan, mode) {
   console.error(`\n  tot dev — ${plan.tenant || "(tenant)"}`);
   console.error(`  ➜  Local:    ${plan.url}`);
   console.error(`  ➜  Edit:     content/home.html + save → the browser reloads`);
-  console.error(`  ➜  Private local preview — nothing is published. Ctrl-C to stop.\n`);
+  console.error(`  ➜  Private local preview — nothing is published. Ctrl-C to stop.`);
+  console.error("  " + versionStamp(mode) + "\n");
 }
 
 /**

package/src/commands/doctor.mjs

@@ -23,6 +23,7 @@ import { existsSync, mkdirSync } from "node:fs";
 import { homedir } from "node:os";
 import { join } from "node:path";
 import { hasOperatorCreds } from "../auth.mjs";
+import { clientPackages, osLabel } from "../mcp.mjs";
 import { defaultCredentialsPath, readCredentials, isExpired } from "../token-store.mjs";
 import { dockerAvailable, tryStartDocker } from "./dev.mjs";
 import { loginAndCache } from "./login.mjs";
@@ -60,6 +61,12 @@ export function collectChecks(_ctx, env = process.env) {
   const nodeMajor = Number(process.versions.node.split(".")[0]);
   checks.push({ name: "node >= 20", pass: nodeMajor >= 20, detail: `have ${process.versions.node}`, blocking: true });
 
+  // Informational: the versions + OS this invocation is running on — the same
+  // context the run banners/error footers stamp, surfaced up front for a bug report.
+  // (No resolved runner here — `tot doctor` never spawns the runner.)
+  checks.push({ name: "tot CLI", pass: true, detail: `v${clientPackages().cli}`, blocking: false });
+  checks.push({ name: "OS", pass: true, detail: osLabel(), blocking: false });
+
   const gitRes = spawnSync("git", ["--version"], {
     encoding: "utf8",
     stdio: ["ignore", "pipe", "ignore"],

package/src/commands/start.mjs

@@ -49,7 +49,7 @@ import { resolve } from "node:path";
 import { createInterface } from "node:readline/promises";
 
 import { detectContext } from "../context.mjs";
-import { createMcpClient } from "../mcp.mjs";
+import { createMcpClient, versionStamp } from "../mcp.mjs";
 import { establishSession, AuthUnavailableError } from "../auth.mjs";
 import { CliError, fail, formatError, exitCodeFor } from "../errors.mjs";
 import { openBrowser, waitForServer, firstFreePort } from "../open.mjs";
@@ -65,6 +65,7 @@ import {
 } from "./dev.mjs";
 import { scaffoldSample, isSampleCheckout, sampleConfig, SAMPLE_DIR_NAME } from "../sample.mjs";
 import { startHeartbeatFromEnv } from "../dev-heartbeat.mjs";
+import { streamDevLogs } from "../dev-logs.mjs";
 import { IDEAS } from "./ideas.mjs";
 
 const DEFAULT_MCP_URL = "https://mcp.tokenoftrust.com";
@@ -617,6 +618,7 @@ function printLiveEnding(tenant, url, elapsed) {
   console.log(`  ✨ You're live.${elapsed ? `  (${elapsed})` : ""}`);
   console.log(`     ${url}`);
   console.log("     Edit content/home.html + save → it reloads.");
+  console.log("  " + versionStamp("native"));
   console.log("");
   console.log("  Now try, in Claude:");
   console.log(`     "${IDEAS[0]}"`);
@@ -637,6 +639,7 @@ function printSampleLiveEnding(url, elapsed) {
   console.log(`     ${url}`);
   console.log("     Edit content/home.html + save → it reloads. The age-gate + nicotine warning");
   console.log("     you see ARE Token of Trust compliance rendering — live, on your machine.");
+  console.log("  " + versionStamp("sample"));
   console.log("");
   console.log("  This is a sample store, running locally, for free. Connect the ToT MCP to use");
   console.log("  your REAL store, AI editing, and live compliance previews:");
@@ -664,59 +667,6 @@ 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/commands/submit.mjs

@@ -35,18 +35,21 @@ import { createMcpClient } from "../mcp.mjs";
 import { establishSession, AuthUnavailableError } from "../auth.mjs";
 import { validateTenant, ERROR } from "../validate.mjs";
 import { openBrowser } from "../open.mjs";
+import { startProgress } from "../progress.mjs";
 import { fail } from "../errors.mjs";
 
 const DEFAULT_MCP_URL = "https://mcp.tokenoftrust.com";
 const DEFAULT_REF = "preview";
 
-function parseArgs(argv) {
-  const a = { mcp: null, identity: null, ref: DEFAULT_REF, skipValidate: false, noWait: false, watch: false, noOpen: false, help: false };
+export function parseArgs(argv) {
+  const a = { mcp: null, identity: null, ref: DEFAULT_REF, skipValidate: false, noWait: false, watch: false, noOpen: false, message: null, summary: null, help: false };
   for (let i = 0; i < argv.length; i++) {
     const t = argv[i];
     if (t === "--mcp") a.mcp = argv[++i];
     else if (t === "--identity") a.identity = argv[++i];
     else if (t === "--ref") a.ref = argv[++i];
+    else if (t === "-m" || t === "--message") a.message = argv[++i];
+    else if (t === "--summary") a.summary = argv[++i];
     else if (t === "--skip-validate") a.skipValidate = true;
     else if (t === "--no-wait") a.noWait = true;
     else if (t === "--watch") a.watch = true;
@@ -62,9 +65,14 @@ const USAGE = `tot submit — submit your store for preview
   tot submit --watch            stay attached through reconcile + compliance + accept (long-poll)
   tot submit --skip-validate    push without the local lint (not recommended)
   tot submit --ref <name>       push ref (default: ${DEFAULT_REF})
+  tot submit -m "<title>"       one-line summary of what changed (the approver sees this)
+  tot submit --summary "<text>" longer description to accompany the title
   tot submit --no-wait          push and exit without polling for the reconcile result
   tot submit --no-open          don't open the preview URL in the browser on success
-  tot submit --mcp <url>        MCP base URL (default: env MCP_BASE_URL / TOT_MCP_URL)`;
+  tot submit --mcp <url>        MCP base URL (default: env MCP_BASE_URL / TOT_MCP_URL)
+
+  If you omit -m, a summary is generated from git (commit subject + the diff vs
+  what's live in preview) so the change record the approver reviews is never blank.`;
 
 // Default bounded wait (~20s, matching the pre-E2 fixed poll's total budget) vs.
 // --watch's longer per-call long-poll + more attempts (~8 min ceiling) for a dev
@@ -74,6 +82,38 @@ const WATCH_POLL = { attempts: 24, delayMs: 20_000, waitMs: 20_000, untilShipped
 
 const redactUrl = (s) => String(s).replace(/\/\/[^/@\s]*@/g, "//***@");
 
+const SUMMARY_FILE_LIMIT = 12;
+
+/**
+ * Build the human "what changed" summary the approver is greeted with. Explicit
+ * `--message` (title) / `--summary` (body) always win; when a title is omitted we
+ * fall back to the HEAD commit subject, and the body always carries the git delta
+ * (shortstat + changed files) so a submit never leaves the approver a blank record.
+ * Pure (all git I/O is done by the caller and passed in) so it's unit-tested.
+ * @param {{ message?: string|null, summary?: string|null, headSubject?: string,
+ *   statLine?: string, files?: string[] }} input
+ * @returns {{ title: string, body: string[], autoTitle: boolean }}
+ */
+export function buildChangeSummary({ message, summary, headSubject = "", statLine = "", files = [] } = {}) {
+  const title = (message && message.trim()) || headSubject.trim() || "(untitled change)";
+  const body = [];
+  if (summary && summary.trim()) body.push(...summary.trim().split(/\r?\n/).map((l) => l.trimEnd()));
+  if (statLine) body.push(statLine);
+  for (const f of files.slice(0, SUMMARY_FILE_LIMIT)) body.push(`· ${f}`);
+  if (files.length > SUMMARY_FILE_LIMIT) body.push(`· … +${files.length - SUMMARY_FILE_LIMIT} more file(s)`);
+  return { title, body, autoTitle: !(message && message.trim()) };
+}
+
+/** Print the change summary block. Push-only: this is what a human relays to the
+ *  approver, or the agent carries into change_open — the CLI does not open the
+ *  change record itself. */
+function printChangeSummary({ title, body, autoTitle }) {
+  console.log(`\n  Change summary (for the approver / the change record):`);
+  console.log(`    ${title}`);
+  for (const l of body) console.log(`      ${l}`);
+  if (autoTitle) console.log(`  (auto-generated from git — pass -m "…" / --summary "…" to refine)`);
+}
+
 /** @param {string[]} argv @param {any} ctx */
 export async function run(argv, ctx) {
   const env = process.env;
@@ -118,6 +158,32 @@ export async function run(argv, ctx) {
     return 1;
   }
   const short = commit.slice(0, 9);
+
+  // Build the "what changed" summary the approver is greeted with — BEFORE the
+  // push, because `git push` fast-forwards the local origin/<ref> tracking ref and
+  // would zero out the "vs what's live in preview" diff. Explicit -m/--summary win;
+  // otherwise it's generated from git so the change record is never blank. Push-only:
+  // we surface it (the agent carries it into change_open) — the CLI never opens the
+  // change record itself.
+  const gitSafe = (cargs) => {
+    try {
+      return git(cargs);
+    } catch {
+      return "";
+    }
+  };
+  const headSubject = gitSafe(["log", "-1", "--format=%s"]).trim();
+  const trackingRef = `refs/remotes/origin/${args.ref}`;
+  const base = gitSafe(["rev-parse", "--verify", "--quiet", trackingRef]).trim()
+    ? trackingRef
+    : gitSafe(["rev-parse", "--verify", "--quiet", "HEAD~1"]).trim()
+      ? "HEAD~1"
+      : "";
+  const nameCmd = base ? ["diff", "--name-only", `${base}..HEAD`] : ["show", "--name-only", "--format=", "HEAD"];
+  const files = gitSafe(nameCmd).split("\n").map((s) => s.trim()).filter(Boolean);
+  const statLine = base ? gitSafe(["diff", "--shortstat", `${base}..HEAD`]).trim() : "";
+  const changeSummary = buildChangeSummary({ message: args.message, summary: args.summary, headSubject, statLine, files });
+
   console.error(`~ pushing ${short} → ${args.ref} (origin)`);
   try {
     const out = git(["push", "-f", "origin", `HEAD:refs/heads/${args.ref}`]);
@@ -132,10 +198,12 @@ export async function run(argv, ctx) {
     return 1;
   }
   console.log(`\n+ submitted ${short} to ${args.ref}.`);
+  printChangeSummary(changeSummary);
 
   // 3. report reconcile + compliance + preview URL from the MCP (graceful seam).
   const baseUrl = args.mcp || env.MCP_BASE_URL || env.TOT_MCP_URL || DEFAULT_MCP_URL;
   const client = createMcpClient(baseUrl);
+  let progress = null;
   try {
     // Attach auth before the first server call (developer bearer pre-initialize,
     // operator credential_validate post-initialize) — see establishSession.
@@ -143,20 +211,38 @@ export async function run(argv, ctx) {
     // Set the active tenant so preview_status reads the right scope (it keys on
     // the session's tenant + the commit — no tenant arg of its own).
     await client.callTool("client_switch", { tenant });
-    const status = args.noWait
-      ? normalizePreviewStatus(await client.callTool("preview_status", { commit }))
-      : await pollPreviewStatus(client, commit, {
-          ...(args.watch ? WATCH_POLL : DEFAULT_POLL),
-          onTick: (s, i) => {
-            if (s.status === "pending") console.error(`~ reconcile running for ${short} … (${i + 1})`);
-            else if (s.status === "reconciled" && !s.shipped) {
-              console.error(`~ reconciled — waiting for a ship decision … (${i + 1})`);
-            }
-          },
-        });
+    let status;
+    if (args.noWait) {
+      status = normalizePreviewStatus(await client.callTool("preview_status", { commit }));
+    } else {
+      // One in-place status line (TTY: a spinner with an elapsed-seconds counter;
+      // non-TTY: a ~10s heartbeat) instead of a newline per poll — the wait reads
+      // as live, not as a growing wall of "(1)…(8)" lines. The counter keeps
+      // ticking on its own 90ms timer even while a single poll long-polls for
+      // waitMs, so elapsed time is real wall-clock, not the attempt count.
+      let phase = "reconcile";
+      progress = startProgress(`reconcile running for ${short}…`, {
+        stages: [{ afterMs: 45_000, text: `still reconciling ${short}… (larger changes take longer)` }],
+      });
+      status = await pollPreviewStatus(client, commit, {
+        ...(args.watch ? WATCH_POLL : DEFAULT_POLL),
+        onTick: (s) => {
+          // Reconcile is done but we're still waiting on a ship decision (--watch):
+          // swap the label so the single line reflects the new phase, timer resets.
+          if (s.status === "reconciled" && !s.shipped && phase !== "ship") {
+            phase = "ship";
+            progress.stop();
+            progress = startProgress(`reconciled ${short} — waiting for a ship decision…`);
+          }
+        },
+      });
+      progress.stop();
+      progress = null;
+    }
     reportStatus(status, tenant, { open: !args.noOpen });
     return status?.status === "failed" ? 1 : 0;
   } catch (e) {
+    progress?.stop();
     if (e instanceof AuthUnavailableError) {
       console.log(`  (sign in to see the reconcile/compliance/preview result — ${e.hint || "developer sign-in pending"})`);
     } else {

package/src/dev-heartbeat.mjs

@@ -18,12 +18,18 @@
  * session, or the zero-login `--sample` path) it's a silent no-op.
  * Dependency-free (global fetch, Node 20+).
  */
+import os from "node:os";
 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;
 
+/** The developer's OS, structured + queryable for the hosted telemetry. Computed
+ * once — the OS doesn't change mid-run. `os`=platform (darwin/linux/win32),
+ * `osVersion`=kernel release, `arch`=CPU arch (arm64/x64). */
+const OS_INFO = { os: os.platform(), osVersion: os.release(), arch: os.arch() };
+
 /**
  * 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
@@ -34,7 +40,7 @@ const HEARTBEAT_INTERVAL_MS = 10_000;
 export function postHeartbeat({ activityUrl, token, url, cliVersion, runnerVersion, editor, cwd } = {}) {
   if (!activityUrl || !token) return undefined;
   /** @type {Record<string, unknown>} */
-  const body = { event: "heartbeat", cliVersion, at: Date.now() };
+  const body = { event: "heartbeat", cliVersion, at: Date.now(), ...OS_INFO };
   if (runnerVersion) body.runnerVersion = runnerVersion;
   if (url) body.url = url;
   // The developer's terminal $EDITOR (if set) — lets the cockpit suggest the exact

package/src/dev-logs.mjs

@@ -0,0 +1,67 @@
+/**
+ * Shared dev-server log streaming — the single source of the "quiet, business-
+ * voice" runner output used by BOTH `tot start` (start.mjs) and `tot dev`
+ * (dev.mjs). Extracted so the two entrypoints stream identically instead of one
+ * inheriting the raw vite/astro firehose while the other collapses it.
+ *
+ * Dependency-free (no imports) — pure line buffering + filtering over a child's
+ * stdout/stderr.
+ */
+
+/**
+ * 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).
+ * @param {import("node:child_process").ChildProcess} child
+ */
+export 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).
+ * @param {import("node:stream").Readable|null|undefined} stream
+ * @param {(line: string) => void} cb
+ */
+export 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); });
+}

package/src/errors.mjs

@@ -8,9 +8,27 @@
  *   - anything else (thrown Error, AuthUnavailableError, a string) — we render
  *     its message and, when we can recognise it, its remedy.
  *
- * Dependency-free. Kept import-cycle-free by duck-typing AuthUnavailableError
- * (matched on `.name`/`.hint`) rather than importing auth.mjs.
+ * Kept import-cycle-free by duck-typing AuthUnavailableError (matched on
+ * `.name`/`.hint`) rather than importing auth.mjs. The one import it DOES take —
+ * versionStamp from mcp.mjs — is safe: mcp.mjs pulls only node builtins, so it
+ * can't cycle back here.
  */
+import { versionStamp } from "./mcp.mjs";
+
+/**
+ * The version/OS context appended to every failure's stderr — so a bug report
+ * pasted from a failed run already carries `tot`/runner/node/OS. No mode (a
+ * failure isn't a run mode); runner shows `—` when the failure predates its
+ * resolution. Best-effort — never let a stamp problem swallow the real error.
+ * @returns {string}
+ */
+function versionFooter() {
+  try {
+    return `\n  (${versionStamp()})`;
+  } catch {
+    return "";
+  }
+}
 
 /**
  * A failure worth surfacing with a concrete next step.
@@ -42,6 +60,11 @@ export function fail(what, next) {
  * @returns {string}
  */
 export function formatError(err) {
+  return formatErrorBody(err) + versionFooter();
+}
+
+/** The house-style failure line(s), WITHOUT the trailing version/OS footer. */
+function formatErrorBody(err) {
   if (err instanceof CliError) return fail(err.what, err.next);
   // AuthUnavailableError, duck-typed to avoid an import cycle with auth.mjs.
   if (err && typeof err === "object" && err.name === "AuthUnavailableError") {

package/src/mcp.mjs

@@ -8,6 +8,7 @@
  * `Mcp-Session-Id` header across calls. Dependency-free (global fetch, Node 20+).
  */
 import { readFileSync } from "node:fs";
+import os from "node:os";
 
 // The CLI's REAL version for the MCP handshake — the transmission channel the
 // server-side support policy (update-awareness Layer 2) decides against. Read from
@@ -39,6 +40,47 @@ export function clientPackages() {
   return { cli: CLI_VERSION, runner: RUNNER_VERSION };
 }
 
+/**
+ * A readable OS string for debugging — friendly platform name + the raw release
+ * and arch (kept raw so it's honest for a bug report). e.g. `macOS 24.6.0 arm64`,
+ * `Linux 6.8.0-generic x64`, `Windows 10.0.22631 x64`.
+ * @returns {string}
+ */
+export function osLabel() {
+  const platform = os.platform();
+  const friendly =
+    platform === "darwin"
+      ? "macOS"
+      : platform === "win32"
+        ? "Windows"
+        : platform === "linux"
+          ? "Linux"
+          : platform;
+  return `${friendly} ${os.release()} ${os.arch()}`;
+}
+
+/**
+ * A one-line version/OS stamp shown wherever a developer runs the CLI (run
+ * banners, live endings, error footers, `tot doctor`) — the exact context a
+ * future bug report needs. e.g.:
+ *   `tot v1.3.3 · runner v1.3.2 · node v24.2.0 · macOS 24.6.0 arm64 · native`
+ * The runner shows `—` until it's resolved this invocation (setRunnerVersion),
+ * and the trailing `· <mode>` is appended only when a mode label is passed.
+ * @param {string} [mode] - the run mode label (e.g. "native", "docker", "sample").
+ * @returns {string}
+ */
+export function versionStamp(mode) {
+  const { cli, runner } = clientPackages();
+  const parts = [
+    `tot v${cli}`,
+    `runner ${runner ? `v${runner}` : "—"}`,
+    `node v${process.versions.node}`,
+    osLabel(),
+  ];
+  if (mode) parts.push(String(mode));
+  return parts.join(" · ");
+}
+
 /**
  * @param {string} baseUrl - MCP base URL; `/mcp` is appended if absent.
  * @param {{ token?: string, clientVersion?: string }} [opts] - optional developer OAuth

package/src/validate.mjs

@@ -96,6 +96,28 @@ function validateRawHtmlBody(html) {
   if (!html.includes("<")) return "no markup tags found";
   return null;
 }
+/**
+ * Does the tenant provide chrome to wrap body-only fragments? True when it ships
+ * EITHER a hand-authored `content/chrome.html`, OR a `content/chrome.json` that
+ * opts into the canonical shared chrome. Mirrors the serve-time resolution in
+ * apps/storefront getChromeHtml() → parseChromeConfig(): an opted-in config is
+ * rendered into the wrapper (renderRawChrome), so a fragment is NOT served naked.
+ * Kept in step with lib/chrome/parseConfig.ts's opt-in gate.
+ */
+function providesChrome(contentDir) {
+  if (existsSync(join(contentDir, "chrome.html"))) return true;
+  const configPath = join(contentDir, "chrome.json");
+  if (!existsSync(configPath)) return false;
+  const { value } = readJsonSafe(configPath);
+  if (value == null || typeof value !== "object") return false;
+  if (value.sharedChrome !== true) return false;
+  const brand = value.brand;
+  if (brand == null || typeof brand !== "object" || typeof brand.label !== "string") return false;
+  if (!Array.isArray(value.nav)) return false;
+  const footer = value.footer;
+  if (footer == null || typeof footer !== "object" || !Array.isArray(footer.columns)) return false;
+  return true;
+}
 
 // --- filesystem helpers ------------------------------------------------------
 function readJsonSafe(path) {
@@ -186,8 +208,7 @@ export function validateTenant(tenantDir, opts = {}) {
   }
 
   // 4. raw HTML documents — validate + portability + resolution
-  const chromePath = join(contentDir, "chrome.html");
-  const hasChrome = existsSync(chromePath);
+  const hasChrome = providesChrome(contentDir);
   const htmlFiles = walk(contentDir, (p) => p.endsWith(".html"));
   const pageTargets = buildPageTargetSet(contentDir, pagesDir);
 
@@ -204,8 +225,8 @@ export function validateTenant(tenantDir, opts = {}) {
     if (!base && !isFullDocument(html) && !hasChrome) {
       findings.push(
         mk(ERROR, "html-fragment", r,
-          "is an HTML fragment but the tenant ships no content/chrome.html to wrap it — it will serve unwrapped/naked",
-          "make it a full <!doctype html> document, or add content/chrome.html with <!--PAGE_BODY-->"),
+          "is an HTML fragment but the tenant ships no chrome to wrap it — it will serve unwrapped/naked",
+          "make it a full <!doctype html> document, add a content/chrome.json with \"sharedChrome\": true (brand + nav + footer), or add content/chrome.html with <!--PAGE_BODY-->"),
       );
     }
     if (STYLE_OPEN_WITH_ATTRS_RE.test(html)) {