@tokenoftrust/cli 2.5.4 → 2.5.5

package/bin/tot.mjs

@@ -24,6 +24,7 @@ import { emitActivity, capRendered } from "../src/activity.mjs";
 import { maybeNotifyUpdate } from "../src/update-check.mjs";
 import {
   currentInvocationDiagnostics,
+  currentInvocationSession,
   hasRequiredInvocationDiagnostic,
   recordDiagnostic,
   resetInvocationDiagnostics,
@@ -403,6 +404,7 @@ async function main() {
     }
     const diagnostics = currentInvocationDiagnostics();
     const diagnosticIds = diagnostics.map((entry) => entry.diagnosticId).filter(Boolean);
+    const session = currentInvocationSession();
     // Best-effort activity breadcrumb (never throws, never blocks). `feedback`'s own
     // free-text message is omitted — it's user-typed and belongs only in the report.
     recordActivity({
@@ -414,6 +416,7 @@ async function main() {
       ms: durationMs,
       ...(errMsg ? { err: String(errMsg).slice(0, 200) } : {}),
       ...(diagnosticIds.length ? { diagnosticId: diagnosticIds.at(-1), diagnosticIds } : {}),
+      ...(Object.keys(session).length ? { session } : {}),
     });
     // Emit `cli.command.result` (exit code + duration + a bounded/redacted
     // rendered field). The house-style error text is capped + run through the JS

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@tokenoftrust/cli",
-  "version": "2.5.4",
+  "version": "2.5.5",
   "description": "Token of Trust developer CLI — clone a tenant store, run it locally with save→reload, and submit it for preview. Installs the `tot` command.",
   "license": "Apache-2.0",
   "author": "Token of Trust",

package/src/auth.mjs

@@ -23,6 +23,7 @@ import {
   defaultCredentialsPath, readCredentials, writeCredentials, isExpired, normalizeAuthority, selectedAuthority,
 } from "./token-store.mjs";
 import { refreshAccessToken, credentialsFromToken } from "./oauth.mjs";
+import { noteInvocationSession } from "./diagnostics.mjs";
 
 /** Thrown when no provider can authenticate — carries actionable guidance. */
 export class AuthUnavailableError extends Error {
@@ -208,6 +209,7 @@ export async function resolveDeveloperSession(client, env, deps = {}) {
     const priorEmailHint = credentialEmailHint(prior);
     if (priorEmailHint) creds.emailHint = priorEmailHint;
     writeCredentials(path, creds);
+    noteInvocationSession({ refreshed: true });
   }
 
   if (client && typeof client.setToken === "function") client.setToken(creds.accessToken);

package/src/broker-outage.mjs

@@ -0,0 +1,94 @@
+/**
+ * tot20's entitlement broker not answering withholds every store from an MCP session without
+ * withdrawing any: the session holds only what needs no broker (the platform tenant `tot`, for
+ * staff) until it answers again. The MCP says so — `client_list`/`grant_introspect` report
+ * status `degraded`, and a store call is refused with status `broker_unavailable`, retryable.
+ *
+ * This module recognises that refusal, waits a bounded time for the broker to come back (QA
+ * measured outages of one to two minutes), and otherwise names it — so a git push never falls
+ * into a username prompt and nobody is sent to `tot login`, which cannot help.
+ *
+ * Dependency-free.
+ */
+import { CliError } from "./errors.mjs";
+
+export const BROKER_UNAVAILABLE = "broker_unavailable";
+
+/** How long a store call waits for the broker before it reports the outage. */
+export const BROKER_WAIT_MS = 45_000;
+
+const BACKOFF_MS = [2_000, 4_000, 8_000];
+
+/**
+ * Is this error the MCP's "the broker did not answer" refusal, or the CliError a wait for it
+ * ended in? Matched on the structured status the MCP client records for a tool error
+ * (mcp.mjs → diagnostic.serverStatus), never on message text. Pure.
+ * @param {unknown} error
+ * @returns {boolean}
+ */
+export function isBrokerUnavailable(error) {
+  const e = /** @type {any} */ (error);
+  const d = e?.diagnostic ?? e;
+  if (d?.serverStatus === BROKER_UNAVAILABLE || d?.serverCode === BROKER_UNAVAILABLE) return true;
+  return e instanceof CliError && e.cause !== undefined && isBrokerUnavailable(e.cause);
+}
+
+/**
+ * Is a store-list result (`client_list` / `grant_introspect`) incomplete because the broker did
+ * not answer? Pure.
+ * @param {unknown} list
+ * @returns {boolean}
+ */
+export function isDegradedStoreList(list) {
+  const l = /** @type {any} */ (list);
+  return (l?.session?.brokerStatus ?? l?.brokerStatus) === "broker_error";
+}
+
+/** One line naming a degraded store list, for whoami/grants. Pure. */
+export const DEGRADED_STORE_LIST =
+  "couldn't resolve all your stores right now — Token of Trust's entitlement service didn't " +
+  "answer, so this list is incomplete. Your access wasn't revoked: retry in a minute (`tot login` won't help).";
+
+/**
+ * The CliError for a store call that outlasted the wait.
+ * @param {string} tenant
+ * @param {unknown} [cause]
+ */
+export function brokerUnavailableError(tenant, cause) {
+  return new CliError(
+    `couldn't confirm your access to ${tenant} right now — Token of Trust's entitlement service didn't answer`,
+    {
+      next: "your access wasn't revoked: retry in a minute (`tot login` won't help); " +
+        "`tot whoami` lists your stores again once it answers",
+      cause,
+    },
+  );
+}
+
+/**
+ * Run `attempt`, retrying while the MCP reports the broker unavailable, for up to `waitMs`.
+ * Any other failure is rethrown untouched; an outage that outlasts the wait becomes
+ * brokerUnavailableError. `onWait` fires once, before the first wait.
+ * @template T
+ * @param {() => Promise<T>} attempt
+ * @param {{ tenant: string, onWait?: (waitMs: number) => void, waitMs?: number,
+ *   sleep?: (ms: number) => Promise<void>, now?: () => number }} opts
+ * @returns {Promise<T>}
+ */
+export async function waitOutBrokerOutage(attempt, {
+  tenant, onWait = () => {}, waitMs = BROKER_WAIT_MS,
+  sleep = (ms) => new Promise((resolve) => setTimeout(resolve, ms)), now = Date.now,
+}) {
+  const deadline = now() + waitMs;
+  for (let i = 0; ; i++) {
+    try {
+      return await attempt();
+    } catch (error) {
+      if (!isBrokerUnavailable(error)) throw error;
+      const delay = BACKOFF_MS[Math.min(i, BACKOFF_MS.length - 1)];
+      if (now() + delay > deadline) throw brokerUnavailableError(tenant, error);
+      if (i === 0) onWait(waitMs);
+      await sleep(delay);
+    }
+  }
+}

package/src/commands/git-credential.mjs

@@ -24,25 +24,21 @@
  * by `tot clone` under `spaces/<id>/`) mints through `publication_checkout`, never
  * cached, because each mint rotates the editor's older tokens.
  *
- * FAILS SILENT ON STDOUT, NEVER LOUD THERE: `get` prints NOTHING on stdout and
- * exits non-zero on any problem (not signed in, MCP unreachable, cwd isn't a
- * recognizable tenant checkout) — git then falls through to its next
- * configured helper or its own prompt, exactly as if this helper weren't
- * configured. A stack trace or a malformed credential line on STDOUT here
- * would otherwise corrupt EVERY git operation in the checkout. It also NEVER
- * triggers an interactive sign-in — this runs as a non-interactive subprocess
- * of `git`, so a missing session fails through rather than trying to open a
- * browser mid-`git fetch`.
+ * NOTHING ON STDOUT BUT A CREDENTIAL: `get` prints nothing on stdout and exits
+ * non-zero on any problem — a stack trace or a malformed credential line there
+ * would corrupt EVERY git operation in the checkout. It also NEVER triggers an
+ * interactive sign-in — this runs as a non-interactive subprocess of `git`, so
+ * a missing session fails rather than opening a browser mid-`git fetch`.
  *
- * It is NOT silent on stderr for every failure, though: when the MCP itself
- * renders an authoritative decision — a `CliError` from `tenant_checkout` or
- * `repo_read_credential`, e.g. "this checkout names a tenant your session
- * doesn't hold" — that diagnosis is lost forever if swallowed, and git passes
- * a credential helper's stderr straight through to the developer's terminal.
- * So those specific catches print the CliError's house-style message (+ its
- * `next` step) to stderr before returning null. A bare network/auth failure
- * (not signed in, MCP unreachable, wrong dir) has no such decision to report
- * and stays silent exactly as before.
+ * EVERY MINT FAILURE IS NAMED ON STDERR. The helper installed by `tot clone`
+ * clears any inherited helper for the forge host, so a failed `get` leaves git
+ * nothing but its own prompt: "could not read Username … terminal prompts
+ * disabled", which names neither the cause nor the fix. git passes a helper's
+ * stderr straight through, so every failure to mint — signed out, MCP
+ * unreachable, the MCP refusing the store — prints its house-style message and
+ * next step there. A store refused only because Token of Trust's entitlement
+ * broker did not answer (`broker_unavailable`, ../broker-outage.mjs) is retried
+ * for a bounded time first, since that outage withdraws nothing.
  *
  * Dependency-free (global fetch + `git`, via the same MCP client + auth
  * module every other command uses).
@@ -56,7 +52,8 @@ import { checkoutTenant, mintPublicationSpace, mintReadOnlyAlias, resolveReadOnl
 import { scopeToTenant } from "../tenant-scope.mjs";
 import { detectContext } from "../context.mjs";
 import { repoNameFromRemote, tagFromRepoName } from "./submit.mjs";
-import { CliError, formatError } from "../errors.mjs";
+import { formatError } from "../errors.mjs";
+import { waitOutBrokerOutage } from "../broker-outage.mjs";
 import {
   parseCredentialInput, formatCredentialOutput, splitAuthedRemote,
   readCachedCredential, writeCachedCredential,
@@ -98,8 +95,8 @@ export function readStdin() {
  * Mint (or reuse a cached) forge credential for the tenant the CURRENT
  * directory checks out — the same `tenant_checkout` MCP call `tot clone`
  * itself uses, so the credential is exactly as push-capable. Returns null on
- * ANY failure (wrong dir, not signed in, MCP unreachable) rather than
- * throwing — `get` treats null as "say nothing, exit non-zero".
+ * ANY failure rather than throwing, having named a mint failure on stderr — `get`
+ * treats null as "nothing on stdout, exit non-zero".
  *
  * `createClient`/`establish`/`checkout` are injected (default to the real MCP
  * client + auth + clone.mjs's checkoutTenant) purely so this is testable
@@ -120,21 +117,31 @@ export function readStdin() {
  *   checkout?: typeof checkoutTenant,
  *   mintReadOnly?: typeof mintReadOnlyAlias,
  *   mintSpace?: typeof mintPublicationSpace,
+ *   brokerWait?: { waitMs?: number, sleep?: (ms: number) => Promise<void>, now?: () => number },
  * }} [opts]
  * @returns {Promise<{username:string,password:string}|null>}
  */
 export async function mintOrCacheCredential({
   env = process.env, cwd = process.cwd(), expectedHost = null,
   createClient = createMcpClient, establish = establishSession, checkout = checkoutTenant,
-  mintReadOnly = mintReadOnlyAlias, mintSpace = mintPublicationSpace,
+  mintReadOnly = mintReadOnlyAlias, mintSpace = mintPublicationSpace, brokerWait = {},
 } = {}) {
   let authority;
   try { authority = selectedAuthority(env, { cwd }); }
   catch { console.error("tot: this checkout has an invalid MCP authority. Run tot login --mcp <url> in this checkout."); return null; }
   env = { ...env, TOT_SELECTED_MCP_URL: authority, MCP_BASE_URL: authority };
-  const authFailure = (e) => {
-    if (e instanceof AuthUnavailableError) console.error(`tot: ${e.message} ${e.hint || `Run tot login --mcp ${authority}.`}`);
+  const report = (e) => {
+    console.error(e instanceof AuthUnavailableError
+      ? `tot: ${e.message} ${e.hint || `Run tot login --mcp ${authority}.`}`
+      : formatError(e));
   };
+  const waitOut = (tenant, attempt) => waitOutBrokerOutage(attempt, {
+    ...brokerWait,
+    tenant,
+    onWait: (ms) => console.error(
+      `tot: Token of Trust's entitlement service didn't answer — retrying for up to ${Math.round(ms / 1000)}s…`,
+    ),
+  });
   const recorded = recordedCheckout(cwd);
   if (recorded?.kind === "invalid") return null; // a half-recorded space mints nothing, never the store's
   if (recorded?.kind === PUBLICATION_SPACE_KIND) {
@@ -144,20 +151,19 @@ export async function mintOrCacheCredential({
     try {
       await establish(client, { env });
     } catch (e) {
-      authFailure(e);
+      report(e);
       return null;
     }
     try {
       const scoped = await scopeToTenant(client, recorded.tenant);
-      const res = await mintSpace(scoped, {
+      const res = await waitOut(recorded.tenant, () => mintSpace(scoped, {
         id: recorded.spaceId, mount: "", visibility: "public",
         source: { forge: "", repo: recorded.repo, defaultBranch: "" },
-      });
+      }));
       const cred = splitAuthedRemote(res.gitRemote || "");
       return cred ? { username: cred.username, password: cred.token } : null;
     } catch (e) {
-      authFailure(e);
-      if (e instanceof CliError) console.error(formatError(e));
+      report(e);
       return null;
     }
   }
@@ -173,19 +179,14 @@ export async function mintOrCacheCredential({
     const client = createClient(baseUrl);
     try {
       await establish(client, { env });
-      const res = await mintReadOnly(client, alias);
+      const res = await waitOut(alias.target, () => mintReadOnly(client, alias));
       const cred = splitAuthedRemote(res.gitRemote || "");
       if (!cred) return null;
       const fresh = { username: cred.username, password: cred.token };
       writeCachedCredential(cachePath, fresh);
       return fresh;
     } catch (e) {
-      // A CliError is an authoritative decision (e.g. the kit credential was refused) —
-      // report it on stderr so `git fetch` doesn't dead-end the developer in silence. A
-      // bare network/auth failure (not signed in, MCP unreachable) has no decision to
-      // report and stays silent, same as every other "nothing this helper can do" path.
-      authFailure(e);
-      if (e instanceof CliError) console.error(formatError(e));
+      report(e);
       return null;
     }
   }
@@ -239,22 +240,16 @@ export async function mintOrCacheCredential({
   try {
     await establish(client, { env });
   } catch (e) {
-    authFailure(e);
-    return null; // not signed in (or session unrefreshable) — nothing this helper can do
+    report(e);
+    return null;
   }
   try {
-    const res = await checkout(client, { tenant, tag, cloneDir: null });
+    const res = await waitOut(tenant, () => checkout(client, { tenant, tag, cloneDir: null }));
     const cred = splitAuthedRemote(res.gitRemote || "");
     if (!cred) return null;
     return { username: cred.username, password: cred.token };
   } catch (e) {
-    // Same distinction as the kit-checkout catch above: `checkoutTenant` renders a
-    // CliError when the MCP (or this checkout's own state) has an authoritative answer
-    // — e.g. this checkout's `.tot/config.json` names a tenant the session doesn't hold,
-    // or `tenant_checkout` echoed a different tenant than the one asked for — and that
-    // diagnosis is lost forever if swallowed silently. A bare network/auth failure has
-    // no such decision and stays silent, exit non-zero, exactly as before.
-    if (e instanceof CliError) console.error(formatError(e));
+    report(e);
     return null;
   }
 }
@@ -348,7 +343,7 @@ export async function run(argv, _ctx, opts = {}) {
   if (op !== "get") return 0; // store: stateless, nothing to persist.
 
   const cred = await mintOrCacheCredential({ ...opts, expectedHost: request.host });
-  if (!cred) return 1; // silent — let git fall through to its next helper / its own prompt.
+  if (!cred) return 1; // nothing on stdout; any mint failure was named on stderr.
   process.stdout.write(formatCredentialOutput({
     protocol: request.protocol, host: request.host, username: cred.username, password: cred.password,
   }));

package/src/commands/grants.mjs

@@ -29,7 +29,8 @@ import { createMcpClient } from "../mcp.mjs";
 import { storeListError, noStoresGuidance } from "./clone.mjs";
 import { offerSignIn } from "./login.mjs";
 import { recordServerPolicy } from "../update-check.mjs";
-import { recordDiagnostic } from "../diagnostics.mjs";
+import { noteInvocationSession, recordDiagnostic } from "../diagnostics.mjs";
+import { DEGRADED_STORE_LIST, isDegradedStoreList } from "../broker-outage.mjs";
 
 const DEFAULT_MCP_URL = "https://mcp.tokenoftrust.com";
 
@@ -222,6 +223,8 @@ export async function run(argv, _ctx) {
 
   const { introspected, rows } = normalizeGrantRows(resp);
   const listErr = storeListError(resp);
+  const degraded = isDegradedStoreList(resp);
+  noteInvocationSession({ stores: rows.length, brokerStatus: resp?.session?.brokerStatus ?? null });
 
   if (args.json) {
     console.log(
@@ -229,6 +232,7 @@ export async function run(argv, _ctx) {
         {
           introspected,
           error: listErr || null,
+          ...(degraded ? { incomplete: true, reason: DEGRADED_STORE_LIST } : {}),
           grants: rows.map((r) => ({ ...r, status: grantStatus(r, { now }) })),
         },
         null,
@@ -238,6 +242,13 @@ export async function run(argv, _ctx) {
     return listErr && rows.length === 0 ? 1 : 0;
   }
 
+  if (degraded) {
+    // Only what needs no entitlement answer resolved; naming the session's default as the
+    // "active tenant" would read as the store it had switched to.
+    console.log(`\n${DEGRADED_STORE_LIST.charAt(0).toUpperCase()}${DEGRADED_STORE_LIST.slice(1)}`);
+    for (const row of rows) console.log(`  ${row.tenant}${row.environment ? ` [${row.environment}]` : ""}`);
+    return 1;
+  }
   if (listErr && rows.length === 0) {
     console.log(`\nCouldn't read your grants: ${listErr}`);
     console.log("Run `tot whoami` to check your session, or `tot login` again.");

package/src/commands/submit.mjs

@@ -54,7 +54,8 @@ import { normalizeRefreshResult } from "./accept.mjs";
 import { validateTenant, ERROR, printLoudAdvisories } from "../validate.mjs";
 import { openBrowser } from "../open.mjs";
 import { startProgress } from "../progress.mjs";
-import { fail } from "../errors.mjs";
+import { CliError, fail } from "../errors.mjs";
+import { isBrokerUnavailable, waitOutBrokerOutage } from "../broker-outage.mjs";
 import { emitActivity } from "../activity.mjs";
 import {
   diagnosticReference,
@@ -828,6 +829,28 @@ export function tagFromRepoName(repoName, tenant) {
   return r.startsWith(prefix) && r.length > prefix.length ? r.slice(prefix.length) : "main";
 }
 
+/**
+ * Mint the fresh push remote through `checkout`, waiting out a broker outage. A broker outage
+ * is rethrown (the checkout's remote authenticates through the same broker, so falling back
+ * would only trade the explanation for git's username prompt); any other failure calls
+ * `onFallback` and resolves null so the push uses the checkout's existing remote.
+ *
+ * @param {() => Promise<{ gitRemote?: string|null }>} checkoutFn
+ * @param {{ tenant: string, onFallback?: (e: unknown) => void, onWait?: (ms: number) => void,
+ *   wait?: { sleep?: (ms: number) => Promise<void>, now?: () => number, waitMs?: number } }} opts
+ * @returns {Promise<string|null>}
+ */
+export async function mintPushRemote(checkoutFn, { tenant, onFallback = () => {}, onWait, wait = {} }) {
+  try {
+    const res = await waitOutBrokerOutage(checkoutFn, { tenant, onWait, ...wait });
+    return res.gitRemote || null;
+  } catch (e) {
+    if (isBrokerUnavailable(e)) throw e;
+    onFallback(e);
+    return null;
+  }
+}
+
 /**
  * Push the preview ref (decision B): mint a FRESH, short-lived forge credential
  * right before the push and hand it to git EPHEMERALLY (via `http.extraheader` on
@@ -1660,20 +1683,23 @@ export async function run(argv, ctx, {
   //    (never persisted to `.git/config`), re-minting once on an auth failure.
   //    `checkoutTenant(cloneDir:null)` mints without re-cloning.
   const tag = tagFromRepoName(repo, tenant);
-  const mintRemote = async () => {
-    try {
-      const res = await checkout(client, { tenant, tag, cloneDir: null, redact: redactUrl });
-      return res.gitRemote || null;
-    } catch (e) {
-      recordDiagnostic(e, {
-        command: verb, operation: "tenant_checkout", required: false, degraded: true,
-      }, env);
-      console.error(
-        `~ couldn't mint a fresh push credential (${redactUrl(String(e?.message || e))}) — using the checkout's remote`,
-      );
-      return null;
-    }
-  };
+  const mintRemote = () => mintPushRemote(
+    () => checkout(client, { tenant, tag, cloneDir: null, redact: redactUrl }),
+    {
+      tenant,
+      onWait: (ms) => console.error(
+        `~ Token of Trust's entitlement service didn't answer — retrying for up to ${Math.round(ms / 1000)}s`,
+      ),
+      onFallback: (e) => {
+        recordDiagnostic(e, {
+          command: verb, operation: "tenant_checkout", required: false, degraded: true,
+        }, env);
+        console.error(
+          `~ couldn't mint a fresh push credential (${redactUrl(String(/** @type {any} */ (e)?.message || e))}) — using the checkout's remote`,
+        );
+      },
+    },
+  );
 
   console.error(`~ pushing ${short} → ${ref} (origin, fresh credential)`);
   try {
@@ -1689,7 +1715,9 @@ export async function run(argv, ctx, {
     const diagnostic = recordDiagnostic(new Error(msg, { cause: e }), {
       command: verb, operation: "git_push", required: true, degraded: false,
     }, env);
-    console.error(fail(msg, "check your commit and that the checkout's remote is reachable, then re-run"));
+    console.error(fail(msg, e instanceof CliError && e.next
+      ? e.next
+      : "check your commit and that the checkout's remote is reachable, then re-run"));
     if (!args.json) console.error(`  → ${diagnosticReference(diagnostic, env)}`);
     emitJson(args, buildJsonResult({
       ok: false, ref, commit, changeId, error: msg, diagnosticId: diagnostic.diagnosticId,

package/src/commands/whoami.mjs

@@ -13,7 +13,8 @@ import { establishSession } from "../auth.mjs";
 import { createMcpClient } from "../mcp.mjs";
 import { normalizeStores, storeListError, noStoresGuidance } from "./clone.mjs";
 import { recordServerPolicy } from "../update-check.mjs";
-import { recordDiagnostic } from "../diagnostics.mjs";
+import { noteInvocationSession, recordDiagnostic } from "../diagnostics.mjs";
+import { DEGRADED_STORE_LIST, isDegradedStoreList } from "../broker-outage.mjs";
 
 /**
  * Pure summary of the cached session — no network. Returned for both display and
@@ -63,8 +64,13 @@ export async function run(argv, _ctx) {
     recordServerPolicy(listResp?.cliPolicy, env);
     const listErr = storeListError(listResp);
     const stores = normalizeStores(listResp);
+    const degraded = isDegradedStoreList(listResp);
+    noteInvocationSession({ stores: stores.length, brokerStatus: listResp?.session?.brokerStatus ?? null });
+    if (degraded) console.log(`  ! ${DEGRADED_STORE_LIST}`);
     if (stores.length) {
-      console.log(`  stores you can build on: ${stores.map((s) => s.id).join(", ")}`);
+      console.log(`  stores you can build on${degraded ? " (incomplete)" : ""}: ${stores.map((s) => s.id).join(", ")}`);
+    } else if (degraded) {
+      // The outage line above is the whole story; the no-grants guidance would misdirect.
     } else if (listErr) {
       console.log(`  (couldn't list your stores: ${listErr} — try \`tot login\` again)`);
     } else {

package/src/diagnostics.mjs

@@ -37,6 +37,8 @@ const STRUCTURED_CORRELATION_ID = /^(?:[0-9a-f]{16,64}|[0-9a-f]{8}(?:-[0-9a-f]{4
 
 let invocationDiagnostics = [];
 let invocationContext = {};
+/** @type {{ refreshed?: boolean, stores?: number, brokerStatus?: string|null }} */
+let invocationSession = {};
 
 export function diagnosticsLogPath(env = process.env) {
   return join(env.TOT_HOME || homedir(), ".tot", "diagnostics.log");
@@ -154,6 +156,7 @@ export function recordDiagnostic(error, context = {}, env = process.env) {
     httpStatus: source.httpStatus,
     statusText: source.statusText,
     serverCode: source.serverCode,
+    serverStatus: source.serverStatus,
     message: source.message || (error && typeof error === "object" ? error.message : error),
     traceId: source.traceId,
     requestId: source.requestId,
@@ -206,6 +209,21 @@ export function diagnosticReference(record, env = process.env) {
 export function resetInvocationDiagnostics(context = {}) {
   invocationDiagnostics = [];
   invocationContext = { ...context };
+  invocationSession = {};
+}
+
+/**
+ * Record a fact about this invocation's session for its activity-log line: that the token
+ * was refreshed, how many stores resolved, the broker's verdict. Counts and statuses only —
+ * never a token, never an identity.
+ * @param {{ refreshed?: boolean, stores?: number, brokerStatus?: string|null }} facts
+ */
+export function noteInvocationSession(facts) {
+  invocationSession = { ...invocationSession, ...facts };
+}
+
+export function currentInvocationSession() {
+  return { ...invocationSession };
 }
 
 export function currentInvocationDiagnostics() {