@north-light/crouter 0.3.348 → 0.3.350

package/dist/builtin-memory/crouter-sdk/client.md

@@ -17,6 +17,40 @@ const customSocketClient = new Crouter({ socketPath: '/custom/path/crtrd.sock' }
 
 `Crouter` is the default export and the only class an application constructs. `CrtrClient` from `@north-light/crouter-api` is an implementation detail and is not re-exported.
 
+## An app connection and refresh
+
+```ts
+import { OAuth2Client } from '@north-light/crouter-sdk';
+
+const oauth = new OAuth2Client({clientId, privateKey, keyId, redirectUri, issuer});
+const {url, codeVerifier, state, nonce} = await oauth.authorizeUrl({scopes: ['openid', 'crtr:act'], state: sessionState});
+// Save codeVerifier, state, and nonce in the app session; redirect the user to url.
+const connection = await oauth.exchangeCode({code: callbackCode, codeVerifier, state, nonce});
+const client = oauth.client(connection, store);
+```
+
+`ConnectionStore` provides `load(userId)` and `save(connection)`; it may also implement `lock(userId, fn)`. A multi-process app must implement the lock across every process: the SDK reloads the connection, sends the refresh request only if no other process rotated its token, and saves the result while the lock is held. `MemoryConnectionStore` locks only within one process and is for local development.
+
+A Postgres store can hold a transaction-scoped advisory lock for the whole callback (all workers must use the same database):
+
+```ts
+async function lock<T>(userId: string, fn: () => Promise<T>): Promise<T> {
+  const db = await pool.connect();
+  try {
+    await db.query('BEGIN');
+    await db.query('SELECT pg_advisory_xact_lock(hashtextextended($1, 0))', [userId]);
+    const result = await fn(); // load, token request, and save complete before COMMIT
+    await db.query('COMMIT');
+    return result;
+  } catch (error) {
+    await db.query('ROLLBACK');
+    throw error;
+  } finally { db.release(); }
+}
+```
+
+`refresh_token_reused` means the app's processes raced on one refresh token; the directory invalidates the grant's refresh tokens, so the user reconnects (without another consent page). Fix the store's `lock` before reconnecting or the race will recur. `runtime_provisioning` means the user's runtime is still being set up and the SDK retries the token request.
+
 ## Options
 
 | Option | Type | Default | Meaning |

package/dist/builtin-memory/crouter-sdk/errors.md

@@ -13,6 +13,8 @@ when-and-why-to-read: When you need Errors, this knowledge should be read
 
 Exceptions are for the layer underneath: the SDK rejected an invalid local identifier or configuration, the daemon refused the request, the connection failed, the request timed out, or you aborted.
 
+An error without `origin` was produced by the SDK because the request reached no server (runtime, router, or directory). Show it as a connection failure, never as a refusal. An OAuth ID token with a missing or mismatched nonce raises the SDK-only `id_token_invalid` code.
+
 ## Classes and mappings
 
 Every class below extends `APIError`, which carries `status`, `code`, `message`, `details`, and `headers`.

package/dist/builtin-memory/crouter-sdk/memory.md

@@ -45,9 +45,9 @@ Every method accepts `RequestOptions` as its final optional argument (`signal`,
 | `memory.history(name, query?, options?)` | `name`; `MemoryHistoryQuery` | `MemoryHistoryDTO` |
 | `memory.resolve(name, scope?, options?)` | `name`; `MemoryScope` | `MemoryDocRefDTO` |
 
-`MemoryDocCreateRequest` requires `name`, `kind`, `when_and_why_to_read`, and `body`; it also accepts `frontmatter`, `extensions`, and the scope fields. `MemoryDocUpdateRequest` requires `rationale`, which is stored in revision history rather than document text, and optionally accepts `body`, `frontmatter`, `extensions`, `unset`, and the scope fields. `MemoryDocMoveRequest` requires `to` and accepts the scope fields.
+`MemoryDocCreateRequest` requires `name`, `kind`, `when_and_why_to_read`, and `body`; it also accepts `frontmatter`, `extensions`, and the scope fields. `frontmatter.privacy` accepts `public`, `friends`, or `private`; creation defaults to persisted `public`. `MemoryDocUpdateRequest` requires `rationale`, which is stored in revision history rather than document text, and optionally accepts `body`, `frontmatter`, `extensions`, `unset`, and the scope fields. Set `frontmatter.privacy` to change the level; it cannot be unset. A legacy document without the field reads as `private`. `MemoryDocMoveRequest` requires `to` and accepts the scope fields.
 
-`retrieve` returns the body by default. With `frontmatter: true`, its `body` is the complete document source. `MemoryDocDTO` also contains `frontmatter`, `representation` (`'leaf-file'` or `'directory-index'`), `links`, and any lint `findings`; document DTOs include their canonical name, kind, scope, extensions, path, store root, physical relative path, and any competing candidates. `resolve` returns the winning document's location and optional plugin name without reading its body.
+`retrieve` returns the body by default. With `frontmatter: true`, its `body` is the complete document source with the effective privacy level included for older documents. `MemoryDocDTO` also contains `privacy`, `frontmatter`, `representation` (`'leaf-file'` or `'directory-index'`), `links`, and any lint `findings`; document DTOs include their canonical name, kind, scope, extensions, path, store root, physical relative path, and any competing candidates. `resolve` returns the winning document's location and optional plugin name without reading its body.
 
 ```ts
 await client.memory.create({

package/dist/builtin-memory/crouter-sdk/streaming.md

@@ -9,6 +9,27 @@ when-and-why-to-read: When you need Streaming, this knowledge should be read
 
 Watch a run as it works: assistant text as it is produced, tool calls as they start and finish, reports as they are pushed, and the settled outcome.
 
+## Forwarding a run to a browser
+
+The app server keeps the runtime token and connection; the browser connects only to the app. The app server calls `forwardRunEvents(client, runId, {after: cursorFromRequest(request), signal: request.signal})` and returns the Fetch `Response`. After a host cuts the browser connection, EventSource sends its last SSE id as `Last-Event-ID`; `cursorFromRequest` prefers it over the URL's `after` query parameter.
+
+Every forwarded run event is an unnamed SSE record with its `sequence_number` as `id` and the complete event object as `data`. Receive all event types with one handler:
+
+```ts
+const source = new EventSource(`/api/runs/${runId}/events?after=${cursor}`);
+source.onmessage = ({data}) => {
+  const event = JSON.parse(data);
+  if (event.type === 'stream.refused') { showRefusal(event.error); source.close(); return; }
+  if (event.type === 'stream.reconnecting') { showConnectionFailure(event.error); return; }
+  if (event.type === 'stream.reconnected') { clearConnectionFailure(); return; }
+  showRunEvent(event);
+};
+```
+
+The three `stream.*` records are forwarded-stream notices, not daemon run events; they have no `sequence_number` or SSE id. A `stream.refused` carries the full error envelope, including `stream_gap`'s `details.latest_sequence` and `details.earliest_sequence`. The helper ends that response after a refusal. The SDK does not recover a gap by skipping missing events.
+
+When the page reloads mid-reply or gets `stream_gap`, the app reads `runs.trace(runId)` through its server and shows each node's `in_progress_message` (`{thinking, text}` or `null`) as that node's open message. The trace's `latest_sequence` is read consistently with its conversations and open messages. Resume `runs.events(runId, {after: trace.latest_sequence})` (or forward with that cursor); do not use a separately read `runs.get` cursor. Continue appending new deltas to the open message, but replace its thinking or text with the complete content repeated by `node.thinking.done` or `node.output_text.done`. This shows the message from its beginning without duplicating content. `runs.get` and every `runs.list` entry expose `latest_sequence` and `last_activity_at`; a cursor equal to `latest_sequence` is not a gap even when older events have expired.
+
 ## The SDK surface
 
 ```ts

package/dist/builtin-pi-packages/pi-crtr-extensions/extensions/claude-plugin-commands.ts

@@ -1,4 +1,4 @@
-import { envProfileId } from '../../../shared/env.js';
+import { envProfileId, isSandboxedNode } from '../../../shared/env.js';
 import type { ExtensionAPI } from '@earendil-works/pi-coding-agent';
 import {
   readFileSync,
@@ -11,7 +11,7 @@ import {
   realpathSync,
 } from 'node:fs';
 import { homedir } from 'node:os';
-import { join, resolve, dirname } from 'node:path';
+import { join, resolve, dirname, sep } from 'node:path';
 import { loadProfileManifest } from '../../../core/profiles/manifest.js';
 import { stripMarkdownComments } from '../../../core/runtime/command-expansion.js';
 import { expandShellBlocks, DEFAULT_SHELL_TIMEOUT_MS } from '../../../core/runtime/shell-expansion.js';
@@ -146,6 +146,7 @@ function canonicalDir(path: string): string {
  *  and its ancestors come first; selected-profile project pointers widen the
  *  search without letting a duplicate profile entry displace the local copy. */
 export function projectClaudeDirs(cwd: string, profileProjectDirs: readonly string[]): string[] {
+  if (isSandboxedNode()) return [];
   const out: string[] = [];
   const seen = new Set<string>();
   for (const pointer of [cwd, ...profileProjectDirs]) {
@@ -160,6 +161,7 @@ export function projectClaudeDirs(cwd: string, profileProjectDirs: readonly stri
 }
 
 function selectedProfileProjects(): string[] {
+  if (isSandboxedNode()) return [];
   const profileId = envProfileId() ?? "";
   if (profileId === "") return [];
   try {
@@ -184,7 +186,9 @@ function pluginDirs(): { name: string; installPath: string }[] {
     const name = key.split("@")[0];
     for (const rec of records ?? []) {
       if (!rec.installPath) continue;
-      out.push({ name, installPath: rec.installPath });
+      const installPath = resolve(rec.installPath);
+      if (isSandboxedNode() && !installPath.startsWith(resolve(HOME) + sep)) continue;
+      out.push({ name, installPath });
     }
   }
   return out;
@@ -330,7 +334,7 @@ const TOKEN_REGEX = /\$(?:\{\d+:-[^}]*\}|\{@:\d+(?::\d+)?\}|\d+|ARGUMENTS|@)/;
  * handler (such as the command shim path above). */
 function nativePromptBody(name: string, cwd: string): string | undefined {
   if (name.includes("/") || name.includes("\\") || name.includes("\0")) return undefined;
-  for (const dir of [PI_PROMPTS, join(cwd, PROJECT_PI_PROMPTS)]) {
+  for (const dir of isSandboxedNode() ? [PI_PROMPTS] : [PI_PROMPTS, join(cwd, PROJECT_PI_PROMPTS)]) {
     try {
       const raw = readFileSync(join(dir, `${name}.md`), "utf8");
       return splitFrontmatter(raw).body;

package/dist/builtin-pi-packages/pi-crtr-extensions/extensions/memory-slash-commands.ts

@@ -1,25 +1,12 @@
-import { envNodeId } from '../../../shared/env.js';
+import { envNodeId, envProfileId } from '../../../shared/env.js';
 import type { ExtensionAPI } from '@earendil-works/pi-coding-agent';
-import { createMemoryDocSnapshot, listAllMemoryDocs, readMemoryDocContent } from '../../../core/memory-resolver.js';
-import { parseSubstrateDoc } from '../../../core/substrate/schema.js';
-import { docsByName } from '../../../core/substrate/listings.js';
-import { contentReadAttachments } from '../../../core/substrate/on-read.js';
-import { brokerExtensionState } from '../../../core/runtime/broker/daemon-ops.js';
-import type { NodeConfigSubject } from '../../../core/substrate/subject-fields.js';
+import { localClient } from '../../../api/node-transport.js';
 import {
   expandDeterministicCommand,
   type DeterministicCommandExpansion,
 } from '../../../core/runtime/command-expansion.js';
 import { expandShellBlocks, hasShellBlocks, DEFAULT_SHELL_TIMEOUT_MS } from '../../../core/runtime/shell-expansion.js';
 import type { ChatCommandMetadata } from '../../../core/runtime/command-surface.js';
-import {
-  exposureTarget,
-  loadContextExposureState,
-  mergeContextExposureState,
-  registerDocumentExposure,
-  saveContextExposureState,
-  sharedContextExposureState,
-} from '../../../core/substrate/injected-store.js';
 import { piShellRunner } from './pi-shell-runner.js';
 
 // memory-slash-commands: any memory doc frontmatter-flagged `slash: true`
@@ -28,15 +15,16 @@ import { piShellRunner } from './pi-shell-runner.js';
 // the doc body (plus the user's free-text args) as a normal turn instead of
 // requiring a separate skill-invocation mechanism.
 //
-// Discovery uses one in-process target snapshot for both listing and body
-// resolution. The snapshot already resolves exact canonical identities in
-// source precedence; this file does not walk memory directories or reimplement
-// scope resolution.
+// The daemon resolves the target snapshot and returns command bodies. The
+// broker never opens memory stores; shell blocks run only when invoked here.
 
 interface MemoryListItem {
   name: string;
   short_form: string;
-  slash: boolean;
+  path: string;
+  canonical_body: string;
+  execution_body?: string;
+  error?: string;
 }
 
 export interface SlashDoc {
@@ -48,85 +36,32 @@ export interface SlashDoc {
   description: string;
 }
 
-// Keep each canonical winner's body and path for disclosure classification and
-// the existing execution read.
-const resolvedMemoryDocs = new Map<string, { path: string; canonicalBody: string }>();
+// Keep each canonical winner's body for registration-time disclosure classification.
+const resolvedMemoryDocs = new Map<string, MemoryListItem>();
 
 async function defaultListMemoryDocs(): Promise<MemoryListItem[]> {
-  const snapshot = createMemoryDocSnapshot();
-  const items: MemoryListItem[] = [];
-  const seen = new Set<string>();
-  for (const memoryDoc of snapshot.docs) {
-    if (seen.has(memoryDoc.name)) continue;
-    seen.add(memoryDoc.name);
-    const doc = parseSubstrateDoc(memoryDoc);
-    if (doc === null) continue;
-    items.push({
-      name: memoryDoc.name,
-      short_form: doc.shortForm,
-      slash: doc.slash,
-    });
-  }
-
-  // Resolve eligible canonical names against the same target snapshot that
-  // supplied the list rows.
-  const resolved = snapshot.resolve(items.filter((item) => item.slash).map((item) => item.name));
+  const node = envNodeId();
+  const query = new URLSearchParams(node ? { node } : { cwd: process.cwd(), ...(envProfileId() ? { profile: envProfileId() } : {}) });
+  const docs = await localClient({ autostart: false }).request<MemoryListItem[]>('GET', `/v1/memory/slash?${query}`);
   resolvedMemoryDocs.clear();
-  for (const [name, doc] of resolved) {
-    resolvedMemoryDocs.set(name, { path: doc.path, canonicalBody: doc.body });
-  }
-  return items;
+  for (const doc of docs) resolvedMemoryDocs.set(doc.name, doc);
+  return docs;
 }
 
-function defaultReadMemoryDoc(name: string): { path: string; canonicalBody: string; executionBody: string } {
+function defaultReadMemoryDoc(name: string): { canonicalBody: string; executionBody: string } {
   const resolved = resolvedMemoryDocs.get(name);
   if (resolved === undefined) throw new Error(`memory slash document was not resolved: ${name}`);
-  return {
-    path: resolved.path,
-    canonicalBody: resolved.canonicalBody,
-    executionBody: readMemoryDocContent(resolved.path),
-  };
+  if (resolved.error !== undefined) throw new Error(resolved.error);
+  if (resolved.execution_body === undefined) throw new Error(`memory slash document has no execution body: ${name}`);
+  return { canonicalBody: resolved.canonical_body, executionBody: resolved.execution_body };
 }
 
-/** The node-config subject the companion `memory-read` gates evaluate against.
- *  Unreachable daemon = null, which skips gated docs and delivers ungated ones. */
-async function slashSubject(nodeId: string): Promise<NodeConfigSubject | null> {
-  try {
-    return (await brokerExtensionState(nodeId)).subject;
-  } catch {
-    return null;
-  }
-}
-
-/** Invoking a document is content delivery, so it carries the same companions
- *  `crtr memory read` attaches: the directory listings that place it, and every
- *  corpus doc whose `memory-read` route matches its name. Returns the blocks to
- *  prepend and records the whole delivery in the exposure ledger. Without a node
- *  identity nothing records and nothing attaches. */
-async function slashReadAttachments(name: string, path: string, body: string): Promise<string[]> {
-  const nodeId = envNodeId();
-  if (nodeId === undefined || nodeId === "") return [];
-  const state = sharedContextExposureState(nodeId);
-  mergeContextExposureState(state, loadContextExposureState(nodeId));
-  const target = exposureTarget(state, "transcript");
-  // Register the invoked body BEFORE the attachments, so the listings and
-  // companion routes dedupe against the document about to be delivered.
-  registerDocumentExposure(target, path, body, "content");
-  let blocks: string[] = [];
-  try {
-    const byName = docsByName(listAllMemoryDocs(undefined, true, true));
-    // No `explicit`: the read leaf returns a doc's own directory listing in a
-    // separate field, while this path has only the turn — it wants that
-    // listing attached as a block like every other.
-    blocks = contentReadAttachments(
-      { name, path, body },
-      { subject: await slashSubject(nodeId), target, byName, listings: "blocks" },
-    ).blocks;
-  } catch {
-    blocks = [];
-  }
-  saveContextExposureState(nodeId, state);
-  return blocks;
+async function slashReadAttachments(name: string): Promise<{ blocks: string[]; execution_body: string }> {
+  const node = envNodeId();
+  if (!node) throw new Error('memory slash attachments require a node');
+  return localClient({ autostart: false }).request<{ blocks: string[]; execution_body: string }>(
+    'POST', '/v1/memory/slash/attachments', { node, name },
+  );
 }
 
 function hasNodeRelativeExpansion(body: string): boolean {
@@ -141,20 +76,13 @@ export function slashCommandName(docName: string): string {
 /** Every `slash: true` canonical winner, scope-precedence-deduped by name. A
  *  doc without `slash` (or `slash: false`) is silently excluded. */
 export async function discoverSlashDocs(): Promise<SlashDoc[]> {
-  let items: MemoryListItem[];
-  try {
-    items = await defaultListMemoryDocs();
-  } catch {
-    return [];
-  }
+  const items = await defaultListMemoryDocs();
   const seen = new Set<string>();
   const out: SlashDoc[] = [];
   for (const item of items) {
     if (seen.has(item.name)) continue;
     seen.add(item.name);
-    if (item.slash) {
-      out.push({ name: item.name, commandName: slashCommandName(item.name), description: item.short_form });
-    }
+    out.push({ name: item.name, commandName: slashCommandName(item.name), description: item.short_form });
   }
   return out;
 }
@@ -163,9 +91,7 @@ export default async function (pi: ExtensionAPI) {
   const docs = await discoverSlashDocs();
   for (const doc of docs) {
     let expansion: DeterministicCommandExpansion | undefined;
-    let exposure: { path: string; body: string } | undefined;
     let discloseExpansion = false;
-    let loadError: unknown;
     try {
       const body = defaultReadMemoryDoc(doc.name);
       expansion = {
@@ -173,10 +99,10 @@ export default async function (pi: ExtensionAPI) {
         commandName: doc.commandName,
         body: body.executionBody,
       };
-      exposure = { path: body.path, body: body.canonicalBody };
       discloseExpansion = !hasNodeRelativeExpansion(body.canonicalBody);
-    } catch (err) {
-      loadError = err;
+    } catch {
+      // Keep registration for a document that became unreadable; invocation
+      // reports the current read error without executing the cached body.
     }
 
     // pi preserves unknown registration fields on the resolved command object.
@@ -193,28 +119,23 @@ export default async function (pi: ExtensionAPI) {
         ? {}
         : { gateway: true as const, ...(discloseExpansion ? { expansion } : {}) }),
       handler: async (args, ctx) => {
-        if (expansion === undefined) {
-          ctx.ui.notify(
-            `/${doc.commandName}: failed to read memory doc "${doc.name}": ${loadError instanceof Error ? loadError.message : String(loadError)}`,
-            "error",
-          );
+        let current: { blocks: string[]; execution_body: string };
+        try {
+          current = await slashReadAttachments(doc.name);
+        } catch (error) {
+          ctx.ui.notify(`/${doc.commandName}: failed to read memory doc "${doc.name}": ${error instanceof Error ? error.message : String(error)}`, "error");
           return;
         }
-        // Shell runs HERE and only here. `expandDeterministicCommand` stays
-        // inert because it also drives the attach viewer's pre-submit preview,
-        // which re-expands on every keystroke — executing there would run the
-        // document's commands repeatedly while the user is still typing. This
-        // handler fires once, at submit, so the preview shows the command text
-        // and the submitted turn carries its output.
-        const expanded = expandDeterministicCommand(expansion, args ?? "");
+        // The daemon resolves the current slash document and attachments in one
+        // request, before the document can execute any shell block.
+        const expanded = expandDeterministicCommand({ kind: 'memory-slash', commandName: doc.commandName, body: current.execution_body }, args ?? "");
         const content = hasShellBlocks(expanded)
           ? await expandShellBlocks(
               expanded,
               piShellRunner(pi, (ctx as { cwd?: string }).cwd ?? process.cwd(), DEFAULT_SHELL_TIMEOUT_MS),
             )
           : expanded;
-        const blocks =
-          exposure === undefined ? [] : await slashReadAttachments(doc.name, exposure.path, exposure.body);
+        const blocks = current.blocks;
         pi.sendMessage(
           {
             customType: "memory-slash-command",

package/dist/builtin-pi-packages/pi-crtr-extensions/extensions/provider-rotation.d.ts

@@ -11,12 +11,17 @@ type ProviderErrorClassification = {
     status?: number;
     reason: string;
     hadRetryAfterHeader: boolean;
+    /** Cooldown this classification imposes regardless of any Retry-After header. */
+    cooldownMs?: number;
+};
+type ProviderClassificationPolicy = {
+    rotateOnAuth: boolean;
 };
 /** Test seam for the policy mapping over the shared recognition signal. */
 export declare function __classifyProviderErrorForTest(error: unknown, observed?: {
     status?: number;
     retryAfterMs?: number;
-}): ProviderErrorClassification;
+}, policy?: ProviderClassificationPolicy): ProviderErrorClassification;
 declare function defaultSleep(ms: number): Promise<void>;
 /** Test-only seam: override the sleep implementation used for in-place/wait-out retries. Pass undefined to restore the default. */
 export declare function __setSleepForTest(fn: typeof defaultSleep | undefined): void;

package/dist/builtin-pi-packages/pi-crtr-extensions/extensions/provider-rotation.js

@@ -1,7 +1,7 @@
 import { spawn } from 'node:child_process';
 import { createAssistantMessageEventStream, } from '@earendil-works/pi-ai';
 import { anthropicMessagesApi, openAICodexResponsesApi } from '@earendil-works/pi-ai/compat';
-import { ANTHROPIC_PROVIDER_ID, OPENAI_CODEX_PROVIDER_ID, INVALID_REFRESH_TOKEN_BACKOFF_MS, formatStatusLine, getProviderLabel, isManagedProvider, isInvalidRefreshTokenError, addSubscription, enrichManagedLoginIdentity, markSubscriptionAuthenticationFailed, markSubscriptionRateLimited, markSubscriptionSuccess, parseRetryAfterHeader, promoteSubscription, readRotationConfig, readSubscriptionPool, refreshSubscriptionCredential, removeManagedAccount, resolveProviderCandidates, upsertSubscriptionWithUniqueAccount, } from '../../../core/subscription-state.js';
+import { ANTHROPIC_PROVIDER_ID, OPENAI_CODEX_PROVIDER_ID, INVALID_REFRESH_TOKEN_BACKOFF_MS, formatStatusLine, getProviderLabel, isManagedProvider, isInvalidRefreshTokenError, addSubscription, enrichManagedLoginIdentity, markSubscriptionAuthenticationFailed, markSubscriptionRateLimited, markSubscriptionSuccess, retryAfterMsFromHeaders, retryAfterMsFromError, promoteSubscription, readRotationConfig, readSubscriptionPool, refreshSubscriptionCredential, removeManagedAccount, resolveProviderCandidates, upsertSubscriptionWithUniqueAccount, } from '../../../core/subscription-state.js';
 import { readMergedLaunchConfig } from '../../../core/config.js';
 import { expandModelCandidates, modelRequestFromConfig, probeRouteAvailability } from '../../../core/model-routes.js';
 import { envModelExact, envNodeId } from '../../../shared/env.js';
@@ -23,6 +23,11 @@ const TRANSIENT_RETRY_BACKOFFS_MS = [250, 750];
 // so cool it down only briefly -- long enough to rotate to another credential / fallback
 // provider, short enough that it comes back quickly if it was the only option.
 const TRANSIENT_ROTATE_COOLDOWN_MS = 60 * 1000;
+// A 401/403 before any content means the provider refused this credential (a lapsed
+// plan, a revoked server-side key). That is not a transient blip, but it is not proof
+// the account is gone either: cool the account for 30 minutes and rotate, rather than
+// the 30-day invalid_grant backoff. Exact requests keep the auth error.
+const AUTH_REJECTED_COOLDOWN_MS = 30 * 60 * 1000;
 // A few short outer retries absorb a normal multi-broker collision; if the metadata file
 // remains busy, the provider call still proceeds. Subscription bookkeeping must never turn a
 // healthy model response into a fatal generation fault.
@@ -38,7 +43,7 @@ function configuredValue(state, key, envName) {
 function isExactModel(state) {
     return state.options === undefined && envModelExact();
 }
-function classifyProviderSignal(signal) {
+function classifyProviderSignal(signal, policy) {
     const hadRetryAfterHeader = signal.retryAfterMs !== undefined;
     if (signal.kind === 'rate-limit' && signal.matchedOn === 'status') {
         return { kind: 'rate_limit', status: signal.status, reason: 'http 429', hadRetryAfterHeader };
@@ -50,6 +55,9 @@ function classifyProviderSignal(signal) {
         return { kind: 'transient', status: signal.status, reason: `http ${signal.status}`, hadRetryAfterHeader };
     }
     const textMatches = signal.textMatches ?? (signal.matchedOn === 'text' && signal.match ? [{ kind: signal.kind, match: signal.match }] : []);
+    if (policy.rotateOnAuth && signal.kind === 'auth' && signal.matchedOn === 'status' && !textMatches.some(({ kind }) => kind === 'rate-limit')) {
+        return { kind: 'rate_limit', status: signal.status, reason: `http ${signal.status}`, hadRetryAfterHeader, cooldownMs: AUTH_REJECTED_COOLDOWN_MS };
+    }
     const transientMatch = textMatches.find(({ kind }) => kind === 'connection' || kind === 'socket' || kind === 'service-unavailable' || kind === 'overloaded');
     if (transientMatch) {
         return { kind: 'transient', status: signal.status, reason: transientMatch.match.toLowerCase(), hadRetryAfterHeader };
@@ -60,7 +68,7 @@ function classifyProviderSignal(signal) {
     }
     return { kind: 'fatal', status: signal.status, reason: 'unclassified', hadRetryAfterHeader };
 }
-function classifyProviderFailure(failure, retryAfterMs) {
+function classifyProviderFailure(failure, retryAfterMs, policy) {
     const nested = failure.causes ?? [];
     const code = failure.code ?? nested.find((cause) => cause.code !== undefined)?.code;
     const errno = failure.errno ?? nested.find((cause) => cause.errno !== undefined)?.errno;
@@ -73,14 +81,11 @@ function classifyProviderFailure(failure, retryAfterMs) {
         code,
         errno,
         message,
-    }));
-}
-function classifyProviderError(error, observed) {
-    return classifyProviderFailure(normalizeProviderFailure(error, { status: observed.status }), observed.retryAfterMs);
+    }), policy);
 }
 /** Test seam for the policy mapping over the shared recognition signal. */
-export function __classifyProviderErrorForTest(error, observed = {}) {
-    return classifyProviderError(error, observed);
+export function __classifyProviderErrorForTest(error, observed = {}, policy = { rotateOnAuth: false }) {
+    return classifyProviderFailure(normalizeProviderFailure(error, { status: observed.status }), observed.retryAfterMs, policy);
 }
 function providerFailureAssistantMessage(model, failure) {
     const message = toAssistantError(model, failure.message);
@@ -214,15 +219,6 @@ function toAssistantError(model, errorMessage) {
         timestamp: Date.now(),
     };
 }
-function retryAfterMs(headers) {
-    const retryAfterMsHeader = headers["retry-after-ms"];
-    if (retryAfterMsHeader) {
-        const millis = Number(retryAfterMsHeader);
-        if (Number.isFinite(millis))
-            return Math.max(0, millis);
-    }
-    return parseRetryAfterHeader(headers["retry-after"]);
-}
 // Extract an account identity supplied directly by the OAuth credential.
 function loginAccountId(cred) {
     return typeof cred.accountId === "string" && cred.accountId.trim() ? cred.accountId.trim() : undefined;
@@ -392,6 +388,7 @@ export function __setStreamForProviderForTest(fn) {
 // A genuine rate limit ends the attempt immediately (the caller cools the credential down
 // and rotates); a transient blip gets a short in-place retry budget before giving up.
 async function streamProviderAttempt(state, providerId, model, context, options, credential, outer) {
+    const policy = { rotateOnAuth: !isExactModel(state) };
     for (let attempt = 1;; attempt++) {
         const attemptAt = Date.now();
         let observedStatus;
@@ -429,7 +426,7 @@ async function streamProviderAttempt(state, providerId, model, context, options,
             onResponse: async (response, responseModel) => {
                 observedStatus = response.status;
                 if (response.status === 429 || response.status === 503) {
-                    requestedRetryAfterMs = retryAfterMs(response.headers);
+                    requestedRetryAfterMs = retryAfterMsFromHeaders(response.headers);
                 }
                 await options?.onResponse?.(response, responseModel);
             },
@@ -474,7 +471,7 @@ async function streamProviderAttempt(state, providerId, model, context, options,
                     }
                     failure = normalizeProviderFailure(event.error, { status: observedStatus });
                     failureMessage = failure.message;
-                    classification = classifyProviderFailure(failure, requestedRetryAfterMs);
+                    classification = classifyProviderFailure(failure, requestedRetryAfterMs, policy);
                     if (classification.kind === "fatal" || sawContent) {
                         emit({ ...event, error: providerFailureAssistantMessage(model, failure) });
                         flush();
@@ -501,9 +498,10 @@ async function streamProviderAttempt(state, providerId, model, context, options,
                 flush();
                 return { result: "fatal", attemptAt };
             }
+            requestedRetryAfterMs ??= retryAfterMsFromError(error);
             failure = normalizeProviderFailure(error, { status: observedStatus });
             failureMessage = failure.message;
-            classification = classifyProviderFailure(failure, requestedRetryAfterMs);
+            classification = classifyProviderFailure(failure, requestedRetryAfterMs, policy);
             if (classification.kind === "fatal" || sawContent) {
                 emit({
                     type: "error",
@@ -524,7 +522,7 @@ async function streamProviderAttempt(state, providerId, model, context, options,
             return { result: "success", attemptAt };
         }
         if (classification.kind === "rate_limit") {
-            return { result: "rate_limited", retryAfterMs: requestedRetryAfterMs, attemptAt, classification };
+            return { result: "rate_limited", retryAfterMs: classification.cooldownMs ?? requestedRetryAfterMs, attemptAt, classification, failureMessage };
         }
         // Transient: retry the SAME credential/provider in place first -- no cooldown for the
         // quick in-place budget.
@@ -582,7 +580,10 @@ async function runManagedProvider(state, model, context, options, stream) {
         : state.runtimeContext.thinkingLevel;
     const request = modelRequestFromConfig(`${model.provider}/${model.id}${liveThinking ? `:${liveThinking}` : ''}`, configuredValue(state, 'modelIntent', 'CRTR_MODEL_INTENT'), isExactModel(state));
     const expanded = request ? expandModelCandidates(request, configuredValue(state, 'nodeCwd', 'CRTR_NODE_CWD'), configuredValue(state, 'profileId', 'CRTR_PROFILE_ID')) : [];
-    const liveRank = expanded.find((candidate) => candidate.providerId === model.provider && candidate.modelId === model.id && candidate.thinkingLevel === liveThinking)?.rank ?? 0;
+    // The node's thinking level holds on its own model; a route to another
+    // provider or model takes that cell's thinking.
+    const onLiveModel = (candidate) => candidate.providerId === model.provider && candidate.modelId === model.id;
+    const liveRank = (expanded.find((candidate) => onLiveModel(candidate) && candidate.thinkingLevel === liveThinking) ?? expanded.find(onLiveModel))?.rank ?? 0;
     const routeCandidates = expanded.slice(liveRank)
         .map((route) => {
         const registry = state.runtimeContext?.modelRegistry;
@@ -592,9 +593,10 @@ async function runManagedProvider(state, model, context, options, stream) {
         const availability = probeRouteAvailability(route, registry);
         if (!availability.registered || (!isManagedProvider(route.providerId) && !availability.authenticated))
             return undefined;
-        return { routeId: route.routeId, credentialSource: route.credentialSource, rank: route.rank, providerId: route.providerId, model: routeModel, thinkingLevel: route.thinkingLevel };
+        return { routeId: route.routeId, credentialSource: route.credentialSource, rank: route.rank, providerId: route.providerId, model: routeModel, thinkingLevel: onLiveModel(route) ? liveThinking : route.thinkingLevel };
     })
-        .filter((candidate) => candidate !== undefined);
+        .filter((candidate) => candidate !== undefined)
+        .filter((candidate, index, all) => all.findIndex((other) => other.routeId === candidate.routeId && other.providerId === candidate.providerId && other.model.id === candidate.model.id && other.thinkingLevel === candidate.thinkingLevel) === index);
     const isLiveRoute = (candidate) => candidate.providerId === model.provider && candidate.model.id === model.id && candidate.thinkingLevel === liveThinking;
     // A cooling or unauthenticated managed route contributes its diagnostic and may
     // later re-enter when a credential becomes ready, but it is never selected now.
@@ -618,6 +620,9 @@ async function runManagedProvider(state, model, context, options, stream) {
     const cooldownAttempts = new Map();
     let terminalModel = model;
     let lastTransientFailure;
+    // The last pre-content 401/403 that cooled a route; its text is the only
+    // record of why the routes ran out when they end in a cooling error.
+    let lastAuthRejection;
     // Any HTTP response observed this pass (a status, a Retry-After header, or a
     // rate-limit classification) proves this process can still reach a provider,
     // clearing the poisoned-transport suspicion.
@@ -661,6 +666,8 @@ async function runManagedProvider(state, model, context, options, stream) {
             const cooldownMs = result.result === 'rate_limited' ? result.retryAfterMs ?? DEFAULT_RATE_LIMIT_BACKOFF_MS : TRANSIENT_ROTATE_COOLDOWN_MS;
             if (result.result === 'transient_exhausted')
                 lastTransientFailure = result;
+            if (result.result === 'rate_limited' && (result.classification?.status === 401 || result.classification?.status === 403))
+                lastAuthRejection = result;
             localCoolingDeadlines.set(routeId, Math.max(localCoolingDeadlines.get(routeId) ?? 0, Date.now() + cooldownMs));
             logRouteQueueAdvance(candidate, candidates[0], result);
             continue;
@@ -715,6 +722,8 @@ async function runManagedProvider(state, model, context, options, stream) {
             const cooldownMs = result.result === 'rate_limited' ? result.retryAfterMs ?? DEFAULT_RATE_LIMIT_BACKOFF_MS : TRANSIENT_ROTATE_COOLDOWN_MS;
             if (result.result === 'transient_exhausted')
                 lastTransientFailure = result;
+            if (result.result === 'rate_limited' && (result.classification?.status === 401 || result.classification?.status === 403))
+                lastAuthRejection = result;
             if (result.result === 'rate_limited' && result.retryAfterMs !== undefined) {
                 const persisted = await recordSubscriptionMutation(`recording ${getProviderLabel(providerId)} server cooldown`, () => markSubscriptionRateLimited(providerId, freshCredential.label, cooldownMs, result.attemptAt));
                 if (persisted)
@@ -750,7 +759,11 @@ async function runManagedProvider(state, model, context, options, stream) {
     }
     state.transportOnlyExhaustedPasses = 0;
     if (coolingDeadline !== undefined) {
-        emitCoolingError(stream, terminalModel, new ManagedProviderCoolingError(`All provider routes are rate limited (cooling down ~${Math.ceil((coolingDeadline - Date.now()) / 1000)}s; tried ${tried})`, coolingDeadline));
+        const cooling = `cooling down ~${Math.ceil((coolingDeadline - Date.now()) / 1000)}s`;
+        const message = lastAuthRejection === undefined
+            ? `All provider routes are rate limited (${cooling}; tried ${tried})`
+            : `All provider routes are rate limited or rejected (${cooling}; last rejection ${lastAuthRejection.classification.reason}: ${lastAuthRejection.failureMessage ?? 'no error message'}; tried ${tried})`;
+        emitCoolingError(stream, terminalModel, new ManagedProviderCoolingError(message, coolingDeadline));
         return;
     }
     const authFailure = [...authFailures][0];
@@ -856,7 +869,8 @@ async function restoreHigherRankIfAvailable(state, pi, ctx) {
     if (!request || !ctx.model)
         return false;
     const candidates = expandModelCandidates(request, configuredValue(state, 'nodeCwd', 'CRTR_NODE_CWD'), configuredValue(state, 'profileId', 'CRTR_PROFILE_ID'));
-    const liveRank = candidates.find((candidate) => candidate.providerId === ctx.model?.provider && candidate.modelId === ctx.model?.id && candidate.thinkingLevel === liveThinking)?.rank;
+    const onLiveModel = (candidate) => candidate.providerId === ctx.model?.provider && candidate.modelId === ctx.model?.id;
+    const liveRank = (candidates.find((candidate) => onLiveModel(candidate) && candidate.thinkingLevel === liveThinking) ?? candidates.find(onLiveModel))?.rank;
     if (liveRank === undefined)
         return false;
     const preferred = candidates.find((candidate) => candidate.rank < liveRank && resolveProviderCandidates([{