fix(coding-agent,ai): scope auth-stale to credential failures; clear lockouts only on successful explicit selection

Fresh-eyes review fixes:

- New "permission" failure kind: 403s and permission/forbidden/access-denied
  error types (Anthropic permission_error, SDK PermissionDeniedError, AWS
  AccessDeniedException) are entitlement or policy denials, not bad
  credentials. They are permanent (no retry) but never mark auth stale, so
  a model/org/region-scoped 403 cannot lock out the whole provider.
- An auth verdict now needs structured evidence (401 status or an explicit
  authentication error type); free-form message text alone no longer
  launders into a stale-marking "structured" auth diagnostic.
- AgentSession.setModel is the single owner of the stale-auth clear and
  commits it only when staleness is the sole blocker of an explicit
  selection; the in-process and daemon set_model lookups consult the full
  catalog for stale-auth providers instead of mutating stale state before
  validation, so a mistyped model id or failed refresh no longer unlocks
  a provider that was proven bad.

Author: snimu

packages/ai/.changes/res-1271-auth-heuristics.md

@@ -1 +1,2 @@
 - Changed failure classification to stop treating bare 403 responses as authentication failures; an explicit authentication/permission error type or a 401 status is required.
+- Added a `permission` failure kind: 403/permission-type errors classify as entitlement denials (permanent, no retry) instead of authentication failures, and auth verdicts require structured evidence (401 or an explicit authentication error type).

packages/ai/src/utils/stream-failure.ts

@@ -15,6 +15,7 @@ export type StreamFailureKind =
 	| "rate_limit"
 	| "server_error"
 	| "auth"
+	| "permission"
 	| "invalid_request"
 	| "malformed_response"
 	| "unknown";
@@ -48,6 +49,7 @@ const KIND_MESSAGES: Record<StreamFailureKind, string> = {
 	rate_limit: "Provider rate limit exceeded",
 	server_error: "Provider server error",
 	auth: "Provider authentication failed",
+	permission: "Provider denied access to the requested resource",
 	invalid_request: "Provider rejected the request",
 	malformed_response: "Provider returned a malformed response",
 	unknown: "Provider stream failed",
@@ -77,10 +79,11 @@ export function classifyStreamFailure(providerErrorType?: string, status?: numbe
 	if (/rate_limit|usage_limit|usage_not_included|throttl/.test(type) || status === 429) {
 		return "rate_limit";
 	}
-	// 403 alone is NOT auth: providers return it for region blocks, org
-	// policy, and model-access denials. Require an explicit auth/permission
-	// error type unless the status is 401.
-	if (/authentication|permission|unauthorized/.test(type) || status === 401) return "auth";
+	// Only bad credentials (401 / explicit authentication types) are auth.
+	// Permission/403 shapes are entitlement or policy denials (model access,
+	// org policy, region) and must not trigger a stale-auth lockout.
+	if (/authentication|unauthorized/.test(type) || status === 401) return "auth";
+	if (/permission|forbidden|access.?denied/.test(type) || status === 403) return "permission";
 	if (type.includes("invalid_request") || type.includes("not_found_error") || status === 400 || status === 404) {
 		return "invalid_request";
 	}
@@ -166,9 +169,16 @@ function extractStreamFailureParts(error: unknown): { info: StreamFailureInfo; d
 	const retryAfterMs =
 		typeof err.retryAfterMs === "number" && err.retryAfterMs >= 0 ? err.retryAfterMs : parseRetryAfterMs(headers);
 
+	let kind = classifyStreamFailure(providerErrorType ?? error.message, status);
+	// An auth verdict drives the provider-wide stale-auth lockout; free-form
+	// message text without a status is too weak to justify it.
+	if (kind === "auth" && providerErrorType === undefined && status === undefined) {
+		kind = "unknown";
+	}
+
 	return {
 		info: {
-			kind: classifyStreamFailure(providerErrorType ?? error.message, status),
+			kind,
 			providerErrorType,
 			status,
 			requestId,

packages/ai/test/stream-failure.test.ts

@@ -49,8 +49,9 @@ describe("classifyStreamFailure", () => {
 		["guardrail_intervened", undefined, "safety"],
 		["authentication_error", undefined, "auth"],
 		[undefined, 401, "auth"],
-		["permission_error", 403, "auth"],
-		[undefined, 403, "unknown"],
+		["permission_error", 403, "permission"],
+		["PermissionDeniedError", 403, "permission"],
+		[undefined, 403, "permission"],
 		["invalid_request_error", undefined, "invalid_request"],
 		["api_error", undefined, "server_error"],
 		[undefined, 503, "server_error"],
@@ -139,6 +140,14 @@ describe("extractStreamFailureInfo", () => {
 		expect(extractStreamFailureInfo(new Error("provider overloaded, retry later")).kind).toBe("overloaded");
 		expect(extractStreamFailureInfo("not an error").kind).toBe("unknown");
 	});
+
+	test("never classifies auth from message text alone", () => {
+		// No structured type and no status: an auth verdict would lock the whole
+		// provider, so free-form text must not produce one.
+		expect(extractStreamFailureInfo(new Error("Unauthorized: authentication failed")).kind).toBe("unknown");
+		const with401 = Object.assign(new Error("Unauthorized"), { status: 401 });
+		expect(extractStreamFailureInfo(with401).kind).toBe("auth");
+	});
 });
 
 describe("formatStreamFailureMessage", () => {

packages/coding-agent/.changes/res-1271-auth-heuristics.md

@@ -1,2 +1,3 @@
 - Removed the 401/403 message-text sniffing that could mark a whole provider auth-stale from non-auth errors (e.g. region-block 403s); auth-stale now requires a structured provider auth failure.
 - Changed explicit model selection to clear a provider's stale-auth lockout so the request runs again instead of failing with "Model not found"; a structured auth failure re-marks it.
+- Changed the stale-auth clear to commit only when an explicit model selection is blocked solely by staleness; failed lookups and validations no longer unlock a provider.

packages/coding-agent/src/core/agent-session.ts

@@ -7126,11 +7126,17 @@ export class AgentSession {
 	}
 
 	async setModel(model: Model<any>, options: ModelSelectOptions = {}): Promise<void> {
-		// Explicit selection overrides a stale-auth lockout; a structured auth
-		// failure on the next request re-marks the provider.
-		this._modelRegistry.clearProviderAuthStale(model.provider);
 		if (!this._modelRegistry.hasConfiguredAuth(model)) {
-			throw new Error(`No API key for ${model.provider}/${model.id}`);
+			// Explicit selection is the recovery path from a stale-auth lockout:
+			// clear (single owner of the clear) only when staleness is the sole
+			// blocker; a structured auth failure on the next request re-marks it.
+			if (this._modelRegistry.getProviderAuthStatus(model.provider).source !== "stale") {
+				throw new Error(`No API key for ${model.provider}/${model.id}`);
+			}
+			this._modelRegistry.clearProviderAuthStale(model.provider);
+			if (!this._modelRegistry.hasConfiguredAuth(model)) {
+				throw new Error(`No API key for ${model.provider}/${model.id}`);
+			}
 		}
 		if (!(await this._modelRegistry.canUseModel(model))) {
 			throw new Error(`Model "${model.provider}/${model.id}" is not available for the current Prime team.`);

packages/coding-agent/src/core/provider-retry.ts

@@ -59,7 +59,7 @@ export function providerStreamFailureRetryAfterMs(message: AssistantMessage): nu
  * retry so a transient auth hiccup does not immediately mark auth stale.
  */
 export function isPermanentProviderFailureKind(kind: string | undefined, retriesPerformed: number): boolean {
-	if (kind === "invalid_request" || kind === "refusal") {
+	if (kind === "invalid_request" || kind === "refusal" || kind === "permission") {
 		return true;
 	}
 	return retriesPerformed > 0 && kind === "auth";

packages/coding-agent/src/modes/agent-connection/in-process-agent-connection.ts

@@ -448,13 +448,14 @@ export class InProcessAgentConnection implements AgentConnection {
 	}
 
 	async setModel(provider: string, modelId: string): Promise<AgentConnectionModel> {
-		// Clear before the lookup: a stale-auth provider's models are excluded
-		// from the available list, which would misreport them as not found.
-		this.session.modelRegistry.clearProviderAuthStale(provider);
-		const availableModels = await this.session.modelRegistry.refreshAvailableModels();
-		const model = availableModels.find((candidate) => {
-			return candidate.provider === provider && candidate.id === modelId;
-		});
+		const registry = this.session.modelRegistry;
+		const availableModels = await registry.refreshAvailableModels();
+		const model =
+			availableModels.find((candidate) => candidate.provider === provider && candidate.id === modelId) ??
+			// A stale-auth provider's models are excluded from the available list;
+			// explicit selection may still target them. The lookup never mutates
+			// stale state: session.setModel owns the clear on a successful switch.
+			(registry.getProviderAuthStatus(provider).source === "stale" ? registry.find(provider, modelId) : undefined);
 		if (!model) {
 			throw new Error(`Model not found: ${provider}/${modelId}`);
 		}

packages/coding-agent/src/modes/daemon/daemon-mode.ts

@@ -4791,13 +4791,17 @@ export class AgentDaemon {
 			case "set_model": {
 				const state = this.getSessionState(command.activeSessionId);
 				const session = state.runtime.session;
-				// Clear before the lookup: a stale-auth provider's models are excluded
-				// from the available list, which would misreport them as not found.
-				session.modelRegistry.clearProviderAuthStale(command.provider);
 				const availableModels = await session.modelRegistry.refreshAvailableModels();
-				const model = availableModels.find((candidate) => {
-					return candidate.provider === command.provider && candidate.id === command.modelId;
-				});
+				const model =
+					availableModels.find(
+						(candidate) => candidate.provider === command.provider && candidate.id === command.modelId,
+					) ??
+					// A stale-auth provider's models are excluded from the available
+					// list; explicit selection may still target them. The lookup never
+					// mutates stale state: session.setModel owns the clear on success.
+					(session.modelRegistry.getProviderAuthStatus(command.provider).source === "stale"
+						? session.modelRegistry.find(command.provider, command.modelId)
+						: undefined);
 				if (!model) {
 					throw new Error(`Model not found: ${command.provider}/${command.modelId}`);
 				}

packages/coding-agent/test/daemon-agent-roster.test.ts

@@ -468,7 +468,6 @@ describe("worker roster reporter", () => {
 		// set_model has no session-event carrier either; its explicit flush publishes the new model.
 		const session = state.runtime.session as unknown as Record<string, unknown>;
 		session.modelRegistry = {
-			clearProviderAuthStale: () => {},
 			refreshAvailableModels: async () => [{ provider: "prov", id: "m2" }],
 		};
 		session.setModel = async (model: unknown) => {

packages/coding-agent/test/daemon-mode.test.ts

@@ -8877,7 +8877,6 @@ describe("daemon mode helpers", () => {
 			runtime: ActiveSessionState["runtime"] & {
 				session: {
 					modelRegistry: {
-						clearProviderAuthStale(provider: string): void;
 						refreshAvailableModels(): Promise<unknown[]>;
 					};
 					isStreaming: boolean;
@@ -8888,7 +8887,6 @@ describe("daemon mode helpers", () => {
 		};
 		state.runtime.session = {
 			modelRegistry: {
-				clearProviderAuthStale: vi.fn(),
 				refreshAvailableModels: vi.fn(async () => [model]),
 			},
 			isStreaming: true,
@@ -8936,7 +8934,6 @@ describe("daemon mode helpers", () => {
 			runtime: ActiveSessionState["runtime"] & {
 				session: {
 					modelRegistry: {
-						clearProviderAuthStale(provider: string): void;
 						refreshAvailableModels(): Promise<unknown[]>;
 					};
 					isStreaming: boolean;
@@ -8947,7 +8944,6 @@ describe("daemon mode helpers", () => {
 		};
 		state.runtime.session = {
 			modelRegistry: {
-				clearProviderAuthStale: vi.fn(),
 				refreshAvailableModels: vi.fn(async () => [model]),
 			},
 			isStreaming: false,