@mutagent/cli 0.2.53 → 0.2.55

package/dist/bin/cli.js

@@ -893,6 +893,35 @@ var init_config = __esm(() => {
   CREDENTIALS_FILE = join2(CREDENTIALS_DIR, "credentials.json");
 });
 
+// src/lib/tenancy-error.ts
+function shellQuote(value) {
+  if (/^[A-Za-z0-9_-]+$/.test(value))
+    return value;
+  return `'${value.replace(/'/g, `'\\''`)}'`;
+}
+function workspaceDenied(ctx) {
+  const shown = ctx.workspaceName ?? ctx.workspaceId ?? "workspace";
+  const own = ctx.keyScope === "workspace" ? ctx.keyWorkspace : undefined;
+  if (ctx.workspaceOrigin === "selection" && own && own.id !== ctx.workspaceId) {
+    return new TenancyError(TENANCY_DENIED, `This API key only works in workspace ${own.name}; your saved selection is ${shown}.`, `Run: mutagent workspaces use ${shellQuote(own.name)}`);
+  }
+  if (ctx.workspaceOrigin === "selection") {
+    return new TenancyError(TENANCY_DENIED, `Your saved workspace ${shown} is no longer available to you.`, "Run: mutagent workspaces use <name>");
+  }
+  const where = ctx.organizationName ? ` in ${ctx.organizationName}` : "";
+  return new TenancyError(TENANCY_DENIED, `No workspace "${shown}" among your workspaces${where}.`, "See: mutagent workspaces list");
+}
+var TENANCY_DENIED = "TENANCY_DENIED", TenancyError;
+var init_tenancy_error = __esm(() => {
+  init_errors();
+  TenancyError = class TenancyError extends MutagentError {
+    constructor(code, what, fix) {
+      super(code, `${what} ${fix}`, fix.replace(/^(Run|See|To switch): /, ""));
+      this.name = "TenancyError";
+    }
+  };
+});
+
 // src/lib/organization-scope.ts
 function looksLikeWorkspaceId(value) {
   return UUID_PATTERN.test(value);
@@ -924,14 +953,6 @@ function parseBody(body) {
 function deadKeyError() {
   return new TenancyError("AUTH_EXPIRED", "Your CLI key expired or was revoked.", "Run: mutagent login");
 }
-function workspaceDenied(ctx) {
-  const shown = ctx.workspaceName ?? ctx.workspaceId ?? "workspace";
-  if (ctx.workspaceOrigin === "selection") {
-    return new TenancyError(TENANCY_DENIED, `Your saved workspace ${shown} is no longer available to you.`, "Run: mutagent workspaces use <name>");
-  }
-  const where = ctx.organizationName ? ` in ${ctx.organizationName}` : "";
-  return new TenancyError(TENANCY_DENIED, `No workspace "${shown}" among your workspaces${where}.`, "See: mutagent workspaces list");
-}
 function tenancyFailure(status, body, ctx) {
   const parsed = parseBody(body);
   if (status === 401)
@@ -997,11 +1018,6 @@ function matchesOrganization(value, org) {
     return true;
   return org.name !== undefined && value.toLowerCase() === org.name.toLowerCase();
 }
-function shellQuote(value) {
-  if (/^[A-Za-z0-9_-]+$/.test(value))
-    return value;
-  return `'${value.replace(/'/g, `'\\''`)}'`;
-}
 function orgMismatch(value, org) {
   const shown = org.slug ? `${org.name} (${org.slug})` : org.name;
   return new TenancyError("ORG_MISMATCH", `Your key is for ${shown}.`, `Run: mutagent login --org ${shellQuote(value)}`);
@@ -1148,21 +1164,101 @@ async function findWorkspace(wanted, t) {
   const orgs = await fetchOrganizations(t.apiKey, t.endpoint);
   throw otherOrganizationHint(wanted, t.organization, orgs);
 }
-var TENANCY_DENIED = "TENANCY_DENIED", UUID_PATTERN, TenancyError, ENV_KEY_WORKSPACE_FIX = "Pass --workspace <name|id> or set MUTAGENT_WORKSPACE_ID", orgAssertion, workspaceFlag, keySelfProbes, keyScopeConfirmations;
+var UUID_PATTERN, ENV_KEY_WORKSPACE_FIX = "Pass --workspace <name|id> or set MUTAGENT_WORKSPACE_ID", orgAssertion, workspaceFlag, keySelfProbes, keyScopeConfirmations;
 var init_organization_scope = __esm(() => {
   init_errors();
   init_config();
+  init_tenancy_error();
   UUID_PATTERN = /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i;
-  TenancyError = class TenancyError extends MutagentError {
-    constructor(code, what, fix) {
-      super(code, `${what} ${fix}`, fix.replace(/^(Run|See|To switch): /, ""));
-      this.name = "TenancyError";
-    }
-  };
   keySelfProbes = new Map;
   keyScopeConfirmations = new Map;
 });
 
+// src/lib/key-scope-heal.ts
+function isOrgKeyWithoutWorkspace(status, body) {
+  return status === 400 && body.toLowerCase().includes(ORG_KEY_NEEDS_WORKSPACE);
+}
+function codeOf(body) {
+  try {
+    return JSON.parse(body)?.code;
+  } catch {
+    return;
+  }
+}
+async function readKeySelf(key, fetchImpl) {
+  try {
+    const response = await fetchImpl(`${key.endpoint}/api/api-keys/self`, { headers: { "x-api-key": key.apiKey } });
+    const self = response.ok ? await response.json() : undefined;
+    return self?.scope === "workspace" || self?.scope === "organization" || self?.scope === "user" ? self : undefined;
+  } catch {
+    return;
+  }
+}
+async function explainSelectionDenial(status, body, ctx, key, fetchImpl = fetch) {
+  if (status !== 403 || ctx.workspaceOrigin !== "selection" || ctx.keyScope !== "workspace" || ctx.keyWorkspace)
+    return;
+  if (codeOf(body) !== TENANCY_DENIED)
+    return;
+  const self = await readKeySelf(key, fetchImpl);
+  if (!self)
+    return;
+  ctx.keyScope = self.scope;
+  if (self.scope === "workspace") {
+    ctx.keyWorkspace = self.workspace ?? undefined;
+    return;
+  }
+  if (!envKeyReplacesFile())
+    recordKeyScope(self);
+}
+async function explainThrownDenial(error, ctx, key) {
+  if (ctx === undefined || !(error instanceof Error) || !("statusCode" in error) || typeof error.statusCode !== "number")
+    return;
+  const body = "body" in error && typeof error.body === "string" ? error.body : "";
+  await explainSelectionDenial(error.statusCode, body, ctx, key);
+}
+function sameHeaders(a, b) {
+  const keys = Object.keys(a);
+  return keys.length === Object.keys(b).length && keys.every((k) => a[k] === b[k]);
+}
+async function fetchWithScopeHeal(input, init, target) {
+  const spare = input instanceof Request ? input.clone() : undefined;
+  const response = await (init == null ? fetch(input) : fetch(input, init));
+  if (response.status === 403 && target.tenancy) {
+    const denied = await response.clone().text().catch(() => "");
+    await explainSelectionDenial(403, denied, target.tenancy, target);
+    return response;
+  }
+  if (response.status !== 400)
+    return response;
+  const body = await response.clone().text().catch(() => "");
+  if (!isOrgKeyWithoutWorkspace(response.status, body))
+    return response;
+  const before = target.headers();
+  const self = await confirmKeyScope(target.apiKey, target.endpoint).catch(() => {
+    return;
+  });
+  if (!self)
+    return response;
+  target.adopt(self);
+  const after = target.headers();
+  if (sameHeaders(before, after))
+    return response;
+  if (spare) {
+    const headers = new Headers(spare.headers);
+    for (const [name, value] of Object.entries(after))
+      headers.set(name, value);
+    return fetch(new Request(spare, { headers }));
+  }
+  const headers = { ...init?.headers, ...after };
+  return fetch(input, { ...init, headers });
+}
+var ORG_KEY_NEEDS_WORKSPACE = "x-workspace-id header required";
+var init_key_scope_heal = __esm(() => {
+  init_config();
+  init_organization_scope();
+  init_tenancy_error();
+});
+
 // src/lib/sdk-debug.ts
 function isDebugEnabled(env = process.env) {
   return TRUTHY.has((env.MUTAGENT_DEBUG ?? "").trim().toLowerCase());
@@ -1477,46 +1573,6 @@ function buildCreateProviderBody(data) {
   return body;
 }
 
-// src/lib/key-scope-heal.ts
-function isOrgKeyWithoutWorkspace(status, body) {
-  return status === 400 && body.toLowerCase().includes(ORG_KEY_NEEDS_WORKSPACE);
-}
-function sameHeaders(a, b) {
-  const keys = Object.keys(a);
-  return keys.length === Object.keys(b).length && keys.every((k) => a[k] === b[k]);
-}
-async function fetchWithScopeHeal(input, init, target) {
-  const spare = input instanceof Request ? input.clone() : undefined;
-  const response = await (init == null ? fetch(input) : fetch(input, init));
-  if (response.status !== 400)
-    return response;
-  const body = await response.clone().text().catch(() => "");
-  if (!isOrgKeyWithoutWorkspace(response.status, body))
-    return response;
-  const before = target.headers();
-  const self = await confirmKeyScope(target.apiKey, target.endpoint).catch(() => {
-    return;
-  });
-  if (!self)
-    return response;
-  target.adopt(self);
-  const after = target.headers();
-  if (sameHeaders(before, after))
-    return response;
-  if (spare) {
-    const headers = new Headers(spare.headers);
-    for (const [name, value] of Object.entries(after))
-      headers.set(name, value);
-    return fetch(new Request(spare, { headers }));
-  }
-  const headers = { ...init?.headers, ...after };
-  return fetch(input, { ...init, headers });
-}
-var ORG_KEY_NEEDS_WORKSPACE = "x-workspace-id header required";
-var init_key_scope_heal = __esm(() => {
-  init_organization_scope();
-});
-
 // src/lib/sdk-mappers.ts
 import { LlmProviderType as SDKProviderEnum } from "@mutagent/sdk/models";
 function isProviderType(value) {
@@ -1714,9 +1770,8 @@ class SDKClientWrapper {
       const tenancy = tenancyFailure(response.status, error, this.tenancy);
       if (tenancy)
         throw tenancy;
-      if (response.status === 401) {
+      if (response.status === 401)
         throw new AuthenticationError;
-      }
       if (response.status === 403) {
         throw new ApiError(403, error || "Access denied");
       }
@@ -1887,6 +1942,7 @@ class SDKClientWrapper {
       apiKey: this.apiKey,
       endpoint: this.endpoint,
       headers: () => this.tenancyHeaders(),
+      tenancy: this.tenancy,
       adopt: (self) => {
         this.tenancy.keyScope = self.scope;
         if (!this.workspaceId && self.scope === "workspace" && self.workspace)
@@ -18030,6 +18086,7 @@ import chalk2 from "chalk";
 // src/lib/agent/spec-api.ts
 init_config();
 init_errors();
+init_key_scope_heal();
 init_known_secrets();
 init_organization_scope();
 init_sdk_debug();
@@ -18107,6 +18164,7 @@ async function connectAgentSpec() {
       try {
         return await fn(sdk.managedAgents);
       } catch (error) {
+        await explainThrownDenial(error, tenancy, { apiKey, endpoint: resolved.endpoint });
         throw agentSpecError(error, { endpoint: resolved.endpoint, tenancy, slug });
       }
     }
@@ -27316,6 +27374,7 @@ init_secure_file();
 init_errors();
 init_known_secrets();
 init_organization_scope();
+init_key_scope_heal();
 import { existsSync as existsSync15, readFileSync as readFileSync16, mkdirSync as mkdirSync5, rmSync as rmSync2 } from "fs";
 import { homedir as homedir6 } from "os";
 import { join as join21, dirname as dirname8 } from "path";
@@ -27401,6 +27460,7 @@ async function exchangeToken(input, deps = {}) {
   if (response.status === 403) {
     const context = { ...input.tenancy, workspaceId: input.workspaceId };
     const body = await response.text().catch(() => "");
+    await explainSelectionDenial(403, body, context, input, doFetch);
     throw tenancyFailure(403, body, context) ?? workspaceDenied(context);
   }
   if (!response.ok) {
@@ -31699,6 +31759,7 @@ import chalk42 from "chalk";
 
 // src/lib/gateway-api.ts
 init_config();
+init_key_scope_heal();
 init_known_secrets();
 init_organization_scope();
 class GatewayApiError extends Error {
@@ -31799,6 +31860,7 @@ async function gatewayRequest(path, init = {}) {
   if (!response.ok) {
     const bodyText = await response.text().catch(() => "");
     if (response.status === 403 && tenancyCodeOf(bodyText) === TENANCY_DENIED) {
+      await explainSelectionDenial(403, bodyText, connection.tenancy, connection);
       const denied = tenancyFailure(response.status, bodyText, connection.tenancy);
       if (denied)
         throw denied;
@@ -33666,6 +33728,7 @@ init_known_secrets();
 
 // src/lib/gateway-sdk.ts
 import { HTTPClient as HTTPClient4, Mutagent as Mutagent4 } from "@mutagent/sdk";
+init_key_scope_heal();
 init_organization_scope();
 init_sdk_debug();
 var SDK_TRANSPORT_ERRORS3 = new Set(["ConnectionError", "RequestTimeoutError", "RequestAbortedError", "UnexpectedClientError"]);
@@ -33683,12 +33746,12 @@ function gatewaySdkError(error, connection, what) {
     const body = "body" in error && typeof error.body === "string" ? error.body : "";
     if (status === 401)
       return deadKeyError();
-    const parsed = parseGatewayErrorBody(status, body, "");
-    if (status === 403 && parsed.code === TENANCY_DENIED) {
+    if (status === 403 && tenancyCodeOf(body) === TENANCY_DENIED) {
       const denied = tenancyFailure(status, body, connection.tenancy);
       if (denied)
         return denied;
     }
+    const parsed = parseGatewayErrorBody(status, body, "");
     return new GatewayApiError(status, parsed.code, parsed.reason, parsed.fix);
   }
   return error;
@@ -33714,6 +33777,7 @@ async function callGatewaySdk(what, fn) {
   try {
     return await fn(sdk.gateway, connection);
   } catch (error) {
+    await explainThrownDenial(error, connection.tenancy, connection);
     throw gatewaySdkError(error, connection, what);
   }
 }
@@ -34145,6 +34209,7 @@ import chalk50 from "chalk";
 
 // src/lib/gateway-api-events.ts
 import { GatewayStreamError, streamGatewayUpdates } from "@mutagent/sdk/custom/gateway-stream.js";
+init_key_scope_heal();
 init_known_secrets();
 init_organization_scope();
 function iso3(value) {
@@ -34164,11 +34229,13 @@ async function listNotices(query) {
     return scrubKnownSuccessDeep({ items, nextCursor: page.nextCursor });
   });
 }
-function streamError(error, tenancy) {
+async function streamError(error, connection) {
   if (error.status === 401)
     return deadKeyError();
   if (error.status === 403 && error.code === TENANCY_DENIED) {
-    const denied = tenancyFailure(403, JSON.stringify({ code: error.code }), tenancy);
+    const body = JSON.stringify({ code: error.code });
+    await explainSelectionDenial(403, body, connection.tenancy, connection);
+    const denied = tenancyFailure(403, body, connection.tenancy);
     if (denied)
       return denied;
   }
@@ -34187,7 +34254,7 @@ async function* followGateway(signal) {
     });
   } catch (error) {
     if (error instanceof GatewayStreamError)
-      throw streamError(error, connection.tenancy);
+      throw await streamError(error, connection);
     throw error;
   }
 }
@@ -34728,6 +34795,7 @@ init_output();
 // src/lib/reports-api.ts
 init_config();
 init_errors();
+init_key_scope_heal();
 init_known_secrets();
 init_organization_scope();
 init_sdk_debug();
@@ -34797,6 +34865,10 @@ function reportsError(error, ctx) {
   return new MutagentError("REQUEST_FAILED", error instanceof Error ? error.message : "Request failed", "Run: mutagent reports --help");
 }
 function connection(sdk, ctx) {
+  const explain = async (error) => {
+    if (ctx.apiKey !== undefined)
+      await explainThrownDenial(error, ctx.tenancy, { apiKey: ctx.apiKey, endpoint: ctx.endpoint });
+  };
   return {
     endpoint: ctx.endpoint,
     credential: ctx.credential,
@@ -34805,6 +34877,7 @@ function connection(sdk, ctx) {
       try {
         return await fn(sdk.reports);
       } catch (error) {
+        await explain(error);
         throw reportsError(error, ctx);
       }
     },
@@ -34812,6 +34885,7 @@ function connection(sdk, ctx) {
       try {
         return await fn(sdk);
       } catch (error) {
+        await explain(error);
         throw reportsError(error, ctx);
       }
     }
@@ -34865,6 +34939,7 @@ async function connectReports(opts) {
   return connection(sdk, {
     endpoint: tenancy.endpoint,
     credential: "api-key",
+    apiKey,
     tenancy: {
       keyScope: tenancy.keyScope,
       workspaceId: tenancy.workspaceId,
@@ -36548,6 +36623,7 @@ function fixFor(code, serverFix, ctx) {
 init_config();
 init_errors();
 import { HTTPClient as HTTPClient6, Mutagent as Mutagent6 } from "@mutagent/sdk";
+init_key_scope_heal();
 init_known_secrets();
 init_organization_scope();
 init_sdk_debug();
@@ -36616,6 +36692,7 @@ async function connectIntegrations() {
   const tenancy = await resolveKeyTenancy(apiKey);
   if (tenancy.keyScope !== "workspace" && !tenancy.workspaceId)
     throw noWorkspaceSelected();
+  const key = { apiKey, endpoint: tenancy.endpoint };
   const headers = tenancyHeaders({
     keyScope: tenancy.keyScope,
     workspaceId: tenancy.workspaceId,
@@ -36667,6 +36744,7 @@ async function connectIntegrations() {
     try {
       return await fn(sdk.integrations);
     } catch (error) {
+      await explainThrownDenial(error, tenancyCtx, key);
       throw integrationsError(error, { endpoint: tenancy.endpoint, tenancy: tenancyCtx, call: callCtx });
     }
   }
@@ -38163,4 +38241,4 @@ if (process.env.CLI_VERSION) {
 }
 runCli(process.argv.slice(2), cliVersion);
 
-//# debugId=F12EBD8D0A6ACFED64756E2164756E21
+//# debugId=CAC2930F9F23245664756E2164756E21

package/dist/index.js

@@ -1043,6 +1043,35 @@ var init_key_check = __esm(() => {
   };
 });
 
+// src/lib/tenancy-error.ts
+function shellQuote(value) {
+  if (/^[A-Za-z0-9_-]+$/.test(value))
+    return value;
+  return `'${value.replace(/'/g, `'\\''`)}'`;
+}
+function workspaceDenied(ctx) {
+  const shown = ctx.workspaceName ?? ctx.workspaceId ?? "workspace";
+  const own = ctx.keyScope === "workspace" ? ctx.keyWorkspace : undefined;
+  if (ctx.workspaceOrigin === "selection" && own && own.id !== ctx.workspaceId) {
+    return new TenancyError(TENANCY_DENIED, `This API key only works in workspace ${own.name}; your saved selection is ${shown}.`, `Run: mutagent workspaces use ${shellQuote(own.name)}`);
+  }
+  if (ctx.workspaceOrigin === "selection") {
+    return new TenancyError(TENANCY_DENIED, `Your saved workspace ${shown} is no longer available to you.`, "Run: mutagent workspaces use <name>");
+  }
+  const where = ctx.organizationName ? ` in ${ctx.organizationName}` : "";
+  return new TenancyError(TENANCY_DENIED, `No workspace "${shown}" among your workspaces${where}.`, "See: mutagent workspaces list");
+}
+var TENANCY_DENIED = "TENANCY_DENIED", TenancyError;
+var init_tenancy_error = __esm(() => {
+  init_errors();
+  TenancyError = class TenancyError extends MutagentError {
+    constructor(code, what, fix) {
+      super(code, `${what} ${fix}`, fix.replace(/^(Run|See|To switch): /, ""));
+      this.name = "TenancyError";
+    }
+  };
+});
+
 // src/lib/organization-scope.ts
 function looksLikeWorkspaceId(value) {
   return UUID_PATTERN.test(value);
@@ -1074,14 +1103,6 @@ function parseBody(body) {
 function deadKeyError() {
   return new TenancyError("AUTH_EXPIRED", "Your CLI key expired or was revoked.", "Run: mutagent login");
 }
-function workspaceDenied(ctx) {
-  const shown = ctx.workspaceName ?? ctx.workspaceId ?? "workspace";
-  if (ctx.workspaceOrigin === "selection") {
-    return new TenancyError(TENANCY_DENIED, `Your saved workspace ${shown} is no longer available to you.`, "Run: mutagent workspaces use <name>");
-  }
-  const where = ctx.organizationName ? ` in ${ctx.organizationName}` : "";
-  return new TenancyError(TENANCY_DENIED, `No workspace "${shown}" among your workspaces${where}.`, "See: mutagent workspaces list");
-}
 function tenancyFailure(status, body, ctx) {
   const parsed = parseBody(body);
   if (status === 401)
@@ -1147,11 +1168,6 @@ function matchesOrganization(value, org) {
     return true;
   return org.name !== undefined && value.toLowerCase() === org.name.toLowerCase();
 }
-function shellQuote(value) {
-  if (/^[A-Za-z0-9_-]+$/.test(value))
-    return value;
-  return `'${value.replace(/'/g, `'\\''`)}'`;
-}
 function orgMismatch(value, org) {
   const shown = org.slug ? `${org.name} (${org.slug})` : org.name;
   return new TenancyError("ORG_MISMATCH", `Your key is for ${shown}.`, `Run: mutagent login --org ${shellQuote(value)}`);
@@ -1298,17 +1314,12 @@ async function findWorkspace(wanted, t) {
   const orgs = await fetchOrganizations(t.apiKey, t.endpoint);
   throw otherOrganizationHint(wanted, t.organization, orgs);
 }
-var TENANCY_DENIED = "TENANCY_DENIED", UUID_PATTERN, TenancyError, ENV_KEY_WORKSPACE_FIX = "Pass --workspace <name|id> or set MUTAGENT_WORKSPACE_ID", orgAssertion, workspaceFlag, keySelfProbes, keyScopeConfirmations;
+var UUID_PATTERN, ENV_KEY_WORKSPACE_FIX = "Pass --workspace <name|id> or set MUTAGENT_WORKSPACE_ID", orgAssertion, workspaceFlag, keySelfProbes, keyScopeConfirmations;
 var init_organization_scope = __esm(() => {
   init_errors();
   init_config();
+  init_tenancy_error();
   UUID_PATTERN = /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i;
-  TenancyError = class TenancyError extends MutagentError {
-    constructor(code, what, fix) {
-      super(code, `${what} ${fix}`, fix.replace(/^(Run|See|To switch): /, ""));
-      this.name = "TenancyError";
-    }
-  };
   keySelfProbes = new Map;
   keyScopeConfirmations = new Map;
 });
@@ -1434,6 +1445,44 @@ var init_sdk_debug = __esm(() => {
 function isOrgKeyWithoutWorkspace(status, body) {
   return status === 400 && body.toLowerCase().includes(ORG_KEY_NEEDS_WORKSPACE);
 }
+function codeOf(body) {
+  try {
+    return JSON.parse(body)?.code;
+  } catch {
+    return;
+  }
+}
+async function readKeySelf(key, fetchImpl) {
+  try {
+    const response = await fetchImpl(`${key.endpoint}/api/api-keys/self`, { headers: { "x-api-key": key.apiKey } });
+    const self = response.ok ? await response.json() : undefined;
+    return self?.scope === "workspace" || self?.scope === "organization" || self?.scope === "user" ? self : undefined;
+  } catch {
+    return;
+  }
+}
+async function explainSelectionDenial(status, body, ctx, key, fetchImpl = fetch) {
+  if (status !== 403 || ctx.workspaceOrigin !== "selection" || ctx.keyScope !== "workspace" || ctx.keyWorkspace)
+    return;
+  if (codeOf(body) !== TENANCY_DENIED)
+    return;
+  const self = await readKeySelf(key, fetchImpl);
+  if (!self)
+    return;
+  ctx.keyScope = self.scope;
+  if (self.scope === "workspace") {
+    ctx.keyWorkspace = self.workspace ?? undefined;
+    return;
+  }
+  if (!envKeyReplacesFile())
+    recordKeyScope(self);
+}
+async function explainThrownDenial(error, ctx, key) {
+  if (ctx === undefined || !(error instanceof Error) || !("statusCode" in error) || typeof error.statusCode !== "number")
+    return;
+  const body = "body" in error && typeof error.body === "string" ? error.body : "";
+  await explainSelectionDenial(error.statusCode, body, ctx, key);
+}
 function sameHeaders(a, b) {
   const keys = Object.keys(a);
   return keys.length === Object.keys(b).length && keys.every((k) => a[k] === b[k]);
@@ -1441,6 +1490,11 @@ function sameHeaders(a, b) {
 async function fetchWithScopeHeal(input, init, target) {
   const spare = input instanceof Request ? input.clone() : undefined;
   const response = await (init == null ? fetch(input) : fetch(input, init));
+  if (response.status === 403 && target.tenancy) {
+    const denied = await response.clone().text().catch(() => "");
+    await explainSelectionDenial(403, denied, target.tenancy, target);
+    return response;
+  }
   if (response.status !== 400)
     return response;
   const body = await response.clone().text().catch(() => "");
@@ -1467,7 +1521,9 @@ async function fetchWithScopeHeal(input, init, target) {
 }
 var ORG_KEY_NEEDS_WORKSPACE = "x-workspace-id header required";
 var init_key_scope_heal = __esm(() => {
+  init_config();
   init_organization_scope();
+  init_tenancy_error();
 });
 
 // src/lib/sdk-mappers.ts
@@ -1667,9 +1723,8 @@ class SDKClientWrapper {
       const tenancy = tenancyFailure(response.status, error, this.tenancy);
       if (tenancy)
         throw tenancy;
-      if (response.status === 401) {
+      if (response.status === 401)
         throw new AuthenticationError;
-      }
       if (response.status === 403) {
         throw new ApiError(403, error || "Access denied");
       }
@@ -1840,6 +1895,7 @@ class SDKClientWrapper {
       apiKey: this.apiKey,
       endpoint: this.endpoint,
       headers: () => this.tenancyHeaders(),
+      tenancy: this.tenancy,
       adopt: (self) => {
         this.tenancy.keyScope = self.scope;
         if (!this.workspaceId && self.scope === "workspace" && self.workspace)
@@ -1989,4 +2045,4 @@ export {
   version
 };
 
-//# debugId=CB6D96307760100964756E2164756E21
+//# debugId=C31E7F3B419630CE64756E2164756E21

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@mutagent/cli",
-  "version": "0.2.53",
+  "version": "0.2.55",
   "description": "Bun-native CLI for the MutagenT AI platform - auth, provider config, and lifecycle-tool installer for AI-native workflows",
   "type": "module",
   "bin": {