@tokenoftrust/cli 1.4.0-rc.18 → 1.4.0-rc.19

package/bin/tot.mjs

@@ -40,6 +40,7 @@ import { readFileSync } from "node:fs";
 import { detectContext } from "../src/context.mjs";
 import { printError } from "../src/errors.mjs";
 import { recordActivity, redactArgs } from "../src/activity-log.mjs";
+import { emitActivity, capRendered } from "../src/activity.mjs";
 import { maybeNotifyUpdate } from "../src/update-check.mjs";
 
 const BUILD_ORDER = ["clone", "validate", "dev", "preview"];
@@ -295,12 +296,39 @@ async function dispatch(cmd, rest, ctx) {
   return 2;
 }
 
+/**
+ * The safe `subcommand` value for a command's activity event. Only the fixed
+ * sub-dispatcher verbs (e.g. `app scaffold` / `app dev`) are surfaced — an
+ * arbitrary positional (a tenant name, a path, a code) is NEVER used, so the
+ * activity `subcommand` field can't carry PII even before redaction. Returns
+ * undefined for every command without a fixed subcommand vocabulary.
+ */
+function safeSubcommand(cmd, rest) {
+  if (cmd === "app") {
+    const sub = rest.find((t) => t && !t.startsWith("-"));
+    if (sub === "scaffold" || sub === "dev") return sub;
+  }
+  return undefined;
+}
+
 async function main() {
   const [cmd, ...rest] = process.argv.slice(2);
   const ctx = detectContext();
   const startedAt = Date.now();
+  const command = cmd || "(none)";
+  const subcommand = safeSubcommand(cmd, rest);
   let code = 0;
   let errMsg = null;
+
+  // D3: emit `cli.command.invoked` on start — best-effort, a SILENT no-op without a
+  // hosted-bridge credential (never a network call / never blocks). Fired without
+  // await so it adds no latency to the command; settled alongside the result below.
+  const invokedEmit = emitActivity({
+    action: "cli.command.invoked",
+    outcome: { status: "invoked" },
+    payload: { args: { command, ...(subcommand ? { subcommand } : {}), cliVersion: VERSION, node: process.version } },
+  });
+
   try {
     code = await dispatch(cmd, rest, ctx);
     return code;
@@ -308,17 +336,35 @@ async function main() {
     errMsg = e?.message || String(e);
     throw e;
   } finally {
+    const exitCode = errMsg ? 1 : (code ?? 0);
+    const durationMs = Date.now() - startedAt;
     // Best-effort activity breadcrumb (never throws, never blocks). `feedback`'s own
     // free-text message is omitted — it's user-typed and belongs only in the report.
     recordActivity({
       ts: new Date().toISOString(),
       v: VERSION,
-      cmd: cmd || "(none)",
+      cmd: command,
       args: cmd === "feedback" ? ["«omitted»"] : redactArgs(rest),
-      code: errMsg ? 1 : (code ?? 0),
-      ms: Date.now() - startedAt,
+      code: exitCode,
+      ms: durationMs,
       ...(errMsg ? { err: String(errMsg).slice(0, 200) } : {}),
     });
+    // D3: emit `cli.command.result` (exit code + duration + a bounded/redacted
+    // rendered field). The house-style error text is capped + run through the JS
+    // redaction mirror; per the D0 catalog the `cli.*` rendered lane is empty-
+    // allowlisted, so it's DROPPED by design (the safe default for a high-volume
+    // action) — the emit path still exercises the mirror. Bounded-await here (with
+    // the invoked emit) so a live bridge flushes before the process exits; a no-op
+    // when there's no credential.
+    const resultEmit = emitActivity({
+      action: "cli.command.result",
+      outcome: { status: errMsg ? "failed" : "succeeded", durationMs },
+      payload: {
+        args: { command, ...(subcommand ? { subcommand } : {}), cliVersion: VERSION, exitCode, durationMs },
+        ...(errMsg ? { rendered: { output: capRendered(errMsg) } } : {}),
+      },
+    });
+    await Promise.allSettled([invokedEmit, resultEmit]);
     // Nudge if a newer/unsupported version exists (drawn from cache — instant),
     // and kick a detached registry refresh if stale. Never throws, never blocks.
     maybeNotifyUpdate(VERSION);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@tokenoftrust/cli",
-  "version": "1.4.0-rc.18",
+  "version": "1.4.0-rc.19",
   "description": "Token of Trust developer CLI — clone 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/activity.mjs

@@ -0,0 +1,378 @@
+/**
+ * emitActivity — the CLI's operational-activity emitter (card D3).
+ *
+ * This is a hand-maintained JS MIRROR of the D0 actor×action contract that lives,
+ * in TypeScript, in `packages/public-runtime/src/activity/` (event.ts / catalog.ts
+ * / redaction.ts). The CLI is published to npm STANDALONE and is deliberately pure
+ * JS with NO dependency on `@tot/public-runtime` (a TS package) — see that module's
+ * README ("Consuming this from the downstream cards → D3"). So instead of importing
+ * the contract, we mirror the slice of it the CLI needs, and a keep-in-step test
+ * (activity-mirror.test.mjs) fails LOUDLY the moment this mirror drifts from the TS
+ * source of truth (the same discipline as no-gitea-links.test.mjs).
+ *
+ * What this mirrors, exactly:
+ *   • the ActivityEvent envelope shape + ACTIVITY_SCHEMA_VERSION + newEventId()
+ *   • the CLI-relevant subset of ACTION_CATALOG (the `cli.*` action keys + their
+ *     default-deny argsAllow/renderedAllow allowlists)
+ *   • the redaction contract (REDACTION_MARKER, MAX_VALUE_LEN, the VALUE_CANARIES,
+ *     the KEY_NAME_CANARY, and redactPayload/createActivityEvent) — byte-for-byte,
+ *     so a value that the server-side contract would scrub is scrubbed here too.
+ * If you add a `cli.*` action, change an allowlist, or touch a canary in the TS
+ * source, you MUST update this file in lockstep — the keep-in-step test enforces it.
+ *
+ * Transport + gate (generalized from the obstacle beacon, obstacle-beacon.cjs):
+ *   emitActivity() is a SILENT NO-OP without a bridge credential configured — it
+ *   never makes a network call and never fails/blocks a command when the developer
+ *   isn't connected to a hosted /dev bridge (a bare `tot login`, an older session,
+ *   CI, the `--sample` path). With a credential it POSTs the redacted envelope to
+ *   the SAME `<activityUrl>/api/dev/activity` endpoint the obstacle beacon and the
+ *   dev heartbeat already use — best-effort, bounded by a hard timeout, and fully
+ *   swallowed so telemetry can never disrupt or delay the developer's command.
+ *
+ * Dependency-free (node: builtins + global fetch, Node ≥22).
+ */
+import { createHash } from "node:crypto";
+import { defaultCredentialsPath, readCredentials } from "./token-store.mjs";
+
+// ─────────────────────────────────────────────────────────────────────────────
+// Envelope (mirror of event.ts)
+// ─────────────────────────────────────────────────────────────────────────────
+
+/** Envelope contract version — MIRROR of event.ts ACTIVITY_SCHEMA_VERSION. */
+export const ACTIVITY_SCHEMA_VERSION = 1;
+
+/** Node-native UUID v4 (Node ≥22 has globalThis.crypto). Mirror of event.ts newEventId(). */
+export function newEventId() {
+  const c = globalThis.crypto;
+  if (c && typeof c.randomUUID === "function") return c.randomUUID();
+  // Fallback (should never be reached on a supported Node) — node:crypto.
+  return createHash("sha256").update(String(Math.random()) + Date.now()).digest("hex").slice(0, 32);
+}
+
+// ─────────────────────────────────────────────────────────────────────────────
+// Action catalog — the CLI-relevant SUBSET (mirror of the `cli.*` keys in catalog.ts).
+//
+// Keep this in lockstep with packages/public-runtime/src/activity/catalog.ts. Only
+// the `cli.*` domain is mirrored here (the CLI never emits server/ui actions); the
+// keep-in-step test asserts that (a) this set is EXACTLY the `cli.*` keys in the TS
+// catalog and (b) each argsAllow/renderedAllow matches the TS entry.
+// ─────────────────────────────────────────────────────────────────────────────
+export const CLI_ACTION_CATALOG = {
+  "cli.command.invoked": {
+    argsAllow: ["command", "subcommand", "cliVersion", "node"],
+    renderedAllow: [],
+  },
+  "cli.command.result": {
+    argsAllow: ["command", "subcommand", "cliVersion", "exitCode", "durationMs"],
+    renderedAllow: [],
+  },
+  "cli.obstacle.reported": {
+    argsAllow: ["kind", "have", "need", "cliVersion"],
+    renderedAllow: [],
+  },
+  "cli.signin.requested": {
+    argsAllow: ["cliVersion"],
+    renderedAllow: [],
+  },
+};
+
+/** All CLI action keys as a runtime array. */
+export const CLI_ACTION_KEYS = Object.keys(CLI_ACTION_CATALOG);
+
+/** Deny-by-default guard — is this an allowlisted CLI action key? */
+export function isCliActionKey(v) {
+  return typeof v === "string" && Object.prototype.hasOwnProperty.call(CLI_ACTION_CATALOG, v);
+}
+
+// ─────────────────────────────────────────────────────────────────────────────
+// Redaction contract (mirror of redaction.ts) — MUST match byte-for-byte.
+// ─────────────────────────────────────────────────────────────────────────────
+
+/** Marker stored in place of a value that tripped a canary. Mirror of REDACTION_MARKER. */
+export const REDACTION_MARKER = "«redacted»";
+/** Cap on a stored rendered/arg string. Mirror of MAX_VALUE_LEN. */
+export const MAX_VALUE_LEN = 512;
+
+/**
+ * Secret/PII VALUE canaries — MIRROR of redaction.ts VALUE_CANARIES. The regex
+ * SOURCES here must stay identical to the TS side; the keep-in-step test compares
+ * them literally.
+ */
+export const VALUE_CANARIES = [
+  { label: "private_key", re: /-----BEGIN(?: [A-Z]+)? PRIVATE KEY-----/ },
+  { label: "jwt", re: /\beyJ[A-Za-z0-9_-]{8,}\.[A-Za-z0-9_-]{8,}\.[A-Za-z0-9_-]+/ },
+  { label: "bearer", re: /\bBearer\s+[A-Za-z0-9._~+/-]{12,}=*/i },
+  { label: "aws_access_key", re: /\bAKIA[0-9A-Z]{16}\b/ },
+  { label: "gh_token", re: /\b(?:ghp|gho|ghu|ghs|ghr|github_pat)_[A-Za-z0-9_]{20,}/ },
+  { label: "slack_token", re: /\bxox[baprs]-[A-Za-z0-9-]{10,}/ },
+  { label: "openai_key", re: /\bsk-[A-Za-z0-9]{20,}/ },
+  { label: "email", re: /\b[A-Za-z0-9._%+-]+@[A-Za-z0-9.-]+\.[A-Za-z]{2,}\b/ },
+  { label: "card_number", re: /\b(?:\d[ -]?){13,19}\b/ },
+  { label: "phone", re: /\b\+?\d[\d ().-]{9,}\d\b/ },
+  { label: "high_entropy", re: /(?:^|[^A-Za-z0-9_-])[A-Za-z0-9_-]{28,}(?:$|[^A-Za-z0-9_-])/ },
+];
+
+/** Secret-looking KEY NAMES — dropped outright. MIRROR of redaction.ts KEY_NAME_CANARY. */
+export const KEY_NAME_CANARY =
+  /(?:secret|token|passwd|password|authorization|api[_-]?key|private[_-]?key|credential|cookie|session|bearer|jwt)/i;
+
+function isPrimitive(v) {
+  const t = typeof v;
+  return t === "string" || t === "number" || t === "boolean";
+}
+
+/** Scan a stringified value against the value canaries. Mirror of scanValueCanary. */
+export function scanValueCanary(value) {
+  for (const c of VALUE_CANARIES) if (c.re.test(value)) return c.label;
+  return undefined;
+}
+
+function redactLane(lane, raw, allow, hits) {
+  if (!raw) return undefined;
+  const allowSet = new Set(allow);
+  const out = {};
+  for (const [key, value] of Object.entries(raw)) {
+    if (KEY_NAME_CANARY.test(key)) {
+      hits.push({ lane, key, reason: "key_name_canary" });
+      continue;
+    }
+    if (!allowSet.has(key)) {
+      hits.push({ lane, key, reason: "not_allowlisted" });
+      continue;
+    }
+    if (!isPrimitive(value)) {
+      hits.push({ lane, key, reason: "non_primitive" });
+      continue;
+    }
+    const str = String(value).slice(0, MAX_VALUE_LEN);
+    const canary = scanValueCanary(str);
+    if (canary) {
+      hits.push({ lane, key, reason: "value_canary", canary });
+      out[key] = REDACTION_MARKER;
+      continue;
+    }
+    out[key] = typeof value === "string" ? str : value;
+  }
+  return Object.keys(out).length > 0 ? out : undefined;
+}
+
+/**
+ * Apply the redaction contract to a raw payload for a CLI action. Pure. Mirror of
+ * redaction.ts redactPayload (restricted to the CLI catalog). An unknown action
+ * yields an empty payload (deny-all).
+ */
+export function redactPayload(action, raw) {
+  const hits = [];
+  const spec = CLI_ACTION_CATALOG[action];
+  if (!spec) {
+    if (raw?.args) for (const k of Object.keys(raw.args)) hits.push({ lane: "args", key: k, reason: "unknown_action" });
+    if (raw?.rendered) for (const k of Object.keys(raw.rendered)) hits.push({ lane: "rendered", key: k, reason: "unknown_action" });
+    return { payload: undefined, report: { keptArgs: [], keptRendered: [], hits, canaryTripped: false } };
+  }
+  const args = redactLane("args", raw?.args, spec.argsAllow, hits);
+  const renderedRaw = redactLane("rendered", raw?.rendered, spec.renderedAllow, hits);
+  const rendered = renderedRaw
+    ? Object.fromEntries(Object.entries(renderedRaw).map(([k, v]) => [k, String(v)]))
+    : undefined;
+  const payload = args || rendered ? { ...(args ? { args } : {}), ...(rendered ? { rendered } : {}) } : undefined;
+  return {
+    payload,
+    report: {
+      keptArgs: args ? Object.keys(args) : [],
+      keptRendered: rendered ? Object.keys(rendered) : [],
+      hits,
+      canaryTripped: hits.some((h) => h.reason === "value_canary"),
+    },
+  };
+}
+
+/**
+ * The safe constructor — mirror of redaction.ts createActivityEvent. Fills v/id/at
+ * and runs the raw payload through redactPayload() so the returned event's payload
+ * is already default-denied + canary-scanned. Throws only on an out-of-catalog
+ * (non-`cli.*`) action — a programming error.
+ */
+export function createActivityEvent({ action, actor, source = "cli", outcome, scope, payload, at, id }) {
+  if (!isCliActionKey(action)) throw new Error(`activity: unknown CLI action "${action}" (not in the CLI mirror catalog)`);
+  const { payload: redacted, report } = redactPayload(action, payload);
+  const event = {
+    v: ACTIVITY_SCHEMA_VERSION,
+    id: id ?? newEventId(),
+    at: at ?? new Date().toISOString(),
+    actor,
+    action,
+    source,
+    scope: scope ?? {},
+    outcome,
+    ...(redacted ? { payload: redacted } : {}),
+  };
+  return { event, report };
+}
+
+// ─────────────────────────────────────────────────────────────────────────────
+// Bridge resolution + emit
+// ─────────────────────────────────────────────────────────────────────────────
+
+/** Hard cap on how long a single emit may take before it's abandoned (never blocks a command). */
+const EMIT_TIMEOUT_MS = 1500;
+
+/**
+ * The ONE activity-telemetry kill switch (card D8) — the SAME flag name the server
+ * honours (`apps/storefront/src/lib/activity/killSwitch.ts`). Set
+ * `ACTIVITY_TELEMETRY_DISABLED=1` (or true/yes/on) and every CLI emit becomes a silent
+ * no-op — no build, no redaction, no network — while the command itself runs unchanged
+ * (fail-open). Unset ⇒ telemetry enabled (the normal state).
+ */
+export const ACTIVITY_KILL_SWITCH_FLAG = "ACTIVITY_TELEMETRY_DISABLED";
+export function isActivityDisabled(env = process.env) {
+  const v = env && env[ACTIVITY_KILL_SWITCH_FLAG];
+  return typeof v === "string" && ["1", "true", "yes", "on"].includes(v.trim().toLowerCase());
+}
+
+/**
+ * Resolve the local→hosted activity-bridge credential, or null when none is
+ * configured (→ emitActivity is a no-op). Mirrors the resolution the obstacle
+ * beacon (obstacle.mjs) and the heartbeat (dev-heartbeat.mjs) use: the env override
+ * `TOT_DEV_ACTIVITY_URL`/`TOT_DEV_ACTIVITY_TOKEN` (threaded to runner-spawning
+ * paths) wins, else the `activityUrl`/`activityToken` cached in ~/.tot/credentials.json.
+ */
+export function resolveActivityBridge(env = process.env) {
+  const url = env.TOT_DEV_ACTIVITY_URL;
+  const token = env.TOT_DEV_ACTIVITY_TOKEN;
+  if (url && token) return { url, token };
+  try {
+    const creds = readCredentials(defaultCredentialsPath(env));
+    if (creds?.activityUrl && creds?.activityToken) {
+      return { url: creds.activityUrl, token: creds.activityToken };
+    }
+  } catch {
+    /* best-effort — no bridge */
+  }
+  return null;
+}
+
+/**
+ * The event's actor — kind `dev` (or `agent` when the caller signals an automated
+ * run) with an OPAQUE, non-reversible id, per the D0 contract (actor.id in the core
+ * zone is NEVER raw PII). Until the canonical pseudonymization salt lands (an open
+ * question owned by D1/D4 — see redaction.ts header), we derive the id from an
+ * already-opaque handle: the masked emailHint if present, else a one-way hash of the
+ * bridge token, else "anonymous". Never reversible, never raw PII.
+ */
+export function resolveActor(env = process.env) {
+  const kind = env.TOT_ACTOR_KIND === "agent" ? "agent" : "dev";
+  let seed = "anonymous";
+  try {
+    const creds = readCredentials(defaultCredentialsPath(env));
+    if (creds?.emailHint) seed = `hint:${creds.emailHint}`;
+    else if (creds?.activityToken) seed = `tok:${creds.activityToken}`;
+  } catch {
+    /* fall through to anonymous */
+  }
+  const id = seed === "anonymous" ? "anonymous" : createHash("sha256").update(seed).digest("hex").slice(0, 16);
+  return { kind, id };
+}
+
+/**
+ * The scope threaded onto every CLI event — the storefront-minted invite→problem
+ * `traceId` from the credential cache, when present, so a CLI event and the server
+ * event it triggers share one trace (matching the existing feedback/heartbeat use).
+ */
+function resolveScope(env = process.env, extra = {}) {
+  const scope = { ...extra };
+  try {
+    const creds = readCredentials(defaultCredentialsPath(env));
+    if (creds?.traceId && !scope.traceId) scope.traceId = creds.traceId;
+  } catch {
+    /* best-effort */
+  }
+  return scope;
+}
+
+/**
+ * Emit one activity event. SILENT NO-OP without a bridge credential (returns
+ * `{ sent:false }`) — no network call, never throws, never blocks a command. With
+ * a credential it builds the redacted envelope (via createActivityEvent) and POSTs
+ * it best-effort to `<url>/api/dev/activity`, bounded by EMIT_TIMEOUT_MS.
+ *
+ * Returns `{ sent, event?, report? }` so callers/tests can assert what would be
+ * emitted without any network. `fetchImpl` and `bridge` are injectable for tests.
+ *
+ * @param {{ action: string, outcome: object, actor?: object, scope?: object,
+ *   payload?: object, source?: string, env?: NodeJS.ProcessEnv,
+ *   fetchImpl?: typeof fetch, bridge?: {url:string,token:string}|null }} input
+ * @returns {Promise<{sent:boolean, event?:object, report?:object}>}
+ */
+export async function emitActivity({
+  action,
+  outcome,
+  actor,
+  scope,
+  payload,
+  source = "cli",
+  env = process.env,
+  fetchImpl,
+  bridge,
+} = {}) {
+  try {
+    // Kill switch (D8): telemetry off ⇒ true no-op (no build/redaction/network),
+    // fail-open — the command is unaffected.
+    if (isActivityDisabled(env)) return { sent: false, disabled: true };
+    const resolvedBridge = bridge !== undefined ? bridge : resolveActivityBridge(env);
+    // Build the redacted event even when we won't send it — so a caller/test can
+    // inspect the exact shape, and so redaction always runs on the emit path.
+    const { event, report } = createActivityEvent({
+      action,
+      actor: actor ?? resolveActor(env),
+      source,
+      outcome,
+      scope: resolveScope(env, scope ?? {}),
+      payload,
+    });
+    if (!resolvedBridge) return { sent: false, event, report };
+
+    const doFetch = fetchImpl || globalThis.fetch;
+    if (typeof doFetch !== "function") return { sent: false, event, report };
+
+    const controller = new AbortController();
+    const timer = setTimeout(() => controller.abort(), EMIT_TIMEOUT_MS);
+    if (typeof timer.unref === "function") timer.unref();
+    try {
+      await doFetch(`${String(resolvedBridge.url).replace(/\/+$/, "")}/api/dev/activity`, {
+        method: "POST",
+        headers: {
+          "content-type": "application/json",
+          authorization: `Bearer ${resolvedBridge.token}`,
+        },
+        // `event: "activity"` tags the stream for the bridge/D4 ingest to route,
+        // alongside the D0 envelope. Best-effort — an older bridge that doesn't
+        // recognize it simply ignores the post.
+        body: JSON.stringify({ event: "activity", ...event }),
+        signal: controller.signal,
+      });
+    } catch {
+      /* best-effort — a failed/offline/aborted post never disrupts the command */
+    } finally {
+      clearTimeout(timer);
+    }
+    return { sent: true, event, report };
+  } catch {
+    // Absolutely never throw into a command's control flow.
+    return { sent: false };
+  }
+}
+
+/**
+ * Cap + surface a bit of rendered output for a command-result event. The full raw
+ * stdout is NEVER stored — this caps to MAX_VALUE_LEN and hands the string to the
+ * redaction mirror via payload.rendered. NB the `cli.command.*` actions carry an
+ * EMPTY renderedAllow in the D0 catalog, so this string is DROPPED at redaction by
+ * design (the safe default for a high-volume action) — running it through the
+ * mirror is the belt-and-suspenders the contract prescribes, and keeps the emit
+ * path honest if the allowlist ever opens. Pure.
+ */
+export function capRendered(text) {
+  const s = String(text ?? "").trim();
+  if (!s) return undefined;
+  return s.slice(0, MAX_VALUE_LEN);
+}

package/src/commands/clone.mjs

@@ -194,6 +194,22 @@ export async function run(argv, ctx) {
  */
 export async function checkoutTenant(client, { tenant, tag = "main", cloneDir = null, redact = (s) => s }) {
   await client.callTool("client_switch", { tenant });
+  // vc-app-binding safety-net (08-18, §5): ensure THIS developer is bound to the
+  // storefront version-control app BEFORE checkout, so tenant_checkout can resolve
+  // `appForCaller` for them instead of 403-ing "No version-control app is bound." The
+  // human's OWN session self-triggers it (no subject_token — the subject is the
+  // caller's already-verified identity); the MCP entitlement-gates + authors the bind.
+  // Best-effort + FAIL-OPEN: a missing tool / cold MCP / any fault must never block a
+  // checkout that would otherwise succeed, and if the developer is still unbound the
+  // tenant_checkout error below (via checkoutError) is the honest backstop. Binding is
+  // also ensured at the authority seams (native OAuth sign-in) + backfill; this line
+  // self-heals a legacy session that predates them.
+  try {
+    // Wire name is `identity_bind` (tot-mcp taxonomy: <subject>_<action>).
+    await client.callTool("identity_bind", {});
+  } catch {
+    /* fail-open — see above */
+  }
   const checkout = await client.callTool("tenant_checkout", { tenant, tag });
 
   // A non-checkout result (not provisioned / not entitled / failed) must surface
@@ -271,6 +287,22 @@ export function checkoutError(checkout) {
       next: "ask your Token of Trust contact to finish setting up your store, then re-run",
     };
   }
+  // Entitled, but not yet BOUND to the version-control app (appForCaller resolves
+  // nothing for this identity) — the 08-18 vc-app-binding gap. Distinct from
+  // not-provisioned: the STORE is fine; the developer just isn't onboarded to act
+  // THROUGH the app yet. The checkout preflight tries to self-heal this; if it still
+  // surfaces, the binding seam/backfill hasn't reached this identity — say so plainly
+  // instead of the generic "confirm you're entitled" (they ARE entitled).
+  if (
+    typeof msg === "string" &&
+    /version-control app is bound|registered version-control app/i.test(msg)
+  ) {
+    return {
+      message:
+        "your account isn't onboarded to check out this store yet (no version-control app is bound to your session)",
+      next: "re-run `tot login` to refresh your access, then retry — if it persists, ask your Token of Trust contact to finish onboarding your account",
+    };
+  }
   return {
     message: msg || "the store checkout couldn't be completed",
     next: "confirm you're entitled to this store — `tot clone` (lists your stores)",

package/src/commands/dev.mjs

@@ -615,9 +615,19 @@ export async function resolvePublicRendererSource(args, env = process.env, { dec
         `(or pin with --renderer-version to silence).`,
     );
   }
-  const tarball = meta?.versions?.[version]?.dist?.tarball;
-  if (!tarball) throw new Error(`no published ${pkg}@${version} on npm`);
-  return { kind: "public", version, url: tarball, strip: 1, cacheKey: `public-${version}` };
+  const dist = meta?.versions?.[version]?.dist;
+  if (!dist?.tarball) throw new Error(`no published ${pkg}@${version} on npm`);
+  // `integrity` is the artifact's CONTENT identity (npm dist.integrity, else the
+  // legacy shasum) — installRunnerTarball verifies the downloaded bytes against
+  // it and records it so a same-version corrected republish busts the cache.
+  return {
+    kind: "public",
+    version,
+    url: dist.tarball,
+    strip: 1,
+    cacheKey: `public-${version}`,
+    integrity: dist.integrity || dist.shasum || null,
+  };
 }
 
 /**
@@ -637,7 +647,17 @@ export async function resolveEntitledRendererSource(args, { client: providedClie
   if (!res?.url || !res?.version) {
     throw new Error(res?.error || "no renderer-artifact URL returned");
   }
-  return { kind: "entitled", version: res.version, url: res.url, strip: 0, cacheKey: res.version };
+  // Opportunistic content identity: recorded/verified when the MCP declares one
+  // (integrity/sha256); a server that doesn't is simply unverified (null), never
+  // an error — the cache then busts on version changes only, as before.
+  return {
+    kind: "entitled",
+    version: res.version,
+    url: res.url,
+    strip: 0,
+    cacheKey: res.version,
+    integrity: res.integrity || res.sha256 || null,
+  };
 }
 
 /**
@@ -676,7 +696,12 @@ export async function ensureRendererArtifact(args, { client: providedClient } =
 
   try {
     const runnerDir = await installRunnerTarball(
-      { source: credential.url, version: credential.version, isUrl: true },
+      {
+        source: credential.url,
+        version: credential.version,
+        isUrl: true,
+        integrity: credential.integrity || credential.sha256 || null,
+      },
       { log: (m) => console.error(m) },
     );
     setRunnerVersion(credential.version); // telemetry: stamp the entitled runner version, like ensureSampleRenderer
@@ -851,7 +876,7 @@ export async function ensureSampleRenderer(args, ctx, { env = process.env, cache
     console.error(`~ renderer: ${src.why}`);
     return installRunnerTarball(
       { source: src.source, version: sourceVersionKey(src.source), isUrl: src.isUrl },
-      { log: (m) => console.error(m) },
+      { log: (m) => console.error(m), cacheRoot },
     );
   }
 
@@ -862,12 +887,16 @@ export async function ensureSampleRenderer(args, ctx, { env = process.env, cache
   const declared = declaredRunnerVersion(args.workspace || ctx?.workspacePath);
   const wantVersion = declared || CLI_VERSION;
 
-  // Fully-offline fast path: when the WANTED version (declared, else lockstep) is
-  // already cached, reuse it without touching npm — honouring "don't hit npm when
-  // the RIGHT version is already cached" without ever reusing a version the
-  // resolution wouldn't choose. Safe because `public-<version>` only exists if a
-  // prior run fetched exactly that version. Skipped when an explicit pin is set
-  // (that must go through resolution).
+  // Offline-safe fast path: when the WANTED version (declared, else lockstep) is
+  // already cached, reuse it — honouring "don't hit npm when the RIGHT version is
+  // already cached" without ever reusing a version the resolution wouldn't choose.
+  // Safe because `public-<version>` only exists if a prior run fetched exactly
+  // that version. Skipped when an explicit pin is set (that must go through
+  // resolution). One refinement over fully-offline: a QUICK, soft-fail registry
+  // probe (publishedRunnerIntegrity) revalidates the cached CONTENT identity when
+  // npm is reachable, so a corrected republish under the same version string is
+  // picked up automatically; offline/slow/unanswerable → trust the cache exactly
+  // as before (the probe can never block or fail the run).
   if (!explicitPin) {
     const exact = pinnedPublicCacheDir(cacheRoot, wantVersion);
     if (exact) {
@@ -878,21 +907,31 @@ export async function ensureSampleRenderer(args, ctx, { env = process.env, cache
       // host's arch (rendererCacheHealthy) — a cache poisoned with the wrong-arch
       // bindings (npm/cli#4828) would otherwise be reused forever and crash astro
       // at boot with the swallowed "dev server didn't come up". When both hold,
-      // reuse it (fully offline-safe).
+      // reuse it (offline-safe).
       if (probeRunnerVersion(exact) && rendererCacheHealthy(exact)) {
+        const published = await publishedRunnerIntegrity(env, wantVersion);
+        const recorded = readCacheMarker(exact)?.integrity || null;
+        if (!published || !recorded || published === recorded) {
+          console.error(
+            `~ renderer: cached public runner ${wantVersion} (${declared ? "declared by this store" : "matches this CLI"})`,
+          );
+          setRunnerVersion(wantVersion);
+          prunePublicRunnerCache(cacheRoot, wantVersion);
+          return exact;
+        }
+        // Same version string, different published contents — a corrected
+        // republish. Fall through to resolution + a fresh install (which also
+        // verifies the new bytes against the new integrity).
+        console.error(`~ renderer: ${wantVersion} was republished with different contents — refetching the corrected artifact`);
+        prunePublicRunnerCache(cacheRoot, null); // drop ALL public-* — none matches what npm now publishes
+      } else {
         console.error(
-          `~ renderer: cached public runner ${wantVersion} (${declared ? "declared by this store" : "matches this CLI"})`,
+          rendererCacheHealthy(exact)
+            ? `~ renderer: cached runner at ${exact} can't report a version — refetching (forced upgrade)`
+            : `~ renderer: cached runner at ${exact} is missing native bindings for ${process.platform}-${process.arch} — refetching`,
         );
-        setRunnerVersion(wantVersion);
-        prunePublicRunnerCache(cacheRoot, wantVersion);
-        return exact;
+        prunePublicRunnerCache(cacheRoot, null); // drop ALL public-* — none is trustworthy
       }
-      console.error(
-        rendererCacheHealthy(exact)
-          ? `~ renderer: cached runner at ${exact} can't report a version — refetching (forced upgrade)`
-          : `~ renderer: cached runner at ${exact} is missing native bindings for ${process.platform}-${process.arch} — refetching`,
-      );
-      prunePublicRunnerCache(cacheRoot, null); // drop ALL public-* — none is trustworthy
     }
   }
 
@@ -923,8 +962,8 @@ export async function ensureSampleRenderer(args, ctx, { env = process.env, cache
   // The store preview engine (public npm ${PUBLIC_RUNNER_PACKAGE}@${pub.version}) — kept
   // out of the user's way; the setup spinner below is the visible progress.
   const dir = await installRunnerTarball(
-    { source: pub.url, version: pub.cacheKey, isUrl: true, strip: pub.strip },
-    { log: (m) => console.error(m) },
+    { source: pub.url, version: pub.cacheKey, isUrl: true, strip: pub.strip, integrity: pub.integrity },
+    { log: (m) => console.error(m), cacheRoot },
   );
   setRunnerVersion(pub.version); // telemetry: the runner version running this session
   // The pinned version is now installed under public-<version> — drop any other
@@ -949,92 +988,269 @@ function sourceVersionKey(source) {
  * authenticated (ensureRendererArtifact) and zero-login (ensureSampleRenderer)
  * paths so they cache identically.
  *
- * @param {{ source: string, version: string, isUrl?: boolean }} spec
- * @param {{ log?: (m: string) => void }} [opts]
+ * Cache-poisoning invariants (the 2026-08-18 first-run hardening):
+ *   • promote-on-success only — the install runs in a per-attempt staging dir and
+ *     is renamed into the canonical slot ONLY after it fully succeeds, so a failed
+ *     install can never become the cached artifact a later run resumes from.
+ *   • the completion marker is a manifest carrying the source's CONTENT identity
+ *     (`integrity`), so a corrected republish under the SAME version string is a
+ *     cache miss (rebuild), not a stale hit — no manual `rm -rf` ever required.
+ *   • a failed attempt auto-cleans and retries ONCE from a clean slate before
+ *     surfacing the error (transient blips heal themselves); deterministic
+ *     failures (`e.permanent`) skip the retry and fail loud immediately.
+ *
+ * @param {{ source: string, version: string, isUrl?: boolean, strip?: number, integrity?: string|null }} spec
+ *   `integrity` is the source artifact's content identity when the resolver knows
+ *   it (npm `dist.integrity`/`dist.shasum`); used to verify the downloaded bytes
+ *   and to bust a cached entry whose recorded identity no longer matches.
+ * @param {{ log?: (m: string) => void, cacheRoot?: string }} [opts]
  * @returns {Promise<string>} the cached, installed runner tree's root directory.
  */
-export async function installRunnerTarball({ source, version, isUrl = true, strip = 0 }, { log = (m) => console.error(m) } = {}) {
-  const runnerDir = join(RENDERER_CACHE_ROOT, version);
-  const marker = join(runnerDir, ".tot-cache-complete");
-  if (existsSync(marker)) {
-    // Reuse ONLY if the cached tree carries native bindings for this host's arch.
-    // A cache poisoned with the wrong-arch binaries (npm/cli#4828 — e.g. darwin-x64
-    // on an arm64 Mac) is otherwise trusted forever, and astro crashes at boot with
-    // `Cannot find native binding`, swallowed as "the dev server didn't come up".
-    // Unhealthy → fall through and rebuild from the source below.
-    if (rendererCacheHealthy(runnerDir)) return runnerDir; // already downloaded + installed
-    log(`~ store preview engine cache is missing native bindings for ${process.platform}-${process.arch} — rebuilding it…`);
+export async function installRunnerTarball(
+  { source, version, isUrl = true, strip = 0, integrity = null },
+  { log = (m) => console.error(m), cacheRoot = RENDERER_CACHE_ROOT } = {},
+) {
+  const runnerDir = join(cacheRoot, version);
+  // Staging dirs from DEAD runs (crashed/killed installs) must not leak disk
+  // forever — reap them here, the one funnel every install path goes through.
+  sweepStaleStagingDirs(cacheRoot);
+
+  const localSource = isUrl ? null : resolveLocalTarball(source);
+  // The EXPECTED content identity of the source artifact. A local tarball with no
+  // caller-provided integrity is cheap to hash on every run, so a same-path
+  // republish (new contents, same file name) busts the cache too.
+  const expected = integrity || (isUrl ? null : fileIntegrity(localSource));
+
+  const cached = readCacheMarker(runnerDir);
+  if (cached) {
+    if (!rendererCacheHealthy(runnerDir)) {
+      // A cache poisoned with the wrong-arch binaries (npm/cli#4828 — e.g.
+      // darwin-x64 on an arm64 Mac) is otherwise trusted forever, and astro
+      // crashes at boot with `Cannot find native binding`, swallowed as "the dev
+      // server didn't come up". Fall through and rebuild from the source below.
+      log(`~ store preview engine cache is missing native bindings for ${process.platform}-${process.arch} — rebuilding it…`);
+    } else if (expected && cached.integrity && expected !== cached.integrity) {
+      // CONTENT-HASH BUST: same version string, different artifact contents — a
+      // corrected republish. The cached entry is stale by identity, not by label;
+      // rebuild from the corrected source instead of serving the stale cache.
+      log(`~ the preview engine's ${version} artifact changed upstream (same version, new contents) — rebuilding…`);
+    } else {
+      return runnerDir; // already downloaded + installed (and contents still match)
+    }
   }
 
   // First run only — set the expectation so the one-time cost doesn't read as a
   // hang: this downloads + installs the renderer once, then every later run of
   // this version is a no-network cache hit.
   log(`~ first run: setting up your store preview (~a minute, one-time — cached after this)…`);
-  const localSource = isUrl ? null : resolveLocalTarball(source);
-  const archivePath = isUrl ? join(tmpdir(), `tot-renderer-${process.pid}-${Date.now()}.tar.gz`) : localSource;
-  try {
-    if (isUrl) {
-      // The fetch itself is otherwise silent (no per-byte output) and can run
-      // tens of seconds on a cold cache — tick a spinner so it never looks hung.
-      const spin = startProgress("downloading the store preview engine…");
+  // AUTO-CLEAN-AND-RETRY-ONCE: a transient failure (network blip mid-download, a
+  // registry hiccup mid-install) heals itself with one clean re-attempt instead
+  // of stopping a first run at an error only `rm -rf` folklore could clear.
+  // Bounded to one retry so a genuinely-broken source still fails loudly.
+  for (let attempt = 1; ; attempt++) {
+    const archivePath = isUrl ? join(tmpdir(), `tot-renderer-${process.pid}-${attempt}.tar.gz`) : localSource;
+    const stagingDir = `${runnerDir}.staging-${process.pid}`;
+    try {
+      if (isUrl) {
+        // The fetch itself is otherwise silent (no per-byte output) and can run
+        // tens of seconds on a cold cache — tick a spinner so it never looks hung.
+        const spin = startProgress("downloading the store preview engine…");
+        try {
+          await downloadFile(source, archivePath);
+        } finally {
+          spin.stop();
+        }
+      }
+      if (!existsSync(archivePath)) {
+        throw new Error(`renderer tarball not found: ${archivePath}`);
+      }
+      // Refuse to install bytes that don't match the source's declared identity —
+      // a truncated/corrupted download would otherwise be cached as if complete.
+      // (Transient by nature, so the retry above gets a fresh download.)
+      if (expected && !tarballMatchesIntegrity(archivePath, expected)) {
+        throw new Error(`the downloaded preview-engine tarball failed its integrity check (expected ${expected})`);
+      }
+      // The identity recorded in the completion manifest below — what future runs
+      // compare against to detect a same-version republish. Hash the actual bytes
+      // when the resolver couldn't tell us (e.g. the entitled signed-URL path).
+      const contentId = expected || fileIntegrity(archivePath);
+      rmSync(stagingDir, { recursive: true, force: true });
+      mkdirSync(stagingDir, { recursive: true });
+      extractTarball(archivePath, stagingDir, { strip });
+      // Pin the runner install to PUBLIC npm. The moat-free runner has only public
+      // deps, but the HOST's global ~/.npmrc may point `registry` at a private
+      // mirror (an internal proxy that 502s, or one an invited developer can't
+      // reach) — an invited dev's machine config must never decide where the
+      // runner's public deps come from. A project-level .npmrc wins over the user's.
+      writeFileSync(join(stagingDir, ".npmrc"), "registry=https://registry.npmjs.org/\n");
+      // The install is the long, noisy step — tick a spinner while its output goes
+      // to a log, so the terminal shows one clean line instead of the pnpm firehose.
+      // corepack setup logs to the SAME file so its failures aren't invisible (they
+      // were the silent cause of "couldn't set up the store preview engine").
+      const installLog = join(cacheRoot, `${version}.install.log`);
+      ensureCorepackPnpm(stagingDir, { logPath: installLog });
+      const installSpin = startProgress("installing the store preview engine…", {
+        stages: [{ afterMs: 20000, text: "still setting up the preview engine (first run only)…" }],
+      });
       try {
-        await downloadFile(source, archivePath);
+        await runPnpmInstall(stagingDir, { logPath: installLog });
       } finally {
-        spin.stop();
+        installSpin.stop();
       }
+      // Atomic-ish: only rename into the final, discoverable path once install
+      // succeeded, so a crashed/interrupted run never leaves a half-built cache
+      // entry that a later `tot dev` would treat as ready.
+      rmSync(runnerDir, { recursive: true, force: true });
+      renameSync(stagingDir, runnerDir);
+      // Fence a fresh install against npm/cli#4828: if the installer left the wrong
+      // arch's native bindings (or none) for this host, DON'T stamp the completion
+      // marker — an unmarked tree is never reused, so the next run reinstalls cleanly
+      // instead of caching the poison and crashing astro at boot. Fail loud + actionable
+      // rather than swallow it as "the dev server didn't come up". Permanent: the
+      // same installer on the same host would just produce the same result, so the
+      // auto-retry is skipped.
+      if (!rendererCacheHealthy(runnerDir)) {
+        await emitObstacle("renderer-native-bindings-missing");
+        const err = new CliError(
+          `the store preview engine installed but is missing its native components for ${process.platform}-${process.arch}`,
+          {
+            next: "install pnpm (`npm i -g pnpm`, or `corepack enable`) and re-run `tot start` — pnpm installs the platform-native bits npm can skip (npm/cli#4828)",
+            exitCode: 2,
+          },
+        );
+        err.permanent = true;
+        throw err;
+      }
+      writeCacheMarker(runnerDir, { version, integrity: contentId });
+      return runnerDir;
+    } catch (e) {
+      // A failed attempt must never survive on disk — not as staging debris, and
+      // (by promote-on-success) it never reached the canonical slot at all.
+      rmSync(stagingDir, { recursive: true, force: true });
+      if (e?.permanent === true || attempt >= 2) throw e;
+      log(`~ that didn't work (${String(e?.message || e).split("\n")[0]}) — retrying once from a clean slate…`);
+    } finally {
+      if (isUrl) rmSync(archivePath, { force: true });
     }
-    if (!existsSync(archivePath)) {
-      throw new Error(`renderer tarball not found: ${archivePath}`);
-    }
-    const stagingDir = `${runnerDir}.staging-${process.pid}`;
-    rmSync(stagingDir, { recursive: true, force: true });
-    mkdirSync(stagingDir, { recursive: true });
-    extractTarball(archivePath, stagingDir, { strip });
-    // Pin the runner install to PUBLIC npm. The moat-free runner has only public
-    // deps, but the HOST's global ~/.npmrc may point `registry` at a private
-    // mirror (an internal proxy that 502s, or one an invited developer can't
-    // reach) — an invited dev's machine config must never decide where the
-    // runner's public deps come from. A project-level .npmrc wins over the user's.
-    writeFileSync(join(stagingDir, ".npmrc"), "registry=https://registry.npmjs.org/\n");
-    // The install is the long, noisy step — tick a spinner while its output goes
-    // to a log, so the terminal shows one clean line instead of the pnpm firehose.
-    // corepack setup logs to the SAME file so its failures aren't invisible (they
-    // were the silent cause of "couldn't set up the store preview engine").
-    const installLog = join(RENDERER_CACHE_ROOT, `${version}.install.log`);
-    ensureCorepackPnpm(stagingDir, { logPath: installLog });
-    const installSpin = startProgress("installing the store preview engine…", {
-      stages: [{ afterMs: 20000, text: "still setting up the preview engine (first run only)…" }],
-    });
+  }
+}
+
+/**
+ * Read a cache entry's completion marker (`.tot-cache-complete`). Returns the
+ * manifest object (at least `{ integrity: string|null }`), or null when the
+ * marker is absent — i.e. the entry is incomplete/partial and must be treated
+ * as if it didn't exist. A legacy pre-manifest marker (a bare timestamp string)
+ * reads as complete-with-unknown-identity, so existing healthy caches survive
+ * the upgrade without a forced rebuild.
+ */
+export function readCacheMarker(dir) {
+  try {
+    const raw = readFileSync(join(dir, ".tot-cache-complete"), "utf8");
     try {
-      await runPnpmInstall(stagingDir, { logPath: installLog });
-    } finally {
-      installSpin.stop();
+      const m = JSON.parse(raw);
+      if (m && typeof m === "object") return { integrity: null, ...m };
+    } catch {
+      /* legacy timestamp-string marker */
     }
-    // Atomic-ish: only rename into the final, discoverable path once install
-    // succeeded, so a crashed/interrupted run never leaves a half-built cache
-    // entry that a later `tot dev` would treat as ready.
-    rmSync(runnerDir, { recursive: true, force: true });
-    renameSync(stagingDir, runnerDir);
-    // Fence a fresh install against npm/cli#4828: if the installer left the wrong
-    // arch's native bindings (or none) for this host, DON'T stamp the completion
-    // marker — an unmarked tree is never reused, so the next run reinstalls cleanly
-    // instead of caching the poison and crashing astro at boot. Fail loud + actionable
-    // rather than swallow it as "the dev server didn't come up".
-    if (!rendererCacheHealthy(runnerDir)) {
-      await emitObstacle("renderer-native-bindings-missing");
-      throw new CliError(
-        `the store preview engine installed but is missing its native components for ${process.platform}-${process.arch}`,
-        {
-          next: "install pnpm (`npm i -g pnpm`, or `corepack enable`) and re-run `tot start` — pnpm installs the platform-native bits npm can skip (npm/cli#4828)",
-          exitCode: 2,
-        },
-      );
+    return { integrity: null };
+  } catch {
+    return null; // no marker → never treat the entry as installed
+  }
+}
+
+/** Stamp a cache entry complete: version + source content identity + when. */
+function writeCacheMarker(dir, { version, integrity }) {
+  writeFileSync(
+    join(dir, ".tot-cache-complete"),
+    JSON.stringify({ version, integrity: integrity || null, completedAt: new Date().toISOString() }) + "\n",
+  );
+}
+
+/** sha512 SRI (`sha512-<base64>`, npm's `dist.integrity` format) of a file; null when unreadable. */
+function fileIntegrity(path) {
+  try {
+    return `sha512-${createHash("sha512").update(readFileSync(path)).digest("base64")}`;
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * Do the tarball's bytes match `expected` — an SRI string (`sha512-<b64>`, npm's
+ * `dist.integrity`) or npm's legacy `dist.shasum` (bare 40-hex sha1)? Unknown
+ * formats and probe errors return true: this check exists to catch corrupted
+ * bytes, never to block an install on a format we can't verify.
+ */
+export function tarballMatchesIntegrity(archivePath, expected) {
+  try {
+    const want = String(expected).trim();
+    const sri = /^(sha512|sha384|sha256|sha1)-([A-Za-z0-9+/=]+)$/.exec(want);
+    if (sri) {
+      return createHash(sri[1]).update(readFileSync(archivePath)).digest("base64") === sri[2];
     }
-    writeFileSync(marker, new Date().toISOString());
-  } finally {
-    if (isUrl) rmSync(archivePath, { force: true });
+    if (/^[0-9a-f]{40}$/i.test(want)) {
+      return createHash("sha1").update(readFileSync(archivePath)).digest("hex") === want.toLowerCase();
+    }
+    return true;
+  } catch {
+    return true;
+  }
+}
+
+/**
+ * Reap `<entry>.staging-<pid>` dirs left by DEAD processes — failed/killed
+ * installs used to accumulate one orphaned staging tree per attempt, leaking
+ * disk forever. A staging dir whose pid is still alive belongs to a concurrent
+ * `tot dev` mid-install and is left alone. Best-effort: never throws, and never
+ * touches this process's own staging dir (created fresh after this sweep).
+ */
+export function sweepStaleStagingDirs(cacheRoot, { pidAlive = processAlive } = {}) {
+  try {
+    if (!cacheRoot || !existsSync(cacheRoot)) return;
+    for (const name of readdirSync(cacheRoot)) {
+      const m = /\.staging-(\d+)$/.exec(name);
+      if (!m) continue;
+      const pid = Number(m[1]);
+      if (pid === process.pid || pidAlive(pid)) continue;
+      rmSync(join(cacheRoot, name), { recursive: true, force: true });
+    }
+  } catch {
+    /* best-effort cache hygiene */
+  }
+}
+
+/** Is a pid a live process? (signal 0 probe; EPERM = alive but not ours.) */
+function processAlive(pid) {
+  try {
+    process.kill(pid, 0);
+    return true;
+  } catch (e) {
+    return e?.code === "EPERM";
+  }
+}
+
+/**
+ * The registry-declared content identity (`dist.integrity`, else `dist.shasum`)
+ * of the public runner at `version` — or null when npm can't answer QUICKLY
+ * (offline, slow, 4xx/5xx, malformed). Used by ensureSampleRenderer's cached
+ * fast path to detect a same-version republish without ever making the network
+ * a hard dependency: null means "can't verify right now — trust the cache",
+ * preserving the offline-reuse behavior exactly.
+ */
+export async function publishedRunnerIntegrity(env, version, { timeoutMs = 2000, fetchFn = fetch } = {}) {
+  try {
+    const pkg = env.TOT_RUNNER_PACKAGE || PUBLIC_RUNNER_PACKAGE;
+    const registry = (env.TOT_NPM_REGISTRY || DEFAULT_NPM_REGISTRY).replace(/\/$/, "");
+    const res = await fetchFn(`${registry}/${pkg.replace("/", "%2f")}`, {
+      headers: { accept: "application/json" },
+      signal: AbortSignal.timeout(timeoutMs),
+    });
+    if (!res.ok) return null;
+    const dist = (await res.json())?.versions?.[version]?.dist;
+    return dist?.integrity || dist?.shasum || null;
+  } catch {
+    return null;
   }
-  return runnerDir;
 }
 
 /** Strip an optional file:// prefix from a local tarball path and resolve it absolute. */
@@ -1190,22 +1406,27 @@ export async function runPnpmInstall(runnerDir, { logPath, spawnFn = spawnAsyncR
         continue;
       }
       // The launcher ran; the install itself failed. That's the actionable error.
+      // (installRunnerTarball auto-retries this ONCE from a clean slate before it
+      // reaches the user — so by the time this surfaces, it failed twice.)
       await emitObstacle("install-failed");
       throw new CliError(
         `couldn't set up the store preview engine${pnpmFailureHint(logPath)}` +
           (logPath ? `\n     details: ${logPath}` : ""),
-        { next: "check the details log above, then re-run `tot start` (it resumes from the cache)" },
+        { next: "check the details log above, then re-run `tot start` (it retries from a clean slate — no cache to clear)" },
       );
     }
     // Every launcher ENOENT'd → there's no pnpm on this machine and corepack
     // couldn't provide one (corepack isn't bundled on Node 25+). npm ships with
     // every Node, so `npm i -g pnpm` is the escape hatch that always exists.
+    // Permanent: retrying can't conjure a launcher — skip the clean-slate retry.
     await emitObstacle("pnpm-missing");
-    throw new CliError(
+    const err = new CliError(
       "couldn't set up the store preview engine — pnpm isn't available on this machine" +
         (logPath ? `\n     details: ${logPath}` : ""),
       { next: "install pnpm with `npm i -g pnpm` (or `corepack enable`), then re-run `tot start`" },
     );
+    err.permanent = true;
+    throw err;
   } finally {
     if (fd !== null) closeSync(fd);
   }
@@ -1220,6 +1441,20 @@ function pnpmFailureHint(logPath) {
   if (!logPath) return " — is pnpm/corepack available on this host?";
   try {
     const tail = readFileSync(logPath, "utf8").slice(-8000);
+    // A 404 means the registry answered — a specific package/version doesn't
+    // exist there. Since installs now run from a clean slate every attempt
+    // (promote-on-success + auto-retry), this is a BROKEN RUNNER RELEASE (it
+    // references an unpublished package), not the user's cache — no `rm -rf`
+    // will help. Check this BEFORE the generic ERR_PNPM_FETCH match, since
+    // pnpm's 404 error text also contains "ERR_PNPM_FETCH".
+    const missing404 = tail.match(/ERR_PNPM_FETCH_404[^\n]*GET\s+(\S+)/i);
+    if (missing404) {
+      return (
+        ` — the preview engine references a package that isn't published (${missing404[1]});` +
+        " that's a broken preview-engine release, not your machine — try again later or pin a" +
+        " known-good version with --renderer-version"
+      );
+    }
     if (/npm\.tokenoftrust\.com|ERR_PNPM_FETCH|502|ECONNREFUSED|ETIMEDOUT|ENOTFOUND/i.test(tail)) {
       return " — the Token of Trust package registry looks unreachable right now; check your connection and retry";
     }

package/src/commands/pr.mjs

@@ -42,6 +42,24 @@ const DEFAULT_MCP_URL = "https://mcp.tokenoftrust.com";
 const DEFAULT_STOREFRONT_URL = "https://storefront.tokenoftrust.store";
 const SUBCOMMANDS = ["list", "view", "close"];
 
+/**
+ * The storefront-owned, shareable `/preview/<tenant>/pr/<N>` link — NEVER the
+ * forge/Gitea `url` (2026-08-18 incident: a raw forge PR URL reached an
+ * owner). `candidate_status` (the local-checkout MCP tool) has no
+ * `previewUrl` field at all, unlike the operator `GET /api/changes` path — so
+ * this constructs it the same way `runPrListOperator`'s caller resolves
+ * `storefrontUrl`, from the same env/--url override chain. Pure.
+ * @param {string} storefrontUrl
+ * @param {string} tenant
+ * @param {number|null|undefined} prNumber
+ * @returns {string|null}
+ */
+export function buildPreviewUrl(storefrontUrl, tenant, prNumber) {
+  if (typeof prNumber !== "number" || !tenant) return null;
+  const base = (storefrontUrl || DEFAULT_STOREFRONT_URL).trim().replace(/\/+$/, "");
+  return `${base}/preview/${tenant}/pr/${prNumber}`;
+}
+
 const USAGE = `tot pr — see and manage candidate PRs
 
   tot pr [list]              list your open candidate PRs for this store
@@ -118,9 +136,11 @@ export function matchCandidate(candidates, target) {
 /**
  * One-line candidate summary for `tot pr list` — surfaces branch ↔ PR# ↔ preview
  * URL so a dev sees, at a glance, which git branch each candidate belongs to (u4 —
- * branch-bound candidates) and where its preview lives. Prefers the candidate's
- * `previewUrl`, falling back to the PR `url`. `active` marks the one THIS checkout's
- * branch resolves to. Pure — unit-tested.
+ * branch-bound candidates) and where its preview lives. ONLY `previewUrl` (the
+ * storefront-owned `/preview/<tenant>/pr/<N>` link) — NEVER `url` (the forge/
+ * Gitea `html_url`), which must never reach a terminal (2026-08-18 incident:
+ * a raw forge PR URL reached an owner). `active` marks the one
+ * THIS checkout's branch resolves to. Pure — unit-tested.
  * @param {{prNumber?:number|null, branch?:string|null, changeId:string, state?:string|null,
  *   previewUrl?:string|null, url?:string|null}} c
  * @param {{ active?: boolean }} [opts]
@@ -128,8 +148,7 @@ export function matchCandidate(candidates, target) {
 export function formatCandidateLine(c, { active = false } = {}) {
   const pr = typeof c.prNumber === "number" ? `#${c.prNumber}` : "#—";
   const branch = c.branch ? c.branch : "(no branch)";
-  const previewUrl = c.previewUrl || c.url || null;
-  const urlPart = previewUrl ? `  ${previewUrl}` : "";
+  const urlPart = c.previewUrl ? `  ${c.previewUrl}` : "";
   const activePart = active ? "  ← active" : "";
   return `  PR ${pr}  ${branch}  ${c.changeId}  [${c.state ?? "?"}]${urlPart}${activePart}`;
 }
@@ -326,6 +345,7 @@ export async function run(argv, ctx) {
   }
 
   const baseUrl = args.mcp || env.MCP_BASE_URL || env.TOT_MCP_URL || DEFAULT_MCP_URL;
+  const storefrontUrl = args.url || env.TOT_STOREFRONT_URL || env.STOREFRONT_BASE_URL || DEFAULT_STOREFRONT_URL;
   const statePath = defaultCandidateStatePath(env);
   // Branch-bound (u4): the active-pointer namespace is scoped to the current git
   // branch, so the "← active" marker reflects THIS branch's candidate.
@@ -347,7 +367,8 @@ export async function run(argv, ctx) {
       const active = readActiveChangeId(statePath, scope);
       console.log(`Open candidate PRs for ${repo}:`);
       for (const c of candidates) {
-        console.log(formatCandidateLine(c, { active: !!active && c.changeId === active }));
+        const previewUrl = c.previewUrl ?? buildPreviewUrl(storefrontUrl, tenant, c.prNumber);
+        console.log(formatCandidateLine({ ...c, previewUrl }, { active: !!active && c.changeId === active }));
       }
       return 0;
     }
@@ -366,7 +387,9 @@ export async function run(argv, ctx) {
       if (match.headSha) console.log(`  head:             ${match.headSha}`);
       if (match.baseSha) console.log(`  base:             ${match.baseSha}`);
       console.log(`  mergeable (forge): ${match.mergeable ?? "?"}`);
-      if (match.url) console.log(`  ${match.url}`);
+      // ONLY the storefront-owned preview link -- never the raw forge/Gitea `url`.
+      const previewUrl = match.previewUrl ?? buildPreviewUrl(storefrontUrl, tenant, match.prNumber);
+      if (previewUrl) console.log(`  ${previewUrl}`);
       return 0;
     }
 

package/src/commands/ship.mjs

@@ -47,6 +47,7 @@ import { fail } from "../errors.mjs";
 import { planForAction, printPlanAndConfirm } from "../plan.mjs";
 import { startProgress } from "../progress.mjs";
 import { openBrowser } from "../open.mjs";
+import { emitActivity } from "../activity.mjs";
 
 const DEFAULT_STOREFRONT_URL = "https://storefront.tokenoftrust.store";
 
@@ -414,7 +415,25 @@ export async function runShip({ tenant, secret, storefrontUrl = null, yes = fals
   const shipData = await readJsonSafe(shipRes);
   progress?.stop();
 
-  return reportShipResult(normalizeShipResult(shipData), { tenant, liveUrl, noOpen, openUrl: deps.openUrl });
+  const shipResult = normalizeShipResult(shipData);
+  // D3: emit the ship publish lifecycle event — `tot ship` does no LOCAL git op
+  // (it's HTTP-orchestrated), so this marks the outcome of the publish step
+  // itself, distinct from the outer command's invoked/result pair. Fire-and-
+  // forget best-effort: a silent no-op without a hosted-bridge credential, never
+  // awaited, never throws, never alters the ship. `errorClass` stays low-
+  // cardinality (the orchestrator's own terminal state/reason, never free text).
+  const shipped = shipResult.state === "shipped";
+  void emitActivity({
+    action: "cli.command.result",
+    outcome: {
+      status: shipped ? "succeeded" : "failed",
+      ...(shipped ? {} : { errorClass: `ship_${shipResult.state}` }),
+    },
+    scope: { tenantId: tenant },
+    payload: { args: { command: "ship", subcommand: "ship.publish" } },
+  });
+
+  return reportShipResult(shipResult, { tenant, liveUrl, noOpen, openUrl: deps.openUrl });
 }
 
 /**

package/src/commands/submit.mjs

@@ -50,6 +50,7 @@ import { validateTenant, ERROR } from "../validate.mjs";
 import { openBrowser } from "../open.mjs";
 import { startProgress } from "../progress.mjs";
 import { fail } from "../errors.mjs";
+import { emitActivity } from "../activity.mjs";
 import {
   defaultCandidateStatePath,
   readActiveChangeId,
@@ -81,6 +82,23 @@ export function candidateRefFor(changeId) {
   return `${CANDIDATE_REF_PREFIX}${changeId}`;
 }
 
+/**
+ * D3: emit a git-op lifecycle event for `tot submit`/`tot preview` — one per git
+ * operation (commit / push), carrying its own success/failure, so the timeline sees
+ * the individual git steps, not just the outer command's invoked/result pair. Uses
+ * the `cli.command.result` catalog key with a `git.<op>` subcommand (a fixed, safe
+ * value). Fire-and-forget best-effort: a silent no-op without a hosted-bridge
+ * credential, never awaited, never throws, never alters the command. `errorClass` is
+ * a low-cardinality class (never a raw git stderr, which can carry a token/path).
+ */
+function emitGitOp(op, ok, { command = "submit", durationMs, errorClass } = {}) {
+  void emitActivity({
+    action: "cli.command.result",
+    outcome: { status: ok ? "succeeded" : "failed", ...(durationMs != null ? { durationMs } : {}), ...(errorClass ? { errorClass } : {}) },
+    payload: { args: { command, subcommand: `git.${op}`, ...(durationMs != null ? { durationMs } : {}) } },
+  });
+}
+
 export function parseArgs(argv) {
   // `ref: null` — an explicit `--ref` always wins; otherwise the push target is
   // derived per-run as YOUR OWN isolated candidate ref (resolvePushRef, below),
@@ -890,11 +908,13 @@ export async function run(argv, ctx, { verb = "preview" } = {}) {
   try {
     auto = autoCommitKnownTrees(git, { message: args.message, noCommit: args.noCommit });
   } catch (e) {
+    emitGitOp("commit", false, { command: verb, errorClass: "git_commit_failed" });
     const msg = `auto-commit failed: ${String(e?.stderr || e?.message || e)}`;
     console.error(fail(msg, "commit your content manually (git add / git commit), or re-run with --no-commit"));
     emitJson(args, buildJsonResult({ ok: false, error: msg }));
     return 1;
   }
+  if (auto.committed) emitGitOp("commit", true, { command: verb });
   if (auto.refused) {
     console.error(
       fail(
@@ -1007,7 +1027,12 @@ export async function run(argv, ctx, { verb = "preview" } = {}) {
     try {
       const out = git(["push", "-f", "origin", `HEAD:refs/heads/${ref}`]);
       if (out.trim()) console.error(redactUrl(out.trim()));
+      emitGitOp("push", true, { command: verb });
     } catch (pushErr) {
+      emitGitOp("push", false, {
+        command: verb,
+        errorClass: isForgeAuthError(pushErr?.stderr || pushErr?.message || pushErr) ? "forge_auth" : "git_push_failed",
+      });
       const msg = `push failed: ${redactUrl(String(pushErr.stderr || pushErr.message || pushErr))}`;
       // This is the NO-SESSION path pushing the clone-time embedded credential —
       // which rotation kills the moment any fresh mint happens elsewhere. An auth
@@ -1066,7 +1091,12 @@ export async function run(argv, ctx, { verb = "preview" } = {}) {
   try {
     const { out } = await pushPreviewRef(git, mintRemote, { ref });
     if (out && out.trim()) console.error(redactUrl(out.trim()));
+    emitGitOp("push", true, { command: verb });
   } catch (e) {
+    emitGitOp("push", false, {
+      command: verb,
+      errorClass: isForgeAuthError(e?.stderr || e?.message || e) ? "forge_auth" : "git_push_failed",
+    });
     const msg = `push failed: ${redactUrl(String(e.stderr || e.message || e))}`;
     console.error(fail(msg, "check your commit and that the checkout's remote is reachable, then re-run"));
     emitJson(args, buildJsonResult({ ok: false, ref, commit, changeId, error: msg }));

package/src/no-gitea-links.test.mjs

@@ -0,0 +1,55 @@
+// Regression guard: the `tot` CLI must never print/reference a raw Gitea
+// forge URL to a developer's terminal. Gitea's API returns `html_url` when a
+// PR is opened (e.g. `https://git.tokenoftrust.com/storefront/<repo>/pulls/<n>`)
+// -- the CLI must surface the storefront-owned `/preview/<tenant>/pr/<n>` link
+// instead (see apps/storefront's matching noGiteaLinks.test.ts and its header
+// for the full architecture reasoning: apps/CLI never expose the forge
+// directly, the MCP proxies every read/write). Precipitating incident
+// (2026-08-18): a raw git.tokenoftrust.com PR URL reached an owner reviewing
+// tokenoftrust.com. Test fixtures are exempt (they legitimately mock a Gitea
+// URL to test the forge client), everything else in `src` must stay clean.
+import { readdirSync, readFileSync, statSync } from "node:fs";
+import { join, relative, dirname } from "node:path";
+import { fileURLToPath } from "node:url";
+import { test } from "node:test";
+import assert from "node:assert/strict";
+
+const SELF = fileURLToPath(import.meta.url);
+const SRC_ROOT = dirname(SELF);
+
+const TEST_FILE_RE = /\.test\.[cm]?js$/;
+const FORGE_HOST_RE = /\bgit\.tokenoftrust\.com\b/i;
+const SKIP_DIRS = new Set(["node_modules", "dist", ".git"]);
+
+function walk(dir, out = []) {
+  for (const entry of readdirSync(dir)) {
+    if (SKIP_DIRS.has(entry)) continue;
+    const full = join(dir, entry);
+    const st = statSync(full);
+    if (st.isDirectory()) {
+      walk(full, out);
+    } else if (/\.[cm]?js$/.test(entry)) {
+      out.push(full);
+    }
+  }
+  return out;
+}
+
+test("no Gitea forge links in the CLI source outside test fixtures", () => {
+  const offenders = [];
+  for (const file of walk(SRC_ROOT)) {
+    if (TEST_FILE_RE.test(file)) continue;
+    if (file === SELF) continue;
+    const content = readFileSync(file, "utf8");
+    content.split("\n").forEach((line, i) => {
+      if (FORGE_HOST_RE.test(line)) {
+        offenders.push(`${relative(SRC_ROOT, file)}:${i + 1}: ${line.trim()}`);
+      }
+    });
+  }
+  assert.deepEqual(
+    offenders,
+    [],
+    `Found Gitea forge links in non-test CLI source:\n${offenders.join("\n")}`,
+  );
+});