dsh-connect-workbuddy 3.0.2 → 3.3.0

package/lib/{host-heartbeat-Dwmfxuyw.js → host-heartbeat-t93cLCoW.js}

@@ -6,6 +6,7 @@ import { withFileLock, writeFileAtomic } from "@deepseek-ai/dsh-atomic-write";
 import { resolveDshHome } from "@deepseek-ai/dsh-home-paths";
 import { execFile, execFileSync } from "node:child_process";
 import { existsSync, readFileSync, readdirSync, statSync } from "node:fs";
+import { fileURLToPath } from "node:url";
 //#region src/at-rest.ts
 /**
 * WorkBuddy desktop "at-rest" credential decryption.
@@ -535,9 +536,53 @@ function billingHeaders(credential) {
 	return headers;
 }
 /**
+* Stand-in system message for a request that reached the wire carrying none.
+*
+* Not a stylistic default: both WorkBuddy gateways want the conversation to
+* OPEN with a system message, and the international one enforces it — a
+* user-first body there is refused with business code 11128
+* (`first message is not system prompt`), which the gateway surfaces as
+* "blocked by security policy". The domestic gateway tolerates the same body,
+* so the fault only ever shows up on the international route (issue: a global
+* model failing every step while the CN one is fine).
+*
+* A system message can go missing before this module ever sees the body:
+* `dsh-llm-pi-ai` folds a leading `system` message into `Context.systemPrompt`
+* and pi-ai only emits that prompt `if (context.systemPrompt)` — so an EMPTY
+* prompt emits no system message at all, and pi-ai demotes any `system` entry
+* left in `messages` to `user`. By the time the shim holds the JSON, the real
+* prompt is no longer recoverable, and a minimal placeholder is strictly better
+* than a guaranteed 400.
+*
+* Deliberately tiny: this is a last-resort placeholder, not a persona. Inventing
+* a longer one would quietly change model behaviour on every affected request.
+*/
+const WORKBUDDY_FALLBACK_SYSTEM_PROMPT = "You are a helpful assistant.";
+/**
+* Make the conversation open with a system message, prepending the fallback
+* when nothing else supplies one.
+*
+* `developer` is normalized to `system` first (the gateways reject
+* `developer`), so an ordinary DSH request already satisfies this and the
+* function is a no-op for it.
+*/
+function ensureSystemHead(obj) {
+	const messages = obj["messages"];
+	if (!Array.isArray(messages) || messages.length === 0) return;
+	const head = messages[0];
+	if (typeof head !== "object" || head === null || Array.isArray(head)) return;
+	const role = head["role"];
+	if (typeof role === "string" && role.trim().toLowerCase() === "system") return;
+	messages.unshift({
+		role: "system",
+		content: WORKBUDDY_FALLBACK_SYSTEM_PROMPT
+	});
+}
+/**
 * Normalize an OpenAI chat-completions body for the WorkBuddy upstream:
-* force `stream: true` (the upstream rejects non-streaming) and flatten
-* `tool_choice` (the upstream's field is a string; object forms return 400).
+* force `stream: true` (the upstream rejects non-streaming), flatten
+* `tool_choice` (the upstream's field is a string; object forms return 400),
+* and guarantee a leading system message.
 */
 function prepareChatBody(source) {
 	let body;
@@ -554,6 +599,7 @@ function prepareChatBody(source) {
 		const message = value;
 		if (message["role"] === "developer") message["role"] = "system";
 	}
+	ensureSystemHead(obj);
 	normalizeToolChoice(obj);
 	return JSON.stringify(obj);
 }
@@ -591,6 +637,67 @@ function normalizeToolChoice(obj) {
 	delete obj["tool_choice"];
 }
 /**
+* What a PREPARED request body declares, as the input to DSML recovery.
+*
+* This exists so the recovery path can answer the one question its gates turn
+* on — "was this tool name offered in THIS request?" — without a second parse
+* of the body and without a second source of truth. `prepareChatBody` has
+* already parsed it; this reads the same prepared JSON.
+*
+* Two facts make it cheap and exact:
+*
+*   - `tool_choice: "none"` deletes `tools` outright in
+*     {@link normalizeToolChoice}, so "no tools declared" is directly
+*     observable here rather than a separate condition to remember;
+*   - a pinned `tool_choice` arrives as the bare function name (the object form
+*     was flattened), so anything that is not `auto`/`required`/`none` is a pin.
+*
+* Returns `undefined` when the body declares nothing usable — malformed JSON,
+* no `tools` array, or an empty one. Callers must read that as "recovery is
+* off" (gate 3), not as "no information, so guess".
+*/
+function declaredTools(bodyJson) {
+	let body;
+	try {
+		body = JSON.parse(bodyJson);
+	} catch {
+		return;
+	}
+	if (typeof body !== "object" || body === null || Array.isArray(body)) return void 0;
+	const obj = body;
+	const tools = obj["tools"];
+	if (!Array.isArray(tools)) return void 0;
+	const names = /* @__PURE__ */ new Set();
+	const requiredParameters = /* @__PURE__ */ new Map();
+	for (const value of tools) {
+		if (typeof value !== "object" || value === null || Array.isArray(value)) continue;
+		const fn = value["function"];
+		if (typeof fn !== "object" || fn === null || Array.isArray(fn)) continue;
+		const definition = fn;
+		const name = typeof definition["name"] === "string" ? definition["name"] : "";
+		if (name === "") continue;
+		names.add(name);
+		const parameters = definition["parameters"];
+		if (typeof parameters !== "object" || parameters === null || Array.isArray(parameters)) continue;
+		const required = parameters["required"];
+		if (!Array.isArray(required)) continue;
+		const list = required.filter((entry) => typeof entry === "string" && entry !== "");
+		if (list.length > 0) requiredParameters.set(name, list);
+	}
+	if (names.size === 0) return void 0;
+	const pinned = typeof obj["tool_choice"] === "string" ? obj["tool_choice"].trim() : "";
+	const pinnedToolName = pinned !== "" && ![
+		"auto",
+		"required",
+		"none"
+	].includes(pinned.toLowerCase()) ? pinned : void 0;
+	return {
+		names,
+		requiredParameters,
+		...pinnedToolName === void 0 ? {} : { pinnedToolName }
+	};
+}
+/**
 * Gateway (openresty/APISIX) rejection of a token it no longer accepts.
 *
 * The business APIs answer JSON; an edge rejection answers an HTML error page
@@ -2284,9 +2391,136 @@ var WorkBuddyCatalog = class {
 	}
 };
 //#endregion
+//#region src/pi-ai-runtime.ts
+/**
+* Which `@earendil-works/pi-ai` copy THIS plugin actually resolves at runtime.
+*
+* WHY THIS EXISTS (issues #24 / #25 / #26). The plugin declares pi-ai as a
+* peer (`>=0.85.0 <0.88.0`), so the module it imports is whatever the host
+* environment provides — and the two generations consume DIFFERENT context
+* shapes:
+*
+* - 0.87 hands providers a normalized transcript: `{ messages: [ {role:
+*   'system', content, toolsAdded}, … ] }`. The system prompt and the tool
+*   declarations live ONLY on that leading system message; the top-level
+*   `systemPrompt` / `tools` fields are gone, and 0.87's api never reads them
+*   back.
+* - 0.85 expects `{ systemPrompt, tools, messages }` and has no branch for a
+*   `system` message inside `messages` at all: its token estimator crashes on
+*   one (issue #24), and its wire converter silently drops it.
+*
+* Which copy resolves is NOT predictable from the host version alone: a
+* nested 0.85.1 on disk shadows the host's 0.87.1 (the plugin author's own
+* symlinked checkout does exactly that), while a clean market install has no
+* local copy at all and resolves the host's (issue #26's reporter). The
+* adapter therefore gates on what THIS plugin resolves.
+*
+* HOW it is detected — deliberately WITHOUT importing pi-ai:
+* `import.meta.resolve` locates the entry file (executing nothing), the
+* package manifest sitting beside it names the version, and the generation is
+* decided from that version (0.87+ → modern). A static import would drag
+* pi-ai into the standalone `doctor` CLI, which must also run from market
+* installs where NO local pi-ai exists and the module is only provided inside
+* the DSH host — a static import there is a load-time crash. Resolution
+* itself does not need the module: within the peer range, the manifest
+* version and the `normalizeContext` feature (present from 0.87 on, not
+* before) agree.
+*
+* When resolution FAILS — the normal state of a market install probed outside
+* the host — there is no local copy, so inside DSH the host supplies pi-ai.
+* Every DSH host that normalizes contexts (0.2.0+, via 0.87.1) also supplies
+* 0.87.1, so the reported generation defaults to `modern` (pass-through).
+* That default is safe on older hosts too: they never normalize, and a native
+* 0.85-shaped context is an identity under BOTH branches of the adapter gate.
+*
+* `doctor` prints the resolved version and path so mixed-generation setups —
+* the silent kind that produced #24 and #26 — become visible on demand.
+*
+* @module dsh-connect-workbuddy/pi-ai-runtime
+*/
+let cached;
+/** Resolve (once) which pi-ai copy this plugin runs against. */
+function piAiRuntimeInfo() {
+	cached ??= piAiRuntimeFor(resolveModuleFile());
+	return cached;
+}
+/**
+* The decision table for one resolution result, exported so the branch that
+* only ever runs on OTHER machines (a market install with no local pi-ai) is
+* pinned by tests rather than by this comment.
+*
+* `undefined` means nothing local resolved — inside DSH the host supplies the
+* module, and every host that normalizes contexts (0.2.0+, via 0.87.1) ships
+* the modern generation, so that is the default. Older hosts never normalize,
+* and their native 0.85-shaped context is an identity under either gate
+* branch, so the default cannot hurt them.
+*/
+function piAiRuntimeFor(resolvedFrom) {
+	if (resolvedFrom === void 0) return {
+		generation: "modern",
+		resolvedFrom: void 0,
+		version: void 0,
+		resolvedLocally: false
+	};
+	const version = readVersion(resolvedFrom);
+	return {
+		generation: generationOf(version),
+		resolvedFrom,
+		version,
+		resolvedLocally: true
+	};
+}
+/**
+* The file the main entry resolved to; undefined when resolution itself fails.
+*
+* `import.meta.resolve` (not `require.resolve`): pi-ai's exports map exposes
+* "." under the `import` condition only, so the CJS resolver refuses the bare
+* specifier outright — the ESM resolver is the one this plugin actually
+* imports with, so it is also the one whose answer is meaningful here.
+*/
+function resolveModuleFile() {
+	try {
+		return fileURLToPath(import.meta.resolve("@earendil-works/pi-ai"));
+	} catch {
+		return;
+	}
+}
+/**
+* The version of the package owning `moduleFile`. pi-ai's exports map does
+* not expose `./package.json`, so the manifest is found by walking up from
+* the resolved entry — `dist/index.js` sits directly inside the package —
+* and claiming it only when its `name` matches, so a same-named ancestor
+* (a pnpm virtual-store parent, for instance) cannot be misread.
+*/
+function readVersion(moduleFile) {
+	if (moduleFile === void 0) return void 0;
+	let directory = dirname(moduleFile);
+	for (let depth = 0; depth < 4; depth++) {
+		try {
+			const parsed = JSON.parse(readFileSync(join(directory, "package.json"), "utf8"));
+			if (parsed.name === "@earendil-works/pi-ai" && typeof parsed.version === "string") return parsed.version;
+		} catch {}
+		const parent = dirname(directory);
+		if (parent === directory) return void 0;
+		directory = parent;
+	}
+}
+/**
+* The generation a manifest version belongs to. Within the peer range
+* (<0.88.0) the split is exactly `0.87+` versus earlier; an unreadable
+* version conservatively reports `legacy` (and doctor shows it as
+* unreadable, so the guess is visible rather than silent).
+*/
+function generationOf(version) {
+	if (version === void 0) return "legacy";
+	const match = /^0\.(\d+)\./u.exec(version);
+	if (match === null) return "legacy";
+	return Number(match[1]) >= 87 ? "modern" : "legacy";
+}
+//#endregion
 //#region src/version.ts
 /** The npm package version this build was produced from. */
-const WORKBUDDY_CONNECT_VERSION = "3.0.2";
+const WORKBUDDY_CONNECT_VERSION = "3.3.0";
 //#endregion
 //#region src/host-heartbeat.ts
 /**
@@ -2444,4 +2678,4 @@ async function clearHostHeartbeat() {
 	await rm(workbuddyHostHeartbeatPath(), { force: true });
 }
 //#endregion
-export { WorkBuddyCredentialRejectedError as A, clearAtRestKeyCache as B, hasEncryptedCredentialFields as C, workbuddyAccountId as D, parseWorkBuddyAuth as E, parseReasoning as F, isEncryptedFieldWrapper as G, deriveAtRestKeyId as H, parseUpstreamModel as I, macosNestedAppBundles as J, isWorkbuddyBundle as K, prepareChatBody as L, classifyUpstreamError as M, isCredentialRejectedError as N, workbuddyOwnAuthPath as O, parseCreditMultiplier as P, regionOf as R, defaultDesktopAuthPath as S, legacyWorkbuddyOwnAuthPath as T, fetchAtRestKeyPayload as U, deriveAtRestKey as V, findWorkbuddyAppExecutable as W, readAtRestKey as X, openEncryptedField as Y, workbuddyAppExecutableCandidates as Z, WorkBuddyCredentialStore as _, readHostHeartbeat as a, defaultDesktopAuthCandidates as b, WORKBUDDY_CONNECT_VERSION as c, WorkBuddyCatalog as d, deriveCatalog as f, WORKBUDDY_AUTH_FILE_ENV as g, WORKBUDDY_AUTH_FILENAME as h, processStartTimeMs as i, WorkBuddyUpstreamClient as j, CREDENTIAL_REJECTED_CODE as k, FALLBACK_WORKBUDDY_MODELS as l, ENCRYPTED_CREDENTIAL_CODE as m, clearHostHeartbeat as n, workbuddyHostHeartbeatPath as o, fallbackModelsFor as p, macosBundleExecutable as q, isHeartbeatProcessAlive as r, writeHostHeartbeat as s, WORKBUDDY_HOST_HEARTBEAT_FILENAME as t, FALLBACK_WORKBUDDY_MODELS_GLOBAL as u, WorkBuddyEncryptedCredentialError as v, isEncryptedCredentialError as w, defaultDesktopAuthDirs as x, authFileName as y, WORKBUDDY_APP_EXECUTABLE_ENV as z };
+export { readAtRestKey as $, CREDENTIAL_REJECTED_CODE as A, prepareChatBody as B, defaultDesktopAuthPath as C, parseWorkBuddyAuth as D, legacyWorkbuddyOwnAuthPath as E, declaredTools as F, deriveAtRestKeyId as G, WORKBUDDY_APP_EXECUTABLE_ENV as H, isCredentialRejectedError as I, isEncryptedFieldWrapper as J, fetchAtRestKeyPayload as K, parseCreditMultiplier as L, WorkBuddyCredentialRejectedError as M, WorkBuddyUpstreamClient as N, workbuddyAccountId as O, classifyUpstreamError as P, openEncryptedField as Q, parseReasoning as R, defaultDesktopAuthDirs as S, isEncryptedCredentialError as T, clearAtRestKeyCache as U, regionOf as V, deriveAtRestKey as W, macosBundleExecutable as X, isWorkbuddyBundle as Y, macosNestedAppBundles as Z, WORKBUDDY_AUTH_FILE_ENV as _, readHostHeartbeat as a, authFileName as b, WORKBUDDY_CONNECT_VERSION as c, FALLBACK_WORKBUDDY_MODELS_GLOBAL as d, workbuddyAppExecutableCandidates as et, WorkBuddyCatalog as f, WORKBUDDY_AUTH_FILENAME as g, ENCRYPTED_CREDENTIAL_CODE as h, processStartTimeMs as i, WORKBUDDY_FALLBACK_SYSTEM_PROMPT as j, workbuddyOwnAuthPath as k, piAiRuntimeInfo as l, fallbackModelsFor as m, clearHostHeartbeat as n, workbuddyHostHeartbeatPath as o, deriveCatalog as p, findWorkbuddyAppExecutable as q, isHeartbeatProcessAlive as r, writeHostHeartbeat as s, WORKBUDDY_HOST_HEARTBEAT_FILENAME as t, FALLBACK_WORKBUDDY_MODELS as u, WorkBuddyCredentialStore as v, hasEncryptedCredentialFields as w, defaultDesktopAuthCandidates as x, WorkBuddyEncryptedCredentialError as y, parseUpstreamModel as z };

package/lib/index.d.ts

@@ -569,8 +569,9 @@ declare function classifyUpstreamError(status: number, body: string): UpstreamEr
 declare function regionOf(domain: string): WorkBuddyRegion;
 /**
  * Normalize an OpenAI chat-completions body for the WorkBuddy upstream:
- * force `stream: true` (the upstream rejects non-streaming) and flatten
- * `tool_choice` (the upstream's field is a string; object forms return 400).
+ * force `stream: true` (the upstream rejects non-streaming), flatten
+ * `tool_choice` (the upstream's field is a string; object forms return 400),
+ * and guarantee a leading system message.
  */
 declare function prepareChatBody(source: string): string;
 /** Marker carried by {@link WorkBuddyCredentialRejectedError}; survives bundling. */
@@ -792,12 +793,62 @@ interface WorkBuddyShim {
   /** Stop serving and destroy open connections. */
   close(): Promise<void>;
 }
+/**
+ * Supplies the credential to retry a failed chat request with.
+ *
+ * Called with every account id already tried for THIS request, the one that just
+ * failed LAST, and resolves to the next candidate — or `undefined` when the pool
+ * is off, empty, or exhausted, in which case the original failure is reported
+ * unchanged.
+ *
+ * The plugin owns the policy (which pool members count as usable, in what
+ * order); the shim owns only the retry loop and the wire-level rule that a
+ * retry may happen before anything has been written to the client.
+ */
+type WorkBuddyFailoverAccount = (triedAccountIds: readonly string[]) => Promise<WorkBuddyCredential | undefined>;
 /** Constructor dependencies. */
 interface WorkBuddyShimOptions {
   store: WorkBuddyCredentialStore;
   client: Pick<WorkBuddyUpstreamClient, 'chatStream'>;
   catalog: WorkBuddyCatalog;
   logger?: ShimLogger;
+  /**
+   * Pool failover for chat requests. Absent means no failover at all — the
+   * pre-pool behaviour, where the selected account serves and its failure is
+   * reported as-is.
+   */
+  failoverAccount?: WorkBuddyFailoverAccount;
+  /**
+   * Called before the FIRST attempt of every chat request, so the plugin can
+   * point the store at the account the pool's ranking says should serve.
+   *
+   * It exists because "who serves" and "who to retry with" are the same decision
+   * made at two moments: the ranking picks the first account, and after a failure
+   * picks the next one. The shim resolves the credential itself right after this
+   * returns, so the ranking never has to produce a credential — which keeps
+   * token REFRESH in one place (`store.resolve()`) instead of duplicating it on
+   * a path that would silently send expired tokens.
+   *
+   * Absent means the store's own selection always serves.
+   */
+  prepareAccount?: () => Promise<void>;
+  /**
+   * Called for every attempt that failed upstream, before the next one is tried.
+   *
+   * Exists so the plugin can RECORD the failure as a measurement. The ranking
+   * that picks the serving account reads the pool's STORED measurements, so
+   * without this an account that just answered 429 still reads as untested — and
+   * the next request picks it again and pays the same failed round trip before
+   * failing over.
+   *
+   * Fired without awaiting: a slow write must never delay the retry the user is
+   * waiting on, and the measurement only matters for LATER requests.
+   */
+  onAccountFailure?: (accountId: string, failure: {
+    status: number;
+    kind: UpstreamErrorKind;
+    message: string;
+  }) => void;
 }
 /**
  * Start the loopback endpoint. Requests must carry the shim's shared secret;
@@ -805,6 +856,56 @@ interface WorkBuddyShimOptions {
  */
 declare function createWorkBuddyShim(options: WorkBuddyShimOptions): WorkBuddyShim;
 //#endregion
+//#region src/pi-ai-runtime.d.ts
+/**
+ * Which `@earendil-works/pi-ai` copy THIS plugin actually resolves at runtime.
+ *
+ * WHY THIS EXISTS (issues #24 / #25 / #26). The plugin declares pi-ai as a
+ * peer (`>=0.85.0 <0.88.0`), so the module it imports is whatever the host
+ * environment provides — and the two generations consume DIFFERENT context
+ * shapes:
+ *
+ * - 0.87 hands providers a normalized transcript: `{ messages: [ {role:
+ *   'system', content, toolsAdded}, … ] }`. The system prompt and the tool
+ *   declarations live ONLY on that leading system message; the top-level
+ *   `systemPrompt` / `tools` fields are gone, and 0.87's api never reads them
+ *   back.
+ * - 0.85 expects `{ systemPrompt, tools, messages }` and has no branch for a
+ *   `system` message inside `messages` at all: its token estimator crashes on
+ *   one (issue #24), and its wire converter silently drops it.
+ *
+ * Which copy resolves is NOT predictable from the host version alone: a
+ * nested 0.85.1 on disk shadows the host's 0.87.1 (the plugin author's own
+ * symlinked checkout does exactly that), while a clean market install has no
+ * local copy at all and resolves the host's (issue #26's reporter). The
+ * adapter therefore gates on what THIS plugin resolves.
+ *
+ * HOW it is detected — deliberately WITHOUT importing pi-ai:
+ * `import.meta.resolve` locates the entry file (executing nothing), the
+ * package manifest sitting beside it names the version, and the generation is
+ * decided from that version (0.87+ → modern). A static import would drag
+ * pi-ai into the standalone `doctor` CLI, which must also run from market
+ * installs where NO local pi-ai exists and the module is only provided inside
+ * the DSH host — a static import there is a load-time crash. Resolution
+ * itself does not need the module: within the peer range, the manifest
+ * version and the `normalizeContext` feature (present from 0.87 on, not
+ * before) agree.
+ *
+ * When resolution FAILS — the normal state of a market install probed outside
+ * the host — there is no local copy, so inside DSH the host supplies pi-ai.
+ * Every DSH host that normalizes contexts (0.2.0+, via 0.87.1) also supplies
+ * 0.87.1, so the reported generation defaults to `modern` (pass-through).
+ * That default is safe on older hosts too: they never normalize, and a native
+ * 0.85-shaped context is an identity under BOTH branches of the adapter gate.
+ *
+ * `doctor` prints the resolved version and path so mixed-generation setups —
+ * the silent kind that produced #24 and #26 — become visible on demand.
+ *
+ * @module dsh-connect-workbuddy/pi-ai-runtime
+ */
+/** The resolved pi-ai generation, by context-shape capability. */
+type PiAiGeneration = 'modern' | 'legacy';
+//#endregion
 //#region src/adapter.d.ts
 /** Provider route this bundle owns for the domestic (CN) gateway. */
 declare const WORKBUDDY_PROVIDER = "workbuddy";
@@ -829,6 +930,12 @@ interface WorkBuddyAdapterOptions {
   displayName?: string;
   /** Resolve the durable attachment service at request time, when present. */
   resolveAttachments?: () => AttachmentStore | undefined;
+  /**
+   * Override the pi-ai generation gate (see {@link piAiRuntimeInfo}); tests
+   * inject both branches because this checkout only ever RESOLVES one of
+   * them. Production callers leave it unset.
+   */
+  piAiGeneration?: PiAiGeneration;
 }
 /** What {@link createWorkBuddyAdapter} hands back. */
 interface WorkBuddyAdapter {
@@ -1850,8 +1957,13 @@ interface WorkBuddyWebPoolAccount {
  */
 interface WorkBuddyWebPool {
   enabled: boolean;
-  rotateByCredits: boolean;
-  autoTestIntervalMinutes: number;
+  /**
+   * Whether this region offers the daily check-in at all.
+   *
+   * The card hides the action entirely when false, rather than rendering a
+   * button whose only outcome is a refusal.
+   */
+  checkinSupported: boolean;
   /** The model a test would use right now; absent when none can be resolved. */
   targetModelId?: string;
   /**
@@ -1879,15 +1991,6 @@ interface WorkBuddyWebPool {
    * ran on ZERO accounts and reported success.
    */
   effectiveMemberAccountIds?: readonly string[];
-  /**
-   * The account rotation most recently moved billing TO, when it moved.
-   *
-   * Reported so the card can record a switch it did not perform: rotation
-   * happens on the Host (including on a timer), and the card is otherwise
-   * unable to tell a switch from an unchanged state — which would make
-   * "every switch is recorded" a promise the UI could not keep.
-   */
-  rotatedToAccountId?: string;
   accounts: readonly WorkBuddyWebPoolAccount[];
   /**
    * The models a manual target can be chosen from.
@@ -2036,8 +2139,6 @@ interface WorkBuddyPoolDeps {
   /** The region's stored preferences, resolved from the Host config. */
   preferences(region: WorkBuddyRegion): {
     enabled: boolean;
-    rotateByCredits: boolean;
-    autoTestIntervalMinutes: number;
     targetModelId: string;
     memberAccountIds: readonly string[];
   };
@@ -2053,14 +2154,6 @@ interface WorkBuddyPoolDeps {
    * checked) instead of passing the guard and running a batch over nothing.
    */
   effectiveMemberAccountIds?(region: WorkBuddyRegion): Promise<readonly string[]>;
-  /**
-   * The account rotation last redirected billing to, when it did.
-   *
-   * Reported so the card can log a switch that happened on the Host (possibly
-   * on a timer) — without it, "every switch leaves a record" is a promise the
-   * browser half has no way to keep.
-   */
-  rotatedToAccountId?(region: WorkBuddyRegion): Promise<string | undefined>;
   /**
    * Today's check-in state per account id.
    *
@@ -2068,6 +2161,8 @@ interface WorkBuddyPoolDeps {
    * entry) means "not read", which the card renders as unknown rather than as a
    * definite "not checked in" — a claim that would contradict the check-in the
    * user just performed.
+   *
+   * Only the CN region has a check-in to report; see {@link checkinSupported}.
    */
   checkedInToday?(region: WorkBuddyRegion): Promise<Readonly<Record<string, boolean>>>;
   /**
@@ -2080,6 +2175,16 @@ interface WorkBuddyPoolDeps {
   }[]>;
   /** The account currently billing traffic for the region, when known. */
   currentAccountId?(region: WorkBuddyRegion): Promise<string | undefined>;
+  /**
+   * Whether this region offers the daily check-in action at all.
+   *
+   * The CN app rewards a daily check-in; the international region is not offered
+   * one here, so its card must not show the button and its route must refuse the
+   * action. A capability rather than a region name compared in the browser: the
+   * policy belongs in the Host, and the card should not have to know which
+   * regions happen to have the feature.
+   */
+  checkinSupported?(region: WorkBuddyRegion): boolean;
   /**
    * Claim the daily reward for every account of one region.
    *
@@ -2167,18 +2272,21 @@ interface WorkBuddyRegionState {
  * measurement living in the same slot would be rolled back by the next save.
  */
 interface WorkBuddyPoolPreferences {
-  /** Whether the pool is active for this region. Opt-in: default false. */
-  enabled?: boolean;
   /**
-   * Whether the plugin may choose the billed account by credits.
+   * Whether the pool is active for this region — which now means the
+   * FAILOVER switch, not a credit ranking.
    *
-   * Opt-in, and mutually exclusive with manual selection: while it is on, the
-   * card disables the account dropdown, because two writers deciding the same
-   * slot is exactly how "the dropdown says A but B is billed" happens.
+   * Opt-in: default false. While on, a chat request that fails upstream is
+   * retried against the other usable members of this region's pool, in order,
+   * until one serves it or none is left (see `src/shim.ts`). While off the
+   * plugin behaves exactly as it did before the pool existed: the account the
+   * user selected serves every request, and a failure is reported as-is.
+   *
+   * It deliberately does NOT change which account serves NEXT: failover is
+   * per-request borrowing, so the user's selection stays in effect and the
+   * card can keep reporting who really served.
    */
-  rotateByCredits?: boolean;
-  /** Minutes between automatic tests; clamped to 5..1440. */
-  autoTestIntervalMinutes?: number;
+  enabled?: boolean;
   /** Model id to test; `''` means auto-pick a free model from this region. */
   targetModelId?: string;
   /**