@tokenoftrust/cli 1.3.3-rc.1 → 1.3.4-rc.0

package/package.json

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

@@ -31,13 +31,74 @@ import { recordServerPolicy } from "./update-check.mjs";
 
 /** Thrown when no provider can authenticate — carries actionable guidance. */
 export class AuthUnavailableError extends Error {
-  constructor(message, { hint } = {}) {
+  constructor(message, { hint, reason } = {}) {
     super(message);
     this.name = "AuthUnavailableError";
     this.hint = hint || null;
+    this.reason = reason || null;
   }
 }
 
+const FULL_EMAIL_RE = /^[^\s@]+@[^\s@]+\.[^\s@]+$/;
+const SAFE_EMAIL_HINT_RE = /^[a-z0-9._%+\-]{1,96}@[a-z0-9.-]{1,96}\.[a-z]{2,63}$/i;
+
+function maskEmailPart(part) {
+  if (part.length <= 2) return `${part.slice(0, 1)}...`;
+  return `${part.slice(0, 1)}...${part.slice(-1)}`;
+}
+
+/** Display-only email hint for URLs/log-safe UX. Never returns the full address. */
+export function redactEmailForHint(email) {
+  const raw = String(email || "").trim().toLowerCase();
+  const at = raw.indexOf("@");
+  if (at <= 0) return null;
+  const local = raw.slice(0, at);
+  const domain = raw.slice(at + 1);
+  const parts = domain.split(".").filter(Boolean);
+  if (parts.length < 2) return null;
+  const suffix = parts.pop();
+  const registrable = parts.join(".");
+  if (!suffix || !registrable) return null;
+  return `${maskEmailPart(local)}@${maskEmailPart(registrable)}.${suffix}`;
+}
+
+export function normalizeEmailHint(input) {
+  const raw = String(input || "").trim().toLowerCase();
+  if (!raw || raw.length > 160 || /\s/.test(raw) || !raw.includes("@")) return null;
+  if (FULL_EMAIL_RE.test(raw) && !raw.includes("...")) return redactEmailForHint(raw);
+  return SAFE_EMAIL_HINT_RE.test(raw) ? raw : null;
+}
+
+export function credentialEmailHint(creds) {
+  return (
+    normalizeEmailHint(creds?.emailHint) ||
+    normalizeEmailHint(creds?.email) ||
+    redactEmailForHint(emailFromJwt(creds?.accessToken || "") || "")
+  );
+}
+
+/** Hosted cockpit URL for regenerating local CLI credentials, when we cached one. */
+export function cockpitRecoveryUrl(activityUrl, emailHint = null) {
+  if (!activityUrl) return null;
+  try {
+    const url = new URL("/cockpit?recover=cli", String(activityUrl));
+    const hint = normalizeEmailHint(emailHint);
+    if (hint) url.searchParams.set("email_hint", hint);
+    return url.toString();
+  } catch {
+    return null;
+  }
+}
+
+/** Next-step copy for a stale local developer credential. */
+export function developerCredentialRecoveryHint(creds) {
+  const url = cockpitRecoveryUrl(creds?.activityUrl, credentialEmailHint(creds));
+  if (url) {
+    return `open ${url}, sign in if prompted, click "Generate a fresh setup command", then paste it into your terminal.`;
+  }
+  return "run `tot login` to sign in again.";
+}
+
 /** True when a full operator credential triple is present in the environment. */
 export function hasOperatorCreds(env = process.env) {
   return Boolean(env.TOT_API_KEY && env.TOT_SECRET_KEY && env.TOT_APP_DOMAIN);
@@ -95,7 +156,10 @@ export async function resolveDeveloperSession(client, env, deps = {}) {
   if (!creds || !creds.accessToken) {
     throw new AuthUnavailableError(
       "you're not signed in to Token of Trust.",
-      { hint: "run `tot login` to sign in (or `tot login --code <token>` to paste your invite token), then re-run." },
+      {
+        reason: "missing",
+        hint: "run `tot login` to sign in (or `tot login --code <token>` to paste your invite token), then re-run.",
+      },
     );
   }
 
@@ -103,7 +167,7 @@ export async function resolveDeveloperSession(client, env, deps = {}) {
     if (!creds.refreshToken || !creds.tokenEndpoint) {
       throw new AuthUnavailableError(
         "your Token of Trust session has expired.",
-        { hint: "run `tot login` to sign in again." },
+        { reason: "expired", hint: developerCredentialRecoveryHint(creds) },
       );
     }
     let refreshed;
@@ -116,7 +180,7 @@ export async function resolveDeveloperSession(client, env, deps = {}) {
     } catch (e) {
       throw new AuthUnavailableError(
         `couldn't refresh your Token of Trust session: ${e?.message || e}`,
-        { hint: "run `tot login` to sign in again." },
+        { reason: "refreshFailed", hint: developerCredentialRecoveryHint(creds) },
       );
     }
     const prior = creds;
@@ -138,6 +202,9 @@ export async function resolveDeveloperSession(client, env, deps = {}) {
       creds.activityToken = prior.activityToken;
       creds.activityUrl = prior.activityUrl;
     }
+    if (prior.traceId) creds.traceId = prior.traceId;
+    const priorEmailHint = credentialEmailHint(prior);
+    if (priorEmailHint) creds.emailHint = priorEmailHint;
     writeCredentials(path, creds);
   }
 

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/feedback.mjs

@@ -24,6 +24,7 @@ import { createInterface } from "node:readline/promises";
 import { createMcpClient } from "../mcp.mjs";
 import { establishSession, AuthUnavailableError } from "../auth.mjs";
 import { readActivity, formatActivity } from "../activity-log.mjs";
+import { defaultCredentialsPath, readCredentials } from "../token-store.mjs";
 import { fail } from "../errors.mjs";
 
 const DEFAULT_MCP_URL = "https://mcp.tokenoftrust.com";
@@ -50,6 +51,30 @@ const USAGE = `tot feedback — send a note to Token of Trust (with your recent
 
 Requires a signed-in session — run \`tot login\` first if needed.`;
 
+/**
+ * Assemble the `feedback_submit` payload. Pure + exported so the wire shape
+ * (including the additive `sensitive` activity attachment and the invite→problem
+ * `traceId` link) is unit-testable without driving the MCP handshake. Both extras
+ * are OMITTED when their source is absent — never sent as null/empty.
+ * @param {{ type: string, category: string, severity: string, title: string,
+ *   description: string, activityText?: string|null, traceId?: string|null }} f
+ */
+export function buildFeedbackPayload({ type, category, severity, title, description, activityText, traceId }) {
+  return {
+    type,
+    category,
+    severity,
+    title,
+    description,
+    scenario: "tot-cli",
+    // Activity → `sensitive` (ToT-admins-only, never clustered/shared). It's already
+    // secret-redacted; `sensitive` is the belt-and-suspenders home for it.
+    ...(activityText ? { sensitive: `tot CLI activity (most recent last):\n${activityText}` } : {}),
+    // Invite→terminal→problem trace link (omitted when this wasn't an invite login).
+    ...(traceId ? { traceId } : {}),
+  };
+}
+
 function parseArgs(argv) {
   const a = {
     mcp: null, type: "improvement", category: "product-ux", severity: "medium",
@@ -115,6 +140,14 @@ export async function run(argv) {
   const activityText = entries.length ? formatActivity(entries) : null;
   const title = message.length > 80 ? `${message.slice(0, 79)}…` : message;
 
+  // The invite→terminal→problem trace id `tot login` cached from the pasted invite
+  // command (see commands/login.mjs `cacheTraceId`). Stamping it onto the report lets
+  // triage join this problem back to the developer's invite + their live heartbeat
+  // session. Read it BEFORE establishSession — a silent token refresh rewrites the
+  // credential file, so read the cached value first. Absent for a bare (non-invite)
+  // login; omitted from the payload then.
+  const traceId = readCredentials(defaultCredentialsPath(env))?.traceId || null;
+
   // Preview — sending publishes to Token of Trust, so show exactly what goes out.
   console.error("\nAbout to send to Token of Trust:");
   console.error(`  ${args.type} · ${args.category} · ${args.severity}`);
@@ -152,17 +185,15 @@ export async function run(argv) {
       env,
       initialize: () => client.initialize({ name: "tot-cli", version: "feedback" }),
     });
-    const payload = {
+    const payload = buildFeedbackPayload({
       type: args.type,
       category: args.category,
       severity: args.severity,
       title,
       description: message,
-      scenario: "tot-cli",
-      // Activity → `sensitive` (ToT-admins-only, never clustered/shared). It's already
-      // secret-redacted; `sensitive` is the belt-and-suspenders home for it.
-      ...(activityText ? { sensitive: `tot CLI activity (most recent last):\n${activityText}` } : {}),
-    };
+      activityText,
+      traceId,
+    });
     const res = await client.callTool("feedback_submit", payload);
     const id = res?.reportId || res?.id || null;
     console.log(`\n+ sent — thank you.${id ? ` (report ${id})` : ""}`);

package/src/commands/login.mjs

@@ -23,13 +23,14 @@ import { loginFlow, deviceLoginFlow, redeemCodeFlow, NoOpenerError } from "../oa
 import { defaultCredentialsPath, readCredentials, writeCredentials } from "../token-store.mjs";
 import { openBrowser } from "../open.mjs";
 import { fail } from "../errors.mjs";
+import { cockpitRecoveryUrl, normalizeEmailHint } from "../auth.mjs";
 
 const DEFAULT_MCP_URL = "https://mcp.tokenoftrust.com";
 
 function parseArgs(argv) {
   const a = {
     mcp: null, device: false, code: null, help: false,
-    activityToken: null, activityUrl: null,
+    activityToken: null, activityUrl: null, traceId: null, emailHint: null,
   };
   for (let i = 0; i < argv.length; i++) {
     const t = argv[i];
@@ -38,11 +39,44 @@ function parseArgs(argv) {
     else if (t === "--code" || t === "--token") a.code = argv[++i];
     else if (t === "--activity-token") a.activityToken = argv[++i];
     else if (t === "--activity-url") a.activityUrl = argv[++i];
+    else if (t === "--trace-id") a.traceId = argv[++i];
+    else if (t === "--email-hint") a.emailHint = argv[++i];
+    else if (t === "--email") a.emailHint = argv[++i]; // legacy pasted commands
     else if (t === "--help" || t === "-h") a.help = true;
   }
   return a;
 }
 
+/** Canonical UUID (8-4-4-4-12 hex). Used to reject a malformed --trace-id paste. */
+const UUID_RE = /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i;
+
+/**
+ * Cache the invite→terminal→problem trace id (storefront mints it when it issues
+ * the developer's CLI sign-in code and appends it to the pasted login command as
+ * `--trace-id <uuid>` — see apps/storefront/src/lib/dev/cliSignInCode.ts) alongside
+ * the MCP creds `tot login` just wrote, so `tot feedback` can stamp a later problem
+ * report with it and triage can join the report to the invite + live heartbeat
+ * session. Additive, and mirrors cacheActivityBridge. A no-op when the flag is
+ * absent (older pastes / a bare `tot login`) or malformed (defensive — skip rather
+ * than persist junk that would break the join).
+ */
+export function cacheTraceId(env, traceId) {
+  if (!traceId || !UUID_RE.test(traceId)) return;
+  const path = defaultCredentialsPath(env);
+  const current = readCredentials(path) || {};
+  writeCredentials(path, { ...current, traceId });
+}
+
+/** Cache a display-only email hint from the setup command for later recovery UX. */
+export function cacheEmailHint(env, emailHint) {
+  const normalized = normalizeEmailHint(emailHint);
+  if (!normalized) return;
+  const path = defaultCredentialsPath(env);
+  const current = readCredentials(path) || {};
+  const { email: _legacyEmail, ...safeCurrent } = current;
+  writeCredentials(path, { ...safeCurrent, emailHint: normalized });
+}
+
 /**
  * Cache the local→hosted activity-bridge credential (storefront's
  * cli-signin-code mint, piggybacked as two extra login flags — see
@@ -68,9 +102,10 @@ const USAGE = `tot login — sign in to Token of Trust
                             browser opener exists on this box)
   tot login --mcp <url>     MCP base URL (default: env MCP_BASE_URL / TOT_MCP_URL)
 
-  --activity-token/--activity-url are set automatically by the pasted invite
-  command (report local dev-loop activity to your hosted /dev panel) — not
-  meant to be typed by hand.
+  --activity-token/--activity-url/--trace-id/--email-hint are set automatically by the pasted
+  invite command (report local dev-loop activity to your hosted /dev panel, and
+  link a later \`tot feedback\` report to your invite + session) — not meant to be
+  typed by hand.
 
 After signing in, run \`tot whoami\` to confirm, then \`tot checkout\` / \`tot submit\`.`;
 
@@ -128,15 +163,31 @@ export async function redeemAndCache(mcpUrl, code, env = process.env) {
  * prior --code sign-in would otherwise silently drop it on the next `writeCredentials`
  * (a full-object overwrite, not a merge) — carry it forward when re-authing against
  * the SAME mcpUrl (a different MCP means a different session; the old bridge
- * credential no longer applies).
+ * credential and trace no longer apply).
  */
 export function mergeActivityBridge(prior, mcpUrl, creds) {
-  if (prior?.mcpUrl === mcpUrl && prior.activityToken && prior.activityUrl) {
-    return { ...creds, activityToken: prior.activityToken, activityUrl: prior.activityUrl };
+  if (prior?.mcpUrl === mcpUrl) {
+    const emailHint = normalizeEmailHint(prior.emailHint) || normalizeEmailHint(prior.email);
+    return {
+      ...creds,
+      ...(prior.activityToken && prior.activityUrl
+        ? { activityToken: prior.activityToken, activityUrl: prior.activityUrl }
+        : {}),
+      ...(prior.traceId ? { traceId: prior.traceId } : {}),
+      ...(emailHint ? { emailHint } : {}),
+    };
   }
   return creds;
 }
 
+export function inviteCodeRecoveryNext(activityUrl, emailHint = null) {
+  const url = cockpitRecoveryUrl(activityUrl, emailHint);
+  if (url) {
+    return `open ${url}, sign in if prompted, click "Generate a fresh setup command", then paste it into your terminal.`;
+  }
+  return 'open your developer invite again. If the link has expired, use "Send a fresh link", then generate a new setup command from cockpit.';
+}
+
 /** @param {string[]} argv @param {any} _ctx */
 export async function run(argv, _ctx) {
   const env = process.env;
@@ -153,6 +204,8 @@ export async function run(argv, _ctx) {
     try {
       await redeemAndCache(mcpUrl, args.code, env);
       cacheActivityBridge(env, args.activityToken, args.activityUrl);
+      cacheTraceId(env, args.traceId);
+      cacheEmailHint(env, args.emailHint);
       console.log(`\n+ signed in. Session cached to ${defaultCredentialsPath(env)}.`);
       console.log("  Next: `tot whoami` to confirm, or `tot checkout` / `tot submit` to build.");
       return 0;
@@ -160,7 +213,7 @@ export async function run(argv, _ctx) {
       console.error(
         fail(
           `sign-in didn't complete: ${e?.message || e}`,
-          "double-check the sign-in token from your invite — it's single-use and expires, so ask for a fresh invite if needed.",
+          inviteCodeRecoveryNext(args.activityUrl, args.emailHint),
         ),
       );
       return 1;
@@ -170,6 +223,7 @@ export async function run(argv, _ctx) {
   console.error(`~ signing in to Token of Trust (${mcpUrl})`);
   try {
     await loginAndCache(mcpUrl, env, { log: (m) => console.error(m), device: args.device });
+    cacheTraceId(env, args.traceId);
     console.log(`\n+ signed in. Session cached to ${defaultCredentialsPath(env)}.`);
     console.log("  Next: `tot whoami` to confirm, or `tot checkout` / `tot submit` to build.");
     return 0;

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";
@@ -373,7 +374,7 @@ async function tryResolveSession(client, env, args) {
   try {
     return await loginStep(client, env, args);
   } catch (e) {
-    if (e instanceof AuthUnavailableError) return null;
+    if (e instanceof AuthUnavailableError && e.reason === "missing") return null;
     if (e instanceof CliError && /can't reach the Token of Trust MCP/.test(e.message)) return null;
     throw e;
   }
@@ -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/token-store.mjs

@@ -7,7 +7,7 @@
  *
  *   { mcpUrl, clientId, tokenEndpoint, scope,
  *     accessToken, refreshToken, expiresAt (epoch ms), obtainedAt,
- *     activityToken, activityUrl }
+ *     activityToken, activityUrl, traceId, emailHint }
  *
  * We persist `clientId` + `tokenEndpoint` so a refresh needs no re-discovery /
  * re-registration, and `mcpUrl` so we never present a token minted for one MCP
@@ -16,7 +16,16 @@
  * invite paste carries it — see commands/login.mjs `cacheActivityBridge` and
  * commands/dev.mjs `activityBridgeEnv`, which every runner-spawning path (native
  * monorepo, native standalone, Docker) threads in so the local dev-loop process
- * can report file saves to the developer's hosted /dev panel.
+ * can report file saves to the developer's hosted /dev panel. `traceId` is the
+ * storefront-minted invite→terminal→problem trace id (cached by `tot login`'s
+ * `--trace-id` flag, see commands/login.mjs `cacheTraceId`); `tot feedback`
+ * stamps it onto a problem report so triage can join it to the invite + the live
+ * heartbeat session. `emailHint` is masked, display-only recovery context from
+ * the setup command, used to orient cockpit/login after a local credential
+ * expires without persisting a raw address.
+ *
+ * The read/write is a plain JSON pass-through (no schema) — new fields like
+ * `traceId` ride along additively; readers simply pick the keys they need.
  * Dependency-free (node:fs/os/path).
  *
  * `TOT_HOME` overrides the home dir (used by tests to point at a temp dir).

package/src/validate.mjs

@@ -119,6 +119,195 @@ function providesChrome(contentDir) {
   return true;
 }
 
+const CAPABILITY_KEYS = new Set(["cartCheckout", "ageVerification", "exciseTax"]);
+
+function complianceObligations(config) {
+  const compliance = config?.compliance || {};
+  return {
+    ageVerification: !!compliance.minAge,
+    exciseTax: !!compliance.nicotineWarning,
+  };
+}
+
+function rawHtmlAllowed(config) {
+  const obligations = complianceObligations(config);
+  const regulated = obligations.ageVerification || obligations.exciseTax;
+  return !regulated;
+}
+
+function validateCapabilitiesDoc(doc, file, config) {
+  const out = [];
+  if (doc == null || typeof doc !== "object" || Array.isArray(doc)) {
+    return [mk(ERROR, "capabilities-root", file, "capabilities must be a JSON object")];
+  }
+  for (const [key, value] of Object.entries(doc)) {
+    if (!CAPABILITY_KEYS.has(key)) {
+      out.push(mk(ERROR, "capability-unknown", file, `unknown capability "${key}"`));
+      continue;
+    }
+    if (value == null || typeof value !== "object" || typeof value.enabled !== "boolean") {
+      out.push(mk(ERROR, "capability-shape", file, `${key} must be an object with boolean "enabled"`));
+    }
+  }
+  const obligations = complianceObligations(config);
+  if (obligations.ageVerification && doc.ageVerification?.enabled === false) {
+    out.push(mk(ERROR, "capability-compliance-floor", file, "ageVerification cannot be disabled for a tenant with compliance.minAge"));
+  }
+  if (obligations.exciseTax && doc.exciseTax?.enabled === false) {
+    out.push(mk(ERROR, "capability-compliance-floor", file, "exciseTax cannot be disabled for a tenant with compliance.nicotineWarning"));
+  }
+  return out;
+}
+
+function validateScriptsDoc(doc, file, config) {
+  const out = [];
+  if (doc == null || typeof doc !== "object" || !Array.isArray(doc.scripts)) {
+    return [mk(ERROR, "scripts-root", file, 'scripts.json must have a "scripts" array')];
+  }
+  const regulated = !rawHtmlAllowed(config);
+  for (const [i, entry] of doc.scripts.entries()) {
+    const at = `${file} scripts[${i}]`;
+    if (entry == null || typeof entry !== "object") {
+      out.push(mk(ERROR, "script-entry", at, "script entry must be an object"));
+      continue;
+    }
+    if (entry.isolation === "inline") {
+      out.push(
+        regulated
+          ? mk(ERROR, "script-inline-regulated", at, 'inline scripts are not allowed for regulated tenants; use isolation:"sandbox"')
+          : mk(WARN, "script-inline", at, 'inline scripts run same-origin; prefer isolation:"sandbox"'),
+      );
+    }
+  }
+  return out;
+}
+
+const SUPPORTED_BLOCK_CONTRACTS = new Set(["block-palette@1", "block-palette@2", "block-palette@3"]);
+const KNOWN_BLOCKS = new Set([
+  "hero",
+  "promo_tiles",
+  "featured_collections",
+  "featured_products",
+  "editorial",
+  "newsletter",
+  "marketing_hero",
+  "trust_bar",
+  "split_compare",
+  "steps",
+  "card_grid",
+  "integrations",
+  "proof_strip",
+  "testimonials",
+  "faq",
+  "cta_band",
+]);
+const REQUIRED_BLOCK_PROPS = {
+  hero: ["headline"],
+  promo_tiles: ["tiles"],
+  featured_collections: ["handles"],
+  editorial: ["title"],
+  newsletter: ["title"],
+  marketing_hero: ["headline"],
+  trust_bar: ["items"],
+  split_compare: ["title", "before", "after"],
+  steps: ["title", "steps"],
+  card_grid: ["title", "cards"],
+  integrations: ["title", "platforms"],
+  proof_strip: ["title"],
+  testimonials: ["quotes"],
+  faq: ["title", "items"],
+  cta_band: ["title"],
+};
+const PRODUCT_SOURCE_KEYS = new Set([
+  "collection",
+  "tag",
+  "featured",
+  "newest",
+  "bestSelling",
+  "onSale",
+  "handles",
+  "related",
+  "recentlyViewed",
+]);
+const PRODUCT_SOURCE_SHORTCUTS = new Set(["featured", "newest", "bestSelling", "onSale"]);
+
+function validateProductSource(value, file, at) {
+  const out = [];
+  if (typeof value === "string") {
+    if (!PRODUCT_SOURCE_SHORTCUTS.has(value)) {
+      out.push(mk(ERROR, "product-source", file, `${at}.source must be one of featured, newest, bestSelling, onSale or a source object`));
+    }
+    return out;
+  }
+  if (value == null || typeof value !== "object" || Array.isArray(value)) {
+    out.push(mk(ERROR, "product-source", file, `${at}.source must be a source string or object`));
+    return out;
+  }
+  const keys = Object.keys(value).filter((k) => value[k] !== undefined);
+  const recognized = keys.filter((k) => PRODUCT_SOURCE_KEYS.has(k));
+  if (keys.length !== 1 || recognized.length !== 1) {
+    out.push(mk(ERROR, "product-source", file, `${at}.source must declare exactly one recognized source key`));
+    return out;
+  }
+  const key = recognized[0];
+  const got = value[key];
+  if (key === "handles") {
+    if (!Array.isArray(got) || !got.every((v) => typeof v === "string")) {
+      out.push(mk(ERROR, "product-source", file, `${at}.source.handles must be a string array`));
+    }
+  } else if (key === "collection" || key === "tag" || key === "related") {
+    if (typeof got !== "string") {
+      out.push(mk(ERROR, "product-source", file, `${at}.source.${key} must be a string`));
+    }
+  } else if (got !== true) {
+    out.push(mk(ERROR, "product-source", file, `${at}.source.${key} must be true`));
+  }
+  return out;
+}
+
+function validateHomeDoc(doc, file) {
+  const out = [];
+  if (doc == null || typeof doc !== "object" || Array.isArray(doc)) {
+    return [mk(ERROR, "home-root", file, "home.json must be a JSON object")];
+  }
+  if (doc.contract !== undefined && (typeof doc.contract !== "string" || !SUPPORTED_BLOCK_CONTRACTS.has(doc.contract))) {
+    out.push(mk(ERROR, "home-contract", file, `unsupported block contract "${String(doc.contract)}"`));
+  }
+  if (!Array.isArray(doc.blocks)) {
+    out.push(mk(ERROR, "home-blocks", file, "`blocks` must be an array"));
+    return out;
+  }
+  doc.blocks.forEach((block, i) => {
+    const at = `blocks[${i}]`;
+    if (block == null || typeof block !== "object" || Array.isArray(block)) {
+      out.push(mk(ERROR, "block-shape", file, `${at} must be an object`));
+      return;
+    }
+    const component = block.component;
+    if (typeof component !== "string") {
+      out.push(mk(ERROR, "block-component", file, `${at}.component is required`));
+      return;
+    }
+    if (!KNOWN_BLOCKS.has(component)) {
+      out.push(mk(ERROR, "block-unknown", file, `${at}.component "${component}" is not in the supported block palette`));
+      return;
+    }
+    for (const prop of REQUIRED_BLOCK_PROPS[component] || []) {
+      if (block[prop] === undefined) out.push(mk(ERROR, "block-required", file, `${at} (${component}) is missing "${prop}"`));
+    }
+    if (component === "featured_products") {
+      if (block.source !== undefined) out.push(...validateProductSource(block.source, file, at));
+      if (block.handles !== undefined && (!Array.isArray(block.handles) || !block.handles.every((v) => typeof v === "string"))) {
+        out.push(mk(ERROR, "block-prop", file, `${at}.handles must be a string array`));
+      }
+      if (block.limit !== undefined && typeof block.limit !== "number") {
+        out.push(mk(ERROR, "block-prop", file, `${at}.limit must be a number`));
+      }
+    }
+  });
+  return out;
+}
+
 // --- filesystem helpers ------------------------------------------------------
 function readJsonSafe(path) {
   try {
@@ -181,6 +370,9 @@ export function validateTenant(tenantDir, opts = {}) {
     );
   }
   const scope = opts.scope || config?.scope;
+  if (config?.capabilities) {
+    findings.push(...validateCapabilitiesDoc(config.capabilities, ".tot/config.json capabilities", config));
+  }
 
   // 2. theme.json — parse (a malformed one is a WHOLE-APP BUILD FAILURE)
   const themePath = join(tenantDir, "theme.json");
@@ -194,6 +386,26 @@ export function validateTenant(tenantDir, opts = {}) {
     }
   }
 
+  const capabilitiesPath = join(tenantDir, "capabilities.json");
+  if (existsSync(capabilitiesPath)) {
+    const { value, error } = readJsonSafe(capabilitiesPath);
+    if (error) {
+      findings.push(mk(ERROR, "capabilities-parse", "capabilities.json", `invalid JSON: ${error}`));
+    } else {
+      findings.push(...validateCapabilitiesDoc(value, "capabilities.json", config));
+    }
+  }
+
+  const scriptsPath = join(tenantDir, "scripts.json");
+  if (existsSync(scriptsPath)) {
+    const { value, error } = readJsonSafe(scriptsPath);
+    if (error) {
+      findings.push(mk(ERROR, "scripts-parse", "scripts.json", `invalid JSON: ${error}`));
+    } else {
+      findings.push(...validateScriptsDoc(value, "scripts.json", config));
+    }
+  }
+
   // 3. content JSON — parse + blocks shape
   for (const name of ["home.json", "chrome.json"]) {
     const p = join(contentDir, name);
@@ -201,8 +413,8 @@ export function validateTenant(tenantDir, opts = {}) {
       const { value, error } = readJsonSafe(p);
       if (error) {
         findings.push(mk(ERROR, "content-json-parse", `content/${name}`, `invalid JSON: ${error} (fails the build)`));
-      } else if (name === "home.json" && value && "blocks" in value && !Array.isArray(value.blocks)) {
-        findings.push(mk(ERROR, "home-blocks", "content/home.json", "`blocks` must be an array (index.astro throws otherwise)"));
+      } else if (name === "home.json") {
+        findings.push(...validateHomeDoc(value, "content/home.json"));
       }
     }
   }
@@ -222,6 +434,12 @@ export function validateTenant(tenantDir, opts = {}) {
       findings.push(mk(ERROR, "html-invalid", r, `not a servable document: ${bad}`));
       continue;
     }
+    if (config && !rawHtmlAllowed(config)) {
+      findings.push(
+        mk(ERROR, "raw-html-compliance-bypass", r,
+          "raw HTML bypasses platform Layout compliance; regulated commerce tenants must use block composition or an extracted runtime"),
+      );
+    }
     if (!base && !isFullDocument(html) && !hasChrome) {
       findings.push(
         mk(ERROR, "html-fragment", r,