@agent-native/core 0.132.1 → 0.133.0

package/corpus/core/src/agent/run-manager.ts

@@ -4,6 +4,11 @@ import {
   LLM_MISSING_CREDENTIALS_ERROR_CODE,
   LLM_MISSING_CREDENTIALS_MESSAGE,
 } from "./engine/credential-errors.js";
+import {
+  classifyTerminalErrorCode,
+  describeErrorWithCauses,
+  isProviderConnectionError,
+} from "./engine/error-detail.js";
 import { EngineError } from "./engine/types.js";
 import {
   insertRun,
@@ -341,23 +346,16 @@ function getRunErrorMessage(err: unknown): string {
   return "Unknown error";
 }
 
-function isProviderConnectionErrorMessage(message: string): boolean {
-  const normalized = message.trim().toLowerCase();
-  return (
-    normalized === "connection error." ||
-    normalized.includes("cannot connect to api:")
-  );
-}
-
 function getRunErrorCode(err: unknown): string | undefined {
   if (err instanceof EngineError) {
     if (err.errorCode) return err.errorCode;
     if (err.statusCode === 429) return PROVIDER_RATE_LIMITED_ERROR_CODE;
   }
-  if (err instanceof Error && isProviderConnectionErrorMessage(err.message)) {
-    return PROVIDER_NETWORK_ERROR_CODE;
-  }
-  return undefined;
+  if (isProviderConnectionError(err)) return PROVIDER_NETWORK_ERROR_CODE;
+  // The code rides the error EVENT to the client, which decides recovery from
+  // it — so an uncoded transport failure has to be classified here too, not
+  // only when the run row is persisted.
+  return classifyTerminalErrorCode(describeErrorWithCauses(err));
 }
 
 function getEngineRunErrorDetails(err: EngineError): string | undefined {
@@ -376,7 +374,7 @@ function shouldCaptureRunError(err: unknown): boolean {
   }
   if (!(err instanceof Error)) return true;
   if (/^40[13] status code\b/i.test(err.message)) return false;
-  if (isProviderConnectionErrorMessage(err.message)) return false;
+  if (isProviderConnectionError(err)) return false;
   if (!errorCode) return true;
   const normalizedCode = errorCode.toLowerCase();
   return (
@@ -984,6 +982,13 @@ export function startRun(
   // false-stale-reap zombie scenario where the reaper flipped the row while
   // this isolate was briefly unable to heartbeat (DB latency / GC pause).
   let lastAbortCheck = Date.now() - 3000;
+  // A read failure here used to be indistinguishable from "not aborted" —
+  // exactly the coerced-to-false pattern that lets a real Stop go unseen for
+  // the rest of the run. Count consecutive failures like the heartbeat-write
+  // handler above; past the same threshold, fail closed (self-abort with a
+  // reason outside TURN_ENDING_ABORT_REASONS/RECOVERABLE_ABORT_REASONS, so it
+  // surfaces as a typed error) instead of silently retrying forever.
+  let consecutiveAbortCheckFailures = 0;
   const checkSqlAbort = () => {
     const now = Date.now();
     if (now - lastAbortCheck < 3000) return;
@@ -1004,7 +1009,26 @@ export function startRun(
           }
         }
       })
-      .catch(() => {});
+      .then(() => {
+        consecutiveAbortCheckFailures = 0;
+      })
+      .catch((error) => {
+        consecutiveAbortCheckFailures += 1;
+        if (consecutiveAbortCheckFailures >= 3) {
+          captureError(error, {
+            route: "/_agent-native/agent-chat",
+            tags: {
+              source: "agent-run-manager",
+              phase: "abort-check",
+              consecutiveFailures: String(consecutiveAbortCheckFailures),
+            },
+            extra: { runId, threadId },
+          });
+          if (!abort.signal.aborted) {
+            abortInMemoryRun(run, "abort_check_unavailable");
+          }
+        }
+      });
   };
 
   // Heartbeat: bump heartbeat_at every 1.5s so watchers can detect a dead
@@ -1456,6 +1480,11 @@ export function startRun(
               ? completionError.message
               : String(completionError));
         }
+        // An engine that emitted an error event without a code has NOT told us
+        // the failure is unclassifiable — it told us nothing. Recover the code
+        // from the message before falling back to "unknown", which the client
+        // reads as "do not attempt recovery".
+        errorCode ??= classifyTerminalErrorCode(errorDetail);
         runTerminalErrorCode = errorCode ?? "unknown";
         runTerminalErrorDetail = errorDetail;
         await setRunError(runId, errorCode ?? "unknown", errorDetail);

package/corpus/core/src/agent/run-store.ts

@@ -946,6 +946,16 @@ export interface UnclaimedBackgroundRunRow {
    *  pre-inserted — independent of any liveness bump a redispatch attempt
    *  makes along the way. */
   startedAt: number;
+  /**
+   * Whether the row still carries the `dispatch_payload` a redispatched worker
+   * would rehydrate its request body from. Eligibility for this sweep does NOT
+   * imply it: a background row can reach the grace window having never had a
+   * payload at all. Redispatching one of those asserts `payloadRef: true` to a
+   * worker that then cannot rehydrate, so it kills the run as
+   * `dispatch_payload_missing` — a reason that reads like data loss for what is
+   * really an un-redispatchable handoff.
+   */
+  hasDispatchPayload: boolean;
 }
 
 /**
@@ -965,7 +975,10 @@ export async function listUnclaimedBackgroundRunRows(): Promise<
   const { rows } = await client.execute({
     // CAST keeps the ms-epoch param 64-bit on Postgres (see
     // backgroundAwareStaleCutoffSql for the int4-inference failure mode).
-    sql: `SELECT id, started_at FROM agent_runs
+    // Report payload presence rather than filtering on it: a payload-less row
+    // must still be VISIBLE to the sweep so the slow pass can reap it. Filtering
+    // it out here would leave it `running` forever.
+    sql: `SELECT id, started_at, (dispatch_payload IS NOT NULL) AS has_dispatch_payload FROM agent_runs
           WHERE status = 'running'
             AND dispatch_mode = 'background'
             AND COALESCE(heartbeat_at, started_at) < (CAST(? AS BIGINT) - ${UNCLAIMED_BACKGROUND_RUN_GRACE_MS})`,
@@ -975,11 +988,15 @@ export async function listUnclaimedBackgroundRunRows(): Promise<
   for (const row of rows ?? []) {
     const id = (row as { id?: unknown }).id;
     const startedAt = (row as { started_at?: unknown }).started_at;
+    const hasPayload = (row as { has_dispatch_payload?: unknown })
+      .has_dispatch_payload;
     if (typeof id === "string" && id) {
       result.push({
         id,
         startedAt:
           typeof startedAt === "number" ? startedAt : Number(startedAt) || 0,
+        // SQLite returns 1/0 where Postgres returns a boolean.
+        hasDispatchPayload: hasPayload === true || hasPayload === 1,
       });
     }
   }
@@ -1147,10 +1164,20 @@ export async function setRunTerminalReason(
     await ensureRunTables();
     const client = getDbExec();
     const reason = terminalReason.slice(0, 200);
+    // Write-once for a row that is already terminal. Three writers in three
+    // isolates race on this column — the mid-run checkpoint, the run-manager's
+    // finalization, and the background worker's failure path — with no ordering
+    // between them, and last-writer-wins let a late checkpoint relabel a row
+    // another isolate had already finalized. That produced impossible rows
+    // (status='errored' carrying a continuation reason, no error_code, no
+    // terminal event) and misattributed 130 production runs to a failure mode
+    // they never hit. A row still `running` has no honest reason yet, so it
+    // stays writable; once one is recorded on a terminal row, it stands.
+    const guard = `AND (status = 'running' OR terminal_reason IS NULL OR terminal_reason = '')`;
     await client.execute({
       sql: isContinuationTerminalReason(reason)
-        ? `UPDATE agent_runs SET terminal_reason = ?, status = CASE WHEN status = 'completed' THEN 'truncated' ELSE status END WHERE id = ?`
-        : `UPDATE agent_runs SET terminal_reason = ? WHERE id = ?`,
+        ? `UPDATE agent_runs SET terminal_reason = ?, status = CASE WHEN status = 'completed' THEN 'truncated' ELSE status END WHERE id = ? ${guard}`
+        : `UPDATE agent_runs SET terminal_reason = ? WHERE id = ? ${guard}`,
       args: [reason, runId],
     });
   } catch {

package/corpus/core/src/agent/thread-data-builder.ts

@@ -1,4 +1,8 @@
 import type { ActionChatUIConfig } from "../action-ui.js";
+import {
+  formatChatErrorText,
+  normalizeChatError,
+} from "../client/error-format.js";
 import {
   isCredentialGapCodeAgentEvent,
   normalizeCodeAgentTranscript,
@@ -140,12 +144,29 @@ export function buildAssistantMessage(
     }
   };
 
+  // Index of the last event that is not a `clear`. Everything after it is a
+  // trailing run of clears with no successor chunk to re-emit what they wipe.
+  let lastNonClearIndex = events.length - 1;
+  while (
+    lastNonClearIndex >= 0 &&
+    events[lastNonClearIndex]?.event.type === "clear"
+  ) {
+    lastNonClearIndex -= 1;
+  }
+
   for (const [index, { event }] of events.entries()) {
     if (event.type === "clear") {
       // A live stream always follows `clear` with the chunk that re-emits the
       // wiped content. A rebuild has no successor, so applying a TRAILING
       // clear can only destroy the transcript permanently.
-      if (index === events.length - 1) continue;
+      //
+      // The whole trailing RUN has to be skipped, not just the final element:
+      // each failed engine attempt emits one `clear`, so three failed attempts
+      // in a row is the common shape, and skipping only the last still applied
+      // the other two. When the run made no tool calls that emptied `content`
+      // entirely and this builder returned null — the user's message was left
+      // with no assistant reply at all.
+      if (index > lastNonClearIndex) continue;
       clearAssistantDraftContent(content);
       continue;
     }
@@ -248,13 +269,24 @@ export function buildAssistantMessage(
       if (event.errorCode === "run_timeout" && event.recoverable) {
         continue;
       }
+      // Mirror the live client (client/sse-event-processor.ts): route the raw
+      // provider/engine string through the same friendly-copy layer before it
+      // ever becomes persisted chat text, and keep the raw text only in
+      // `details`. Without this, a rebuild (background run, reconnect, poller,
+      // webhook turn) dumps whatever the provider sent — a JSON error body, an
+      // SSL handshake failure — straight into the user-visible transcript.
+      const normalized = normalizeChatError(event.error, event.errorCode);
       runError = {
-        message: event.error,
+        message: normalized.message,
         ...(event.errorCode ? { errorCode: event.errorCode } : {}),
-        ...(event.details ? { details: event.details } : {}),
+        ...((event.details ?? normalized.details)
+          ? { details: event.details ?? normalized.details }
+          : {}),
         ...(event.recoverable ? { recoverable: event.recoverable } : {}),
       };
-      appendText(`${content.length > 0 ? "\n\n" : ""}Error: ${event.error}`);
+      appendText(
+        `${content.length > 0 ? "\n\n" : ""}${formatChatErrorText(event.error, event.upgradeUrl, event.errorCode)}`,
+      );
       continue;
     }
 

package/corpus/core/src/chat-threads/store.ts

@@ -766,6 +766,48 @@ export async function searchThreads(
     .filter((r): r is ChatThreadSummary => r !== null);
 }
 
+/**
+ * Scope a thread should carry after a run inside a resource: adopt when it has
+ * none, otherwise keep what it has. An unscoped thread reads as general, and a
+ * general chat renders inside every resource — so never retag, never clear.
+ */
+export function resolveRunThreadScope(
+  existing: ChatThreadScope | null,
+  incoming: ChatThreadScope | null | undefined,
+): ChatThreadScope | null {
+  if (existing) return existing;
+  return incoming ?? null;
+}
+
+/**
+ * Claim an unscoped thread for `scope`, returning the scope it actually ends up
+ * with. `withThreadDataLock` only serializes one process, so two workers can
+ * both read the same unscoped row; the `scope_type IS NULL` guard makes the
+ * first writer win and the loser reports the winner instead of retagging.
+ */
+export async function adoptThreadScopeIfUnscoped(
+  id: string,
+  scope: ChatThreadScope,
+): Promise<ChatThreadScope | null> {
+  await ensureTable();
+  const client = getDbExec();
+  const result = await client.execute({
+    sql: `UPDATE chat_threads SET scope_type = ?, scope_id = ?, scope_label = ?, updated_at = ? WHERE id = ? AND scope_type IS NULL`,
+    args: [
+      scope.type,
+      scope.id,
+      scope.label ?? null,
+      Math.max(Date.now(), 1),
+      id,
+    ],
+  });
+  if (result.rowsAffected > 0) {
+    emitChatThreadChange(id);
+    return scope;
+  }
+  return (await getThread(id))?.scope ?? null;
+}
+
 /**
  * Detach or rebind a chat's scope. Used by the UI's "Detach from <resource>"
  * action and by templates that need to retag a chat after a rename. Pass

package/corpus/core/src/cli/templates-meta.ts

@@ -254,6 +254,19 @@ export const TEMPLATES: TemplateMeta[] = [
     hidden: true,
     defaultMode: "dev",
   },
+  {
+    name: "factory",
+    label: "Factory",
+    hint: "Build agent factories with gates you control",
+    icon: "Users",
+    color: "#7C3AED",
+    colorRgb: "124 58 237",
+    devPort: 8108,
+    prodUrl: "https://agent-native-factory.netlify.app",
+    hidden: true,
+    defaultMode: "dev",
+    core: false,
+  },
 ];
 
 /** Return templates visible in user-facing pickers (excludes hidden). */

package/corpus/core/src/cli/workspace-dev.ts

@@ -712,6 +712,7 @@ export async function runWorkspaceDev(
         name: workspaceApp.name,
         description: workspaceApp.description,
         path: `/${workspaceApp.id}`,
+        port: workspaceApp.port,
         audience: workspaceApp.audience,
         publicPaths: workspaceApp.publicPaths,
         protectedPaths: workspaceApp.protectedPaths,

package/corpus/core/src/client/error-format.ts

@@ -95,6 +95,7 @@ function isProviderAuthenticationError(
     /\b(?:http\s*)?401\b.*\b(?:status|unauthorized|authentication|auth|no body)\b/i.test(
       text,
     ) ||
+    lower.includes("missing authentication header") ||
     lower.includes("invalid x-api-key") ||
     lower.includes("invalid api key") ||
     lower.includes("incorrect api key") ||
@@ -141,6 +142,17 @@ export function normalizeChatError(
     };
   }
 
+  // A model/parameter combination this provider will never accept. Retrying is
+  // pointless and the raw sentence names an API surface the reader has no way
+  // to act on, so say what they can actually change.
+  if (code === "provider_config_error") {
+    return {
+      message:
+        "This model can't use tools with the current settings. Switch models in Settings, then retry.",
+      details: text,
+    };
+  }
+
   if (isProviderRateLimit(text, errorCode)) {
     return {
       message:

package/corpus/core/src/client/use-chat-threads.ts

@@ -91,6 +91,25 @@ async function fetchThreadListPage(
   });
 }
 
+/**
+ * Look up one thread the list page did not carry. Distinguishes the three states
+ * the caller must not collapse: the thread (found), `null` (the server denies it
+ * exists), and `undefined` (unreachable — nothing was learned).
+ */
+async function fetchThreadById(
+  apiUrl: string,
+  id: string,
+): Promise<ChatThreadSummary | null | undefined> {
+  try {
+    const res = await fetch(`${apiUrl}/threads/${encodeURIComponent(id)}`);
+    if (res.status === 404) return null;
+    if (!res.ok) return undefined;
+    return (await res.json()) as ChatThreadSummary;
+  } catch {
+    return undefined;
+  }
+}
+
 function emitThreadsUpdated() {
   if (typeof window === "undefined") return;
   window.dispatchEvent(new CustomEvent(THREADS_UPDATED_EVENT));
@@ -411,6 +430,17 @@ export function useChatThreads(
       } catch {
         nextActiveThreadId = null;
       }
+      // Only a known mismatch disqualifies the pointer — an unresolved scope
+      // must not be read as "belongs here".
+      if (nextActiveThreadId) {
+        const savedScope = readKnownThreadScope(nextActiveThreadId);
+        if (
+          savedScope !== undefined &&
+          !threadCanStayVisibleInScope(savedScope, scopeRef.current)
+        ) {
+          nextActiveThreadId = null;
+        }
+      }
       if (!nextActiveThreadId && autoCreate) {
         nextActiveThreadId = createLocalThreadId();
         newlyCreatedRef.current.add(nextActiveThreadId);
@@ -583,7 +613,7 @@ export function useChatThreads(
 
     (async () => {
       const loadedThreads = await fetchThreads();
-      const savedId = activeThreadIdRef.current;
+      const restoredId = activeThreadIdRef.current;
       if (loadedThreads === undefined) {
         // Thread-list fetch failed. Do not reclassify a saved id as a new
         // optimistic tab; AssistantChat should still get a chance to restore
@@ -591,8 +621,40 @@ export function useChatThreads(
         setIsLoading(false);
         return;
       }
+      // Exempts route-owned threads (the URL names what the user asked for) and
+      // ids this client generated, which have never reached the server.
+      const lookupRestored = Boolean(
+        restoredId &&
+        !routeControlsActiveThread &&
+        !newlyCreatedRef.current.has(restoredId),
+      );
+      const restoredOnPage = restoredId
+        ? loadedThreads.find((t) => t.id === restoredId)
+        : undefined;
+      // One page, so absence from it is not absence from the server — this is what
+      // separates an older real thread from the ghost tab reclassified below.
+      const restoredThread =
+        lookupRestored && !restoredOnPage
+          ? await fetchThreadById(apiUrl, restoredId!)
+          : restoredOnPage;
+      if (restoredThread === undefined && lookupRestored && !restoredOnPage) {
+        // Lookup unreachable. Reclassifying now would stamp this thread with the
+        // current scope on a guess; leave it untouched for the next mount.
+        setIsLoading(false);
+        return;
+      }
+      const restoredBelongsElsewhere = Boolean(
+        restoredThread &&
+        !threadCanStayVisibleInScope(
+          restoredThread.scope ?? null,
+          scopeRef.current,
+        ),
+      );
+      if (restoredBelongsElsewhere) setActiveThreadId(null);
+      const savedId = restoredBelongsElsewhere ? null : restoredId;
       const loadedHasSavedId = Boolean(
-        savedId && loadedThreads.some((t) => t.id === savedId),
+        savedId &&
+        (restoredThread || loadedThreads.some((t) => t.id === savedId)),
       );
       const savedIdCameFromRoute =
         Boolean(savedId) &&
@@ -646,6 +708,7 @@ export function useChatThreads(
       setIsLoading(false);
     })();
   }, [
+    apiUrl,
     fetchThreads,
     addOptimisticThread,
     autoCreate,
@@ -948,12 +1011,9 @@ export function useChatThreads(
     [apiUrl, clearUserRenamedThread, createThread],
   );
 
-  // Ref to look up the latest scope of a known thread inside
-  // saveThreadData without making the callback re-create on every
-  // setThreads. The thread's scope is owned by createThread /
-  // detachThread / fetchThreads — saveThreadData just mirrors it on
-  // every save so the server eventually catches up after
-  // persistSubmittedUserMessage creates the row sans scope.
+  // Reads scope through refs so this callback survives every setThreads. Scope
+  // rides only on creation: a periodic save must never move an existing thread
+  // between resources, however stale this client's guess is.
   const saveThreadData = useCallback(
     async (
       id: string,
@@ -968,7 +1028,7 @@ export function useChatThreads(
       try {
         const { titleSource, ...threadDataPayload } = data;
         const localThread = threadsRef.current.find((t) => t.id === id);
-        const localScope = localThread?.scope ?? null;
+        const knownScope = readKnownThreadScope(id) ?? null;
         const preserveUserTitle = userRenamedThreadIdsRef.current.has(id);
         const title = nextThreadTitle(
           localThread?.title,
@@ -977,11 +1037,7 @@ export function useChatThreads(
           titleSource,
           { preserveUserTitle },
         );
-        const payload = {
-          ...threadDataPayload,
-          title,
-          scope: localScope,
-        };
+        const payload = { ...threadDataPayload, title };
         let response = await fetch(
           `${apiUrl}/threads/${encodeURIComponent(id)}`,
           {
@@ -997,7 +1053,11 @@ export function useChatThreads(
           const created = await fetch(`${apiUrl}/threads`, {
             method: "POST",
             headers: { "Content-Type": "application/json" },
-            body: JSON.stringify({ id, title, scope: localScope }),
+            body: JSON.stringify({
+              id,
+              title,
+              ...(knownScope ? { scope: knownScope } : {}),
+            }),
           });
           if (!created.ok) return;
           response = await fetch(
@@ -1059,7 +1119,7 @@ export function useChatThreads(
         });
       } catch {}
     },
-    [apiUrl],
+    [apiUrl, readKnownThreadScope],
   );
 
   const generateTitle = useCallback(

package/corpus/core/src/credentials/index.ts

@@ -5,6 +5,7 @@ import {
   isEncryptedSecretValue,
 } from "../secrets/crypto.js";
 import { readAppSecret, type SecretRef } from "../secrets/storage.js";
+import { assertCredentialStoreReadable } from "../server/credential-provider.js";
 import { getSetting, putSetting, deleteSetting } from "../settings/store.js";
 
 const SETTING_PREFIX = "credential:";
@@ -76,6 +77,33 @@ export async function resolveCredentialForScope(
   return readCredentialSetting(userCredentialSettingKey(ctx.userEmail, key));
 }
 
+/**
+ * `ctx.orgId` when the caller supplied one, otherwise the org resolved from
+ * `ctx.userEmail`'s membership. Interactive requests always supply `orgId`
+ * (session/`getOrgContext` backfill it); CLI runs, cron jobs, and any other
+ * caller built straight from `getCredentialContext()` outside a request event
+ * do not, and previously fell through as "no active org" — invisibly skipping
+ * every org-scoped credential a signed-in session could see. Mirrors the
+ * fallback already proven in `resolveSecretDetailed`
+ * (server/credential-provider.ts).
+ */
+async function resolveEffectiveOrgId(
+  ctx: CredentialContext,
+): Promise<{ orgId: string | null; lookupFailed: boolean; cause?: unknown }> {
+  if (ctx.orgId) return { orgId: ctx.orgId, lookupFailed: false };
+  try {
+    const { resolveOrgIdForEmail } = await import("../org/context.js");
+    return {
+      orgId: await resolveOrgIdForEmail(ctx.userEmail),
+      lookupFailed: false,
+    };
+  } catch (cause) {
+    // Membership was unreadable, not merely absent — must not collapse to
+    // "caller has no org", which would silently hide every org-scoped row.
+    return { orgId: null, lookupFailed: true, cause };
+  }
+}
+
 /**
  * Resolve a credential across the encrypted app_secrets store and the legacy
  * settings-backed credential store. User overrides win, followed by the
@@ -92,7 +120,12 @@ export async function resolveCredentialForScope(
  *   5. org-scoped legacy settings credential
  *   6. solo workspace-scoped app_secrets (`solo:<email>`)
  *
- * Steps 3-5 are skipped without an active org.
+ * Steps 3-5 use `ctx.orgId` when given, else the org resolved from
+ * `ctx.userEmail` (see `resolveEffectiveOrgId`), and are skipped only when the
+ * caller truly has no org. A membership lookup that could not be read throws
+ * `CredentialStoreUnavailableError` instead of silently reporting the
+ * credential as unset — "the store didn't answer" and "nothing is saved" are
+ * different outcomes callers must not conflate.
  */
 export async function resolveCredential(
   key: string,
@@ -109,19 +142,20 @@ export async function resolveCredential(
   });
   if (userSetting) return userSetting;
 
-  if (ctx.orgId) {
-    const orgSecret = await readScopedAppSecret(key, "org", ctx.orgId);
+  const orgLookup = await resolveEffectiveOrgId(ctx);
+  assertCredentialStoreReadable(orgLookup);
+  const { orgId } = orgLookup;
+
+  if (orgId) {
+    const orgSecret = await readScopedAppSecret(key, "org", orgId);
     if (orgSecret) return orgSecret;
 
-    const workspaceSecret = await readScopedAppSecret(
-      key,
-      "workspace",
-      ctx.orgId,
-    );
+    const workspaceSecret = await readScopedAppSecret(key, "workspace", orgId);
     if (workspaceSecret) return workspaceSecret;
 
     const orgSetting = await resolveCredentialForScope(key, {
       ...ctx,
+      orgId,
       scope: "org",
     });
     if (orgSetting) return orgSetting;
@@ -156,7 +190,9 @@ export async function resolveCredential(
  * org the caller already belongs to), and never return the owning account, how
  * many rows matched, or any part of the value. Without an active org there is
  * no boundary to bound the probe to, so it declines to answer rather than
- * revealing that some other tenant holds a key of the same name.
+ * revealing that some other tenant holds a key of the same name — this
+ * includes callers whose `ctx.orgId` is unset AND whose org could not be
+ * resolved from `ctx.userEmail` (see `resolveEffectiveOrgId`).
  *
  * Returns null when nothing safe and useful can be said.
  */
@@ -164,10 +200,13 @@ export async function describeCredentialScopeGap(
   keys: readonly string[],
   ctx: CredentialContext,
 ): Promise<string | null> {
-  if (!ctx?.userEmail || !ctx.orgId) return null;
+  if (!ctx?.userEmail) return null;
+  const orgLookup = await resolveEffectiveOrgId(ctx);
+  if (orgLookup.lookupFailed || !orgLookup.orgId) return null;
+  const scopedCtx: CredentialContext = { ...ctx, orgId: orgLookup.orgId };
 
   for (const key of keys) {
-    if (await hasForeignPersonalCredentialInOrg(key, ctx)) {
+    if (await hasForeignPersonalCredentialInOrg(key, scopedCtx)) {
       return (
         `A "${key}" key is saved in this workspace with Personal scope. ` +
         `Personal keys are readable only by their own owner's signed-in sessions, ` +
@@ -177,7 +216,7 @@ export async function describeCredentialScopeGap(
       );
     }
 
-    const holder = await findMemberOrgHoldingCredential(key, ctx);
+    const holder = await findMemberOrgHoldingCredential(key, scopedCtx);
     if (holder) {
       return (
         `A "${key}" key is saved in the ${holder} organization, but this ` +