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

package/src/commands/hotfix.mjs

@@ -0,0 +1,428 @@
+/**
+ * `tot hotfix` (unit b22) — the OWNER-ONLY EXCEPTION LANE: release an urgent
+ * production fix from `main` to live WHILE `preview` still contains other unshipped
+ * work, EXCLUDING that unshipped preview head, then automatically forward-integrate
+ * `main` into `preview` and re-validate.
+ *
+ *   tot dev / preview   build + review the fix (a `main`-based candidate)
+ *   tot hotfix --pr N   release THAT reviewed fix from main to live, bypassing preview  ← you are here
+ *
+ * This is a DELIBERATELY DISTINCT verb — NEVER a `--base main` flag on `tot ship`.
+ * `tot ship` publishes the tenant's current green PREVIEW aggregate; `tot hotfix`
+ * does the opposite in the one case that warrants it: it ships a `main`-based fix
+ * that does NOT include the in-flight preview work, and only then carries `main`
+ * forward into `preview`. Because rewinding what goes live around the normal queue
+ * is a serious exception, it ALWAYS shows the exact plan — including the unshipped
+ * preview work it BYPASSES — and requires an explicit confirm.
+ *
+ * THE FLOW (mirrors `tot ship`'s plan → confirm → act → honest-terminal-state):
+ *   1. GET the read-only PLAN from `/api/changes/hotfix` — the candidate, the
+ *      current live rollback target, the unshipped preview work bypassed, and the
+ *      paywall verdict. Zero side effects.
+ *   2. Print the EXACT plan and require ONE explicit confirm (default NO). `--yes`
+ *      confirms non-interactively; a non-TTY without `--yes` REFUSES.
+ *   3. On confirm, POST `/api/changes/hotfix` with `confirmGoLive: true`.
+ *   4. Report the orchestrator's HONEST terminal state verbatim — `shipped`
+ *      (live VERIFIED on the fix; the ONLY "shipped" state), `refused`,
+ *      `merge_failed` / `build_failed` / `promote_failed` / `record_failed`
+ *      (recoverable, never a false live) — PLUS the automatic forward-integration
+ *      outcome (green, or red + a fix-forward nudge; a red forward-integration
+ *      never un-ships the live fix).
+ *
+ * TRANSPORT: the operator-secret Bearer + `X-Tot-Owner`, the SAME transport as
+ * `tot ship` / `tot revert`. Dependency-free (global fetch + the shared plan module).
+ */
+import { fail } from "../errors.mjs";
+import { planForAction, printPlanAndConfirm } from "../plan.mjs";
+import { startProgress } from "../progress.mjs";
+import { openBrowser } from "../open.mjs";
+// Reuse `tot ship`'s operator-secret precedence + live-url derivation verbatim so
+// ship + hotfix speak ONE operator-auth contract.
+import { resolveOperatorSecret, liveUrlFor } from "./ship.mjs";
+
+const DEFAULT_STOREFRONT_URL = "https://storefront.tokenoftrust.store";
+
+const USAGE = `tot hotfix — OWNER-ONLY: release an urgent fix from main to live, bypassing preview
+
+  tot hotfix --pr <N> --tenant <t>
+  tot hotfix --change <changeId> --tenant <t>
+
+  The EXPLICIT EXCEPTION lane for an urgent production fix while \`preview\` holds
+  other unshipped work. It releases the reviewed, main-based fix to live WITHOUT the
+  unshipped preview head, then automatically forward-integrates main → preview and
+  re-validates the aggregate. It is NOT \`tot ship\` with a flag — \`tot ship\`
+  publishes the current green preview aggregate; \`tot hotfix\` deliberately excludes it.
+
+  It ALWAYS prints the exact plan — including the unshipped preview work it BYPASSES —
+  and asks for an explicit confirm. A non-TTY without --yes is refused.
+
+Options:
+  --pr <N>               The reviewed hotfix candidate's PR number.
+  --change <changeId>    The reviewed hotfix candidate's change id (alternative to --pr).
+  --tenant <appDomain>   Target tenant (e.g. tokenoftrust.com). Defaults to the
+                         current checkout's tenant when run inside one.
+  --message <msg>        Optional merge-commit message.
+  --url <origin>         storefront origin (default: env TOT_STOREFRONT_URL)
+  --secret <s>           operator secret (prefer the env vars below)
+  --yes, -y              Skip the interactive confirm (still an explicit affirmative).
+  --no-open              Don't open the live URL in your browser.
+  --help, -h             Show this help.
+
+  For the ordinary release of the whole green preview aggregate, use \`tot ship\`.
+  To undo something already LIVE, use \`tot rollback\`.
+
+  Operator secret (from env, first found): PREVIEW_RECONCILE_SECRET,
+  GRANTS_ADMIN_SECRET, TOT_OPERATOR_SECRET (or pass --secret).`;
+
+/** Parse `tot hotfix` argv. Pure — unit-testable. */
+export function parseHotfixArgs(argv) {
+  const a = {
+    pr: null,
+    change: null,
+    tenant: null,
+    message: null,
+    url: null,
+    secret: null,
+    yes: false,
+    noOpen: false,
+    help: false,
+  };
+  for (let i = 0; i < argv.length; i++) {
+    const t = argv[i];
+    if (t === "--pr") a.pr = argv[++i];
+    else if (t === "--change" || t === "--changeId") a.change = argv[++i];
+    else if (t === "--tenant") a.tenant = argv[++i];
+    else if (t === "--message" || t === "-m") a.message = argv[++i];
+    else if (t === "--url") a.url = argv[++i];
+    else if (t === "--secret") a.secret = argv[++i];
+    else if (t === "--yes" || t === "-y") a.yes = true;
+    else if (t === "--no-open") a.noOpen = true;
+    else if (t === "--help" || t === "-h") a.help = true;
+  }
+  return a;
+}
+
+/** Normalise a `?pr` value to a positive integer, or null. Pure. */
+export function parsePrNumber(raw) {
+  const t = (raw == null ? "" : `${raw}`).trim().replace(/^#/, "");
+  return /^\d+$/.test(t) ? Number(t) : null;
+}
+
+/**
+ * Normalise a `GET /api/changes/hotfix` body — the {@link HotfixReleasePlan} (an
+ * exception ready to confirm) or a refusal. Read defensively (crossed the wire as
+ * JSON). Pure — unit-tested.
+ * @param {any} data
+ */
+export function normalizeHotfixPlan(data) {
+  const o = data && typeof data === "object" ? data : {};
+  if (o.ok === true) {
+    return {
+      ok: true,
+      tenantId: typeof o.tenantId === "string" ? o.tenantId : null,
+      changeId: typeof o.changeId === "string" ? o.changeId : null,
+      prNumber: typeof o.prNumber === "number" ? o.prNumber : null,
+      bypassedPreviewSha: typeof o.bypassedPreviewSha === "string" ? o.bypassedPreviewSha : null,
+      bypassedPrs: Array.isArray(o.bypassedPrs) ? o.bypassedPrs : [],
+      rollbackTarget: o.rollbackTarget && typeof o.rollbackTarget === "object" ? o.rollbackTarget : null,
+      paywall:
+        o.paywall && typeof o.paywall === "object"
+          ? { allowed: o.paywall.allowed === true, message: typeof o.paywall.message === "string" ? o.paywall.message : null }
+          : { allowed: true, message: null },
+    };
+  }
+  return {
+    ok: false,
+    reason: typeof o.reason === "string" ? o.reason : "unknown",
+    message: typeof o.message === "string" ? o.message : "the hotfix plan was refused for an unknown reason",
+  };
+}
+
+/**
+ * Normalise a `POST /api/changes/hotfix` body — the {@link HotfixReleaseResult}.
+ * `state` is the ONLY honest terminal authority: render "shipped live" for
+ * `"shipped"` and nothing else. Pure — unit-tested.
+ * @param {any} data
+ */
+export function normalizeHotfixResult(data) {
+  const o = data && typeof data === "object" ? data : {};
+  const fwd = o.forwardIntegration && typeof o.forwardIntegration === "object" ? o.forwardIntegration : null;
+  return {
+    ok: o.ok === true,
+    state: typeof o.state === "string" ? o.state : "unknown",
+    reason: typeof o.reason === "string" ? o.reason : null,
+    message: typeof o.message === "string" ? o.message : "",
+    mainSha: typeof o.mainSha === "string" ? o.mainSha : null,
+    artifactDigest: typeof o.artifactDigest === "string" ? o.artifactDigest : null,
+    receiptId: typeof o.receiptId === "string" ? o.receiptId : null,
+    rollbackTarget: o.rollbackTarget && typeof o.rollbackTarget === "object" ? o.rollbackTarget : null,
+    forwardIntegration: fwd
+      ? {
+          ok: fwd.ok === true,
+          queueState: typeof fwd.queueState === "string" ? fwd.queueState : null,
+          runState: typeof fwd.runState === "string" ? fwd.runState : null,
+          reason: typeof fwd.reason === "string" ? fwd.reason : null,
+          aggregateSha: typeof fwd.aggregateSha === "string" ? fwd.aggregateSha : null,
+          statusMessage: typeof fwd.statusMessage === "string" ? fwd.statusMessage : null,
+        }
+      : null,
+  };
+}
+
+/** A clear next step per hotfix plan/release refusal reason. Pure. */
+export function hotfixNextStep(reason) {
+  switch (reason) {
+    case "no_candidate":
+      return "pass --pr <N> (or --change <id>) naming the reviewed hotfix candidate";
+    case "paywall":
+      return "upgrade the storefront subscription to enable go-live";
+    case "golive_unconfirmed":
+      return "re-run `tot hotfix` and confirm the plan";
+    case "digest_mismatch":
+      return "main moved under review — re-preview the hotfix against current main, then re-run `tot hotfix`";
+    default:
+      return "re-run `tot hotfix`";
+  }
+}
+
+/** Read a fetch Response body as JSON, tolerating a non-JSON/empty body. */
+async function readJsonSafe(res) {
+  try {
+    return await res.json();
+  } catch {
+    return {};
+  }
+}
+
+/**
+ * The hotfix flow: GET the plan, print it + confirm, POST to release, report the
+ * honest terminal state + the forward-integration outcome. `fetch`/`confirmPlan`/
+ * `openUrl`/`progress` are injected so it's unit-tested with no live network/TTY.
+ *
+ * @param {{ tenant:string, prNumber:number|null, changeId:string|null,
+ *   message:string|null, secret:string, storefrontUrl?:string|null,
+ *   yes?:boolean, noOpen?:boolean }} params
+ * @param {{ fetch?:typeof fetch, confirmPlan?:typeof printPlanAndConfirm,
+ *   openUrl?:(u:string)=>boolean, progress?:boolean }} [deps]
+ * @returns {Promise<number>} process exit code
+ */
+export async function runHotfix(
+  { tenant, prNumber, changeId, message = null, secret, storefrontUrl = null, yes = false, noOpen = false },
+  deps = {},
+) {
+  const fetchImpl = deps.fetch || globalThis.fetch;
+  const confirmPlan = deps.confirmPlan || printPlanAndConfirm;
+  const base = (storefrontUrl || DEFAULT_STOREFRONT_URL).trim().replace(/\/+$/, "");
+  const label = prNumber != null ? `PR #${prNumber}` : changeId ? changeId : "the hotfix candidate";
+
+  if (!secret) {
+    console.error(
+      fail(
+        "a hotfix is an OWNER action — it needs an operator secret",
+        "set PREVIEW_RECONCILE_SECRET (or GRANTS_ADMIN_SECRET / TOT_OPERATOR_SECRET), or pass --secret",
+      ),
+    );
+    return 2;
+  }
+
+  const authHeaders = {
+    authorization: `Bearer ${secret}`,
+    "x-tot-owner": tenant,
+    "x-tot-capability": "ship-on-behalf",
+  };
+
+  // 1. GET the read-only plan (candidate + bypassed preview work + rollback + paywall).
+  const query = prNumber != null ? `pr=${encodeURIComponent(prNumber)}` : `changeId=${encodeURIComponent(changeId || "")}`;
+  let planRes;
+  try {
+    planRes = await fetchImpl(`${base}/api/changes/hotfix?${query}`, { method: "GET", headers: authHeaders });
+  } catch (e) {
+    console.error(
+      fail(`couldn't reach the hotfix plan at ${base}: ${String(e?.message || e)}`, "check --url / your network, then re-run"),
+    );
+    return 1;
+  }
+  const planData = await readJsonSafe(planRes);
+  if (!planRes.ok && planData?.ok !== false) {
+    const msg = planData?.error || `HTTP ${planRes.status}`;
+    console.error(
+      fail(
+        `the hotfix plan was refused: ${msg}`,
+        planRes.status === 401 || planRes.status === 403
+          ? "check the operator secret and that it's authorised for this tenant"
+          : "check --tenant / --url / --pr, then re-run",
+      ),
+    );
+    return 1;
+  }
+  const plan = normalizeHotfixPlan(planData);
+  if (!plan.ok) {
+    console.error(fail(plan.message, hotfixNextStep(plan.reason)));
+    return 1;
+  }
+
+  // 2. Print the EXACT plan — including the unshipped preview work it BYPASSES —
+  //    then require ONE explicit confirm (default NO).
+  const liveUrl = liveUrlFor(tenant);
+  const planLines = planForAction({
+    action: "hotfix",
+    tenant,
+    pr: plan.prNumber,
+    changeId: plan.changeId,
+    bypassedPrs: plan.bypassedPrs,
+    bypassedPreviewSha: plan.bypassedPreviewSha,
+    rollbackTarget: plan.rollbackTarget,
+    paywall: plan.paywall,
+    targets: { live: liveUrl },
+  });
+  const { confirmed, reason } = await confirmPlan(planLines, {
+    yes,
+    question: `Release ${label} from main to live for ${tenant}, BYPASSING the unshipped preview work?`,
+  });
+  if (!confirmed) {
+    if (reason === "non-tty") {
+      console.error(
+        fail(
+          "`tot hotfix` needs an interactive terminal to confirm this live exception",
+          "run it from a terminal, or pass --yes to confirm non-interactively",
+        ),
+      );
+      return 2;
+    }
+    console.log("  Hotfix cancelled — nothing changed.");
+    return 0;
+  }
+
+  // 3. RELEASE — the human go-live gate (confirmGoLive).
+  const progress = deps.progress === false ? null : startProgress("releasing hotfix…");
+  let res;
+  try {
+    res = await fetchImpl(`${base}/api/changes/hotfix`, {
+      method: "POST",
+      headers: { "content-type": "application/json", ...authHeaders },
+      body: JSON.stringify({
+        confirmGoLive: true,
+        ...(prNumber != null ? { prNumber } : {}),
+        ...(plan.changeId ? { changeId: plan.changeId } : {}),
+        ...(message ? { message } : {}),
+      }),
+    });
+  } catch (e) {
+    progress?.stop();
+    console.error(
+      fail(`couldn't reach the hotfix endpoint at ${base}: ${String(e?.message || e)}`, "check --url / your network, then re-run"),
+    );
+    return 1;
+  }
+  const resultData = await readJsonSafe(res);
+  progress?.stop();
+
+  return reportHotfixResult(normalizeHotfixResult(resultData), { tenant, liveUrl, noOpen, openUrl: deps.openUrl });
+}
+
+/**
+ * Report the orchestrator's HONEST terminal state + the automatic forward-integration
+ * outcome. `shipped` is the ONLY state rendered as "shipped live"; a red
+ * forward-integration is surfaced as a fix-forward nudge but never un-ships live.
+ * @returns {number} process exit code
+ */
+export function reportHotfixResult(result, { tenant, liveUrl, noOpen, openUrl }) {
+  if (result.state === "shipped") {
+    console.log(`\n  ✓ shipped hotfix live for ${tenant} — the unshipped preview work was NOT included.`);
+    if (result.mainSha) console.log(`  main:    ${result.mainSha}`);
+    if (result.receiptId) console.log(`  receipt: ${result.receiptId}`);
+    if (liveUrl) {
+      console.log(`  Live: ${liveUrl}`);
+      if (!noOpen && openUrl && openUrl(liveUrl)) console.log("  (opened in your browser)");
+    }
+    // The automatic forward-integration: honest whether green or red.
+    const fwd = result.forwardIntegration;
+    if (fwd && fwd.ok) {
+      console.log(`  forward-integrated main → preview (green${fwd.aggregateSha ? `, ${fwd.aggregateSha}` : ""}).`);
+    } else if (fwd) {
+      console.log(
+        `  ⚠ forward-integration main → preview is ${fwd.queueState ?? "?"}/${fwd.runState ?? "—"}` +
+          `${fwd.reason ? `  (${fwd.reason})` : ""} — the live hotfix is fine, but preview needs a fix-forward.`,
+      );
+      if (fwd.statusMessage) console.log(`    why: ${fwd.statusMessage}`);
+      console.log("    → next: resolve preview against main, then `tot preview`.");
+    }
+    return 0;
+  }
+  if (result.state === "refused") {
+    console.error(fail(result.message || `hotfix refused (${result.reason})`, hotfixNextStep(result.reason)));
+    return 1;
+  }
+  if (
+    result.state === "merge_failed" ||
+    result.state === "build_failed" ||
+    result.state === "promote_failed" ||
+    result.state === "record_failed"
+  ) {
+    console.error(
+      fail(
+        result.message || `hotfix ${result.state.replace("_", " ")}`,
+        "re-run `tot hotfix` — the release is idempotent and safe to retry",
+      ),
+    );
+    return 1;
+  }
+  console.error(
+    fail(
+      `unexpected hotfix response (state: ${result.state})`,
+      "re-run `tot hotfix`; check the storefront logs if it persists",
+    ),
+  );
+  return 1;
+}
+
+/**
+ * @param {string[]} argv
+ * @param {any} ctx
+ */
+export async function run(argv, ctx) {
+  const env = process.env;
+  const args = parseHotfixArgs(argv);
+  if (args.help) {
+    console.log(USAGE);
+    return 0;
+  }
+
+  const tenant = (args.tenant || (ctx?.mode === "checkout" ? ctx.tenant : null) || ctx?.tenant || "").trim();
+  if (!tenant) {
+    console.error(
+      fail(
+        "`tot hotfix` needs a target tenant",
+        "pass --tenant <appDomain> (e.g. --tenant tokenoftrust.com), or run inside a store checkout.",
+      ),
+    );
+    return 2;
+  }
+
+  const prNumber = parsePrNumber(args.pr);
+  const changeId = (args.change || "").trim() || null;
+  if (prNumber == null && !changeId) {
+    console.error(
+      fail(
+        "`tot hotfix` needs the reviewed hotfix candidate",
+        "pass --pr <N> (a PR number) or --change <changeId>.",
+      ),
+    );
+    return 2;
+  }
+
+  const storefrontUrl = args.url || env.TOT_STOREFRONT_URL || env.STOREFRONT_BASE_URL || DEFAULT_STOREFRONT_URL;
+  return await runHotfix(
+    {
+      tenant,
+      prNumber,
+      changeId,
+      message: (args.message || "").trim() || null,
+      secret: resolveOperatorSecret(args.secret, env),
+      storefrontUrl,
+      yes: args.yes,
+      noOpen: args.noOpen,
+    },
+    { openUrl: (u) => openBrowser(u) },
+  );
+}

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 = /** @type {any} */ (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 = /** @type {any} */ (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;
+}