dsh-connect-workbuddy 4.9.4 → 4.10.1

package/lib/{host-heartbeat-BpArQi1Q.js → host-heartbeat-Cq4_pJ_l.js}

@@ -863,21 +863,93 @@ function fetchAtRestKeyPayload(executable) {
 let cachedKey;
 let inflightKey;
 /**
+* When the last FAILED lookup finished, epoch ms; 0 means "no recent failure".
+*
+* Issue #77: only a SUCCESS was remembered, so a machine where the key cannot
+* be obtained re-ran the whole discovery on every single probe. `scanAll()`
+* probes one auth file at a time, and a usage request scans several times, so
+* one page open re-ran the discovery dozens of times — each run being three
+* SYNCHRONOUS `reg query` child processes on the host's main thread when the
+* desktop app is not installed (measured 15.3 s of a 19.1 s request, 135
+* `reg.exe` spawns). A failure is therefore remembered for
+* {@link AT_REST_KEY_FAILURE_TTL_MS}: the answer cannot change within one page
+* open, while a user who installs or launches the app still sees it pick up
+* within that window instead of only after a restart.
+*/
+let failedKeyAtMs = 0;
+/** The discovery result behind the current key (or failure); see {@link discoverAppExecutable}. */
+let cachedAppExecutable;
+/**
+* How long a failed key lookup is remembered. Long enough to collapse the
+* dozens of probes one request makes, short enough that installing (or
+* launching) the desktop app takes effect without a restart.
+*/
+const AT_REST_KEY_FAILURE_TTL_MS = 6e4;
+/**
+* How long a NEGATIVE executable discovery is remembered.
+*
+* The negative answer is the expensive one: every candidate path misses, then
+* the Windows fallback shells out to `reg query` once per uninstall hive. The
+* positive answer is cached for the process lifetime instead — its path is
+* retried with `existsSync` on every call anyway, so an app that was moved or
+* removed still falls through to a fresh discovery.
+*/
+const APP_EXECUTABLE_MISS_TTL_MS = 6e4;
+/**
+* Locate the desktop executable through {@link findWorkbuddyAppExecutable},
+* remembering a MISS for {@link APP_EXECUTABLE_MISS_TTL_MS}.
+*
+* Only this module's own lookup is cached, and only when it goes through the
+* real seams: `findWorkbuddyAppExecutable` stays a pure function of its
+* arguments for `doctor` and for the injected-platform tests, which must keep
+* seeing the machine as it is right now.
+*/
+function discoverAppExecutable() {
+	const now = Date.now();
+	if (cachedAppExecutable !== void 0) {
+		if (now - cachedAppExecutable.foundAtMs < APP_EXECUTABLE_MISS_TTL_MS) return cachedAppExecutable.executable;
+		cachedAppExecutable = void 0;
+	}
+	const executable = findWorkbuddyAppExecutable();
+	if (executable === void 0) {
+		cachedAppExecutable = {
+			executable: "",
+			foundAtMs: now
+		};
+		return;
+	}
+	cachedAppExecutable = {
+		executable,
+		foundAtMs: Number.POSITIVE_INFINITY
+	};
+	return executable;
+}
+/**
 * 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.
+* build that rotates the payload).
+*
+* Both outcomes are cached: a success for the process lifetime (the app is
+* spawned at most once), a failure for {@link AT_REST_KEY_FAILURE_TTL_MS}. The
+* failure TTL is what keeps a machine WITHOUT the app from paying the
+* synchronous registry probe on every credential file — see {@link failedKeyAtMs}.
 */
 function readAtRestKey() {
 	if (cachedKey !== void 0) return Promise.resolve(cachedKey);
-	inflightKey ??= (async () => {
-		const executable = findWorkbuddyAppExecutable();
+	if (inflightKey !== void 0) return inflightKey;
+	if (failedKeyAtMs !== 0 && Date.now() - failedKeyAtMs < AT_REST_KEY_FAILURE_TTL_MS) return Promise.resolve(void 0);
+	inflightKey = (async () => {
+		const executable = discoverAppExecutable();
 		if (executable === void 0) return void 0;
-		const key = deriveAtRestKey(await fetchAtRestKeyPayload(executable));
+		return deriveAtRestKey(await fetchAtRestKeyPayload(executable));
+	})().then((key) => {
 		cachedKey = key;
+		failedKeyAtMs = key === void 0 ? Date.now() : 0;
 		return key;
-	})().finally(() => {
+	}, (error) => {
+		failedKeyAtMs = Date.now();
+		throw error;
+	}).finally(() => {
 		inflightKey = void 0;
 	});
 	return inflightKey;
@@ -886,6 +958,8 @@ function readAtRestKey() {
 function clearAtRestKeyCache() {
 	cachedKey = void 0;
 	inflightKey = void 0;
+	failedKeyAtMs = 0;
+	cachedAppExecutable = void 0;
 }
 //#endregion
 //#region src/upstream.ts
@@ -917,6 +991,19 @@ function clearAtRestKeyCache() {
 *
 * @module dsh-connect-workbuddy/upstream
 */
+/**
+* The write half of each campaign: the endpoint that actually grants the
+* credits.
+*
+* Kept beside the status paths because they must move together: the pair is
+* what the 「套餐与积分」 page itself uses (`xp`/`vp` in its bundle), and a
+* campaign whose status is read from one path can only be claimed through its
+* matching claim path. Note the same absence of a `/v2` prefix.
+*/
+const BENEFIT_CLAIM_PATHS = {
+	compensation: "/billing/meter/claim-compensation",
+	gift: "/billing/meter/claim-gift"
+};
 const CN_CHAT_BASE = "https://copilot.tencent.com";
 const CN_BILLING_BASE = "https://www.codebuddy.cn";
 const GLOBAL_BASE = "https://www.workbuddy.ai";
@@ -1921,6 +2008,90 @@ var WorkBuddyUpstreamClient = class {
 			...typeof data["claim_button_text"] === "string" && data["claim_button_text"] !== "" ? { claimButtonText: data["claim_button_text"] } : {}
 		};
 	}
+	/**
+	* Read every promotional benefit this account can still see, WITHOUT claiming
+	* anything.
+	*
+	* The campaign list is closed and small on purpose: the gateway exposes one
+	* status endpoint per campaign, so "discover benefits" is a fixed fan-out, not
+	* a search. A new campaign type means a new `/billing/meter/*-status` endpoint
+	* added here — the plugin never guesses at undocumented ones.
+	*
+	* Every endpoint is read in parallel because they are independent, and a
+	* failure is per-endpoint: one campaign answering 5xx must not blank out the
+	* other. The caller gets only what was actually read.
+	*
+	* Note the paths carry NO `/v2` prefix — these are not the `/v2/billing/meter`
+	* family the credit and check-in calls use. Probing `/v2/...` answers 404, which
+	* is how this distinction was found.
+	*/
+	async fetchBenefits(credential) {
+		const read = async (kind, path) => {
+			try {
+				return await this.readBenefitStatus(kind, credential, path);
+			} catch {
+				return;
+			}
+		};
+		const [compensation, gift] = await Promise.all([read("compensation", "/billing/meter/compensation-status"), read("gift", "/billing/meter/check-gift-claimed")]);
+		return [compensation, gift].filter((benefit) => benefit !== void 0);
+	}
+	/** One benefit status endpoint. Throws on anything that is not a clean `code: 0`. */
+	async readBenefitStatus(kind, credential, path) {
+		const response = await fetch(`${billingBase(credential)}${path}`, {
+			method: "POST",
+			headers: billingHeaders(credential),
+			body: "{}",
+			signal: AbortSignal.timeout(JSON_TIMEOUT_MS)
+		});
+		const envelope = await readEnvelope(response);
+		if (!response.ok || envelope.code !== 0) throw envelopeError(response.status, envelope);
+		const data = typeof envelope.data === "object" && envelope.data !== null ? envelope.data : {};
+		const numberField = (key) => typeof data[key] === "number" ? data[key] : 0;
+		/** The gateway states times as `YYYY-MM-DD HH:MM:SS` in local time. */
+		const timeField = (key) => {
+			const raw = data[key];
+			if (typeof raw !== "string" || raw.trim() === "") return void 0;
+			const parsed = Date.parse(raw.replace(" ", "T"));
+			return Number.isNaN(parsed) ? void 0 : parsed;
+		};
+		const endsAtMs = timeField("end_time");
+		const startsAtMs = timeField("start_time");
+		const claimedAtMs = timeField("claimed_at");
+		return {
+			kind,
+			active: data["active"] === true,
+			claimed: data["claimed"] === true,
+			creditNum: numberField("credit_num"),
+			...endsAtMs === void 0 ? {} : { endsAtMs },
+			...startsAtMs === void 0 ? {} : { startsAtMs },
+			...claimedAtMs === void 0 ? {} : { claimedAtMs }
+		};
+	}
+	/**
+	* Claim one benefit campaign on ONE account (issue #79).
+	*
+	* This is a real credit grant on a real account, so it takes no account
+	* argument other than the credential it is handed: the caller decides which
+	* single account, and there is deliberately no batch form of this method. The
+	* browser route is the only caller, and it guards the mutation with the same
+	* POST + loopback checks the check-in route carries.
+	*
+	* The response is not parsed: the documented envelope of these two endpoints
+	* is an empty success, and the caller re-reads the status afterwards. That
+	* re-read, not this answer, is what the user is shown — which is why a claim
+	* that silently did nothing still cannot leave the card saying 待领取.
+	*/
+	async claimBenefit(credential, kind) {
+		const response = await fetch(`${billingBase(credential)}${BENEFIT_CLAIM_PATHS[kind]}`, {
+			method: "POST",
+			headers: billingHeaders(credential),
+			body: "{}",
+			signal: AbortSignal.timeout(JSON_TIMEOUT_MS)
+		});
+		const envelope = await readEnvelope(response);
+		if (!response.ok || envelope.code !== 0) throw envelopeError(response.status, envelope);
+	}
 	/** Claim today's check-in reward. The browser route guards this mutation. */
 	async claimDailyCheckin(credential) {
 		const response = await fetch(`${billingBase(credential)}/v2/billing/meter/daily-checkin`, {
@@ -2766,8 +2937,17 @@ var WorkBuddyCredentialStore = class {
 	* Undefined means "no scan in flight and nothing cached".
 	*/
 	scanInflight;
-	/** When the cached scan was STARTED, epoch ms; only meaningful with it set. */
-	scanAtMs = 0;
+	/**
+	* When the cached scan FINISHED, epoch ms; 0 means "not finished yet".
+	*
+	* Deliberately the finish time, not the start time (issue #77). The window
+	* used to be measured from the START, so a scan that took longer than the
+	* window was already outside it the moment it landed: the very next `readAll`
+	* started a fresh scan, and the sharing this cache exists for never happened.
+	* On the machine in that report one scan took 1.4–2.1 s against a 1000 ms
+	* window, so every one of a page open's ~6 reads re-scanned the filesystem.
+	*/
+	scanFinishedAtMs = 0;
 	/**
 	* A RUNTIME account override from the pool's rotation, or undefined.
 	*
@@ -2924,28 +3104,38 @@ var WorkBuddyCredentialStore = class {
 	/**
 	* The account list, sharing one scan across concurrent and repeated reads.
 	*
-	* See {@link scanInflight}: the whole performance fix lives in these four
-	* lines. Every caller keeps its OWN semantics (`current`, `accounts`,
-	* `status`, `selectionLost`), because this returns the same array they used
-	* to build themselves — only the filesystem work is shared.
+	* See {@link scanInflight}: the whole performance fix lives in these lines.
+	* Every caller keeps its OWN semantics (`current`, `accounts`, `status`,
+	* `selectionLost`), because this returns the same array they used to build
+	* themselves — only the filesystem work is shared.
+	*
+	* The window runs from the FINISH time ({@link scanFinishedAtMs}), so a scan
+	* slower than the window still serves the reads that follow it. A scan in
+	* flight is always joined, however long it has been running.
 	*
 	* A failed scan is NOT cached: the rejection clears the slot so the next read
 	* retries, rather than pinning every later caller to one transient failure.
 	*/
 	async readAll() {
-		const now = Date.now();
-		if (this.scanInflight !== void 0 && now - this.scanAtMs < SCAN_SHARE_WINDOW_MS) return this.scanInflight;
-		this.scanAtMs = now;
-		this.scanInflight = this.scanAll().catch((error) => {
-			this.scanInflight = void 0;
+		if (this.scanInflight !== void 0) {
+			if (this.scanFinishedAtMs === 0 || Date.now() - this.scanFinishedAtMs < SCAN_SHARE_WINDOW_MS) return this.scanInflight;
+		}
+		this.scanFinishedAtMs = 0;
+		const scan = this.scanAll().then((credentials) => {
+			this.scanFinishedAtMs = Date.now();
+			return credentials;
+		}, (error) => {
+			if (this.scanInflight === scan) this.scanInflight = void 0;
+			this.scanFinishedAtMs = 0;
 			throw error;
 		});
-		return this.scanInflight;
+		this.scanInflight = scan;
+		return scan;
 	}
 	/** Drop the shared scan so the next read re-reads the filesystem. */
 	invalidateScan() {
 		this.scanInflight = void 0;
-		this.scanAtMs = 0;
+		this.scanFinishedAtMs = 0;
 	}
 	/** The one real scan: read every candidate file, then merge the vault. */
 	async scanAll() {
@@ -3977,7 +4167,7 @@ function generationOf(version) {
 //#endregion
 //#region src/version.ts
 /** The npm package version this build was produced from. */
-const WORKBUDDY_CONNECT_VERSION = "4.9.4";
+const WORKBUDDY_CONNECT_VERSION = "4.10.1";
 //#endregion
 //#region src/host-heartbeat.ts
 /**

package/lib/index.d.ts

@@ -267,8 +267,17 @@ declare class WorkBuddyCredentialStore {
    * Undefined means "no scan in flight and nothing cached".
    */
   private scanInflight;
-  /** When the cached scan was STARTED, epoch ms; only meaningful with it set. */
-  private scanAtMs;
+  /**
+   * When the cached scan FINISHED, epoch ms; 0 means "not finished yet".
+   *
+   * Deliberately the finish time, not the start time (issue #77). The window
+   * used to be measured from the START, so a scan that took longer than the
+   * window was already outside it the moment it landed: the very next `readAll`
+   * started a fresh scan, and the sharing this cache exists for never happened.
+   * On the machine in that report one scan took 1.4–2.1 s against a 1000 ms
+   * window, so every one of a page open's ~6 reads re-scanned the filesystem.
+   */
+  private scanFinishedAtMs;
   /**
    * A RUNTIME account override from the pool's rotation, or undefined.
    *
@@ -356,10 +365,14 @@ declare class WorkBuddyCredentialStore {
   /**
    * The account list, sharing one scan across concurrent and repeated reads.
    *
-   * See {@link scanInflight}: the whole performance fix lives in these four
-   * lines. Every caller keeps its OWN semantics (`current`, `accounts`,
-   * `status`, `selectionLost`), because this returns the same array they used
-   * to build themselves — only the filesystem work is shared.
+   * See {@link scanInflight}: the whole performance fix lives in these lines.
+   * Every caller keeps its OWN semantics (`current`, `accounts`, `status`,
+   * `selectionLost`), because this returns the same array they used to build
+   * themselves — only the filesystem work is shared.
+   *
+   * The window runs from the FINISH time ({@link scanFinishedAtMs}), so a scan
+   * slower than the window still serves the reads that follow it. A scan in
+   * flight is always joined, however long it has been running.
    *
    * A failed scan is NOT cached: the rejection clears the slot so the next read
    * retries, rather than pinning every later caller to one transient failure.
@@ -706,6 +719,47 @@ interface WorkBuddyCheckinClaim {
   streakDays: number;
   isStreakDay: boolean;
 }
+/**
+ * One promotional benefit the account may or may not still be entitled to.
+ *
+ * Read from the billing gateway's OWN status endpoints — the same two the
+ * 「套餐与积分」 page calls before it decides whether to render a claim card
+ * (`/billing/meter/compensation-status`, `/billing/meter/check-gift-claimed`).
+ * Reading them is what makes the card honest: the plugin shows a benefit only
+ * while the gateway itself would still show one.
+ *
+ * The two flags answer DIFFERENT questions and neither can be derived from the
+ * other — this is the single most important fact about this shape, measured on
+ * a real account pool:
+ *
+ *   - `active` is about the WINDOW, not about the reader. An account that has
+ *     already claimed still reports `active: true` (observed: `claimed: true`
+ *     together with `active: true` on a claimed gift), so `active` alone cannot
+ *     mean "claimable".
+ *   - `claimed` is about THIS account, and it survives the window: once the
+ *     campaign lapses the endpoint keeps answering `claimed: false` with
+ *     `active: false` (observed on every international account, whose campaign
+ *     ended months ago).
+ *
+ * Hence a benefit is claimable exactly when {@link active} AND NOT
+ * {@link claimed}. See `benefitOf` in `src/benefits.ts`.
+ */
+interface WorkBuddyBenefit {
+  /** Which campaign this is; the plugin renders one row per kind. */
+  kind: 'compensation' | 'gift';
+  /** The campaign is inside its window (empty, see: already claimed ≠ inactive). */
+  active: boolean;
+  /** This account has already taken it — permanently, even after the window. */
+  claimed: boolean;
+  /** Credits on offer, as the gateway states them. */
+  creditNum: number;
+  /** Window end, epoch ms. Absent when the gateway sent none it could parse. */
+  endsAtMs?: number;
+  /** Window start, epoch ms. Compensation omits it. */
+  startsAtMs?: number;
+  /** When this account claimed it, epoch ms. Only meaningful with `claimed`. */
+  claimedAtMs?: number;
+}
 /** Token refresh answer; fields the upstream omits stay absent. */
 interface WorkBuddyRefreshOutcome {
   accessToken: string;
@@ -934,6 +988,41 @@ declare class WorkBuddyUpstreamClient {
   fetchModels(credential: WorkBuddyCredential, signal?: AbortSignal): Promise<readonly WorkBuddyUpstreamModel[]>;
   /** Query today's check-in status without changing account state. */
   fetchCheckinStatus(credential: WorkBuddyCredential): Promise<WorkBuddyCheckinStatus>;
+  /**
+   * Read every promotional benefit this account can still see, WITHOUT claiming
+   * anything.
+   *
+   * The campaign list is closed and small on purpose: the gateway exposes one
+   * status endpoint per campaign, so "discover benefits" is a fixed fan-out, not
+   * a search. A new campaign type means a new `/billing/meter/*-status` endpoint
+   * added here — the plugin never guesses at undocumented ones.
+   *
+   * Every endpoint is read in parallel because they are independent, and a
+   * failure is per-endpoint: one campaign answering 5xx must not blank out the
+   * other. The caller gets only what was actually read.
+   *
+   * Note the paths carry NO `/v2` prefix — these are not the `/v2/billing/meter`
+   * family the credit and check-in calls use. Probing `/v2/...` answers 404, which
+   * is how this distinction was found.
+   */
+  fetchBenefits(credential: WorkBuddyCredential): Promise<readonly WorkBuddyBenefit[]>;
+  /** One benefit status endpoint. Throws on anything that is not a clean `code: 0`. */
+  private readBenefitStatus;
+  /**
+   * Claim one benefit campaign on ONE account (issue #79).
+   *
+   * This is a real credit grant on a real account, so it takes no account
+   * argument other than the credential it is handed: the caller decides which
+   * single account, and there is deliberately no batch form of this method. The
+   * browser route is the only caller, and it guards the mutation with the same
+   * POST + loopback checks the check-in route carries.
+   *
+   * The response is not parsed: the documented envelope of these two endpoints
+   * is an empty success, and the caller re-reads the status afterwards. That
+   * re-read, not this answer, is what the user is shown — which is why a claim
+   * that silently did nothing still cannot leave the card saying 待领取.
+   */
+  claimBenefit(credential: WorkBuddyCredential, kind: WorkBuddyBenefit['kind']): Promise<void>;
   /** Claim today's check-in reward. The browser route guards this mutation. */
   claimDailyCheckin(credential: WorkBuddyCredential): Promise<WorkBuddyCheckinClaim>;
   /**
@@ -1638,9 +1727,12 @@ 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.
+ * build that rotates the payload).
+ *
+ * Both outcomes are cached: a success for the process lifetime (the app is
+ * spawned at most once), a failure for {@link AT_REST_KEY_FAILURE_TTL_MS}. The
+ * failure TTL is what keeps a machine WITHOUT the app from paying the
+ * synchronous registry probe on every credential file — see {@link failedKeyAtMs}.
  */
 declare function readAtRestKey(): Promise<Buffer | undefined>;
 /** Drop the cached key; tests and diagnostics only. */
@@ -2011,6 +2103,29 @@ declare function probeModel(input: {
   signal?: AbortSignal;
 }): Promise<WorkBuddyProbeResult>;
 //#endregion
+//#region src/benefits.d.ts
+/** What the account card shows for one campaign. */
+type WorkBuddyBenefitState =
+/** Offered, inside its window, not taken yet. The only state with a claim button. */
+'claimable' |
+/** This account already took it. Rendered as nothing at all. */
+'claimed' |
+/** The window is over and it was never taken — the offer is gone. */
+'expired';
+/** One campaign, resolved for display. */
+interface WorkBuddyBenefitView {
+  kind: WorkBuddyBenefit['kind'];
+  state: WorkBuddyBenefitState;
+  /** Credits on offer, as the gateway stated them. */
+  creditNum: number;
+  /** Window end, epoch ms. */
+  endsAtMs?: number;
+  /** Whole days until the window closes, floored at 0. Absent without `endsAtMs`. */
+  daysLeft?: number;
+  /** True while the window closes within {@link URGENT_DAYS} days. */
+  urgent: boolean;
+}
+//#endregion
 //#region src/account-pool.d.ts
 /**
  * Which of the pool's writers produced a measurement.
@@ -2651,6 +2766,24 @@ type WorkBuddyWebPoolExclusion = 'unusable' | 'rate-limited' |
  * does not say (issue #56).
  */
 'model-busy' | 'out-of-credit' | 'credential-rejected' | 'not-found' | 'unavailable' | 'failed';
+/** One claimable benefit, as the card renders it (issue #79). */
+interface WorkBuddyWebBenefit {
+  /** Which campaign: compensation (crash补偿) or gift (新人首月赠送). */
+  kind: 'compensation' | 'gift';
+  /** Display name for the campaign, resolved Host-side so both clients agree. */
+  title: string;
+  /** Credits on offer. */
+  creditNum: number;
+  /**
+   * Whole days until the window closes, floored at 0.
+   *
+   * ABSENT when the gateway stated no end time — the card must then omit the
+   * countdown rather than print a number nobody knows.
+   */
+  daysLeft?: number;
+  /** True when the window closes within 3 days, so the card can say 即将到期. */
+  urgent: boolean;
+}
 /**
  * One account's row in the pool, as the card renders it.
  *
@@ -2727,6 +2860,16 @@ interface WorkBuddyWebPoolAccount {
    * result the user just watched succeed.
    */
   checkedInToday?: boolean;
+  /**
+   * Promotional benefits this account can STILL claim (issue #79).
+   *
+   * Never carries a claimed or lapsed campaign: the issue's rule is that those
+   * do not appear at all, so their absence here IS the "hide it" instruction.
+   * ABSENT means not read (or nothing claimable), and the card renders no line
+   * either way — a benefit line is only ever added to say "there is something
+   * here for you", never to announce its own absence.
+   */
+  benefits?: readonly WorkBuddyWebBenefit[];
   /**
    * The model a TEST of this row would use (issue #61).
    *
@@ -2884,7 +3027,7 @@ declare const WORKBUDDY_SETTINGS_NS: "workbuddy";
 interface WorkBuddyStatusRouteOptions {
   /** The region-scoped credential store backing each region's requests. */
   store(region: WorkBuddyRegion): WorkBuddyCredentialStore;
-  client: Pick<WorkBuddyUpstreamClient, 'fetchCredits' | 'fetchCheckinStatus' | 'claimDailyCheckin'>;
+  client: Pick<WorkBuddyUpstreamClient, 'fetchCredits' | 'fetchCheckinStatus' | 'claimDailyCheckin' | 'fetchBenefits' | 'claimBenefit'>;
   /**
    * The requested region's last-refreshed model directory (unfiltered) for
    * card display. Region-scoped because the CN and international apps expose
@@ -3170,6 +3313,37 @@ interface WorkBuddyPoolDeps {
    * per-account read in the full document.
    */
   cachedCheckedInToday?(region: WorkBuddyRegion): Readonly<Record<string, boolean>>;
+  /**
+   * Claimable promotional benefits per account id (issue #79).
+   *
+   * Only campaigns the account can STILL claim are present; a claimed or lapsed
+   * campaign is absent on purpose, so the card renders nothing for it. Absent
+   * (or a missing entry) also means "not read yet", which the card treats the
+   * same way — no line, rather than a guessed state.
+   */
+  benefits?(region: WorkBuddyRegion): Promise<Readonly<Record<string, readonly WorkBuddyBenefitView[]>>>;
+  /**
+   * Claimable benefits, from the readings already taken this process.
+   *
+   * The first-paint counterpart of {@link benefits}: no request, so painting
+   * never waits on two upstream reads per account.
+   */
+  cachedBenefits?(region: WorkBuddyRegion): Readonly<Record<string, readonly WorkBuddyBenefitView[]>>;
+  /**
+   * Forget this account's cached benefit reading so the next status read is live.
+   *
+   * The claim route writes to upstream directly, so nothing else in the plugin
+   * knows the campaign just changed. Without this the card kept showing 领取 for
+   * up to `BENEFIT_CACHE_MS` (30 min) after a SUCCESSFUL claim: the credits went
+   * up, the pill stayed, and the only remaining explanation was "the claim
+   * silently failed" — which invited a second click the route then refused as
+   * already-claimed. `checkin` has the same rule and invalidates its own cache;
+   * this is the benefit counterpart.
+   *
+   * Absent is legal (a Host from before this hook) and means "the click refreshes
+   * the card, but the host-side cache may still answer stale for a while".
+   */
+  invalidateBenefit?(region: WorkBuddyRegion, accountId: string): void;
   /**
    * Every local sign-in the pool does NOT cover, so the card can offer them to
    * check in. Absent means the card lists only pool members.