heybash-xdpool 1.0.4 → 1.0.6

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
package/lib/client.js CHANGED
@@ -6,6 +6,7 @@ window.__ModuleLoader__.load({
6
6
  Object.defineProperty(exports, Symbol.toStringTag, { value: "Module" });
7
7
  let react = require("react");
8
8
  let react_jsx_runtime = require("react/jsx-runtime");
9
+ let react_dom = require("react-dom");
9
10
  // src/client/sidebar-row.ts
10
11
  /**
11
12
  * The `sidebarRow` switch, read and written from one place.
@@ -1796,9 +1797,13 @@ window.__ModuleLoader__.load({
1796
1797
  .dsm-xdpool-dot[data-state='empty']{color:color-mix(in srgb, var(--dsw-alias-label-tertiary,#8a90a0) 85%, transparent)}
1797
1798
  .dsm-xdpool-dot:focus-visible{outline:2px solid var(--dsw-alias-brand-primary,#5686fe);outline-offset:3px}
1798
1799
  /* Measured coordinates, not flow: the composer sits at the bottom of the viewport, so a
1799
- panel laid out downward would be clipped. */
1800
- .dsm-xdpool-dotpanel{position:fixed;z-index:80;width:max-content;min-width:172px;max-width:min(280px,calc(100vw - 24px));display:flex;flex-direction:column;gap:7px;padding:10px 12px 11px;border-radius:14px;border:1px solid color-mix(in srgb, var(--dsw-alias-border-l2,#ffffff1f) 92%, transparent);background:var(--dsw-alias-bg-layer-2,#1c1e22);box-shadow:0 18px 48px rgb(0 0 0 / 44%),0 3px 10px rgb(0 0 0 / 24%),inset 0 1px 0 rgb(255 255 255 / 7%);animation:dsm-xdpool-dotpanel-in .16s cubic-bezier(.16,1,.3,1)}
1801
- @keyframes dsm-xdpool-dotpanel-in{from{opacity:0;transform:translateY(5px) scale(.985)}to{opacity:1;transform:none}}
1800
+ panel laid out downward would be clipped.
1801
+
1802
+ fixed is required, not incidental: the panel is portaled to document.body, so it has
1803
+ no dot wrapper to anchor to. Placement accounts for visual viewport offsets
1804
+ when a zoomed viewport is smaller than the layout viewport. */
1805
+ .dsm-xdpool-dotpanel{position:fixed;z-index:80;box-sizing:border-box;width:max-content;min-width:min(172px,calc(100vw - 16px));max-width:min(280px,calc(100vw - 16px));max-height:calc(100vh - 16px);overflow-y:auto;display:flex;flex-direction:column;gap:7px;padding:10px 12px 11px;border-radius:14px;border:1px solid color-mix(in srgb, var(--dsw-alias-border-l2,#ffffff1f) 92%, transparent);background:var(--dsw-alias-bg-layer-2,#1c1e22);box-shadow:0 18px 48px rgb(0 0 0 / 44%),0 3px 10px rgb(0 0 0 / 24%),inset 0 1px 0 rgb(255 255 255 / 7%);animation:dsm-xdpool-dotpanel-in .16s cubic-bezier(.16,1,.3,1)}
1806
+ @keyframes dsm-xdpool-dotpanel-in{from{opacity:0}to{opacity:1}}
1802
1807
  .dsm-xdpool-dotpanel-head{display:flex;align-items:center;gap:8px;min-width:0}
1803
1808
  .dsm-xdpool-dotpanel-channel{font-size:12.5px;font-weight:600;letter-spacing:.01em;color:var(--dsw-alias-label-primary,#e8eaf0);overflow:hidden;text-overflow:ellipsis;white-space:nowrap;min-width:0}
1804
1809
  .dsm-xdpool-dotpanel-chip{margin-left:auto;padding:1px 8px;border-radius:999px;font-size:10px;line-height:16px;font-weight:500}
@@ -7888,6 +7893,32 @@ window.__ModuleLoader__.load({
7888
7893
  "anthropic-messages": "/messages"
7889
7894
  });
7890
7895
  typeof process === "undefined" || process.platform;
7896
+ // src/member-id.ts
7897
+ /** A login channel member has a colon before any slash in its model id. */
7898
+ function channelMemberOf(id) {
7899
+ const colon = id.indexOf(":");
7900
+ if (colon <= 0) return void 0;
7901
+ const channel = id.slice(0, colon);
7902
+ const model = id.slice(colon + 1);
7903
+ if (!/^[A-Za-z0-9_-]+$/u.test(channel) || model === "" || model.startsWith("//")) return void 0;
7904
+ return {
7905
+ channel,
7906
+ model: id
7907
+ };
7908
+ }
7909
+ /** Remove repeated legacy slash prefixes while preserving canonical colon IDs. */
7910
+ function memberForOwner(owner, model) {
7911
+ if (owner === "workbuddy") return model;
7912
+ while (model.startsWith(`${owner}/`)) model = model.slice(owner.length + 1);
7913
+ while (model.startsWith(`${owner}:${owner}:`)) model = model.slice(owner.length + 1);
7914
+ return model;
7915
+ }
7916
+ /** Flatten one editor member; canonical channel IDs are already complete. */
7917
+ function flattenMember(owner, model) {
7918
+ const value = memberForOwner(owner, model);
7919
+ if (owner === "workbuddy" || channelMemberOf(value)?.channel === owner) return value;
7920
+ return `${owner}/${value}`;
7921
+ }
7891
7922
  Object.freeze({
7892
7923
  "openai-chat": "chat",
7893
7924
  "openai-responses": "responses",
@@ -10136,17 +10167,11 @@ window.__ModuleLoader__.load({
10136
10167
  * a fallback that never happened. A pool model is its bare id; anything else is
10137
10168
  * `owner/model`, the same composite id the aggregate catalog publishes.
10138
10169
  */
10139
- function bareForOwner(owner, model) {
10140
- if (owner === "workbuddy") return model;
10141
- while (model.startsWith(`${owner}/`) || model.startsWith(`${owner}:`)) model = model.slice(owner.length + 1);
10142
- return model;
10143
- }
10144
10170
  function flattenDraft(platforms) {
10145
10171
  const out = [];
10146
10172
  const seen = /* @__PURE__ */ new Set();
10147
10173
  for (const platform of platforms) for (const model of platform.models) {
10148
- const bare = bareForOwner(platform.owner, model);
10149
- const id = platform.owner === "workbuddy" ? bare : `${platform.owner}/${bare}`;
10174
+ const id = flattenMember(platform.owner, model);
10150
10175
  if (seen.has(id)) continue;
10151
10176
  seen.add(id);
10152
10177
  out.push(id);
@@ -10174,17 +10199,16 @@ window.__ModuleLoader__.load({
10174
10199
  const owner = typeof group.owner === "string" ? group.owner : "workbuddy";
10175
10200
  return {
10176
10201
  owner,
10177
- models: Array.isArray(group.models) ? [...new Set(group.models.filter((model) => typeof model === "string").map((model) => bareForOwner(owner, model)))] : []
10202
+ models: Array.isArray(group.models) ? [...new Set(group.models.filter((model) => typeof model === "string").map((model) => memberForOwner(owner, model)))] : []
10178
10203
  };
10179
10204
  });
10180
10205
  const known = new Set(Array.isArray(combo.models) ? combo.models : []);
10181
10206
  for (const modelId of Array.isArray(combo.missing) ? combo.missing : []) {
10182
10207
  if (known.has(modelId)) continue;
10208
+ const channel = channelMemberOf(modelId);
10183
10209
  const slash = modelId.indexOf("/");
10184
- const colon = modelId.indexOf(":");
10185
- const separator = slash === -1 ? colon : colon === -1 ? slash : Math.min(slash, colon);
10186
- const owner = separator === -1 ? "workbuddy" : modelId.slice(0, separator);
10187
- const model = bareForOwner(owner, separator === -1 ? modelId : modelId.slice(separator + 1));
10210
+ const owner = channel?.channel ?? (slash === -1 ? "workbuddy" : modelId.slice(0, slash));
10211
+ const model = channel?.model ?? memberForOwner(owner, slash === -1 ? modelId : modelId.slice(slash + 1));
10188
10212
  const group = platforms.find((entry) => entry.owner === owner);
10189
10213
  if (group === void 0) platforms.push({
10190
10214
  owner,
@@ -10765,7 +10789,7 @@ window.__ModuleLoader__.load({
10765
10789
  }) : /* @__PURE__ */ (0, react_jsx_runtime.jsx)("ol", {
10766
10790
  className: "dsm-xdpool-rt-members",
10767
10791
  children: platform.models.map((model, modelIndex) => {
10768
- const fullId = platform.owner === "workbuddy" ? model : `${platform.owner}/${model}`;
10792
+ const fullId = flattenMember(platform.owner, model);
10769
10793
  const candidate = candidateById.get(fullId);
10770
10794
  return /* @__PURE__ */ (0, react_jsx_runtime.jsxs)("li", {
10771
10795
  className: "dsm-xdpool-rt-member",
@@ -13294,7 +13318,7 @@ window.__ModuleLoader__.load({
13294
13318
  }
13295
13319
  // src/version.ts
13296
13320
  /** Version embedded in the browser bundle at build time from the package manifest. */
13297
- const POOL_VERSION = "1.0.4";
13321
+ const POOL_VERSION = "1.0.6";
13298
13322
  // src/client/PoolCard.tsx
13299
13323
  /**
13300
13324
  * Heybash card contributed to DSH Plugin configuration.
@@ -15821,6 +15845,21 @@ window.__ModuleLoader__.load({
15821
15845
  *
15822
15846
  * @module dsh-xdpool/client/credit-strip
15823
15847
  */
15848
+ // src/client/credit-position.ts
15849
+ /** Position a measured panel above its trigger, flipping and clamping at viewport edges. */
15850
+ function creditPanelPosition(anchor, panel, viewport) {
15851
+ const margin = 8;
15852
+ const minLeft = (viewport.left ?? 0) + margin;
15853
+ const minTop = (viewport.top ?? 0) + margin;
15854
+ const left = Math.min(Math.max(minLeft, anchor.left + anchor.width / 2 - panel.width / 2), Math.max(minLeft, (viewport.left ?? 0) + viewport.width - panel.width - margin));
15855
+ const above = anchor.top - panel.height - margin;
15856
+ const below = anchor.bottom + margin;
15857
+ const preferAbove = above >= minTop || anchor.top - (viewport.top ?? 0) >= (viewport.top ?? 0) + viewport.height - anchor.bottom;
15858
+ return {
15859
+ top: Math.min(Math.max(minTop, preferAbove ? above : below), Math.max(minTop, (viewport.top ?? 0) + viewport.height - panel.height - margin)),
15860
+ left
15861
+ };
15862
+ }
15824
15863
  // src/client/nav-icon.ts
15825
15864
  /**
15826
15865
  * Nav glyph for the Heybash settings page.
@@ -15913,10 +15952,8 @@ window.__ModuleLoader__.load({
15913
15952
  *
15914
15953
  * POSITIONING AND DISMISSAL ARE DONE HERE
15915
15954
  *
15916
- * The host's own floating primitive is internal to its packages, so this uses a fixed
15917
- * anchor measured from the button plus a document-level listener for outside clicks and
15918
- * Escape. That is the same contract the host's meters use, implemented locally rather
15919
- * than depending on a module this bundle cannot import.
15955
+ * The panel is portaled to the document body so transformed or clipping composer
15956
+ * ancestors cannot change the coordinate system of its fixed position.
15920
15957
  *
15921
15958
  * @module dsh-xdpool/client/CreditDot
15922
15959
  */
@@ -16154,69 +16191,57 @@ window.__ModuleLoader__.load({
16154
16191
  observer.disconnect();
16155
16192
  };
16156
16193
  }, []);
16157
- /**
16158
- * Place the panel above the dot.
16159
- *
16160
- * Measured rather than CSS-anchored because the composer row can be at the bottom of
16161
- * the viewport, and a panel that opens downward would be clipped by it. `side: top`
16162
- * with a viewport clamp is the same rule the host's own meters follow.
16163
- */
16194
+ /** Keep the anchor and fixed panel in layout-viewport CSS coordinates. */
16164
16195
  (0, react.useLayoutEffect)(() => {
16165
16196
  if (!open) {
16166
16197
  setPos(void 0);
16167
16198
  return;
16168
16199
  }
16169
16200
  const anchor = anchorRef.current;
16170
- if (anchor === null) return;
16171
- const box = anchor.getBoundingClientRect();
16172
- /**
16173
- * The panel sizes to its content (`width: max-content`), so its width can only be
16174
- * read AFTER it has rendered. A hard-coded number here was what made a short line of
16175
- * text sit in a 300px box: the width came from this layout maths rather than from
16176
- * what the text needed. Measuring the element keeps the two in step.
16177
- *
16178
- * Falling back to 200 when the ref is not attached yet (first frame) is safe: the
16179
- * effect re-runs on `open`, and the panel is `visibility: hidden` until `pos` exists.
16180
- */
16181
- const width = panelRef.current?.offsetWidth ?? 200;
16182
- const margin = 8;
16183
- const left = Math.min(Math.max(margin, box.left + box.width / 2 - width / 2), Math.max(margin, window.innerWidth - width - margin));
16184
- const panelHeight = panelRef.current?.offsetHeight ?? 240;
16185
- const above = box.top - panelHeight - 8;
16186
- const top = above >= margin ? above : box.bottom + 8;
16187
- setPos({
16188
- top,
16189
- left
16190
- });
16191
- }, [open]);
16192
- /**
16193
- * Re-measure once the panel has painted.
16194
- *
16195
- * `width: max-content` means the first pass measures a zero-width element: the panel is
16196
- * attached but `pos` is still undefined, so it is laid out at its min-width. Re-running
16197
- * after the content exists is what makes the width follow the text rather than the
16198
- * placeholder. Keyed on the model and the channel so a longer name (a real possibility
16199
- * with a `· 14,031` suffix) triggers a fresh measurement.
16200
- */
16201
- (0, react.useLayoutEffect)(() => {
16202
- if (!open) return;
16203
- const anchor = anchorRef.current;
16204
16201
  const panel = panelRef.current;
16205
16202
  if (anchor === null || panel === null) return;
16206
- const box = anchor.getBoundingClientRect();
16207
- const width = panel.offsetWidth;
16208
- const margin = 8;
16209
- const left = Math.min(Math.max(margin, box.left + box.width / 2 - width / 2), Math.max(margin, window.innerWidth - width - margin));
16210
- const above = box.top - panel.offsetHeight - 8;
16211
- setPos((current) => {
16212
- if (current === void 0) return current;
16213
- const top = above >= margin ? above : box.bottom + 8;
16214
- if (current.top === top && current.left === left) return current;
16215
- return {
16203
+ let frame;
16204
+ const update = () => {
16205
+ frame = void 0;
16206
+ const box = anchor.getBoundingClientRect();
16207
+ const panelBox = {
16208
+ width: panel.offsetWidth,
16209
+ height: panel.offsetHeight
16210
+ };
16211
+ const vv = window.visualViewport;
16212
+ const { left, top } = creditPanelPosition(box, panelBox, vv === null || vv === void 0 ? {
16213
+ width: window.innerWidth,
16214
+ height: window.innerHeight
16215
+ } : {
16216
+ width: vv.width,
16217
+ height: vv.height,
16218
+ left: vv.offsetLeft,
16219
+ top: vv.offsetTop
16220
+ });
16221
+ setPos((current) => current?.top === top && current.left === left ? current : {
16216
16222
  top,
16217
16223
  left
16218
- };
16219
- });
16224
+ });
16225
+ };
16226
+ const schedule = () => {
16227
+ if (frame === void 0) frame = window.requestAnimationFrame(update);
16228
+ };
16229
+ update();
16230
+ const observer = typeof ResizeObserver === "undefined" ? void 0 : new ResizeObserver(schedule);
16231
+ observer?.observe(anchor);
16232
+ observer?.observe(panel);
16233
+ window.addEventListener("resize", schedule);
16234
+ window.addEventListener("scroll", schedule, true);
16235
+ window.visualViewport?.addEventListener("resize", schedule);
16236
+ window.visualViewport?.addEventListener("scroll", schedule);
16237
+ return () => {
16238
+ observer?.disconnect();
16239
+ window.removeEventListener("resize", schedule);
16240
+ window.removeEventListener("scroll", schedule, true);
16241
+ window.visualViewport?.removeEventListener("resize", schedule);
16242
+ window.visualViewport?.removeEventListener("scroll", schedule);
16243
+ if (frame !== void 0) window.cancelAnimationFrame(frame);
16244
+ };
16220
16245
  }, [
16221
16246
  open,
16222
16247
  snapshot?.model,
@@ -16290,7 +16315,7 @@ window.__ModuleLoader__.load({
16290
16315
  "aria-hidden": "true"
16291
16316
  })
16292
16317
  }),
16293
- !open ? null : /* @__PURE__ */ (0, react_jsx_runtime.jsxs)("div", {
16318
+ !open || typeof document === "undefined" ? null : (0, react_dom.createPortal)(/* @__PURE__ */ (0, react_jsx_runtime.jsxs)("div", {
16294
16319
  ref: panelRef,
16295
16320
  className: "dsm-xdpool-dotpanel",
16296
16321
  role: "dialog",
@@ -16358,7 +16383,7 @@ window.__ModuleLoader__.load({
16358
16383
  })
16359
16384
  }) : null
16360
16385
  ] })]
16361
- })
16386
+ }), document.body)
16362
16387
  ]
16363
16388
  });
16364
16389
  }
package/lib/index.d.ts CHANGED
@@ -572,8 +572,17 @@ export declare class WorkBuddyUpstreamClient {
572
572
  * list is missing half its entries for the rest of the session".
573
573
  */
574
574
  private fetchModelsOnce;
575
- /** Read-only credits query, aggregated by package. Does not consume credits. */
576
- fetchCredits(credential: WorkBuddyCredential): Promise<WorkBuddyCredits>;
575
+ /**
576
+ * Read-only credits query, aggregated by package. Does not consume credits.
577
+ *
578
+ * `signal` is the caller's cancellation, merged with the built-in timeout
579
+ * rather than replacing it: the pool's background warm must give up when the
580
+ * host shuts down, and a caller that has already gone away must not leave a
581
+ * 30 s request running. `AbortSignal.any` is already the repo's way of
582
+ * combining these (see the pricing probe in the shim), and the timeout stays
583
+ * in force so a signal-less caller keeps the old behaviour exactly.
584
+ */
585
+ fetchCredits(credential: WorkBuddyCredential, signal?: AbortSignal): Promise<WorkBuddyCredits>;
577
586
  /** Query today's check-in status without changing account state. */
578
587
  fetchCheckinStatus(credential: WorkBuddyCredential): Promise<WorkBuddyCheckinStatus>;
579
588
  /** Claim today's check-in reward. The browser route guards this mutation. */
@@ -835,6 +844,41 @@ interface TokenRefresher {
835
844
  domain?: string;
836
845
  }>;
837
846
  }
847
+ /**
848
+ * Minimal billing surface the pool needs to fill `creditExpiry` itself.
849
+ *
850
+ * Declared here for the same reason as {@link TokenRefresher}: the pool knows
851
+ * about accounts, not about HTTP, and importing `WorkBuddyUpstreamClient` would
852
+ * make the two modules circular. `fetchCredits` is OPTIONAL so every existing
853
+ * `TokenRefresher` — the test stubs, and any host that only wired token refresh
854
+ * — keeps working untouched; a client without it simply warms nothing.
855
+ */
856
+ interface CreditReader {
857
+ fetchCredits(credential: WorkBuddyCredential, signal?: AbortSignal): Promise<{
858
+ total: number;
859
+ /** Absent (or undefined) when no one-off pack has a deadline. */
860
+ nearestExpiryMs?: number | undefined;
861
+ }>;
862
+ }
863
+ /**
864
+ * What the pool knows about one account's one-off pack deadlines.
865
+ *
866
+ * The three `state`s are the whole point of the B+ fix: "never asked", "asked,
867
+ * nothing has a deadline" and "asked, here is the deadline" need different
868
+ * handling, and collapsing them into one absent-key predicate is what made a
869
+ * pure monthly-pack account be re-read forever (S1 in
870
+ * `EXPIRY-ADVERSARIAL-20261111.md`). `stale` is orthogonal: the reading is real
871
+ * but older than {@link EXPIRY_READING_TTL_MS}, so it describes the past.
872
+ */
873
+ interface ExpiryReading {
874
+ state: 'unread' | 'none' | 'at';
875
+ /** Deadline, epoch ms; present exactly when `state === 'at'`. */
876
+ at?: number;
877
+ /** When this reading was written, epoch ms; absent for `unread`. */
878
+ readAtMs?: number;
879
+ /** True when the reading is older than {@link EXPIRY_READING_TTL_MS}. */
880
+ stale: boolean;
881
+ }
838
882
  /** Live auth file name the WorkBuddy desktop app writes. */
839
883
  export declare const WORKBUDDY_LIVE_FILENAME = "workbuddy-desktop.info";
840
884
  /** Snapshot files left behind by previous logins share this prefix. */
@@ -963,9 +1007,16 @@ interface AccountPoolOptions {
963
1007
  */
964
1008
  credentialDeadCooldownMs?: number;
965
1009
  /** Upstream client used to refresh near-expiry tokens. */
966
- client?: TokenRefresher;
1010
+ client?: TokenRefresher & Partial<CreditReader>;
967
1011
  /** Refresh this long before actual expiry; default five minutes. */
968
1012
  refreshMarginMs?: number;
1013
+ /**
1014
+ * How long a credit-pack deadline reading is trusted, in ms.
1015
+ *
1016
+ * Defaults to {@link EXPIRY_READING_TTL_MS}; overridable so a test can age a
1017
+ * reading without sleeping for an hour.
1018
+ */
1019
+ expiryReadingTtlMs?: number;
969
1020
  /**
970
1021
  * How requests are spread across the pool.
971
1022
  *
@@ -1017,6 +1068,7 @@ export declare class WorkBuddyAccountPool {
1017
1068
  private credentialDeadCooldownMs;
1018
1069
  private readonly client;
1019
1070
  private readonly refreshMarginMs;
1071
+ private readonly expiryReadingTtlMs;
1020
1072
  private accounts;
1021
1073
  /**
1022
1074
  * Files the last scan could not read, with the reason.
@@ -1112,10 +1164,41 @@ export declare class WorkBuddyAccountPool {
1112
1164
  * their own cycle and are therefore never urgent — which is why this is
1113
1165
  * written from the same `fetchCredits` reading that fills `creditBalances`.
1114
1166
  *
1115
- * An absent entry means "never probed, or nothing is about to expire". Both
1116
- * are the same thing to `expiry` mode: not urgent, so it sorts last.
1167
+ * A positive value is a deadline. The two other states are kept in
1168
+ * {@link creditExpiryNone} and {@link creditExpiryReadAt} rather than as a
1169
+ * missing key, because a missing key cannot tell "we never looked" from "we
1170
+ * looked and nothing has a deadline" — and only the first is worth reading
1171
+ * again. An account whose packs are all monthly reads as `none` forever, which
1172
+ * is exactly right: asking again cannot change the answer (S1).
1117
1173
  */
1118
1174
  private creditExpiry;
1175
+ /**
1176
+ * Accounts whose last reading found NO one-off deadline (all monthly packs, or
1177
+ * none at all). Written instead of deleting the key, so the account stops
1178
+ * being a candidate for re-reading.
1179
+ */
1180
+ private creditExpiryNone;
1181
+ /** When each account's deadline reading was taken, epoch ms. */
1182
+ private creditExpiryReadAt;
1183
+ /**
1184
+ * Accounts whose deadline reading is being fetched right now.
1185
+ *
1186
+ * Same de-duplication idea as {@link refreshInflight}, for the same reason: a
1187
+ * scan-triggered warm and a request-triggered top-up must not both spend a
1188
+ * billing round trip on the same account. A Set rather than a Map of promises
1189
+ * because no caller ever awaits the warm — the point is only that a second
1190
+ * pass skips it.
1191
+ */
1192
+ private expiryWarmInflight;
1193
+ /**
1194
+ * Last time the pool tried to warm an account's deadline reading, epoch ms.
1195
+ *
1196
+ * The TTL is the success gate, not a retry gate: a failed read writes nothing,
1197
+ * so without this a permanently failing billing endpoint would be hit on every
1198
+ * scan and every served request. One attempt per account per minute is cheap
1199
+ * and still recovers quickly from a transient failure.
1200
+ */
1201
+ private expiryWarmAttemptAt;
1119
1202
  /**
1120
1203
  * Last time each account served a request, epoch ms. Drives the idle term
1121
1204
  * of the priority-mode weighting below: an account that just served loses to
@@ -1210,6 +1293,47 @@ export declare class WorkBuddyAccountPool {
1210
1293
  private pruneExpiredSnapshots;
1211
1294
  /** Rescan the auth directories and merge newly discovered accounts. */
1212
1295
  scan(): Promise<WorkBuddyAccount[]>;
1296
+ /**
1297
+ * Warm the deadline readings that `expiry` mode sorts on.
1298
+ *
1299
+ * Fire-and-forget on purpose, from `scan()`: the pool's first request arrives
1300
+ * before any reading exists, and the honest answer to that is the documented
1301
+ * fallback plus a log line, not a stalled request. Everything about the call
1302
+ * is chosen to be unable to make things worse:
1303
+ *
1304
+ * - `this.client` may not exist (a host that wired only token refresh), in
1305
+ * which case there is nothing to read with and the pass is a no-op — the
1306
+ * same guard `ensureFresh` uses;
1307
+ * - a dead sign-in is skipped, and a successful read NEVER calls
1308
+ * `clearCredentialDead`. That is the difference between this and
1309
+ * `reviveBenched`: the billing endpoint answers 200 for a banned account
1310
+ * (observed on 11140), so treating a read as proof of health is what got a
1311
+ * banned account revived six times in a day (S2). Only a token refresh or a
1312
+ * fresh sign-in may clear that mark;
1313
+ * - accounts whose reading is fresh enough are skipped, and so are accounts
1314
+ * already being read (S10's de-duplication, mirroring `refreshInflight`);
1315
+ * - a failed read writes nothing and only warns, so the next pass tries
1316
+ * again without the failure being mistaken for a reading.
1317
+ */
1318
+ private warmExpiryReadings;
1319
+ /** One account's warm read; see {@link warmExpiryReadings} for the rules. */
1320
+ private warmOneExpiryReading;
1321
+ /**
1322
+ * Top up one account's deadline reading, from wherever the pool notices it is
1323
+ * missing or stale.
1324
+ *
1325
+ * The request path is the second caller (after `scan()`), because a reading
1326
+ * ages out while the pool is busy too: the shim calls this for the account that
1327
+ * just served a request, which is the one whose spend is most likely to have
1328
+ * moved its deadline. No timer is created — the existing balance refresh is
1329
+ * already the natural heartbeat, and this rides on it.
1330
+ *
1331
+ * Every gate lives here rather than in the callers, so both paths obey exactly
1332
+ * the same rules: no client, no account, a rejected sign-in, an already-running
1333
+ * read, a finished "nothing expires" answer, a fresh reading, or an attempt
1334
+ * made within the last minute all mean "do nothing".
1335
+ */
1336
+ warmExpiryReadingFor(accountId: string): void;
1213
1337
  /** All accounts, cooldown state included. */
1214
1338
  list(region?: WorkBuddyRegion): readonly WorkBuddyAccount[];
1215
1339
  /**
@@ -1331,6 +1455,14 @@ export declare class WorkBuddyAccountPool {
1331
1455
  * A pool where nobody has a known expiry therefore behaves exactly like
1332
1456
  * priority, which is the honest degradation: without a reading there is
1333
1457
  * nothing to sort by.
1458
+ *
1459
+ * What this method must NOT do is pretend. With only SOME readings in hand it
1460
+ * still has to fall back to `pool[0]`, because picking the earliest of the
1461
+ * accounts that happen to have answered would silently drop the account that
1462
+ * really dies first — the failure mode S0 in `EXPIRY-ADVERSARIAL-20261111.md`
1463
+ * called "worse than not fixing it", since the pick looks plausible and is
1464
+ * wrong. So the incomplete case is announced instead: the caller keeps the old
1465
+ * semantics and the log says which accounts were not read.
1334
1466
  */
1335
1467
  private pickByExpiry;
1336
1468
  /**
@@ -1423,10 +1555,50 @@ export declare class WorkBuddyAccountPool {
1423
1555
  * merged: a pack that has been spent or has died disappears from the next
1424
1556
  * reading, and keeping the stale deadline would pin the pool to an account
1425
1557
  * whose credits are already gone — the opposite of what `expiry` mode wants.
1558
+ *
1559
+ * "Nothing expires" is a real answer, not the absence of one: it is stored as
1560
+ * {@link creditExpiryNone} so the account is not read again on every pass.
1426
1561
  */
1427
1562
  noteCredits(accountId: string, balance: number, nearestExpiryMs?: number): void;
1563
+ /**
1564
+ * Record ONLY the deadline, never the balance.
1565
+ *
1566
+ * The scan-triggered warm exists to fill `expiry` mode's sort key. Writing the
1567
+ * balance as a side effect would change what the reserve floor decides — an
1568
+ * account could be pulled out of rotation by a background read the user never
1569
+ * asked for, which is a behaviour change outside this fix's scope (S7 in
1570
+ * `EXPIRY-ADVERSARIAL-20261111.md`; the reserve's own cold-start hole is V4,
1571
+ * fixed separately).
1572
+ */
1573
+ noteExpiryOnly(accountId: string, nearestExpiryMs?: number): void;
1574
+ /**
1575
+ * The three-state writer both entry points funnel through.
1576
+ *
1577
+ * One place, so the invariant "a finished reading always leaves a state" can be
1578
+ * read off a single function: either a deadline is stored, or the account joins
1579
+ * `creditExpiryNone`. Nothing here deletes the read stamp — that is what makes
1580
+ * "read, found nothing" distinguishable from "never read".
1581
+ */
1582
+ private noteExpiryReading;
1428
1583
  /** Nearest one-off pack expiry for one account, or undefined when none known. */
1429
1584
  creditExpiryOf(accountId: string): number | undefined;
1585
+ /**
1586
+ * The full three-state reading for one account, including staleness.
1587
+ *
1588
+ * `stale` is evaluated against {@link EXPIRY_READING_TTL_MS} here rather than
1589
+ * baked into the stored value, so the TTL stays a constant of the policy and
1590
+ * not of the data.
1591
+ *
1592
+ * Only a real deadline can go stale. "We never asked" is not a reading, and
1593
+ * "nothing here has a deadline" does not become less true with age: a monthly
1594
+ * pack does not grow an expiry date by waiting. Keeping `none` permanently
1595
+ * valid is what makes the S1 loop impossible — an account that answered once
1596
+ * is never read again by the expiry machinery, so there is no predicate that
1597
+ * can stay true forever and re-read it on every pass. If such an account does
1598
+ * gain a one-off pack later, the card refresh (which writes through
1599
+ * `noteCredits` on every poll) is what notices.
1600
+ */
1601
+ expiryReadingOf(accountId: string, now?: number): ExpiryReading;
1430
1602
  /** Last known balance for one account, or undefined when never read. */
1431
1603
  creditsOf(accountId: string): number | undefined;
1432
1604
  /** The credit floor the user set for one account; 0 when unset. */
@@ -3664,6 +3836,17 @@ export declare class WorkBuddyScheduler {
3664
3836
  private travelHours;
3665
3837
  private compensationHours;
3666
3838
  private timer;
3839
+ /** The one-shot kick scheduled just after `start`; cleared by `stop`. */
3840
+ private settleTimer;
3841
+ /**
3842
+ * Deadline for the start-of-day window described in {@link dueSlot}.
3843
+ *
3844
+ * Zero until {@link start} sets it, so a manual `tick` before the loop starts
3845
+ * keeps the original "only past hours" behaviour.
3846
+ */
3847
+ private startupCatchUpUntilMs;
3848
+ /** A startup pass is extra work; it never spends a future scheduled slot. */
3849
+ private readonly startupCompleted;
3667
3850
  private running;
3668
3851
  /** Guards against a slow run overlapping the next tick. */
3669
3852
  private busy;
@@ -3798,6 +3981,8 @@ export declare class WorkBuddyScheduler {
3798
3981
  * PASSED and its slot is still unconsumed, so a laptop that slept through
3799
3982
  * 10:00 still runs the job when it wakes, on the same day.
3800
3983
  *
3984
+ * Startup runs are handled separately in tick and do not spend a future slot.
3985
+ *
3801
3986
  * The EARLIEST unconsumed candidate wins, which is what keeps a two-hour job
3802
3987
  * (`travelHours: [9, 21]`) whole: consuming the earliest due slot leaves the
3803
3988
  * later one for its own hour.