@tokenoftrust/cli 1.4.1 → 1.5.0

package/src/commands/accept.mjs

@@ -1,9 +1,9 @@
 /**
  * `tot accept --tenant <t> --pr <N>` (alias: `tot merge`) — OPERATOR verb: QUEUE a
  * PR's integration into the protected `preview` AGGREGATE. This SUPERSEDES the
- * retired `tot accept` = merge-PR→main semantics (operator-console U5): accepting a
+ * retired `tot accept` = merge-PR→main semantics: accepting a
  * change no longer merges it to main — it enqueues it into the tenant's shared
- * `preview` aggregate, where b07's tenant-serialized queue merges it (b06
+ * `preview` aggregate, where the tenant-serialized queue merges it (via
  * `candidate_accept`, preview-base only), rebuilds the aggregate, and moves the
  * shared preview pointer ONLY when combined evidence is green.
  *
@@ -14,20 +14,20 @@
  * see.
  *
  * TARGET RESOLUTION — `--pr N --tenant t` names the PR; the server resolves it to its
- * candidate from the tenant's ReviewEnvironment index (unit b04 — tenant + PR, NO
+ * candidate from the tenant's ReviewEnvironment index (tenant + PR, NO
  * chg-id). An explicit `--change-id` is still accepted (targets a specific record),
- * but is no longer REQUIRED — the whole point of b08 is that a PR number is enough.
+ * but is no longer REQUIRED — a PR number alone is enough.
  *
  * TRANSPORT — the honest accept path is `POST /api/changes/integrate` (the ONE call
- * site of b07's `TenantIntegrationQueue.enqueue`). Like `tot ship --pr` (U16) and
- * `tot pr list --tenant` (U17), the CLI reaches it with the OPERATOR-SECRET Bearer
+ * site of `TenantIntegrationQueue.enqueue`). Like `tot ship --pr` and
+ * `tot pr list --tenant`, the CLI reaches it with the OPERATOR-SECRET Bearer
  * transport (`resolveOperatorSecret` + `X-Tot-Owner` + `x-tot-capability`), since the
  * CLI holds no storefront cookie. The response is the honest `IntegrateOutcome` —
  * `queueState` / `runState` / `pointerMoved` / `aggregateSha` / `statusMessage` —
  * which this verb renders VERBATIM, never a bare "merged".
  *
  * HUMAN GATE — integrating into the shared preview is a decision a human makes, so
- * this ALWAYS states the EXACT plan (shared `planForAction`, unit U10: which PR,
+ * this ALWAYS states the EXACT plan (shared `planForAction`: which PR,
  * which tenant, "queue for integration into the preview aggregate — NO merge, NO
  * go-live") and requires an explicit confirm. `--yes` is an explicit affirmative; a
  * non-TTY without `--yes` is refused (mirrors `tot ship`'s non-TTY refusal).
@@ -39,17 +39,24 @@ import { planForAction, printPlanAndConfirm } from "../plan.mjs";
 // Reuse `tot ship`'s operator-secret precedence verbatim so accept + ship + pr-list
 // speak ONE operator-auth contract, not three.
 import { resolveOperatorSecret } from "./ship.mjs";
-// Automate-first conflict recovery (workstream tot-merge-conflict-resolution-ux, unit
-// u5): the ONE-CLICK `--refresh` path calls the `candidate_refresh` MCP tool (u1) —
+// Automate-first conflict recovery: the ONE-CLICK `--refresh` path calls the
+// `candidate_refresh` MCP tool —
 // which has NO operator-secret HTTP route, so it is reached over the MCP client the
 // same way `tot pr` reaches `candidate_status`/`candidate_close`.
 import { createMcpClient } from "../mcp.mjs";
 import { establishSession, AuthUnavailableError } from "../auth.mjs";
+// No-operator-secret path: mint a viewer session from the developer's OWN `tot`
+// login and integrate as themselves (server gates on their live ship-on-behalf grant).
+import { resolveViewerTransport } from "../viewer-session.mjs";
+// The doctor PUSH: on a failed accept/integrate, auto-append the COMPACT
+// "here's what's blocking you" summary over the SAME transport we just used, so a
+// developer doesn't have to remember to run `tot preview doctor` themselves.
+import { autoSurfaceDoctor } from "../merge-doctor-report.mjs";
 
 const DEFAULT_STOREFRONT_URL = "https://storefront.tokenoftrust.store";
 const DEFAULT_MCP_URL = "https://mcp.tokenoftrust.com";
 
-// The three refresh strategies `candidate_refresh` (u1) accepts, mirroring the admin
+// The three refresh strategies `candidate_refresh` accepts, mirroring the admin
 // panel's one-click resolver (keep-mine / keep-current / smart-merge). `merge` is the
 // DEFAULT: a real forge three-way merge that refuses cleanly (with the diverged file
 // list) on a genuine same-line overlap rather than silently clobbering either side —
@@ -170,7 +177,7 @@ function candidateLabel(pr, changeId) {
 
 /**
  * Read the forge `mergeable` verdict for a candidate out of a `GET /api/changes`
- * body (b07's operator queue — its BUILT entries carry the full ReviewEnvironment
+ * body (the operator queue — its BUILT entries carry the full ReviewEnvironment
  * shape, incl. `mergeable`). This is the mergeable PREFLIGHT source: one read over the
  * SAME operator-secret transport accept already uses, so a not-mergeable candidate is
  * caught BEFORE a doomed integrate round-trips to the forge. Best-effort by design —
@@ -212,7 +219,7 @@ export function readCandidateVerdict(data, { pr, changeId }) {
 }
 
 /**
- * Normalise a `candidate_refresh` (u1) result read back over the MCP client.
+ * Normalise a `candidate_refresh` result read back over the MCP client.
  * `status:"committed"` is the ONLY success (the candidate was rebuilt and is now
  * mergeable); a `merge_failed` refusal carries `unresolved` (the diverged files);
  * any other status is an honest refusal/error surfaced by its `message`. Reads
@@ -260,7 +267,7 @@ export function notMergeableOfferLines(tenant, { pr, changeId }) {
 }
 
 /**
- * Run `candidate_refresh` (u1) over the MCP client — the ONE-CLICK rebuild of a
+ * Run `candidate_refresh` over the MCP client — the ONE-CLICK rebuild of a
  * not-mergeable candidate onto the current preview tip. `candidate_refresh` has no
  * operator-secret HTTP route, so this reaches it exactly as `tot pr` reaches
  * `candidate_status`: an OAuth developer session (`tot login`) + `client_switch` to
@@ -453,8 +460,10 @@ export function reportIntegrated(result, { tenant, label }) {
  * unit-tested with no network/TTY.
  *
  * @param {{ tenant:string, pr:number|null, changeId:string|null, headSha:string|null,
- *   secret:string, storefrontUrl?:string|null, yes?:boolean }} params
- * @param {{ fetch?:typeof fetch, confirmPlan?:typeof printPlanAndConfirm }} [deps]
+ *   secret:string, storefrontUrl?:string|null, yes?:boolean, refresh?:boolean,
+ *   strategy?:string, mcpUrl?:string|null, identity?:string|null, env?:NodeJS.ProcessEnv }} params
+ * @param {{ fetch?:typeof fetch, confirmPlan?:typeof printPlanAndConfirm,
+ *   resolveViewerTransport?:typeof resolveViewerTransport }} [deps]
  * @returns {Promise<number>} process exit code
  */
 export async function runIntegrate(
@@ -476,10 +485,11 @@ export async function runIntegrate(
 ) {
   const fetchImpl = deps.fetch || globalThis.fetch;
   const confirmPlan = deps.confirmPlan || printPlanAndConfirm;
-  const base = (storefrontUrl || DEFAULT_STOREFRONT_URL).trim().replace(/\/+$/, "");
+  const resolveViewer = deps.resolveViewerTransport || resolveViewerTransport;
+  let base = (storefrontUrl || DEFAULT_STOREFRONT_URL).trim().replace(/\/+$/, "");
   const label = pr != null ? `PR #${pr}` : changeId;
 
-  // 1. State the EXACT plan (shared U10 affordance) — queue-integrate-into-preview,
+  // 1. State the EXACT plan (shared affordance) — queue-integrate-into-preview,
   //    NO merge, NO go-live — and gate on an explicit confirm.
   const planLines = planForAction({ action: "accept", tenant, pr, changeId, headSha });
   const { confirmed, reason } = await confirmPlan(planLines, {
@@ -502,25 +512,39 @@ export async function runIntegrate(
     return 1;
   }
 
-  // 2. Operator-secret transport — the CLI holds no storefront cookie, so the
-  //    Bearer + X-Tot-Owner path is its route (same as `tot ship --pr`). No
-  //    `content-type` here: it's added per-POST; the mergeable preflight GET wants none.
-  if (!secret) {
-    console.error(
-      fail(
-        "integrating a PR is an OPERATOR action — it needs an operator secret",
-        "set PREVIEW_RECONCILE_SECRET (or GRANTS_ADMIN_SECRET / TOT_OPERATOR_SECRET), or pass --secret",
-      ),
-    );
-    return 2;
+  // 2. Resolve the transport. Two routes to the SAME `/api/changes/integrate`:
+  //    - OPERATOR SECRET (operators/CI): Bearer + X-Tot-Owner on the generic host.
+  //    - VIEWER SESSION (an invited developer, no secret): mint a `tot_session` from
+  //      their OWN `tot` login on the TENANT'S host and send it as a cookie. The
+  //      server authorizes on their live ship-on-behalf grant either way.
+  //    No `content-type` here: it's added per-POST; the mergeable preflight GET wants none.
+  let authHeaders;
+  if (secret) {
+    authHeaders = {
+      authorization: `Bearer ${secret}`,
+      "x-tot-owner": tenant,
+      "x-tot-capability": "ship-on-behalf",
+    };
+  } else {
+    const viewer = await resolveViewer({ tenant, env, fetchImpl });
+    if (!viewer.ok) {
+      console.error(fail(viewer.message, viewer.hint));
+      return 2;
+    }
+    base = viewer.base; // the tenant's own host — the dev-viewer admission is host-scoped
+    authHeaders = viewer.authHeaders;
   }
-  const authHeaders = {
-    authorization: `Bearer ${secret}`,
-    "x-tot-owner": tenant,
-    "x-tot-capability": "ship-on-behalf",
+
+  // Auto-surface the merge-doctor on a failed accept. Best-effort: fetches the
+  // hosted doctor over the SAME transport we just resolved and prints the COMPACT
+  // summary; never throws and never touches the exit code (it's called AFTER the
+  // outcome is decided, purely to append diagnostic context to where the failure
+  // already surfaced). A clean/unreachable doctor prints nothing.
+  const surfaceDoctor = async () => {
+    for (const line of await autoSurfaceDoctor({ base, authHeaders, fetchImpl })) console.error(line);
   };
 
-  // 2.5. MERGEABLE PREFLIGHT — read the candidate's forge verdict from b07's queue
+  // 2.5. MERGEABLE PREFLIGHT — read the candidate's forge verdict from the queue
   //      (`GET /api/changes`, SAME transport) so a doomed accept never round-trips to
   //      the forge. Best-effort: on any listing gap it's `known:false` → proceed as
   //      normal. When it KNOWS the candidate isn't mergeable, take the automate-first
@@ -543,13 +567,13 @@ export async function runIntegrate(
       },
       deps,
     );
-    if (!handled.integrate) return handled.code;
+    if (!handled.integrate) return /** @type {number} */ (handled.code);
     curPr = handled.pr ?? curPr;
     curChangeId = handled.changeId ?? curChangeId;
     curHead = null; // the rebuilt PR has a fresh head; let the server re-resolve.
   }
 
-  // 3. POST the honest accept path (b07 queue enqueue) and render the terminal state.
+  // 3. POST the honest accept path (queue enqueue) and render the terminal state.
   let res;
   let result;
   try {
@@ -579,7 +603,7 @@ export async function runIntegrate(
       { tenant, pr: curPr, changeId: result.changeId ?? curChangeId, strategy, refresh, mcpUrl, identity, env },
       deps,
     );
-    if (!handled.integrate) return handled.code;
+    if (!handled.integrate) return /** @type {number} */ (handled.code);
     try {
       ({ res, result } = await postIntegrate(
         {
@@ -614,10 +638,13 @@ export async function runIntegrate(
     for (const line of notMergeableOfferLines(tenant, { pr: curPr, changeId: curChangeId })) {
       console.log(line);
     }
+    await surfaceDoctor();
     return 1;
   }
 
-  return reportIntegrated(result, { tenant, label });
+  const code = reportIntegrated(result, { tenant, label: /** @type {string} */ (label) });
+  if (code !== 0) await surfaceDoctor();
+  return code;
 }
 
 /** The mergeable PREFLIGHT read (best-effort). See readCandidateVerdict. */
@@ -646,7 +673,7 @@ function reportIntegrateHttpError(result, res, { tenant, label }) {
     fail(
       `the integration queue refused the request: ${msg}`,
       res.status === 401 || res.status === 403
-        ? "check the operator secret and that it's authorised for this tenant"
+        ? "you need a live ship-on-behalf grant on this tenant (ask the store owner) — or an operator secret authorised for it"
         : res.status === 404
           ? `check that ${label} has a built candidate in ${tenant}'s queue (\`tot pr list --tenant ${tenant}\`)`
           : "check --tenant / --url / --pr, then re-run",

package/src/commands/app/dev.mjs

@@ -1,5 +1,5 @@
 /**
- * `tot app dev` — the local Private App harness (PrivateApps epic D6 Chunk D).
+ * `tot app dev` — the local Private App harness (PrivateApps epic).
  * Everything here is OFFLINE: no network beyond the localhost URL you point
  * it at, no MCP, no real ToT credentials. It generates and reuses its own
  * throwaway RS256 keypair per app directory (`.tot/dev-keys.json`) so signing
@@ -49,7 +49,10 @@ function randHex(bytes) {
   return Buffer.from(crypto.getRandomValues(new Uint8Array(bytes))).toString("hex");
 }
 
-/** Load or create the app's throwaway RS256 keypair at `<appDir>/.tot/dev-keys.json`. */
+/**
+ * Load or create the app's throwaway RS256 keypair at `<appDir>/.tot/dev-keys.json`.
+ * @param {string} appDir @param {{ kid?: string }} [opts]
+ */
 export async function ensureDevKeys(appDir, { kid } = {}) {
   const keysPath = join(appDir, ".tot", "dev-keys.json");
   const alg = { name: "RSASSA-PKCS1-v1_5", hash: "SHA-256" };
@@ -107,8 +110,9 @@ function runValidate(argv, { appDir }) {
     console.log(`✔ ${manifestPath} is a valid tot-app.json (contract v${result.manifest.contractVersion})`);
     return 0;
   }
-  console.log(`✖ ${manifestPath} — ${result.errors.length} error(s):`);
-  for (const e of result.errors) console.log(`  - ${e}`);
+  const errs = result.errors || [];
+  console.log(`✖ ${manifestPath} — ${errs.length} error(s):`);
+  for (const e of errs) console.log(`  - ${e}`);
   return 1;
 }
 

package/src/commands/app/index.mjs

@@ -1,6 +1,6 @@
 /**
  * `tot app` — the Storefront Private App developer subcommand group
- * (PrivateApps epic D6 Chunks C+D): scaffold a new app, then exercise its
+ * (PrivateApps epic): scaffold a new app, then exercise its
  * webhook/manifest/widget-launch loop entirely offline.
  *
  *   tot app scaffold <name>   materialize a runnable Private App skeleton
@@ -23,11 +23,11 @@ export async function run(argv, ctx) {
 
   if (sub === "scaffold") {
     const { run: runScaffold } = await import("./scaffold.mjs");
-    return runScaffold(rest, ctx);
+    return /** @type {any} */ (runScaffold)(rest, ctx);
   }
   if (sub === "dev") {
     const { run: runDev } = await import("./dev.mjs");
-    return runDev(rest, ctx);
+    return /** @type {any} */ (runDev)(rest, ctx);
   }
 
   console.error(fail(`unknown \`tot app\` subcommand: ${sub}`, "tot app --help"));

package/src/commands/app/scaffold.mjs

@@ -1,6 +1,6 @@
 /**
  * `tot app scaffold <name>` — materialize a runnable Storefront Private App
- * skeleton on disk (PrivateApps epic D6 Chunk C). See ../../app-scaffold.mjs
+ * skeleton on disk (PrivateApps epic). See ../../app-scaffold.mjs
  * for the offline, idempotent copy logic this wraps.
  *
  *   tot app scaffold <name>          scaffold ./<name>

package/src/commands/branches.mjs

@@ -1,13 +1,13 @@
 /**
- * `tot branches` — the full branch-cleanup REPORT for one tenant's repo (P1
- * item 9 of the branch-lifecycle-and-integration-preview contract: "join
+ * `tot branches` — the full branch-cleanup REPORT for one tenant's repo (per
+ * the branch-lifecycle-and-integration-preview contract: "join
  * branch, PR, candidate, head SHA, actor, full zoned timestamp, age, evidence,
  * aggregate status, and cleanup eligibility"). Distinct from `tot pr list`,
  * which only shows OPEN PRs — this shows EVERY branch on the repo (protected,
  * active, stale, integrated, closed, orphaned), because that is what a
  * cleanup decision needs.
  *
- * The report itself is server-side classification (b13's `candidate_list` MCP
+ * The report itself is server-side classification (the `candidate_list` MCP
  * tool → `classifyBranches`); this command is presentation only — it never
  * re-derives eligibility, an "aggregate" verdict, or a classification bucket
  * client-side. The contract's complaint about a "truncated human table" (see
@@ -58,6 +58,7 @@ Options:
 
 /** Parse `tot branches` argv. Pure — unit-testable. */
 export function parseBranchesArgs(argv) {
+  /** @type {{ tenant: string|null, repo: string|null, staleAfterDays: number|null, mcp: string|null, identity: string|null, json: boolean, help: boolean }} */
   const a = {
     tenant: null,
     repo: null,

package/src/commands/cleanup.mjs

@@ -1,9 +1,9 @@
 /**
- * `tot cleanup` — owner-confirmed branch GC (P1 items 9+10 of the
- * branch-lifecycle-and-integration-preview contract's "Current gaps").
+ * `tot cleanup` — owner-confirmed branch GC, per the
+ * branch-lifecycle-and-integration-preview contract's "Current gaps".
  *
  * `tot cleanup --dry-run` runs the SAME fresh server-side classification
- * `tot branches` shows (b13's `candidate_list` MCP tool) and prints exactly
+ * `tot branches` shows (the `candidate_list` MCP tool) and prints exactly
  * which refs are eligible to delete and WHY — no writes, ever, no matter what
  * else is passed. An owner-confirmed execution mode (`--yes`, or an
  * interactive y/N via the shared plan affordance) then deletes ONLY that
@@ -12,10 +12,6 @@
  * — this CLI's dry-run read is a convenience for the human, never the source
  * of truth the delete trusts.
  *
- * Distinct from `tot retire` (evicts a HOSTED PREVIEW artifact, rebuildable,
- * touches no git ref) — `tot cleanup` is branch GC: an irreversible ref
- * delete. See retire.mjs's header for that distinction.
- *
  * THE CONTRACT'S HARD RULES, ENFORCED SERVER-SIDE AND NEVER RELAXED HERE:
  *   - age alone NEVER makes an open candidate deletable (`stale-open` is a
  *     WARN bucket only);
@@ -45,9 +41,8 @@ const USAGE = `tot cleanup — owner-confirmed branch GC (deletes terminal candi
   Deletes ONLY branches the server just (re-)classified as "integrated" (PR
   merged) or "closed-or-rejected" (PR closed without merging). NEVER deletes
   by age alone, NEVER touches \`main\`/\`preview\`, and NEVER deletes an orphan
-  (no PR record) — orphans are reported, not removed. \`tot retire\` is a
-  DIFFERENT verb: it evicts a hosted preview artifact (rebuildable), not a
-  git branch.
+  (no PR record) — orphans are reported, not removed. Reject closes the PR and
+  removes its hosted candidate artifact; cleanup deletes the terminal git ref.
 
 Options:
   --tenant <appDomain>       Target tenant/repo. Defaults to the current
@@ -65,6 +60,7 @@ Options:
 
 /** Parse `tot cleanup` argv. Pure — unit-testable. */
 export function parseCleanupArgs(argv) {
+  /** @type {{ tenant: string|null, repo: string|null, staleAfterDays: number|null, ref: string|null, dryRun: boolean, yes: boolean, mcp: string|null, identity: string|null, help: boolean }} */
   const a = {
     tenant: null,
     repo: null,
@@ -206,7 +202,7 @@ export async function run(argv, ctx) {
 
     const planLines = planForAction({
       action: "cleanup",
-      tenant: tenant || repo,
+      tenant: /** @type {string} */ (tenant || repo),
       refs: eligible.map((b) => ({ ref: b.ref, sha: b.sha, reason: b.reason })),
     });
     const { confirmed, reason } = await printPlanAndConfirm(planLines, {

package/src/commands/clone.mjs

@@ -23,7 +23,7 @@
  * resolved via src/auth.mjs). When there's no session yet and we're on a TTY, we
  * offer to sign in right here and retry — no "run tot login, then re-run".
  *
- * OPERATOR CROSS-TENANT PR CLONE (unit u6). `tot clone <tenant> --pr <N> [dir]`
+ * OPERATOR CROSS-TENANT PR CLONE. `tot clone <tenant> --pr <N> [dir]`
  * materializes a PARTICULAR pull request's head — including on a tenant the
  * operator does NOT own/isn't a member of (e.g. inspecting someone else's PR
  * #7). This does NOT go through `tenant_checkout` — that tool mints a PUSH
@@ -61,6 +61,7 @@ const execFileP = promisify(execFile);
 const DEFAULT_MCP_URL = "https://mcp.tokenoftrust.com";
 
 function parseArgs(argv) {
+  /** @type {{ tenant: string|null, dir: string|null, tag: string, pr: string|null, remoteOnly: boolean, mcp: string|null, printRemote: boolean, help: boolean }} */
   const a = {
     tenant: null,
     dir: null,
@@ -325,10 +326,10 @@ export async function checkoutTenant(client, { tenant, tag = "main", cloneDir =
 
 /**
  * git clone the authenticated remote into `dir` — WITHOUT ever writing the
- * live token to `.git/config` (unit u10). The MCP mints `gitRemote` as a
+ * live token to `.git/config`. The MCP mints `gitRemote` as a
  * basic-auth URL (`user:token@host`); rather than passing that straight to
  * `git clone` (which records exactly the URL it was given as `origin`, token
- * and all — the pre-u10 shape this fixes), the token is handed to git
+ * and all), the token is handed to git
  * EPHEMERALLY via a one-shot `http.extraheader` (same mechanism
  * pushPreviewRef in submit.mjs uses for a push) while the clone SOURCE is
  * already the tokenless public URL — so `origin` comes out tokenless from
@@ -377,7 +378,7 @@ async function cloneRepo(gitRemote, dir, redact) {
 }
 
 /**
- * The cross-tenant PR-clone core (unit u6), composable in-process exactly like
+ * The cross-tenant PR-clone core, composable in-process exactly like
  * `checkoutTenant`: mint a READ-ONLY credential via `repo_read_credential`, then
  * (optionally) clone it and materialize PR #<pr>'s head. This is the path `--pr`
  * ALWAYS takes — own tenant or foreign — because tenant_checkout has no PR-ref
@@ -474,7 +475,7 @@ export async function cloneRepoAtPrRef(gitRemote, dir, pr, redact, deps = {}) {
  * @returns {{ message: string, next: string }|null}
  */
 export function readCredentialError(minted) {
-  const c = minted && typeof minted === "object" && !Array.isArray(minted) ? minted : null;
+  const c = /** @type {any} */ (minted && typeof minted === "object" && !Array.isArray(minted) ? minted : null);
   if (c && Array.isArray(c.repos) && c.repos.some((r) => r && r.gitRemote)) return null;
   const msg =
     (c && (c.message || (typeof c.error === "string" ? c.error : c.error?.message))) ||
@@ -521,7 +522,7 @@ export function readCredentialError(minted) {
  * @returns {{ message: string, next: string }|null}
  */
 export function checkoutError(checkout) {
-  const c = checkout && typeof checkout === "object" && !Array.isArray(checkout) ? checkout : null;
+  const c = /** @type {any} */ (checkout && typeof checkout === "object" && !Array.isArray(checkout) ? checkout : null);
   if (c && c.gitRemote) return null; // a usable checkout — never an error
   const msg =
     (c && (c.message || (typeof c.error === "string" ? c.error : c.error?.message))) ||
@@ -564,7 +565,8 @@ export function checkoutError(checkout) {
  * @returns {Array<{ id: string, name: string, raw: any }>}
  */
 export function normalizeStores(list) {
-  const rows = Array.isArray(list) ? list : list?.clients || list?.tenants || [];
+  const l = /** @type {any} */ (list);
+  const rows = Array.isArray(l) ? l : l?.clients || l?.tenants || [];
   if (!Array.isArray(rows)) return [];
   return rows
     .map((r) => ({
@@ -590,23 +592,24 @@ export function normalizeStores(list) {
  */
 export function storeListError(list) {
   if (list == null || typeof list !== "object" || Array.isArray(list)) return null;
+  const l = /** @type {any} */ (list);
   // A resolvable store array present → it succeeded, never an error.
-  if (Array.isArray(list.clients) || Array.isArray(list.tenants)) return null;
+  if (Array.isArray(l.clients) || Array.isArray(l.tenants)) return null;
   const msg =
-    list.message ||
-    (typeof list.error === "string" ? list.error : list.error?.message) ||
+    l.message ||
+    (typeof l.error === "string" ? l.error : l.error?.message) ||
     null;
-  if (list.isError) return msg || "the store list request returned an error";
-  if (typeof list.status === "string" && !/^(ok|success)$/i.test(list.status)) {
-    return msg || `the store list request returned status "${list.status}"`;
+  if (l.isError) return msg || "the store list request returned an error";
+  if (typeof l.status === "string" && !/^(ok|success)$/i.test(l.status)) {
+    return msg || `the store list request returned status "${l.status}"`;
   }
-  if (list.error) return msg || "the store list request returned an error";
-  if (typeof list.raw === "string" && list.raw.trim()) return list.raw.trim();
+  if (l.error) return msg || "the store list request returned an error";
+  if (typeof l.raw === "string" && l.raw.trim()) return l.raw.trim();
   return null;
 }
 
 /**
- * Extract card c1's broker-identity remediation signal from a `client_list`
+ * Extract the broker-identity remediation signal from a `client_list`
  * result. When the identity resolved ZERO stores, the server MAY carry:
  *   - `brokerStatus`: 'unlinked' | 'unconfigured' | 'broker_error' — present only
  *      when the empty scope is a BROKER-IDENTITY problem (not an entitlement one);
@@ -620,7 +623,7 @@ export function storeListError(list) {
  * @returns {{ brokerStatus: string|null, nextAction: string|null }}
  */
 export function brokerRemediation(list) {
-  const c = list && typeof list === "object" && !Array.isArray(list) ? list : null;
+  const c = /** @type {any} */ (list && typeof list === "object" && !Array.isArray(list) ? list : null);
   const brokerStatus = c && typeof c.brokerStatus === "string" ? c.brokerStatus : null;
   const nextAction =
     c && typeof c.nextAction === "string" && c.nextAction.trim() ? c.nextAction.trim() : null;
@@ -629,8 +632,8 @@ export function brokerRemediation(list) {
 
 /**
  * Status-aware human guidance for an authenticated identity that resolved ZERO
- * stores (card c2 — the fix for the misleading "may still be propagating / ask for
- * a store invite" copy that dead-ended an UNLINKED identity). Driven by card c1's
+ * stores (fixes the misleading "may still be propagating / ask for
+ * a store invite" copy that dead-ended an UNLINKED identity). Driven by
  * `brokerStatus`/`nextAction`:
  *   - `unlinked` → the identity isn't linked to the ToT broker yet, so no scope can
  *      resolve. This is NOT an entitlement problem — point at `tot link` (the
@@ -655,7 +658,7 @@ export function noStoresGuidance(list, { linkHint = "tot link" } = {}) {
 
   if (brokerStatus === "unlinked") {
     // The actionable terminal step beats the server's identity_link_begin/poll
-    // MCP-tool wording for a CLI user, so lead with `tot link` (c2 optional-arm
+    // MCP-tool wording for a CLI user, so lead with `tot link` (the optional-arm
     // directive). Fall back to the server string only if there's no link action.
     return {
       brokerStatus,