@tokenoftrust/cli 2.2.0 → 2.2.1

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@tokenoftrust/cli",
-  "version": "2.2.0",
+  "version": "2.2.1",
   "description": "Token of Trust developer CLI — clone a tenant store, run it locally with save→reload, and submit it for preview. Installs the `tot` command.",
   "license": "Apache-2.0",
   "author": "Token of Trust",

package/src/commands/clone.mjs

@@ -342,6 +342,27 @@ async function runReadOnlyAlias(alias, args, { env, createClient, establish, sig
   }
 }
 
+/**
+ * Where an invited developer whose store does not resolve gets the exact broken step: the
+ * owner's Team page "Check access" (tot-mcp access_explain), which walks their sign-in and
+ * checkout chain and names the first failure with its fix.
+ * @param {string} tenant
+ */
+export const ACCESS_EXPLAIN_HINT = (tenant) =>
+  `To see exactly which step breaks, ask the owner of ${tenant} to click "Check access" ` +
+  "next to your name on their Team page (or run the tot MCP tool access_explain).";
+
+/**
+ * Does tenant_checkout's own denial send the caller to the entitlement plane (no grant or
+ * client context resolved for the tenant), as opposed to a staff-preview authorization?
+ * Read from the structured fields tenant_checkout sets, never from message text.
+ * @param {unknown} checkout
+ */
+export function checkoutPointsAtEntitlement(checkout) {
+  const c = /** @type {any} */ (checkout);
+  return c?.status === "not_entitled" || c?.nextAction === "grant_introspect";
+}
+
 /**
  * Is this client_switch failure the EXPECTED "that tenant is not one of your clients"
  * refusal, as opposed to a broken session (transport, auth, malformed envelope, internal
@@ -446,7 +467,8 @@ export async function checkoutTenant(client, { tenant, tag = "main", cloneDir =
       throw new CliError(redact(String(expectedSwitchRefusal?.message || expectedSwitchRefusal)), {
         next:
           "confirm you're entitled to this store — `tot grants` lists what your session can " +
-          "act on, and `tot login` refreshes a grant issued after you signed in",
+          "act on, and `tot login` refreshes a grant issued after you signed in. " +
+          ACCESS_EXPLAIN_HINT(tenant),
         cause: expectedSwitchRefusal,
       });
     }
@@ -460,7 +482,18 @@ export async function checkoutTenant(client, { tenant, tag = "main", cloneDir =
   if (err) {
     // AUTHORITATIVE: the checkout rendered a decision, so it is the answer — even when the
     // switch also refused. Substituting grant guidance here is what would tell someone whose
-    // staff authorization had EXPIRED to go looking at their grants.
+    // staff authorization had EXPIRED to go looking at their grants. Only when the checkout's
+    // OWN denial points at entitlement does the switch refusal ride below it: for an invited
+    // developer it is the one that names the cause (the store is not among the tenants their
+    // session resolved), and dropping it left only a downstream "Over-scoped" that reads like
+    // a selection error.
+    if (expectedSwitchRefusal && checkoutPointsAtEntitlement(checkout)) {
+      const switchMessage = String(expectedSwitchRefusal?.message || expectedSwitchRefusal);
+      throw new CliError(
+        redact(`${err.message}\n  client_switch also refused: ${switchMessage}`),
+        { next: `${err.next} ${ACCESS_EXPLAIN_HINT(tenant)}`, cause: expectedSwitchRefusal },
+      );
+    }
     throw new CliError(redact(err.message), { next: err.next });
   }
   const gitRemote = checkout.gitRemote;