switchroom 0.17.5 → 0.17.6

package/dist/agent-scheduler/index.js

@@ -11591,7 +11591,7 @@ var SwitchroomConfigSchema = exports_external.object({
       name: exports_external.string().regex(/^[a-zA-Z0-9][a-zA-Z0-9_-]*$/, {
         message: "Consumer name must be a path-safe slug (letters, digits, underscore, hyphen)"
       }).describe("Socket-path identity; binds at /run/switchroom/auth-broker/<name>/sock"),
-      account: exports_external.string().min(1).describe("Pinned account label for this consumer. `get-credentials` returns " + "this account's credentials; `mark-exhausted` from this consumer " + "only affects this account."),
+      account: exports_external.string().min(1).optional().describe("Optional pinned account label for this consumer. When set, " + "`get-credentials` serves this account (with automatic failover " + "while it is quota-exhausted) and `mark-exhausted` from this " + "consumer attributes to it — use a pin for quota isolation. " + "When omitted, the consumer follows the fleet `auth.active` " + "exactly like an agent: same account swaps, same failover."),
       uid: exports_external.number().int().nonnegative().optional().describe("Optional UID to chown the consumer socket to (defaults to 0 = root, " + "suitable for sibling containers running as root)."),
       mirror_dir: exports_external.string().optional().describe("Optional host-side directory path. When set, the broker actively " + "writes the consumer's effective-account `.credentials.json` mirror " + "here — in addition to serving creds on demand via `get-credentials`. " + "Use this to eliminate the pull-latency gap: without a mirror the " + "consumer only gets failover creds at its next scheduled re-fetch " + "(up to 30 min). With a mirror the broker pushes failover creds " + "immediately when it detects exhaustion (consumer-quota-sensor tick, " + "or a mark-exhausted RPC on the pinned account). The directory must " + "be accessible to the broker container (bind-mounted from the host) " + "and to the consumer container; the broker writes " + "`<mirror_dir>/.credentials.json` atomically. Chown is attempted to " + "`uid` (default 0) — swallowed when CAP_CHOWN is absent.")
     })).optional().describe("Non-agent peers that hold a broker socket (RFC H §4.8). Each gets " + "its own `/run/switchroom/auth-broker/<name>/sock` chowned to its UID. " + "Consumers cannot be admins; a consumer name that collides with an " + "agent (whether that agent has `admin: true` or not) is a config " + "error caught at schema validation."),

package/dist/auth-broker/index.js

@@ -11591,7 +11591,7 @@ var SwitchroomConfigSchema = exports_external.object({
       name: exports_external.string().regex(/^[a-zA-Z0-9][a-zA-Z0-9_-]*$/, {
         message: "Consumer name must be a path-safe slug (letters, digits, underscore, hyphen)"
       }).describe("Socket-path identity; binds at /run/switchroom/auth-broker/<name>/sock"),
-      account: exports_external.string().min(1).describe("Pinned account label for this consumer. `get-credentials` returns " + "this account's credentials; `mark-exhausted` from this consumer " + "only affects this account."),
+      account: exports_external.string().min(1).optional().describe("Optional pinned account label for this consumer. When set, " + "`get-credentials` serves this account (with automatic failover " + "while it is quota-exhausted) and `mark-exhausted` from this " + "consumer attributes to it — use a pin for quota isolation. " + "When omitted, the consumer follows the fleet `auth.active` " + "exactly like an agent: same account swaps, same failover."),
       uid: exports_external.number().int().nonnegative().optional().describe("Optional UID to chown the consumer socket to (defaults to 0 = root, " + "suitable for sibling containers running as root)."),
       mirror_dir: exports_external.string().optional().describe("Optional host-side directory path. When set, the broker actively " + "writes the consumer's effective-account `.credentials.json` mirror " + "here — in addition to serving creds on demand via `get-credentials`. " + "Use this to eliminate the pull-latency gap: without a mirror the " + "consumer only gets failover creds at its next scheduled re-fetch " + "(up to 30 min). With a mirror the broker pushes failover creds " + "immediately when it detects exhaustion (consumer-quota-sensor tick, " + "or a mark-exhausted RPC on the pinned account). The directory must " + "be accessible to the broker container (bind-mounted from the host) " + "and to the consumer container; the broker writes " + "`<mirror_dir>/.credentials.json` atomically. Chown is attempted to " + "`uid` (default 0) — swallowed when CAP_CHOWN is absent.")
     })).optional().describe("Non-agent peers that hold a broker socket (RFC H §4.8). Each gets " + "its own `/run/switchroom/auth-broker/<name>/sock` chowned to its UID. " + "Consumers cannot be admins; a consumer name that collides with an " + "agent (whether that agent has `admin: true` or not) is a config " + "error caught at schema validation."),
@@ -13910,10 +13910,12 @@ class AuthBroker {
   refreshInFlight = new Set;
   consumerLastSeen = {};
   capChownWarned = false;
+  yamlActive;
   closed = false;
   constructor(config, opts = {}) {
     this.opts = opts;
     this.config = config;
+    this.yamlActive = config.auth?.active;
     this.home = opts.home;
     this.now = opts.now ?? nowMs;
     this.operatorUid = opts.operatorUid;
@@ -14040,6 +14042,8 @@ class AuthBroker {
     this.assertConfigConsistent(config);
     const prev = this.config;
     this.config = config;
+    this.yamlActive = config.auth?.active;
+    this.applyActiveOverride();
     const wanted = new Set;
     for (const name of Object.keys(config.agents ?? {})) {
       wanted.add(this.agentSocketPath(name));
@@ -14331,7 +14335,9 @@ class AuthBroker {
       return auth.active ?? null;
     if (identity2.kind === "consumer") {
       const c = (auth.consumers ?? []).find((x) => x.name === identity2.name);
-      return c?.account ?? null;
+      if (!c)
+        return null;
+      return c.account ?? auth.active ?? null;
     }
     const agent = (this.config.agents ?? {})[identity2.name];
     const override = agent?.auth?.override;
@@ -14475,7 +14481,7 @@ class AuthBroker {
     });
     const consumers = (auth.consumers ?? []).map((c) => ({
       name: c.name,
-      account: c.account,
+      account: c.account ?? auth.active ?? "",
       last_seen_at: this.consumerLastSeen[c.name] ?? null
     }));
     const active_overage_serving = this.isActiveOverageServing(this.callerAccount(identity2));
@@ -14594,10 +14600,20 @@ class AuthBroker {
         continue;
       }
       this.cacheQuotaSnapshot(label, result);
+      const active = this.config.auth?.active;
+      if (label !== active)
+        continue;
+      const decision = quotaIndicatesExhaustion(result, this.isOverageAllowed(label));
+      if (!decision.exhausted)
+        continue;
+      process.stdout.write(`auth-broker: fleet-quota-probe shows ACTIVE ${label} exhausted — proactive failover
+`);
+      this.audit({ op: "mark-exhausted", identity: { kind: "operator" }, account: label, accountKind: "claude", ok: true });
+      await this.markExhaustedAndRoll(label, decision.until ?? undefined, { kind: "operator" });
     }
   }
   async consumerQuotaProbeTick() {
-    const accounts = Array.from(new Set((this.config.auth?.consumers ?? []).map((c) => c.account)));
+    const accounts = Array.from(new Set((this.config.auth?.consumers ?? []).map((c) => c.account).filter((a) => typeof a === "string" && a.length > 0)));
     for (const label of accounts) {
       const creds = readAccountCredentials(label, this.home);
       const token = creds?.claudeAiOauth?.accessToken;
@@ -14654,6 +14670,7 @@ class AuthBroker {
       auth: { ...this.config.auth ?? {}, active: account }
     };
     this.config = cfg;
+    this.persistActiveOverride(account);
     const fanned = this.fanoutToAffectedAgents(account);
     this.fanoutAllConsumers();
     this.audit({ op: "set-active", identity: identity2, account, accountKind: "claude", ok: true });
@@ -14666,6 +14683,11 @@ class AuthBroker {
       socket.write(encodeError(id, "ACCOUNT_NOT_FOUND", "no active account configured"));
       return;
     }
+    const { rolled, rolledTo } = await this.markExhaustedAndRoll(account, until, identity2);
+    this.audit({ op: "mark-exhausted", identity: identity2, account, accountKind: "claude", ok: true });
+    socket.write(encodeSuccess(id, { account, rolled, rolledTo }));
+  }
+  async markExhaustedAndRoll(account, until, identity2) {
     const now = this.now();
     const exhaustedUntil = clampMarkExpiry({
       proposedUntil: until ?? now + MARK_EXHAUSTED_DEFAULT_MS,
@@ -14678,8 +14700,26 @@ class AuthBroker {
     const rolledTo = await this.nextHealthyAccountLive(account, this.config.auth?.fallback_order ?? []);
     const rolled = this.fanoutFailoverTo(account, rolledTo);
     this.fanoutToAffectedConsumers(account);
-    this.audit({ op: "mark-exhausted", identity: identity2, account, accountKind: "claude", ok: true });
-    socket.write(encodeSuccess(id, { account, rolled, rolledTo }));
+    if (rolledTo && this.config.auth?.active === account && this.exhaustionLiveCorroborated(account)) {
+      this.config = {
+        ...this.config,
+        auth: { ...this.config.auth ?? {}, active: rolledTo }
+      };
+      this.persistActiveOverride(rolledTo);
+      this.fanoutAllConsumers();
+      this.audit({ op: "auto-promote-active", identity: identity2, account: rolledTo, accountKind: "claude", ok: true });
+      process.stdout.write(`auth-broker: auto-promoted auth.active ${account} → ${rolledTo} ` + `(${account} exhausted until ${new Date(exhaustedUntil).toISOString()}) — persisted
+`);
+    }
+    return { rolled, rolledTo };
+  }
+  exhaustionLiveCorroborated(account) {
+    const snapshot = this.lastQuotaCache[account];
+    if (!snapshot || !snapshotFresh(snapshot, this.now(), MARK_EXHAUSTED_DEFAULT_MS))
+      return false;
+    if (!snapshotWalled(snapshot))
+      return false;
+    return !overageLiftsWall(snapshot, this.isOverageAllowed(account));
   }
   opClaimNotification(socket, id, identity2, key, windowMs) {
     const now = this.now();
@@ -15187,12 +15227,15 @@ class AuthBroker {
     for (const consumer of this.config.auth?.consumers ?? []) {
       if (!consumer.mirror_dir)
         continue;
-      const isPinned = consumer.account === label;
+      const bound = consumer.account ?? this.config.auth?.active;
+      const isPinned = bound === label;
       const effective = this.servingAccountForConsumer(consumer.name);
       const isEffective = effective === label;
       if (!isPinned && !isEffective)
         continue;
-      const toMirror = effective ?? consumer.account;
+      const toMirror = effective ?? bound;
+      if (toMirror == null)
+        continue;
       if (this.mirrorAccountToConsumer(toMirror, consumer)) {
         fanned.push(consumer.name);
       }
@@ -15216,7 +15259,7 @@ class AuthBroker {
     const c = (this.config.auth?.consumers ?? []).find((x) => x.name === name);
     if (!c)
       return null;
-    return this.accountWithFailover(c.account);
+    return this.accountWithFailover(c.account ?? this.config.auth?.active);
   }
   mirrorAccountToConsumer(label, consumer) {
     const mirrorDir = consumer.mirror_dir;
@@ -15362,6 +15405,42 @@ class AuthBroker {
     this.thresholdViolations = this.readJson("threshold-violations.json") ?? {};
     this.notificationClaims = this.readJson("notification-claims.json") ?? {};
     this.lastQuotaCache = this.readJson("last-quota.json") ?? {};
+    this.applyActiveOverride();
+  }
+  applyActiveOverride() {
+    const ov = this.readJson("active-override.json");
+    if (!ov || typeof ov.active !== "string" || ov.active.length === 0)
+      return;
+    const yamlActive = this.yamlActive ?? null;
+    if ((ov.yaml_active_at_write ?? null) !== yamlActive) {
+      process.stdout.write(`auth-broker: active-override dropped — yaml auth.active changed since the swap ` + `(${ov.yaml_active_at_write ?? "unset"} → ${yamlActive ?? "unset"}); yaml wins
+`);
+      try {
+        unlinkSync(join4(this.stateDir, "active-override.json"));
+      } catch {}
+      return;
+    }
+    if (!accountExists(ov.active, this.home)) {
+      process.stdout.write(`auth-broker: active-override ignored — account '${ov.active}' not found on disk
+`);
+      return;
+    }
+    if (ov.active === this.config.auth?.active)
+      return;
+    this.config = {
+      ...this.config,
+      auth: { ...this.config.auth ?? {}, active: ov.active }
+    };
+    process.stdout.write(`auth-broker: active-override applied — auth.active ${yamlActive ?? "unset"} → ${ov.active} ` + `(persisted swap survives restarts)
+`);
+  }
+  persistActiveOverride(active) {
+    const entry = {
+      active,
+      yaml_active_at_write: this.yamlActive ?? null,
+      updated_at: this.now()
+    };
+    atomicWriteJsonSync(join4(this.stateDir, "active-override.json"), entry, 384);
   }
   readJson(name) {
     const p = join4(this.stateDir, name);

package/dist/cli/notion-write-pretool.mjs

@@ -12339,7 +12339,7 @@ var SwitchroomConfigSchema = exports_external.object({
       name: exports_external.string().regex(/^[a-zA-Z0-9][a-zA-Z0-9_-]*$/, {
         message: "Consumer name must be a path-safe slug (letters, digits, underscore, hyphen)"
       }).describe("Socket-path identity; binds at /run/switchroom/auth-broker/<name>/sock"),
-      account: exports_external.string().min(1).describe("Pinned account label for this consumer. `get-credentials` returns " + "this account's credentials; `mark-exhausted` from this consumer " + "only affects this account."),
+      account: exports_external.string().min(1).optional().describe("Optional pinned account label for this consumer. When set, " + "`get-credentials` serves this account (with automatic failover " + "while it is quota-exhausted) and `mark-exhausted` from this " + "consumer attributes to it \u2014 use a pin for quota isolation. " + "When omitted, the consumer follows the fleet `auth.active` " + "exactly like an agent: same account swaps, same failover."),
       uid: exports_external.number().int().nonnegative().optional().describe("Optional UID to chown the consumer socket to (defaults to 0 = root, " + "suitable for sibling containers running as root)."),
       mirror_dir: exports_external.string().optional().describe("Optional host-side directory path. When set, the broker actively " + "writes the consumer's effective-account `.credentials.json` mirror " + "here \u2014 in addition to serving creds on demand via `get-credentials`. " + "Use this to eliminate the pull-latency gap: without a mirror the " + "consumer only gets failover creds at its next scheduled re-fetch " + "(up to 30 min). With a mirror the broker pushes failover creds " + "immediately when it detects exhaustion (consumer-quota-sensor tick, " + "or a mark-exhausted RPC on the pinned account). The directory must " + "be accessible to the broker container (bind-mounted from the host) " + "and to the consumer container; the broker writes " + "`<mirror_dir>/.credentials.json` atomically. Chown is attempted to " + "`uid` (default 0) \u2014 swallowed when CAP_CHOWN is absent.")
     })).optional().describe("Non-agent peers that hold a broker socket (RFC H \u00a74.8). Each gets " + "its own `/run/switchroom/auth-broker/<name>/sock` chowned to its UID. " + "Consumers cannot be admins; a consumer name that collides with an " + "agent (whether that agent has `admin: true` or not) is a config " + "error caught at schema validation."),

package/dist/cli/switchroom.js

@@ -14177,7 +14177,7 @@ var init_schema = __esm(() => {
         name: exports_external.string().regex(/^[a-zA-Z0-9][a-zA-Z0-9_-]*$/, {
           message: "Consumer name must be a path-safe slug (letters, digits, underscore, hyphen)"
         }).describe("Socket-path identity; binds at /run/switchroom/auth-broker/<name>/sock"),
-        account: exports_external.string().min(1).describe("Pinned account label for this consumer. `get-credentials` returns " + "this account's credentials; `mark-exhausted` from this consumer " + "only affects this account."),
+        account: exports_external.string().min(1).optional().describe("Optional pinned account label for this consumer. When set, " + "`get-credentials` serves this account (with automatic failover " + "while it is quota-exhausted) and `mark-exhausted` from this " + "consumer attributes to it \u2014 use a pin for quota isolation. " + "When omitted, the consumer follows the fleet `auth.active` " + "exactly like an agent: same account swaps, same failover."),
         uid: exports_external.number().int().nonnegative().optional().describe("Optional UID to chown the consumer socket to (defaults to 0 = root, " + "suitable for sibling containers running as root)."),
         mirror_dir: exports_external.string().optional().describe("Optional host-side directory path. When set, the broker actively " + "writes the consumer's effective-account `.credentials.json` mirror " + "here \u2014 in addition to serving creds on demand via `get-credentials`. " + "Use this to eliminate the pull-latency gap: without a mirror the " + "consumer only gets failover creds at its next scheduled re-fetch " + "(up to 30 min). With a mirror the broker pushes failover creds " + "immediately when it detects exhaustion (consumer-quota-sensor tick, " + "or a mark-exhausted RPC on the pinned account). The directory must " + "be accessible to the broker container (bind-mounted from the host) " + "and to the consumer container; the broker writes " + "`<mirror_dir>/.credentials.json` atomically. Chown is attempted to " + "`uid` (default 0) \u2014 swallowed when CAP_CHOWN is absent.")
       })).optional().describe("Non-agent peers that hold a broker socket (RFC H \u00a74.8). Each gets " + "its own `/run/switchroom/auth-broker/<name>/sock` chowned to its UID. " + "Consumers cannot be admins; a consumer name that collides with an " + "agent (whether that agent has `admin: true` or not) is a config " + "error caught at schema validation."),
@@ -43431,7 +43431,7 @@ function checkHindsightConsumer(config, opts) {
     return {
       name: "hindsight consumer",
       status: "warn",
-      detail: `auth.consumers[hindsight] -> ${entry.account} (uid ${entry.uid ?? 0}); ` + `couldn't query auth-broker container (not running / docker unavailable)`,
+      detail: `auth.consumers[hindsight] -> ${entry.account ?? "(follows active)"} (uid ${entry.uid ?? 0}); ` + `couldn't query auth-broker container (not running / docker unavailable)`,
       fix: "Check `auth-broker: service health` row above; if the broker is " + "down, `switchroom apply` will bring it back and bind the socket."
     };
   }
@@ -43439,14 +43439,14 @@ function checkHindsightConsumer(config, opts) {
     return {
       name: "hindsight consumer",
       status: "warn",
-      detail: `auth.consumers[hindsight] -> ${entry.account} (uid ${entry.uid ?? 0}); ` + `auth-broker is running but socket not bound at /run/switchroom/auth-broker/${entry.name}/sock`,
+      detail: `auth.consumers[hindsight] -> ${entry.account ?? "(follows active)"} (uid ${entry.uid ?? 0}); ` + `auth-broker is running but socket not bound at /run/switchroom/auth-broker/${entry.name}/sock`,
       fix: "Run `switchroom apply` to refresh compose and rebind per-consumer sockets."
     };
   }
   return {
     name: "hindsight consumer",
     status: "ok",
-    detail: `auth.consumers[hindsight] -> ${entry.account} (uid ${entry.uid ?? 0})`
+    detail: `auth.consumers[hindsight] -> ${entry.account ?? "(follows active)"} (uid ${entry.uid ?? 0})`
   };
 }
 function probeAuthBrokerSocket(consumerName) {
@@ -63737,8 +63737,8 @@ import { existsSync, readFileSync } from "node:fs";
 import { dirname, join } from "node:path";
 
 // src/build-info.ts
-var VERSION = "0.17.5";
-var COMMIT_SHA = "aae03307";
+var VERSION = "0.17.6";
+var COMMIT_SHA = "0cc74c23";
 
 // src/cli/resolve-version.ts
 function readPackageVersion() {
@@ -77748,7 +77748,8 @@ async function ensureHindsightConsumer(configPath, account, uid = HINDSIGHT_DEFA
   }
   const entry = new YAMLMap;
   entry.set("name", HINDSIGHT_CONSUMER_NAME);
-  entry.set("account", account);
+  if (account !== undefined)
+    entry.set("account", account);
   entry.set("uid", uid);
   consumersNode.add(entry);
   const out = String(doc);
@@ -82886,14 +82887,11 @@ async function stepMemoryBackend(config, nonInteractive, switchroomConfigPath) {
       }
     }
   } catch {}
-  const activeAccount = config.auth?.active;
-  if (!activeAccount) {
-    console.log(source_default.yellow(`  No auth.active account set \u2014 skipping consumer registration. ` + `Run \`switchroom auth use <label>\` and re-run setup.`));
-  } else {
+  {
     try {
-      const result = await ensureHindsightConsumer(switchroomConfigPath, activeAccount);
+      const result = await ensureHindsightConsumer(switchroomConfigPath);
       if (result.added) {
-        console.log(source_default.green(`  ${STEP_DONE} Registered auth.consumers[${HINDSIGHT_CONSUMER_NAME}] = ${activeAccount}`));
+        console.log(source_default.green(`  ${STEP_DONE} Registered auth.consumers[${HINDSIGHT_CONSUMER_NAME}] (follows the fleet active account)`));
       } else {
         console.log(source_default.gray(`  auth.consumers[${HINDSIGHT_CONSUMER_NAME}] already present.`));
       }

package/dist/host-control/main.js

@@ -16371,7 +16371,7 @@ var SwitchroomConfigSchema = exports_external.object({
       name: exports_external.string().regex(/^[a-zA-Z0-9][a-zA-Z0-9_-]*$/, {
         message: "Consumer name must be a path-safe slug (letters, digits, underscore, hyphen)"
       }).describe("Socket-path identity; binds at /run/switchroom/auth-broker/<name>/sock"),
-      account: exports_external.string().min(1).describe("Pinned account label for this consumer. `get-credentials` returns " + "this account's credentials; `mark-exhausted` from this consumer " + "only affects this account."),
+      account: exports_external.string().min(1).optional().describe("Optional pinned account label for this consumer. When set, " + "`get-credentials` serves this account (with automatic failover " + "while it is quota-exhausted) and `mark-exhausted` from this " + "consumer attributes to it — use a pin for quota isolation. " + "When omitted, the consumer follows the fleet `auth.active` " + "exactly like an agent: same account swaps, same failover."),
       uid: exports_external.number().int().nonnegative().optional().describe("Optional UID to chown the consumer socket to (defaults to 0 = root, " + "suitable for sibling containers running as root)."),
       mirror_dir: exports_external.string().optional().describe("Optional host-side directory path. When set, the broker actively " + "writes the consumer's effective-account `.credentials.json` mirror " + "here — in addition to serving creds on demand via `get-credentials`. " + "Use this to eliminate the pull-latency gap: without a mirror the " + "consumer only gets failover creds at its next scheduled re-fetch " + "(up to 30 min). With a mirror the broker pushes failover creds " + "immediately when it detects exhaustion (consumer-quota-sensor tick, " + "or a mark-exhausted RPC on the pinned account). The directory must " + "be accessible to the broker container (bind-mounted from the host) " + "and to the consumer container; the broker writes " + "`<mirror_dir>/.credentials.json` atomically. Chown is attempted to " + "`uid` (default 0) — swallowed when CAP_CHOWN is absent.")
     })).optional().describe("Non-agent peers that hold a broker socket (RFC H §4.8). Each gets " + "its own `/run/switchroom/auth-broker/<name>/sock` chowned to its UID. " + "Consumers cannot be admins; a consumer name that collides with an " + "agent (whether that agent has `admin: true` or not) is a config " + "error caught at schema validation."),
@@ -22670,7 +22670,7 @@ import { existsSync as existsSync6, readFileSync as readFileSync4 } from "node:f
 import { dirname as dirname4, join as join2 } from "node:path";
 
 // src/build-info.ts
-var VERSION = "0.17.5";
+var VERSION = "0.17.6";
 
 // src/cli/resolve-version.ts
 function readPackageVersion() {

package/dist/vault/approvals/kernel-server.js

@@ -4619,7 +4619,7 @@ var init_schema = __esm(() => {
         name: exports_external.string().regex(/^[a-zA-Z0-9][a-zA-Z0-9_-]*$/, {
           message: "Consumer name must be a path-safe slug (letters, digits, underscore, hyphen)"
         }).describe("Socket-path identity; binds at /run/switchroom/auth-broker/<name>/sock"),
-        account: exports_external.string().min(1).describe("Pinned account label for this consumer. `get-credentials` returns " + "this account's credentials; `mark-exhausted` from this consumer " + "only affects this account."),
+        account: exports_external.string().min(1).optional().describe("Optional pinned account label for this consumer. When set, " + "`get-credentials` serves this account (with automatic failover " + "while it is quota-exhausted) and `mark-exhausted` from this " + "consumer attributes to it — use a pin for quota isolation. " + "When omitted, the consumer follows the fleet `auth.active` " + "exactly like an agent: same account swaps, same failover."),
         uid: exports_external.number().int().nonnegative().optional().describe("Optional UID to chown the consumer socket to (defaults to 0 = root, " + "suitable for sibling containers running as root)."),
         mirror_dir: exports_external.string().optional().describe("Optional host-side directory path. When set, the broker actively " + "writes the consumer's effective-account `.credentials.json` mirror " + "here — in addition to serving creds on demand via `get-credentials`. " + "Use this to eliminate the pull-latency gap: without a mirror the " + "consumer only gets failover creds at its next scheduled re-fetch " + "(up to 30 min). With a mirror the broker pushes failover creds " + "immediately when it detects exhaustion (consumer-quota-sensor tick, " + "or a mark-exhausted RPC on the pinned account). The directory must " + "be accessible to the broker container (bind-mounted from the host) " + "and to the consumer container; the broker writes " + "`<mirror_dir>/.credentials.json` atomically. Chown is attempted to " + "`uid` (default 0) — swallowed when CAP_CHOWN is absent.")
       })).optional().describe("Non-agent peers that hold a broker socket (RFC H §4.8). Each gets " + "its own `/run/switchroom/auth-broker/<name>/sock` chowned to its UID. " + "Consumers cannot be admins; a consumer name that collides with an " + "agent (whether that agent has `admin: true` or not) is a config " + "error caught at schema validation."),

package/dist/vault/broker/server.js

@@ -4619,7 +4619,7 @@ var init_schema = __esm(() => {
         name: exports_external.string().regex(/^[a-zA-Z0-9][a-zA-Z0-9_-]*$/, {
           message: "Consumer name must be a path-safe slug (letters, digits, underscore, hyphen)"
         }).describe("Socket-path identity; binds at /run/switchroom/auth-broker/<name>/sock"),
-        account: exports_external.string().min(1).describe("Pinned account label for this consumer. `get-credentials` returns " + "this account's credentials; `mark-exhausted` from this consumer " + "only affects this account."),
+        account: exports_external.string().min(1).optional().describe("Optional pinned account label for this consumer. When set, " + "`get-credentials` serves this account (with automatic failover " + "while it is quota-exhausted) and `mark-exhausted` from this " + "consumer attributes to it — use a pin for quota isolation. " + "When omitted, the consumer follows the fleet `auth.active` " + "exactly like an agent: same account swaps, same failover."),
         uid: exports_external.number().int().nonnegative().optional().describe("Optional UID to chown the consumer socket to (defaults to 0 = root, " + "suitable for sibling containers running as root)."),
         mirror_dir: exports_external.string().optional().describe("Optional host-side directory path. When set, the broker actively " + "writes the consumer's effective-account `.credentials.json` mirror " + "here — in addition to serving creds on demand via `get-credentials`. " + "Use this to eliminate the pull-latency gap: without a mirror the " + "consumer only gets failover creds at its next scheduled re-fetch " + "(up to 30 min). With a mirror the broker pushes failover creds " + "immediately when it detects exhaustion (consumer-quota-sensor tick, " + "or a mark-exhausted RPC on the pinned account). The directory must " + "be accessible to the broker container (bind-mounted from the host) " + "and to the consumer container; the broker writes " + "`<mirror_dir>/.credentials.json` atomically. Chown is attempted to " + "`uid` (default 0) — swallowed when CAP_CHOWN is absent.")
       })).optional().describe("Non-agent peers that hold a broker socket (RFC H §4.8). Each gets " + "its own `/run/switchroom/auth-broker/<name>/sock` chowned to its UID. " + "Consumers cannot be admins; a consumer name that collides with an " + "agent (whether that agent has `admin: true` or not) is a config " + "error caught at schema validation."),

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "switchroom",
   "//version": "NOT the release version — source of truth is the git tag, resolved by scripts/build.mjs:resolveVersion() (see CLAUDE.md > Standard release process). This field is stale by design and only the Layer-4 dev/non-tag fallback for build.mjs + src/cli/resolve-version.ts; do NOT bump it expecting a release to pick it up. npm-pack tarball naming needs a real version — do that as an UNCOMMITTED pack-time bump (see release step 6), never a committed one.",
-  "version": "0.17.5",
+  "version": "0.17.6",
   "description": "Run Claude Code 24/7 on your Claude Pro/Max subscription over Telegram. Open-source alternative to OpenClaw and NanoClaw — no API keys.",
   "type": "module",
   "bin": {

package/telegram-plugin/auth-snapshot-format.ts

@@ -859,6 +859,14 @@ export interface SnapshotKeyboardOpts {
    *  keyboard agrees with the card body instead of defaulting to a second
    *  `new Date()`. Defaults to wall-clock. */
   now?: Date;
+  /**
+   * Demo mode (the `/auth demo` / `/usage demo` suffix). Masks the
+   * account-email in each switch-button LABEL (the callback_data keeps the
+   * real label — the broker needs it to act) and flips the refresh callback
+   * to `auth:refresh:demo` so a ↻ tap re-renders the card still masked
+   * instead of leaking the real emails mid-screen-recording.
+   */
+  demo?: boolean;
 }
 
 /**
@@ -891,14 +899,14 @@ export function buildSnapshotKeyboard(
   for (const t of switchTargets) {
     rows.push([
       {
-        text: `Switch fleet → ${t.label}`,
+        text: `Switch fleet → ${opts.demo ? maskEmail(t.label) : t.label}`,
         callbackData: `auth:use:${t.label}`,
       },
     ]);
   }
 
   rows.push([
-    { text: '↻ Refresh', callbackData: 'auth:refresh' },
+    { text: '↻ Refresh', callbackData: opts.demo ? 'auth:refresh:demo' : 'auth:refresh' },
     { text: '/usage', insertText: '/usage' },
     { text: '+ Add', insertText: '/auth add ' },
   ]);
@@ -919,6 +927,46 @@ function switchPriority(s: AccountSnapshot, now: Date = new Date()): number {
 
 // ── snapshot assembly helper ─────────────────────────────────────────
 
+/**
+ * One per-account row of a broker `probe-quota` response. Mirrors the
+ * shape `AuthBrokerClient.probeQuota` returns (src/auth/broker/client.ts)
+ * without importing across the package boundary.
+ */
+export interface ProbeQuotaResultRow {
+  label: string;
+  result: QuotaResult;
+  /** #2495 Change 2 — how this result was sourced. */
+  served?: 'live' | 'cache';
+  /** Unix ms the served snapshot was captured (set when served==="cache"). */
+  capturedAt?: number;
+}
+
+/**
+ * Zip a broker `probe-quota` response back onto the account list, in input
+ * order, and surface cache staleness. Shared by every /auth-surface caller
+ * (/auth show, /usage, the ↻ refresh callback) so the "⚠ cached Nm ago"
+ * footer logic can't drift between them (#2495 Change 2).
+ *
+ * Returns `quotas` parallel to `labels` (a missing row degrades to an
+ * `ok:false` result, never a hole) and `staleCachedAtMs` — the OLDEST
+ * `capturedAt` among cache-served rows, undefined when everything was live.
+ */
+export function zipProbeResults(
+  labels: readonly string[],
+  results: readonly ProbeQuotaResultRow[],
+): { quotas: QuotaResult[]; staleCachedAtMs?: number } {
+  let staleCachedAtMs: number | undefined;
+  const quotas = labels.map((label): QuotaResult => {
+    const hit = results.find((r) => r.label === label);
+    if (!hit) return { ok: false, reason: 'broker returned no result for account' };
+    if (hit.served === 'cache' && hit.capturedAt != null) {
+      staleCachedAtMs = staleCachedAtMs == null ? hit.capturedAt : Math.min(staleCachedAtMs, hit.capturedAt);
+    }
+    return hit.result;
+  });
+  return staleCachedAtMs != null ? { quotas, staleCachedAtMs } : { quotas };
+}
+
 /**
  * Given the broker's `listState` data + a parallel array of live quota
  * results (same length, same order), return the AccountSnapshot[] the

package/telegram-plugin/dist/gateway/gateway.js

@@ -24748,7 +24748,7 @@ var init_schema = __esm(() => {
         name: exports_external.string().regex(/^[a-zA-Z0-9][a-zA-Z0-9_-]*$/, {
           message: "Consumer name must be a path-safe slug (letters, digits, underscore, hyphen)"
         }).describe("Socket-path identity; binds at /run/switchroom/auth-broker/<name>/sock"),
-        account: exports_external.string().min(1).describe("Pinned account label for this consumer. `get-credentials` returns " + "this account's credentials; `mark-exhausted` from this consumer " + "only affects this account."),
+        account: exports_external.string().min(1).optional().describe("Optional pinned account label for this consumer. When set, " + "`get-credentials` serves this account (with automatic failover " + "while it is quota-exhausted) and `mark-exhausted` from this " + "consumer attributes to it \u2014 use a pin for quota isolation. " + "When omitted, the consumer follows the fleet `auth.active` " + "exactly like an agent: same account swaps, same failover."),
         uid: exports_external.number().int().nonnegative().optional().describe("Optional UID to chown the consumer socket to (defaults to 0 = root, " + "suitable for sibling containers running as root)."),
         mirror_dir: exports_external.string().optional().describe("Optional host-side directory path. When set, the broker actively " + "writes the consumer's effective-account `.credentials.json` mirror " + "here \u2014 in addition to serving creds on demand via `get-credentials`. " + "Use this to eliminate the pull-latency gap: without a mirror the " + "consumer only gets failover creds at its next scheduled re-fetch " + "(up to 30 min). With a mirror the broker pushes failover creds " + "immediately when it detects exhaustion (consumer-quota-sensor tick, " + "or a mark-exhausted RPC on the pinned account). The directory must " + "be accessible to the broker container (bind-mounted from the host) " + "and to the consumer container; the broker writes " + "`<mirror_dir>/.credentials.json` atomically. Chown is attempted to " + "`uid` (default 0) \u2014 swallowed when CAP_CHOWN is absent.")
       })).optional().describe("Non-agent peers that hold a broker socket (RFC H \u00a74.8). Each gets " + "its own `/run/switchroom/auth-broker/<name>/sock` chowned to its UID. " + "Consumers cannot be admins; a consumer name that collides with an " + "agent (whether that agent has `admin: true` or not) is a config " + "error caught at schema validation."),
@@ -30892,6 +30892,7 @@ var init_boot_card = __esm(() => {
 // auth-snapshot-format.ts
 var exports_auth_snapshot_format = {};
 __export(exports_auth_snapshot_format, {
+  zipProbeResults: () => zipProbeResults,
   reviveLastQuota: () => reviveLastQuota,
   renderFallbackAnnouncement: () => renderFallbackAnnouncement2,
   renderAuthSnapshotFormat2: () => renderAuthSnapshotFormat22,
@@ -31283,13 +31284,13 @@ function buildSnapshotKeyboard2(snapshots, opts = {}) {
   for (const t of switchTargets) {
     rows.push([
       {
-        text: `Switch fleet \u2192 ${t.label}`,
+        text: `Switch fleet \u2192 ${opts.demo ? maskEmail(t.label) : t.label}`,
         callbackData: `auth:use:${t.label}`
       }
     ]);
   }
   rows.push([
-    { text: "\u21bb Refresh", callbackData: "auth:refresh" },
+    { text: "\u21bb Refresh", callbackData: opts.demo ? "auth:refresh:demo" : "auth:refresh" },
     { text: "/usage", insertText: "/usage" },
     { text: "+ Add", insertText: "/auth add " }
   ]);
@@ -31305,6 +31306,19 @@ function switchPriority2(s, now = new Date) {
     return 2;
   return 3;
 }
+function zipProbeResults(labels, results) {
+  let staleCachedAtMs;
+  const quotas = labels.map((label) => {
+    const hit = results.find((r) => r.label === label);
+    if (!hit)
+      return { ok: false, reason: "broker returned no result for account" };
+    if (hit.served === "cache" && hit.capturedAt != null) {
+      staleCachedAtMs = staleCachedAtMs == null ? hit.capturedAt : Math.min(staleCachedAtMs, hit.capturedAt);
+    }
+    return hit.result;
+  });
+  return staleCachedAtMs != null ? { quotas, staleCachedAtMs } : { quotas };
+}
 function buildSnapshotsFromState2(state4, quotas) {
   const out = [];
   for (let i = 0;i < state4.accounts.length; i++) {
@@ -42519,13 +42533,13 @@ function buildSnapshotKeyboard(snapshots, opts = {}) {
   for (const t of switchTargets) {
     rows.push([
       {
-        text: `Switch fleet \u2192 ${t.label}`,
+        text: `Switch fleet \u2192 ${opts.demo ? maskEmail(t.label) : t.label}`,
         callbackData: `auth:use:${t.label}`
       }
     ]);
   }
   rows.push([
-    { text: "\u21bb Refresh", callbackData: "auth:refresh" },
+    { text: "\u21bb Refresh", callbackData: opts.demo ? "auth:refresh:demo" : "auth:refresh" },
     { text: "/usage", insertText: "/usage" },
     { text: "+ Add", insertText: "/auth add " }
   ]);
@@ -42721,7 +42735,7 @@ async function handleAuthCommand(parsed, ctx) {
       let keyboard;
       if (liveQuotas && liveQuotas.length === state3.accounts.length) {
         const snapshots = buildSnapshotsFromState(state3, liveQuotas);
-        keyboard = buildSnapshotKeyboard(snapshots, { now: new Date });
+        keyboard = buildSnapshotKeyboard(snapshots, { now: new Date, demo: ctx.demo });
       }
       return {
         text: renderShowText(state3, Date.now(), {
@@ -58590,10 +58604,10 @@ function readTurnActiveMarkerAgeMs(stateDir, now) {
 }
 
 // ../src/build-info.ts
-var VERSION = "0.17.5";
-var COMMIT_SHA = "aae03307";
-var COMMIT_DATE = "2026-07-05T22:09:14+10:00";
-var LATEST_PR = null;
+var VERSION = "0.17.6";
+var COMMIT_SHA = "0cc74c23";
+var COMMIT_DATE = "2026-07-05T13:02:44Z";
+var LATEST_PR = 2854;
 var COMMITS_AHEAD_OF_TAG = 0;
 
 // gateway/boot-version.ts
@@ -69315,17 +69329,7 @@ Send \`/auth cancel\` to abort.`, { html: true });
     liveQuotas: async (accounts) => {
       try {
         const { results } = await client3.probeQuota(accounts.map((a) => a.label));
-        let staleCachedAtMs;
-        const quotas = accounts.map((a) => {
-          const hit = results.find((r) => r.label === a.label);
-          if (!hit)
-            return { ok: false, reason: "broker returned no result for account" };
-          if (hit.served === "cache" && hit.capturedAt != null) {
-            staleCachedAtMs = staleCachedAtMs == null ? hit.capturedAt : Math.min(staleCachedAtMs, hit.capturedAt);
-          }
-          return hit.result;
-        });
-        return { quotas, staleCachedAtMs };
+        return zipProbeResults(accounts.map((a) => a.label), results);
       } catch (err) {
         const reason = `broker probe-quota failed: ${err?.message ?? String(err)}`;
         return { quotas: accounts.map(() => ({ ok: false, reason })) };
@@ -70467,7 +70471,8 @@ _Tap /auth to see updated quota for the new active account._`), {}), { chat_id:
     }
     return;
   }
-  if (data === "auth:refresh") {
+  if (data === "auth:refresh" || data === "auth:refresh:demo") {
+    const refreshDemo = data === "auth:refresh:demo";
     const refreshMsg = ctx.callbackQuery?.message;
     if (refreshMsg) {
       const key = `${refreshMsg.chat.id}:${refreshMsg.message_id}`;
@@ -70494,20 +70499,19 @@ _Tap /auth to see updated quota for the new active account._`), {}), { chat_id:
         return;
       }
       const state4 = await client3.listState();
-      const probeResp = state4.accounts.length > 0 ? await client3.probeQuota(state4.accounts.map((a) => a.label)).catch(() => ({ results: [] })) : { results: [] };
-      const quotas = state4.accounts.map((a) => {
-        const hit = probeResp.results.find((r) => r.label === a.label);
-        return hit?.result ?? { ok: false, reason: "broker returned no result for account" };
-      });
+      const probeResp = state4.accounts.length > 0 ? await client3.probeQuota(state4.accounts.map((a) => a.label), undefined, true).catch(() => ({ results: [] })) : { results: [] };
+      const { quotas, staleCachedAtMs } = zipProbeResults(state4.accounts.map((a) => a.label), probeResp.results);
       const tz = process.env.SWITCHROOM_TIMEZONE ?? process.env.TZ ?? "UTC";
       const { renderAuthSnapshotFormat2: renderAuthSnapshotFormat23, buildSnapshotsFromState: buildSnapshotsFromState4, buildSnapshotKeyboard: buildSnapshotKeyboard3 } = await Promise.resolve().then(() => (init_auth_snapshot_format(), exports_auth_snapshot_format));
       const snapshots = buildSnapshotsFromState4(state4, quotas);
+      const renderNow = new Date;
       const text2 = renderAuthSnapshotFormat23(snapshots, {
         tz,
-        now: new Date,
-        liveProbedAtMs: Date.now()
+        now: renderNow,
+        demo: refreshDemo,
+        ...staleCachedAtMs != null ? { staleCachedAtMs } : { liveProbedAtMs: renderNow.getTime() }
       });
-      const kbRows = buildSnapshotKeyboard3(snapshots);
+      const kbRows = buildSnapshotKeyboard3(snapshots, { now: renderNow, demo: refreshDemo });
       const inline_keyboard = kbRows.map((row) => row.map((b) => {
         if (b.callbackData)
           return { text: b.text, callback_data: b.callbackData };
@@ -70888,14 +70892,7 @@ bot.command("usage", async (ctx) => {
       const state4 = await client3.listState();
       if (state4.accounts.length > 0) {
         const probeResp = await client3.probeQuota(state4.accounts.map((a) => a.label)).catch(() => ({ results: [] }));
-        let staleCachedAtMs;
-        const quotas = state4.accounts.map((a) => {
-          const hit = probeResp.results.find((r) => r.label === a.label);
-          if (hit?.served === "cache" && hit.capturedAt != null) {
-            staleCachedAtMs = staleCachedAtMs == null ? hit.capturedAt : Math.min(staleCachedAtMs, hit.capturedAt);
-          }
-          return hit?.result ?? { ok: false, reason: "broker returned no result for account" };
-        });
+        const { quotas, staleCachedAtMs } = zipProbeResults(state4.accounts.map((a) => a.label), probeResp.results);
         const { renderAuthSnapshotFormat2: renderAuthSnapshotFormat23, buildSnapshotsFromState: buildSnapshotsFromState4, buildSnapshotKeyboard: buildSnapshotKeyboard3 } = await Promise.resolve().then(() => (init_auth_snapshot_format(), exports_auth_snapshot_format));
         const tz = process.env.SWITCHROOM_TIMEZONE ?? process.env.TZ ?? "UTC";
         const snapshots = buildSnapshotsFromState4(state4, quotas);
@@ -70905,7 +70902,7 @@ bot.command("usage", async (ctx) => {
           demo,
           ...staleCachedAtMs != null ? { staleCachedAtMs } : { liveProbedAtMs: Date.now() }
         });
-        const kbRows = buildSnapshotKeyboard3(snapshots, { now: new Date });
+        const kbRows = buildSnapshotKeyboard3(snapshots, { now: new Date, demo });
         const keyboard = new import_grammy12.InlineKeyboard;
         kbRows.forEach((row, ri) => {
           if (ri > 0)

package/telegram-plugin/gateway/auth-command.ts

@@ -403,7 +403,7 @@ export async function handleAuthCommand(
       let keyboard: AuthCommandReply['keyboard']
       if (liveQuotas && liveQuotas.length === state.accounts.length) {
         const snapshots = buildSnapshotsFromState(state, liveQuotas)
-        keyboard = buildSnapshotKeyboard(snapshots, { now: new Date() })
+        keyboard = buildSnapshotKeyboard(snapshots, { now: new Date(), demo: ctx.demo })
       }
       return {
         text: renderShowText(state, Date.now(), {

package/telegram-plugin/gateway/gateway.ts

@@ -574,7 +574,7 @@ import {
   QUOTA_WATCH_CLAIM_WINDOW_MS,
   isLiveCorroboration,
 } from '../quota-watch.js'
-import { buildSnapshotsFromState, buildSnapshotsFromCachedState } from '../auth-snapshot-format.js'
+import { buildSnapshotsFromState, buildSnapshotsFromCachedState, zipProbeResults } from '../auth-snapshot-format.js'
 import { maskUsername, maskVaultKey } from '../demo-mask.js'
 import {
   writeTurnActiveMarker,
@@ -19284,19 +19284,9 @@ bot.command("auth", async ctx => {
         const { results } = await client.probeQuota(accounts.map((a) => a.label))
         // #2495 Change 2 — the broker tags each result `served:"live"|"cache"`
         // (TTL hit or failed-probe fallback). When ANY account was served from
-        // cache, surface the OLDEST snapshot's capturedAt so the card stamps
-        // "⚠ cached Nm ago" instead of a false live stamp.
-        let staleCachedAtMs: number | undefined
-        // Preserve input order (broker also preserves it, but be defensive).
-        const quotas = accounts.map((a) => {
-          const hit = results.find((r) => r.label === a.label)
-          if (!hit) return { ok: false as const, reason: "broker returned no result for account" }
-          if (hit.served === 'cache' && hit.capturedAt != null) {
-            staleCachedAtMs = staleCachedAtMs == null ? hit.capturedAt : Math.min(staleCachedAtMs, hit.capturedAt)
-          }
-          return hit.result
-        })
-        return { quotas, staleCachedAtMs }
+        // cache, zipProbeResults surfaces the OLDEST snapshot's capturedAt so
+        // the card stamps "⚠ cached Nm ago" instead of a false live stamp.
+        return zipProbeResults(accounts.map((a) => a.label), results)
       } catch (err) {
         // Surface a uniform per-account failure so the dashboard renders
         // gracefully (label badge stays UNKNOWN) instead of falling back
@@ -21283,13 +21273,18 @@ async function handleAuthDashboardCallback(ctx: Context): Promise<void> {
   }
 
   // auth:refresh — re-render the /auth snapshot in-place with a fresh
-  // live probe. Replaces the message body; keyboard stays.
-  if (data === 'auth:refresh') {
+  // live probe. Replaces the message body; keyboard stays. The `:demo`
+  // variant re-renders with email masking intact (a ↻ tap on an
+  // `/auth demo` / `/usage demo` card must not unmask mid-recording).
+  if (data === 'auth:refresh' || data === 'auth:refresh:demo') {
+    const refreshDemo = data === 'auth:refresh:demo'
     // Freshness throttle: each refresh fan-fires N live api.anthropic.com
-    // probes (one per account, force=true bypasses the 5-min cache).
-    // Without this, a user double-tapping the ↻ button burns through
-    // their account's RPM budget on duplicate work. Cap at one per
-    // AUTH_REFRESH_THROTTLE_MS per (chat, message) pair.
+    // probes (one per account — forceLive bypasses the broker's 45s
+    // probe-on-open TTL, because an explicit ↻ tap is the user asking
+    // for live-now data). Without this, a user double-tapping the ↻
+    // button burns through their account's RPM budget on duplicate
+    // work. Cap at one per AUTH_REFRESH_THROTTLE_MS per (chat, message)
+    // pair.
     const refreshMsg = ctx.callbackQuery?.message
     if (refreshMsg) {
       const key = `${refreshMsg.chat.id}:${refreshMsg.message_id}`
@@ -21315,24 +21310,34 @@ async function handleAuthDashboardCallback(ctx: Context): Promise<void> {
       }
       const state = await client.listState()
       // Broker-routed probe (#1336) — see gateway.ts:8910 for diagnosis.
+      // forceLive=true: an explicit ↻ tap must bypass the broker's
+      // probe-on-open TTL — pre-fix, a tap inside the TTL window served
+      // the cached snapshot while stamping "Live · refreshed 0s ago".
       const probeResp = state.accounts.length > 0
-        ? await client.probeQuota(state.accounts.map((a) => a.label)).catch(() => ({ results: [] }))
+        ? await client.probeQuota(state.accounts.map((a) => a.label), undefined, true).catch(() => ({ results: [] }))
         : { results: [] }
-      const quotas = state.accounts.map((a) => {
-        const hit = probeResp.results.find((r) => r.label === a.label)
-        return hit?.result ?? { ok: false as const, reason: 'broker returned no result for account' }
-      })
+      // #2495 Change 2 — even under forceLive a failed upstream probe falls
+      // back to the broker cache (served:"cache"); stamp "⚠ cached Nm ago"
+      // instead of a false live stamp, same as the /auth and /usage paths.
+      const { quotas, staleCachedAtMs } = zipProbeResults(
+        state.accounts.map((a) => a.label),
+        probeResp.results,
+      )
       const tz = process.env.SWITCHROOM_TIMEZONE ?? process.env.TZ ?? 'UTC'
       const { renderAuthSnapshotFormat2, buildSnapshotsFromState, buildSnapshotKeyboard } = await import(
         '../auth-snapshot-format.js'
       )
       const snapshots = buildSnapshotsFromState(state, quotas)
+      // Single clock for card body + keyboard so health classification
+      // can't disagree between the two (#2495 folded nit A).
+      const renderNow = new Date()
       const text = renderAuthSnapshotFormat2(snapshots, {
         tz,
-        now: new Date(),
-        liveProbedAtMs: Date.now(),
+        now: renderNow,
+        demo: refreshDemo,
+        ...(staleCachedAtMs != null ? { staleCachedAtMs } : { liveProbedAtMs: renderNow.getTime() }),
       })
-      const kbRows = buildSnapshotKeyboard(snapshots)
+      const kbRows = buildSnapshotKeyboard(snapshots, { now: renderNow, demo: refreshDemo })
       const inline_keyboard = kbRows.map((row) =>
         row.map((b) => {
           if (b.callbackData) return { text: b.text, callback_data: b.callbackData }
@@ -21797,14 +21802,10 @@ bot.command('usage', async ctx => {
         // which we surface as a "⚠ cached Nm ago" footer instead of a false
         // live stamp.
         const probeResp = await client.probeQuota(state.accounts.map((a) => a.label)).catch(() => ({ results: [] }))
-        let staleCachedAtMs: number | undefined
-        const quotas = state.accounts.map((a) => {
-          const hit = probeResp.results.find((r) => r.label === a.label)
-          if (hit?.served === 'cache' && hit.capturedAt != null) {
-            staleCachedAtMs = staleCachedAtMs == null ? hit.capturedAt : Math.min(staleCachedAtMs, hit.capturedAt)
-          }
-          return hit?.result ?? { ok: false as const, reason: 'broker returned no result for account' }
-        })
+        const { quotas, staleCachedAtMs } = zipProbeResults(
+          state.accounts.map((a) => a.label),
+          probeResp.results,
+        )
         const { renderAuthSnapshotFormat2, buildSnapshotsFromState, buildSnapshotKeyboard } = await import(
           '../auth-snapshot-format.js'
         )
@@ -21821,7 +21822,7 @@ bot.command('usage', async ctx => {
         // /auth snapshot does. switchroomReply routes through the rich path
         // (replyWithRichMessage), which accepts reply_markup. Build a grammy
         // InlineKeyboard so the markup type matches switchroomReply's contract.
-        const kbRows = buildSnapshotKeyboard(snapshots, { now: new Date() })
+        const kbRows = buildSnapshotKeyboard(snapshots, { now: new Date(), demo })
         const keyboard = new InlineKeyboard()
         kbRows.forEach((row, ri) => {
           if (ri > 0) keyboard.row()

package/telegram-plugin/tests/auth-snapshot-format.test.ts

@@ -18,6 +18,7 @@ import {
   renderFallbackAnnouncement,
   buildSnapshotKeyboard,
   buildSnapshotsFromState,
+  zipProbeResults,
   buildSnapshotsFromCachedState,
   reviveLastQuota,
   THROTTLING_THRESHOLD_PCT,
@@ -720,6 +721,80 @@ describe('buildSnapshotKeyboard', () => {
       .flat().map((b) => b.text);
     expect(before).not.toContain('Switch fleet → refilled@x');
   });
+
+  it('demo mode masks the switch-button label but keeps the real label in callback_data', () => {
+    __resetDemoMaskCachesForTest();
+    const snaps: AccountSnapshot[] = [
+      snap({ label: 'ken.real@example.com', isActive: true, quota: quota({ fiveHourUtilizationPct: 5 }) }),
+      snap({ label: 'alt.real@example.com', quota: quota({ fiveHourUtilizationPct: 5 }) }),
+    ];
+    const rows = buildSnapshotKeyboard(snaps, { now: NOW, demo: true });
+    const switchBtn = rows.flat().find((b) => b.callbackData?.startsWith('auth:use:'));
+    expect(switchBtn).toBeDefined();
+    // Label masked — the real email never appears on screen…
+    expect(switchBtn!.text).not.toContain('alt.real@example.com');
+    // …but the broker still gets the real label to act on.
+    expect(switchBtn!.callbackData).toBe('auth:use:alt.real@example.com');
+  });
+
+  it('demo mode flips the refresh callback to auth:refresh:demo so a ↻ tap stays masked', () => {
+    const snaps: AccountSnapshot[] = [
+      snap({ label: 'a@x', isActive: true, quota: quota({}) }),
+    ];
+    const demoRows = buildSnapshotKeyboard(snaps, { demo: true }).flat();
+    expect(demoRows.find((b) => b.text === '↻ Refresh')?.callbackData).toBe('auth:refresh:demo');
+    const plainRows = buildSnapshotKeyboard(snaps).flat();
+    expect(plainRows.find((b) => b.text === '↻ Refresh')?.callbackData).toBe('auth:refresh');
+  });
+});
+
+// ── zipProbeResults ──────────────────────────────────────────────────
+
+describe('zipProbeResults', () => {
+  const okResult = { ok: true as const, data: quota({ fiveHourUtilizationPct: 5 }) };
+
+  it('returns quotas parallel to labels with no staleCachedAtMs when everything is live', () => {
+    const { quotas, staleCachedAtMs } = zipProbeResults(
+      ['a@x', 'b@x'],
+      [
+        { label: 'a@x', result: okResult, served: 'live' },
+        { label: 'b@x', result: okResult, served: 'live' },
+      ],
+    );
+    expect(quotas).toHaveLength(2);
+    expect(quotas.every((q) => q.ok)).toBe(true);
+    expect(staleCachedAtMs).toBeUndefined();
+  });
+
+  it('surfaces the OLDEST capturedAt among cache-served rows (#2495 Change 2)', () => {
+    const { staleCachedAtMs } = zipProbeResults(
+      ['a@x', 'b@x', 'c@x'],
+      [
+        { label: 'a@x', result: okResult, served: 'live' },
+        { label: 'b@x', result: okResult, served: 'cache', capturedAt: 5_000 },
+        { label: 'c@x', result: okResult, served: 'cache', capturedAt: 2_000 },
+      ],
+    );
+    expect(staleCachedAtMs).toBe(2_000);
+  });
+
+  it('degrades a missing per-label row to ok:false, preserving input order', () => {
+    const { quotas } = zipProbeResults(
+      ['a@x', 'gone@x'],
+      [{ label: 'a@x', result: okResult }],
+    );
+    expect(quotas[0]!.ok).toBe(true);
+    expect(quotas[1]!.ok).toBe(false);
+    expect((quotas[1] as { ok: false; reason: string }).reason).toContain('no result');
+  });
+
+  it('ignores served:"cache" rows without capturedAt (no false staleness)', () => {
+    const { staleCachedAtMs } = zipProbeResults(
+      ['a@x'],
+      [{ label: 'a@x', result: okResult, served: 'cache' }],
+    );
+    expect(staleCachedAtMs).toBeUndefined();
+  });
 });
 
 // ── buildSnapshotsFromState ──────────────────────────────────────────