@tokenoftrust/cli 1.2.1 → 1.2.3

package/bin/tot.mjs

@@ -5,14 +5,12 @@
  * One command a developer learns to go from an invite to a running store:
  *
  *   tot start                 invite → running store in one command      ← built (orchestrates the below, value-first)
- *   tot start --sample        FREE local preview — no login, no MCP       ← built (zero-login quickstart; MCP is the upsell)
  *   tot login                 sign in to Token of Trust (OAuth)          ← built (MCP OAuth PKCE loopback; caches ~/.tot/credentials.json)
  *   tot logout                sign out (clear the cached session)        ← built (deletes ~/.tot/credentials.json; local-only, no server revoke)
  *   tot whoami                who you're signed in as                    ← built
  *   tot checkout [<tenant>]   clone a store you can build on            ← built
  *   tot validate              lint your store before you submit         ← built
  *   tot dev                   run your store locally with save→reload   ← built (monorepo: host astro; standalone: runs the published runner image)
- *   tot dev --sample          run a FREE bundled sample store locally    ← built (zero-login, no MCP; compliance rendering still shows)
  *   tot submit                submit your store for preview             ← built (validate + push preview ref; MCP preview_status read-back)
  *   tot doctor                check this machine is ready
  *   tot ideas                 copy-paste AI prompts that reliably wow
@@ -24,7 +22,7 @@
  * from anywhere else. Every command receives the detected context.
  *
  * This package is `@tokenoftrust/cli` (bin `tot`). Its heaviest command, `tot dev`,
- * bundles the moat-free storefront runner; `tot checkout/validate/submit` are
+ * fetches the published storefront runner; `tot checkout/validate/submit` are
  * pure Node. Dependency-free by design so `npm i -g @tokenoftrust/cli` stays light.
  */
 import { readFileSync } from "node:fs";
@@ -49,14 +47,12 @@ function usage() {
 tot — Token of Trust developer CLI
 
   tot start                 invite → running store in one command (start here)
-  tot start --sample        free local preview — no login, no account needed
   tot login                 sign in to Token of Trust
   tot logout                sign out (clear the cached session)
   tot whoami                show who you're signed in as
   tot checkout [<tenant>]   clone a store you can build on
   tot validate              lint your store before you submit
   tot dev                   run your store locally with save→reload
-  tot dev --sample          run a free bundled sample store (no login, no MCP)
   tot submit                submit your store for preview
   tot doctor                check this machine is ready
   tot ideas                 copy-paste AI prompts that reliably wow

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@tokenoftrust/cli",
-  "version": "1.2.1",
+  "version": "1.2.3",
   "description": "Token of Trust developer CLI — check out a tenant store, run it locally with save→reload, and submit it for preview. Installs the `tot` command.",
   "license": "Apache-2.0",
   "author": "Token of Trust",
@@ -25,7 +25,6 @@
   "files": [
     "bin",
     "src",
-    "template",
     "README.md",
     "LICENSE"
   ],

package/src/auth.mjs

@@ -132,5 +132,70 @@ export async function resolveDeveloperSession(client, env, deps = {}) {
   }
 
   if (client && typeof client.setToken === "function") client.setToken(creds.accessToken);
-  return { identity: "developer", appDomain: null, token: creds.accessToken };
+  return {
+    identity: "developer",
+    appDomain: null,
+    token: creds.accessToken,
+    email: emailFromJwt(creds.accessToken),
+  };
+}
+
+/**
+ * Establish a validated session on `client`, attaching auth in the CORRECT order
+ * relative to the MCP handshake — the one thing every command must get right:
+ *
+ *   developer  → attach the cached bearer via setToken() BEFORE client.initialize(),
+ *                so the server binds the session to this identity AT initialize time.
+ *                An init-then-attach order leaves the session anonymous for its whole
+ *                life on a server that only binds identity at initialize — this is the
+ *                invited-developer "no stores you can build on" dead-end.
+ *   operator   → client.initialize() FIRST, then credential_validate, which is an
+ *                in-session tool call that requires a completed handshake.
+ *
+ * Every command calls THIS instead of hand-ordering initialize() + resolveSession(),
+ * so the ordering rule lives in exactly one place. `opts.initialize` lets a caller
+ * inject its own handshake (to wrap the unreachable-MCP error, or pass custom
+ * clientInfo); it defaults to `() => client.initialize()`.
+ *
+ * @param {ReturnType<import("./mcp.mjs").createMcpClient>} client
+ * @param {{ env?: NodeJS.ProcessEnv, prefer?: "operator"|"developer",
+ *   initialize?: () => Promise<any> }} [opts]
+ * @returns {Promise<{ identity: "operator"|"developer", appDomain: string|null, email?: string|null }>}
+ */
+export async function establishSession(client, opts = {}) {
+  const env = opts.env || process.env;
+  const prefer = opts.prefer || (hasOperatorCreds(env) ? "operator" : "developer");
+  const initialize = opts.initialize || (() => client.initialize());
+
+  if (prefer === "developer") {
+    // Attach the bearer, THEN handshake — the handshake carries the Authorization
+    // header so the server binds this identity at initialize time.
+    const session = await resolveDeveloperSession(client, env);
+    await initialize();
+    return session;
+  }
+  // Operator: handshake FIRST, then credential_validate (an in-session tool call).
+  await initialize();
+  return resolveSession(client, { env, prefer });
+}
+
+/**
+ * Best-effort email from an OAuth access token when it's a JWT — for DISPLAY ONLY
+ * (self-diagnosing dead-ends: "signed in as <email> via <origin>"), never for trust.
+ * Decodes the unverified payload segment; returns null for an opaque token or one
+ * with no email-ish claim. Never throws.
+ * @param {string} token
+ * @returns {string|null}
+ */
+export function emailFromJwt(token) {
+  try {
+    const seg = String(token).split(".")[1];
+    if (!seg) return null;
+    const json = JSON.parse(
+      Buffer.from(seg.replace(/-/g, "+").replace(/_/g, "/"), "base64").toString("utf8"),
+    );
+    return json.email || json.preferred_username || null;
+  } catch {
+    return null;
+  }
 }

package/src/commands/checkout.mjs

@@ -13,14 +13,14 @@
  * `tot` performs NO privileged forge work itself — the MCP owns that.
  *
  * Auth is resolved through src/auth.mjs: operator creds (our dogfooding / CI) or
- * the developer's own ToT identity (workstream #2). This command doesn't care
+ * the developer's own ToT identity. This command doesn't care
  * which — it just needs a validated session.
  *
  * Dependency-free (global fetch + `git` via child_process).
  */
 import { execFileSync } from "node:child_process";
 import { createMcpClient } from "../mcp.mjs";
-import { resolveSession, AuthUnavailableError } from "../auth.mjs";
+import { establishSession, AuthUnavailableError } from "../auth.mjs";
 import { CliError, fail, formatError } from "../errors.mjs";
 
 const DEFAULT_MCP_URL = "https://mcp.tokenoftrust.com";
@@ -94,8 +94,9 @@ export async function run(argv, ctx) {
   const client = createMcpClient(baseUrl);
 
   try {
-    await client.initialize();
-    const session = await resolveSession(client, {
+    // Attach auth in the right order relative to the handshake (developer bearer
+    // BEFORE initialize; operator credential_validate after) — see establishSession.
+    const session = await establishSession(client, {
       env,
       prefer: args.identity || undefined,
     });
@@ -218,10 +219,47 @@ export function normalizeStores(list) {
     .filter((r) => r.id);
 }
 
+/**
+ * Detect whether a `client_list` tool result is an ERROR result rather than a
+ * genuinely empty-but-successful store list — so callers surface it (identity +
+ * origin + reason, per fb-1783905718950-f45zg9) instead of collapsing it to an
+ * empty list and dead-ending at "ask for an invite". callTool unwraps a tool
+ * result to its structuredContent / parsed text, so an error surfaces as a
+ * status other than ok/success, an `error`/`isError` field, or an unparseable
+ * `raw` text blob. A response that carries a resolvable store array (even empty)
+ * is always a success. Returns a short human reason, or null when it's not an
+ * error. Pure + exported so it's unit-tested without any I/O.
+ * @param {unknown} list
+ * @returns {string|null}
+ */
+export function storeListError(list) {
+  if (list == null || typeof list !== "object" || Array.isArray(list)) return null;
+  // A resolvable store array present → it succeeded, never an error.
+  if (Array.isArray(list.clients) || Array.isArray(list.tenants)) return null;
+  const msg =
+    list.message ||
+    (typeof list.error === "string" ? list.error : list.error?.message) ||
+    null;
+  if (list.isError) return msg || "the store list request returned an error";
+  if (typeof list.status === "string" && !/^(ok|success)$/i.test(list.status)) {
+    return msg || `the store list request returned status "${list.status}"`;
+  }
+  if (list.error) return msg || "the store list request returned an error";
+  if (typeof list.raw === "string" && list.raw.trim()) return list.raw.trim();
+  return null;
+}
+
 function printClientList(list) {
+  const err = storeListError(list);
   const stores = normalizeStores(list);
+  if (err && stores.length === 0) {
+    console.log(`\nCouldn't list your stores: ${err}`);
+    console.log("Run `tot whoami` to check your session, or `tot login` again.");
+    return;
+  }
   if (stores.length === 0) {
     console.log("\nNo stores available to build on for this identity yet.");
+    console.log("If you were just invited, it may still be propagating — try again in a minute.");
     if (list && !Array.isArray(list)) console.log(JSON.stringify(list, null, 2));
     return;
   }

package/src/commands/dev.mjs

@@ -8,7 +8,7 @@
  *              monorepo or --workspace graft mode). Fast host loop for platform devs.
  *
  *   checkout — a standalone tenant checkout has no runner. `tot dev` DOWNLOADS the
- *              published, moat-free RUNNER ARTIFACT (a plain tarball — the exact
+ *              published, RUNNER ARTIFACT (a plain tarball — the exact
  *              same tree Docker used to bake into the image, see
  *              scripts/build/build-runner.mjs) and runs it NATIVELY: no Docker, no
  *              container. Cached once per version under ~/.tot/cache/renderer/, so
@@ -40,7 +40,7 @@ import { Readable } from "node:stream";
 import { pipeline } from "node:stream/promises";
 import { setTimeout as delay } from "node:timers/promises";
 import { createMcpClient } from "../mcp.mjs";
-import { resolveSession } from "../auth.mjs";
+import { establishSession } from "../auth.mjs";
 import { CliError, fail, formatError } from "../errors.mjs";
 import { openBrowser, waitForServer } from "../open.mjs";
 import {
@@ -48,7 +48,7 @@ import {
   resolveRendererSource as resolveLocalRendererSource, SAMPLE_DIR_NAME,
 } from "../sample.mjs";
 
-/** The published moat-free runner image (--docker fallback). Override with --image / TOT_DEV_IMAGE. */
+/** The published runner image (--docker fallback). Override with --image / TOT_DEV_IMAGE. */
 const DEFAULT_DEV_IMAGE =
   "242086487598.dkr.ecr.us-east-1.amazonaws.com/tot-dev:latest";
 const DEFAULT_MCP_URL = "https://mcp.tokenoftrust.com";
@@ -147,16 +147,56 @@ async function runStandalone(workspace, args, ctx) {
     return await runNative(workspace, args, ctx);
   } catch (e) {
     if (e instanceof NativeArtifactUnavailableError) {
-      console.error(
-        `~ native runtime unavailable (${e.message}) — falling back to the Docker runner.`,
-      );
-      return runContainer(workspace, args, ctx);
+      // Entitled artifact unavailable — stay NATIVE on the public npm runner
+      // (@tokenoftrust/storefront-runner, the SAME renderer bits), so
+      // `tot dev` never needs Docker just because dev_renderer_artifact isn't
+      // 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).`);
+        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.`);
+          return runContainer(workspace, args, ctx);
+        }
+        console.error(formatError(e2));
+        return e2 instanceof CliError ? (e2.exitCode ?? 2) : 2;
+      }
     }
     console.error(formatError(e));
     return e instanceof CliError ? (e.exitCode ?? 2) : 2;
   }
 }
 
+/**
+ * Native boot against the PUBLIC/local renderer (no MCP, no
+ * entitlement) — the fallback for a standalone checkout when the entitled
+ * artifact isn't available. Mirrors runNative but resolves the renderer via
+ * ensureSampleRenderer (env override → cached runner → in-tree monorepo →
+ * public npm), which throws NativeArtifactUnavailableError when even the public
+ * runner can't be fetched (offline) so the caller can drop to Docker.
+ */
+async function runNativePublic(workspace, args, ctx) {
+  const cfg = readWorkspaceConfig(workspace);
+  if (!cfg) {
+    throw new CliError(`${workspace} isn't a tenant checkout (no readable .tot/config.json)`, {
+      next: "tot checkout <tenant> --clone <dir>   (produces a runnable checkout)",
+      exitCode: 2,
+    });
+  }
+  const port = String(args.port || "4321");
+  const { url } = deriveUrl(cfg, port);
+  let runnerDir;
+  try {
+    runnerDir = await ensureSampleRenderer(args, ctx);
+  } catch (e) {
+    throw new NativeArtifactUnavailableError(String(e?.message || e));
+  }
+  printDevBanner({ tenant: cfg.tenant || null, url });
+  return bootNative(runnerDir, workspace, port, url, args);
+}
+
 function runMonorepo(ctx, argv) {
   const script = join(ctx.repoRoot, "scripts", "tot-dev.mjs");
   if (!existsSync(script)) {
@@ -274,7 +314,7 @@ export function printSampleBanner({ url }) {
 }
 
 /**
- * Resolve WHERE to get the moat-free runner tarball for this run — the seam that
+ * Resolve WHERE to get the runner tarball for this run — the seam that
  * splits the entitled and the public (zero-login sample) delivery paths. Returns
  * `{ kind, version, url, strip, cacheKey }`; callers download + extract + install +
  * cache it uniformly (installRunnerTarball).
@@ -297,7 +337,7 @@ export async function resolveRendererSource(args, { client } = {}) {
 }
 
 /**
- * PUBLIC, un-entitled source for sample / zero-login mode: the moat-free runner
+ * PUBLIC, un-entitled source for sample / zero-login mode: the runner
  * straight from the public npm registry — NO MCP call, NO entitlement. Reads the
  * package's registry metadata (unauthenticated JSON) for the tarball URL + version.
  * Pin with `--renderer-version` / TOT_RUNNER_VERSION, else the `latest` dist-tag.
@@ -328,8 +368,9 @@ export async function resolveEntitledRendererSource(args, { client: providedClie
   const baseUrl = args.mcp || process.env.MCP_BASE_URL || process.env.TOT_MCP_URL || DEFAULT_MCP_URL;
   const client = providedClient || createMcpClient(baseUrl);
   if (!providedClient) {
-    await client.initialize();
-    await resolveSession(client, { env: process.env });
+    // Auth before the entitlement-gated tool call, in handshake order (developer
+    // bearer pre-initialize) — see establishSession.
+    await establishSession(client, { env: process.env });
   }
   const res = await client.callTool("dev_renderer_artifact", {});
   if (!res?.url || !res?.version) {
@@ -339,7 +380,7 @@ export async function resolveEntitledRendererSource(args, { client: providedClie
 }
 
 /**
- * Get the moat-free renderer artifact for this host — a signed URL from the MCP
+ * Get the renderer artifact for this host — a signed URL from the MCP
  * (dev_renderer_artifact, same entitlement gate as the Docker pull token),
  * downloaded + extracted + `pnpm install`'d ONCE per version under
  * ~/.tot/cache/renderer/<version>/. Later runs of the same version reuse the
@@ -360,8 +401,8 @@ export async function ensureRendererArtifact(args, { client: providedClient } =
   try {
     const client = providedClient || createMcpClient(baseUrl);
     if (!providedClient) {
-      await client.initialize();
-      await resolveSession(client, { env: process.env });
+      // Auth in handshake order before the entitlement-gated tool call.
+      await establishSession(client, { env: process.env });
     }
     const res = await client.callTool("dev_renderer_artifact", {});
     if (!res?.url || !res?.version) {
@@ -751,8 +792,7 @@ export function isPrivateRegistryImage(image) {
  * Entitlement-gated registry login: ask the MCP for a short-lived pull credential
  * (`dev_image_pull_token`) and `docker login` with it. Best-effort — if the MCP,
  * the session, or the tool isn't available yet, warn softly and continue (an
- * existing `docker login`, or the docker pull error, takes over). This is the CLI
- * half of ~/.tot-mcp/handoffs/2026-07-09-tot-mcp-dev-image-pull-token.md.
+ * existing `docker login`, or the docker pull error, takes over).
  *
  * Exported + accepts an already-authenticated `client` (C1: `tot start` reuses
  * its own session and overlaps this with the checkout clone instead of paying
@@ -765,8 +805,8 @@ export async function ensureRegistryLogin(image, args, { client: providedClient
   try {
     const client = providedClient || createMcpClient(baseUrl);
     if (!providedClient) {
-      await client.initialize();
-      await resolveSession(client, { env: process.env });
+      // Auth in handshake order before the entitlement-gated tool call.
+      await establishSession(client, { env: process.env });
     }
     const tok = await client.callTool("dev_image_pull_token", {});
     const username = tok?.username || "AWS";

package/src/commands/feedback.mjs

@@ -22,7 +22,7 @@
  */
 import { createInterface } from "node:readline/promises";
 import { createMcpClient } from "../mcp.mjs";
-import { resolveSession, AuthUnavailableError } from "../auth.mjs";
+import { establishSession, AuthUnavailableError } from "../auth.mjs";
 import { readActivity, formatActivity } from "../activity-log.mjs";
 import { fail } from "../errors.mjs";
 
@@ -145,8 +145,13 @@ export async function run(argv) {
   const mcpUrl = args.mcp || env.MCP_BASE_URL || env.TOT_MCP_URL || DEFAULT_MCP_URL;
   const client = createMcpClient(mcpUrl);
   try {
-    await resolveSession(client);
-    await client.initialize({ name: "tot-cli", version: "feedback" });
+    // Attach auth in the right order relative to the handshake (developer bearer
+    // pre-initialize, operator credential_validate post-initialize). We keep the
+    // feedback-specific clientInfo by injecting our own initialize.
+    await establishSession(client, {
+      env,
+      initialize: () => client.initialize({ name: "tot-cli", version: "feedback" }),
+    });
     const payload = {
       type: args.type,
       category: args.category,

package/src/commands/start.mjs

@@ -50,12 +50,12 @@ import { createInterface } from "node:readline/promises";
 
 import { detectContext } from "../context.mjs";
 import { createMcpClient } from "../mcp.mjs";
-import { resolveSession, AuthUnavailableError } from "../auth.mjs";
+import { establishSession, AuthUnavailableError } from "../auth.mjs";
 import { CliError, fail, formatError, exitCodeFor } from "../errors.mjs";
 import { openBrowser, waitForServer } from "../open.mjs";
 import { defaultLastTenantPath, readLastTenant, writeLastTenant } from "../last-tenant.mjs";
 import { collectChecks } from "./doctor.mjs";
-import { normalizeStores, checkoutTenant } from "./checkout.mjs";
+import { normalizeStores, storeListError, checkoutTenant } from "./checkout.mjs";
 import {
   buildContainerPlan, spawnDevContainer, dockerAvailable, tryStartDocker,
   resolveDevImage, isPrivateRegistryImage, ensureRegistryLogin,
@@ -93,12 +93,9 @@ const USAGE = `tot start — go from invite to a running store in one command
 
   tot start                 preflight → sign in → pick your store → check out →
                             run it → open your browser → connect Claude
-  tot start --sample        the FREE local preview — no login, no MCP, no account:
-                            scaffold + run a sample store, then offer the MCP upsell
 Options:
   --tenant <id>    use this store (skips auto-pick/prompt; remembered for next time)
   --port <n>       host port for the dev server (default 4321)
-  --sample         zero-login free taste (see above); also what a no-session run offers
   --docker         use the Docker runner instead of the native runtime (F3
                     default); also the automatic fallback if the native
                     artifact can't be fetched
@@ -183,8 +180,8 @@ export async function run(argv, ctx) {
     const session = await tryResolveSession(client, env, args);
     if (decideStartMode({ sampleFlag: false, hasSession: !!session }) === "sample") {
       if (!(await confirmSampleFallback(args))) {
-        throw new CliError("no Token of Trust session, and you declined the free local preview", {
-          next: "tot login   (then re-run `tot start`), or `tot start --sample` for the free local preview",
+        throw new CliError("no Token of Trust session", {
+          next: "tot login   (then re-run `tot start`)",
         });
       }
       return await runSampleStart(args, ctx, env, startedAt);
@@ -193,11 +190,17 @@ export async function run(argv, ctx) {
     // Authenticated path. Preflight (F) now that we know we're taking it — the
     // local machine checks (node/git/Docker) that the authed loop needs.
     await preflight(ctx, env);
-    console.log(`  ✓ signed in as ${session.identity}${session.appDomain ? ` (${session.appDomain})` : ""}`);
+    console.log(`  ✓ signed in as ${describeIdentity(session)} via ${mcpOrigin(baseUrl)}`);
 
     // 3. store — auto-pick, use --tenant, use the remembered one, or choose (A4).
-    const stores = normalizeStores(await client.callTool("client_list", {}));
-    const tenant = await resolveTenant(stores, args, env, baseUrl);
+    // Keep the raw client_list so a tool ERROR (unauthenticated / not-entitled) is
+    // surfaced with who + where, not collapsed to an empty list (fb-...f45zg9).
+    const listResp = await client.callTool("client_list", {});
+    const stores = normalizeStores(listResp);
+    const tenant = await resolveTenant(stores, args, env, baseUrl, {
+      session,
+      listErr: storeListError(listResp),
+    });
 
     // 4. checkout → ./<tenant> (reuse an existing checkout on a re-run),
     // OVERLAPPED (C1) with prefetching the runner: the native artifact by
@@ -213,7 +216,7 @@ export async function run(argv, ctx) {
     const runtime = { useDocker: args.docker, runnerDir: null };
     await Promise.all([
       ensureCheckout(client, tenant, dir, env),
-      prefetchRuntime(client, devArgs, env, runtime),
+      prefetchRuntime(client, devArgs, env, runtime, ctx),
     ]);
 
     // 5. dev — native by default (F3), Docker on --docker or the fallback
@@ -340,14 +343,24 @@ async function runSampleStart(args, ctx, env, startedAt) {
  * AuthUnavailableError (no creds) or a CliError (can't reach the MCP).
  */
 async function loginStep(client, env, args) {
-  try {
-    await client.initialize();
-  } catch (e) {
-    throw new CliError(`can't reach the Token of Trust MCP at ${client.mcpUrl} (${String(e?.message || e)})`, {
-      next: "check your network, then re-run — or point elsewhere with --mcp <url>",
-    });
-  }
-  return resolveSession(client, { env, prefer: args.identity || undefined });
+  // establishSession attaches auth in the right order relative to the handshake:
+  // the developer bearer BEFORE initialize (so the server binds this identity at
+  // initialize time — otherwise the session is anonymous and client_list is empty),
+  // the operator credential_validate after it. We inject our own initialize so the
+  // unreachable-MCP case still surfaces the actionable CliError below.
+  return establishSession(client, {
+    env,
+    prefer: args.identity || undefined,
+    initialize: async () => {
+      try {
+        await client.initialize();
+      } catch (e) {
+        throw new CliError(`can't reach the Token of Trust MCP at ${client.mcpUrl} (${String(e?.message || e)})`, {
+          next: "check your network, then re-run — or point elsewhere with --mcp <url>",
+        });
+      }
+    },
+  });
 }
 
 /**
@@ -402,11 +415,16 @@ async function preflight(ctx, env) {
  * Prefetch the runner (C1) so it's overlapped with checkout instead of paid
  * for serially afterward: the native renderer artifact by default (F3 — no
  * Docker prerequisite), or the Docker registry pull credential on --docker.
- * On a native fetch failure, falls back to Docker automatically — the same
- * fallback `tot dev` uses (dev.mjs#runStandalone) — flipping
- * `runtime.useDocker` so the caller's subsequent dev step picks it up.
+ *
+ * On a native (entitled-artifact) fetch failure the runtime stays NATIVE: it
+ * falls back to the PUBLIC npm runner (@tokenoftrust/storefront-runner) — the
+ * SAME renderer bits the entitled artifact ships, just delivered over
+ * public npm instead of a signed URL — so `tot dev`/`tot start` never require
+ * Docker just because `dev_renderer_artifact` isn't configured on a deployment.
+ * Docker is the LAST resort, only when the public runner is also unreachable
+ * (offline) — flipping `runtime.useDocker` so the caller's dev step picks it up.
  */
-async function prefetchRuntime(client, devArgs, env, runtime) {
+async function prefetchRuntime(client, devArgs, env, runtime, ctx) {
   if (runtime.useDocker) {
     await prefetchDockerLogin(client, devArgs, env);
     return;
@@ -415,9 +433,15 @@ async function prefetchRuntime(client, devArgs, env, runtime) {
     runtime.runnerDir = await ensureRendererArtifact(devArgs, { client });
   } catch (e) {
     if (!(e instanceof NativeArtifactUnavailableError)) throw e;
-    console.log(`  ~ native runtime unavailable (${e.message}) — falling back to the Docker runner.`);
-    runtime.useDocker = true;
-    await prefetchDockerLogin(client, devArgs, env);
+    // Entitled artifact unavailable — stay native on the public runner (no Docker).
+    try {
+      console.log(`  ~ entitled renderer unavailable (${e.message}) — using the public runner (no Docker).`);
+      runtime.runnerDir = await ensureSampleRenderer(devArgs, ctx, { env });
+    } catch (e2) {
+      console.log(`  ~ public runner unavailable (${e2?.message || e2}) — falling back to the Docker runner.`);
+      runtime.useDocker = true;
+      await prefetchDockerLogin(client, devArgs, env);
+    }
   }
 }
 
@@ -436,12 +460,58 @@ async function prefetchDockerLogin(client, devArgs, env) {
   if (!dockerAvailable()) await tryStartDocker();
 }
 
+/** A human label for a resolved session — the email when we could read it from
+ * the OAuth token, else the operator app domain, else the identity kind. */
+function describeIdentity(session) {
+  if (!session) return "an unknown identity";
+  if (session.email) return session.email;
+  if (session.identity === "operator") {
+    return session.appDomain ? `operator (${session.appDomain})` : "operator";
+  }
+  return "your developer identity";
+}
+
+/** The MCP host for user-facing messages (never the full /mcp URL). */
+function mcpOrigin(baseUrl) {
+  try {
+    return new URL(baseUrl).host;
+  } catch {
+    return String(baseUrl);
+  }
+}
+
+/**
+ * Build the CliError for an authenticated session that surfaced NO usable store,
+ * making the dead-end SELF-DIAGNOSING (fb-1783905718950-f45zg9): always report who
+ * we're signed in as and against which MCP, and distinguish an ERRORED client_list
+ * (surface the reason — likely an auth/entitlement problem) from a genuinely empty
+ * result (invite may still be propagating, or you need one). Points at `tot whoami`.
+ */
+function noStoresError({ session, baseUrl, listErr }) {
+  const who = describeIdentity(session);
+  const origin = mcpOrigin(baseUrl);
+  if (listErr) {
+    return new CliError(
+      `signed in as ${who} via ${origin}, but listing your stores failed: ${listErr}`,
+      { next: "run `tot whoami` to check your session, or `tot login` again — then re-run `tot start`" },
+    );
+  }
+  return new CliError(
+    `signed in as ${who} via ${origin}, but you have no stores to build on yet`,
+    {
+      next:
+        "if you were just invited, it may still be propagating — try again in a minute; " +
+        "otherwise ask your Token of Trust contact for a store invite (see `tot whoami`)",
+    },
+  );
+}
+
 /**
  * Resolve the tenant to work on from the (normalized) store list, args, and
  * the remembered last tenant (A4) — then remember whatever was decided so the
  * next bare `tot start` doesn't have to ask again.
  */
-async function resolveTenant(stores, args, env, baseUrl) {
+async function resolveTenant(stores, args, env, baseUrl, { session = null, listErr = null } = {}) {
   const lastTenantPath = defaultLastTenantPath(env);
   const pick = pickTenant(stores, {
     explicit: args.tenant || null,
@@ -450,9 +520,7 @@ async function resolveTenant(stores, args, env, baseUrl) {
 
   let tenant;
   if (pick.kind === "none") {
-    throw new CliError("no stores you can build on yet", {
-      next: "ask your Token of Trust contact for a store invite, then re-run — or `tot start --sample` for the free local preview",
-    });
+    throw noStoresError({ session, baseUrl, listErr });
   } else if (pick.kind === "explicit") {
     tenant = pick.tenant;
     console.log(`  → your store: ${tenant} (--tenant)`);

package/src/commands/submit.mjs

@@ -7,9 +7,8 @@
  *   3. report back — reconcile result + compliance verdict + the preview URL — from the MCP.
  *
  * This is submit-for-PREVIEW, not ship-to-live (`change_accept` / a future `tot ship`
- * is the separate ship gate). Step 3 calls the MCP `preview_status` read-back
- * (~/.tot-mcp/handoffs/2026-07-09-tot-mcp-tot-submit-contract.md): given the commit
- * just pushed it returns { status, reconcile, compliance, previewUrl } and we poll it
+ * is the separate ship gate). Step 3 calls the MCP `preview_status` read-back:
+ * given the commit just pushed it returns { status, reconcile, compliance, previewUrl } and we poll it
  * while reconcile is pending. If that tool isn't present (older MCP) the command still
  * validates + pushes and reports "reconcile pending" — degrading visibly, never a crash.
  *
@@ -33,7 +32,7 @@
 import { execFileSync } from "node:child_process";
 import { setTimeout as delay } from "node:timers/promises";
 import { createMcpClient } from "../mcp.mjs";
-import { resolveSession, AuthUnavailableError } from "../auth.mjs";
+import { establishSession, AuthUnavailableError } from "../auth.mjs";
 import { validateTenant, ERROR } from "../validate.mjs";
 import { openBrowser } from "../open.mjs";
 import { fail } from "../errors.mjs";
@@ -138,8 +137,9 @@ export async function run(argv, ctx) {
   const baseUrl = args.mcp || env.MCP_BASE_URL || env.TOT_MCP_URL || DEFAULT_MCP_URL;
   const client = createMcpClient(baseUrl);
   try {
-    await client.initialize();
-    await resolveSession(client, { env, prefer: args.identity || undefined });
+    // Attach auth before the first server call (developer bearer pre-initialize,
+    // operator credential_validate post-initialize) — see establishSession.
+    await establishSession(client, { env, prefer: args.identity || undefined });
     // 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 });
@@ -230,8 +230,8 @@ const CHECK_GLYPH = { pass: "✓", fail: "✗", warn: "⚠", skip: "~" };
 
 /**
  * Print one per-rule compliance check: id/label, required-ness, why it didn't
- * pass (detail), and a concrete fix suggestion (hint) when there is one. This is
- * the moat over a bare pass/fail — an agent (or a human) reading `tot submit`
+ * pass (detail), and a concrete fix suggestion (hint) when there is one. This
+ * beats a bare pass/fail — an agent (or a human) reading `tot submit`
  * output should know exactly what to change and why, with no dashboard round-trip.
  */
 function reportComplianceCheck(c) {