pi-workbuddy 0.2.2 → 0.2.4

package/README.md

@@ -6,15 +6,15 @@ A **WorkBuddy AI** provider for [Pi](https://pi.dev), with browser-based account
 
 ## Getting started
 
-Requires Node.js ≥22.19 and Pi with native provider support. Tested with Pi CLI **1.3.0**.
+Requires Node.js ≥22.19 and Pi with native provider support. Tested with Pi CLI **1.3.0** and Pendant 0.41.0's bundled Pi SDK **1.2.0**.
 
-Install the npm package after the `pi-workbuddy` release is published:
+Install the published npm package:
 
 ```sh
 pi install npm:pi-workbuddy
 ```
 
-Until the npm release is available, or to install directly from GitHub:
+Or install directly from GitHub:
 
 ```sh
 pi install git:github.com/lutfi238/pi-workbuddy
@@ -48,9 +48,10 @@ Use `/reload` after updating a loaded extension. To sign out, run `/logout` and
 | `/logout` → WorkBuddy AI | Remove Pi's local WorkBuddy credentials |
 | `/workbuddy status` or `/workbuddy doctor` | Show local configuration, catalog source, active model, and the last sanitized catalog error; no network requests |
 | `/workbuddy refresh` | Fetch the authenticated catalog, refreshing the token if needed |
+| `/workbuddy-tooltip on/off/refresh/status` | Experimental opt-in credit relay; requires the separately reviewed Pendant host adapter |
 | `/model` | Refresh model catalogs in the background and select a model |
 
-Before discovery, the provider includes conservative fallback metadata for `default-model`. Models are not listed as available until authentication is configured. If discovery fails, the last known catalog is retained **in memory**; it is not persisted across restarts. Pi may invoke discovery during its refresh lifecycle, but the extension factory does not make network requests when loaded.
+Before discovery or cache restoration, the provider includes fallback metadata for `default-model`. Models are not available until authentication is configured. Successful catalogs are persisted through **Pi's model store** as projected public metadata, scoped by a hash of the account origin/user/domain/tenant (never access or refresh tokens). Cached models are revalidated on restoration, including removal of DeepSeek `-sg` variants. A failed refresh retains the last known catalog. The extension factory itself makes no network requests.
 
 ### Automatic model discovery
 
@@ -58,7 +59,19 @@ There is no hardcoded allowlist of WorkBuddy model IDs. The provider fetches `/v
 
 A newly advertised model can therefore appear without changing the extension or adding its ID manually. The model must pass the existing compatibility and security filters: disabled models, models explicitly lacking tool support, and custom endpoints/protocols/API keys are excluded. Starting with 0.2.2, DeepSeek variants ending in `-sg` are intentionally excluded, including after catalog refresh; the regular DeepSeek models remain available. Catalog visibility does not guarantee that your account can run every listed model.
 
-This is refresh-based discovery, not a realtime push subscription or continuous idle polling. Reopen `/model` to check for additions during a long session. Offline mode does not fetch new catalogs. Extension updates may still be necessary if WorkBuddy changes its API, authentication, metadata schema, or wire protocol.
+A `session_start` hook refreshes only WorkBuddy using the registry's default network policy and honors `PI_OFFLINE` (also set by Pi CLI `--offline`). This covers embedded hosts that re-register a provider but do not refetch an already-seen provider ID. Offline provider refreshes can restore a matching cached catalog without network access.
+
+This is refresh-based discovery, not a realtime push subscription or continuous idle polling. Reopen `/model` to check for additions during a long session. Extension updates may still be necessary if WorkBuddy changes its API, authentication, metadata schema, or wire protocol.
+
+### Pendant / VS Code stays on WorkBuddy Default (fallback)
+
+Version **0.2.3** restores cached catalogs after provider re-registration and refreshes WorkBuddy at session startup. It also replaces an active bootstrap fallback with fresh metadata for the same ID. For resumed sessions, it reads only the latest model-change record; a removed DeepSeek `-sg` selection is restored to its exact non-SG counterpart if available. It does not change another provider, overwrite a newer observed selection, edit global defaults, or send a chat request. `/workbuddy refresh` also repairs stale active-model metadata.
+
+After the 0.2.3 release is published, update the package used by the host and reload the session. Restarting an old installed copy will not pick up repository changes. `/workbuddy doctor` reports the loaded extension version and `catalog=fallback`, `cache`, or `remote`; share only this sanitized diagnostic, never credentials. A genuine network/authentication error with no usable cache still requires resolving the error; no fabricated catalog is substituted.
+
+### Package published, but absent from gallery search
+
+The [direct package page](https://pi.dev/packages/pi-workbuddy) can work before the searchable gallery includes the package. npm publication and Pi gallery discovery are separate. Confirm the public npm version and the `pi-package` keyword before assuming a publishing failure. See the [reported npm-search discovery issue](https://github.com/earendil-works/pi/issues/7885). Do not repeatedly publish identical releases just to try to trigger gallery indexing.
 
 ### Login succeeds, but discovery fails or Codex remains selected
 
@@ -105,6 +118,40 @@ Smaller explicit output requests remain supported; sampling and payload hooks ca
 
 See the current [capability policy](research/capability-policy.md), [vendor references](research/vendor-capability-comparison.md), and historical [context-limit audit](research/context-limit-audit.md). No global Pi compaction settings are changed by the extension.
 
+### Read-only credit-reader backend
+
+Version **0.2.4** adds `createCreditsReader()` in `src/native-credits.js` for the verified personal-account endpoint `POST /billing/meter/get-user-resource-summary` with body `{}`. The reader itself does not run automatically. An opt-in experimental Pendant relay/adapter is available separately below; no installed host is modified automatically.
+
+The reader returns `creditsTotal`, `creditsRemaining`, `creditsUsed`, `packageCount`, and `fetchedAt`; optional `planCode`, `planName`, and `isPaidUser` are included only when supplied with the expected types. Invalid/missing numeric fields stay `null`, not zero. The default client also returns immutable `packageDetails` (`state`, `count`, `items`) from the verified paid/free package read routes. Each resource has a reviewed kind, precise total/remaining/used credits, and its own supplied expiry. Different grants of the same product stay separate. Missing dates stay unknown; offset-less dates retain an explicit server-time label. `packageCount` is the legacy summary-group count, not necessarily the number of individual grants. No subscription renewal date, USD value, or allowance is inferred. The account balance is not a separate allowance for each model.
+
+```js
+import { createCreditsReader } from "./src/native-credits.js";
+
+const reader = createCreditsReader();
+// credential is the current WorkBuddy OAuth credential supplied by the caller's Pi auth flow.
+const result = await reader.read(credential, { signal });
+// result.source: "remote" or "cache"; result.stale explicitly marks old/failed-refresh data.
+await reader.read(credential, { signal, force: true });
+await reader.read(credential, { allowNetwork: false });
+reader.clear(); // Required when a future UI/controller logs out or disposes this reader.
+```
+
+The default cache TTL is **60 seconds**, with at most **8 account scopes** and **8 concurrent underlying reads**. Cache keys use hashed account identity/domain, never tokens. Token rotation retains the same account cache. Cache entries are memory-only and are never added to the persistent model catalog. Callers receive independent snapshots; repeated concurrent reads share one bounded read job. A fresh job reads the summary and relevant paid/free package pages, at most ten pages of 200 records per route, under a shared detail deadline. Detail failures are explicitly partial/unavailable and do not make old details look fresh. Cancelling one caller leaves other subscribers running; cancelling the last caller or clearing the reader aborts the request and prevents late cache writes.
+
+Transient failures may return last-good data with `stale: true` and a sanitized `error`. Authentication/business denials discard the balance rather than returning stale data. Offline reads and `PI_OFFLINE` never trigger a fetch; without a matching cached value they report unavailable. `force` bypasses freshness, not offline policy. `ttlMs` and `maxEntries` can be configured when constructing the reader.
+
+This layer never performs login or token refresh itself: its caller must supply current Pi-owned credentials. It never claims rewards, buys credits, changes subscriptions, or sends chat. The enterprise usage route has not been verified and is deliberately not substituted with a potentially misleading personal balance; enterprise-scoped calls report unsupported for now. See [endpoint verification](research/credits-endpoint-verification.md) and [tooltip findings](research/model-tooltip-findings.md) for integration boundaries.
+
+### Optional Pendant credit tooltip (experimental)
+
+The exact native model-hover integration requires a host adapter in Pendant **0.41.0**, not just provider metadata. See [the preparation/review guide](integrations/pendant/README.md). The included `prepare.mjs` validates the inspected host version and hash, checks JavaScript syntax, and produces separate modified renderer/broker copies and a manifest. It **never applies** that copy to your installed VS Code extension. Generated vendor bundles are not shipped in npm or committed to Git.
+
+After an explicitly approved adapter installation, `/workbuddy-tooltip on` enables a session-scoped credit relay over Pi's normal status API. The adapter consumes that reserved payload inside the existing native model tooltip instead of displaying an extra status badge. `/workbuddy-tooltip refresh`, `status`, and `off` manage the relay. It is disabled by default; normal CLI behavior is unchanged. Do not enable it in an unpatched host. Persistent opt-in after installing the adapter uses `WORKBUDDY_PENDANT_TOOLTIP=1` in the host process environment.
+
+Adapter v2 also fixes Pendant's default `extensionStatus.surface=off` transport gate: it forwards only the reserved WorkBuddy payload while leaving other status visibility and user settings unchanged. It hides the encoded transport from VS Code's separate status bar. Install both prepared host bundles and use **Developer: Reload Window**; Pi `/reload` alone does not reload the host broker. `/workbuddy-tooltip status` reports whether the relay payload is waiting, loading, ready, or unavailable without querying credits.
+
+Rows show a remaining-credit summary, then separate base/bonus/top-up grants with `remaining / total left` and each grant's expiry, plus update time, optional plan name, and stale/partial markers. At most four grants are previewed (base/daily first, then earliest known expiry); omitted loaded grants have an explicit count. Without usable details, aggregate used/total and credit-group count remain as a labeled fallback. Fresh remaining credits, including each grant, reuse the native OpenAI color thresholds: green at ≥50%, yellow at 15–<50%, red below 15%. Unknown or stale balances are not painted as current healthy quota; other model/account rows stay neutral. No ChatGPT five-hour/weekly allowances, renewal dates, percentages, or USD values are fabricated. Read events use the private reader's cache and cancellation; hovering does not send a chat or start repeated network requests. Tokens and account identity never cross into the webview. Isolated tests cover the patched renderer and the actual shipped SDK transport. The operator also confirmed the native hover, colors, individual grants, and expiry dates visually in the backed-up local Pendant 0.41.0 preview. That confirmation does not establish compatibility with other host versions.
+
 ### Native configuration
 
 ```powershell
@@ -124,7 +171,7 @@ The `.env.example` file is a reference only: Pi and this extension do **not** au
 
 - Pi stores credentials in its agent profile (`auth.json`), not in the project. Protect that file; never commit or share it.
 - The extension does not read the desktop application's credentials, databases, cookies, or sessions.
-- Authentication, discovery, and chat requests target only the HTTPS origin `www.workbuddy.ai`; HTTP redirects are rejected. Recognized production WorkBuddy/CodeBuddy account domains are used only as header values, not destination URLs.
+- Authentication, discovery, credit reads, and chat requests target only the HTTPS origin `www.workbuddy.ai`; HTTP redirects are rejected. Recognized production WorkBuddy/CodeBuddy account domains are used only as header values, not destination URLs.
 - Browser login URLs must use recognized production WorkBuddy/CodeBuddy origins. Login URLs can contain sensitive state; do not share them or screenshots containing them.
 - Remote configuration cannot import prompts, tools, commands, credentials, or model URLs into this extension. Discovery does not send a list of repositories.
 - `X-Private-Data: true` is a conservative privacy default, **not a guarantee** of the server's retention policy.
@@ -182,13 +229,23 @@ npm test
 node scripts/smoke-cli.mjs "C:/path/to/pi-coding-agent/dist/bundle/cli.js"
 ```
 
+To additionally test against an installed Pendant bundle (no live credentials or inference):
+
+```powershell
+$env:PI_SDK_TEST_PATH = "C:/path/to/pendant/dist/pi-sdk.cjs"
+npm test
+```
+
+Pendant integration tests instantiate its actual `ModelRuntime`, resource services, session manager, and `session_start` bindings. They cover provider re-registration, offline cache restoration in a fresh runtime, startup fallback repair, and migration of a saved DeepSeek SG selection. Cache tests cover account isolation, secret/endpoint stripping, malformed entries, failed refreshes, and generation rejection.
+
 Host tests cover coordinated login, storage and refresh, tool-call/result round trips, reasoning, Unicode, usage tails, instrumentation, empty and truncated streams, errors, and cancellation. The CLI smoke test uses an offline temporary profile with synthetic credentials and removes it afterward. **None of these automated tests sends a prompt to the live WorkBuddy service.**
 
 Local investigation notes:
 [authentication](research/workbuddy-auth-findings.md) ·
 [chat protocol](research/workbuddy-protocol-findings.md) ·
 [error 12403](research/12403-findings.md) ·
-[context-limit audit](research/context-limit-audit.md).
+[context-limit audit](research/context-limit-audit.md) ·
+[Pendant recovery and gallery findings](research/pendant-recovery-findings.md).
 
 These notes are not included in the npm tarball. Raw third-party snapshots and generated evidence remain local and are excluded from Git; they are preserved verbatim rather than translated so their provenance and hashes remain valid. The authored documentation, code comments, user-facing messages, and test fixtures use English. Emoji in test fixtures intentionally exercise Unicode streaming.
 

package/extensions/workbuddy.js

@@ -1,6 +1,8 @@
 import { openAICompletionsApi } from "@earendil-works/pi-ai/compat";
 import bridge from "../src/bridge-extension.js";
 import { createWorkbuddyProvider, registerNativeCommands } from "../src/native-provider.js";
+import { registerNativeLifecycle } from "../src/native-lifecycle.js";
+import { registerPendantTooltip } from "../src/native-tooltip-controller.js";
 
 export default async function workbuddy(pi) {
   const mode = process.env.WORKBUDDY_MODE || "native";
@@ -9,7 +11,12 @@ export default async function workbuddy(pi) {
   if (process.env.WORKBUDDY_GZIP && !["0", "1"].includes(process.env.WORKBUDDY_GZIP)) {
     throw new Error("WORKBUDDY_GZIP must be 0 or 1.");
   }
+  if (process.env.WORKBUDDY_PENDANT_TOOLTIP && !["0", "1"].includes(process.env.WORKBUDDY_PENDANT_TOOLTIP)) {
+    throw new Error("WORKBUDDY_PENDANT_TOOLTIP must be 0 or 1.");
+  }
   const provider = createWorkbuddyProvider({ api: openAICompletionsApi(), gzip: process.env.WORKBUDDY_GZIP !== "0" });
   pi.registerProvider(provider);
   registerNativeCommands(pi, provider);
+  registerNativeLifecycle(pi, provider);
+  registerPendantTooltip(pi, { enabled: process.env.WORKBUDDY_PENDANT_TOOLTIP === "1" });
 }

package/integrations/pendant/README.md

@@ -0,0 +1,174 @@
+# Optional Pendant model-tooltip adapter (experimental)
+
+This integration prepares **WorkBuddy credit rows in Pendant's existing native
+model-hover grid**, without disguising credits as OpenAI five-hour/weekly limits.
+It is not an official Pendant API or an upstream-supported integration.
+
+## Important boundary
+
+- The Pi extension alone cannot add arbitrary model-hover rows in Pendant 0.41.0.
+- Adapter v2 prepares modified **copies** of the webview and host status-broker bundles. Preparation
+  never overwrites the installed host and does not imply that the visible UI has
+  changed. Installing that copy is a separate, explicitly approved step.
+- It supports only `cdervis.vscode-pi` **0.41.0** with the exact inspected original
+  webview SHA-256:
+  `88c02dc6b1474e83fb5b8762ef1f26ae2d07abe04145b1b04f0ba519039bc38c`.
+  Its original `dist/extension.js` must also match
+  `8c449489dfba9f04fb8e96c2f09640b7ddf69900f6ca0e88ca1a4389b43714d6`.
+- Other versions, changed hashes, duplicate patching, and an output path inside
+  the host installation are rejected. Updates require a new review, not disabling
+  the checks. Generated vendor bundles are excluded from Git and npm publication.
+
+## Architecture
+
+1. The opt-in WorkBuddy controller resolves credentials through Pi's existing
+   `modelRegistry.getApiKeyAndHeaders()` flow, then calls the private in-memory
+   credit reader. Pi may refresh expired OAuth credentials through its normal
+   auth lock; the controller does not read `auth.json` or manage tokens itself.
+2. Only a whitelisted credit snapshot and session ID cross Pi's standard
+   `setStatus` transport under the reserved key `workbuddy.credits.v1`.
+   Credentials, user IDs, emails, and raw errors are never serialized.
+3. The host broker forwards the reserved entry even when the ordinary extension-
+   status surface is off (Pendant's default). Other entries retain their existing
+   display policy. It does not enable a panel/status bar or change user settings.
+   The reserved entry is excluded from the separate VS Code status-bar badge.
+4. The webview consumes the reserved entry instead of showing encoded text in the
+   ordinary extension-status badge/panel.
+5. Its renderer appends rows only for an available WorkBuddy model in the exact
+   matching active session. Non-WorkBuddy tooltips keep their original rows.
+   Session mismatch, missing model/auth availability, duplicate entries, and
+   malformed/oversized payloads hide the credit rows rather than guessing.
+6. Status changes refresh an already-open tooltip. No global frontend balance
+   cache, new worker request kind, local HTTP server, or credential-bearing
+   webview request is introduced.
+
+The controller is **disabled by default**. Normal CLI behavior remains unchanged.
+It refreshes on session start, model selection, and completed agent runs only
+while explicitly enabled and on a WorkBuddy model. The reader's 60-second cache
+and request deduplication apply. There is no hover-triggered network request or
+idle polling; old snapshots are explicitly marked `Cached / stale`. Use the
+refresh command when a newer balance is needed without sending a chat.
+
+Observed provider/session changes cancel outdated publication. Moving away from
+WorkBuddy, disabling the relay, or shutting down clears its private reader. The
+host hides balances for models no longer present in its available-model list.
+Account changes must reach the normal Pi auth/session lifecycle or be followed
+by an explicit refresh; this is not a separate account-monitoring service.
+
+## Prepare, without applying
+
+From the repository (the output directory must not already exist):
+
+```powershell
+node integrations/pendant/prepare.mjs `
+  "C:/Users/YOUR_USER/.vscode/extensions/cdervis.vscode-pi-0.41.0" `
+  "integrations/pendant/generated"
+```
+
+The command validates the version/hash and generated JavaScript syntax, then
+writes only:
+
+- `generated/webview.js`: the optional prepared renderer copy.
+- `generated/extension.js`: the optional prepared broker copy.
+- `generated/manifest.json`: original/prepared hashes for both and `applied: false`.
+
+If the output already exists, preserve/review it or choose a different new
+output directory. Do not use preparation to overwrite an installed bundle.
+
+The preparation utility is included in the npm package at
+`integrations/pendant/prepare.mjs`; paths in the command above assume a repository
+checkout. It requires only Node.js and the supplied installed host directory.
+
+## Before any installation
+
+Review the manifest and diff. Prefer testing in a disposable VS Code profile.
+Applying v2 requires explicit backups of the original `dist/webview.js` and
+`dist/extension.js`, original-hash checks, and reversible replacements of both. This
+utility deliberately has **no apply command**. No installed Pendant file has
+been modified by implementing or preparing this integration.
+
+A local modification is not guaranteed to survive extension updates and may
+interact with host integrity/CSP behavior that isolated tests cannot prove.
+Keep the backup and restore the original before upgrading or troubleshooting
+unrelated host problems. Do not publish modified vendor bundles as this project.
+
+## After an approved adapter installation
+
+Load the updated `pi-workbuddy` extension, then in the patched Pendant session:
+
+```text
+/workbuddy-tooltip on
+/workbuddy-tooltip refresh
+/workbuddy-tooltip status
+/workbuddy-tooltip off
+```
+
+The command is a Pi extension command, not a chat prompt. It sends only a
+bounded read-only credit requests when enabled (summary and relevant detail pages); it never invokes inference. Do not enable
+it in an unmodified host: an ordinary status surface might display the encoded
+transport rather than a native tooltip. It refuses the normal TUI mode.
+
+For persistent opt-in **after installing the adapter**, launch the host process
+with `WORKBUDDY_PENDANT_TOOLTIP=1`. The `.env.example` is documentation only; it is
+not automatically loaded. If `pendant.extensionStatus.keys` is configured as an
+allowlist, include `workbuddy.credits.v1`; the integration does not bypass that
+user-controlled filter.
+
+## Displayed fields
+
+The native model header, provider, context, reasoning and input rows remain.
+Additional credit rows use only verified data:
+
+- Plan name, if supplied by the credit summary (no guessed Free/Pro label).
+- Credits remaining.
+- Separate base/daily/bonus/top-up grants, each with `remaining / total left`.
+- Each grant's supplied expiry; never substitute an ordinary renewal/reset date.
+- A maximum of four preview grants (base/daily first, then earliest known expiry),
+  with an explicit count of further loaded grants. Partial detail reads are labeled.
+- Aggregate used/total and summary-group count only when details are unavailable.
+- Last successful update.
+- Explicit cached/stale indicator when applicable.
+
+`Credits remaining` and each grant's remaining balance reuse Pendant's native OpenAI semantic tones: green at
+50% or more remaining, yellow from 15% to below 50%, and red below 15% (including
+an explicitly known zero). A positive balance with an unknown/inconsistent total
+stays neutral; stale balances are not shown as current healthy/depleted quota.
+The percentage only selects a tone, not a new displayed allowance. Other rows
+stay neutral; package count is not a banked-reset count. Absolute expiry timestamps
+render in the browser's local timezone. Offset-less dates remain unchanged under
+`Expires (server time)`; unknown dates show `Unknown`, not `Never`. The stale marker and
+unavailable state use the host's warning tone. No custom RGB/CSS palette is added.
+
+Missing numbers show `Unknown`, not zero. Loading/unavailable replaces the
+credit values. No expiry, renewal time, percentage, or USD conversion is invented.
+The balance belongs to the account, not independently to each model. Only the
+verified personal-account route is currently supported.
+
+## Validation and remaining verification
+
+If the installed host is already adapted, keep its original backup as the test
+fixture instead of weakening the original-hash check:
+
+```powershell
+$env:PI_PENDANT_FIXTURE_PATH = "C:/path/to/backup/pendant-original"
+# This fixture contains original package.json, dist/webview.js and dist/extension.js.
+# PI_SDK_TEST_PATH still points to the real installed dist/pi-sdk.cjs.
+npm test
+```
+
+Tests cover payload redaction and bounds, account/session cancellation, Pi's
+actual bundled SDK auth/status APIs with synthetic credentials, and the patched
+native renderer methods extracted from the exact shipped bundle. Preparation
+also checks that the original file is unchanged and the output parses as ESM.
+These are not a browser screenshot or a test of an applied VS Code installation.
+The operator separately confirmed the native hover, colors, per-grant balances
+and expiry dates visually in the local 0.41.0 deployment. New deployments or host
+versions still need their own visible hover check.
+In particular, the regression suite now checks the default `off` status surface;
+renderer-only v1 omitted that broker gate and could not receive the payload.
+Use **Developer: Reload Window** after installing v2, not only Pi `/reload`.
+
+For upstream support, the preferable long-term change is a documented generic
+provider-details API with text rows and session/account scoping. The current
+version-pinned adapter is an explicit compatibility bridge, not a claim that
+Pendant already implements that public API.

package/integrations/pendant/prepare.mjs

@@ -0,0 +1,86 @@
+// Optional, version-pinned adapter preparation. Never writes to the installed host.
+import { readFileSync, writeFileSync, mkdirSync, realpathSync } from "node:fs";
+import { resolve, dirname, relative, isAbsolute, join } from "node:path";
+import { pathToFileURL } from "node:url";
+import { createHash } from "node:crypto";
+import { spawnSync } from "node:child_process";
+import { createTooltipAdapter, TOOLTIP_STATUS_KEY } from "../../src/pendant-tooltip.js";
+
+export const PENDANT_VERSION = "0.41.0";
+export const ORIGINAL_SHA256 = "88c02dc6b1474e83fb5b8762ef1f26ae2d07abe04145b1b04f0ba519039bc38c";
+export const HOST_EXTENSION_SHA256 = "8c449489dfba9f04fb8e96c2f09640b7ddf69900f6ca0e88ca1a4389b43714d6";
+const hash = value => createHash("sha256").update(value).digest("hex");
+function replaceOnce(source, before, after) {
+  const index = source.indexOf(before);
+  if (index < 0 || source.indexOf(before, index + before.length) >= 0) throw new Error("Pendant adapter anchor is absent or ambiguous.");
+  return source.slice(0, index) + after + source.slice(index + before.length);
+}
+export function patchWebview(source) {
+  if (hash(source) !== ORIGINAL_SHA256) throw new Error("Unsupported Pendant webview hash; refusing to patch.");
+  const modelStart = source.indexOf("renderModelTooltipFor(e){"), modelEnd = source.indexOf("prepareModelTooltipFor(e){", modelStart);
+  const originalModel = source.slice(modelStart, modelEnd);
+  let model = replaceOnce(originalModel, "return s$(xn(this.options.getModels(),e.provider,e.modelId),",
+    "let __wbModel=xn(this.options.getModels(),e.provider,e.modelId);let __wbBase=s$(__wbModel,");
+  model = replaceOnce(model, ",n.error)}", ",n.error);return __piWorkbuddyTooltip.append(__wbBase,this.__piWorkbuddyEntries??[],{provider:e.provider,sessionId:this.options.getState().sessionId,modelAvailable:!!__wbModel},Date.now())}");
+  let output = replaceOnce(source, originalModel, model);
+  const statusStart = source.indexOf("setExtensionStatus(e){"), statusEnd = source.indexOf("setExtensionStatusSurface(e){", statusStart);
+  const originalStatus = source.slice(statusStart, statusEnd);
+  let status = replaceOnce(originalStatus, "setExtensionStatus(e){this.extensionStatus.entries=e.map(",
+    "setExtensionStatus(e){this.__piWorkbuddyEntries=e.filter(n=>n.key===" + JSON.stringify(TOOLTIP_STATUS_KEY) +
+    ");this.extensionStatus.entries=e.filter(n=>n.key!==" + JSON.stringify(TOOLTIP_STATUS_KEY) + ").map(");
+  status = replaceOnce(status, "this.ui.footerTooltipController.refresh(this.options.extensionStatusButton,t)}",
+    "this.ui.footerTooltipController.refresh(this.options.extensionStatusButton,t);this.ui.footerTooltipController.refreshActive()}");
+  output = replaceOnce(output, originalStatus, status);
+  // This is a module-local helper; no global account cache, network API, or credentials enter the webview.
+  return "// pi-workbuddy optional Pendant tooltip adapter v1\nconst __piWorkbuddyTooltip=(" + createTooltipAdapter.toString() + ")();\n" + output;
+}
+export function patchHostExtension(source) {
+  if (hash(source) !== HOST_EXTENSION_SHA256) throw new Error("Unsupported Pendant broker hash; refusing to patch.");
+  const start = source.indexOf("broadcastExtensionStatus(){"), end = source.indexOf("waitForSidebarWebviewReady(", start);
+  const original = source.slice(start, end);
+  // A hidden status surface must not drop the private tooltip transport. Other entries stay hidden.
+  const replacement = "broadcastExtensionStatus(){let visible=this.extensionStatusSurface===\"panel\"||this.extensionStatusSurface===\"both\";let targets=[...this.view?[{source:\"sidebar\"}]:[],...[...this.editorSurfaces.values()].map(n=>({source:\"editor\",surfaceId:n.id}))];for(let target of targets){let entries=this.extensionUiHost.getStatusSnapshot(B(target));if(!visible)entries=entries.filter(entry=>entry.key===" + JSON.stringify(TOOLTIP_STATUS_KEY) + ");this.postMessage({type:\"extension_status\",entries},target)}}";
+  let output = replaceOnce(source, original, replacement);
+  // Never expose the encoded transport in VS Code's separate status bar either.
+  output = replaceOnce(output, "refreshStatusBar(){let e=this.getStatusSnapshot(),n=e.flatMap(",
+    "refreshStatusBar(){let e=this.getStatusSnapshot().filter(entry=>entry.key!==" + JSON.stringify(TOOLTIP_STATUS_KEY) + "),n=e.flatMap(");
+  return output;
+}
+function within(child, parent) {
+  const path = relative(parent, child);
+  return path === "" || !path.startsWith("..") && !isAbsolute(path);
+}
+export function prepareAdapter(sourceDirectory, outputDirectory) {
+  const sourceRoot = realpathSync(sourceDirectory);
+  const parent = realpathSync(dirname(resolve(outputDirectory)));
+  const output = join(parent, resolve(outputDirectory).split(/[\\/]/).at(-1));
+  if (within(output, sourceRoot)) throw new Error("Output must not be inside the installed Pendant directory.");
+  const pkg = JSON.parse(readFileSync(join(sourceRoot, "package.json"), "utf8"));
+  if (pkg.publisher !== "cdervis" || pkg.name !== "vscode-pi" || pkg.version !== PENDANT_VERSION) {
+    throw new Error("Only cdervis.vscode-pi 0.41.0 is supported by this experimental adapter.");
+  }
+  const original = readFileSync(join(sourceRoot, "dist", "webview.js"));
+  const brokerOriginal = readFileSync(join(sourceRoot, "dist", "extension.js"));
+  const patched = patchWebview(original.toString("utf8"));
+  const brokerPatched = patchHostExtension(brokerOriginal.toString("utf8"));
+  for (const [source, esm] of [[patched, true], [brokerPatched, false]]) {
+    const checked = spawnSync(process.execPath, [...(esm ? ["--input-type=module"] : []), "--check"], { input: source, encoding: "utf8", timeout: 15000 });
+    if (checked.error || checked.status !== 0) throw new Error("Prepared adapter failed syntax validation; nothing was written.");
+  }
+  const manifest = { adapter: "pi-workbuddy-tooltip-v2", hostVersion: pkg.version, originalSha256: hash(original),
+    preparedSha256: hash(patched), target: "dist/webview.js", brokerOriginalSha256: hash(brokerOriginal),
+    brokerPreparedSha256: hash(brokerPatched), brokerTarget: "dist/extension.js", applied: false };
+  mkdirSync(output); // Fail if output already exists; never overwrite a previous artifact.
+  writeFileSync(join(output, "webview.js"), patched, { flag: "wx" });
+  writeFileSync(join(output, "extension.js"), brokerPatched, { flag: "wx" });
+  writeFileSync(join(output, "manifest.json"), JSON.stringify(manifest, null, 2) + "\n", { flag: "wx" });
+  return manifest;
+}
+if (process.argv[1] && import.meta.url === pathToFileURL(resolve(process.argv[1])).href) {
+  try {
+    if (process.argv.length !== 4) throw new Error("Usage: node integrations/pendant/prepare.mjs PENDANT_DIRECTORY NEW_OUTPUT_DIRECTORY");
+    const manifest = prepareAdapter(process.argv[2], process.argv[3]);
+    console.log(JSON.stringify(manifest, null, 2));
+    console.log("Prepared only. Installed Pendant files have NOT been changed.");
+  } catch (error) { console.error(error.message); process.exitCode = 1; }
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "pi-workbuddy",
-  "version": "0.2.2",
+  "version": "0.2.4",
   "description": "Native WorkBuddy account login and direct model provider for Pi",
   "type": "module",
   "license": "MIT",
@@ -20,6 +20,8 @@
   "files": [
     "extensions",
     "src",
+    "integrations/pendant/prepare.mjs",
+    "integrations/pendant/README.md",
     "README.md",
     "LICENSE"
   ],

package/src/client-identity.js

@@ -1,6 +1,6 @@
 // Compatibility baseline: the operator-supplied WorkBuddy AI 5.8.4 artifact.
 // This is a protocol/version marker, not an assertion that Pi is the official desktop app.
-export const EXTENSION_VERSION = "0.2.2";
+export const EXTENSION_VERSION = "0.2.4";
 export const WORKBUDDY_PROTOCOL_VERSION = "5.8.4";
 export const USER_AGENT = "CLI/unknown WorkBuddy/" + WORKBUDDY_PROTOCOL_VERSION +
   " pi-workbuddy/" + EXTENSION_VERSION;

package/src/native-catalog-cache.js

@@ -0,0 +1,38 @@
+import { createHash } from "node:crypto";
+import { BASE_URL, ORIGIN } from "./native-client.js";
+import { projectModels } from "./native-models.js";
+import { WorkbuddyError } from "./native-errors.js";
+
+/** Local cache validator only; never sent as an HTTP ETag. Tokens are not hashed or stored. */
+export function catalogCacheKey(credential) {
+  if (credential?.type !== "oauth" || credential.origin !== ORIGIN || !credential.userId) return undefined;
+  const parts = [ORIGIN, credential.userId, credential.domain || "www.workbuddy.ai", credential.enterpriseId || ""];
+  if (parts.some(value => typeof value !== "string" || value.length > 2048 || /[\r\n\0]/.test(value))) return undefined;
+  return "workbuddy-catalog-v1:" + createHash("sha256").update(JSON.stringify(parts)).digest("hex");
+}
+
+/** Reproject a public metadata whitelist, never cached auth, endpoints, headers or instructions. */
+export function restoreCatalog(entry, key) {
+  if (!key || entry?.etag !== key) return undefined;
+  if (!Array.isArray(entry.models) || entry.models.length > 2000) {
+    throw new WorkbuddyError("catalog-cache", "Cached WorkBuddy model metadata is invalid.");
+  }
+  const models = entry.models.filter(model => model?.provider === "workbuddy" && model.api === "openai-completions" &&
+    model.baseUrl === BASE_URL).map(model => ({
+    id: model.id, name: model.name,
+    maxInputTokens: model.contextWindow, maxOutputTokens: model.maxTokens,
+    supportsReasoning: model.reasoning === true,
+    supportsImages: Array.isArray(model.input) && model.input.includes("image"),
+    onlyReasoning: model.thinkingLevelMap?.off === null,
+    reasoning: { supportedEfforts: model.thinkingLevelMap && typeof model.thinkingLevelMap === "object" ?
+      Object.entries(model.thinkingLevelMap).filter(([level, value]) => level !== "off" && typeof value === "string").map(([level]) => level) : [] },
+    temperature: model.samplingParams?.temperature, top_p: model.samplingParams?.top_p,
+  }));
+  try { return projectModels({ models }); }
+  catch { throw new WorkbuddyError("catalog-cache", "Cached WorkBuddy model metadata is invalid."); }
+}
+
+export function catalogCacheEntry(models, key) {
+  // Models originate from projectModels(), which emits only bounded public metadata.
+  return { models, checkedAt: Date.now(), etag: key };
+}

package/src/native-client.js

@@ -1,6 +1,7 @@
 import { setTimeout as sleep } from "node:timers/promises";
 import { WorkbuddyError } from "./native-errors.js";
 import { USER_AGENT } from "./client-identity.js";
+import { readCreditPackages } from "./native-credit-packages.js";
 
 export const ORIGIN = "https://www.workbuddy.ai";
 export const BASE_URL = ORIGIN + "/v2";
@@ -88,7 +89,7 @@ export function createNativeClient({
   fetch: fetchImpl = globalThis.fetch, requestTimeoutMs = 15000,
   loginTimeoutMs = 300000, pollIntervalMs = 1000, now = Date.now,
 } = {}) {
-  async function request(path, { method = "GET", credential, signal, pendingCode, headers = {} } = {}) {
+  async function request(path, { method = "GET", credential, signal, pendingCode, headers = {}, body = {} } = {}) {
     const url = new URL(path, ORIGIN);
     if (url.origin !== ORIGIN || url.username || url.password) throw new WorkbuddyError("endpoint", "Untrusted WorkBuddy endpoint.");
     const timed = AbortSignal.timeout(requestTimeoutMs);
@@ -104,7 +105,7 @@ export function createNativeClient({
     try {
       response = await fetchImpl(url, {
         method, redirect: "error", signal: activeSignal, headers: requestHeaders,
-        ...(method === "POST" ? { body: "{}" } : {}),
+        ...(method === "POST" ? { body: JSON.stringify(body) } : {}),
       });
     } catch {
       if (signal?.aborted) throw new WorkbuddyError("cancelled", "WorkBuddy operation cancelled or timed out.");
@@ -179,5 +180,35 @@ export function createNativeClient({
     async catalog(credential, signal) {
       return request("/v3/config", { credential, signal });
     },
+    async credits(credential, signal) {
+      accountHeaders(credential);
+      if (credential.enterpriseId) {
+        throw new WorkbuddyError("credits-scope", "The verified credits route supports personal accounts only.");
+      }
+      return request("/billing/meter/get-user-resource-summary", { method: "POST", credential, signal });
+    },
+    async creditPackages(credential, signal, summary) {
+      accountHeaders(credential);
+      if (credential.enterpriseId) throw new WorkbuddyError("credits-scope", "Credit-package details support personal accounts only.");
+      const deadline = AbortSignal.timeout(requestTimeoutMs);
+      const activeSignal = signal ? AbortSignal.any([signal, deadline]) : deadline;
+      try {
+        return await readCreditPackages({ summary, signal: activeSignal,
+          fetchPage: (group, body) => {
+            const today = new Date(now()), pad = value => String(value).padStart(2, "0");
+            const day = `${today.getFullYear()}-${pad(today.getMonth() + 1)}-${pad(today.getDate())}`;
+            return request("/billing/meter/get-user-resource-" + group + "-packages", {
+              method: "POST", credential, signal: activeSignal, headers: { "Accept-Language": "en" },
+              body: { ...body, ...(group === "paid" ? { NeedRenewInfo: true } : {
+                SlicePeriodStartTime: day + " 00:00:00", SlicePeriodEndTime: day + " 23:59:59",
+              }) },
+            });
+          },
+        });
+      } catch {
+        if (signal?.aborted) throw new WorkbuddyError("cancelled", "WorkBuddy credit read cancelled.");
+        return { accounts: [], state: "unavailable" };
+      }
+    },
   };
 }

package/src/native-credit-packages.js

@@ -0,0 +1,117 @@
+import { WorkbuddyError } from "./native-errors.js";
+
+const MAX_PACKAGES = 2000, PAGE_SIZE = 200, MAX_PAGES = 10;
+// Public product codes reviewed in WorkBuddy 5.8.4; unknown summary codes are queried on both read routes.
+const products = {
+  TCACA_code_001_PqouKr6QWV: ["free", "daily"],
+  TCACA_code_002_AkiJS3ZHF5: ["paid", "base"],
+  TCACA_code_005_maRGyrHhw1: ["paid", "base"],
+  TCACA_code_003_FAnt7lcmRT: ["paid", "base"],
+  TCACA_code_006_DbXS0lrypC: ["free", "bonus"],
+  TCACA_code_007_nzdH5h4Nl0: ["free", "bonus"],
+  TCACA_code_008_cfWoLwvjU4: ["free", "base"],
+  TCACA_code_009_0XmEQc2xOf: ["paid", "topup"],
+  TCACA_code_023_4xbGhMrE6q: ["paid", "base"],
+  TCACA_code_026_BaESVICNoi: ["paid", "base"],
+  TCACA_code_027_0FCGVA6vSa: ["paid", "base"],
+  TCACA_code_028_NtpWi0jzXs: ["free", "bonus"],
+  TCACA_code_029_6wCGEWquYy: ["free", "bonus"],
+  TCACA_code_030_BjSt89qTvr: ["free", "bonus"],
+  TCACA_code_035_ArVxJcGDsm: ["free", "base"],
+  TCACA_code_036_lupO5WgNdG: ["paid", "topup"],
+  TCACA_code_037_WxOD3MpI2o: ["free", "bonus"],
+  TCACA_code_038_OhvqZtiPKr: ["paid", "topup"],
+  TCACA_code_039_KRcQj7wUat: ["free", "base"],
+  TCACA_code_040_mi9rCYg46x: ["free", "base"],
+};
+const codeOf = value => typeof value === "string" && /^[\w-]{1,128}$/.test(value) ? value : undefined;
+const cancelled = () => new WorkbuddyError("cancelled", "WorkBuddy credit read cancelled.");
+
+/** Bounded, read-only detail discovery. Never claims rewards or changes renewal/purchases. */
+export async function readCreditPackages({ summary, fetchPage, signal }) {
+  if (!Array.isArray(summary?.Packages) || summary.Packages.length > MAX_PACKAGES ||
+    summary.Packages.some(item => !item || typeof item !== "object" || Array.isArray(item))) return { accounts: [], state: "unavailable" };
+  const codes = [...new Set((summary?.Packages ?? []).map(item => codeOf(item?.PackageCode)).filter(Boolean))];
+  if (!codes.length) return { accounts: [], state: summary?.Packages?.length === 0 ? "complete" : "unavailable" };
+  const missingCode = summary.Packages.some(item => !codeOf(item?.PackageCode));
+  const groups = await Promise.allSettled(["paid", "free"].map(async group => {
+    const selected = codes.filter(code => !Object.hasOwn(products, code) || products[code][0] === group);
+    if (!selected.length) return { accounts: [], complete: true };
+    const accounts = [];
+    for (let page = 1; page <= MAX_PAGES; page++) {
+      if (signal?.aborted) throw cancelled();
+      let data;
+      try {
+        data = await fetchPage(group, { PageNumber: page, PageSize: PAGE_SIZE, PackageCodes: selected,
+          Status: [0, 3], OnlyValidPeriod: true, IsDisplayTotalInfo: true });
+      } catch {
+        if (signal?.aborted) throw cancelled();
+        return { accounts, complete: false };
+      }
+      if (!Array.isArray(data?.Accounts) || data.Accounts.length > PAGE_SIZE ||
+        !Number.isSafeInteger(data.TotalCount) || data.TotalCount < 0 ||
+        data.Accounts.some(item => !item || typeof item !== "object" || Array.isArray(item))) {
+        return { accounts, complete: false };
+      }
+      // Some servers return unrelated products; never project them as matching this summary.
+      const matching = data.Accounts.filter(item => selected.includes(item.PackageCode));
+      accounts.push(...matching);
+      if (matching.length !== data.Accounts.length) return { accounts, complete: false };
+      if (accounts.length >= data.TotalCount) return { accounts, complete: accounts.length === data.TotalCount };
+      if (!data.Accounts.length) return { accounts, complete: false };
+    }
+    return { accounts, complete: false };
+  }));
+  if (signal?.aborted) throw cancelled();
+  const accounts = [], seen = new Set(); let complete = !missingCode;
+  for (const result of groups) {
+    if (result.status !== "fulfilled") { complete = false; continue; }
+    complete &&= result.value.complete;
+    for (const item of result.value.accounts) {
+      const id = typeof item.ResourceId === "string" && item.ResourceId || Number.isSafeInteger(item.ResourceId) && String(item.ResourceId);
+      if (id && seen.has(id)) continue;
+      if (id) seen.add(id);
+      if (accounts.length < MAX_PACKAGES) accounts.push(item); else complete = false;
+    }
+  }
+  const returnedCodes = new Set(accounts.map(item => item.PackageCode));
+  if (codes.some(code => !returnedCodes.has(code))) complete = false;
+  return { accounts, state: complete ? "complete" : accounts.length ? "partial" : "unavailable" };
+}
+
+function capacity(value) {
+  if (typeof value === "string" && /^\d+(?:\.\d+)?$/.test(value.trim())) value = Number(value);
+  return typeof value === "number" && Number.isFinite(value) && value >= 0 && value <= Number.MAX_SAFE_INTEGER ? value : null;
+}
+function date(value) {
+  // The verified numeric field is Unix milliseconds; do not guess seconds or a timezone for wall-clock strings.
+  if (typeof value === "string" && /^\d+$/.test(value)) value = Number(value);
+  if (typeof value === "string" && /^\d{4}-\d\d-\d\dT\d\d:\d\d:\d\d(?:\.\d{1,3})?(?:Z|[+-]\d\d:\d\d)$/.test(value) && wallClock(value.slice(0, 19))) value = Date.parse(value);
+  return Number.isSafeInteger(value) && value >= Date.UTC(2000, 0, 1) && value <= 8640000000000000 ? value : null;
+}
+function wallClock(value) {
+  if (typeof value !== "string" || !/^\d{4}-\d\d-\d\d[ T]\d\d:\d\d:\d\d$/.test(value)) return null;
+  const normalized = value.replace(" ", "T"), stamp = Date.parse(normalized + "Z");
+  return Number.isFinite(stamp) && new Date(stamp).toISOString().slice(0, 19) === normalized ? normalized.replace("T", " ") : null;
+}
+
+/** Whitelist only display metrics and expiry. No account/resource/order IDs or upstream names leave this module. */
+export function normalizeCreditPackages(details, summary) {
+  if (!details || !["complete", "partial"].includes(details.state) || !Array.isArray(details.accounts) || details.accounts.length > MAX_PACKAGES ||
+    details.accounts.some(item => !item || typeof item !== "object" || Array.isArray(item))) {
+    return Object.freeze({ state: "unavailable", count: 0, items: Object.freeze([]) });
+  }
+  const items = details.accounts.map(item => {
+    const code = codeOf(item.PackageCode), kind = code && code === summary.SubscriptionPackageCode ? "base" :
+      code && Object.hasOwn(products, code) ? products[code][1] : "other";
+    const slice = Number(item.CapacityType) === 4 ? item.SlicePeriodUsageDetails?.[0] : undefined;
+    const total = capacity(slice ? slice.SlicePeriodCapacitySizePrecise : item.CycleCapacitySizePrecise);
+    const remaining = capacity(slice ? slice.SlicePeriodCapacityRemainPrecise : item.CycleCapacityRemainPrecise);
+    const used = total !== null && remaining !== null && total >= remaining ? total - remaining : null;
+    const candidates = kind === "daily" ? [item.CycleEndTime] : [item.DeductionEndTime, item.ExpiredTime];
+    const expiresAt = candidates.map(date).find(value => value !== null) ?? null;
+    const expiresText = expiresAt === null ? candidates.map(wallClock).find(Boolean) ?? null : null;
+    return Object.freeze({ kind, total, remaining, used, expiresAt, expiresText });
+  });
+  return Object.freeze({ state: details.state, count: items.length, items: Object.freeze(items) });
+}

package/src/native-credits.js

@@ -0,0 +1,175 @@
+import { createNativeClient, accountHeaders } from "./native-client.js";
+import { catalogCacheKey } from "./native-catalog-cache.js";
+import { WorkbuddyError, describeFailure } from "./native-errors.js";
+import { normalizeCreditPackages } from "./native-credit-packages.js";
+
+const MAX_PACKAGES = 2000;
+function capacity(value) {
+  if (typeof value === "string") {
+    if (!/^\d+(?:\.\d+)?$/.test(value.trim())) return null;
+    value = Number(value);
+  }
+  return typeof value === "number" && Number.isFinite(value) && value >= 0 && value <= Number.MAX_SAFE_INTEGER ? value : null;
+}
+function text(value) {
+  if (typeof value !== "string") return undefined;
+  const result = value.replace(/[\x00-\x1f\x7f]/g, "").trim().slice(0, 128);
+  return result || undefined;
+}
+
+/** Personal-account credits only; never infer a plan label, expiry, USD cost, or percentage. */
+export function normalizeCredits(data, fetchedAt) {
+  if (!Number.isSafeInteger(fetchedAt) || fetchedAt < 0 || !data || !Array.isArray(data.Packages) || data.Packages.length > MAX_PACKAGES ||
+    data.Packages.some(item => !item || typeof item !== "object" || Array.isArray(item))) {
+    throw new WorkbuddyError("credits-shape", "Unsupported WorkBuddy credit summary.");
+  }
+  const total = field => {
+    let result = 0;
+    for (const item of data.Packages) {
+      const value = capacity(item[field]);
+      if (value === null || result + value > Number.MAX_SAFE_INTEGER) return null;
+      result += value;
+    }
+    return result;
+  };
+  const planCode = text(data.SubscriptionPackageCode), planName = text(data.SubscriptionPackageName);
+  return {
+    creditsTotal: total("CycleTotalCapacity"),
+    creditsRemaining: total("CycleRemainCapacity"),
+    creditsUsed: total("CycleUsedCapacity"),
+    packageCount: data.Packages.length, fetchedAt,
+    ...(typeof data.IsPaidUser === "boolean" ? { isPaidUser: data.IsPaidUser } : {}),
+    ...(planCode ? { planCode } : {}), ...(planName ? { planName } : {}),
+  };
+}
+
+function cancelled() { return new WorkbuddyError("cancelled", "WorkBuddy credit read cancelled."); }
+function safeError(error) {
+  const message = describeFailure(error);
+  if (error instanceof WorkbuddyError && !message.startsWith("[unknown]")) {
+    const details = {};
+    if (Number.isInteger(error.details.status)) details.status = error.details.status;
+    if (Number.isSafeInteger(error.details.businessCode)) details.businessCode = error.details.businessCode;
+    // Do not expose upstream/custom error text, causes, or arbitrary diagnostic fields.
+    return new WorkbuddyError(error.diagnosticCode, message, details);
+  }
+  return new WorkbuddyError("credits-request", "WorkBuddy credits could not be refreshed.");
+}
+function permitsStale(error) {
+  if (["cancelled", "credentials", "account-domain", "metadata", "endpoint", "credits-scope"].includes(error.diagnosticCode)) return false;
+  if (error.diagnosticCode !== "http") return true;
+  const status = error.details.status;
+  return status === 408 || status === 429 || status >= 500 && status <= 599;
+}
+
+/** No timers, persistence, automatic login/refresh, or network work until read() is explicitly called. */
+export function createCreditsReader({ client = createNativeClient(), ttlMs = 60000, maxEntries = 8, now = Date.now } = {}) {
+  if (!Number.isSafeInteger(ttlMs) || ttlMs < 0 || !Number.isSafeInteger(maxEntries) || maxEntries < 1 || maxEntries > 128 ||
+    typeof now !== "function" || typeof client?.credits !== "function") throw new Error("Invalid WorkBuddy credit-reader configuration.");
+  const cache = new Map(), pending = new Map();
+  const timestamp = () => {
+    const value = now();
+    if (!Number.isSafeInteger(value) || value < 0) throw new Error("WorkBuddy credit-reader clock must return a nonnegative safe integer.");
+    return value;
+  };
+  function keyFor(credential) {
+    accountHeaders(credential);
+    if (credential.enterpriseId) throw new WorkbuddyError("credits-scope", "The verified credits route supports personal accounts only.");
+    const key = catalogCacheKey(credential); // Reuse only the hashed account scope, never the model store.
+    if (!key) throw new WorkbuddyError("credentials", "Invalid WorkBuddy account scope.");
+    return key;
+  }
+  function fresh(snapshot) {
+    const age = timestamp() - snapshot.fetchedAt;
+    return age >= 0 && age < ttlMs;
+  }
+  function remember(key, snapshot) {
+    cache.delete(key); cache.set(key, snapshot);
+    while (cache.size > maxEntries) cache.delete(cache.keys().next().value);
+  }
+  function start(key, credential) {
+    if (pending.size >= maxEntries) throw new WorkbuddyError("credits-busy", "Too many WorkBuddy credit reads.");
+    const job = { controller: new AbortController(), users: 0, settled: false };
+    // Defer execution until the job has been registered, including synchronous client failures.
+    job.promise = Promise.resolve().then(async () => {
+      try {
+        if (job.controller.signal.aborted) throw cancelled();
+        const raw = await client.credits(credential, job.controller.signal);
+        if (job.controller.signal.aborted) throw cancelled();
+        const metrics = normalizeCredits(raw, timestamp());
+        let packageDetails;
+        if (typeof client.creditPackages === "function") {
+          let details;
+          try { details = await client.creditPackages(credential, job.controller.signal, raw); }
+          catch { if (job.controller.signal.aborted) throw cancelled(); }
+          packageDetails = normalizeCreditPackages(details, raw);
+        }
+        if (job.controller.signal.aborted) throw cancelled();
+        // All fields share the start-of-read timestamp, rather than making older metrics look newer.
+        const snapshot = Object.freeze({ ...metrics, ...(packageDetails ? { packageDetails } : {}) });
+        remember(key, snapshot);
+        return snapshot;
+      } catch (error) {
+        const failure = job.controller.signal.aborted ? cancelled() : safeError(error);
+        if (!permitsStale(failure) && failure.diagnosticCode !== "cancelled") cache.delete(key);
+        throw failure;
+      }
+    }).finally(() => {
+      job.settled = true;
+      if (pending.get(key) === job) pending.delete(key);
+    });
+    pending.set(key, job);
+    return job;
+  }
+  function join(key, job, signal) {
+    job.users++;
+    return new Promise((resolve, reject) => {
+      let active = true;
+      const leave = () => {
+        active = false;
+        signal?.removeEventListener("abort", abort);
+        job.controller.signal.removeEventListener("abort", abort);
+        if (--job.users === 0 && !job.settled) {
+          if (pending.get(key) === job) pending.delete(key);
+          job.controller.abort();
+        }
+      };
+      const abort = () => { if (active) { leave(); reject(cancelled()); } };
+      signal?.addEventListener("abort", abort, { once: true });
+      job.controller.signal.addEventListener("abort", abort, { once: true });
+      job.promise.then(value => { if (active) { leave(); resolve(value); } }, error => { if (active) { leave(); reject(error); } });
+      if (signal?.aborted || job.controller.signal.aborted) abort();
+    });
+  }
+  return {
+    async read(credential, { signal, force = false, allowNetwork = true } = {}) {
+      if (typeof force !== "boolean" || typeof allowNetwork !== "boolean" || signal !== undefined &&
+        (typeof signal?.aborted !== "boolean" || typeof signal.addEventListener !== "function" || typeof signal.removeEventListener !== "function")) {
+        throw new Error("Invalid WorkBuddy credit-read options.");
+      }
+      if (signal?.aborted) throw cancelled();
+      const key = keyFor(credential), saved = cache.get(key);
+      const network = allowNetwork && process.env.PI_OFFLINE === undefined;
+      if (saved && (!network || !force && fresh(saved))) {
+        remember(key, saved);
+        return { ...saved, source: "cache", stale: !fresh(saved) };
+      }
+      if (!network) throw new WorkbuddyError("credits-offline", "No cached WorkBuddy credits available offline.");
+      try {
+        const snapshot = await join(key, pending.get(key) ?? start(key, credential), signal);
+        return { ...snapshot, source: "remote", stale: false };
+      } catch (error) {
+        const failure = safeError(error), previous = cache.get(key);
+        if (previous && permitsStale(failure)) return { ...previous, source: "cache", stale: true, error: failure.message };
+        throw failure;
+      }
+    },
+    clear(credential) {
+      const key = credential === undefined ? undefined : keyFor(credential);
+      for (const [id, job] of pending) if (key === undefined || id === key) {
+        pending.delete(id); job.controller.abort();
+      }
+      if (key === undefined) cache.clear(); else cache.delete(key);
+    },
+  };
+}

package/src/native-errors.js

@@ -15,6 +15,12 @@ const REASONS = {
   "envelope": "The JSON response envelope was unexpected.",
   "catalog-shape": "The response did not contain a supported models array.",
   "catalog-empty": "The server returned an empty model list.",
+  "catalog-cache": "Cached model metadata was rejected; refresh to rebuild the catalog.",
+  "credits-shape": "WorkBuddy returned unsupported credit-summary metadata.",
+  "credits-request": "WorkBuddy credits could not be refreshed.",
+  "credits-offline": "No cached WorkBuddy credits are available while offline.",
+  "credits-scope": "The verified credit reader supports personal WorkBuddy accounts only.",
+  "credits-busy": "Too many WorkBuddy credit reads are in progress; retry shortly.",
   "catalog-filtered": "No model passed the provider's compatibility/security filters.",
 };
 export class WorkbuddyError extends Error {

package/src/native-lifecycle.js

@@ -0,0 +1,52 @@
+import { describeFailure } from "./native-errors.js";
+
+function definition(model) {
+  return JSON.stringify([model?.provider, model?.id, model?.name, model?.contextWindow,
+    model?.maxTokens, model?.reasoning, model?.input, model?.thinkingLevelMap]);
+}
+
+export async function recoverSelectedModel(pi, provider, ctx, selected = ctx.model) {
+  // Never switch away from another provider, race a user selection, or alter a running turn.
+  if (!selected || selected.provider !== "workbuddy" || ctx.model !== selected || ctx.isIdle?.() === false) return;
+  let previousId = selected.id;
+  const placeholder = selected.name === "WorkBuddy Default (fallback)";
+  if (placeholder) {
+    // On resume Pi can replace a missing selection before session_start; the latest
+    // model-change record still identifies it. Never scan past a newer valid choice.
+    const previous = ctx.sessionManager?.getBranch?.().findLast(entry => entry.type === "model_change");
+    if (previous?.provider === "workbuddy" && typeof previous.modelId === "string") previousId = previous.modelId;
+  }
+  const id = /^deepseek-/i.test(previousId) && /-sg$/i.test(previousId) ? previousId.slice(0, -3) : previousId;
+  const replacement = provider.getModels().find(model => model.id === id) ??
+    (placeholder ? provider.getModels().find(model => model.id === selected.id) : undefined);
+  if (!replacement || definition(selected) === definition(replacement)) return;
+  if (await pi.setModel(replacement) === false) {
+    ctx.ui?.notify?.("WorkBuddy catalog is ready; select an available model with /model.", "warning");
+  } else if (id !== selected.id && replacement.id === id) {
+    ctx.ui?.notify?.("WorkBuddy restored the available model " + replacement.id + ". No chat request sent.", "info");
+  }
+}
+
+/** Embedded hosts can re-register providers without refreshing an already-seen provider ID. */
+export function registerNativeLifecycle(pi, provider) {
+  pi.on("session_start", async (_event, ctx) => {
+    const selected = ctx.model;
+    try {
+      if (!ctx.modelRegistry.hasConfiguredAuth(provider.getModels()[0])) return;
+      const result = await ctx.modelRegistry.refresh({
+        providers: ["workbuddy"], force: true, signal: ctx.signal,
+        // Honor PI_OFFLINE; otherwise inherit the registry's default network policy.
+        ...(process.env.PI_OFFLINE !== undefined ? { allowNetwork: false } : {}),
+      });
+      if (result.aborted) return;
+      if (result.errors.has("workbuddy")) {
+        ctx.ui?.notify?.("WorkBuddy catalog refresh failed: " + describeFailure(result.errors.get("workbuddy")) +
+          " Cached models, if available, were retained. No chat request sent.", "warning");
+      }
+      await recoverSelectedModel(pi, provider, ctx, selected);
+    } catch (error) {
+      ctx.ui?.notify?.("WorkBuddy startup recovery failed: " + describeFailure(error) +
+        " Use /workbuddy refresh to retry. No chat request sent.", "warning");
+    }
+  });
+}

package/src/native-provider.js

@@ -3,12 +3,16 @@ import { fallbackModels, projectModels } from "./native-models.js";
 import { createChatFetch } from "./native-transport.js";
 import { describeFailure } from "./native-errors.js";
 import { resolveOutputLimit, capPayloadOutput } from "./native-limits.js";
+import { catalogCacheKey, catalogCacheEntry, restoreCatalog } from "./native-catalog-cache.js";
+import { recoverSelectedModel } from "./native-lifecycle.js";
+import { EXTENSION_VERSION } from "./client-identity.js";
 
 export function createWorkbuddyProvider({ api, client = createNativeClient(), fetch: fetchImpl, gzip = true } = {}) {
   if (!api?.stream || !api?.streamSimple) throw new Error("Pi OpenAI streaming API is required.");
   let models = fallbackModels();
   let catalogSource = "fallback";
   let lastCatalogError;
+  let catalogAccountKey;
   function prepareRequest(model, options = {}) {
     let outputLimit = resolveOutputLimit(model, options.maxTokens);
     const modelSampling = model.samplingParams ? { ...model.samplingParams } : undefined;
@@ -51,13 +55,33 @@ export function createWorkbuddyProvider({ api, client = createNativeClient(), fe
     getModels: () => models,
     getCatalogStatus: () => ({ source: catalogSource, lastError: lastCatalogError }),
     async refreshModels(context) {
+      const key = catalogCacheKey(context.credential);
+      if (catalogAccountKey && catalogAccountKey !== key) {
+        if (await context.publish({ update: () => {
+          models = fallbackModels(); catalogSource = "fallback"; catalogAccountKey = undefined; lastCatalogError = undefined;
+        } }) === false) return;
+      }
+      if (catalogSource === "fallback" && context.stored) {
+        try {
+          const restored = restoreCatalog(context.stored, key);
+          if (restored && await context.publish({ update: () => {
+            models = restored; catalogSource = "cache"; catalogAccountKey = key; lastCatalogError = undefined;
+          } }) === false) return;
+        } catch (error) {
+          // Invalid or fully filtered caches must not block a fresh authenticated catalog fetch.
+          lastCatalogError = describeFailure(error);
+        }
+      }
       if (!context.allowNetwork || context.credential?.type !== "oauth") return;
       try {
         const next = projectModels(await client.catalog(context.credential, context.signal));
-        // Generation-checked publication owned by Pi. No auth or remote instructions persisted.
-        await context.publish({ update: () => {
-          models = next; catalogSource = "remote"; lastCatalogError = undefined;
-        } });
+        // Pi owns persistence and generation checks. Persist only projected public metadata.
+        await context.publish({
+          ...(key ? { persist: catalogCacheEntry(next, key) } : {}),
+          update: () => {
+            models = next; catalogSource = "remote"; catalogAccountKey = key; lastCatalogError = undefined;
+          },
+        });
       } catch (error) {
         lastCatalogError = describeFailure(error);
         throw error;
@@ -83,11 +107,12 @@ export function registerNativeCommands(pi, provider) {
         const ready = ctx.modelRegistry.hasConfiguredAuth(provider.getModels()[0]);
         const catalog = provider.getCatalogStatus?.();
         const active = ctx.model ? ctx.model.provider + "/" + ctx.model.id : "unknown";
-        ctx.ui.notify("WorkBuddy native (experimental): " + (ready ? "account configured" : "not logged in; use /login") +
+        ctx.ui.notify("WorkBuddy native " + EXTENSION_VERSION + " (experimental): " + (ready ? "account configured" : "not logged in; use /login") +
           ". " + provider.getModels().length + " known models; catalog=" + (catalog?.source ?? "unknown") +
           ". Active model: " + active + "." + (catalog?.lastError ? " Last catalog failure: " + catalog.lastError : "") +
           " No chat request sent.", "info");
       } else if (action === "refresh") {
+        const selected = ctx.model;
         try {
           if (!ctx.modelRegistry.hasConfiguredAuth(provider.getModels()[0])) {
             ctx.ui.notify("Sign in to WorkBuddy using /login first.", "warning"); return;
@@ -102,6 +127,7 @@ export function registerNativeCommands(pi, provider) {
               " Existing catalog retained. No chat request sent.", "warning");
             return;
           }
+          await recoverSelectedModel(pi, provider, ctx, selected);
           ctx.ui.notify("WorkBuddy catalog refreshed: " + provider.getModels().length + " models. Select with /model.", "info");
         } catch (error) {
           ctx.ui.notify("WorkBuddy catalog refresh failed: " +

package/src/native-tooltip-controller.js

@@ -0,0 +1,90 @@
+import { createCreditsReader } from "./native-credits.js";
+import { ORIGIN } from "./native-client.js";
+import { createTooltipAdapter, TOOLTIP_STATUS_KEY } from "./pendant-tooltip.js";
+
+/** Opt-in status transport for the optional Pendant adapter, not a native Pi usage hook. */
+export function registerPendantTooltip(pi, { reader = createCreditsReader(), enabled = false } = {}) {
+  const wire = createTooltipAdapter();
+  let active = enabled, generation = 0, pending, lastContext, published = false;
+  let payloadState = enabled ? "waiting" : "disabled";
+  const clear = ctx => {
+    try { if (published) ctx?.ui?.setStatus?.(TOOLTIP_STATUS_KEY, undefined); } catch { /* Unsupported UI must not break a turn. */ }
+    published = false;
+  };
+  const session = ctx => ctx.sessionManager?.getSessionId?.();
+  function stop(ctx) {
+    generation++;
+    pending?.controller.abort(); pending = undefined;
+    reader.clear(); clear(ctx ?? lastContext);
+    payloadState = active ? "waiting" : "disabled";
+  }
+  async function refresh(ctx, force = false) {
+    lastContext = ctx;
+    if (!active || ctx.mode !== "rpc" || ctx.model?.provider !== "workbuddy") { stop(ctx); return; }
+    const sessionId = session(ctx);
+    if (typeof sessionId !== "string" || !/^[\w-]{1,128}$/.test(sessionId)) { stop(ctx); return; }
+    const identity = sessionId + "/" + ctx.model.id;
+    if (pending?.identity === identity && !force) return pending.promise;
+    generation++;
+    pending?.controller.abort();
+    const ticket = generation, controller = new AbortController();
+    const job = { identity, controller };
+    pending = job;
+    const current = () => active && generation === ticket && !controller.signal.aborted && session(ctx) === sessionId && ctx.model?.provider === "workbuddy";
+    const publish = (state, data = {}) => {
+      if (current()) {
+        try {
+          ctx.ui.setStatus(TOOLTIP_STATUS_KEY, wire.encode({ ...data, v: 1, provider: "workbuddy", sessionId, state }));
+          published = true; payloadState = state;
+        } catch { active = false; stop(ctx); }
+      }
+    };
+    job.promise = Promise.resolve().then(async () => {
+      publish("loading"); // Remove old balances while the current auth scope is being resolved.
+      if (!current()) { if (pending === job) pending = undefined; return; }
+      try {
+        const model = ctx.model;
+        const auth = await ctx.modelRegistry.getApiKeyAndHeaders(model);
+        if (!current()) return;
+        if (!auth?.ok) throw new Error("Account unavailable");
+        if (auth.baseUrl && new URL(auth.baseUrl).origin !== ORIGIN) throw new Error("Untrusted account origin");
+        const headers = new Headers(auth.headers);
+        const access = auth.apiKey || headers.get("Authorization")?.replace(/^Bearer\s+/i, "");
+        const credential = { type: "oauth", origin: ORIGIN, access, userId: headers.get("X-User-Id"),
+          domain: headers.get("X-Domain") || "www.workbuddy.ai",
+          ...(headers.get("X-Enterprise-Id") ? { enterpriseId: headers.get("X-Enterprise-Id") } : {}),
+        };
+        const signal = ctx.signal ? AbortSignal.any([ctx.signal, controller.signal]) : controller.signal;
+        const data = await reader.read(credential, { force, signal, allowNetwork: process.env.PI_OFFLINE === undefined });
+        publish("ready", data);
+      } catch {
+        if (current()) { reader.clear(); publish("unavailable"); }
+      } finally {
+        if (pending === job) pending = undefined;
+      }
+    });
+    return job.promise;
+  }
+  pi.registerCommand("workbuddy-tooltip", {
+    description: "Experimental Pendant tooltip relay: on/off/refresh/status (requires the optional host adapter)",
+    async handler(args, ctx) {
+      const action = args.trim() || "status";
+      if (action === "off") { active = false; stop(ctx); ctx.ui.notify("WorkBuddy tooltip relay disabled.", "info"); return; }
+      if (action === "status") {
+        ctx.ui.notify("WorkBuddy tooltip relay: " + (active ? "enabled" : "disabled") + "; payload=" + payloadState +
+          ". Requires the optional Pendant adapter v2 (renderer + broker). No chat request sent.", "info"); return;
+      }
+      if (!["on", "refresh"].includes(action)) { ctx.ui.notify("Usage: /workbuddy-tooltip [on|off|refresh|status]", "warning"); return; }
+      if (ctx.mode !== "rpc") { ctx.ui.notify("The experimental tooltip relay is for Pendant/RPC, not the CLI footer.", "warning"); return; }
+      if (action === "on") {
+        active = true;
+        ctx.ui.notify("Experimental WorkBuddy tooltip relay enabled. The separate Pendant adapter must already be installed; this command does not patch the host.", "info");
+      }
+      if (!active) { ctx.ui.notify("Enable the optional relay with /workbuddy-tooltip on first.", "warning"); return; }
+      await refresh(ctx, action === "refresh");
+    },
+  });
+  for (const event of ["session_start", "model_select", "agent_end"]) pi.on(event, async (_event, ctx) => { await refresh(ctx); });
+  pi.on("session_shutdown", async (_event, ctx) => { active = false; stop(ctx); });
+  return { refresh, dispose() { active = false; stop(lastContext); } };
+}

package/src/pendant-tooltip.js

@@ -0,0 +1,105 @@
+export const TOOLTIP_STATUS_KEY = "workbuddy.credits.v1";
+
+/** Self-contained so the optional host adapter can embed exactly the same validator/renderer. */
+export function createTooltipAdapter(statusKey = "workbuddy.credits.v1") {
+  const number = value => value === null || typeof value === "number" && Number.isFinite(value) && value >= 0 && value <= Number.MAX_SAFE_INTEGER;
+  const text = value => typeof value === "string" ? value.replace(/[\x00-\x1f\x7f\u202a-\u202e\u2066-\u2069]/g, "").trim().slice(0, 128) : "";
+  const instant = value => value === null || Number.isSafeInteger(value) && value >= 0 && value <= 8640000000000000;
+  const wallClock = value => value === null || typeof value === "string" && /^\d{4}-\d\d-\d\d \d\d:\d\d:\d\d$/.test(value) &&
+    Number.isFinite(Date.parse(value.replace(" ", "T") + "Z")) && new Date(value.replace(" ", "T") + "Z").toISOString().slice(0, 19) === value.replace(" ", "T");
+  const tone = (remaining, total, stale) => {
+    if (stale || remaining === null) return undefined;
+    if (remaining === 0) return "danger";
+    if (total > 0 && remaining <= total) {
+      const percent = remaining / total * 100;
+      return percent < 15 ? "danger" : percent < 50 ? "warning" : "good";
+    }
+  };
+  function validate(input, maxItems = 4) {
+    if (!input || input.v !== 1 || input.provider !== "workbuddy" || typeof input.sessionId !== "string" || !/^[\w-]{1,128}$/.test(input.sessionId) ||
+      !["loading", "ready", "unavailable"].includes(input.state)) return undefined;
+    const packet = { v: 1, provider: "workbuddy", sessionId: input.sessionId, state: input.state };
+    if (input.state !== "ready") return packet;
+    if (![input.creditsTotal, input.creditsRemaining, input.creditsUsed].every(number) ||
+      !Number.isSafeInteger(input.packageCount) || input.packageCount < 0 || input.packageCount > 2000 ||
+      !Number.isSafeInteger(input.fetchedAt) || input.fetchedAt < 0 || input.fetchedAt > 8640000000000000 ||
+      !["cache", "remote"].includes(input.source) || typeof input.stale !== "boolean") return undefined;
+    Object.assign(packet, { creditsTotal: input.creditsTotal, creditsRemaining: input.creditsRemaining,
+      creditsUsed: input.creditsUsed, packageCount: input.packageCount, fetchedAt: input.fetchedAt,
+      source: input.source, stale: input.stale });
+    if (input.packageDetails !== undefined) {
+      const details = input.packageDetails;
+      if (!details || !["complete", "partial", "unavailable"].includes(details.state) ||
+        !Number.isSafeInteger(details.count) || details.count < 0 || details.count > 2000 || !Array.isArray(details.items) ||
+        details.items.length > maxItems || details.items.length > details.count ||
+        details.state === "unavailable" && (details.count !== 0 || details.items.length !== 0)) return undefined;
+      const items = [];
+      for (const item of details.items) {
+        if (!item || !["base", "bonus", "topup", "daily", "other"].includes(item.kind) ||
+          ![item.total, item.remaining, item.used].every(number) || !instant(item.expiresAt) || !wallClock(item.expiresText) ||
+          item.expiresAt !== null && item.expiresText !== null) return undefined;
+        items.push({ kind: item.kind, total: item.total, remaining: item.remaining, used: item.used,
+          expiresAt: item.expiresAt, expiresText: item.expiresText });
+      }
+      packet.packageDetails = { state: details.state, count: details.count, items };
+    }
+    const name = text(input.planName);
+    if (name) packet.planName = name;
+    return packet;
+  }
+  return {
+    encode(input) {
+      const packet = validate(input, 2000);
+      if (!packet) throw new Error("Invalid WorkBuddy tooltip payload.");
+      if (packet.packageDetails) {
+        const priority = item => item.kind === "base" ? 0 : item.kind === "daily" ? 1 : 2;
+        packet.packageDetails.items.sort((a, b) => priority(a) - priority(b) || (a.expiresAt ?? Infinity) - (b.expiresAt ?? Infinity));
+        packet.packageDetails.items = packet.packageDetails.items.slice(0, 4);
+      }
+      return JSON.stringify(packet);
+    },
+    append(base, entries, context, now = Date.now()) {
+      if (base?.kind !== "grid" || !Array.isArray(base.rows) || context?.provider !== "workbuddy" ||
+        context.modelAvailable !== true || !context.sessionId || !Array.isArray(entries)) return base;
+      const candidates = entries.filter(entry => entry?.key === statusKey);
+      if (candidates.length !== 1 || typeof candidates[0].text !== "string" || candidates[0].text.length > 4096) return base;
+      let packet;
+      try { packet = validate(JSON.parse(candidates[0].text)); } catch { return base; }
+      if (!packet || packet.sessionId !== context.sessionId) return base;
+      const rows = [];
+      if (packet.state !== "ready") rows.push({ label: "WorkBuddy credits", value: packet.state === "loading" ? "Loading…" : "Unavailable",
+        ...(packet.state === "unavailable" ? { valueTone: "warning" } : {}) });
+      else {
+        const format = value => value === null ? "Unknown" : value.toLocaleString(undefined, { maximumFractionDigits: 6 });
+        const stale = packet.stale || !Number.isFinite(now) || now < packet.fetchedAt || now - packet.fetchedAt >= 60000;
+        const remainingTone = tone(packet.creditsRemaining, packet.creditsTotal, stale);
+        if (packet.planName) rows.push({ label: "Plan", value: packet.planName });
+        rows.push({ label: "Credits remaining", value: format(packet.creditsRemaining), ...(remainingTone ? { valueTone: remainingTone } : {}) });
+        const details = packet.packageDetails;
+        if (details?.items.length) {
+          const counts = {}, names = { base: "Base credits", daily: "Daily credits", bonus: "Bonus", topup: "Top-up", other: "Credit pack" };
+          for (const item of details.items) {
+            counts[item.kind] = (counts[item.kind] ?? 0) + 1;
+            const indexed = !["base", "daily"].includes(item.kind) || details.items.filter(other => other.kind === item.kind).length > 1;
+            const valueTone = tone(item.remaining, item.total, stale);
+            rows.push({ label: names[item.kind] + (indexed ? " " + counts[item.kind] : ""),
+              value: format(item.remaining) + " / " + format(item.total) + " left", ...(valueTone ? { valueTone } : {}) });
+            rows.push({ label: item.expiresText ? "Expires (server time)" : "Expires", value: item.expiresAt !== null ?
+              new Date(item.expiresAt).toLocaleString() : item.expiresText ?? "Unknown" });
+          }
+          if (details.count > details.items.length) rows.push({ label: "More packages", value: String(details.count - details.items.length) + " not shown" });
+        } else {
+          rows.push({ label: "Credits used / total", value: format(packet.creditsUsed) + " / " + format(packet.creditsTotal) });
+          rows.push({ label: "Credit groups", value: String(packet.packageCount) });
+        }
+        if (details && details.state !== "complete") rows.push({ label: "Package details",
+          value: details.state === "partial" ? "Partial" : "Unavailable", valueTone: "warning" });
+        rows.push({ label: "Updated", value: new Date(packet.fetchedAt).toLocaleString() });
+        if (stale) {
+          rows.push({ label: "Credit data", value: "Cached / stale", valueTone: "warning" });
+        }
+      }
+      return { ...base, rows: [...base.rows, ...rows] };
+    },
+  };
+}