@tokenoftrust/cli 2.2.3 → 2.2.5

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@tokenoftrust/cli",
-  "version": "2.2.3",
+  "version": "2.2.5",
   "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/accept.mjs

@@ -45,6 +45,7 @@ import { resolveOperatorSecret } from "./ship.mjs";
 // same way `tot pr` reaches `candidate_status`/`candidate_close`.
 import { createMcpClient } from "../mcp.mjs";
 import { establishSession, AuthUnavailableError } from "../auth.mjs";
+import { scopeToTenant } from "../tenant-scope.mjs";
 // No-operator-secret path: mint a viewer session from the developer's OWN `tot`
 // login and integrate as themselves (server gates on their live ship-on-behalf grant).
 import { resolveViewerTransport } from "../viewer-session.mjs";
@@ -270,8 +271,8 @@ export function notMergeableOfferLines(tenant, { pr, changeId }) {
  * Run `candidate_refresh` over the MCP client — the ONE-CLICK rebuild of a
  * not-mergeable candidate onto the current preview tip. `candidate_refresh` has no
  * operator-secret HTTP route, so this reaches it exactly as `tot pr` reaches
- * `candidate_status`: an OAuth developer session (`tot login`) + `client_switch` to
- * bind the tenant scope. `createClient`/`establishSession` are injected so it's
+ * `candidate_status`: an OAuth developer session (`tot login`) scoped to the tenant with
+ * `scopeToTenant`. `createClient`/`establishSession` are injected so it's
  * unit-tested with no live MCP.
  *
  * @param {{ tenant:string, changeId:string, strategy:string, mcpUrl?:string|null,
@@ -289,14 +290,8 @@ export async function runRefresh(
   const client = create(baseUrl);
   try {
     await establish(client, { env, prefer: identity || undefined });
-    // Bind the active tenant so candidate_refresh resolves the right scope (mirrors
-    // `tot pr`). Best-effort — the tool also takes `repo` explicitly.
-    try {
-      await client.callTool("client_switch", { tenant });
-    } catch {
-      /* best-effort scope bind */
-    }
-    const raw = await client.callTool("candidate_refresh", { repo: tenant, changeId, strategy });
+    const scoped = await scopeToTenant(client, tenant);
+    const raw = await scoped.callTool("candidate_refresh", { repo: tenant, changeId, strategy });
     return normalizeRefreshResult(raw);
   } catch (e) {
     if (e instanceof AuthUnavailableError) {

package/src/commands/branches.mjs

@@ -30,6 +30,7 @@ import { execFileSync } from "node:child_process";
 import { createMcpClient } from "../mcp.mjs";
 import { establishSession, AuthUnavailableError } from "../auth.mjs";
 import { fail } from "../errors.mjs";
+import { scopeToTenant } from "../tenant-scope.mjs";
 import { repoNameFromRemote } from "./submit.mjs";
 
 const DEFAULT_MCP_URL = "https://mcp.tokenoftrust.com";
@@ -256,9 +257,9 @@ export async function run(argv, ctx) {
   const client = createMcpClient(baseUrl);
   try {
     await establishSession(client, { env, prefer: args.identity || undefined });
-    if (tenant) await client.callTool("client_switch", { tenant });
+    const scoped = await scopeToTenant(client, /** @type {string} */ (tenant));
 
-    const report = await client.callTool("candidate_list", {
+    const report = await scoped.callTool("candidate_list", {
       repo,
       ...(args.staleAfterDays != null && Number.isFinite(args.staleAfterDays)
         ? { staleAfterDays: args.staleAfterDays }

package/src/commands/cleanup.mjs

@@ -27,6 +27,7 @@
 import { createMcpClient } from "../mcp.mjs";
 import { establishSession, AuthUnavailableError } from "../auth.mjs";
 import { fail } from "../errors.mjs";
+import { scopeToTenant } from "../tenant-scope.mjs";
 import { planForAction, printPlanAndConfirm } from "../plan.mjs";
 import { resolveRepoAndTenant, renderBranchesTable, formatBranchRow } from "./branches.mjs";
 
@@ -154,9 +155,9 @@ export async function run(argv, ctx) {
   const client = createMcpClient(baseUrl);
   try {
     await establishSession(client, { env, prefer: args.identity || undefined });
-    if (tenant) await client.callTool("client_switch", { tenant });
+    const scoped = await scopeToTenant(client, /** @type {string} */ (tenant));
 
-    const report = await client.callTool("candidate_list", {
+    const report = await scoped.callTool("candidate_list", {
       repo,
       ...(args.staleAfterDays != null && Number.isFinite(args.staleAfterDays)
         ? { staleAfterDays: args.staleAfterDays }
@@ -226,7 +227,7 @@ export async function run(argv, ctx) {
     let failures = 0;
     for (const b of eligible) {
       try {
-        const res = await client.callTool("candidate_delete", {
+        const res = await scoped.callTool("candidate_delete", {
           repo,
           ref: b.ref,
           expectedSha: b.sha,

package/src/commands/clone.mjs

@@ -58,6 +58,7 @@ import { createMcpClient } from "../mcp.mjs";
 import { establishSession, AuthUnavailableError } from "../auth.mjs";
 import { offerSignIn } from "./login.mjs";
 import { CliError, fail, formatError } from "../errors.mjs";
+import { scopeToTenant } from "../tenant-scope.mjs";
 import { writeNvmrc } from "../sample.mjs";
 import { emitObstacle } from "../obstacle.mjs";
 import {
@@ -364,41 +365,8 @@ export function checkoutPointsAtEntitlement(checkout) {
 }
 
 /**
- * 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
- * error)? The distinction is load-bearing: an expected refusal is a normal step on the
- * staff-preview path and must be tolerated, while anything else means the session itself
- * is unusable and must surface immediately rather than be mistaken for an authorization
- * problem later.
- *
- * Matched on the server's STRUCTURED signal first (`serverCode` / status), because message
- * text is not a contract. The text fallback exists only for servers predating a typed code
- * and is deliberately narrow — when in doubt this returns false, which escalates. Treating
- * an unknown failure as "expected" is the unsafe direction: it would let a dead connection
- * pass for a routine refusal.
- *
- * Pure + exported so it is unit-tested without any I/O.
- * @param {unknown} error
- * @returns {boolean}
- */
-export function isNotClientTenantRefusal(error) {
-  const e = /** @type {any} */ (error);
-  if (!e) return false;
-  // A transport/protocol-level failure is never an authorization refusal.
-  const category = e?.diagnostic?.category ?? e?.category;
-  if (category && category !== "tool_error") return false;
-  const code = e?.diagnostic?.serverCode ?? e?.serverCode;
-  if (typeof code === "string") {
-    return code === "not_client_tenant" || code === "over_scoped";
-  }
-  // Text fallback (pre-typed-code servers) — narrow on purpose.
-  const message = typeof e?.message === "string" ? e.message : "";
-  return /not one of your client tenants/i.test(message);
-}
-
-/**
- * The privileged checkout core, composable in-process (used by `tot clone`
- * and by `tot start`): client_switch → tenant_checkout → optionally clone. The
+ * The privileged checkout core, composable in-process (used by `tot clone`, `tot start`
+ * and `tot git-credential`): scope to the tenant → tenant_checkout → optionally clone. The
  * MCP mints a fresh, repo-scoped push credential each time. Assumes `client` is
  * already initialized + has a validated session.
  *
@@ -408,38 +376,23 @@ export function isNotClientTenantRefusal(error) {
  *   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. client_switch is a scope
-  // convenience whose 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
-  // switch MUST refuse while the checkout legitimately succeeds. `tot git-credential` mints
-  // through this same function, so treating the switch as fatal breaks every fetch and push
-  // in such a checkout, not only the clone.
+  // 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 failure modes are therefore BOTH wrong, and the second is the dangerous one:
-  //   - discarding the refusal loses the only good explanation when a tenant genuinely is
-  //     not yours;
-  //   - letting the refusal 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 switch refusal may never speak over a checkout denial (see below).
-  //
-  // An UNEXPECTED switch failure — transport, auth, a malformed envelope — is not the
-  // not-a-client case at all. It means the session itself is broken, and carrying it
-  // silently would let a dead connection masquerade as an authorization problem, so it is
-  // raised immediately rather than remembered.
-  let expectedSwitchRefusal = null;
-  try {
-    await client.callTool("client_switch", { tenant });
-  } catch (e) {
-    if (isNotClientTenantRefusal(e)) {
-      expectedSwitchRefusal = e;
-    } else {
-      throw new CliError(redact(String(e?.message || e)), {
-        next: "the session could not be scoped — check your connection and run `tot whoami`",
-        cause: e,
-      });
-    }
-  }
+  // 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).
+  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
@@ -458,7 +411,7 @@ export async function checkoutTenant(client, { tenant, tag = "main", cloneDir =
   }
   let checkout;
   try {
-    checkout = await client.callTool("tenant_checkout", { tenant, tag });
+    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

package/src/commands/pr.mjs

@@ -27,6 +27,7 @@ import { execFileSync } from "node:child_process";
 import { createMcpClient } from "../mcp.mjs";
 import { establishSession, AuthUnavailableError } from "../auth.mjs";
 import { fail } from "../errors.mjs";
+import { scopeToTenant } from "../tenant-scope.mjs";
 import { repoNameFromRemote, currentBranch } from "./submit.mjs";
 // `tot pr list` reuses `tot ship --pr`'s operator-secret transport helpers verbatim
 // (same env precedence, same queue normalisation) so the two speak one wire, not two.
@@ -368,10 +369,9 @@ export async function run(argv, ctx) {
   try {
     const session = await establishSession(client, { env, prefer: args.identity || undefined });
     void session;
-    // Bind the active tenant so candidate_status/close read the right scope.
-    await client.callTool("client_switch", { tenant });
+    const scoped = await scopeToTenant(client, tenant);
 
-    const candidates = extractCandidates(await client.callTool("candidate_status", { repo }));
+    const candidates = extractCandidates(await scoped.callTool("candidate_status", { repo }));
 
     if (args.sub === "list") {
       if (!candidates.length) {
@@ -408,7 +408,7 @@ export async function run(argv, ctx) {
     }
 
     // close
-    await client.callTool("candidate_close", {
+    await scoped.callTool("candidate_close", {
       repo,
       changeId: match.changeId,
       ...(args.reason ? { reason: args.reason } : {}),

package/src/commands/rollback.mjs

@@ -36,6 +36,7 @@
 import { createMcpClient } from "../mcp.mjs";
 import { establishSession, AuthUnavailableError } from "../auth.mjs";
 import { fail } from "../errors.mjs";
+import { scopeToTenant } from "../tenant-scope.mjs";
 import { isInteractive, promptYesNo } from "../prompt.mjs";
 import { startProgress } from "../progress.mjs";
 
@@ -224,7 +225,7 @@ export function renderRollbackPreview({ tenant, target, toVersionId, preview })
  * confirm → commit (with a target). Split out from `run` so it's driven in tests
  * with a mock client + injected confirm/interactive, no network/TTY.
  *
- * @param {{callTool:Function}} client an MCP client (real or mock)
+ * @param {{callTool:Function}} scoped the tenant-scoped handle from `scopeToTenant` (or a mock)
  * @param {{ tenant:string, target:string, toVersionId:string|null,
  *   revisionBase?:string|null }} params `revisionBase` is the storefront origin
  *   the listing's `/rev/<sha>` links resolve against; omit to list
@@ -233,7 +234,7 @@ export function renderRollbackPreview({ tenant, target, toVersionId, preview })
  *   progress?:boolean }} [deps]
  * @returns {Promise<number>} process exit code
  */
-export async function runRollback(client, { tenant, target, toVersionId, revisionBase }, deps = {}) {
+export async function runRollback(scoped, { tenant, target, toVersionId, revisionBase }, deps = {}) {
   const interactive = deps.interactive || isInteractive;
   const confirm = deps.confirm || promptYesNo;
 
@@ -241,7 +242,7 @@ export async function runRollback(client, { tenant, target, toVersionId, revisio
   if (!toVersionId) {
     let status;
     try {
-      status = normalizeStatus(await client.callTool("promotion_status", { target }));
+      status = normalizeStatus(await scoped.callTool("promotion_status", { target }));
     } catch (e) {
       console.error(
         fail(
@@ -272,7 +273,7 @@ export async function runRollback(client, { tenant, target, toVersionId, revisio
   let preview;
   try {
     preview = normalizeRollbackPreview(
-      await client.callTool("promotion_rollback", { target, toVersionId, dryRun: true }),
+      await scoped.callTool("promotion_rollback", { target, toVersionId, dryRun: true }),
     );
   } catch (e) {
     console.error(
@@ -320,7 +321,7 @@ export async function runRollback(client, { tenant, target, toVersionId, revisio
   let result;
   try {
     result = normalizeRollbackResult(
-      await client.callTool("promotion_rollback", { target, toVersionId, dryRun: false }),
+      await scoped.callTool("promotion_rollback", { target, toVersionId, dryRun: false }),
     );
   } catch (e) {
     console.error(
@@ -383,10 +384,9 @@ export async function run(argv, ctx) {
   const client = createMcpClient(baseUrl);
   try {
     await establishSession(client, { env, prefer: args.identity || undefined });
-    // Bind the active tenant so the promotion tools read/write the right scope.
-    await client.callTool("client_switch", { tenant });
+    const scoped = await scopeToTenant(client, tenant);
 
-    return await runRollback(client, { tenant, target, toVersionId: args.versionId, revisionBase });
+    return await runRollback(scoped, { tenant, target, toVersionId: args.versionId, revisionBase });
   } catch (e) {
     if (e instanceof AuthUnavailableError) {
       console.error(fail("sign in to roll back", e.hint || "run `tot login`, then re-run `tot rollback`"));

package/src/commands/ship.mjs

@@ -188,15 +188,15 @@ export function normalizeChangeResult(r) {
 /**
  * Poll `change_status` until the change reports shipped (or the attempts budget
  * runs out). Injectable delay/attempts.
- * @param {{callTool:Function}} client
- * @param {{ id:string, tenant?:string }} target
+ * @param {{callTool:Function}} scoped the tenant-scoped handle from `scopeToTenant` (or a mock)
+ * @param {{ id:string }} target
  * @param {{ attempts?:number, delayMs?:number, sleep?:(ms:number)=>Promise<void> }} [opts]
  */
-export async function pollChangeShipped(client, { id, tenant }, { attempts = 6, delayMs = 1500, sleep } = {}) {
+export async function pollChangeShipped(scoped, { id }, { attempts = 6, delayMs = 1500, sleep } = {}) {
   const wait = sleep || ((ms) => new Promise((r) => setTimeout(r, ms)));
   let last = null;
   for (let i = 0; i < attempts; i++) {
-    last = normalizeChangeResult(await client.callTool("change_status", { id, ...(tenant ? { tenant } : {}) }));
+    last = normalizeChangeResult(await scoped.callTool("change_status", { id }));
     if (last.shipped) return last;
     if (i < attempts - 1) await wait(delayMs);
   }

package/src/commands/submit.mjs

@@ -45,6 +45,7 @@ import { setTimeout as delay } from "node:timers/promises";
 import { createMcpClient } from "../mcp.mjs";
 import { establishSession, AuthUnavailableError } from "../auth.mjs";
 import { checkoutTenant } from "./clone.mjs";
+import { scopeToTenant } from "../tenant-scope.mjs";
 // Reuse the operator side's `candidate_refresh` result normaliser (unit c3 — the
 // born-rebased submit rebuilds a candidate onto the current base with the SAME
 // engine `tot accept --refresh` uses, so the two read its result identically).
@@ -497,13 +498,13 @@ export const DEFAULT_BORN_REBASED_STRATEGY = "merge";
  * throw — an owner-gated denial (candidate_refresh is app-owner gated), an older MCP
  * without the tool, a transient failure — normalizes to a non-ok error result the
  * caller submits-as-is on, NEVER blocking the push that already landed.
- * @param {{callTool:Function}} client
+ * @param {{callTool:Function}} scoped the tenant-scoped handle from `scopeToTenant` (or a mock)
  * @param {{ repo: string, changeId: string, strategy: string }} opts
  * @returns {Promise<ReturnType<typeof normalizeRefreshResult>>}
  */
-export async function runBornRebased(client, { repo, changeId, strategy }) {
+export async function runBornRebased(scoped, { repo, changeId, strategy }) {
   try {
-    const raw = await client.callTool("candidate_refresh", { repo, changeId, strategy });
+    const raw = await scoped.callTool("candidate_refresh", { repo, changeId, strategy });
     return normalizeRefreshResult(raw);
   } catch (e) {
     const diagnostic = recordDiagnostic(e, {
@@ -957,13 +958,13 @@ export function chooseChangeId({ tenant, actorKey, branch = null, active = null,
  * that can't run never blocks, changes, or crashes a submit (u17 acceptance #3).
  * Tolerates the tool returning a bare candidate, a `{candidates:[…]}` list, or a
  * plain array. Injectable client for tests.
- * @param {{callTool:Function}} client
+ * @param {{callTool:Function}} scoped the tenant-scoped handle from `scopeToTenant` (or a mock)
  * @param {{ repo: string, changeId: string }} opts
  * @returns {Promise<string|null>}
  */
-export async function candidateStateFor(client, { repo, changeId }) {
+export async function candidateStateFor(scoped, { repo, changeId }) {
   try {
-    const r = await client.callTool("candidate_status", { repo, changeId });
+    const r = await scoped.callTool("candidate_status", { repo, changeId });
     const c = Array.isArray(r)
       ? r.find((x) => x?.changeId === changeId)
       : Array.isArray(r?.candidates)
@@ -993,13 +994,13 @@ export async function candidateStateFor(client, { repo, changeId }) {
  * state drops the pointer. When it does, `dropped` carries the old changeId + the
  * terminal state so the caller can tell the operator and forget the on-disk pointer.
  * Injectable client for tests.
- * @param {{callTool:Function}} client
+ * @param {{callTool:Function}} scoped the tenant-scoped handle from `scopeToTenant` (or a mock)
  * @param {{ repo: string|null, active: string|null }} opts
  * @returns {Promise<{ active: string|null, dropped?: { changeId: string, state: string } }>}
  */
-export async function resolveActivePointer(client, { repo, active }) {
+export async function resolveActivePointer(scoped, { repo, active }) {
   if (!active || !repo) return { active };
-  const state = await candidateStateFor(client, { repo, changeId: active });
+  const state = await candidateStateFor(scoped, { repo, changeId: active });
   if (isTerminalCandidateState(state)) return { active: null, dropped: { changeId: active, state: /** @type {string} */ (state) } };
   return { active };
 }
@@ -1039,19 +1040,19 @@ export class CandidateRegistrationError extends Error {
  * has already pushed its real commits, so this call sends only the exact candidate
  * ref and asserted HEAD plus PR metadata. Any registration failure is fatal: a
  * pushed ref without a review PR is not a successful submit.
- * @param {ReturnType<import("../mcp.mjs").createMcpClient>} client
+ * @param {{callTool:Function}} scoped the tenant-scoped handle from `scopeToTenant` (or a mock)
  * @param {{ repo: string|null, changeId: string, ref: string, headSha: string,
  *   changeSummary: {title:string, body:string[]}, hasChanges: boolean,
  *   quiet?: boolean }} opts  `quiet` (--json) suppresses the human print; the same
  *   result is still returned for the caller's JSON payload.
  */
-export async function submitCandidate(client, { repo, changeId, ref, headSha, changeSummary, hasChanges, quiet = false }) {
+export async function submitCandidate(scoped, { repo, changeId, ref, headSha, changeSummary, hasChanges, quiet = false }) {
   if (!repo) {
     throw new CandidateRegistrationError("Candidate not created: couldn't derive the forge repo from origin.");
   }
   if (!hasChanges) throw new CandidateRegistrationError("Candidate not created: no content changes were found.");
   try {
-    const result = await client.callTool("candidate_open", {
+    const result = await scoped.callTool("candidate_open", {
       repo,
       changeId,
       // Defensively bounded to candidate_open's own schema limits (title<=200,
@@ -1536,17 +1537,20 @@ export async function run(argv, ctx, {
   // and opening a NEW PR that inherits a guaranteed conflict (the live incident this
   // guards against). Skipped under --fork-candidate (chooseChangeId ignores `active`
   // there anyway). Purely diagnostic: a check that errors leaves the pointer untouched.
-  // Needs the tenant scope bound for candidate_status to resolve — idempotent with
-  // the later client_switch / the fresh-mint checkoutTenant.
+  // Runs scoped to the tenant (idempotent with the later scoping / the fresh-mint
+  // checkoutTenant); a session that cannot be scoped leaves the pointer untouched.
   if (active && repo && !args.forkCandidate) {
+    let pointerScope = null;
     try {
-      await client.callTool("client_switch", { tenant });
+      pointerScope = await scopeToTenant(client, tenant);
     } catch (error) {
       recordDiagnostic(error, {
         command: verb, operation: "client_switch", required: false, degraded: true,
       }, env);
     }
-    const resolved = await resolveActivePointer(client, { repo, active });
+    const resolved = pointerScope
+      ? await resolveActivePointer(pointerScope, { repo, active })
+      : /** @type {Awaited<ReturnType<typeof resolveActivePointer>>} */ ({ active });
     if (resolved.dropped) {
       console.error(
         `~ remembered candidate ${resolved.dropped.changeId} is ${resolved.dropped.state} — dropping it and submitting fresh (a ${resolved.dropped.state} PR can't be reused).`,
@@ -1611,8 +1615,7 @@ export async function run(argv, ctx, {
   //    (decision B). The token baked into `.git/config` at clone time expires within
   //    hours, so we re-mint right before the push and hand it to git ephemerally
   //    (never persisted to `.git/config`), re-minting once on an auth failure.
-  //    `checkoutTenant(cloneDir:null)` mints without re-cloning AND client_switch()es,
-  //    binding the tenant scope the candidate/preview read-back below reads.
+  //    `checkoutTenant(cloneDir:null)` mints without re-cloning.
   const tag = tagFromRepoName(repo, tenant);
   const mintRemote = async () => {
     try {
@@ -1661,21 +1664,22 @@ export async function run(argv, ctx, {
   let operation = "client_switch";
   const candidateRequired = changedEntries.length > 0;
   try {
-    // Bind the active tenant so preview_status/candidate_open read the right scope
-    // (idempotent — checkoutTenant already switched when the fresh mint succeeded).
+    // Every candidate/preview call below goes through this tenant-scoped handle
+    // (idempotent with checkoutTenant's own scoping when the fresh mint succeeded).
+    let scoped;
     try {
-      await client.callTool("client_switch", { tenant });
+      scoped = await scopeToTenant(client, tenant);
     } catch (e) {
       throw new CandidateRegistrationError(
         `Candidate not created: tenant scope could not be bound (${describeReadbackError(e)}).`,
-        e,
+        /** @type {any} */ (e)?.cause ?? e,
       );
     }
 
     // 2b. Register the exact ref and asserted commit that git just pushed. No file
     // bytes cross MCP and the server does not reconstruct or replace these commits.
     operation = "candidate_open";
-    candidate = await submitCandidate(client, {
+    candidate = await submitCandidate(scoped, {
       repo, changeId, ref, headSha: commit, changeSummary,
       hasChanges: changedEntries.length > 0, quiet: args.json,
     });
@@ -1699,7 +1703,7 @@ export async function run(argv, ctx, {
     // baseDrift (0 when skipped).
     if (repo && baseDrift > 0 && candidate && !isTerminalCandidateState(candidate.state) && changeId) {
       operation = "candidate_refresh";
-      const rebased = await runBornRebased(client, { repo, changeId, strategy: bornRebasedStrategy });
+      const rebased = await runBornRebased(scoped, { repo, changeId, strategy: bornRebasedStrategy });
       if (rebased.ok) {
         for (const line of formatBornRebasedSuccess({ behind: baseDrift, strategy: rebased.strategy || bornRebasedStrategy, refreshedFiles: rebased.refreshedFiles })) {
           if (!args.json) console.log(line);
@@ -1757,7 +1761,7 @@ export async function run(argv, ctx, {
     let status;
     operation = "preview_status";
     if (args.noWait) {
-      status = normalizePreviewStatus(await client.callTool("preview_status", { commit: statusSha }));
+      status = normalizePreviewStatus(await scoped.callTool("preview_status", { commit: statusSha }));
     } else {
       // One in-place status line (TTY: a spinner with an elapsed-seconds counter;
       // non-TTY: a ~10s heartbeat) instead of a newline per poll — the wait reads
@@ -1777,7 +1781,7 @@ export async function run(argv, ctx, {
           stages: [{ afterMs: 45_000, text: `still reconciling ${statusShort}… (larger changes take longer)` }],
         });
       }
-      status = await pollPreviewStatus(client, statusSha, {
+      status = await pollPreviewStatus(scoped, statusSha, {
         ...(args.watch ? WATCH_POLL : DEFAULT_POLL),
         onTick: (s) => {
           // Reconcile is done but we're still waiting on a ship decision (--watch):
@@ -1900,14 +1904,14 @@ export function previewSubmitSucceeded(status) {
  * observed. Injectable delay/attempts/waitMs/grace + a `now` clock and `sleep`
  * fn for tests (so the fallback-sleep cadence can be asserted deterministically
  * off the injected clock instead of real wall-clock elapsed time).
- * @param {{callTool:Function}} client
+ * @param {{callTool:Function}} scoped the tenant-scoped handle from `scopeToTenant` (or a mock)
  * @param {string} commit
  * @param {{ attempts?: number, delayMs?: number, waitMs?: number, untilShipped?: boolean,
  *   notDispatchedGraceMs?: number, now?: () => number, sleep?: (ms:number) => Promise<void>,
  *   onTick?: (s:object,i:number)=>void }} [opts]
  */
 export async function pollPreviewStatus(
-  client,
+  scoped,
   commit,
   {
     attempts = 8,
@@ -1926,7 +1930,7 @@ export async function pollPreviewStatus(
   for (let i = 0; i < attempts; i++) {
     const startedAt = now();
     const args = waitMs ? { commit, waitMs } : { commit };
-    last = normalizePreviewStatus(await client.callTool("preview_status", args));
+    last = normalizePreviewStatus(await scoped.callTool("preview_status", args));
     if (last.dispatched) everDispatched = true;
     last.everDispatched = everDispatched;
     if (onTick) onTick(last, i);

package/src/tenant-scope.mjs

@@ -0,0 +1,184 @@
+/**
+ * The ONE way a `tot` command acts on a store.
+ *
+ * Every `tot` command is a fresh MCP session, so nothing about "which store" carries over
+ * 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.
+ *   - 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
+ * TENANT_SCOPED_TOOLS / PIN_SCOPED_TOOLS tool other than through a handle (named `scoped`),
+ * or calls `client_switch` anywhere but here, or calls a tool this file does not classify.
+ */
+import { CliError } from "./errors.mjs";
+
+/**
+ * Tools whose `tenant` argument is the tenant the call acts on. Action-harness tools get the
+ * argument from `registerActionTool` (tot-mcp `src/modules/mcp/tools/action-tool.ts`), which
+ * resolves it through `resolveCallTenant` and echoes the tenant it acted on in every success
+ * result; `tenant_checkout` declares the same argument itself and echoes it too.
+ */
+export const TENANT_SCOPED_TOOLS = Object.freeze(new Set([
+  "candidate_open",
+  "candidate_close",
+  "change_status",
+  "preview_status",
+  "promotion_rollback",
+  "promotion_status",
+  "tenant_checkout",
+]));
+
+/**
+ * Tools that act on a store named by their `repo` argument and take no tenant-of-the-call
+ * 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.
+ */
+export const PIN_SCOPED_TOOLS = Object.freeze(new Set([
+  "candidate_status",
+  "candidate_list",
+  "candidate_delete",
+  "candidate_refresh",
+]));
+
+/**
+ * Tools that act on no store, or name their own target with a meaning other than "the
+ * tenant of this call" (`repo_read_credential`'s `tenant` is the active scope or a FOREIGN
+ * tenant for an authorized cross-tenant read, and its `alias` form takes no tenant at all).
+ * Called directly on the client.
+ */
+export const TENANT_NEUTRAL_TOOLS = Object.freeze(new Set([
+  "client_list",
+  "identity_bind",
+  "identity_link_begin",
+  "identity_link_poll",
+  "grant_introspect",
+  "dev_renderer_artifact",
+  "dev_image_pull_token",
+  "feedback_submit",
+  "repo_read_credential",
+]));
+
+/** @param {unknown} tenant */
+function normalizeTenant(tenant) {
+  return typeof tenant === "string" ? tenant.trim().toLowerCase() : "";
+}
+
+/**
+ * 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
+ * error)? The distinction is load-bearing: an expected refusal is a normal step on the
+ * staff-preview path and must be tolerated, while anything else means the session itself
+ * is unusable and must surface immediately rather than be mistaken for an authorization
+ * problem later.
+ *
+ * Matched on the server's STRUCTURED signal first (`serverCode` / status), because message
+ * text is not a contract. The text fallback exists only for servers predating a typed code
+ * and is deliberately narrow — when in doubt this returns false, which escalates. Treating
+ * an unknown failure as "expected" is the unsafe direction: it would let a dead connection
+ * pass for a routine refusal.
+ *
+ * Pure + exported so it is unit-tested without any I/O.
+ * @param {unknown} error
+ * @returns {boolean}
+ */
+export function isNotClientTenantRefusal(error) {
+  const e = /** @type {any} */ (error);
+  if (!e) return false;
+  // A transport/protocol-level failure is never an authorization refusal.
+  const category = e?.diagnostic?.category ?? e?.category;
+  if (category && category !== "tool_error") return false;
+  const code = e?.diagnostic?.serverCode ?? e?.serverCode;
+  if (typeof code === "string") {
+    return code === "not_client_tenant" || code === "over_scoped";
+  }
+  // Text fallback (pre-typed-code servers) — narrow on purpose.
+  const message = typeof e?.message === "string" ? e.message : "";
+  return /not one of your client tenants/i.test(message);
+}
+
+/**
+ * @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.
+ *
+ * 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.
+ *
+ * @param {{ callTool: (name: string, args: unknown) => Promise<any> }} client
+ * @param {string} tenant
+ * @param {{ redact?: (s: string) => string }} [opts]
+ * @returns {Promise<ScopedClient>}
+ */
+export async function scopeToTenant(client, tenant, { redact = (s) => s } = {}) {
+  const requested = normalizeTenant(tenant);
+  if (!requested) {
+    throw new CliError("no store to act on: scopeToTenant needs a tenant", {
+      next: "run this from a `tot clone` checkout, or pass --tenant <appDomain>",
+    });
+  }
+  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,
+      });
+    }
+  }
+
+  /**
+   * @param {string} tool
+   * @param {Record<string, unknown>} [args]
+   */
+  async function 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(
+        `refusing ${tool}: the call names tenant "${String(args.tenant)}" but this command is scoped to "${name}"`,
+        { next: "this is a bug in tot — please report it with `tot feedback`" },
+      );
+    }
+    const result = await client.callTool(tool, { ...args, tenant: name });
+    const echoed = /** @type {any} */ (result)?.tenant;
+    if (typeof echoed === "string" && normalizeTenant(echoed) !== requested) {
+      throw new CliError(
+        `${tool} answered for "${echoed}", not "${name}" — refusing to use a result for another store`,
+        {
+          next: "tot stopped here. This is a server-side scoping fault: report it with `tot feedback`, " +
+            "and run `tot whoami` to see which stores your session holds",
+        },
+      );
+    }
+    return result;
+  }
+
+  return { tenant: name, pinRefusal, callTool };
+}

package/src/validate.mjs

@@ -653,6 +653,24 @@ export const TRACKING_ID_STEP_NAME = "assign stable tracking ids";
 export const CTA_MISSING_ID_FIX =
   "assign stable tracking ids: GET/POST /api/admin/tracking-writeback proposes a data-tot-el for every element that's missing one, as a reviewable candidate PR (GET first for a dry-run preview) — or run `tot validate` to see the full list before you submit.";
 
+// `public/**` is git-tracked and wholesale-ingested into R2 on every publish
+// with no content-hash dedup (ingestAssetVersion re-copies every file under a
+// new version key, changed or not) — see docs/versioned-assets-contract.md.
+// A large binary there works, but it compounds: every future publish re-pays
+// its storage cost, and the tenant's Gitea repo keeps that blob permanently.
+// WARN only — never blocks a submit. Idea tracked for a built-in fix (auto
+// relocation to a deduped, content-addressed store): fb-1790956035713-snpovm.
+export const LARGE_PUBLIC_ASSET_BYTES = 100 * 1024;
+export const LARGE_PUBLIC_ASSET_IDEA_ID = "fb-1790956035713-snpovm";
+export const LARGE_PUBLIC_ASSET_FIX =
+  `storing it under public/ will work, but every publish re-copies it into R2 and ` +
+  `your Gitea repo keeps it forever — on a tenant with many of these, expect ` +
+  `slower publishes and slower clones over time. Today, host it on a shared drive ` +
+  `you control and tell us the URL so we can pull it in and serve it from R2 directly, ` +
+  `rather than committing it to the tenant repo. We're tracking a built-in fix ` +
+  `(automatic relocation to deduped storage, idea ${LARGE_PUBLIC_ASSET_IDEA_ID}) — ` +
+  `vote for it if you'd like this handled for you sooner.`;
+
 /**
  * The advisory rules LOUD enough to call out by NAME at `tot validate` / `tot
  * submit` / `tot preview` — none of them block, but each ships a page that
@@ -682,6 +700,11 @@ export const LOUD_ADVISORY_RULES = [
     `actionable element with no governed identity (data-tot-el) — needs to ${TRACKING_ID_STEP_NAME}`,
     `It renders and works fine, but it's invisible to interaction tracking — nothing about it is ever recorded. ${CTA_MISSING_ID_FIX}`,
   ],
+  [
+    "large-public-asset",
+    `a public/ asset is ${(LARGE_PUBLIC_ASSET_BYTES / 1024).toFixed(0)}KB or larger`,
+    LARGE_PUBLIC_ASSET_FIX,
+  ],
   [
     "cta-id-drift",
     "a previously-declared data-tot-el changed value",
@@ -1208,6 +1231,9 @@ export function validateTenant(tenantDir, opts = {}) {
     }
   }
 
+  // large public assets — advisory (never blocks); see LARGE_PUBLIC_ASSET_FIX.
+  findings.push(...findLargePublicAssets(publicDir, rel));
+
   const ok = !findings.some((f) => f.level === ERROR);
   return { ok, findings };
 }
@@ -1276,4 +1302,20 @@ function checkAsset(src, file, publicDir, tenantId) {
   return null;
 }
 
+/**
+ * Every file under `public/**` at or above `LARGE_PUBLIC_ASSET_BYTES`. WARN only —
+ * the file works fine, this is a cost/perf nudge toward the hosted-upload path
+ * (see LARGE_PUBLIC_ASSET_FIX for why: no R2 dedup, permanent Gitea growth).
+ */
+function findLargePublicAssets(publicDir, rel) {
+  const out = [];
+  for (const p of walk(publicDir, () => true)) {
+    const size = statSync(p).size;
+    if (size >= LARGE_PUBLIC_ASSET_BYTES) {
+      out.push(mk(WARN, "large-public-asset", rel(p), `${(size / 1024).toFixed(0)}KB`));
+    }
+  }
+  return out;
+}
+
 const escapeRe = (s) => s.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");