@mutagent/cli 0.2.52 → 0.2.54

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);
@@ -901,11 +930,6 @@ function tenancyHeaders(t) {
   const headers = {};
   if (!t.workspaceId)
     return headers;
-  if (t.keyScope === "workspace") {
-    if (t.workspaceOrigin === "override")
-      headers["x-workspace-id"] = t.workspaceId;
-    return headers;
-  }
   headers["x-workspace-id"] = t.workspaceId;
   if (t.keyScope === "user" && t.organizationId)
     headers["x-organization-id"] = t.organizationId;
@@ -915,7 +939,6 @@ function configTenancyHeaders(config) {
   return tenancyHeaders({
     keyScope: config.keyScope,
     workspaceId: config.defaultWorkspace,
-    workspaceOrigin: config.workspaceOrigin,
     organizationId: config.defaultOrganization
   });
 }
@@ -930,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)
@@ -1003,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)}`);
@@ -1052,6 +1062,17 @@ ${apiKey}`;
   probe.catch(() => keySelfProbes.delete(cacheKey));
   return probe;
 }
+function confirmKeyScope(apiKey, endpoint) {
+  const cacheKey = `${endpoint}
+${apiKey}`;
+  const done = keyScopeConfirmations.get(cacheKey);
+  if (done)
+    return done;
+  const read = readKeyScope(apiKey, endpoint, !envKeyReplacesFile());
+  keyScopeConfirmations.set(cacheKey, read);
+  keySelfProbes.set(cacheKey, read);
+  return read;
+}
 async function readKeyScope(apiKey, endpoint, fromFile) {
   try {
     const self = await fetchKeySelf(apiKey, endpoint);
@@ -1119,7 +1140,14 @@ async function findWorkspace(wanted, t) {
     if (t.workspaceId && (wanted === t.workspaceId || wanted === t.workspaceName)) {
       return { id: t.workspaceId, name: t.workspaceName ?? t.workspaceId };
     }
-    throw new TenancyError("WORKSPACE_KEY_MISMATCH", `This key only works in ${t.workspaceName ?? t.workspaceId ?? "its own workspace"}.`, "Run: mutagent login (for a key that can switch workspaces)");
+    const self = await confirmKeyScope(t.apiKey, t.endpoint);
+    if (self && self.scope !== "workspace") {
+      return findWorkspace(wanted, { ...t, keyScope: self.scope, organization: self.organization ?? t.organization });
+    }
+    const own = self?.workspace ?? (t.workspaceId ? { id: t.workspaceId, name: t.workspaceName ?? t.workspaceId } : undefined);
+    if (own && (wanted === own.id || wanted === own.name))
+      return { id: own.id, name: own.name };
+    throw new TenancyError("WORKSPACE_KEY_MISMATCH", `This key only works in ${own?.name ?? "its own workspace"}.`, "Run: mutagent login (for a key that can switch workspaces)");
   }
   const rows = await listKeyWorkspaces(t.apiKey, t.endpoint, t);
   const byId = rows.find((w) => w.id === wanted);
@@ -1136,18 +1164,14 @@ 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;
+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/sdk-debug.ts
@@ -1464,6 +1488,85 @@ 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 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);
+}
+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-mappers.ts
 import { LlmProviderType as SDKProviderEnum } from "@mutagent/sdk/models";
 function isProviderType(value) {
@@ -1574,7 +1677,7 @@ class SDKClientWrapper {
       workspaceOrigin: opts.workspaceOrigin ?? (opts.workspaceId ? "selection" : undefined),
       organizationName: opts.organizationName
     };
-    const httpClient = new HTTPClient;
+    const httpClient = new HTTPClient({ fetcher: (input, init) => fetchWithScopeHeal(input, init, this.scopeHealTarget()) });
     httpClient.addHook("beforeRequest", (req) => {
       for (const [name, value] of Object.entries(this.tenancyHeaders()))
         req.headers.set(name, value);
@@ -1644,7 +1747,7 @@ class SDKClientWrapper {
     }
     let response;
     try {
-      response = await fetch(`${this.endpoint}${path}`, {
+      response = await fetchWithScopeHeal(`${this.endpoint}${path}`, {
         ...options,
         headers: {
           "x-api-key": this.apiKey,
@@ -1652,7 +1755,7 @@ class SDKClientWrapper {
           ...this.tenancyHeaders(),
           ...extraHeaders
         }
-      });
+      }, this.scopeHealTarget());
     } catch {
       throw unreachableServerError(this.endpoint);
     }
@@ -1661,9 +1764,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");
       }
@@ -1826,10 +1928,24 @@ class SDKClientWrapper {
     return tenancyHeaders({
       keyScope: this.tenancy.keyScope,
       workspaceId: this.workspaceId,
-      workspaceOrigin: this.tenancy.workspaceOrigin,
       organizationId: this.organizationId
     });
   }
+  scopeHealTarget() {
+    return {
+      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)
+          this.workspaceId = self.workspace.id;
+        if (self.scope === "user" && self.organization)
+          this.organizationId ??= self.organization.id;
+      }
+    };
+  }
   requireSelectedWorkspace() {
     if (!this.workspaceId)
       throw noWorkspaceSelected();
@@ -1944,6 +2060,7 @@ var init_sdk_client = __esm(() => {
   init_key_check();
   init_organization_scope();
   init_sdk_debug();
+  init_key_scope_heal();
   init_known_secrets();
   init_sdk_mappers();
   init_organization_scope();
@@ -2140,7 +2257,8 @@ async function createAgentDeploymentAPI() {
   const workspaceId = context.requireSelectedWorkspace();
   const httpClient = new HTTPClient2;
   httpClient.addHook("beforeRequest", (request) => {
-    request.headers.set("x-workspace-id", workspaceId);
+    for (const [name, value] of Object.entries(tenancyHeaders({ workspaceId })))
+      request.headers.set(name, value);
     return request;
   });
   const sdk = new Mutagent2({ security: { apiKey }, serverURL: endpoint, httpClient, timeoutMs: Math.max(config.timeout, 120000), retryConfig: { strategy: "none" } });
@@ -18011,7 +18129,6 @@ async function connectAgentSpec() {
   const headers = tenancyHeaders({
     keyScope: resolved.keyScope,
     workspaceId: resolved.workspaceId,
-    workspaceOrigin: resolved.workspaceOrigin,
     organizationId: resolved.organization?.id
   });
   const httpClient = new HTTPClient3;
@@ -21219,7 +21336,6 @@ the answer is verified, not read from local config.
       const headers = tenancyHeaders({
         keyScope: tenancy.keyScope,
         workspaceId: tenancy.workspaceId,
-        workspaceOrigin: tenancy.workspaceOrigin,
         organizationId: tenancy.organization?.id
       });
       const self = await fetchKeySelf(apiKey, tenancy.endpoint, { headers, ctx: tenancy });
@@ -27250,6 +27366,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";
@@ -27335,6 +27452,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) {
@@ -27422,7 +27540,6 @@ async function resolveConnection() {
   const headers = tenancyHeaders({
     keyScope: tenancy.keyScope,
     workspaceId,
-    workspaceOrigin: tenancy.workspaceOrigin,
     organizationId: tenancy.organization?.id
   });
   return {
@@ -31702,7 +31819,7 @@ async function resolveGatewayConnection() {
   const headers = {
     "x-api-key": apiKey,
     "Content-Type": "application/json",
-    "x-workspace-id": workspaceId
+    ...tenancyHeaders({ workspaceId })
   };
   return {
     endpoint: tenancy.endpoint,
@@ -34782,7 +34899,6 @@ async function connectReports(opts) {
   const headers = tenancyHeaders({
     keyScope: tenancy.keyScope,
     workspaceId: tenancy.workspaceId,
-    workspaceOrigin: tenancy.workspaceOrigin,
     organizationId: tenancy.organization?.id
   });
   const httpClient = new HTTPClient5;
@@ -36555,7 +36671,6 @@ async function connectIntegrations() {
   const headers = tenancyHeaders({
     keyScope: tenancy.keyScope,
     workspaceId: tenancy.workspaceId,
-    workspaceOrigin: tenancy.workspaceOrigin,
     organizationId: tenancy.organization?.id
   });
   const tenancyCtx = {
@@ -38100,4 +38215,4 @@ if (process.env.CLI_VERSION) {
 }
 runCli(process.argv.slice(2), cliVersion);
 
-//# debugId=7181C3F925DEA1DA64756E2164756E21
+//# debugId=C914B921636AC8AB64756E2164756E21

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);
@@ -1051,11 +1080,6 @@ function tenancyHeaders(t) {
   const headers = {};
   if (!t.workspaceId)
     return headers;
-  if (t.keyScope === "workspace") {
-    if (t.workspaceOrigin === "override")
-      headers["x-workspace-id"] = t.workspaceId;
-    return headers;
-  }
   headers["x-workspace-id"] = t.workspaceId;
   if (t.keyScope === "user" && t.organizationId)
     headers["x-organization-id"] = t.organizationId;
@@ -1065,7 +1089,6 @@ function configTenancyHeaders(config) {
   return tenancyHeaders({
     keyScope: config.keyScope,
     workspaceId: config.defaultWorkspace,
-    workspaceOrigin: config.workspaceOrigin,
     organizationId: config.defaultOrganization
   });
 }
@@ -1080,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)
@@ -1153,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)}`);
@@ -1202,6 +1212,17 @@ ${apiKey}`;
   probe.catch(() => keySelfProbes.delete(cacheKey));
   return probe;
 }
+function confirmKeyScope(apiKey, endpoint) {
+  const cacheKey = `${endpoint}
+${apiKey}`;
+  const done = keyScopeConfirmations.get(cacheKey);
+  if (done)
+    return done;
+  const read = readKeyScope(apiKey, endpoint, !envKeyReplacesFile());
+  keyScopeConfirmations.set(cacheKey, read);
+  keySelfProbes.set(cacheKey, read);
+  return read;
+}
 async function readKeyScope(apiKey, endpoint, fromFile) {
   try {
     const self = await fetchKeySelf(apiKey, endpoint);
@@ -1269,7 +1290,14 @@ async function findWorkspace(wanted, t) {
     if (t.workspaceId && (wanted === t.workspaceId || wanted === t.workspaceName)) {
       return { id: t.workspaceId, name: t.workspaceName ?? t.workspaceId };
     }
-    throw new TenancyError("WORKSPACE_KEY_MISMATCH", `This key only works in ${t.workspaceName ?? t.workspaceId ?? "its own workspace"}.`, "Run: mutagent login (for a key that can switch workspaces)");
+    const self = await confirmKeyScope(t.apiKey, t.endpoint);
+    if (self && self.scope !== "workspace") {
+      return findWorkspace(wanted, { ...t, keyScope: self.scope, organization: self.organization ?? t.organization });
+    }
+    const own = self?.workspace ?? (t.workspaceId ? { id: t.workspaceId, name: t.workspaceName ?? t.workspaceId } : undefined);
+    if (own && (wanted === own.id || wanted === own.name))
+      return { id: own.id, name: own.name };
+    throw new TenancyError("WORKSPACE_KEY_MISMATCH", `This key only works in ${own?.name ?? "its own workspace"}.`, "Run: mutagent login (for a key that can switch workspaces)");
   }
   const rows = await listKeyWorkspaces(t.apiKey, t.endpoint, t);
   const byId = rows.find((w) => w.id === wanted);
@@ -1286,18 +1314,14 @@ 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;
+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/provider-request.ts
@@ -1417,6 +1441,85 @@ var init_sdk_debug = __esm(() => {
   };
 });
 
+// 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);
+}
+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-mappers.ts
 import { LlmProviderType as SDKProviderEnum } from "@mutagent/sdk/models";
 function isProviderType(value) {
@@ -1527,7 +1630,7 @@ class SDKClientWrapper {
       workspaceOrigin: opts.workspaceOrigin ?? (opts.workspaceId ? "selection" : undefined),
       organizationName: opts.organizationName
     };
-    const httpClient = new HTTPClient;
+    const httpClient = new HTTPClient({ fetcher: (input, init) => fetchWithScopeHeal(input, init, this.scopeHealTarget()) });
     httpClient.addHook("beforeRequest", (req) => {
       for (const [name, value] of Object.entries(this.tenancyHeaders()))
         req.headers.set(name, value);
@@ -1597,7 +1700,7 @@ class SDKClientWrapper {
     }
     let response;
     try {
-      response = await fetch(`${this.endpoint}${path}`, {
+      response = await fetchWithScopeHeal(`${this.endpoint}${path}`, {
         ...options,
         headers: {
           "x-api-key": this.apiKey,
@@ -1605,7 +1708,7 @@ class SDKClientWrapper {
           ...this.tenancyHeaders(),
           ...extraHeaders
         }
-      });
+      }, this.scopeHealTarget());
     } catch {
       throw unreachableServerError(this.endpoint);
     }
@@ -1614,9 +1717,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");
       }
@@ -1779,10 +1881,24 @@ class SDKClientWrapper {
     return tenancyHeaders({
       keyScope: this.tenancy.keyScope,
       workspaceId: this.workspaceId,
-      workspaceOrigin: this.tenancy.workspaceOrigin,
       organizationId: this.organizationId
     });
   }
+  scopeHealTarget() {
+    return {
+      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)
+          this.workspaceId = self.workspace.id;
+        if (self.scope === "user" && self.organization)
+          this.organizationId ??= self.organization.id;
+      }
+    };
+  }
   requireSelectedWorkspace() {
     if (!this.workspaceId)
       throw noWorkspaceSelected();
@@ -1897,6 +2013,7 @@ var init_sdk_client = __esm(() => {
   init_key_check();
   init_organization_scope();
   init_sdk_debug();
+  init_key_scope_heal();
   init_known_secrets();
   init_sdk_mappers();
   init_organization_scope();
@@ -1922,4 +2039,4 @@ export {
   version
 };
 
-//# debugId=4CBE15031C5FFF4664756E2164756E21
+//# debugId=B6CD43FAA918848864756E2164756E21

package/package.json

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