@go-labs-sg/bb 2.45.1 → 2.47.0

package/README.md

@@ -1,10 +1,22 @@
 # bb
 
-Command-line interface for **Budget Builder**. Call budgets, bills, claims, approvals, suppliers, dashboard, and more from your terminal or from tools that don’t support MCP (e.g. some AI agents). Responses are JSON on stdout.
+Command-line interface for **Budget Builder**. Call budgets, bills, claims, approvals, suppliers, dashboard, and more from your terminal or from AI agents and automation. The CLI is the maintained integration surface; the former MCP server is deprecated. Responses are JSON on stdout.
 
-For AI agents: bills and claims are stored as the same underlying bill records. Use the `isClaimable` column/flag to distinguish them: `isClaimable=false` means a normal bill, while `isClaimable=true` means a reimbursable claim.
+## First step: update before use
+
+Before starting a task, **update to the latest published release first**, including when an AI agent runs this CLI:
+
+```bash
+bun add --global @go-labs-sg/bb@latest
+bb version
+bb --help
+```
 
-For AI agents using this CLI: always check whether a newer `@go-labs-sg/bb` version is available before running Budget Builder commands, then update the CLI if needed so command flags and API behavior stay current.
+Run this sequence once per task, not before every command. Re-read the updated help before choosing commands or flags. If updating fails, stop and report the failure rather than silently using an outdated CLI. If the user explicitly requested a pinned version or a development/staging build, preserve that version instead of replacing it with the public release.
+
+New installation? Follow the runtime and installation instructions below to install Bun first, then return to this step.
+
+For AI agents: bills and claims are stored as the same underlying bill records. Use the `isClaimable` column/flag to distinguish them: `isClaimable=false` means a normal bill, while `isClaimable=true` means a reimbursable claim.
 
 For AI agents using this CLI: run `bb auth whoami` before reading or changing Budget Builder data. The CLI displays every command regardless of the authenticated user's role, but the API authorizes each request using the current browser-authorized CLI user or automation API-key owner, resource ownership or project assignment, current workflow state, and approval assignment. See the [role-aware agent guide](./role-aware-agent-guide.md) before choosing commands.
 
@@ -12,6 +24,20 @@ For AI agents using this CLI: do not execute mutations until the user explicitly
 
 **Registry:** [`@go-labs-sg/bb`](https://www.npmjs.com/package/@go-labs-sg/bb)
 
+## Bill and claim list summaries
+
+`bb bill list` / `bb claim list` (legacy `list-bills` / `list-claims`) use the updated summary-only `bill.getAll`. Lists return summary fields, `isClaimable`, `lineItemCount` and `hasPendingApproval`, plus the existing pagination, counts and metrics envelope. Filters, sorting and the CLI's existing summary output are unchanged. Lists do not return attachment, detailed line-item or approval arrays, full supplier/budget/project/company records, or detail-only payment/integration/verification metadata.
+
+**Breaking API migration:** `bill.getList` is removed completely, with no alias or fallback. Direct scripts reading the former rich `bill.getAll` response must adopt summaries and fetch selected bill/claim details with `bb get-bill-details <billId>`. Do not fetch details for every list row unless the task actually needs them. No rich-list flag or automatic detail expansion is added.
+
+Coordinate the matching API/web deployment and CLI release/installations. MCP is deprecated and is not a rollout or acceptance gate. Published CLI builds still calling `getList` receive `NOT_FOUND` after API rollout, so a mixed-revision deployment is not compatible. Update those installations to the matching CLI release. Budget-list options are unchanged. This source change does not publish the CLI or deploy the API.
+
+## Inventory list reads
+
+`bb item list` / `bb list-items` now use the updated page-only `item.getItems` and separate `item.getItemCounts`. The JSON output remains `{ items, pageCount, counts }`; filters and pagination are unchanged. Neither request carries an acting-user cache ID. The server authenticates the CLI session or API-key owner as usual.
+
+The existing `item.getItems` API is updated in place: it now returns an array rather than `{ items, pageCount, counts }`. There is no separate `getItemPage` procedure. Coordinate the API/web deployment and CLI release/installations: old clients expecting the combined response must be upgraded, and new clients require the revised response and separate counts. Direct integrations should fetch counts only when needed. This PR does not publish the CLI or deploy the API.
+
 ## Company discovery and reuse
 
 `bb company search --query "a star" [--page 2]` searches stored BB companies and QuickBooks company customers, including inactive records. Results identify `bb`, `qbo`, or `both`; punctuation/spacing normalization is for suggestions only. Search does not write to either system.
@@ -63,7 +89,7 @@ See the [supplier review and rollout policy](../api/docs/supplier-edit-review.md
 
 ## Runtime and installation
 
-The same CLI package supports macOS and Windows. It requires [Bun](https://bun.com/docs/installation) 1.4.0 or newer and a Budget Builder account with any active user role. Windows users can run the commands below in native PowerShell; Bash and `export PATH=...` are not required.
+The same CLI package targets macOS, Windows, and Linux; authentication depends on the secure backend described below. It requires [Bun](https://bun.com/docs/installation) 1.4.0 or newer and a Budget Builder account with any active user role. Windows users can run the commands below in native PowerShell; Bash and `export PATH=...` are not required.
 
 Check whether a compatible Bun version is already available:
 
@@ -125,6 +151,16 @@ bb get-budget-details <budget-id> --includeInactive
 
 `--active false` lists inactive budgets only. `--active all` lists active and inactive budgets. `--includeInactive` allows the three budget/detail/item commands to read inactive history. If the authenticated identity is not an Admin, the API rejects the historical request before reading budget data. For `get-budget`, the CLI requests the budget and its line items concurrently; each API read independently enforces the same active-only default and Admin-only historical opt-in.
 
+## Secure credential storage
+
+`GO_LABS_CLI_CREDENTIAL_ACCOUNT` selects the native credential-store account for this CLI. The default is `default`, preserving existing production logins. The downloadable staging launcher sets it to `staging` so a staging login does not replace the production login; keep the same account value for login and subsequent commands. The launcher also sets `GO_LABS_CLI_SKIP_DOTENV=1`, which skips the CLI's explicit current-directory `.env` load while leaving normal production behavior unchanged.
+
+Browser sessions use `Bun.secrets`: macOS Keychain, Windows Credential Manager, or Linux Secret Service. Linux requires libsecret, a reachable user D-Bus session, and an unlocked Secret Service collection. SSH and containers must provide those native prerequisites themselves; `--no-browser` only lets approval happen on another device. Denied D-Bus access is a host permissions/session issue, not something the CLI bypasses.
+
+Before requesting approval, login verifies write/read/delete capability with a unique non-secret probe. Native operations have a 10-second process deadline and sanitized errors. Issued credentials are read back and verified; failed persistence attempts remote revocation and reports local and remote cleanup separately. There is no plaintext fallback or external credential-helper configuration.
+
+See the [shared authentication contract](../../cli-auth/README.md) for recovery and verification limits.
+
 ## Authentication
 
 Interactive users authorize the CLI through Budget Builder's normal Google-backed
@@ -142,12 +178,12 @@ credentials through `Bun.secrets`. It never stores Google credentials. Use
 `bb auth logout` to revoke the interactive session. For SSH or containers, pass
 `--no-browser` and open the printed URL on another device.
 
-Credentials use macOS Keychain or Windows Credential Manager, not plaintext files.
+Credentials use macOS Keychain, Windows Credential Manager, or Linux Secret Service, not plaintext files.
 The per-user lock directory contains only random ownership markers used to serialize
 login, refresh, and logout. macOS/Linux enforce owner-only POSIX permissions there;
 Windows uses its native filesystem access controls rather than POSIX mode checks.
 
-Budget Builder API keys remain supported for MCP, CI, and non-interactive
+Budget Builder API keys remain supported for CI and non-interactive CLI
 automation. When `BB_API_KEY` is present it takes precedence over the interactive
 session for that process. Create and manage automation keys under **API Keys** or
 with the commands below:
@@ -164,6 +200,16 @@ only. Revoking the key currently stored in `BB_API_KEY` causes that automation
 process to fail until the environment credential is replaced or removed so the
 interactive session can be used.
 
+`bb user api-key list` and the `mcpApiKey.list` API retain the nullable
+`lastUsedAt` field for compatibility (an ISO timestamp in CLI JSON). Interpret
+only its calendar date in `Asia/Singapore` (UTC+08:00): it records the first
+successful usage touch of that day, **not the most recent request time**.
+Null means no use has been recorded; pre-rollout values may represent any use
+on their recorded day. Do not use the time portion for inactivity timeouts,
+minute-level mutation attribution, or request auditing. Authentication still
+reads the key and current user ban status on every request; revocation does
+not cancel requests already in flight.
+
 Admins can provision API-only service identities and manage their keys from the
 CLI. These identities are not human web accounts: `create-user` does not create
 or link a Google OAuth account, so the resulting user cannot sign in with Google.
@@ -248,7 +294,7 @@ Global options and command flags use `--key=value` or `--key value`. Run `bb hel
 
 Run `bb version` before agent-driven work to record the installed package version and production API target. This is read-only and does not require authentication.
 
-**Authoritative command list:** run `bb help` or inspect the generated `command-reference.md` / `command-manifest.json`. The catalog includes every canonical route, global option, and effect classification, but does not filter by the current `whoami` role. During the handler migration, command-specific arguments retain the compatibility dispatcher's validation and are explicitly marked `legacy-passthrough` in the manifest; use `bb help --legacy` for their detailed transition reference. Version 2 uses grouped, resource-first commands such as `bb budget list` and `bb bill attachment upload`. Flat commands such as `bb list-budgets` and their MCP-style `snake_case` aliases remain available during the v2 transition, with a deprecation notice and an equivalent grouped command in help. MCP exposes a subset of the same tRPC surface; the CLI additionally includes a few procedures mainly used by the web UI.
+**Authoritative command list:** run `bb help` or inspect the generated `command-reference.md` / `command-manifest.json`. The catalog includes every canonical route, global option, and effect classification, but does not filter by the current `whoami` role. During the handler migration, command-specific arguments retain the compatibility dispatcher's validation and are explicitly marked `legacy-passthrough` in the manifest; use `bb help --legacy` for their detailed transition reference. Version 2 uses grouped, resource-first commands such as `bb budget list` and `bb bill attachment upload`. Flat commands such as `bb list-budgets` and their legacy `snake_case` aliases remain available during the v2 transition, with a deprecation notice and an equivalent grouped command in help. The CLI calls the shared tRPC API, including procedures also used by the web UI.
 
 **Budget status automation:** Setting a budget to `ESTIMATE_ACCEPTED` requires a confirmed win-proof attachment. `--invoiceSettings '<json>'` remains available when the project needs saved delivery preferences, but invoice creation chooses its amount independently from those settings. If the parent project is `PITCH` or `LOST`, the API marks it `WON` automatically and runs enabled Asana automation. When rejecting the only accepted/closed budget on a commercial project, pass `--projectStatusOnCommercialRejection PITCH|LOST`.
 
@@ -440,6 +486,23 @@ bb quotation create --payload '{
 Use the same fields for `bb quotation update --payload`, adding the existing quotation `"id": "<quotation-id>"`. Read the quotation and its budget before updating so the IDs and current status are confirmed. The example's subtotal is S$1,200, GST is S$0, and total is S$1,200; those values are illustrative only and contain no live resource IDs.
 
 
+### Budget version history (pagination contract change)
+
+`bb budget version list <budgetId>` now returns **one page**, not the full history array. The normal CLI envelope contains `data: { versions, nextCursor }`; legacy aliases `get-budget-versions` and `get_budget_versions` return that page object directly. Update scripts that previously iterated the top-level array to iterate `versions` and explicitly request older pages when needed.
+
+```bash
+bb budget version list <budgetId>
+bb budget version list <budgetId> --limit 20 --cursor <nextCursor>
+bb budget version list <budgetId> --all
+```
+
+- Default page size: 20; `--limit` accepts integers from 1 to 50.
+- `nextCursor: null` means no older visible versions. Otherwise pass it as `--cursor` for the next page; do not automatically drain history for ordinary browsing.
+- `--all` explicitly collects all visible history through sequential bounded requests. It cannot be combined with `--cursor`; `--limit` controls each request's size. It can still be expensive and retains the complete result in memory. A failed page aborts without emitting a successful partial export.
+- Pages preserve newest-first `createdAt`/`id` ordering, role visibility, and creator/version-group metadata. They are not a point-in-time database snapshot; versions added after traversal starts require a fresh first-page read, and concurrent changes to visibility can affect traversal.
+
+The backend must expose `budgetVersion.getBudgetVersionsPage`. The legacy unbounded tRPC `getBudgetVersions` remains available but deprecated for external compatibility; unknown external clients are not silently capped. Removing that endpoint requires a separate usage/compatibility review. This change does not publish the CLI, deploy the backend, delete audit snapshots, or establish measured RU savings.
+
 ### Link an existing QuickBooks invoice
 
 **Release status:** these CLI commands are pending release. The repository package version remains `2.31.0`; that version number alone does not establish that a published CLI contains them. Check `bb help` for `customer-invoice preview-qbo` and `customer-invoice import-qbo` after the normal CLI release. This code delivery does not publish the CLI, deploy the API, or perform a production import. The backend must expose `customerInvoice.previewExistingInvoice` and `customerInvoice.linkExistingInvoice` (implemented in PR #1067).

package/command-manifest.json

@@ -606,6 +606,18 @@
 			{
 				"name": "--allow-financial-write",
 				"description": "Allow financial-record changes in non-interactive use."
+			},
+			{
+				"name": "--limit <1-50>",
+				"description": "Versions per page (default 20). Returns versions and nextCursor, not a full-history array."
+			},
+			{
+				"name": "--cursor <versionId>",
+				"description": "Load the next page using the previous nextCursor; null means complete."
+			},
+			{
+				"name": "--all",
+				"description": "Explicitly fetch all visible history in bounded pages; cannot combine with --cursor. May be expensive."
 			}
 		],
 		"argumentMode": "legacy-passthrough",

package/dist/index.js

@@ -468,7 +468,9 @@ var require_dist = __commonJS(function(exports, module) {
 // src/load-env.ts
 var import_dotenv = __toESM(require_dist(), 1);
 import path from "path";
-import_dotenv.config({ path: path.resolve(process.cwd(), ".env"), quiet: true });
+if (process.env.GO_LABS_CLI_SKIP_DOTENV !== "1") {
+  import_dotenv.config({ path: path.resolve(process.cwd(), ".env"), quiet: true });
+}
 
 // ../../cli-auth/src/client/credential-store.ts
 import { createHash as createHash2, randomUUID } from "crypto";
@@ -1483,6 +1485,8 @@ function datetime(args) {
 }
 var anyString = /^[\s\S]{0,}$/;
 var number = /^-?\d+(?:\.\d+)?$/;
+var boolean = /^(?:true|false)$/i;
+var _null = /^null$/i;
 var lowercase = /^[^A-Z]*$/;
 var uppercase = /^[^a-z]*$/;
 
@@ -2364,6 +2368,43 @@ var $ZodNumberFormat = /* @__PURE__ */ $constructor("$ZodNumberFormat", (inst, d
   $ZodCheckNumberFormat.init(inst, def);
   $ZodNumber.init(inst, def);
 });
+var $ZodBoolean = /* @__PURE__ */ $constructor("$ZodBoolean", (inst, def) => {
+  $ZodType.init(inst, def);
+  inst._zod.pattern = boolean;
+  inst._zod.parse = (payload, _ctx) => {
+    if (def.coerce)
+      try {
+        payload.value = Boolean(payload.value);
+      } catch (_) {}
+    const input = payload.value;
+    if (typeof input === "boolean")
+      return payload;
+    payload.issues.push({
+      expected: "boolean",
+      code: "invalid_type",
+      input,
+      inst
+    });
+    return payload;
+  };
+});
+var $ZodNull = /* @__PURE__ */ $constructor("$ZodNull", (inst, def) => {
+  $ZodType.init(inst, def);
+  inst._zod.pattern = _null;
+  inst._zod.values = new Set([null]);
+  inst._zod.parse = (payload, _ctx) => {
+    const input = payload.value;
+    if (input === null)
+      return payload;
+    payload.issues.push({
+      expected: "null",
+      code: "invalid_type",
+      input,
+      inst
+    });
+    return payload;
+  };
+});
 var $ZodUnknown = /* @__PURE__ */ $constructor("$ZodUnknown", (inst, def) => {
   $ZodType.init(inst, def);
   inst._zod.parse = (payload) => payload;
@@ -3901,6 +3942,18 @@ function _int(Class, params) {
     ...normalizeParams(params)
   });
 }
+function _boolean(Class, params) {
+  return new Class({
+    type: "boolean",
+    ...normalizeParams(params)
+  });
+}
+function _null2(Class, params) {
+  return new Class({
+    type: "null",
+    ...normalizeParams(params)
+  });
+}
 function _unknown(Class) {
   return new Class({
     type: "unknown"
@@ -4783,6 +4836,18 @@ var numberProcessor = (schema, ctx, _json, params) => {
       json.allOf = [...json.allOf ?? [], ...rest.map((m) => ({ multipleOf: m }))];
   }
 };
+var booleanProcessor = (_schema, _ctx, json, _params) => {
+  json.type = "boolean";
+};
+var nullProcessor = (_schema, ctx, json, _params) => {
+  if (ctx.target === "openapi-3.0") {
+    json.type = "string";
+    json.nullable = true;
+    json.enum = [null];
+  } else {
+    json.type = "null";
+  }
+};
 var neverProcessor = (_schema, _ctx, json, _params) => {
   json.not = {};
 };
@@ -5577,6 +5642,22 @@ var ZodNumberFormat = /* @__PURE__ */ $constructor("ZodNumberFormat", (inst, def
 function int(params) {
   return _int(ZodNumberFormat, params);
 }
+var ZodBoolean = /* @__PURE__ */ $constructor("ZodBoolean", (inst, def) => {
+  $ZodBoolean.init(inst, def);
+  ZodType.init(inst, def);
+  inst._zod.processJSONSchema = (ctx, json, params) => booleanProcessor(inst, ctx, json, params);
+});
+function boolean2(params) {
+  return _boolean(ZodBoolean, params);
+}
+var ZodNull = /* @__PURE__ */ $constructor("ZodNull", (inst, def) => {
+  $ZodNull.init(inst, def);
+  ZodType.init(inst, def);
+  inst._zod.processJSONSchema = (ctx, json, params) => nullProcessor(inst, ctx, json, params);
+});
+function _null3(params) {
+  return _null2(ZodNull, params);
+}
 var ZodUnknown = /* @__PURE__ */ $constructor("ZodUnknown", (inst, def) => {
   $ZodUnknown.init(inst, def);
   ZodType.init(inst, def);
@@ -5995,6 +6076,9 @@ var storedCliCredentialsSchema = object({
   session: cliSessionIdentitySchema
 }).strict();
 var cliProductSchema = _enum(cliProducts);
+// ../../cli-auth/src/client/secret-backend.ts
+import { execFile } from "child_process";
+
 // ../../cli-auth/src/client/runtime.ts
 var MINIMUM_BUN_VERSION = [1, 4, 0];
 var parseBunVersion = (version) => {
@@ -6020,27 +6104,145 @@ var assertBunRuntime = (runtime = globalThis.Bun) => {
   }
 };
 
-// ../../cli-auth/src/client/credential-store.ts
+// ../../cli-auth/src/client/storage-error.ts
+var guidance = {
+  "missing-library": "Install the runtime's native credential-store library and ensure your own native keyring/session is accessible and unlocked; Linux desktop storage requires libsecret AND an accessible, unlocked Secret Service.",
+  "bus-unavailable": "The Linux user D-Bus session is absent or unreachable. --no-browser does not provide storage. Start or repair your own user session and native keyring before retrying.",
+  "bus-denied": "Access to the Linux user bus was denied. Fix your own native keyring/session permissions or host policy; do not change bus/socket permissions or borrow another user's bus.",
+  "service-unavailable": "The user bus is reachable but your own Secret Service is unavailable. Start or repair your own native keyring session; do not expose another user's store.",
+  locked: "Unlock your own native credential collection/session before retrying. The CLI will not wait indefinitely for an unlock prompt.",
+  timeout: "The native credential backend did not finish within 10 seconds and its process was terminated. Fix or unlock your own native keyring/session outside the CLI; the CLI will not bypass host permissions.",
+  "invalid-response": "The native credential backend returned an invalid response. Check your own keyring/session and configuration; no credential output was disclosed.",
+  "read-failed": "The native credential backend could not read credentials. Check your own keyring/session availability and permissions; this is not evidence that you are logged out.",
+  "write-failed": "The native credential backend could not persist credentials. Check your own keyring/session write permissions and availability; no plaintext fallback is used.",
+  "delete-failed": "The native credential backend could not delete its entry. Check your own keyring/session permissions and remove any non-secret preflight probe through that backend if necessary."
+};
+
 class CliCredentialStoreUnavailableError extends Error {
   code = "CLI_CREDENTIAL_STORE_UNAVAILABLE";
-  constructor(product, options) {
-    super(`Secure credential storage is unavailable for the ${product} CLI. Bun.secrets requires the operating system credential store, including Secret Service on Linux. Browser authentication cannot continue without a supported secure store.`, options);
+  reason;
+  constructor(product, reason = "read-failed") {
+    super(`Secure credential storage is unavailable for the ${product} CLI [CLI_CREDENTIAL_STORE_UNAVAILABLE:${reason}]. ${guidance[reason]}`);
     this.name = "CliCredentialStoreUnavailableError";
-  }
+    this.reason = reason;
+  }
+}
+var classifyCredentialStoreFailure = (message, fallback) => {
+  if (/libsecret.*(not found|not available|cannot open|load)|dlopen|shared (object|library).*not found/i.test(message))
+    return "missing-library";
+  if (/(d-?bus|user bus|session bus).*(denied|not permitted)|(?:denied|not permitted).*(d-?bus|user bus|session bus)/i.test(message))
+    return "bus-denied";
+  if (/locked|interaction.*not allowed|user.*cancel/i.test(message))
+    return "locked";
+  if (/ServiceUnknown|org\.freedesktop\.secrets.*(not provided|no owner|not available)|secret.?service.*(unavailable|not running)/i.test(message))
+    return "service-unavailable";
+  if (/d-?bus|user bus|session bus|autolaunch/i.test(message))
+    return "bus-unavailable";
+  return fallback;
+};
+
+class CliCredentialPersistenceError extends Error {
+  remoteRevoked;
+  localRestored;
+  phase;
+  code = "CLI_CREDENTIAL_PERSISTENCE_FAILED";
+  constructor(remoteRevoked, localRestored, phase) {
+    super(`CLI credentials could not be saved after ${phase} [CLI_CREDENTIAL_PERSISTENCE_FAILED]. ${remoteRevoked ? "The newly issued session was revoked." : "Remote revocation could not be confirmed; revoke the session in the product's session management before retrying."} ${localRestored ? phase === "login" ? "The previous local credentials were preserved." : "The unusable rotated local credentials were removed; sign in again." : "Local cleanup could not be confirmed. Inspect your own native credential backend before retrying."}`);
+    this.remoteRevoked = remoteRevoked;
+    this.localRestored = localRestored;
+    this.phase = phase;
+    this.name = "CliCredentialPersistenceError";
+  }
+}
+var getCliStorageError = (error) => {
+  if (error instanceof CliCredentialStoreUnavailableError)
+    return {
+      code: error.code,
+      message: error.message,
+      details: { reason: error.reason }
+    };
+  if (error instanceof CliCredentialPersistenceError)
+    return {
+      code: error.code,
+      message: error.message,
+      details: {
+        remoteRevoked: error.remoteRevoked,
+        localRestored: error.localRestored,
+        phase: error.phase
+      }
+    };
+  return;
+};
+
+// ../../cli-auth/src/client/secret-backend.ts
+var timeoutMs = 1e4;
+var maxBuffer = 64 * 1024;
+var runBackend = (product, executable, args, input, failure) => new Promise((resolve, reject) => {
+  const child = execFile(executable, args, {
+    timeout: timeoutMs,
+    killSignal: "SIGKILL",
+    maxBuffer,
+    windowsHide: true
+  }, (error, stdout, stderr) => {
+    if (error) {
+      const reason = error.code === "ERR_CHILD_PROCESS_STDIO_MAXBUFFER" ? "invalid-response" : error.killed ? "timeout" : classifyCredentialStoreFailure(`${stdout}
+${stderr}`, failure);
+      reject(new CliCredentialStoreUnavailableError(product, reason));
+      return;
+    }
+    resolve(stdout);
+  });
+  child.stdin?.on("error", () => {});
+  child.stdin?.end(input);
+});
+var nativeWorker = `
+try {
+ const { operation, input } = JSON.parse(await Bun.stdin.text());
+ const value = await Bun.secrets[operation](input);
+ process.stdout.write(JSON.stringify({ value: value ?? null }));
+} catch (error) {
+ const message = error instanceof Error ? error.message : "Credential backend failed";
+ // libsecret's bus transport errors can omit the D-Bus context.
+ const context = process.platform === "linux" && /^Could not connect:/i.test(message) ? "D-Bus: " : "";
+ process.stderr.write(context + message);
+ process.exitCode = 1;
 }
-var useSecrets = async (product, operation) => {
+`;
+var nativeResponse = object({ value: union([string2(), boolean2(), _null3()]) }).strict();
+var createIsolatedBunSecrets = (product) => {
+  const run = async (operation, input) => {
+    assertBunRuntime();
+    const output = await runBackend(product, process.execPath, ["--no-env-file", "--eval", nativeWorker], JSON.stringify({ operation, input }), operation === "set" ? "write-failed" : operation === "delete" ? "delete-failed" : "read-failed");
+    try {
+      return nativeResponse.parse(JSON.parse(output)).value;
+    } catch {
+      throw new CliCredentialStoreUnavailableError(product, "invalid-response");
+    }
+  };
+  return {
+    get: async (input) => {
+      const value = await run("get", input);
+      if (value === null || typeof value === "string")
+        return value;
+      throw new CliCredentialStoreUnavailableError(product, "invalid-response");
+    },
+    set: async (input) => {
+      await run("set", input);
+    },
+    delete: async (input) => await run("delete", input) === true
+  };
+};
+
+// ../../cli-auth/src/client/credential-store.ts
+var runSecretOperation = async (product, operation, fallback = "read-failed") => {
   try {
     return await operation();
   } catch (cause) {
     if (cause instanceof CliCredentialStoreUnavailableError)
       throw cause;
-    throw new CliCredentialStoreUnavailableError(product, { cause });
+    throw new CliCredentialStoreUnavailableError(product, classifyCredentialStoreFailure(cause instanceof Error ? cause.message : "", fallback));
   }
 };
-var defaultSecrets = () => {
-  assertBunRuntime();
-  return Bun.secrets;
-};
 var refreshLockTimeoutMs = 5 * 60 * 1000;
 var refreshLockRetryMs = 50;
 var getCredentialLockDirectoryPath = () => {
@@ -6112,18 +6314,38 @@ var acquireRefreshLock = async (path) => {
   }
   throw new Error("Timed out waiting for another CLI process to refresh credentials. Retry the command.");
 };
+var resolveCliCredentialAccount = (environment = process.env) => environment.GO_LABS_CLI_CREDENTIAL_ACCOUNT?.trim() || "default";
 var createBunCredentialStore = ({
-  account = "default",
+  account = resolveCliCredentialAccount(),
   product,
-  secrets = defaultSecrets()
+  secrets = createIsolatedBunSecrets(product)
 }) => {
   const service = `go-labs-cli:${product}`;
   return {
+    preflight: async () => {
+      const input = { name: `probe-${randomUUID()}`, service };
+      const value = `go-labs-non-secret-probe:${randomUUID()}`;
+      try {
+        await runSecretOperation(product, () => secrets.set({ ...input, value }), "write-failed");
+        if (await runSecretOperation(product, () => secrets.get(input)) !== value) {
+          throw new CliCredentialStoreUnavailableError(product, "write-failed");
+        }
+      } catch (error) {
+        await secrets.delete(input).catch(() => {
+          return;
+        });
+        throw error;
+      }
+      await runSecretOperation(product, () => secrets.delete(input), "delete-failed");
+      if (await runSecretOperation(product, () => secrets.get(input)) !== null) {
+        throw new CliCredentialStoreUnavailableError(product, "delete-failed");
+      }
+    },
     delete: async () => {
-      await useSecrets(product, () => secrets.delete({ name: account, service }));
+      await runSecretOperation(product, () => secrets.delete({ name: account, service }), "delete-failed");
     },
     get: async () => {
-      const value = await useSecrets(product, () => secrets.get({ name: account, service }));
+      const value = await runSecretOperation(product, () => secrets.get({ name: account, service }));
       if (value === null)
         return null;
       try {
@@ -6134,11 +6356,11 @@ var createBunCredentialStore = ({
     },
     set: async (credentials) => {
       const parsed = storedCliCredentialsSchema.parse(credentials);
-      await useSecrets(product, () => secrets.set({
+      await runSecretOperation(product, () => secrets.set({
         name: account,
         service,
         value: JSON.stringify(parsed)
-      }));
+      }), "write-failed");
     },
     withCredentialLock: async (operation) => {
       const refreshLockPath = await getCredentialLockPath(product, account);
@@ -6159,6 +6381,7 @@ var createBunCredentialStore = ({
 };
 // ../../cli-auth/src/client/login.ts
 import { hostname } from "os";
+import { isDeepStrictEqual } from "util";
 var normalizeCliAuthIssuer = (value) => {
   const url = new URL(value);
   url.hash = "";
@@ -6221,12 +6444,15 @@ var openSystemBrowser = async (url) => {
     "-NoProfile",
     "-NonInteractive",
     "-Command",
-    "Start-Process -FilePath $args[0]",
-    url
+    "Start-Process -FilePath $env:GO_LABS_CLI_VERIFICATION_URI -ErrorAction Stop"
   ] : ["xdg-open", url];
   try {
-    const process2 = Bun.spawn(command, { stderr: "ignore", stdout: "ignore" });
-    return await process2.exited === 0;
+    const browserProcess = Bun.spawn(command, {
+      env: process.platform === "win32" ? { ...process.env, GO_LABS_CLI_VERIFICATION_URI: url } : process.env,
+      stderr: "ignore",
+      stdout: "ignore"
+    });
+    return await browserProcess.exited === 0;
   } catch {
     return false;
   }
@@ -6244,6 +6470,8 @@ var loginWithBrowser = async ({
   store
 }) => {
   const baseUrl = normalizeCliAuthIssuer(apiBaseUrl);
+  if (store.preflight)
+    await withCredentialLock(store, () => store.preflight?.() ?? Promise.resolve());
   const pkce = createPkcePair();
   const beginResponse = await postJson(fetchImplementation, `${baseUrl}/api/cli-auth/device`, {
     clientName,
@@ -6271,7 +6499,19 @@ var loginWithBrowser = async ({
     if (response.ok) {
       const issued = tokenResponseSchema.parse(payload);
       const credentials = toStoredCredentials(issued, baseUrl, now());
-      await withCredentialLock(store, () => store.set(credentials));
+      try {
+        await withCredentialLock(store, () => persistIssuedCredentials({
+          store,
+          credentials,
+          apiBaseUrl: baseUrl,
+          fetch: fetchImplementation,
+          phase: "login"
+        }));
+      } catch (error) {
+        if (error instanceof CliCredentialPersistenceError)
+          throw error;
+        throw new CliCredentialPersistenceError(await revokeIssuedCredentials(fetchImplementation, baseUrl, credentials), false, "login");
+      }
       return credentials;
     }
     const error = deviceTokenErrorSchema.safeParse(payload);
@@ -6291,6 +6531,55 @@ var loginWithBrowser = async ({
   }
   throw new Error("CLI authentication expired. Run auth login again.");
 };
+var revokeIssuedCredentials = async (fetchImplementation, apiBaseUrl, credentials) => {
+  try {
+    const response = await postJson(fetchImplementation, `${normalizeCliAuthIssuer(apiBaseUrl)}/api/cli-auth/revoke`, { refreshToken: credentials.refreshToken }, { signal: AbortSignal.timeout(refreshRequestTimeoutMs) });
+    return response.ok;
+  } catch {
+    return false;
+  }
+};
+var persistIssuedCredentials = async ({
+  store,
+  credentials,
+  previous,
+  apiBaseUrl,
+  fetch: fetchImplementation,
+  phase
+}) => {
+  let prior = previous;
+  try {
+    if (phase === "login")
+      prior = await store.get();
+    await store.set(credentials);
+    const saved = await store.get();
+    if (!isDeepStrictEqual(saved, credentials))
+      throw new Error("Credential write could not be verified");
+    return;
+  } catch {
+    const remoteRevoked = await revokeIssuedCredentials(fetchImplementation, apiBaseUrl, credentials);
+    let localRestored = false;
+    try {
+      const current = await store.get();
+      if (phase === "login" && prior !== undefined) {
+        if (isDeepStrictEqual(current, prior))
+          localRestored = true;
+        else if (current === null || current.refreshToken === credentials.refreshToken) {
+          if (prior)
+            await store.set(prior);
+          else
+            await store.delete();
+          localRestored = isDeepStrictEqual(await store.get(), prior);
+        }
+      } else if (phase === "refresh" && (!current || current.refreshToken === credentials.refreshToken || current.refreshToken === prior?.refreshToken)) {
+        if (current)
+          await store.delete();
+        localRestored = await store.get() === null;
+      }
+    } catch {}
+    throw new CliCredentialPersistenceError(remoteRevoked, localRestored, phase);
+  }
+};
 var refreshes = new WeakMap;
 var refreshRequestTimeoutMs = 30000;
 var isInvalidGrantResponse = (payload) => {
@@ -6345,7 +6634,14 @@ var refreshAccessToken = async ({
     throw new Error("Unable to refresh the CLI session because the API returned invalid credentials. Credentials were kept; retry the command.");
   }
   const stored = toStoredCredentials(issued, normalizeCliAuthIssuer(apiBaseUrl), now());
-  await store.set(stored);
+  await persistIssuedCredentials({
+    store,
+    credentials: stored,
+    previous: credentials,
+    apiBaseUrl,
+    fetch: fetchImplementation,
+    phase: "refresh"
+  });
   return stored.accessToken;
 };
 var refreshWithCurrentCredentials = async ({
@@ -6901,6 +7197,9 @@ var isNetworkError = (error, depth = 0) => {
   return isNetworkError(error.cause, depth + 1);
 };
 var normalizeCliError = (error) => {
+  const storageError = getCliStorageError(error);
+  if (storageError)
+    return storageError;
   if (error instanceof CliRuntimeError) {
     return {
       code: error.code,
@@ -8208,10 +8507,12 @@ var MAX_ASANA_LEAD_CANDIDATES = 5;
 var ASANA_SEARCH_DETAIL_LIMIT = 15;
 var NOTIFICATION_PAGE_LIMIT = 50;
 var getAllNotifications = async () => {
+  const user = await api2.user.getCurrentUser.query();
   const notifications = [];
   let cursor;
   do {
-    const page = await api2.budget.getNotifications.query({
+    const page = await api2.budget.getNotificationPage.query({
+      cacheUserId: user.id,
       cursor,
       limit: NOTIFICATION_PAGE_LIMIT
     });
@@ -9267,12 +9568,30 @@ async function getBudgetCategories() {
   const categories = await api2.budget.getBudgetCategories.query();
   out(categories);
 }
-async function getBudgetVersions(budgetId) {
-  const versions = await api2.budgetVersion.getBudgetVersions.query({
-    budgetId
-  });
-  out(versions);
-}
+var getBudgetVersions = async (budgetId, options = {}) => {
+  if (options.all && options.cursor !== undefined) {
+    throw new CliRuntimeError("USAGE", "--all cannot be combined with --cursor.");
+  }
+  const versions = [];
+  const seenCursors = new Set;
+  let cursor = options.cursor;
+  do {
+    const page = await api2.budgetVersion.getBudgetVersionsPage.query({
+      budgetId,
+      limit: options.limit,
+      cursor
+    });
+    versions.push(...page.versions);
+    cursor = page.nextCursor;
+    if (!options.all || cursor === undefined)
+      break;
+    if (seenCursors.has(cursor)) {
+      throw new Error("Budget history pagination did not advance; export aborted.");
+    }
+    seenCursors.add(cursor);
+  } while (cursor !== undefined);
+  out({ versions, nextCursor: cursor ?? null });
+};
 async function createBudgetApproval(budgetId, preflight) {
   await assertSensitiveWorkflowConfirmed({
     action: "Create budget approval request",
@@ -10292,13 +10611,16 @@ async function listContacts(companyId) {
   out(contacts);
 }
 async function listItems(opts) {
-  const result = await api2.item.getItems.query({
+  const filters = {
     includeQuickBooksDeactivationPending: opts.includeQuickBooksDeactivationPending,
-    page: opts.page ?? 1,
-    perPage: opts.perPage ?? 20,
     name: opts.name
-  });
-  out(result);
+  };
+  const perPage = opts.perPage ?? 20;
+  const [items, { total, counts }] = await Promise.all([
+    api2.item.getItems.query({ ...filters, page: opts.page ?? 1, perPage }),
+    api2.item.getItemCounts.query(filters)
+  ]);
+  out({ items, pageCount: Math.ceil(total / perPage), counts });
 }
 async function getItem(id) {
   const item = await api2.item.getItem.query({ id });
@@ -11033,7 +11355,20 @@ var registry2 = [
     }
   ]),
   legacyCommand("get-budget-categories", ["budget", "category", "list"]),
-  legacyCommand("get-budget-versions", ["budget", "version", "list"]),
+  legacyCommand("get-budget-versions", ["budget", "version", "list"], [], [
+    {
+      name: "--limit <1-50>",
+      description: "Versions per page (default 20). Returns versions and nextCursor, not a full-history array."
+    },
+    {
+      name: "--cursor <versionId>",
+      description: "Load the next page using the previous nextCursor; null means complete."
+    },
+    {
+      name: "--all",
+      description: "Explicitly fetch all visible history in bounded pages; cannot combine with --cursor. May be expensive."
+    }
+  ]),
   legacyCommand("rename-budget-version", ["budget", "version", "rename"]),
   legacyCommand("restore-budget-version", ["budget", "version", "restore"]),
   legacyCommand("update-budget-status", ["budget", "status", "update"]),
@@ -11469,9 +11804,12 @@ var resolveCommand = (argv) => {
     isLegacyAlias: true
   };
 };
+var updateBeforeUse = "First step before each task: update to the latest published release with 'bun add --global @go-labs-sg/bb@latest', then run 'bb version' and 'bb --help' before using commands. Update once per task. If updating fails, stop and report it. Preserve an explicitly requested pinned or development/staging version.";
 var createHumanHelp = (command) => {
   if (command) {
     return [
+      updateBeforeUse,
+      "",
       `Usage: bb ${command.path.join(" ")} [options] [args]`,
       "",
       command.summary,
@@ -11496,6 +11834,8 @@ var createHumanHelp = (command) => {
   return [
     "bb \u2014 Budget Builder CLI",
     "",
+    updateBeforeUse,
+    "",
     "Usage: bb <resource> <operation> [options] [args]",
     "",
     "Global options",
@@ -11691,6 +12031,8 @@ function printLegacyHelp(runtime) {
   const help = `
 bb \u2014 Budget Builder CLI for AI agents (parity with MCP tools)
 
+First step before each task: update to the latest published release with 'bun add --global @go-labs-sg/bb@latest', then run 'bb version' and 'bb --help' before using commands. Update once per task. If updating fails, stop and report it. Preserve an explicitly requested pinned or development/staging version.
+
 Usage: bb <command> [options] [args]
 
 Identity: bb version \u2014 print the installed CLI package version and API target as JSON.
@@ -11723,7 +12065,7 @@ Budgets
   get-budget-items <id>      Line items only
   get-budget-details <id>    Full detail (margins, suppliers, etc.)
   get-budget-categories
-  get-budget-versions <budgetId>
+  get-budget-versions <budgetId> [--limit <1-50>] [--cursor <versionId> | --all]
   rename-budget-version <versionId> --name <text>
   restore-budget-version <versionId>   Replace current budget data and return it to DRAFT.
   update-budget-status <id> <status> [--projectManagerId <id>] [--markProjectWon true|false] [--projectStatusOnCommercialRejection PITCH|LOST]
@@ -11760,6 +12102,7 @@ Budgets
 Bills
   list-bills                 [--projectId] [--budgetId] [--status CSV] [--search <text>] [--isClaimable true|false] [--createdByIds <csv>] [--sortBy createdAt|amount|status] [--sortDir asc|desc] [--page] [--pageSize]
   list-claims                same flags as list-bills; only reimbursable claims (ignores --isClaimable)
+                            Both lists return summaries; use get-bill-details <billId> for full detail.
     isClaimable differentiates the shared bill/claim records: false = bill, true = claim.
   Create supplier bills from approved quotations from the same supplier and project. Use quotationAllocations plus lineAmounts when quotations split one bill line. Eligible exemptions require explicit --quotation-exempt intent; claims do not consume or link quotations.
   Amounts for create/update (including drafts) exclude GST: amount = portion billed; extractedAmount = full invoice subtotal; lineAmounts[].amount and quotationAllocations[].amount also exclude GST. The CLI does not strip GST from input.
@@ -12139,7 +12482,10 @@ async function runCli(argv = process.argv, runtime = createProcessRuntime(), cre
       if (commandArgv.length !== 2) {
         throw new CliRuntimeError("USAGE", `auth ${authAction} accepts no positional arguments.`);
       }
-      const store = credentialStore ?? createBunCredentialStore({ product: "budget-builder" });
+      const store = credentialStore ?? createBunCredentialStore({
+        account: resolveCliCredentialAccount(runtime.env),
+        product: "budget-builder"
+      });
       if (authAction === "login") {
         const credentials = await loginWithBrowser({
           apiBaseUrl: BUDGET_BUILDER_API_BASE_URL,
@@ -12255,9 +12601,14 @@ Waiting for approval\u2026
       try {
         accessToken = await getAuthenticatedAccessToken({
           apiBaseUrl: BUDGET_BUILDER_API_BASE_URL,
-          store: credentialStore ?? createBunCredentialStore({ product: "budget-builder" })
+          store: credentialStore ?? createBunCredentialStore({
+            account: resolveCliCredentialAccount(runtime.env),
+            product: "budget-builder"
+          })
         });
       } catch (error) {
+        if (getCliStorageError(error))
+          throw error;
         throw new CliRuntimeError("AUTHENTICATION", error instanceof Error ? error.message : "Not authenticated. Run bb auth login first.");
       }
       configureAccessToken(accessToken);
@@ -12348,7 +12699,18 @@ Waiting for approval\u2026
         const id = positional[0];
         if (!id)
           throw new Error("get-budget-versions requires <budgetId>");
-        await getBudgetVersions(id);
+        const limit = flags.limit === undefined ? undefined : Number(flags.limit);
+        if (flags.limit === true || limit !== undefined && (!Number.isInteger(limit) || limit < 1 || limit > 50)) {
+          throw new CliRuntimeError("USAGE", "--limit must be an integer from 1 to 50.");
+        }
+        if (flags.cursor === true || flags.cursor === "") {
+          throw new CliRuntimeError("USAGE", "--cursor requires a non-empty version ID.");
+        }
+        await getBudgetVersions(id, {
+          limit,
+          cursor: flags.cursor,
+          all: flags.all === true || (parseOptionalBoolFlag(flags, "all") ?? false)
+        });
         break;
       }
       case "rename-budget-version": {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@go-labs-sg/bb",
-  "version": "2.45.1",
+  "version": "2.47.0",
   "description": "Budget Builder CLI for AI agents — manage budgets, bills, claims, quotations, and customer invoices with explicit workflow previews for sensitive changes.",
   "type": "module",
   "main": "./dist/index.js",