@tokenoftrust/cli 2.2.10 → 2.2.12

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@tokenoftrust/cli",
-  "version": "2.2.10",
+  "version": "2.2.12",
   "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

@@ -17,8 +17,8 @@
  * every store-only step. The checkout records its kind in local git config so
  * `tot git-credential` re-mints it the same way.
  *
- * 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
+ * This is the SAME MCP code path a developer's agent takes: sign-in →
+ * tenant_checkout({ tenant }) — the tenant named on the call, no client_switch — 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
@@ -238,9 +238,8 @@ export async function run(argv, ctx, deps = {}) {
       return 0;
     }
 
-    console.error(`~ client_switch → ${args.tenant}`);
     console.error(
-      `~ tenant_checkout (tag=${args.tag}) — MCP mints a fresh repo-scoped credential`,
+      `~ tenant_checkout (tenant=${args.tenant}) — MCP mints a fresh repo-scoped credential`,
     );
     const res = await checkoutTenant(client, {
       tenant: args.tenant,
@@ -308,7 +307,7 @@ function reportFailure(e, redact) {
 /**
  * `tot clone <alias> [dir]` for a read-only alias (the agency kit). Only the steps a
  * non-store repo needs: sign-in, the read mint, the token-free clone, the helper. No store
- * listing, client_switch, identity_bind, tenant_checkout, tenant inference, `.nvmrc` or
+ * listing, identity_bind, tenant_checkout, tenant inference, `.nvmrc` or
  * `tot dev` guidance.
  */
 async function runReadOnlyAlias(alias, args, { env, createClient, establish, signIn, cloneDeps }) {
@@ -376,23 +375,13 @@ export function checkoutPointsAtEntitlement(checkout) {
  *   cloned: boolean, dir: string|null, head: string|null }>}
  */
 export async function checkoutTenant(client, { tenant, tag = "main", cloneDir = null, redact = (s) => s }) {
-  // tenant_checkout is the SOLE AUTHORITATIVE checkout decision. The pin's refusal may be
-  // entirely expected: a staff human checking out a merchant tenant under a staff-preview
-  // authorization holds no client grant on it, so the pin MUST refuse while the checkout
-  // legitimately succeeds. `tot git-credential` mints through this same function, so
-  // treating the pin as fatal breaks every fetch and push in such a checkout, not only the
-  // clone. scopeToTenant remembers that expected refusal as `pinRefusal` and throws at once
-  // on any other pin failure (a broken session must not masquerade as an authorization
-  // problem).
-  //
-  // Two uses of the remembered refusal are BOTH wrong, and the second is the dangerous one:
-  //   - discarding it loses the only good explanation when a tenant genuinely is not yours;
-  //   - letting it OVERRIDE a checkout denial replaces an authoritative answer ("your staff
-  //     authorization expired / was revoked / does not cover this resource") with grant
-  //     guidance that sends you chasing the wrong thing entirely.
-  // So an expected pin refusal may never speak over a checkout denial (see below).
+  // tenant_checkout is the SOLE AUTHORITATIVE checkout decision, and it names the tenant
+  // (scopeToTenant injects it), so the server checks out that held tenant directly — or
+  // answers for a staff-preview authorization, or refuses naming the tenants the session
+  // holds. No client_switch is sent: it writes a selection shared by every windowless
+  // session on this login, so it can lose to another session's switch before the checkout
+  // lands, and it moves that other session's selection too.
   const scoped = await scopeToTenant(client, tenant, { redact });
-  const expectedSwitchRefusal = scoped.pinRefusal;
   // 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
@@ -409,45 +398,18 @@ export async function checkoutTenant(client, { tenant, tag = "main", cloneDir =
   } catch {
     /* fail-open — see above */
   }
-  let checkout;
-  try {
-    checkout = await scoped.callTool("tenant_checkout", { tag });
-  } catch (e) {
-    // A THROWN checkout is not a denial — it never rendered an authorization decision. Only
-    // here may the expected switch refusal speak, because it is the only explanation either
-    // call produced.
-    if (expectedSwitchRefusal) {
-      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. " +
-          ACCESS_EXPLAIN_HINT(tenant),
-        cause: expectedSwitchRefusal,
-      });
-    }
-    throw e;
-  }
+  const checkout = await scoped.callTool("tenant_checkout", { 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) {
-    // 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. 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 });
+    // AUTHORITATIVE: the checkout rendered a decision, so it is the answer. When that denial
+    // points at entitlement (the store is not among the tenants the session holds), the
+    // access_explain route rides below it: it names the exact broken step for an invitee.
+    const next = checkoutPointsAtEntitlement(checkout) ? `${err.next} ${ACCESS_EXPLAIN_HINT(tenant)}` : err.next;
+    throw new CliError(redact(err.message), { next });
   }
   const gitRemote = checkout.gitRemote;
   const cloneUrl = checkout.cloneUrl ?? null;

package/src/commands/submit.mjs

@@ -1545,7 +1545,7 @@ export async function run(argv, ctx, {
       pointerScope = await scopeToTenant(client, tenant);
     } catch (error) {
       recordDiagnostic(error, {
-        command: verb, operation: "client_switch", required: false, degraded: true,
+        command: verb, operation: "tenant_scope", required: false, degraded: true,
       }, env);
     }
     const resolved = pointerScope
@@ -1661,7 +1661,7 @@ export async function run(argv, ctx, {
   let progress = null;
   let candidate = null;
   let previewPrUrl = null;
-  let operation = "client_switch";
+  let operation = "tenant_scope";
   const candidateRequired = changedEntries.length > 0;
   try {
     // Every candidate/preview call below goes through this tenant-scoped handle

package/src/tenant-scope.mjs

@@ -5,13 +5,15 @@
  * from a previous command. A command that acts on a store calls `scopeToTenant(client,
  * tenant)` once and makes every store call through the handle it returns:
  *
- *   - It pins the session with `client_switch`. A server that resolves the tenant of each
- *     call from its own `tenant` argument does not need the pin; one that still reads the
- *     session's active tenant does, and the pin is also what scopes the repo-addressed tools
- *     (PIN_SCOPED_TOOLS) for an invited developer.
  *   - It names the tenant on every call to a tool in TENANT_SCOPED_TOOLS — tools whose
  *     `tenant` argument means "the tenant this call acts on". The server uses a held tenant
  *     directly and refuses one the session does not hold; it never falls back to another.
+ *     These calls never send `client_switch`.
+ *   - It sends `client_switch` only before the first call to a tool in PIN_SCOPED_TOOLS, and
+ *     at most once. `client_switch` writes a selection the server shares across every
+ *     windowless session on the same login, so a pin can lose to another session's switch
+ *     between the pin and the call, and it moves that other session's selection too. A
+ *     command that needs no repo-addressed tool therefore never pins.
  *   - It refuses a result that reports acting on a different tenant than the one asked for.
  *
  * `test/tenant-scope-contract.test.mjs` fails the build if any file under `src/` calls a
@@ -41,7 +43,8 @@ export const TENANT_SCOPED_TOOLS = Object.freeze(new Set([
  * argument (`candidate_status` / `candidate_list` accept `tenant` only as an alias FOR `repo`;
  * `candidate_delete` / `candidate_refresh` have no `tenant` field and the server drops one).
  * The server confines them to the session's held tenants — for an invited developer, the
- * pinned one — so they go through the handle (which pinned first) with their args untouched.
+ * pinned one — so they go through the handle (which pins before the first of them) with
+ * their args untouched.
  */
 export const PIN_SCOPED_TOOLS = Object.freeze(new Set([
   "candidate_status",
@@ -109,22 +112,18 @@ export function isNotClientTenantRefusal(error) {
 /**
  * @typedef {{
  *   tenant: string,
- *   pinRefusal: any,
  *   callTool: (name: string, args?: Record<string, unknown>) => Promise<any>,
  * }} ScopedClient
- *   `pinRefusal` is the expected client_switch refusal (see isNotClientTenantRefusal) when
- *   the pin was refused, else null. The calls still name the tenant, so the server answers
- *   them authoritatively; `pinRefusal` is only the explanation a caller may add when no
- *   call produced a better one.
  */
 
 /**
- * Pin the session to `tenant` and return the handle every store call goes through.
+ * Return the handle every store call for `tenant` goes through. Sends nothing by itself.
  *
- * An expected client_switch refusal (the tenant is not one of the caller's clients — the
- * normal case for a staff human under a staff-preview authorization) is remembered on the
- * handle and the calls proceed, each naming the tenant, so the server decides. Any other
- * client_switch failure means the session is unusable and throws a CliError at once.
+ * The pin (`client_switch`) is sent lazily, once, before the first PIN_SCOPED_TOOLS call.
+ * An expected refusal of it (the tenant is not one of the caller's clients — the normal
+ * case for a staff human under a staff-preview authorization) is tolerated and the call
+ * proceeds, so the server decides. Any other pin failure means the session is unusable and
+ * that call throws a CliError without being sent.
  *
  * @param {{ callTool: (name: string, args: unknown) => Promise<any> }} client
  * @param {string} tenant
@@ -140,18 +139,20 @@ export async function scopeToTenant(client, tenant, { redact = (s) => s } = {})
   }
   const name = String(tenant).trim();
 
-  let pinRefusal = null;
-  try {
-    await client.callTool("client_switch", { tenant: name });
-  } catch (e) {
-    if (isNotClientTenantRefusal(e)) {
-      pinRefusal = e;
-    } else {
-      throw new CliError(redact(String(/** @type {any} */ (e)?.message || e)), {
-        next: "the session could not be scoped — check your connection and run `tot whoami`",
-        cause: e,
-      });
-    }
+  /** @type {Promise<void>|null} */
+  let pinned = null;
+  function pin() {
+    pinned ??= client.callTool("client_switch", { tenant: name }).then(
+      () => undefined,
+      (e) => {
+        if (isNotClientTenantRefusal(e)) return;
+        throw new CliError(redact(String(/** @type {any} */ (e)?.message || e)), {
+          next: "the session could not be scoped — check your connection and run `tot whoami`",
+          cause: e,
+        });
+      },
+    );
+    return pinned;
   }
 
   /**
@@ -159,6 +160,10 @@ export async function scopeToTenant(client, tenant, { redact = (s) => s } = {})
    * @param {Record<string, unknown>} [args]
    */
   async function callTool(tool, args = {}) {
+    if (PIN_SCOPED_TOOLS.has(tool)) {
+      await pin();
+      return client.callTool(tool, args);
+    }
     if (!TENANT_SCOPED_TOOLS.has(tool)) return client.callTool(tool, args);
     if (args && Object.hasOwn(args, "tenant") && normalizeTenant(args.tenant) !== requested) {
       throw new CliError(
@@ -180,5 +185,5 @@ export async function scopeToTenant(client, tenant, { redact = (s) => s } = {})
     return result;
   }
 
-  return { tenant: name, pinRefusal, callTool };
+  return { tenant: name, callTool };
 }

package/template/sample-store/content/chrome.json

@@ -25,7 +25,7 @@
     },
     {
       "label": "About",
-      "href": "/about"
+      "href": "/pages/about-us"
     }
   ],
   "footer": {
@@ -57,15 +57,15 @@
         "links": [
           {
             "label": "About",
-            "href": "/about"
+            "href": "/pages/about-us"
           },
           {
             "label": "Shipping & Returns",
-            "href": "/shipping-returns"
+            "href": "/pages/shipping-returns"
           },
           {
             "label": "Privacy",
-            "href": "/privacy"
+            "href": "/pages/privacy-policy"
           }
         ]
       }