@tokenoftrust/cli 1.4.0-rc.2 → 1.4.0-rc.20

package/src/commands/clone.mjs

@@ -0,0 +1,682 @@
+/**
+ * `tot clone` — clone the tenant store you're entitled to build on, with an
+ * authenticated remote already configured, ready for the local loop. Mirrors
+ * `git clone <repo> [dir]`: the tenant is the repo, the dir defaults to the
+ * tenant name. (Named `clone`, not `checkout`, so it means what `git clone`
+ * means — materialize a local working copy — and never collides with the
+ * unrelated `git checkout` = switch-refs verb.)
+ *
+ *   tot clone                    list the stores you can build on
+ *   tot clone <tenant>           clone into ./<tenant> (authenticated remote configured)
+ *   tot clone <tenant> <dir>     clone into <dir>
+ *   tot clone <tenant> --remote-only   just mint + print the remote, don't materialize
+ *
+ * This is the SAME MCP code path a developer gets when they switch to a tenant:
+ * sign-in → client_switch(tenant) → tenant_checkout, where the MCP derives your
+ * per-tenant Git user and mints a FRESH, single-active, repo-scoped push
+ * credential (a later clone for the same tenant rotates it). `tot` performs NO
+ * privileged forge work itself — the MCP owns that. ("checkout" survives only as
+ * the domain/lease term: the `tenant_checkout` MCP tool + the on-disk noun for a
+ * materialized store dir — never as a developer-facing verb.)
+ *
+ * Auth is the developer's own ToT identity (the cached `tot login` session,
+ * resolved via src/auth.mjs). When there's no session yet and we're on a TTY, we
+ * offer to sign in right here and retry — no "run tot login, then re-run".
+ *
+ * OPERATOR CROSS-TENANT PR CLONE (unit u6). `tot clone <tenant> --pr <N> [dir]`
+ * materializes a PARTICULAR pull request's head — including on a tenant the
+ * operator does NOT own/isn't a member of (e.g. inspecting someone else's PR
+ * #7). This does NOT go through `tenant_checkout` — that tool mints a PUSH
+ * credential for your own active tenant only, its `tag` param is deprecated +
+ * ignored (repo-name cutover, 8425), and it flatly refuses a foreign tenant
+ * (over-scoped). Instead it mints a SHORT-lived, READ-ONLY credential via
+ * `repo_read_credential({ tenant })` — the read counterpart to tenant_checkout,
+ * server-authorized by tot20's `decideContentRead` (deny-by-default: org-wide
+ * read authority, ownership of the target, or a per-tenant operator grant). The
+ * SAME call also covers your OWN tenant (its exact-tenant path needs no grant),
+ * so `--pr` always takes this path regardless of membership — there is no
+ * PR-ref parameter on tenant_checkout to make the own-tenant case worth
+ * special-casing. Once cloned, the PR's head is fetched by NUMBER via Gitea's
+ * standard `refs/pull/<N>/head` ref — no separate PR-metadata lookup is needed
+ * (and `repo_pr_read`/`repo_pr_list` are app-session-only tools today, per their
+ * `guardCommon`/`boundApp` gate in tot-mcp — unreachable from this CLI's single
+ * developer-OAuth auth plane for a genuine cross-tenant human operator, so this
+ * command does not depend on them). The CLI never reimplements or bypasses the
+ * server's authorization decision — only requests it and relays the result.
+ *
+ * Dependency-free (global fetch + `git` via child_process).
+ */
+import { execFile } from "node:child_process";
+import { promisify } from "node:util";
+import { createMcpClient } from "../mcp.mjs";
+import { establishSession, AuthUnavailableError } from "../auth.mjs";
+import { offerSignIn } from "./login.mjs";
+import { CliError, fail, formatError } from "../errors.mjs";
+import { writeNvmrc } from "../sample.mjs";
+import { emitObstacle } from "../obstacle.mjs";
+
+const execFileP = promisify(execFile);
+
+const DEFAULT_MCP_URL = "https://mcp.tokenoftrust.com";
+
+function parseArgs(argv) {
+  const a = {
+    tenant: null,
+    dir: null,
+    tag: "main",
+    pr: null,
+    remoteOnly: false,
+    mcp: null,
+    printRemote: false,
+    help: false,
+  };
+  for (let i = 0; i < argv.length; i++) {
+    const t = argv[i];
+    if (t === "--tag") a.tag = argv[++i];
+    else if (t === "--pr") a.pr = argv[++i];
+    else if (t === "--remote-only") a.remoteOnly = true;
+    else if (t === "--mcp") a.mcp = argv[++i];
+    else if (t === "--print-remote") a.printRemote = true;
+    else if (t === "--help" || t === "-h") a.help = true;
+    // Positional, git-clone style: `tot clone <tenant> [<dir>]`.
+    else if (!t.startsWith("--")) {
+      if (!a.tenant) a.tenant = t;
+      else if (!a.dir) a.dir = t;
+    }
+  }
+  return a;
+}
+
+/**
+ * Parse + validate the `--pr` value into a positive integer, or null when
+ * absent. Throws a CliError (never a raw NaN downstream) on garbage input.
+ * Pure. @param {unknown} raw @returns {number|null}
+ */
+export function parsePrNumber(raw) {
+  if (raw == null) return null;
+  const n = Number(raw);
+  if (!Number.isInteger(n) || n < 1) {
+    throw new CliError(`invalid --pr value "${raw}" — must be a positive PR number`, {
+      next: "tot clone <tenant> --pr <N> [dir]",
+    });
+  }
+  return n;
+}
+
+const USAGE = `tot clone — clone a tenant store you can build on (mirrors \`git clone\`)
+
+  tot clone                    list the stores you can build on
+  tot clone <tenant>           clone into ./<tenant> (authenticated remote configured)
+  tot clone <tenant> <dir>     clone into <dir>
+  tot clone <tenant> --pr <N> [dir]   OPERATOR: clone PR #<N>'s head, READ-ONLY
+                                (works even on a tenant you don't own/aren't a
+                                member of, when authorized; dir defaults to
+                                <tenant>-pr<N>)
+
+Options:
+  --tag <tag>       which repo (repo = "<tenant>-<tag>"). Default: main.
+  --pr <N>          clone PR #<N>'s head instead of the default branch — a
+                    READ-ONLY cross-tenant credential, not a push checkout.
+  --remote-only     don't clone; just mint + print the clone URL for <tenant>.
+  --mcp <url>       MCP base URL. Default: env MCP_BASE_URL / TOT_MCP_URL, else
+                    ${DEFAULT_MCP_URL}.
+  --print-remote    with --remote-only, also print the authenticated remote
+                    (contains a live token!).`;
+
+/** Redact known secrets from any string before it hits the terminal. */
+function makeRedactor(env) {
+  const secrets = [env.TOT_API_KEY, env.TOT_SECRET_KEY].filter(Boolean);
+  return (s) => {
+    let o = String(s);
+    for (const x of secrets) o = o.split(x).join("***");
+    return o;
+  };
+}
+
+/**
+ * @param {string[]} argv - args AFTER `checkout`
+ * @param {import("../context.mjs").detectContext extends (...a:any)=>infer R ? R : any} ctx
+ */
+export async function run(argv, ctx) {
+  const env = process.env;
+  const args = parseArgs(argv);
+  if (args.help) {
+    console.log(USAGE);
+    return 0;
+  }
+
+  // Infer the tenant from a standalone checkout when run without one.
+  if (!args.tenant && ctx.mode === "checkout" && ctx.tenant) {
+    args.tenant = ctx.tenant;
+  }
+
+  let pr;
+  try {
+    pr = parsePrNumber(args.pr);
+  } catch (e) {
+    console.error(formatError(e));
+    return e.exitCode ?? 1;
+  }
+
+  // git-clone semantics: unless you explicitly asked for --remote-only, cloning
+  // is the default, and the target dir defaults to the tenant name (like
+  // `git clone <url>` deriving the dir from the repo basename) — or, with
+  // --pr, to "<tenant>-pr<N>" so a PR clone never collides with a plain one.
+  const cloneDir = args.remoteOnly ? null : args.dir || (pr ? `${args.tenant}-pr${pr}` : args.tenant);
+
+  const baseUrl = args.mcp || env.MCP_BASE_URL || env.TOT_MCP_URL || DEFAULT_MCP_URL;
+  const redact = makeRedactor(env);
+  const client = createMcpClient(baseUrl);
+
+  try {
+    // Attach auth in the right order relative to the handshake (developer bearer
+    // BEFORE initialize) — see establishSession. When there's no session yet and
+    // we're on a TTY, offer to sign in inline and retry once, so a not-signed-in
+    // developer isn't dead-ended at "run tot login, then re-run".
+    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; // declined/non-TTY → the crisp error below
+        await establishSession(client, { env }); // retry once, in-flow
+      } else {
+        throw e;
+      }
+    }
+    console.error(`~ signed in → ${client.mcpUrl}`);
+
+    // No tenant → list the stores this identity can build on and stop.
+    if (!args.tenant) {
+      if (pr) {
+        console.error(fail("`tot clone --pr` needs a tenant", "tot clone <tenant> --pr <N> [dir]"));
+        return 2;
+      }
+      const list = await client.callTool("client_list", {});
+      printClientList(list);
+      return 0;
+    }
+
+    // --pr ALWAYS takes the cross-tenant read-credential path, even for your own
+    // tenant — tenant_checkout has no PR-ref parameter to select, so there is no
+    // membership-based fork here (see the file header comment).
+    if (pr) {
+      console.error(
+        `~ repo_read_credential (tenant=${args.tenant}) — MCP mints a read-only credential`,
+      );
+      const res = await cloneCrossTenantPr(client, {
+        tenant: args.tenant,
+        pr,
+        cloneDir,
+        redact,
+      });
+      console.log(`\n+ ready (read-only). repo: ${res.publicUrl}`);
+
+      if (res.cloned) {
+        console.log(`+ cloned PR #${pr}. HEAD: ${res.head}`);
+        console.log(`\nYour local read-only clone of PR #${pr} is at ${res.dir}.`);
+        console.log(`  (this credential can only pull, never push — for your own tenant's`);
+        console.log(`   push checkout, run \`tot clone ${args.tenant}\` without --pr)`);
+        return 0;
+      }
+
+      console.log(`\nPublic clone URL (no credential): ${res.publicUrl}`);
+      console.log(`Drop --remote-only to clone PR #${pr} with the read-only remote configured.`);
+      if (args.printRemote) {
+        console.log(
+          `\nREAD-ONLY remote (contains a live token — handle carefully):\n${res.gitRemote}`,
+        );
+      }
+      return 0;
+    }
+
+    console.error(`~ client_switch → ${args.tenant}`);
+    console.error(
+      `~ tenant_checkout (tag=${args.tag}) — MCP mints a fresh repo-scoped credential`,
+    );
+    const res = await checkoutTenant(client, {
+      tenant: args.tenant,
+      tag: args.tag,
+      cloneDir,
+      redact,
+    });
+    console.log(`\n+ ready. repo: ${res.cloneUrl || res.publicUrl}`);
+
+    if (res.cloned) {
+      console.log(`+ cloned. HEAD: ${res.head}`);
+      console.log(`\nYour local working clone is at ${res.dir} with an authenticated remote.`);
+      console.log(`  cd ${res.dir} && tot dev            # run it locally with save→reload`);
+      console.log(`  (the minted token lives in .git/config; a later clone rotates it)`);
+      return 0;
+    }
+
+    console.log(`\nPublic clone URL (no credential): ${res.publicUrl}`);
+    console.log(`Drop --remote-only to clone with the authenticated remote configured.`);
+    if (args.printRemote) {
+      console.log(
+        `\nAUTHENTICATED remote (contains a live token — handle carefully):\n${res.gitRemote}`,
+      );
+    }
+    return 0;
+  } catch (e) {
+    if (e instanceof AuthUnavailableError) {
+      console.error(formatError(e));
+      return 1;
+    }
+    if (e instanceof CliError) {
+      console.error(formatError(e));
+      return e.exitCode ?? 1;
+    }
+    console.error(fail(`checkout failed: ${redact(String(e?.message || e))}`));
+    return 1;
+  }
+}
+
+/**
+ * The privileged checkout core, composable in-process (used by `tot clone`
+ * and by `tot start`): client_switch → tenant_checkout → optionally clone. The
+ * MCP mints a fresh, repo-scoped push credential each time. Assumes `client` is
+ * already initialized + has a validated session.
+ *
+ * @param {ReturnType<import("../mcp.mjs").createMcpClient>} client
+ * @param {{ tenant: string, tag?: string, cloneDir?: string|null, redact?: (s:string)=>string }} opts
+ * @returns {Promise<{ gitRemote: string, cloneUrl: string|null, publicUrl: string,
+ *   cloned: boolean, dir: string|null, head: string|null }>}
+ */
+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
+  // the MCP's human message + a concrete next step, NEVER a raw JSON.stringify
+  // dump (James's 2026-07-19 first-experience failure).
+  const err = checkoutError(checkout);
+  if (err) {
+    throw new CliError(redact(err.message), { next: err.next });
+  }
+  const gitRemote = checkout.gitRemote;
+  const cloneUrl = checkout.cloneUrl ?? null;
+  const u = new URL(gitRemote);
+  const publicUrl = `${u.protocol}//${u.host}${u.pathname}`;
+
+  if (!cloneDir) {
+    return { gitRemote, cloneUrl, publicUrl, cloned: false, dir: null, head: null };
+  }
+  const { dir, head } = await cloneRepo(gitRemote, cloneDir, redact);
+  return { gitRemote, cloneUrl, publicUrl, cloned: true, dir, head };
+}
+
+/**
+ * git clone the authenticated remote into `dir`. Throws CliError on failure.
+ * Runs git as a NON-BLOCKING child process (promisified execFile) so the clone
+ * doesn't stall the Node event loop — `tot start` runs this inside a
+ * `Promise.all([...])` alongside the renderer prefetch, and a synchronous clone
+ * would serialize what's meant to overlap.
+ */
+async function cloneRepo(gitRemote, dir, redact) {
+  const git = async (cargs) => (await execFileP("git", cargs)).stdout.toString();
+  console.log(`+ git clone → ${dir}`);
+  try {
+    await git(["clone", gitRemote, dir]);
+  } catch (e) {
+    // Beacon the cockpit before we surface the error — covers this path for both
+    // `tot clone` and `tot start` (which clones through here). Awaited so the
+    // packet lands before the process prints + exits; swallowed either way.
+    await emitObstacle("clone-failed");
+    throw new CliError(`clone failed: ${redact(String(e.stderr || e.message || e))}`, {
+      next: `check the target dir is empty and you can reach the remote, then re-run`,
+    });
+  }
+  const head = (await git(["-C", dir, "log", "-1", "--oneline"])).trim();
+  writeNvmrc(dir); // version-manager hooks land on a supported Node on cd
+  return { dir, head };
+}
+
+/**
+ * The cross-tenant PR-clone core (unit u6), composable in-process exactly like
+ * `checkoutTenant`: mint a READ-ONLY credential via `repo_read_credential`, then
+ * (optionally) clone it and materialize PR #<pr>'s head. This is the path `--pr`
+ * ALWAYS takes — own tenant or foreign — because tenant_checkout has no PR-ref
+ * parameter (see the file header). Assumes `client` is already initialized +
+ * has a validated session.
+ *
+ * @param {ReturnType<import("../mcp.mjs").createMcpClient>} client
+ * @param {{ tenant: string, pr: number, cloneDir?: string|null, redact?: (s:string)=>string }} opts
+ * @returns {Promise<{ gitRemote: string, publicUrl: string, cloned: boolean,
+ *   dir: string|null, head: string|null }>}
+ */
+export async function cloneCrossTenantPr(
+  client,
+  { tenant, pr, cloneDir = null, redact = (s) => s },
+) {
+  const minted = await client.callTool("repo_read_credential", { tenant });
+
+  // A non-mint result (unauthenticated / forbidden / invalid_input / error) must
+  // surface the MCP's OWN denial reason + a concrete next step — never a raw
+  // JSON dump, and never a CLI-side re-derivation of the authorization call
+  // (the server's `decideContentRead` is the sole authority here).
+  const err = readCredentialError(minted);
+  if (err) {
+    throw new CliError(redact(err.message), { next: err.next });
+  }
+
+  const repos = Array.isArray(minted.repos) ? minted.repos : [];
+  const target = repos.find((r) => r.repo === tenant || r.owner === tenant) ?? repos[0];
+  if (!target || !target.gitRemote) {
+    throw new CliError(
+      `repo_read_credential minted no usable credential for tenant "${tenant}"`,
+      { next: "confirm the tenant name, then re-run" },
+    );
+  }
+  const gitRemote = target.gitRemote;
+  const u = new URL(gitRemote);
+  const publicUrl = `${u.protocol}//${u.host}${u.pathname}`;
+
+  if (!cloneDir) {
+    return { gitRemote, publicUrl, cloned: false, dir: null, head: null };
+  }
+  const { dir, head } = await cloneRepoAtPrRef(gitRemote, cloneDir, pr, redact);
+  return { gitRemote, publicUrl, cloned: true, dir, head };
+}
+
+/**
+ * git clone the authenticated (READ-ONLY) remote into `dir`, then materialize
+ * PR #<pr>'s head by NUMBER — Gitea exposes every pull request at the standard
+ * `refs/pull/<N>/head` ref, so this needs no separate PR-metadata lookup (see
+ * the file header on why `repo_pr_read` isn't used here). Runs git as a
+ * NON-BLOCKING child process (promisified execFile), same as `cloneRepo`.
+ * `deps.git` is injectable for tests (an async `(cargs) => stdout` runner);
+ * defaults to the real `git` binary. Throws CliError on failure.
+ * @param {string} gitRemote
+ * @param {string} dir
+ * @param {number} pr
+ * @param {(s: string) => string} redact
+ * @param {{ git?: (cargs: string[]) => Promise<string> }} [deps]
+ */
+export async function cloneRepoAtPrRef(gitRemote, dir, pr, redact, deps = {}) {
+  const git = deps.git || (async (cargs) => (await execFileP("git", cargs)).stdout.toString());
+  console.log(`+ git clone → ${dir}`);
+  try {
+    await git(["clone", gitRemote, dir]);
+  } catch (e) {
+    await emitObstacle("clone-failed");
+    throw new CliError(`clone failed: ${redact(String(e.stderr || e.message || e))}`, {
+      next: `check the target dir is empty and you can reach the remote, then re-run`,
+    });
+  }
+  const prRef = `refs/pull/${pr}/head`;
+  console.log(`+ git fetch ${prRef}`);
+  try {
+    await git(["-C", dir, "fetch", "origin", prRef]);
+    await git(["-C", dir, "checkout", "-B", `pr-${pr}`, "FETCH_HEAD"]);
+  } catch (e) {
+    throw new CliError(
+      `couldn't fetch PR #${pr}: ${redact(String(e.stderr || e.message || e))}`,
+      { next: `confirm PR #${pr} exists on this tenant — \`tot pr list --tenant <t>\`, then re-run` },
+    );
+  }
+  const head = (await git(["-C", dir, "log", "-1", "--oneline"])).trim();
+  writeNvmrc(dir);
+  return { dir, head };
+}
+
+/**
+ * Classify a `repo_read_credential` tool result: null when it's a genuine,
+ * usable mint (carries at least one repo with a gitRemote), otherwise a human
+ * { message, next } pair — mirrors `checkoutError`'s contract exactly (never a
+ * raw JSON dump; the MCP's own denial reason + a concrete next step). Pure +
+ * exported so it's unit-tested without any I/O.
+ * @param {unknown} minted
+ * @returns {{ message: string, next: string }|null}
+ */
+export function readCredentialError(minted) {
+  const c = minted && typeof minted === "object" && !Array.isArray(minted) ? minted : null;
+  if (c && Array.isArray(c.repos) && c.repos.some((r) => r && r.gitRemote)) return null;
+  const msg =
+    (c && (c.message || (typeof c.error === "string" ? c.error : c.error?.message))) ||
+    (c && typeof c.raw === "string" && c.raw.trim() ? c.raw.trim() : null) ||
+    null;
+  if (typeof msg === "string" && /not authorized/i.test(msg)) {
+    return {
+      message: msg,
+      next:
+        "a cross-tenant read needs org-wide read authority, ownership of the target, or a " +
+        "per-tenant operator grant — ask your Token of Trust contact for one, or confirm the tenant name",
+    };
+  }
+  if (
+    typeof msg === "string" &&
+    /version-control app is bound|registered version-control app/i.test(msg)
+  ) {
+    return {
+      message: "your account isn't onboarded to read this tenant's content yet",
+      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 read credential couldn't be minted",
+    next: "confirm the tenant name and that you're authorized to read it, then re-run",
+  };
+}
+
+/**
+ * Classify a `tenant_checkout` tool result: null when it's a genuine, usable
+ * checkout (carries a gitRemote), otherwise a human { message, next } pair so
+ * callers surface the MCP's own words + a concrete next step instead of dumping
+ * raw JSON (James's 2026-07-19 first-experience failure: a not-provisioned store
+ * printed JSON.stringify(checkout)). callTool unwraps the tool result to its
+ * structuredContent / parsed text, so a failure surfaces as an error-ish status
+ * ('forbidden' | 'invalid_input' | 'checkout_failed' | 'error'), a `message`, or
+ * simply a missing gitRemote. When the repo isn't provisioned yet we speak to the
+ * INVITED DEVELOPER ("your store isn't set up yet"), not the operator — dropping
+ * the `repo_provision` jargon the MCP aims at whoever provisions. Any other
+ * failure surfaces the MCP's own message. Pure + exported so it's unit-tested
+ * without any I/O.
+ * @param {unknown} checkout
+ * @returns {{ message: string, next: string }|null}
+ */
+export function checkoutError(checkout) {
+  const c = checkout && typeof checkout === "object" && !Array.isArray(checkout) ? checkout : null;
+  if (c && c.gitRemote) return null; // a usable checkout — never an error
+  const msg =
+    (c && (c.message || (typeof c.error === "string" ? c.error : c.error?.message))) ||
+    (c && typeof c.raw === "string" && c.raw.trim() ? c.raw.trim() : null) ||
+    null;
+  // The store's repo isn't provisioned yet — it isn't set up for this developer.
+  if (typeof msg === "string" && /not provisioned/i.test(msg)) {
+    return {
+      message: "your store isn't set up on Token of Trust yet",
+      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)",
+  };
+}
+
+/**
+ * Normalize the (shape-varying) `client_list` response into a plain, sorted
+ * list of the stores this identity can build on. Shared by `tot clone`'s
+ * listing and `tot start`'s auto-pick so both read the same fields.
+ * @param {unknown} list
+ * @returns {Array<{ id: string, name: string, raw: any }>}
+ */
+export function normalizeStores(list) {
+  const rows = Array.isArray(list) ? list : list?.clients || list?.tenants || [];
+  if (!Array.isArray(rows)) return [];
+  return rows
+    .map((r) => ({
+      id: r?.tenant || r?.id || r?.clientId || r?.appDomain || null,
+      name: r?.displayName || r?.name || "",
+      raw: r,
+    }))
+    .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;
+}
+
+/**
+ * Extract card c1's broker-identity remediation signal from a `client_list`
+ * result. When the identity resolved ZERO stores, the server MAY carry:
+ *   - `brokerStatus`: 'unlinked' | 'unconfigured' | 'broker_error' — present only
+ *      when the empty scope is a BROKER-IDENTITY problem (not an entitlement one);
+ *      ABSENT for the genuine linked-but-zero-grants case.
+ *   - `nextAction`: a status-specific human remediation string the server owns
+ *      (single source of truth; e.g. an unlinked identity is told to finish
+ *      linking, an operator sees a diagnostic, zero-grants sees NO_TENANTS_MESSAGE).
+ * Returns { brokerStatus, nextAction } with nulls when absent. Pure + exported so
+ * it's unit-tested without any I/O.
+ * @param {unknown} list
+ * @returns {{ brokerStatus: string|null, nextAction: string|null }}
+ */
+export function brokerRemediation(list) {
+  const c = list && typeof list === "object" && !Array.isArray(list) ? list : null;
+  const brokerStatus = c && typeof c.brokerStatus === "string" ? c.brokerStatus : null;
+  const nextAction =
+    c && typeof c.nextAction === "string" && c.nextAction.trim() ? c.nextAction.trim() : null;
+  return { brokerStatus, nextAction };
+}
+
+/**
+ * Status-aware human guidance for an authenticated identity that resolved ZERO
+ * stores (card c2 — the fix for the misleading "may still be propagating / ask for
+ * a store invite" copy that dead-ended an UNLINKED identity). Driven by card c1's
+ * `brokerStatus`/`nextAction`:
+ *   - `unlinked` → the identity isn't linked to the ToT broker yet, so no scope can
+ *      resolve. This is NOT an entitlement problem — point at `tot link` (the
+ *      terminal action), NOT "ask for a store invite".
+ *   - `unconfigured` | `broker_error` → an operator/diagnostic condition; surface
+ *      the server's own `nextAction`, never "ask for an invite".
+ *   - no brokerStatus → the genuine linked-but-zero-grants case; keep the existing
+ *      "invite may still be propagating / ask for one" wording (NO_TENANTS_MESSAGE),
+ *      preferring the server's `nextAction` when present.
+ *
+ * Prefers the server's `nextAction` as the concrete `next` step (single source of
+ * truth) and falls back to sensible local copy when it's absent (older server).
+ * `linkHint` names the terminal action an unlinked identity is pointed at — the
+ * built-in `tot link`; a caller that didn't build `tot link` passes an MCP-client
+ * phrasing instead. Pure + exported so it's unit-tested without any I/O.
+ * @param {unknown} list
+ * @param {{ linkHint?: string }} [opts]
+ * @returns {{ brokerStatus: string|null, headline: string, next: string }}
+ */
+export function noStoresGuidance(list, { linkHint = "tot link" } = {}) {
+  const { brokerStatus, nextAction } = brokerRemediation(list);
+
+  if (brokerStatus === "unlinked") {
+    // The actionable terminal step beats the server's identity_link_begin/poll
+    // MCP-tool wording for a CLI user, so lead with `tot link` (c2 optional-arm
+    // directive). Fall back to the server string only if there's no link action.
+    return {
+      brokerStatus,
+      headline: "your Token of Trust identity isn't linked yet, so no stores could be resolved",
+      next: linkHint
+        ? `run \`${linkHint}\` to finish linking your identity, then re-run`
+        : nextAction || "finish linking your identity (identity_link_begin), then re-run",
+    };
+  }
+  if (brokerStatus === "unconfigured" || brokerStatus === "broker_error") {
+    // Operator/diagnostic conditions — surface the server's own words; do NOT tell
+    // the developer to "ask for an invite" (it isn't an entitlement problem).
+    return {
+      brokerStatus,
+      headline: "no stores could be resolved — the Token of Trust identity broker had a problem",
+      next: nextAction || "run `tot whoami` for details, or contact your Token of Trust operator",
+    };
+  }
+  // No brokerStatus → the genuine linked-but-zero-grants case.
+  return {
+    brokerStatus: null,
+    headline: "you have no stores to build on yet",
+    next:
+      nextAction ||
+      "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`)",
+  };
+}
+
+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) {
+    // Status-aware, human-readable guidance — NEVER a raw JSON dump (the old
+    // behaviour, James's 2026-07-19 failure mode).
+    const g = noStoresGuidance(list);
+    const line = g.headline.charAt(0).toUpperCase() + g.headline.slice(1);
+    console.log(`\n${line}.`);
+    console.log(`Next: ${g.next}`);
+    return;
+  }
+  console.log("\nStores you can build on:\n");
+  for (const s of stores) {
+    console.log(`  ${s.id}${s.name ? `  — ${s.name}` : ""}`);
+  }
+  console.log(`\nNext:  tot clone <tenant>`);
+}