dsh-connect-workbuddy 2.0.6 → 2.0.11

package/lib/index.d.ts

@@ -31,6 +31,31 @@ interface WorkBuddyCredential {
    */
   lastRefreshAtMs?: number;
 }
+/**
+ * Why one probed path did not yield an account.
+ *
+ * These are safe to surface: they carry paths and cause only, never token
+ * material. `encrypted` is the WorkBuddy-specific one — a build whose token
+ * fields are encrypted cannot be read at all unless the desktop app itself is
+ * present to hand over its at-rest key, so "sign in again" is the wrong advice
+ * for it (the user may be perfectly signed in).
+ *
+ * `wrong-region` is the second WorkBuddy-specific one, and it exists because of
+ * a real bug: a region-scoped store filters out every credential that belongs to
+ * the other region, so a candidate file holding a perfectly valid sign-in for
+ * the other tab was dropped by exactly the same `continue` that drops malformed
+ * files. The file then appeared in NO list at all — not an account (filtered by
+ * region) and not a failure (it parsed) — so a card could name two paths while
+ * its report listed one, and the user's actual, working sign-in was the one
+ * made invisible. Reporting it is also the most useful answer we can give: the
+ * user is signed in, and merely on the wrong tab.
+ */
+interface WorkBuddyCandidateFailure {
+  path: string;
+  source: 'desktop' | 'dsh';
+  reason: 'missing' | 'unreadable' | 'invalid' | 'encrypted' | 'wrong-region';
+  message?: string;
+}
 /** Read-only sign-in summary for status and doctor output. */
 interface WorkBuddyAuthStatus {
   state: 'signed-in' | 'signed-out';
@@ -40,6 +65,36 @@ interface WorkBuddyAuthStatus {
   domain?: string;
   source?: 'desktop' | 'dsh';
 }
+/**
+ * Marker for a credential that EXISTS but could not be decrypted.
+ *
+ * Identified by {@link ENCRYPTED_CREDENTIAL_CODE} rather than `instanceof`, so
+ * the check keeps working when the thrower and the caller end up in different
+ * module instances (bundled host half vs. a test's source import) — the same
+ * convention `WorkBuddyCredentialRejectedError` uses.
+ */
+declare const ENCRYPTED_CREDENTIAL_CODE = "WORKBUDDY_ENCRYPTED_CREDENTIAL";
+/**
+ * The user IS signed in, but the credential file cannot be read.
+ *
+ * This exists because "signed out" and "signed in with an unreadable credential"
+ * resolve to the same observable state — zero accounts — and were therefore
+ * reported with the same message. That message told a correctly signed-in user
+ * to sign in again, which cannot possibly help: from WorkBuddy 5.6.x the desktop
+ * app encrypts its token fields, and reading them requires asking the installed
+ * app for its key. If that app cannot be located, the fix is to point the plugin
+ * at it (`WORKBUDDY_APP_EXECUTABLE`), never to sign in again.
+ *
+ * No token material is carried: only the paths and the environment variable.
+ */
+declare class WorkBuddyEncryptedCredentialError extends Error {
+  readonly code = "WORKBUDDY_ENCRYPTED_CREDENTIAL";
+  /** Files that hold an encrypted credential, for the user to recognize. */
+  readonly paths: readonly string[];
+  constructor(paths: readonly string[]);
+}
+/** Whether an error reports an unreadable (encrypted) credential. */
+declare function isEncryptedCredentialError(value: unknown): value is WorkBuddyEncryptedCredentialError;
 /** Constructor options; only {@link refresh} is required. */
 interface WorkBuddyStoreOptions {
   /** Explicit desktop auth-file path, overriding env and platform defaults. */
@@ -69,13 +124,25 @@ interface WorkBuddyStoreOptions {
   refresh: (credential: WorkBuddyCredential) => Promise<WorkBuddyRefreshOutcome>;
   /** Refresh this long before actual expiry; default five minutes. */
   refreshMarginMs?: number;
+  /**
+   * Resolves the desktop app's at-rest field key, used to open documents whose
+   * token fields are encrypted (Windows builds). Defaults to asking the
+   * installed app; injectable so the encrypted path is testable.
+   */
+  resolveAtRestKey?: () => Promise<Buffer | undefined>;
 }
 /** One selectable local account, token-free. */
 interface WorkBuddyAccountChoice {
   /** Stable id derived from `uin` (or `uid` when uin is absent). */
   id: string;
+  /**
+   * The account's human name, or `''` when the desktop app recorded none.
+   *
+   * Never an identifier: `uin`/`uid` are opaque numbers and UUIDs, and using one
+   * as a display name reads as "the plugin does not know who this is". Callers
+   * that render a name choose their own placeholder for the empty case.
+   */
   accountName: string;
-  uin?: string;
   domain: string;
   source: 'desktop' | 'dsh';
   tokenExpiresAtMs: number;
@@ -119,8 +186,24 @@ declare function defaultDesktopAuthPath(): string | undefined;
  * Parse a WorkBuddy auth document in either on-disk shape: the plugin OAuth
  * nested form `{"auth":{...},"account":{...}}` and the flat panel form.
  * Returns undefined when the document carries no access token.
+ *
+ * `atRestKey` is required to read documents whose fields are encrypted
+ * (see {@link credentialField}); pass the key obtained from
+ * `readAtRestKey()` when the plain read reports no token.
+ */
+declare function parseWorkBuddyAuth(text: string, filePath: string, atRestKey?: Buffer): WorkBuddyCredential | undefined;
+/**
+ * Whether a document carries any field the reader must decrypt — the token
+ * fields or the identity fields — i.e. whether reading it needs the at-rest key
+ * at all.
+ *
+ * Deciding this BEFORE asking the app for its key keeps the plain case (macOS
+ * and older Windows builds, and every plugin-owned copy) from paying for a
+ * child process on every credential read. Identity fields are included because
+ * a future build could encrypt the display name while leaving tokens plain;
+ * gating on tokens alone would then silently drop the name again.
  */
-declare function parseWorkBuddyAuth(text: string, filePath: string): WorkBuddyCredential | undefined;
+declare function hasEncryptedCredentialFields(text: string): boolean;
 /**
  * Filename of a path regardless of the host separator: Windows paths use `\`
  * and this helper must keep working when a Windows path is compared on a
@@ -150,6 +233,7 @@ declare class WorkBuddyCredentialStore {
   private readonly legacyOwnPath;
   private readonly legacyOwnPathExplicit;
   private readonly authDirs;
+  private readonly resolveAtRestKey;
   private desktopPathOverride;
   private accountId;
   private inflight;
@@ -262,8 +346,33 @@ declare class WorkBuddyCredentialStore {
   selectionLost(): Promise<boolean>;
   /** The freshest stored credential for the current selection, no refresh. */
   current(): Promise<WorkBuddyCredential | undefined>;
+  /**
+   * One account's stored credential by id, WITHOUT consulting or changing the
+   * current selection.
+   *
+   * Exists so a recovery probe can test whether some OTHER local account is
+   * still accepted upstream while a rejected one stays selected: mutating the
+   * live selection to find that out would be exactly the silent account switch
+   * this store refuses to perform (it would bill the wrong account mid-probe).
+   */
+  credentialFor(accountId: string): Promise<WorkBuddyCredential | undefined>;
   /** The credential to send upstream: {@link current}, refreshed on demand. */
   resolve(): Promise<WorkBuddyCredential>;
+  /**
+   * WHY no credential resolved, as the error to throw.
+   *
+   * `resolve()` seeing zero accounts has two very different causes, and the
+   * generic "sign in once" message is only correct for one of them. When a
+   * probe finds a credential file whose fields are encrypted and the key could
+   * not be obtained, the user is signed in and re-authenticating cannot help —
+   * so that case gets {@link WorkBuddyEncryptedCredentialError} instead, naming
+   * the file and the environment variable that actually fixes it.
+   *
+   * The probe is only run on the failure path, so the healthy case pays nothing.
+   * A probe that itself throws must not replace the real error, hence the
+   * fallback to the generic message.
+   */
+  private describeMissingCredential;
   /** Read-only sign-in summary; never refreshes and never throws. */
   status(): Promise<WorkBuddyAuthStatus>;
   /**
@@ -284,6 +393,21 @@ declare class WorkBuddyCredentialStore {
   private readOwns;
   /** Whether any candidate file exists as a regular file; diagnostics only. */
   desktopFilePresent(): Promise<boolean>;
+  /**
+   * Which paths were probed and why each one yielded no credential.
+   *
+   * Read-only and token-free: it exists so a signed-out card can explain
+   * itself. A bare "not signed in" is undiagnosable on a machine whose layout
+   * differs from the ones this plugin was written against — and on Windows it
+   * is actively misleading, because encrypted token fields need the desktop app
+   * present to be read at all. Only paths this store actually consults are
+   * reported, and only files that failed: one healthy sibling would make the
+   * whole list noise.
+   */
+  diagnose(): Promise<{
+    tried: string[];
+    failures: WorkBuddyCandidateFailure[];
+  }>;
 }
 //#endregion
 //#region src/upstream.d.ts
@@ -395,6 +519,28 @@ declare function regionOf(domain: string): WorkBuddyRegion;
  * `tool_choice` (the upstream's field is a string; object forms return 400).
  */
 declare function prepareChatBody(source: string): string;
+/** Marker carried by {@link WorkBuddyCredentialRejectedError}; survives bundling. */
+declare const CREDENTIAL_REJECTED_CODE = "WORKBUDDY_CREDENTIAL_REJECTED";
+/**
+ * The upstream refused the CREDENTIAL itself rather than failing the request.
+ *
+ * This is a distinct, actionable class: the token is not usable and no retry
+ * with the same token will help. Callers use it to tell the user what to do
+ * about it (switch accounts, or sign in again) instead of showing a raw HTTP
+ * error, and the card must never confuse it with a transient upstream fault.
+ *
+ * Identified by {@link CREDENTIAL_REJECTED_CODE} rather than `instanceof`, so
+ * the check keeps working when the caller and the thrower end up in different
+ * module instances (bundled host half vs. a test's source import).
+ */
+declare class WorkBuddyCredentialRejectedError extends Error {
+  readonly code = "WORKBUDDY_CREDENTIAL_REJECTED";
+  /** HTTP status the upstream answered with (401 or 403). */
+  readonly status: number;
+  constructor(status: number);
+}
+/** Whether an error reports that the upstream refused the credential itself. */
+declare function isCredentialRejectedError(value: unknown): value is WorkBuddyCredentialRejectedError;
 /**
  * Parse the upstream's `credits` string into a multiplier.
  *
@@ -496,6 +642,18 @@ declare class WorkBuddyCatalog {
    * serving the fallback rather than blanking a region that may be fine.
    */
   private usable;
+  /**
+   * Whether the user has switched this region's provider ON. Opt-out: defaults
+   * to `true`, so a config predating this switch (and the pre-region-split flat
+   * fields, which never carry `enabled`) keeps both providers running. Set to
+   * `false` by `setRegionEnabled` to withdraw the region from DSH's model
+   * picker entirely (its adapter route and configurable-provider entry are
+   * pulled by the Host via `AdapterRegistrationHandle.replace([])` /
+   * `DirectoryRegistrationHandle.replace([])`). This is a USER choice, distinct
+   * from {@link usable}: a region the user switched off keeps its catalog,
+   * accounts, and model picks intact and reappears the moment they re-check it.
+   */
+  private enabled;
   /**
    * @param region Seeds the static fallback for this region; each region's
    * provider must never serve the other region's roster before its first
@@ -505,15 +663,19 @@ declare class WorkBuddyCatalog {
   /**
    * Current entries; the fallback list until the upstream answer lands.
    *
-   * Empty while this region has no local sign-in: the provider stays
-   * registered (its row still hosts the settings card and the account picker),
-   * but it advertises nothing to pick. DSH drops empty provider groups from
-   * the picker (`buildModelCatalog` filters `models.length > 0`), so the group
-   * disappears exactly when it would be pure noise.
+   * Empty while this region has no local sign-in OR the user has switched it
+   * off: the provider stays registered (its row still hosts the settings card
+   * and the account picker), but it advertises nothing to pick. DSH drops empty
+   * provider groups from the picker (`buildModelCatalog` filters
+   * `models.length > 0`), so the group disappears exactly when it would be pure
+   * noise. The two empty causes are independent: `usable` is the automatic
+   * "no account" gate (issue #12), `enabled` is the user's explicit on/off.
    */
   current(): readonly WorkBuddyModelInfo[];
   /** Whether this region currently advertises any model. */
   isRegionUsable(): boolean;
+  /** Whether the user has this region's provider switched on. */
+  isRegionEnabled(): boolean;
   /**
    * Record whether this region has a local sign-in.
    *
@@ -526,6 +688,16 @@ declare class WorkBuddyCatalog {
    *   its adapter snapshots when nothing moved.
    */
   setRegionUsable(usable: boolean): boolean;
+  /**
+   * Record the user's explicit on/off choice for this region's provider.
+   *
+   * Distinct from {@link setRegionUsable}: that is the automatic "no local
+   * account" gate, while this is a deliberate user action (issue #11-style
+   * region switch). The Host reads the same `enabled` flag through
+   * `regionStateOf(config, region).enabled !== false`, so the two halves never
+   * disagree. Returns whether the value changed.
+   */
+  setRegionEnabled(enabled: boolean): boolean;
   /** Replace the list; callers invalidate their adapter snapshot after this. */
   set(models: readonly WorkBuddyModelInfo[]): void;
 }
@@ -622,6 +794,228 @@ declare function workBuddyThinkingLevelMap(info: WorkBuddyModelInfo): WorkBuddyT
  */
 declare function createWorkBuddyAdapter(options: WorkBuddyAdapterOptions): WorkBuddyAdapter;
 //#endregion
+//#region src/at-rest.d.ts
+/**
+ * WorkBuddy desktop "at-rest" credential decryption.
+ *
+ * From 5.6.0 the WorkBuddy desktop app no longer stores `auth.accessToken` /
+ * `auth.refreshToken` as plain strings. It writes a field wrapper:
+ *
+ *   { "$wbEncrypted": 1, "envelope": "<base64 of a JSON envelope>" }
+ *
+ * where the envelope is `{suite, keyId, nonce, authTag, ciphertext}` for
+ * AES-256-GCM with a 12-byte nonce and a 16-byte tag. The authenticated
+ * additional data is a length-prefixed transcript over the scheme, suite,
+ * keyId and framing, so the ciphertext can only be opened for the exact field
+ * shape it was sealed for.
+ *
+ * The field key itself is NOT a user secret: it is a build-time constant
+ * compiled into the app's own Electron native module
+ * (`electron_browser_workbuddy_storage`). The app fetches it through
+ * `loggerGet()` and hashes the returned base64 STRING (not the decoded bytes)
+ * to obtain the 32-byte key; `keyId` is the first 16 hex characters of that
+ * key's SHA-256.
+ *
+ * This module re-derives the same key by asking the installed app for the same
+ * payload, and caches it in memory for the process lifetime. Nothing is ever
+ * written to disk, and the payload is never logged.
+ *
+ * 改动：**「macOS 也加密」这一事实**（issue #15 真机取证）。本模块原先假设该
+ *   policy 是 Windows 先行、macOS 只是「将来可能」，于是 macOS 的可执行文件
+ *   路径用 App 名拼成 `<bundle>/Contents/MacOS/WorkBuddy`——而两个真实 bundle
+ *   的 `CFBundleExecutable` 都是 `Electron`，该路径并不存在。结果是 macOS 上
+ *   加密凭据**永远**取不到密钥，用户却被报成「未登录」。现在二进制名向 bundle
+ *   自己问（`macosBundleExecutable()`），候选含国际版 `WorkBuddy AI.app`，
+ *   并允许 App 被归入 applications 目录的子目录——扫到的候选必须先用
+ *   `CFBundleIdentifier` 确认身份才 `execFile`，因为**每个 Electron 应用的
+ *   二进制都叫 `Electron`**，只按名字匹配就可能启动另一个产品。
+ *
+ * @module dsh-connect-workbuddy/at-rest
+ */
+/** A `{$wbEncrypted:1,envelope}` field wrapper, the only shape this module opens. */
+interface WorkBuddyEncryptedField {
+  $wbEncrypted: 1;
+  envelope: string;
+}
+/** Env override pointing at the WorkBuddy desktop executable. */
+declare const WORKBUDDY_APP_EXECUTABLE_ENV = "WORKBUDDY_APP_EXECUTABLE";
+/** Whether a value is the app's encrypted-field wrapper. */
+declare function isEncryptedFieldWrapper(value: unknown): value is WorkBuddyEncryptedField;
+/**
+ * The at-rest key id for a derived 32-byte key: the first 16 hex characters of
+ * its SHA-256. This is what the envelope's `keyId` is checked against, so a
+ * mismatched key fails loudly instead of returning garbage.
+ */
+declare function deriveAtRestKeyId(key: Buffer): string;
+/**
+ * Derive the 32-byte field key from the app's key payload JSON.
+ *
+ * The app hashes the payload's base64 STRING — not its decoded bytes — so the
+ * same spelling is required here; hashing the decoded secret would produce a
+ * different key and every field would fail to open.
+ */
+declare function deriveAtRestKey(payloadJson: string): Buffer;
+/**
+ * Open one encrypted field with a derived key and return its plaintext.
+ *
+ * Throws when the envelope is malformed, belongs to another key, or fails
+ * authentication — a GCM tag mismatch is the signal that the transcript or the
+ * key is wrong, and it must never degrade into a truncated token.
+ */
+declare function openEncryptedField(field: WorkBuddyEncryptedField, key: Buffer): string;
+/**
+ * The executable inside a macOS app bundle, read from the bundle's own
+ * `Info.plist`.
+ *
+ * The binary is NOT reliably named after the app: the WorkBuddy bundles ship
+ * with `CFBundleExecutable` set to `Electron`, so a path assembled as
+ * `<bundle>/Contents/MacOS/WorkBuddy` does not exist and the app looks absent
+ * even when it is installed in the default location. Because the bundle
+ * documents the real name, asking it is both correct and robust to a future
+ * build that renames the binary.
+ *
+ * Returns undefined when the plist is absent, unreadable, or carries no usable
+ * name — never a guessed path, so a caller can keep probing.
+ */
+declare function macosBundleExecutable(bundle: string): string | undefined;
+/**
+ * Candidate paths of the WorkBuddy desktop executable, in probe order.
+ *
+ * The Windows build is the one that encrypts credentials, so Windows leads;
+ * the macOS bundles are listed because the same native module ships there and
+ * the encryption policy is enabled on macOS builds too (observed from 5.6.x),
+ * and `undefined` entries (an unset env variable) are dropped.
+ *
+ * On macOS the executable name comes from each bundle (see
+ * {@link macosBundleExecutable}) rather than being assembled from the app name.
+ *
+ * `readBundleExecutable` is injectable, in the same spirit as `platform`/`home`/
+ * `env`: the macOS branch consults the real filesystem, so without a seam the
+ * expected candidates would depend on whether the host machine happens to have
+ * the app installed — and the test would pass on a developer's Mac while
+ * failing in CI.
+ */
+declare function workbuddyAppExecutableCandidates(platform?: NodeJS.Platform, home?: string, env?: NodeJS.ProcessEnv, readBundleExecutable?: (bundle: string) => string | undefined): string[];
+/**
+ * Whether a bundle identifies itself as the WorkBuddy desktop app.
+ *
+ * The match is on dot boundaries, so a hypothetical `com.workbuddyish` cannot
+ * pass as `com.workbuddy`.
+ *
+ * An unreadable or identifier-less plist is treated as NOT WorkBuddy: refusing
+ * a candidate only costs a fallback to another path, whereas accepting the
+ * wrong one would execute an unrelated application.
+ */
+declare function isWorkbuddyBundle(bundle: string): boolean;
+/**
+ * Bundles of the desktop app found one level BELOW a macOS applications
+ * directory.
+ *
+ * Users do file apps into subfolders (`/Applications/IDE/WorkBuddy.app`), and
+ * a hardcoded `/Applications/<name>` then reports the app as missing while it
+ * is installed and signed in. The scan is deliberately ONE level deep and
+ * matches the known bundle names only, so it stays predictable and cheap; each
+ * candidate is then confirmed by {@link isWorkbuddyBundle} before use.
+ *
+ * Returns [] when the parent is absent or unreadable — a missing directory is
+ * the normal case, not an error.
+ */
+declare function macosNestedAppBundles(parent: string): string[];
+/**
+ * The first candidate that exists as a file, or undefined when the desktop app
+ * is not installed where this platform expects it.
+ */
+declare function findWorkbuddyAppExecutable(platform?: NodeJS.Platform, home?: string, env?: NodeJS.ProcessEnv): string | undefined;
+/**
+ * Ask the installed desktop app for its key payload by running its own binary
+ * as plain Node (`ELECTRON_RUN_AS_NODE`) and calling the native binding.
+ *
+ * The binding is the app's own public surface for this value, so the plugin
+ * never has to carry a copy of a build-specific constant: it asks the very
+ * build that wrote the file. The child is given no stdin and a hard timeout,
+ * and its stdout is the only thing read.
+ */
+declare function fetchAtRestKeyPayload(executable: string): Promise<string>;
+/**
+ * The desktop app's at-rest field key, or undefined when it cannot be obtained
+ * (app not installed, an older build without the native module, or a future
+ * build that rotates the payload). Cached after the first success so the app is
+ * spawned at most once per process; a failure is retried on the next call,
+ * because the user may install or start the app between reads.
+ */
+declare function readAtRestKey(): Promise<Buffer | undefined>;
+/** Drop the cached key; tests and diagnostics only. */
+declare function clearAtRestKeyCache(): void;
+//#endregion
+//#region src/credential-recovery.d.ts
+/** What the user can do about a refused credential. */
+interface WorkBuddyCredentialRecovery {
+  /**
+   * Another local account answered the upstream during this recovery, so
+   * switching to it is a fix that has been verified — not a guess.
+   */
+  usableAccount?: {
+    accountId: string;
+    accountName: string;
+  };
+  /**
+   * Whether signing in again is the only remaining fix: no other local account
+   * exists at all, so there is nothing to switch to.
+   */
+  reloginRequired: boolean;
+}
+/** One account as the recovery path needs to see it. */
+interface WorkBuddyRecoveryCandidate {
+  id: string;
+  accountName: string;
+}
+/** Reads one account's credential for probing, without changing the selection. */
+interface WorkBuddyProbeStore {
+  accounts(): Promise<readonly WorkBuddyRecoveryCandidate[]>;
+  credentialFor(accountId: string): Promise<WorkBuddyCredential | undefined>;
+}
+/** Constructor options for {@link createAccountUsabilityProbe}. */
+interface WorkBuddyUsabilityProbeOptions {
+  /** The credential store for one region (its selection is never touched). */
+  store(region: WorkBuddyRegion): WorkBuddyProbeStore;
+  /** The upstream client; only its cheap read-only calls are used. */
+  client: Pick<WorkBuddyUpstreamClient, 'fetchCheckinStatus'>;
+  /**
+   * How long a probe verdict is reused. The card polls the usage route, so
+   * without this a broken selection would re-probe every account on every poll.
+   */
+  ttlMs?: number;
+  /** Injectable clock, for tests. */
+  now?: () => number;
+}
+/**
+ * Cached "is this account still accepted upstream?" probe.
+ *
+ * The cache key includes the credential's own `lastRefreshAtMs`, so a fresh
+ * sign-in (which rewrites the file's issuance time) invalidates a stale verdict
+ * automatically — a rejection recorded before the user signed in again cannot
+ * keep labelling the account unusable afterwards, and no explicit invalidation
+ * is needed.
+ */
+declare function createAccountUsabilityProbe(options: WorkBuddyUsabilityProbeOptions): (region: WorkBuddyRegion, account: WorkBuddyRecoveryCandidate) => Promise<boolean>;
+/**
+ * Decide what to tell the user after the upstream refused the selected
+ * credential: switch to a verified-usable account, or sign in again.
+ *
+ * The two answers are mutually exclusive by construction. `reloginRequired` is
+ * set ONLY when there is no other local account to switch to — never as a
+ * fallback for "the probe did not verify anything", because that would repeat
+ * the misdirection this module exists to remove. When other accounts exist but
+ * none was verified, both fields stay empty and the card says so honestly.
+ */
+declare function resolveCredentialRecovery(options: {
+  region: WorkBuddyRegion;
+  store: WorkBuddyProbeStore;
+  rejectedAccountId?: string;
+  /** Verifies whether one account is still accepted; see the probe factory. */
+  probe: (region: WorkBuddyRegion, account: WorkBuddyRecoveryCandidate) => Promise<boolean>;
+}): Promise<WorkBuddyCredentialRecovery>;
+//#endregion
 //#region src/host-heartbeat.d.ts
 /**
  * Host-side heartbeat: a small JSON file written under `$DSH_HOME` once the
@@ -725,6 +1119,36 @@ declare function withWorkBuddyRegion(path: string, region: WorkBuddyWebRegion):
  * answer 400 instead of guessing.
  */
 declare function regionOfStatusUrl(url: string): WorkBuddyWebRegion | undefined;
+/**
+ * Whether one region's provider is switched on. Opt-out semantics: only an
+ * explicit `false` disables it, so a config written before this switch existed
+ * (and the pre-region-split flat fields, which never carry `enabled`) keep both
+ * providers running exactly as before. The Host reads the same rule through
+ * `regionStateOf`, so card and Host can never disagree about a region's state.
+ *
+ * `value` may be the whole settings section or the `regions` map (see
+ * {@link regionsMapOf}).
+ */
+declare function regionEnabledOf(value: unknown, region: WorkBuddyWebRegion): boolean;
+/** Build the next `regions` settings value for a signed-in tab's save. */
+declare function nextRegionSlots<Slot extends object>(regions: unknown, region: WorkBuddyWebRegion, slot: Slot): Record<string, unknown>;
+/**
+ * Build the next `regions` settings value for a provider on/off toggle. ONLY
+ * the target region's `enabled` flag changes: every other field of that slot
+ * (its directory, selection, image opt-ins, context budgets) and every other
+ * region's slot are carried over verbatim, so switching a provider off never
+ * discards the user's model picks and switching it back on restores them.
+ *
+ * This is deliberately separate from {@link nextRegionSlots}: that helper
+ * writes a whole slot from a signed-in tab's draft, while this one must work
+ * for a region that is signed OUT — which is precisely the region a user wants
+ * to switch off (no international install, no international account).
+ *
+ * `value` may be the whole settings section or the `regions` map; the RETURN
+ * value is always the `regions` map, i.e. exactly what `settingsScope.set(
+ * 'regions', ...)` needs.
+ */
+declare function nextRegionEnabled(value: unknown, region: WorkBuddyWebRegion, enabled: boolean): Record<string, unknown>;
 /** One credit package as the upstream returns it, node-free. */
 interface WorkBuddyWebCreditPackage {
   packageName: string;
@@ -759,6 +1183,30 @@ interface WorkBuddyWebCheckin {
   streakBonusCredit: number;
   claimButtonText?: string;
 }
+/**
+ * What the user can do about a credential the upstream refused.
+ *
+ * Two different fixes hide behind one 401, and naming the wrong one is worse
+ * than saying nothing: with a stale account SELECTED but a healthy sign-in
+ * sitting right there, "sign in again" sends the user to re-authenticate — which
+ * changes nothing, because the credentials were never the problem.
+ */
+interface WorkBuddyWebRecovery {
+  /**
+   * Another local account answered the upstream during recovery, so switching
+   * to it is a VERIFIED fix rather than a suggestion.
+   */
+  usableAccount?: {
+    accountId: string;
+    accountName: string;
+  };
+  /**
+   * Signing in again is the only remaining fix: this region has no other local
+   * account to switch to. Set only in that case — never as a fallback for
+   * "nothing could be verified".
+   */
+  reloginRequired: boolean;
+}
 /** Editable WorkBuddy model row rendered by the plugin-owned settings card. */
 interface WorkBuddyWebModel {
   id: string;
@@ -789,14 +1237,39 @@ declare function toPersistedWorkBuddyModel(model: WorkBuddyWebModel): Omit<WorkB
 /** One selectable local account, token-free. */
 interface WorkBuddyWebAccount {
   id: string;
+  /**
+   * The account's human name, or `''` when the desktop app recorded none.
+   * The card renders its own placeholder for the empty case.
+   */
   accountName: string;
-  uin?: string;
   domain: string;
   source: 'desktop' | 'dsh';
   tokenExpiresAtMs: number;
   selected: boolean;
 }
 type WorkBuddyWebPackage = WorkBuddyWebCreditPackage;
+/**
+ * One probed candidate path and why it yielded no account.
+ *
+ * Safe to send to the browser: a path, its source, and a cause. No token
+ * material, and no content read out of the files beyond an error string.
+ *
+ * `encrypted` exists because WorkBuddy (unlike a plain JSON-token app) can
+ * refuse a correctly signed-in user: Windows builds encrypt the token fields,
+ * and opening them needs the desktop app present to hand over its at-rest key.
+ * Telling that user to "sign in again" is wrong — they already are.
+ *
+ * `wrong-region` is the other WorkBuddy-specific one: the file holds a valid
+ * sign-in for the OTHER tab's region, so this tab filters it out of the account
+ * list. Without this entry the file was reported nowhere at all, which both
+ * undercounted "paths checked" and hid the user's real sign-in.
+ */
+interface WorkBuddyWebSearchPath {
+  path: string;
+  source: 'desktop' | 'dsh';
+  reason: 'missing' | 'unreadable' | 'invalid' | 'encrypted' | 'wrong-region';
+  message?: string;
+}
 /**
  * Region of the signed-in credential: the CN app (`codebuddy.cn` /
  * `workbuddy.cn`) or the international WorkBuddy AI app (`workbuddy.ai`).
@@ -822,19 +1295,36 @@ type WorkBuddyWebUsage =
 {
   status: 'signed-out';
   accounts: readonly WorkBuddyWebAccount[];
+  /** Whether this region's provider is currently offered to DSH. */
+  enabled?: boolean;
   message?: string;
   /** The persisted account id matches no local account. */
   selectionLost?: boolean;
   /** A saved per-region choice is in effect (false = following the app). */
   selectionExplicit: boolean;
+  /**
+   * The paths this region's store probed, and why each yielded nothing.
+   *
+   * Present only on the "nothing was found at all" branch — it is the
+   * explanation for a state that is otherwise a dead end. A missing candidate
+   * (`missing`) is normal noise on any machine and the card filters those out
+   * of its default view; the interesting ones are `unreadable`, `invalid`,
+   * and especially `encrypted`.
+   */
+  searched?: readonly WorkBuddyWebSearchPath[];
 } | {
   status: 'signed-in';
   accountId: string;
+  /**
+   * The account's human name, or `''` when the desktop app recorded none.
+   * Never an identifier — see {@link WorkBuddyWebAccount.accountName}.
+   */
   accountName: string;
-  uin?: string;
   domain?: string;
   /** Which per-region model directory and selection this account owns. */
   region: WorkBuddyWebRegion;
+  /** Whether this region's provider is currently offered to DSH. */
+  enabled?: boolean;
   source?: 'desktop' | 'dsh';
   tokenExpiresAtMs: number;
   /** A saved per-region choice is in effect (false = following the app). */
@@ -847,6 +1337,14 @@ type WorkBuddyWebUsage =
   creditsError?: string;
   checkin?: WorkBuddyWebCheckin;
   checkinError?: string;
+  /**
+   * The upstream refused the credential itself (a 401/403), as opposed to a
+   * transient upstream fault. Distinguishes "your token is not usable" from
+   * "the request failed", which need opposite advice.
+   */
+  credentialRejected?: boolean;
+  /** Present only alongside {@link credentialRejected}. */
+  recovery?: WorkBuddyWebRecovery;
 } | {
   status: 'error';
   message: string;
@@ -873,6 +1371,12 @@ interface WorkBuddyStatusRouteOptions {
   contextBudgets(region: WorkBuddyRegion): Readonly<Record<string, number | undefined>>;
   /** Re-read the live catalog of one region from the upstream. */
   discoverModels?(region: WorkBuddyRegion, signal?: AbortSignal): Promise<readonly WorkBuddyModelInfo[]>;
+  /**
+   * Whether the requested region's provider is currently offered to DSH. The
+   * card renders this as the tab's on/off checkbox, so the switch reflects the
+   * committed settings value rather than a local guess.
+   */
+  regionEnabled(region: WorkBuddyRegion): boolean;
   /**
    * Report whether a region still has at least one local sign-in.
    *
@@ -883,6 +1387,15 @@ interface WorkBuddyStatusRouteOptions {
    * no scan of its own.
    */
   regionUsable?(region: WorkBuddyRegion, usable: boolean): void;
+  /**
+   * Verify whether one local account is still accepted by the upstream.
+   *
+   * Consulted ONLY after the selected credential has been refused, to tell
+   * "switch accounts" apart from "sign in again". Left undefined, nothing is
+   * claimed usable and the card falls back to the re-login advice that needs no
+   * probe.
+   */
+  accountUsable?(region: WorkBuddyRegion, account: WorkBuddyRecoveryCandidate): Promise<boolean>;
 }
 /**
  * Assemble one region's card document. `region` is the tab the card is on;
@@ -908,6 +1421,15 @@ declare const inject: string[];
 declare const WORKBUDDY_SETTINGS_NS: SettingsNamespace;
 /** One region's model directory and the user's selection within it. */
 interface WorkBuddyRegionState {
+  /**
+   * Whether this region's provider is switched on. Opt-out: only an explicit
+   * `false` disables it, so a config predating this switch keeps both providers
+   * running. A disabled region is fully withdrawn from the harness — its adapter
+   * route and its configurable-provider entry both hold zero routes, so it
+   * disappears from DSH's model picker instead of lingering as an unselectable
+   * row (see `syncRegionRegistration`).
+   */
+  enabled?: boolean;
   /** The last-refreshed directory for this region; what the card displays. */
   lastCatalog?: WorkBuddyModelInfo[];
   /** The user's selection in this region, as model ids. */
@@ -964,6 +1486,15 @@ declare const Config: z<Config>;
  * picks.
  */
 declare function regionStateOf(config: Config, region: WorkBuddyRegion): WorkBuddyRegionState;
+/**
+ * Whether one region's provider is switched on. Opt-out semantics: only an
+ * explicit `false` disables it, so every config written before this switch
+ * existed — including the pre-region-split flat fields, which never carry
+ * `enabled` — keeps both providers running exactly as before. The card reads the
+ * same rule through `regionEnabledOf`, so the two halves can never disagree
+ * about a region's state.
+ */
+declare function regionEnabled(config: Config, region: WorkBuddyRegion): boolean;
 /**
  * The account id a region should select, or `undefined` for the documented
  * default: follow whatever the WorkBuddy app is currently signed in as.
@@ -1014,4 +1545,4 @@ declare function legacyAttributionRegion(value: Config, accountsFor: (region: Wo
  */
 declare function apply(ctx: Context, config: Config): void;
 //#endregion
-export { Config, FALLBACK_WORKBUDDY_MODELS, FALLBACK_WORKBUDDY_MODELS_GLOBAL, type UpstreamErrorKind, WORKBUDDY_ACCOUNTS_REFRESH_PATH, WORKBUDDY_AUTH_FILENAME, WORKBUDDY_AUTH_FILE_ENV, WORKBUDDY_CHECKIN_PATH, WORKBUDDY_CONNECT_VERSION, WORKBUDDY_GLOBAL_PROVIDER, WORKBUDDY_HOST_HEARTBEAT_FILENAME, WORKBUDDY_MODELS_REFRESH_PATH, WORKBUDDY_PROVIDER, WORKBUDDY_PROVIDERS, WORKBUDDY_PROVIDER_DISPLAY_NAMES, WORKBUDDY_REGIONS, WORKBUDDY_REGION_PARAM, WORKBUDDY_SETTINGS_NS, WORKBUDDY_STREAM_IDLE_TIMEOUT_MS, WORKBUDDY_USAGE_PATH, type WorkBuddyAccountChoice, type WorkBuddyAdapter, type WorkBuddyAuthStatus, WorkBuddyCatalog, type WorkBuddyChatResult, type WorkBuddyCredential, WorkBuddyCredentialStore, type WorkBuddyCreditPackage, type WorkBuddyCredits, type WorkBuddyHostHeartbeat, type WorkBuddyModelInfo, type WorkBuddyReasoning, type WorkBuddyRefreshOutcome, WorkBuddyRegionState, type WorkBuddyShim, type WorkBuddyStatusRouteOptions, type WorkBuddyStoreOptions, WorkBuddyUpstreamClient, type WorkBuddyUpstreamModel, type WorkBuddyWebAccount, type WorkBuddyWebCheckin, type WorkBuddyWebCredits, type WorkBuddyWebModel, type WorkBuddyWebPackage, type WorkBuddyWebRegion, type WorkBuddyWebUsage, apply, authFileName, classifyUpstreamError, clearHostHeartbeat, createWorkBuddyAdapter, createWorkBuddyShim, defaultDesktopAuthCandidates, defaultDesktopAuthDirs, defaultDesktopAuthPath, deriveCatalog, fallbackModelsFor, inject, isHeartbeatProcessAlive, legacyAttributionRegion, legacyWorkbuddyOwnAuthPath, name, parseCreditMultiplier, parseReasoning, parseUpstreamModel, parseWorkBuddyAuth, prepareChatBody, processStartTimeMs, readHostHeartbeat, regionCleared, regionOf, regionOfProvider, regionOfStatusUrl, regionStateOf, registerWorkBuddyStatusRoute, selectAccountFor, toPersistedWorkBuddyModel, withWorkBuddyRegion, workBuddyDisplayName, workBuddyModelInput, workBuddyThinkingLevelMap, workBuddyWebStatus, workbuddyAccountId, workbuddyHostHeartbeatPath, workbuddyOwnAuthPath, writeHostHeartbeat };
+export { CREDENTIAL_REJECTED_CODE, Config, ENCRYPTED_CREDENTIAL_CODE, FALLBACK_WORKBUDDY_MODELS, FALLBACK_WORKBUDDY_MODELS_GLOBAL, type UpstreamErrorKind, WORKBUDDY_ACCOUNTS_REFRESH_PATH, WORKBUDDY_APP_EXECUTABLE_ENV, WORKBUDDY_AUTH_FILENAME, WORKBUDDY_AUTH_FILE_ENV, WORKBUDDY_CHECKIN_PATH, WORKBUDDY_CONNECT_VERSION, WORKBUDDY_GLOBAL_PROVIDER, WORKBUDDY_HOST_HEARTBEAT_FILENAME, WORKBUDDY_MODELS_REFRESH_PATH, WORKBUDDY_PROVIDER, WORKBUDDY_PROVIDERS, WORKBUDDY_PROVIDER_DISPLAY_NAMES, WORKBUDDY_REGIONS, WORKBUDDY_REGION_PARAM, WORKBUDDY_SETTINGS_NS, WORKBUDDY_STREAM_IDLE_TIMEOUT_MS, WORKBUDDY_USAGE_PATH, type WorkBuddyAccountChoice, type WorkBuddyAdapter, type WorkBuddyAuthStatus, type WorkBuddyCandidateFailure, WorkBuddyCatalog, type WorkBuddyChatResult, type WorkBuddyCredential, type WorkBuddyCredentialRecovery, WorkBuddyCredentialRejectedError, WorkBuddyCredentialStore, type WorkBuddyCreditPackage, type WorkBuddyCredits, WorkBuddyEncryptedCredentialError, type WorkBuddyEncryptedField, type WorkBuddyHostHeartbeat, type WorkBuddyModelInfo, type WorkBuddyProbeStore, type WorkBuddyReasoning, type WorkBuddyRecoveryCandidate, type WorkBuddyRefreshOutcome, WorkBuddyRegionState, type WorkBuddyShim, type WorkBuddyStatusRouteOptions, type WorkBuddyStoreOptions, WorkBuddyUpstreamClient, type WorkBuddyUpstreamModel, type WorkBuddyUsabilityProbeOptions, type WorkBuddyWebAccount, type WorkBuddyWebCheckin, type WorkBuddyWebCredits, type WorkBuddyWebModel, type WorkBuddyWebPackage, type WorkBuddyWebRegion, type WorkBuddyWebSearchPath, type WorkBuddyWebUsage, apply, authFileName, classifyUpstreamError, clearAtRestKeyCache, clearHostHeartbeat, createAccountUsabilityProbe, createWorkBuddyAdapter, createWorkBuddyShim, defaultDesktopAuthCandidates, defaultDesktopAuthDirs, defaultDesktopAuthPath, deriveAtRestKey, deriveAtRestKeyId, deriveCatalog, fallbackModelsFor, fetchAtRestKeyPayload, findWorkbuddyAppExecutable, hasEncryptedCredentialFields, inject, isCredentialRejectedError, isEncryptedCredentialError, isEncryptedFieldWrapper, isHeartbeatProcessAlive, isWorkbuddyBundle, legacyAttributionRegion, legacyWorkbuddyOwnAuthPath, macosBundleExecutable, macosNestedAppBundles, name, nextRegionEnabled, nextRegionSlots, openEncryptedField, parseCreditMultiplier, parseReasoning, parseUpstreamModel, parseWorkBuddyAuth, prepareChatBody, processStartTimeMs, readAtRestKey, readHostHeartbeat, regionCleared, regionEnabled, regionEnabledOf, regionOf, regionOfProvider, regionOfStatusUrl, regionStateOf, registerWorkBuddyStatusRoute, resolveCredentialRecovery, selectAccountFor, toPersistedWorkBuddyModel, withWorkBuddyRegion, workBuddyDisplayName, workBuddyModelInput, workBuddyThinkingLevelMap, workBuddyWebStatus, workbuddyAccountId, workbuddyAppExecutableCandidates, workbuddyHostHeartbeatPath, workbuddyOwnAuthPath, writeHostHeartbeat };