@tokenoftrust/cli 2.5.4 → 2.5.6

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.6",
   "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/report.mjs

@@ -39,7 +39,7 @@ export const USAGE = `tot report go-live — the go-live readiness report for yo
 
 Save each page's JSON from the devkit page checks into <dir> first, e.g.
   validate-page.sh <base> / > <dir>/home.json
-  validate-page-browser.mjs <base> / --provider cloudflare > <dir>/home.browser.json
+  validate-page-browser.mjs <base> / --store . --provider cloudflare > <dir>/home.browser.json
 
 ${TEASER}`;
 
@@ -147,9 +147,9 @@ export function storeConfigCheck(lint) {
 /**
  * Everything the report needs, from a page-results directory. A site-wide run's summary is used as
  * is; otherwise the checks are derived here from the single-page results.
- * @param {{ pagesDir: string, stylePath?: string|null, lint?: any }} input
+ * @param {{ pagesDir: string, stylePath?: string|null, lint?: any, config?: Record<string, any>|null }} input the store checkout's lint and `.tot/config.json`
  */
-export function evidenceFromDir({ pagesDir, stylePath = null, lint = null }) {
+export function evidenceFromDir({ pagesDir, stylePath = null, lint = null, config = null }) {
   const summary = readJson(join(pagesDir, "site-summary.json"));
   const styleJson = readJson(stylePath ?? join(pagesDir, "style.json"));
   const browserDir = join(pagesDir, "browser");
@@ -177,6 +177,7 @@ export function evidenceFromDir({ pagesDir, stylePath = null, lint = null }) {
             aggregate: { ...summary, totals: { ...summary.totals, issues: summary.totals?.issues ?? { lowRiskOpen: 0 } } },
             styleJson: styleJson ?? (summary.style?.gates ? { gates: summary.style.gates } : null),
             args: { manifest: summary.manifest ?? "(none supplied to the style-concept audit)" },
+            config,
           }),
         ];
     return {
@@ -195,6 +196,7 @@ export function evidenceFromDir({ pagesDir, stylePath = null, lint = null }) {
       aggregate: { pages: results, totals: { issues: { lowRiskOpen: 0 } } },
       styleJson,
       args: { manifest: "(none supplied to the style-concept audit)" },
+      config,
     }).filter((c) => c.area !== "Low-risk fix loop"),
   ];
   const failing = results.filter((r) => Object.values(r.gates).some((v) => v === false)).length;
@@ -288,7 +290,8 @@ export function run(argv, ctx, io = {}) {
     return 2;
   }
   const lint = storeExists ? validateTenant(store, { tenantId: tenant, mode: args.workspace ? "workspace" : "monorepo" }) : null;
-  const evidence = evidenceFromDir({ pagesDir, stylePath: args.style ? resolve(args.style) : null, lint });
+  const config = storeExists ? readJson(join(store, ".tot", "config.json")) : null;
+  const evidence = evidenceFromDir({ pagesDir, stylePath: args.style ? resolve(args.style) : null, lint, config });
   if (!evidence.measured) {
     err(`${fail(
       `no page-check results under ${pagesDir}`,

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/declared-config.d.mts

@@ -59,7 +59,10 @@ export const NICOTINE_WARNING_TEXT: string;
 export const CONSPICUITY_FLOOR: Readonly<{ contrast: number; fontSizePx: number; fontWeight: number }>;
 export const DEFAULT_NICOTINE_WARNING_PRESET: string;
 export const NICOTINE_WARNING_PRESETS: Readonly<Record<string, Readonly<NicotineWarningPresentation>>>;
+export const NICOTINE_WARNING_KEYS: readonly string[];
 export const NICOTINE_WARNING_STYLE_KEYS: readonly string[];
+export const NICOTINE_WARNING_CHECK_WIDTH_BOUNDS: Readonly<{ min: number; max: number }>;
+export function nicotineWarningCheckWidths(declaration: unknown): { widths: number[]; problems: string[] };
 export function contrastRatio(a: string, b: string): number;
 export function conspicuityProblems(p: NicotineWarningPresentation): string[];
 export function resolveNicotineWarning(declaration: unknown): ResolvedNicotineWarning;

package/src/declared-config.mjs

@@ -12,7 +12,9 @@
  *
  * Mirrors packages/public-runtime/src/declared-tenant-config.mjs (this package ships
  * to npm on its own); test/declared-config-parity.test.mjs pins the two together.
- * Dependency-free: the storefront runner copies this file as-is.
+ * Dependency-free: the storefront runner copies this file as-is, and the devkit page checks carry
+ * a byte-identical copy (docs/devkit-staging/tools/lib/declared-config.mjs, pinned by
+ * test/declared-config-devkit-copy.test.mjs) so their gates read a store's declaration the same way.
  */
 
 export const TOT_CONFIG_KEYS = [
@@ -184,6 +186,7 @@ export const MANDATED_NOTICE_KEYS = [
 
 const ERROR = "error";
 const WARN = "warn";
+/** @type {(v: unknown) => v is Record<string, any>} */
 const isObject = (v) => v !== null && typeof v === "object" && !Array.isArray(v);
 
 /**
@@ -470,7 +473,13 @@ export function validateDeclaredConfig(config, file = ".tot/config.json") {
     }
   }
   out.push(...complianceFindings(config, file));
-  const warning = resolveNicotineWarning(isObject(config.compliance) ? config.compliance.nicotineWarning : undefined);
+  const declaration = isObject(config.compliance) ? config.compliance.nicotineWarning : undefined;
+  for (const problem of nicotineWarningCheckWidths(declaration).problems) {
+    out.push(mk(ERROR, "config-nicotine-warning-check-widths", `${file} compliance`,
+      `\`compliance.nicotineWarning\`: ${problem}. The page browser gate cannot check the warning at the widths you meant.`,
+      "list the widths where your layout changes (e.g. where your header becomes fixed), or remove `checkWidthsPx`"));
+  }
+  const warning = resolveNicotineWarning(declaration);
   if (warning.enabled && warning.problems.length > 0) {
     out.push(mk(ERROR, "config-nicotine-warning", `${file} compliance`, nicotineWarningProblemMessage(warning.problems),
       'use `true`, `{ "preset": "dark" }` or `{ "preset": "light" }`, or fix the style values named above'));
@@ -504,6 +513,7 @@ export function validateDeclaredConfig(config, file = ".tot/config.json") {
 //   "nicotineWarning": true                                   → the "dark" preset
 //   "nicotineWarning": { "preset": "light" }                  → a validated preset
 //   "nicotineWarning": { "preset": "light", "style": {...} }  → a custom presentation
+//   "nicotineWarning": { "checkWidthsPx": [800] }             → also checked seen at 800px wide
 //
 // Every presentation — preset or custom — must clear CONSPICUITY_FLOOR. A preset needs no
 // review. A custom presentation is a deviation the owner approves at go-live:
@@ -562,6 +572,9 @@ export const NICOTINE_WARNING_PRESETS = Object.freeze({
  * }} NicotineWarningPresentation
  */
 
+/** Every key a `compliance.nicotineWarning` object may declare. */
+export const NICOTINE_WARNING_KEYS = Object.freeze(["preset", "style", "checkWidthsPx"]);
+
 export const NICOTINE_WARNING_STYLE_KEYS = Object.freeze([
   "background", "text", "border", "textTransform", "fontWeight", "fontSizePx",
 ]);
@@ -669,8 +682,9 @@ export function resolveNicotineWarning(declaration) {
   if (!isObject(declaration)) {
     return resolved({ problems: ["must be `true` or an object like { \"preset\": \"light\" }"] });
   }
-  const { preset: presetName = DEFAULT_NICOTINE_WARNING_PRESET, style, ...rest } = /** @type {Record<string, unknown>} */ (declaration);
-  const problems = Object.keys(rest).map((k) => `\`${k}\` is not a nicotineWarning key (allowed: preset, style)`);
+  const { preset: presetName = DEFAULT_NICOTINE_WARNING_PRESET, style, checkWidthsPx: _checkWidths, ...rest } =
+    /** @type {Record<string, unknown>} */ (declaration);
+  const problems = Object.keys(rest).map((k) => `\`${k}\` is not a nicotineWarning key (allowed: ${NICOTINE_WARNING_KEYS.join(", ")})`);
   const base = typeof presetName === "string" ? NICOTINE_WARNING_PRESETS[presetName] : undefined;
   if (!base) {
     problems.push(`\`preset\` must be one of ${Object.keys(NICOTINE_WARNING_PRESETS).map((p) => `"${p}"`).join(", ")}`);
@@ -695,6 +709,35 @@ export function resolveNicotineWarning(declaration) {
   return resolved({ presentation, preset: matching ?? null, custom: !matching });
 }
 
+/** The viewport widths a store may add to the page browser gate's nicotine-warning check. */
+export const NICOTINE_WARNING_CHECK_WIDTH_BOUNDS = Object.freeze({ min: 320, max: 3840 });
+
+/**
+ * The extra viewport widths at which the page browser gate checks the nicotine warning is seen.
+ *
+ * The gate always checks its own phone, tablet, laptop and desktop widths; `checkWidthsPx` adds
+ * the store's own breakpoints (e.g. the width where its header becomes fixed) and never removes
+ * a default. A store that does not declare the warning has no widths; `true` and an object
+ * without `checkWidthsPx` add none.
+ *
+ *   "nicotineWarning": { "preset": "dark", "checkWidthsPx": [800, 1180] }
+ *
+ * `problems` lists why a declared value is unusable, in which case no extra width is used.
+ * @param {unknown} declaration the store's `compliance.nicotineWarning`
+ * @returns {{ widths: number[], problems: string[] }}
+ */
+export function nicotineWarningCheckWidths(declaration) {
+  if (!isObject(declaration)) return { widths: [], problems: [] };
+  const value = /** @type {Record<string, unknown>} */ (declaration).checkWidthsPx;
+  if (value === undefined) return { widths: [], problems: [] };
+  const { min, max } = NICOTINE_WARNING_CHECK_WIDTH_BOUNDS;
+  const usable = (/** @type {unknown} */ w) => Number.isInteger(w) && /** @type {number} */ (w) >= min && /** @type {number} */ (w) <= max;
+  if (!Array.isArray(value) || value.length === 0 || !value.every(usable)) {
+    return { widths: [], problems: [`\`checkWidthsPx\` must be a non-empty array of whole pixel widths from ${min} to ${max}, e.g. [800]`] };
+  }
+  return { widths: [...new Set(/** @type {number[]} */ (value))].sort((a, b) => a - b), problems: [] };
+}
+
 /**
  * The exact, human-readable statement of a custom presentation — what the owner approves.
  * Every resolved value is in it, so two presentations that differ in any value describe
@@ -720,7 +763,8 @@ export function describeNicotineWarningPresentation(p) {
  * fixed or sticky header pinned to the top of the viewport). Raising the warning above page
  * chrome would paint it over the tenant's own open menus and drawers, so occlusion is measured
  * instead: the page browser gate (`validate-page-browser.mjs`, `nicotineWarning`) fails a page
- * whose warning is covered at a phone, tablet or desktop width and names the covering element.
+ * whose warning is covered at a phone, tablet or desktop width, or at a width the store declares
+ * in `checkWidthsPx`, and names the covering element.
  * @param {unknown} declaration the tenant's `compliance.nicotineWarning`
  * @param {"bar" | "block"} variant
  */

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() {

package/src/readiness-checks.mjs

@@ -178,8 +178,38 @@ export function ecommerceStyleGuideCheck(styleJson) {
   };
 }
 
-export function buildReadinessChecks({ aggregate, styleJson, args }) {
+/**
+ * The store's declared compliance notices, judged on every page. Only a notice the store declares
+ * is a row, and a page that did not judge it fails: a declared legal notice nobody has seen on the
+ * page is not ready, whatever the page check reported.
+ * @param {{ gates?: Record<string, boolean | null> }[]} results
+ * @param {Record<string, any> | null | undefined} config the store's `.tot/config.json`
+ */
+export function complianceNoticesCheck(results, config) {
+  if (!config?.compliance?.nicotineWarning) return null;
+  const counts = countGate(results, "nicotineWarning");
+  const problem = counts.total === 0
+    ? "No pages were discovered for validation."
+    : counts.fail > 0 || counts.unknown > 0
+      ? `The store declares the FDA nicotine warning: ${counts.fail}/${counts.total} page(s) fail the visibility gate` +
+        `${counts.unknown > 0 ? ` and ${counts.unknown}/${counts.total} were not judged against the declaration` : ""}.`
+      : `The FDA nicotine warning is seen on all ${counts.total} page(s) at every checked width.`;
+  return {
+    area: "Compliance notices",
+    status: counts.total > 0 && counts.fail === 0 && counts.unknown === 0 ? "PASS" : "FAIL",
+    why: "A store that declares the FDA nicotine warning must show it, conspicuously and uncovered, on every page (21 CFR 1143.3).",
+    problem,
+    fix: "Run the browser page checks with --store <your checkout> on every page, then offset any fixed or sticky header the gate names; never restyle or move the warning.",
+  };
+}
+
+/**
+ * @param {{ aggregate: any, styleJson: any, args: { manifest: string }, config?: Record<string, any> | null }} input
+ *   `config` is the store's `.tot/config.json`, which decides the compliance notices row.
+ */
+export function buildReadinessChecks({ aggregate, styleJson, args, config = null }) {
   const results = aggregate.pages;
+  const compliance = complianceNoticesCheck(results, config);
   const render = countGate(results, "render");
   const boundary = countGate(results, "boundary");
   const seo = combineCounts(countGate(results, "seo"), countGate(results, "sitemap"));
@@ -191,6 +221,7 @@ export function buildReadinessChecks({ aggregate, styleJson, args }) {
   const lowRisk = aggregate.totals.issues.lowRiskOpen ?? 0;
 
   return [
+    ...(compliance ? [compliance] : []),
     styleGuideCheck(styleJson, args.manifest),
     ecommerceStyleGuideCheck(styleJson),
     styleQualityCheck(styleJson),