@tokenoftrust/cli 1.4.0-rc.1 → 1.4.0-rc.11

package/src/commands/dev.mjs

@@ -138,7 +138,7 @@ export async function run(argv, ctx) {
     console.error(
       fail(
         "nothing to run — you're not inside a tenant checkout",
-        "tot checkout <tenant> --clone <dir>   (then `cd` in and re-run), pass --workspace <dir>, or try `tot dev --sample`",
+        "tot clone <tenant>   (then `cd` in and re-run), pass --workspace <dir>, or try `tot dev --sample`",
       ),
     );
     return 2;
@@ -194,7 +194,7 @@ 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)",
+      next: "tot clone <tenant>   (produces a runnable checkout)",
       exitCode: 2,
     });
   }
@@ -280,7 +280,7 @@ async function runNative(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)",
+      next: "tot clone <tenant>   (produces a runnable checkout)",
       exitCode: 2,
     });
   }
@@ -700,6 +700,66 @@ export function pinnedPublicCacheDir(cacheRoot, version) {
   return existsSync(join(dir, ".tot-cache-complete")) ? dir : null;
 }
 
+/**
+ * List the installed package dirs that could carry a platform-native binary,
+ * normalised so a scoped package reads as `@scope+name` (mirroring pnpm's virtual
+ * store naming) regardless of the on-disk layout. Prefers the pnpm virtual store
+ * (`node_modules/.pnpm/*`); falls back to a shallow `node_modules` scan (one level
+ * into `@scope/`) for an npm/flat install. Best-effort — returns [] on any error.
+ */
+function collectNativePackageDirs(runnerDir) {
+  const pnpmDir = join(runnerDir, "node_modules", ".pnpm");
+  if (existsSync(pnpmDir)) return readdirSync(pnpmDir);
+  const nm = join(runnerDir, "node_modules");
+  if (!existsSync(nm)) return [];
+  const names = [];
+  for (const e of readdirSync(nm, { withFileTypes: true })) {
+    if (e.name.startsWith("@") && e.isDirectory()) {
+      for (const s of readdirSync(join(nm, e.name))) names.push(`${e.name}+${s}`);
+    } else {
+      names.push(e.name);
+    }
+  }
+  return names;
+}
+
+/**
+ * True unless the installed renderer is POISONED for this host's CPU arch — the
+ * "the dev server didn't come up" root cause. Platform-native binding packages
+ * are named `<family>-<os>-<cpu>[-<abi>]` (e.g. `@esbuild/darwin-arm64`,
+ * `lightningcss-linux-x64-gnu`, `@rollup/rollup-win32-x64-msvc`). npm's optional-
+ * deps bug (npm/cli#4828) can materialise a DIFFERENT arch's variant than the host
+ * needs (e.g. darwin-x64 on an arm64 Mac) — pnpm gets it right. We flag the tree
+ * as poisoned exactly when a family ships a binding for our OS but NOT our OS+CPU,
+ * which is the precise shape of the `Cannot find native binding` boot crash. A
+ * family with no variant for our OS at all is a cross-platform optional dep that's
+ * correctly absent, so it never trips the check. Never throws; on any probe error
+ * it returns true (trust the cache) so a health probe can't itself break `tot dev`.
+ *
+ * `platform`/`arch` are injectable so this is testable off the host's real arch.
+ */
+export function rendererCacheHealthy(runnerDir, { platform = process.platform, arch = process.arch } = {}) {
+  try {
+    const re = /^(.*?)[-+](darwin|linux|win32|freebsd|android|openharmony)-([a-z0-9]+)/;
+    const families = new Map(); // family -> Set("<os>-<cpu>")
+    for (const name of collectNativePackageDirs(runnerDir)) {
+      const m = name.match(re);
+      if (!m) continue;
+      const [, family, os, cpu] = m;
+      if (!families.has(family)) families.set(family, new Set());
+      families.get(family).add(`${os}-${cpu}`);
+    }
+    const want = `${platform}-${arch}`;
+    for (const variants of families.values()) {
+      const hasOurOs = [...variants].some((v) => v.startsWith(`${platform}-`));
+      if (hasOurOs && !variants.has(want)) return false; // wrong-arch binary present, ours missing
+    }
+    return true;
+  } catch {
+    return true;
+  }
+}
+
 /**
  * Delete every OTHER public-runner cache dir (`public-*` except `keepVersion`)
  * once we've resolved the version this CLI pins to — so a pre-alignment dir
@@ -814,8 +874,12 @@ export async function ensureSampleRenderer(args, ctx, { env = process.env, cache
       // Trust-but-verify: a `public-<version>` dir SHOULD be a current runner,
       // but if it can't report its own version it predates the --version surface
       // (a corrupt/half-migrated cache) — force a fresh fetch rather than run a
-      // runner we can't identify. When it DOES answer, reuse it (fully offline-safe).
-      if (probeRunnerVersion(exact)) {
+      // runner we can't identify. It must ALSO carry native bindings for THIS
+      // 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).
+      if (probeRunnerVersion(exact) && rendererCacheHealthy(exact)) {
         console.error(
           `~ renderer: cached public runner ${wantVersion} (${declared ? "declared by this store" : "matches this CLI"})`,
         );
@@ -823,7 +887,11 @@ export async function ensureSampleRenderer(args, ctx, { env = process.env, cache
         prunePublicRunnerCache(cacheRoot, wantVersion);
         return exact;
       }
-      console.error(`~ renderer: cached runner at ${exact} can't report a version — refetching (forced upgrade)`);
+      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
     }
   }
@@ -888,7 +956,15 @@ function sourceVersionKey(source) {
 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)) return runnerDir; // already downloaded + installed
+  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…`);
+  }
 
   // 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
@@ -939,6 +1015,21 @@ export async function installRunnerTarball({ source, version, isUrl = true, stri
     // 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,
+        },
+      );
+    }
     writeFileSync(marker, new Date().toISOString());
   } finally {
     if (isUrl) rmSync(archivePath, { force: true });
@@ -1059,21 +1150,25 @@ function spawnAsyncResult(cmd, args, opts = {}) {
 export async function runPnpmInstall(runnerDir, { logPath, spawnFn = spawnAsyncResult } = {}) {
   const fd = logPath ? openSync(logPath, "a") : null;
   const installArgs = ["install", "--config.dangerouslyAllowAllBuilds=true"];
-  // npm FIRST: it ships with EVERY Node (including 25+, where corepack is no
-  // longer bundled), so it's the launcher with zero machine-specific setup —
-  // no global pnpm, no corepack shim dance. The runner tree is built to be
-  // npm-installable (build-runner.mjs rewrites `workspace:*` → "*" and emits an
-  // npm `workspaces` field; verified end-to-end with both installers). pnpm and
-  // the corepack-pinned pnpm remain as fallbacks for hosts with a broken npm.
+  // pnpm FIRST: the renderer tree is a bundle of native optional deps (rolldown,
+  // esbuild, sharp, @rollup, lightningcss, @tailwindcss/oxide, @astrojs/compiler,
+  // workerd), and npm's optional-deps bug (npm/cli#4828) routinely installs the
+  // WRONG arch's binary or none — poisoning the cache so astro crashes at boot with
+  // `Cannot find native binding`. pnpm resolves per-platform optional bindings
+  // correctly (proven end-to-end). ensureCorepackPnpm() ran just above, so on the
+  // Node floor (22.12, which bundles corepack) pnpm is available; `corepack pnpm`
+  // is the shim path if a bare `pnpm` isn't on PATH. npm stays LAST as the escape
+  // hatch for hosts with neither pnpm nor corepack — where rendererCacheHealthy()
+  // then fences a poisoned result rather than shipping a broken cache silently.
   // If a launcher isn't installed at all (ENOENT) we move on; a launcher that
   // RAN but whose install failed is the real error and stops the loop.
   // REQUIRES a runner >= 1.3.4-rc.2 — older runner tarballs still carry
   // `workspace:*` deps npm rejects (harmless here: pickRunnerVersion pins the
   // runner to this CLI's version, so this CLI never installs those).
   const attempts = [
-    { cmd: "npm", args: ["install", "--no-audit", "--no-fund"] },
     { cmd: "pnpm", args: installArgs },
     { cmd: "corepack", args: ["pnpm", ...installArgs] },
+    { cmd: "npm", args: ["install", "--no-audit", "--no-fund"] },
   ];
   try {
     for (const { cmd, args } of attempts) {
@@ -1240,7 +1335,7 @@ export function buildContainerPlan(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)",
+      next: "tot clone <tenant>   (produces a runnable checkout)",
       exitCode: 2,
     });
   }

package/src/commands/doctor.mjs

@@ -1,7 +1,7 @@
 /**
  * `tot doctor` — is this machine ready to run the loop?
  *
- * Standalone (unlike the in-monorepo doctor): checks the things `tot checkout`
+ * Standalone (unlike the in-monorepo doctor): checks the things `tot clone`
  * and `tot dev`/`tot start` actually need — Node, git, an MCP URL, whether an
  * auth identity is available, and Docker — plus reports the detected context
  * so a developer knows which mode `tot` will use here.
@@ -187,7 +187,8 @@ export async function run(argv, ctx) {
   }
   console.log(
     failed === 0
-      ? "\n✔ Ready. Try: tot start   (checks out your store and runs it), or tot checkout\n"
+      ? "\n✔ Ready. Try: tot start   (checks out your store and runs it), or tot clone." +
+        "\n  The loop: tot dev → tot preview → tot ship.\n"
       : args.fix
         ? `\n✖ ${failed} check(s) still failing — see the exact next command(s) above, then re-run \`tot doctor\`.\n`
         : `\n✖ ${failed} check(s) failed — try \`tot doctor --fix\`, or fix the above, then re-run \`tot doctor\`.\n`,
@@ -199,5 +200,5 @@ function describeContext(ctx) {
   if (ctx.mode === "monorepo") return `storefront monorepo (${ctx.repoRoot})`;
   if (ctx.mode === "checkout")
     return `tenant checkout${ctx.tenant ? ` for "${ctx.tenant}"` : ""} (${ctx.workspacePath})`;
-  return "loose (not inside a checkout — `tot checkout <tenant> --clone <dir>` to get one)";
+  return "loose (not inside a checkout — `tot clone <tenant>` to get one)";
 }

package/src/commands/grants.mjs

@@ -26,7 +26,7 @@
 import { defaultCredentialsPath, readCredentials } from "../token-store.mjs";
 import { establishSession, AuthUnavailableError } from "../auth.mjs";
 import { createMcpClient } from "../mcp.mjs";
-import { storeListError } from "./checkout.mjs";
+import { storeListError, noStoresGuidance } from "./clone.mjs";
 import { offerSignIn } from "./login.mjs";
 import { recordServerPolicy } from "../update-check.mjs";
 
@@ -238,8 +238,13 @@ export async function run(argv, _ctx) {
     return 1;
   }
   if (rows.length === 0) {
-    console.log("\nNo stores you can act on yet for this identity.");
-    console.log("If you were just invited, it may still be propagating — try again in a minute.");
+    // Status-aware, like whoami/checkout (card c2): an UNLINKED identity is told to
+    // link, not given the "may still be propagating" copy — that's only the genuine
+    // linked-but-zero-grants case.
+    const g = noStoresGuidance(resp);
+    const line = g.headline.charAt(0).toUpperCase() + g.headline.slice(1);
+    console.log(`\n${line}.`);
+    console.log(`Next: ${g.next}`);
     return 0;
   }
 

package/src/commands/link.mjs

@@ -0,0 +1,225 @@
+/**
+ * `tot link` — link your signed-in Token of Trust identity to the ToT identity
+ * broker so your store scope can be resolved.
+ *
+ * Some developers sign in fine (a valid ToT OAuth session) but their identity
+ * isn't yet linked to the broker that maps a person → the tenants they can build
+ * on — so `tot start` / `tot clone` / `tot whoami` resolve ZERO stores. That's
+ * NOT a "you weren't invited" problem and NOT "the invite is still propagating";
+ * it's a one-time link step. This command drives it end-to-end from the terminal:
+ *
+ *   identity_link_begin           → the MCP returns an authUrl + a poll handle
+ *   open the authUrl              → you approve the link in the browser
+ *   identity_link_poll(handle)    → we poll until it's linked, then confirm scope
+ *
+ * It reuses the SAME auth ceremony as the rest of the CLI (establishSession — the
+ * cached `tot login` session, offering an inline sign-in when there's none and
+ * we're on a TTY), so a not-signed-in developer isn't dead-ended.
+ *
+ * Dependency-free (node built-ins via mcp.mjs / auth.mjs / open.mjs).
+ */
+import { setTimeout as delay } from "node:timers/promises";
+import { createMcpClient } from "../mcp.mjs";
+import { establishSession, AuthUnavailableError } from "../auth.mjs";
+import { offerSignIn } from "./login.mjs";
+import { openBrowser } from "../open.mjs";
+import { CliError, fail, formatError } from "../errors.mjs";
+import { normalizeStores } from "./clone.mjs";
+
+const DEFAULT_MCP_URL = "https://mcp.tokenoftrust.com";
+
+function parseArgs(argv) {
+  const a = { mcp: null, help: false };
+  for (let i = 0; i < argv.length; i++) {
+    const t = argv[i];
+    if (t === "--mcp") a.mcp = argv[++i];
+    else if (t === "--help" || t === "-h") a.help = true;
+  }
+  return a;
+}
+
+const USAGE = `tot link — link your Token of Trust identity so your stores resolve
+
+  tot link                  open the browser, approve the link, confirm your scope
+  tot link --mcp <url>      MCP base URL (default: env MCP_BASE_URL / TOT_MCP_URL)
+
+Run this when \`tot whoami\` / \`tot start\` say your identity isn't linked yet.`;
+
+/**
+ * Tolerant extraction of the fields `identity_link_begin` returns. The link URL
+ * and poll handle field names can vary by server version, so probe the known
+ * candidates (the `pollHandle` name is fixed by the identity_link_poll contract).
+ * Pure + exported so it's unit-tested without any I/O.
+ * @param {unknown} res
+ * @returns {{ authUrl: string|null, pollHandle: string|null }}
+ */
+export function linkBeginFields(res) {
+  const c = res && typeof res === "object" && !Array.isArray(res) ? res : {};
+  const authUrl =
+    c.authUrl ||
+    c.url ||
+    c.verificationUrl ||
+    c.verificationUriComplete ||
+    c.verification_uri_complete ||
+    null;
+  const pollHandle = c.pollHandle || c.handle || c.poll_handle || c.pollHandleId || null;
+  return {
+    authUrl: typeof authUrl === "string" && authUrl ? authUrl : null,
+    pollHandle: typeof pollHandle === "string" && pollHandle ? pollHandle : null,
+  };
+}
+
+/**
+ * Classify an `identity_link_poll` result into 'linked' | 'pending' | a raw error
+ * status. Tolerant of the shape (a boolean flag, or a status/state string) so a
+ * server-version drift doesn't strand the poll. Pure + exported for unit tests.
+ * @param {unknown} res
+ * @returns {"linked"|"pending"|string}
+ */
+export function linkPollStatus(res) {
+  const c = res && typeof res === "object" && !Array.isArray(res) ? res : {};
+  if (c.linked === true || c.done === true || c.complete === true) return "linked";
+  const raw =
+    (typeof c.status === "string" && c.status) || (typeof c.state === "string" && c.state) || "";
+  const s = raw.toLowerCase();
+  if (!s) return "pending";
+  // The broker namespaces its poll status with a `link_` prefix (e.g. `link_pending`,
+  // `link_approved`, `link_denied`) — strip it before matching so a normal "still
+  // waiting" state isn't misread as an unknown/error status and doesn't abort the poll.
+  // (Regression: `link_pending` fell through to the error branch and killed `tot link`
+  // the instant the developer hadn't yet finished the browser step.)
+  const bare = s.replace(/^link[_-]/, "");
+  if (/^(linked|link|complete|completed|done|ok|success|succeeded|active|approved|granted)$/.test(bare))
+    return "linked";
+  if (/^(pending|waiting|in_?progress|processing|started|created|authorizing|polling)$/.test(bare))
+    return "pending";
+  return s; // a terminal error status (link_denied, link_expired, …) — surfaced to the caller
+}
+
+/** @param {string[]} argv @param {any} _ctx */
+export async function run(argv, _ctx) {
+  const env = process.env;
+  const args = parseArgs(argv);
+  if (args.help) {
+    console.log(USAGE);
+    return 0;
+  }
+
+  const baseUrl = args.mcp || env.MCP_BASE_URL || env.TOT_MCP_URL || DEFAULT_MCP_URL;
+  const client = createMcpClient(baseUrl);
+
+  try {
+    // Same auth ordering as checkout/start — developer bearer BEFORE initialize —
+    // and the same inline sign-in offer so a not-signed-in dev isn't dead-ended.
+    try {
+      await establishSession(client, { env });
+    } catch (e) {
+      if (e instanceof AuthUnavailableError && e.reason === "missing") {
+        const signedIn = await offerSignIn(client.mcpUrl, env, {});
+        if (!signedIn) throw e;
+        await establishSession(client, { env });
+      } else {
+        throw e;
+      }
+    }
+    console.error(`~ signed in → ${client.mcpUrl}`);
+
+    console.error("~ identity_link_begin — asking Token of Trust to start the link");
+    let begin;
+    try {
+      begin = await client.callTool("identity_link_begin", {});
+    } catch (e) {
+      throw new CliError(`couldn't start the identity link: ${String(e?.message || e)}`, {
+        next: "your MCP may not support `tot link` yet — run `tot whoami` for the current guidance",
+      });
+    }
+    const { authUrl, pollHandle } = linkBeginFields(begin);
+    if (!pollHandle) {
+      throw new CliError("Token of Trust didn't return a link handle to poll", {
+        next: "re-run `tot link`, or run `tot whoami` for the current guidance",
+      });
+    }
+
+    if (authUrl) {
+      const opened = openBrowser(authUrl);
+      console.log(
+        opened
+          ? `\n+ opening your browser to finish linking:\n  ${authUrl}`
+          : `\nOpen this URL to finish linking your identity:\n  ${authUrl}`,
+      );
+    } else {
+      console.log("\n+ finishing the link — no approval step needed …");
+    }
+
+    const linked = await pollLink(client, pollHandle, {
+      log: (m) => console.error(m),
+    });
+    if (!linked) {
+      throw new CliError("the identity link didn't complete in time", {
+        next: "finish the approval in your browser, then re-run `tot link`",
+      });
+    }
+
+    console.log("\n+ your identity is linked.");
+    // Confirm scope now resolves — best-effort, so a transient list hiccup doesn't
+    // fail an otherwise-successful link.
+    try {
+      const list = await client.callTool("client_list", {});
+      const stores = normalizeStores(list);
+      if (stores.length) {
+        console.log(`  stores you can build on: ${stores.map((s) => s.id).join(", ")}`);
+        console.log("  Next: `tot start` (or `tot clone <tenant>`).");
+      } else {
+        console.log("  Next: `tot start` — if it still shows no stores, ask your ToT contact for a store invite.");
+      }
+    } catch {
+      console.log("  Next: `tot start` to build your store.");
+    }
+    return 0;
+  } catch (e) {
+    if (e instanceof AuthUnavailableError || e instanceof CliError) {
+      console.error(formatError(e));
+      return e instanceof CliError ? (e.exitCode ?? 1) : 1;
+    }
+    console.error(fail(`link failed: ${String(e?.message || e)}`));
+    return 1;
+  }
+}
+
+/**
+ * Poll `identity_link_poll(pollHandle)` until the link is complete, or give up
+ * after `timeoutMs`. Returns true on 'linked', false on timeout; throws a CliError
+ * on a definite error status the server reports. Injectable clock/interval keep it
+ * unit-testable, but the default path is the live poll.
+ * @param {ReturnType<import("../mcp.mjs").createMcpClient>} client
+ * @param {string} pollHandle
+ * @param {{ timeoutMs?: number, intervalMs?: number, log?: (m:string)=>void }} [opts]
+ * @returns {Promise<boolean>}
+ */
+export async function pollLink(client, pollHandle, { timeoutMs = 120000, intervalMs = 2500, log = () => {} } = {}) {
+  const deadline = Date.now() + timeoutMs;
+  let announced = false;
+  while (Date.now() < deadline) {
+    let res;
+    try {
+      res = await client.callTool("identity_link_poll", { pollHandle });
+    } catch (e) {
+      // A transient poll error isn't fatal — keep trying until the deadline.
+      await delay(intervalMs);
+      continue;
+    }
+    const status = linkPollStatus(res);
+    if (status === "linked") return true;
+    if (status !== "pending") {
+      throw new CliError(`Token of Trust reported the link couldn't complete (${status})`, {
+        next: "re-run `tot link`, or run `tot whoami` for the current guidance",
+      });
+    }
+    if (!announced) {
+      log("~ waiting for you to approve the link in your browser …");
+      announced = true;
+    }
+    await delay(intervalMs);
+  }
+  return false;
+}

package/src/commands/login.mjs

@@ -4,7 +4,7 @@
  * Runs the MCP OAuth 2.1 PKCE loopback (the same ceremony `claude mcp add` runs):
  * opens the browser to the MCP's authorize page, the developer signs in with their
  * ToT identity + approves, and the loopback catches the code and exchanges it for a
- * token cached at ~/.tot/credentials.json. Every later command (`tot checkout`,
+ * token cached at ~/.tot/credentials.json. Every later command (`tot clone`,
  * `tot submit`, …) then runs as that developer with NO re-auth.
  *
  * The MCP defaults to the same target `tot submit` talks to (env MCP_BASE_URL /
@@ -19,12 +19,13 @@
  *
  * Dependency-free (node built-ins via oauth.mjs).
  */
-import { loginFlow, deviceLoginFlow, redeemCodeFlow, NoOpenerError } from "../oauth.mjs";
+import { loginFlow, deviceLoginFlow, rendezvousLoginFlow, NoOpenerError } from "../oauth.mjs";
 import { defaultCredentialsPath, readCredentials, writeCredentials } from "../token-store.mjs";
 import { openBrowser } from "../open.mjs";
 import { fail } from "../errors.mjs";
 import { cockpitRecoveryUrl, normalizeEmailHint, redactEmailForHint, emailFromJwt } from "../auth.mjs";
 import { isInteractive, promptYesNo } from "../prompt.mjs";
+import { versionStamp } from "../mcp.mjs";
 
 const DEFAULT_MCP_URL = "https://mcp.tokenoftrust.com";
 
@@ -108,7 +109,7 @@ const USAGE = `tot login — sign in to Token of Trust
   link a later \`tot feedback\` report to your invite + session) — not meant to be
   typed by hand.
 
-After signing in, run \`tot whoami\` to confirm, then \`tot checkout\` / \`tot submit\`.`;
+After signing in, run \`tot whoami\` to confirm, then \`tot clone\` / \`tot submit\`.`;
 
 /**
  * The core of `tot login`: run the OAuth ceremony (browser loopback, or the
@@ -188,23 +189,25 @@ export async function offerSignIn(mcpUrl, env = process.env, {
 }
 
 /**
- * The core of `tot login --code`: run the browserless redemption (POST the invite
- * token to the MCP, get a grant back) and cache it, reusing a previously-registered
- * client for THIS MCP so we don't re-register on every login.
+ * The core of `tot login --code`: run the browserless RENDEZVOUS sign-in (attach the
+ * terminal's PKCE challenge to the pasted rendezvous handle, surface the fingerprint,
+ * poll until the developer approves it in the cockpit) and cache the grant, reusing a
+ * previously-registered client for THIS MCP so we don't re-register on every login.
+ * `log` carries the fingerprint + "waiting for approval" lines to the terminal.
  * @returns {Promise<object>} the credentials written to disk.
  */
-export async function redeemAndCache(mcpUrl, code, env = process.env) {
+export async function redeemAndCache(mcpUrl, code, env = process.env, { log = () => {} } = {}) {
   const path = defaultCredentialsPath(env);
   const prior = readCredentials(path);
   const clientId = prior && prior.mcpUrl === mcpUrl ? prior.clientId : undefined;
-  const creds = await redeemCodeFlow({ mcpUrl, clientId, code });
+  const creds = await rendezvousLoginFlow({ mcpUrl, clientId, code, log });
   const merged = mergeActivityBridge(prior, mcpUrl, creds);
   writeCredentials(path, merged);
   return merged;
 }
 
 /**
- * `loginFlow`/`deviceLoginFlow`/`redeemCodeFlow` all return the bare OAuth shape —
+ * `loginFlow`/`deviceLoginFlow`/`rendezvousLoginFlow` all return the bare OAuth shape —
  * none of them know about activityToken/activityUrl, a SEPARATE credential this
  * same file caches via cacheActivityBridge. A bare re-login (no --code) after a
  * prior --code sign-in would otherwise silently drop it on the next `writeCredentials`
@@ -253,17 +256,21 @@ export async function run(argv, _ctx) {
     return 0;
   }
 
+  // Show which CLI/runtime is actually running BEFORE anything else — the first thing
+  // a "why did sign-in behave oddly" investigation needs (e.g. a stale shadowing `tot`).
+  console.error(versionStamp());
+
   const mcpUrl = args.mcp || env.MCP_BASE_URL || env.TOT_MCP_URL || DEFAULT_MCP_URL;
 
   if (args.code) {
     console.error(`~ signing in to Token of Trust with your invite code (${mcpUrl})`);
     try {
-      await redeemAndCache(mcpUrl, args.code, env);
+      await redeemAndCache(mcpUrl, args.code, env, { log: (m) => console.error(m) });
       cacheActivityBridge(env, args.activityToken, args.activityUrl);
       cacheTraceId(env, args.traceId);
       cacheEmailHint(env, args.emailHint);
       console.log(`\n+ signed in. Session cached to ${defaultCredentialsPath(env)}.`);
-      console.log("  Next: `tot whoami` to confirm, or `tot checkout` / `tot submit` to build.");
+      console.log("  Next: `tot whoami` to confirm, or `tot clone` / `tot submit` to build.");
       return 0;
     } catch (e) {
       console.error(
@@ -281,7 +288,7 @@ export async function run(argv, _ctx) {
     await loginAndCache(mcpUrl, env, { log: (m) => console.error(m), device: args.device });
     cacheTraceId(env, args.traceId);
     console.log(`\n+ signed in. Session cached to ${defaultCredentialsPath(env)}.`);
-    console.log("  Next: `tot whoami` to confirm, or `tot checkout` / `tot submit` to build.");
+    console.log("  Next: `tot whoami` to confirm, or `tot clone` / `tot submit` to build.");
     return 0;
   } catch (e) {
     console.error(