cascade-ai 0.74.0 → 0.75.0

package/dist/index.d.cts

@@ -185,9 +185,19 @@ interface ProviderConfig {
     apiVersion?: string;
     model?: string;
     /**
-     * OAuth bearer token (e.g. a Claude Code subscription token) used instead
-     * of an API key. When set on an Anthropic provider, the request uses
-     * `Authorization: Bearer` + the oauth beta header rather than `x-api-key`.
+     * Bearer token for an LLM **gateway or proxy** — what Anthropic documents
+     * `ANTHROPIC_AUTH_TOKEN` for — used instead of an API key. The request goes
+     * out as `Authorization: Bearer` rather than `x-api-key`.
+     *
+     * Requires `baseUrl`: a bearer is only valid at the gateway that issued it,
+     * so without one there is nowhere it can be sent, and the provider refuses
+     * rather than falling back to the public host.
+     *
+     * NOT a Claude subscription token. Those were accepted here once, with an
+     * `anthropic-beta: oauth-…` header; Anthropic does not permit third-party
+     * clients to route requests through Free/Pro/Max credentials, and such a
+     * token is now refused wherever it appears — including on a config passed
+     * straight to `createCascade()`.
      */
     authToken?: string;
     /** Where an adopted credential came from, e.g. "Claude Code". Informational. */
@@ -3764,11 +3774,46 @@ interface CascadeMdContent {
     systemPrompt: string;
 }
 
+/**
+ * Whether a provider entry carries a credential at all.
+ *
+ * `authToken` counts, not just `apiKey`: `cascade link` stores an adopted
+ * bearer there and `AnthropicProvider` runs on it happily. Every surface that
+ * asks "is this provider set up" goes through this one predicate, because the
+ * answer was written out by hand in four places — `hasUsableProvider`, the
+ * dashboard's `config:current`, `cascade doctor`, and the desktop's IPC
+ * settings snapshot — and each was fixed separately as it was noticed, the last
+ * of them two rounds after the first.
+ */
+declare function hasProviderCredential(p: {
+    apiKey?: string;
+    authToken?: string;
+    baseUrl?: string;
+} | undefined | null): boolean;
 declare function hasUsableProvider(providers: Array<{
     type: string;
     apiKey?: string;
     authToken?: string;
+    baseUrl?: string;
+    deploymentName?: string;
 }> | undefined): boolean;
+/**
+ * Write a provider's API key, clearing any bearer token it replaces.
+ *
+ * `AnthropicProvider` reads `authToken` in preference to `apiKey` whenever both
+ * are set, so a settings save that wrote only the key left the key the user had
+ * just typed silently unused — and from the UI that is indistinguishable from
+ * the save having failed. Every place a key is written from user input goes
+ * through here, because this was got wrong independently in three of them.
+ */
+declare function applyProviderApiKey(providers: Array<{
+    type: string;
+    apiKey?: string;
+    authToken?: string;
+    baseUrl?: string;
+}>, type: string, apiKey: string, extra?: {
+    baseUrl?: string;
+}): void;
 declare class ConfigManager {
     private config;
     private keystore;
@@ -3788,6 +3833,16 @@ declare class ConfigManager {
      * fallback for a list that is empty for some unrelated reason.
      */
     private retiredCleanup?;
+    /**
+     * How many dead subscription credentials THIS load removed. Per-load like
+     * `retiredCleanup`, for the same reason: a second load() on the same instance
+     * must not re-announce a migration that already happened.
+     */
+    private revokedCredentials;
+    /** Tier pins cleared by the revoked-credential migration this load. */
+    private revokedPins;
+    /** This load's revoked-credential explanation, joined with any retirement one. */
+    private revokedNotice?;
     /**
      * Human-readable migration notice held for a UI to display. `console.warn`
      * is not sufficient: the REPL clears the TTY immediately after load(), and
@@ -3805,10 +3860,59 @@ declare class ConfigManager {
     getStore(): MemoryStore;
     getCascadeMd(): CascadeMdContent | null;
     getWorkspacePath(): string;
-    save(): Promise<void>;
+    /**
+     * @param config What to persist. Defaults to the manager's own, but a
+     * transactional save hands in the validated copy it has NOT adopted yet —
+     * writing before adopting is what stops a run picking up configuration that
+     * never reached the disk (see `commitSettings`).
+     */
+    save(config?: CascadeConfig): Promise<void>;
     updateConfig(updates: Partial<CascadeConfig>): Promise<void>;
     getApiKey(provider: string): string | undefined;
+    /**
+     * The bearer token configured for a provider, if any.
+     *
+     * Companion to getApiKey(). A provider can be fully configured with only
+     * this — `cascade link` and ANTHROPIC_AUTH_TOKEN both produce it — so any
+     * surface that asks "is this provider set up" has to consult both, or it
+     * reports a working install as unconfigured.
+     */
+    getAuthToken(provider: string): string | undefined;
     private loadConfig;
+    /**
+     * Rewrite the workspace file with those tier pins removed.
+     *
+     * A targeted edit of the RAW file, not save(). By this point `this.config`
+     * carries environment keys and machine-global credentials, and save()
+     * serializes the whole object — so persisting through it would copy secrets
+     * kept 0600 in ~/.cascade-ai into a workspace file that may be 0644. Same
+     * reasoning as the migration write in loadConfig(); best-effort for the same
+     * reason, since a read-only config directory must not abort startup.
+     */
+    /**
+     * The Azure entries `AZURE_OPENAI_KEY` belongs to — possibly several.
+     *
+     * `AZURE_OPENAI_ENDPOINT` names the resource. Without one, a single
+     * configured resource is unambiguous and anything more is a guess — and
+     * guessing wrong writes a key to a resource that will reject it.
+     *
+     * ALL the deployments on that resource, not the first. An Azure key is
+     * resource-scoped, so every deployment there shares it, and Azure is
+     * configured one entry per deployment — the router binds each model to its
+     * own row, matching `deploymentName` against the model id, so filling only
+     * the first left the rest issuing requests with no key at all.
+     */
+    private azureEntriesForEnv;
+    private persistClearedPins;
+    /**
+     * `globalProviders` is the machine-global credential store, passed in
+     * READ-ONLY. This runs before mergeGlobalCredentials() on purpose — an
+     * exported key should outrank a stored one, which only holds while the
+     * injection goes first — but a few of the questions asked here are about the
+     * user's whole configuration rather than this workspace's file, and answering
+     * those from the workspace alone is what produced the gateway bug this
+     * argument fixes.
+     */
     private injectEnvKeys;
     /**
      * Follow a disambiguation rename into `tools.mcpTrusted`.
@@ -3857,11 +3961,394 @@ declare class ConfigManager {
     private ensureDefaultIdentity;
 }
 
+/** A provider row, as every settings surface manipulates it. */
+interface WritableProvider {
+    type: string;
+    apiKey?: string;
+    authToken?: string;
+    baseUrl?: string;
+    /** See `isLocalEndpoint` in core/router/pricing.ts. */
+    local?: boolean;
+}
+/**
+ * What the caller is able to say about where the key it is writing belongs.
+ *
+ * Not an endpoint value — a statement about the SURFACE. That is the whole
+ * point: `{ kind: 'provider-default' }` and `{ kind: 'preserve' }` both carry
+ * no URL and mean opposite things, and only the caller knows which it is.
+ */
+type CredentialEndpoint = 
+/** The user named a host in the same save. The key belongs there. */
+{
+    kind: 'at';
+    baseUrl: string;
+}
+/**
+ * The caller HAS an endpoint field for this provider and the user left it
+ * empty. That is a statement, and what it states depends on the provider: for
+ * one with a public host the key belongs there, and for one WITHOUT the row
+ * now addresses nothing at all.
+ *
+ * Not the same as `preserve`, though both arrive carrying no URL — collapsing
+ * them turned an explicit clear into "keep the old host", so a replacement
+ * key stayed attached to a URL the user had just deleted.
+ */
+ | {
+    kind: 'cleared';
+}
+/**
+ * The caller has no endpoint field for this provider at all.
+ *
+ * Absence here is a limit of the surface, not evidence, so an untouched
+ * credential keeps whatever host the row names. It is NOT enough to place a
+ * NEW secret: see the refusal in `applyProviderCredential`.
+ */
+ | {
+    kind: 'preserve';
+};
+/** Whether a key was written, and if not, why the caller has to ask a human. */
+type CredentialWriteOutcome = {
+    written: true;
+} | {
+    written: false;
+    reason: 'ambiguous-scope' | 'unroutable';
+};
+/**
+ * Read the intent out of a settings payload's `endpoints` map.
+ *
+ * The KEY's presence is the signal, not its value. A surface that can address a
+ * provider's endpoint sends an entry for it — possibly `undefined`, meaning the
+ * field was shown and left blank — and one that cannot sends no entry at all.
+ * That distinction is exactly the one `CredentialEndpoint` needs and the only
+ * place it survives.
+ */
+declare function endpointFromSettingsPayload(endpoints: Record<string, string | undefined> | undefined, type: string): CredentialEndpoint;
+/**
+ * Write a user-supplied key together with the host it belongs to.
+ *
+ * `applyProviderApiKey()` only touches `baseUrl` when it is handed one, which
+ * is right for the field and wrong for the pairing — so every surface that
+ * wrote a key through it kept whatever host was already on the row. Callers go
+ * through here instead, and say what they know.
+ */
+declare function applyProviderCredential(providers: WritableProvider[], type: string, apiKey: string, endpoint: CredentialEndpoint): CredentialWriteOutcome;
+/** What happens to the credential already on a row when its endpoint is edited. */
+type CredentialDisposition = 
+/** Nothing typed, and the endpoint still identifies the same host — it stays. */
+'keep'
+/** The endpoint moved or was cleared with nothing typed — the pairing is gone. */
+ | 'clear'
+/** A key was typed in this save; it is the credential now, and must not be touched. */
+ | 'replaced';
+/**
+ * What becomes of a stored credential when the endpoint field is edited.
+ *
+ * Three outcomes, not two. This started life as a boolean "does the credential
+ * survive?", and the caller read `false` as "delete the credential" — so a save
+ * carrying BOTH a new key and a new endpoint wrote the key and then deleted it,
+ * because `false` also meant "a replacement was supplied". A user typing a key
+ * into Settings watched it vanish. `'replaced'` exists so that case cannot be
+ * confused with `'clear'` again.
+ */
+declare function credentialDispositionForEdit(existing: {
+    type: string;
+    baseUrl?: string;
+}, nextBaseUrl: string | undefined, replacementKey: string | undefined): CredentialDisposition;
+/**
+ * Apply ONE provider's endpoint edit, retiring the credential when the host
+ * changes and nothing was typed to replace it.
+ *
+ * This is the endpoint-ONLY half — the key field left blank. It is reached from
+ * three places (onboarding, the Settings save, and the live dashboard), and the
+ * dashboard did not reach it at all until the sibling was noticed: a standalone
+ * `cascade dashboard` reported a saved endpoint change it had never applied.
+ */
+declare function applyEndpointEdit(existing: WritableProvider, nextBaseUrl: string | undefined, replacementKey: string | undefined): void;
+/** What a settings save could not store, and why. */
+interface SettingsCredentialResult {
+    refused: Array<{
+        type: string;
+        reason: 'ambiguous-scope' | 'unroutable';
+    }>;
+}
+/** A refusal, phrased for the person who typed the key. */
+declare function explainRefusal(type: string, reason: 'ambiguous-scope' | 'unroutable'): string;
+/** The non-Azure halves of a settings save. */
+interface SettingsCredentialPayload {
+    keys?: Record<string, string | undefined>;
+    endpoints?: Record<string, string | undefined>;
+}
+/**
+ * Apply the non-Azure `keys` and `endpoints` halves of a settings save, in order.
+ *
+ * The ORDER is the whole point, and it is why this is one function rather than
+ * two loops in each caller. Keys are written first and endpoints second, so the
+ * endpoint step has to know that a key it is about to consider retiring may be
+ * the one just written. Expressed as two loops with a boolean between them,
+ * that knowledge went missing and the save deleted the key it had installed a
+ * few lines earlier — with no test able to see it, because the loops lived
+ * inside `ipcMain.handle`.
+ */
+declare function applySettingsCredentials(providers: WritableProvider[], data: SettingsCredentialPayload): SettingsCredentialResult;
+
+/** One Azure deployment as the settings panel sends it. */
+interface AzureDeploymentInput {
+    label?: string;
+    apiKey?: string;
+    baseUrl?: string;
+    deploymentName?: string;
+    apiVersion?: string;
+    /**
+     * Base-model override and pricing region.
+     *
+     * The panel has no controls for these, but the config does and
+     * `azureModelForDeployment()` reads both — `model` for the real base-model
+     * identity, `region` for Azure's regional pricing. The save REPLACES the
+     * whole Azure list, so leaving them out of the DTO meant an unrelated or
+     * no-op Settings save silently dropped a base-model mapping and a region,
+     * changing routing and cost accounting through controls that were never
+     * shown. Round-tripped so a replacement is a replacement of the fields the
+     * editor owns, not of the row.
+     */
+    model?: string;
+    region?: string;
+}
+/** The complete Settings save, as both surfaces send it. */
+interface SettingsPayload {
+    keys?: Record<string, string | undefined>;
+    endpoints?: Record<string, string | undefined>;
+    models?: Record<string, string | undefined>;
+    budget?: {
+        maxCostPerRun?: number;
+        autoBias?: string;
+        dailyBudgetUsd?: number;
+        sessionBudgetUsd?: number;
+        maxTokensPerRun?: number;
+        warnAtPct?: number;
+    };
+    azureDeployments?: AzureDeploymentInput[];
+    webSearch?: {
+        searxngUrl?: string;
+        braveApiKey?: string;
+        tavilyApiKey?: string;
+    };
+    advanced?: Record<string, unknown>;
+}
+/**
+ * The prior Azure row a saved deployment may inherit its key from.
+ *
+ * Matched on deployment name AND resource. An Azure key is resource-scoped, so
+ * matching the name alone meant moving deployment "prod" from resource A to
+ * resource B with a blank key field copied A's key onto B — a credential sent
+ * to a resource that never issued it.
+ */
+declare function priorAzureRow<T extends {
+    deploymentName?: string;
+    baseUrl?: string;
+    model?: string;
+    region?: string;
+}>(prior: readonly T[], incoming: {
+    deploymentName?: string;
+    baseUrl?: string;
+}): T | undefined;
+/** Apply the whole payload to a live config, in place. */
+declare function applySettingsPayload(config: CascadeConfig, data: SettingsPayload): SettingsCredentialResult;
+/**
+ * The redacted Settings snapshot, as the panel reads it back.
+ *
+ * The read counterpart to `applySettingsPayload`, and it has to be as complete
+ * as the write is. The desktop's IPC reply carried every section; the socket's
+ * `config:current` carried models, two budget fields, key status and endpoints.
+ * That was merely incomplete while the socket save was also partial — and
+ * became DESTRUCTIVE the moment the save started applying the whole payload:
+ * the panel keeps its own defaults for anything a snapshot does not fill
+ * (`azureDeployments: []`, a blank SearXNG URL, the advanced defaults) and
+ * serializes them on every save. A socket-only save of an unrelated setting
+ * could therefore delete every Azure deployment and reset advanced knobs the
+ * user had never seen.
+ *
+ * Secrets never come back — only whether one is set.
+ */
+interface SettingsSnapshot {
+    models: Record<string, string>;
+    budget: {
+        maxCostPerRun?: number;
+        autoBias?: string;
+        dailyBudgetUsd?: number;
+        sessionBudgetUsd?: number;
+        maxTokensPerRun?: number;
+        warnAtPct?: number;
+    };
+    providersWithKey: string[];
+    endpoints: Record<string, string>;
+    azureDeployments: Array<{
+        label?: string;
+        baseUrl?: string;
+        deploymentName?: string;
+        apiVersion?: string;
+        model?: string;
+        region?: string;
+        hasKey: boolean;
+    }>;
+    webSearch: {
+        searxngUrl?: string;
+        hasBraveKey: boolean;
+        hasTavilyKey: boolean;
+    };
+    advanced: Record<string, unknown>;
+}
+declare function settingsSnapshot(config: CascadeConfig): SettingsSnapshot;
+/** The outcome of a settings save, for whichever surface asked for it. */
+interface SettingsCommitResult {
+    /** False only when nothing was stored — the live config is untouched. */
+    ok: boolean;
+    /** Credentials deliberately not written, with the reason to show the user. */
+    refused: SettingsCredentialResult['refused'];
+    /** Why the save failed, when it did. */
+    error?: string;
+}
+/**
+ * Apply a settings save as a TRANSACTION, for every surface that has one.
+ *
+ * Both writers had the same bug and it was fixed in only one of them: the
+ * payload was applied to the LIVE config and persisted afterwards, so a failed
+ * write left the change running while the caller was told it had not saved. The
+ * socket handler was made transactional; the desktop IPC bridge — the primary
+ * path, tried before the socket — was not. Rather than stage in two places,
+ * both call this.
+ *
+ * The order matters and each step exists for a reported failure:
+ *
+ *  1. apply the payload to a COPY, so a rejected save never runs;
+ *  2. VALIDATE, and keep what the validator returns — it applies schema
+ *     defaults, and discarding it left a config missing the fields a cleared
+ *     cap should have fallen back to until the next restart re-applied them;
+ *  3. write that validated copy, and only then
+ *  4. adopt it into the live object IN PLACE, because the desktop main process
+ *     holds a reference to it and swapping would strand that alias.
+ *
+ * Writing BEFORE adopting is the part that took two attempts. An earlier
+ * revision adopted first and rolled back on failure, which reads as
+ * equivalent and is not: `write()` is asynchronous filesystem I/O, and the
+ * embedded `DashboardServer` reads that same live object when a run starts. A
+ * run beginning inside that window used configuration that was never
+ * persisted — and for an endpoint or credential change, may already have sent
+ * the new secret somewhere — before the failed write rolled memory back and
+ * the panel truthfully reported that nothing had saved. Handing the writer the
+ * validated config as an argument, rather than letting it read the live one,
+ * is what removes the window rather than narrowing it.
+ *
+ * There is consequently no rollback image: nothing is modified until the write
+ * has landed.
+ *
+ * The caller syncs machine-global credentials only when this returns `ok`.
+ */
+declare function commitSettings(live: CascadeConfig, data: SettingsPayload, write: (config: CascadeConfig) => Promise<{
+    ok: true;
+} | {
+    ok: false;
+    error: string;
+}> | ({
+    ok: true;
+} | {
+    ok: false;
+    error: string;
+})): Promise<SettingsCommitResult>;
+
+/**
+ * Keep localhost intact. Node's `dns.setDefaultResultOrder('ipv4first')` handles IPv4 priority process-wide.
+ * We no longer forcefully rewrite `localhost` to `127.0.0.1` as it breaks IPv6-only environments (e.g. ::1).
+ */
+declare function preferIpv4Host(url: string | undefined): string | undefined;
+/**
+ * An endpoint URL reduced to what identifies the host it addresses.
+ *
+ * Trailing slashes go because every provider client drops them anyway; case
+ * goes because the meaningful part is a hostname, which is case-insensitive.
+ * A missing or blank endpoint normalizes to the empty string, so rows with no
+ * endpoint compare equal to each other and to nothing else.
+ *
+ * Lives here rather than in `azure-endpoint.ts` because the question is not
+ * Azure's: "is this bearer's gateway the same host as the one already
+ * configured?" needs the identical normalization, and writing it out a second
+ * time is how two call sites start disagreeing about what "same endpoint"
+ * means.
+ */
+declare function normalizeEndpoint(url: string | undefined | null): string;
+/** Whether two endpoint URLs address the same host. */
+declare function sameEndpoint(a: string | undefined | null, b: string | undefined | null): boolean;
+interface NodeHttpFetchOptions {
+    /**
+     * When set, every redirect hop (not just the initial request) must resolve
+     * to this exact origin, or the fetch rejects instead of following it. For
+     * a caller sending a credential in `init.headers` (a bearer token, a PAT),
+     * omitting this means that credential is replayed on ANY origin a 3xx
+     * response points to — a malicious or misconfigured redirect, including an
+     * HTTPS→HTTP downgrade, would silently exfiltrate it, since `init` (and
+     * its headers) is reused verbatim on the followed request below. Every
+     * existing caller omits this and keeps today's follow-anywhere behaviour
+     * unchanged; it exists for exactly the callers that attach a credential.
+     */
+    allowedRedirectOrigin?: string;
+}
+declare function nodeHttpFetch(input: string | URL | Request, init?: RequestInit, redirectCount?: number, opts?: NodeHttpFetchOptions): Promise<Response>;
+
+/** Whether absence of `baseUrl` resolves to a known public host for this type. */
+declare function hasDefaultEndpoint(type: string): boolean;
+/**
+ * The host a credential on this row is scoped to, normalized for comparison.
+ *
+ * Returns `null` only when the type has no default and no endpoint is set —
+ * the genuinely unscoped case, where there is nothing to compare and a caller
+ * must not infer agreement.
+ */
+declare function credentialEndpointIdentity(type: string, baseUrl?: string): string | null;
+/**
+ * Whether a credential scoped to `a` is still scoped to `b` for this provider.
+ *
+ * Conservative when it cannot tell: two unscoped configurations are the same
+ * (nothing changed), but an unscoped one and a configured one are NOT — that
+ * is a host being introduced where there was none, which is exactly the edit
+ * that must retire a key.
+ */
+declare function sameCredentialEndpoint(type: string, a: string | undefined, b: string | undefined): boolean;
+
+/** Whether two Azure endpoints name the same resource. */
+declare function sameAzureEndpoint(a: string | undefined | null, b: string | undefined | null): boolean;
+
 interface DashboardSocketOptions {
     authRequired: boolean;
     secret: string;
     corsOrigin?: string | string[];
 }
+/**
+ * The Settings save as it arrives over the socket — the SAME type the desktop
+ * IPC bridge takes.
+ *
+ * It was a narrower hand-written copy, and the narrowing was not harmless: the
+ * panel posts one payload to both surfaces, so a field missing from this
+ * declaration was not missing from the wire, merely invisible to the code
+ * handling it. That hid the endpoint a key was typed beside (a public-host key
+ * ended up stored against a gateway) and then hid budget, Azure, web-search and
+ * advanced entirely (controls that reported success and changed nothing).
+ */
+type ConfigUpdatePayload = SettingsPayload;
+/** What the save could not store, phrased for the person who typed it. */
+interface ConfigUpdateResult {
+    refused: Array<{
+        type: string;
+        reason: string;
+        message: string;
+    }>;
+    /** What is actually stored now — the panel re-hydrates from this. */
+    snapshot?: SettingsSnapshot;
+    /**
+     * Set when the save could not be written to disk. Its absence is the only
+     * thing that makes this acknowledgement mean "durable" rather than merely
+     * "the handler ran".
+     */
+    error?: string;
+}
 declare class DashboardSocket {
     private io;
     private authRequired;
@@ -3923,14 +4410,16 @@ declare class DashboardSocket {
         note?: string;
     }) => void): void;
     onSessionSteer(callback: (message: string, sessionId?: string, nodeId?: string) => void): void;
-    onConfigUpdate(callback: (data: {
-        keys?: Record<string, string>;
-        models?: Record<string, string>;
-        budget?: {
-            maxCostPerRun?: number;
-            autoBias?: string;
-        };
-    }) => void): void;
+    /**
+     * The handler's result is ACKNOWLEDGED to the caller.
+     *
+     * A settings save can be partly refused — a key whose host cannot be
+     * determined is deliberately not stored — and this path had no way to say so,
+     * so the panel cleared the input and reported success over a key the backend
+     * had dropped. Socket.IO's own ack channel carries it back, which needs no
+     * new event name and cannot be missed by a client that forgot to subscribe.
+     */
+    onConfigUpdate(callback: (data: ConfigUpdatePayload) => Promise<ConfigUpdateResult>): void;
     emitToSocket(socketId: string, event: string, data: unknown): void;
     onConfigGet(callback: (socketId: string) => void): void;
     onCascadeRun(callback: (prompt: string, model: string, socketId: string, sessionId?: string, forceTier?: string) => void): void;
@@ -4009,7 +4498,41 @@ declare class DashboardServer {
      * made over the socket (Settings → Save) persist across restarts. Best-effort:
      * a write failure is logged but never crashes the running dashboard.
      */
+    /**
+     * Returns the durability of the WORKSPACE write, because a caller
+     * acknowledging a save has to know it happened.
+     *
+     * This was `void` and swallowed every filesystem error, so a read-only
+     * config path or a full disk produced: the live object mutated, the write
+     * failed, the socket acknowledged success, and the panel cleared the keys the
+     * user had typed. The changes then vanished at the next restart. "The handler
+     * ran" is not "the save is durable".
+     *
+     * The global-credential sync below is genuinely best-effort — it is a
+     * convenience copy, and failing it does not lose what the user just entered.
+     */
+    /**
+     * @param config REQUIRED, with no default. `commitSettings` writes the
+     * validated copy BEFORE adopting it, so a writer that reached for
+     * `this.config` instead would persist the configuration being replaced — and
+     * a default parameter is exactly the affordance that lets that happen
+     * silently and still typecheck.
+     */
     private persistConfig;
+    /**
+     * Copy provider credentials to the machine-global store, so keys saved over
+     * the socket survive a workspace switch — the same sync `ConfigManager.save()`
+     * performs.
+     *
+     * Separate from the workspace write, and called only AFTER it succeeds. It
+     * used to run unconditionally inside `persistConfig()`, so a failed workspace
+     * write still pushed the provider half of a rejected save into the global
+     * store: half the change persisted, behind an error saying none of it had.
+     *
+     * Best-effort on its own account: this is a convenience copy, and failing it
+     * does not lose what the user just entered.
+     */
+    private syncGlobalCredentials;
     /**
      * Produce a stable dashboard JWT signing secret.
      *
@@ -5219,27 +5742,6 @@ declare class CascadeToolError extends Error {
     constructor(userMessage: string, cause?: unknown, retryable?: boolean);
 }
 
-/**
- * Keep localhost intact. Node's `dns.setDefaultResultOrder('ipv4first')` handles IPv4 priority process-wide.
- * We no longer forcefully rewrite `localhost` to `127.0.0.1` as it breaks IPv6-only environments (e.g. ::1).
- */
-declare function preferIpv4Host(url: string | undefined): string | undefined;
-interface NodeHttpFetchOptions {
-    /**
-     * When set, every redirect hop (not just the initial request) must resolve
-     * to this exact origin, or the fetch rejects instead of following it. For
-     * a caller sending a credential in `init.headers` (a bearer token, a PAT),
-     * omitting this means that credential is replayed on ANY origin a 3xx
-     * response points to — a malicious or misconfigured redirect, including an
-     * HTTPS→HTTP downgrade, would silently exfiltrate it, since `init` (and
-     * its headers) is reused verbatim on the followed request below. Every
-     * existing caller omits this and keeps today's follow-anywhere behaviour
-     * unchanged; it exists for exactly the callers that attach a credential.
-     */
-    allowedRedirectOrigin?: string;
-}
-declare function nodeHttpFetch(input: string | URL | Request, init?: RequestInit, redirectCount?: number, opts?: NodeHttpFetchOptions): Promise<Response>;
-
 /** Selectable base models, in the order a picker should show them. */
 declare const AZURE_BASE_MODELS: readonly string[];
 declare function inferAzureBaseModel(deploymentName: string): string | null;
@@ -5420,6 +5922,24 @@ interface RetiredProviderCleanup {
     removed: string[];
     /** Tier keys (`t1`/`t2`/`t3`) whose pin named a retired provider and was cleared. */
     clearedPins: string[];
+    /**
+     * Dead Claude subscription credentials dropped from an incoming sync bundle.
+     *
+     * Reported here rather than left to `removed`, which names retired provider
+     * TYPES — `anthropic` is not retired, its credential is. Without this a
+     * bundle whose only content was the dead token produced an empty cleanup, so
+     * both callers announced a clean sync while the one key it carried had been
+     * discarded.
+     */
+    revokedCredentials?: number;
+    /**
+     * Incoming rows dropped for carrying a bearer with no gateway.
+     *
+     * A separate count from `revokedCredentials`: that one is a credential
+     * Anthropic has revoked, this one is a live token with nowhere to send it.
+     * Distinct causes, distinct advice.
+     */
+    unusableCredentials?: number;
 }
 
 /**
@@ -5472,4 +5992,4 @@ declare function gatherSyncBundle(config: CascadeConfig): SyncBundle;
 /** Merge a pulled bundle into a config, returning the updated config to persist. */
 declare function applySyncBundle(bundle: SyncBundle, config: CascadeConfig, cleanup?: RetiredProviderCleanup): CascadeConfig;
 
-export { AZURE_BASE_MODELS, AZURE_BASE_URL_TEMPLATE, type AcceptanceProbe, type AcceptanceResult, type AcceptanceVerdict, type ApprovalRequest, type ApprovalResponse, type AuditEntry, AuditLogger, type BenchmarksConfig, type Block, type BudgetConfig, CASCADE_AUDIT_FILE, CASCADE_CONFIG_DIR, CASCADE_CONFIG_FILE, CASCADE_DASHBOARD_SECRET_FILE, CASCADE_DB_FILE, CASCADE_IGNORE_FILE, CASCADE_KEYSTORE_FILE, CASCADE_MD_FILE, CASCADE_VERSION, CHARS_PER_TOKEN, COMPLEXITY_T2_COUNT, Cascade, CascadeCancelledError, type CascadeConfig, type CascadeEvent, type CascadeEventType, CascadeIgnore, type CascadeMessage, CascadeRouter, type CascadeRunOptions, type CascadeRunResult, type CascadeThemeName, CascadeToolError, type ChartSeries, type ChartSpec, type Chunk, type ChunkOptions, CloudClient, type CloudConversation, type CloudMessage, type CloudSession, type CloudSessionStore, type CloudTurnInput, type CloudUser, type CodeChunkOptions, type CodeChunker, CodeSearchTool, type CompileTaskGraphOptions, type CompiledTaskGraph, type CompleteFn, type CompletedNode, ConfigManager, type ConversationMessage, type CurrentPageProvider, type CurrentPageSnapshot, CurrentPageTool, DEFAULT_API_PORT, DEFAULT_APPROVAL_REQUIRED, DEFAULT_AUTO_SUMMARIZE_AT, DEFAULT_CLOUD_URL, DEFAULT_CONTEXT_LIMIT, DEFAULT_DASHBOARD_PORT, DEFAULT_MAX_SESSION_MESSAGES, DEFAULT_RETENTION_DAYS, DEFAULT_THEME, DOCUMENT_MIME, type DashboardConfig, DashboardServer, DependencyScheduler, type DeviceStart, type DiscoveredMcpTool, type DistilledFact, type ChartKind as DocumentChartKind, type DocumentFormat, type Embedder, type EncryptedBlob, type EscalationDecision, type EscalationPayload, type ExtendedContextConfig, type FileManifest, FileMcpOAuthStore, GLOBAL_CONFIG_DIR, GLOBAL_CREDENTIALS_FILE, GLOBAL_DB_FILE, GLOBAL_KEYSTORE_FILE, GLOBAL_RUNTIME_DB_FILE, GenerateDocumentTool, type GenerateOptions, type GenerateResult, type GraphFactSource, GraphRetriever, type GraphSearchOptions, GraphSearchTool, type HookDefinition, type HooksConfig, HooksRunner, type Identity, type ImageAttachment, type ImageByteLoader, type ImageInfo, type ImageRef, type InlineRun, Keystore, LLMReranker, LM_STUDIO_BASE_URL, type LegacyThemeName, type LoadedImage, MAX_PAGE_TEXT_CHARS, MCP_TOOL_PREFIX, MODELS, type ManifestDiff, McpClient, type McpDiscoveryResult, McpOAuthProvider, type McpOAuthState, type McpOAuthStore, type McpServerConfig$1 as McpServerConfig, type McpServerRename, type MemoryConfig, MemoryStore, type Message, type MessageContent, type MessagePayload, type MessageStatus, type MessageType, type ModelInfo, type ModelOverrides, type NativeProvider, OLLAMA_BASE_URL, OpenAICompatibleEmbedder, type OpenAIEmbedderOptions, PROVIDER_DISPLAY_NAMES, type PeerMessage, type PeerMessageEvent, type PeerSyncPayload, type PeerSyncType, type PermissionDecision, type PermissionDecisionPayload, type PermissionRequest, type PermissionTrailEntry, type PlanReviewConfig, type ProviderConfig, type ProviderType, RESUME_SCHEMA_VERSION, type RankedFact, type RefreshResult, type RenderOptions, type Reranker, type ResumeCheckpoint, type ResumeReason, ResumeStore, type ResumeStoreOptions, type RetrievalContext, type RetrievalMode, type RetrievalPlan, Retriever, type RetrieverSearchOptions, type RuntimeNode, type RuntimeNodeLog, type RuntimeRefreshPayload, type RuntimeScope, type RuntimeSession, type RuntimeSnapshotPayload, type ScheduledTask, type SchedulerExecutionMode, type SchedulerHooks, type SchedulerOptions, type SchedulerResult, type ScoredChunk, type SearchOptions, type Session, type SessionCheckpoint, type SessionMetadata, type SessionSubscriptionPayload, type Slide, SqliteVectorStore, type StatusUpdate, type StoredMessage, type StreamChunk, type SyncBundle, T1Administrator, type T1ToT2Assignment, T1_MODEL_PRIORITY, T2Manager, type T2Result, type T2ToT3Assignment, T2_MODEL_PRIORITY, type T3Result, type T3ResultPayload, type T3SubtaskSpec, T3Worker, T3_MODEL_PRIORITY, THEME_NAMES, TOOL_NAMES, type TaskComplexity, type TaskGraph, type TaskGraphInputNode, type TaskGraphIssue, type TaskGraphIssueCode, type TaskGraphNode, type TaskGraphNodeKind, TaskGraphValidationError, type TaskGraphValidationMode, TaskScheduler, Telemetry, type TelemetryConfig, type Theme, type ThemeColors, type ThemeName, type TierConfig, type TierLimits, type TierRole, type TierStatus, type TokenUsage, type ToolCall, type ToolDefinition, type ToolExecuteOptions, ToolRegistry, type ToolResult, type ToolsConfig, VISION_MODEL_PRIORITY, type VectorStore, type WebSearchConfig, type WebhookConfig, type WorkspaceConfig, type WorkspaceFileReader, WorkspaceIndex, type WorkspaceIndexOptions, applySyncBundle, azureModelForDeployment, beginMcpOAuth, buildDocumentTools, buildManifest, buildSessionTranscript, bytesToBase64, cagCharBudget, chartKind, chartToTableRows, chatCompleterFromProviders, chunkCode, chunkText, compileSectionGraph, compileSubtaskGraph, compileTaskGraph, completeMcpOAuth, connectMcpWithLoopbackOAuth, createCascade, decryptJSON as decryptSyncBlob, diffManifest, disambiguateMcpServerNames, discoverMcpAuthServer, discoverMcpTools, distillSessionFacts, embedderFromProviders, encryptJSON as encryptSyncBlob, evaluateAcceptance, extractCharts, failures, fileExt, fileOAuthProvider, gatherSyncBundle, hasUsableProvider, hashContent, heuristicCodeChunker, inferAzureBaseModel, inlineRuns, isDocumentFormat, isMcpToolName, matchImageLine, mcpServerPrefix, mcpToolName, nodeHttpFetch, parseBlocks, parseChartSpec, parseDelimited, parseRankOrder, parseSlide, planRetrieval, preferIpv4Host, reciprocalRankFusion, refreshMcpToken, removeMcpServerDenials, renderDocument, renderDocx, renderPptx, renderXlsx, runCascade, sessionWorthRemembering, sniffImage, splitSlides, streamCascade, stripInline, summarizeCompleted, undecided, uniqueMcpServerName };
+export { AZURE_BASE_MODELS, AZURE_BASE_URL_TEMPLATE, type AcceptanceProbe, type AcceptanceResult, type AcceptanceVerdict, type ApprovalRequest, type ApprovalResponse, type AuditEntry, AuditLogger, type AzureDeploymentInput, type BenchmarksConfig, type Block, type BudgetConfig, CASCADE_AUDIT_FILE, CASCADE_CONFIG_DIR, CASCADE_CONFIG_FILE, CASCADE_DASHBOARD_SECRET_FILE, CASCADE_DB_FILE, CASCADE_IGNORE_FILE, CASCADE_KEYSTORE_FILE, CASCADE_MD_FILE, CASCADE_VERSION, CHARS_PER_TOKEN, COMPLEXITY_T2_COUNT, Cascade, CascadeCancelledError, type CascadeConfig, type CascadeEvent, type CascadeEventType, CascadeIgnore, type CascadeMessage, CascadeRouter, type CascadeRunOptions, type CascadeRunResult, type CascadeThemeName, CascadeToolError, type ChartSeries, type ChartSpec, type Chunk, type ChunkOptions, CloudClient, type CloudConversation, type CloudMessage, type CloudSession, type CloudSessionStore, type CloudTurnInput, type CloudUser, type CodeChunkOptions, type CodeChunker, CodeSearchTool, type CompileTaskGraphOptions, type CompiledTaskGraph, type CompleteFn, type CompletedNode, ConfigManager, type ConversationMessage, type CredentialDisposition, type CredentialEndpoint, type CredentialWriteOutcome, type CurrentPageProvider, type CurrentPageSnapshot, CurrentPageTool, DEFAULT_API_PORT, DEFAULT_APPROVAL_REQUIRED, DEFAULT_AUTO_SUMMARIZE_AT, DEFAULT_CLOUD_URL, DEFAULT_CONTEXT_LIMIT, DEFAULT_DASHBOARD_PORT, DEFAULT_MAX_SESSION_MESSAGES, DEFAULT_RETENTION_DAYS, DEFAULT_THEME, DOCUMENT_MIME, type DashboardConfig, DashboardServer, DependencyScheduler, type DeviceStart, type DiscoveredMcpTool, type DistilledFact, type ChartKind as DocumentChartKind, type DocumentFormat, type Embedder, type EncryptedBlob, type EscalationDecision, type EscalationPayload, type ExtendedContextConfig, type FileManifest, FileMcpOAuthStore, GLOBAL_CONFIG_DIR, GLOBAL_CREDENTIALS_FILE, GLOBAL_DB_FILE, GLOBAL_KEYSTORE_FILE, GLOBAL_RUNTIME_DB_FILE, GenerateDocumentTool, type GenerateOptions, type GenerateResult, type GraphFactSource, GraphRetriever, type GraphSearchOptions, GraphSearchTool, type HookDefinition, type HooksConfig, HooksRunner, type Identity, type ImageAttachment, type ImageByteLoader, type ImageInfo, type ImageRef, type InlineRun, Keystore, LLMReranker, LM_STUDIO_BASE_URL, type LegacyThemeName, type LoadedImage, MAX_PAGE_TEXT_CHARS, MCP_TOOL_PREFIX, MODELS, type ManifestDiff, McpClient, type McpDiscoveryResult, McpOAuthProvider, type McpOAuthState, type McpOAuthStore, type McpServerConfig$1 as McpServerConfig, type McpServerRename, type MemoryConfig, MemoryStore, type Message, type MessageContent, type MessagePayload, type MessageStatus, type MessageType, type ModelInfo, type ModelOverrides, type NativeProvider, OLLAMA_BASE_URL, OpenAICompatibleEmbedder, type OpenAIEmbedderOptions, PROVIDER_DISPLAY_NAMES, type PeerMessage, type PeerMessageEvent, type PeerSyncPayload, type PeerSyncType, type PermissionDecision, type PermissionDecisionPayload, type PermissionRequest, type PermissionTrailEntry, type PlanReviewConfig, type ProviderConfig, type ProviderType, RESUME_SCHEMA_VERSION, type RankedFact, type RefreshResult, type RenderOptions, type Reranker, type ResumeCheckpoint, type ResumeReason, ResumeStore, type ResumeStoreOptions, type RetrievalContext, type RetrievalMode, type RetrievalPlan, Retriever, type RetrieverSearchOptions, type RuntimeNode, type RuntimeNodeLog, type RuntimeRefreshPayload, type RuntimeScope, type RuntimeSession, type RuntimeSnapshotPayload, type ScheduledTask, type SchedulerExecutionMode, type SchedulerHooks, type SchedulerOptions, type SchedulerResult, type ScoredChunk, type SearchOptions, type Session, type SessionCheckpoint, type SessionMetadata, type SessionSubscriptionPayload, type SettingsCommitResult, type SettingsCredentialResult, type SettingsPayload, type SettingsSnapshot, type Slide, SqliteVectorStore, type StatusUpdate, type StoredMessage, type StreamChunk, type SyncBundle, T1Administrator, type T1ToT2Assignment, T1_MODEL_PRIORITY, T2Manager, type T2Result, type T2ToT3Assignment, T2_MODEL_PRIORITY, type T3Result, type T3ResultPayload, type T3SubtaskSpec, T3Worker, T3_MODEL_PRIORITY, THEME_NAMES, TOOL_NAMES, type TaskComplexity, type TaskGraph, type TaskGraphInputNode, type TaskGraphIssue, type TaskGraphIssueCode, type TaskGraphNode, type TaskGraphNodeKind, TaskGraphValidationError, type TaskGraphValidationMode, TaskScheduler, Telemetry, type TelemetryConfig, type Theme, type ThemeColors, type ThemeName, type TierConfig, type TierLimits, type TierRole, type TierStatus, type TokenUsage, type ToolCall, type ToolDefinition, type ToolExecuteOptions, ToolRegistry, type ToolResult, type ToolsConfig, VISION_MODEL_PRIORITY, type VectorStore, type WebSearchConfig, type WebhookConfig, type WorkspaceConfig, type WorkspaceFileReader, WorkspaceIndex, type WorkspaceIndexOptions, applyEndpointEdit, applyProviderApiKey, applyProviderCredential, applySettingsCredentials, applySettingsPayload, applySyncBundle, azureModelForDeployment, beginMcpOAuth, buildDocumentTools, buildManifest, buildSessionTranscript, bytesToBase64, cagCharBudget, chartKind, chartToTableRows, chatCompleterFromProviders, chunkCode, chunkText, commitSettings, compileSectionGraph, compileSubtaskGraph, compileTaskGraph, completeMcpOAuth, connectMcpWithLoopbackOAuth, createCascade, credentialDispositionForEdit, credentialEndpointIdentity, decryptJSON as decryptSyncBlob, diffManifest, disambiguateMcpServerNames, discoverMcpAuthServer, discoverMcpTools, distillSessionFacts, embedderFromProviders, encryptJSON as encryptSyncBlob, endpointFromSettingsPayload, evaluateAcceptance, explainRefusal, extractCharts, failures, fileExt, fileOAuthProvider, gatherSyncBundle, hasDefaultEndpoint, hasProviderCredential, hasUsableProvider, hashContent, heuristicCodeChunker, inferAzureBaseModel, inlineRuns, isDocumentFormat, isMcpToolName, matchImageLine, mcpServerPrefix, mcpToolName, nodeHttpFetch, normalizeEndpoint, parseBlocks, parseChartSpec, parseDelimited, parseRankOrder, parseSlide, planRetrieval, preferIpv4Host, priorAzureRow, reciprocalRankFusion, refreshMcpToken, removeMcpServerDenials, renderDocument, renderDocx, renderPptx, renderXlsx, runCascade, sameAzureEndpoint, sameCredentialEndpoint, sameEndpoint, sessionWorthRemembering, settingsSnapshot, sniffImage, splitSlides, streamCascade, stripInline, summarizeCompleted, undecided, uniqueMcpServerName };