@tokenoftrust/cli 1.4.1 → 1.5.0

package/src/commands/dev.mjs

@@ -147,11 +147,11 @@ export async function run(argv, ctx) {
 }
 
 /**
- * Standalone-checkout entrypoint: native runtime by default (F3 — no Docker
+ * Standalone-checkout entrypoint: native runtime by default (no Docker
  * prerequisite), Docker on explicit request, and Docker as an automatic
  * fallback when the native artifact can't be fetched (e.g. the MCP's
  * dev_renderer_artifact isn't configured on this deployment yet) — so `tot dev`
- * keeps working through the WS3 rollout instead of hard-failing.
+ * keeps working instead of hard-failing.
  */
 async function runStandalone(workspace, args, ctx) {
   if (args.docker) return runContainer(workspace, args, ctx);
@@ -266,7 +266,7 @@ function runMonorepo(ctx, argv) {
  * Thrown when the native runtime can't be used for a reason that's about the
  * artifact/service, not the developer's checkout — runStandalone catches this
  * specifically and falls back to Docker instead of hard-failing. Exported so
- * `tot start` (C1/F3 integration) can catch it too and fall back the same way.
+ * `tot start` can catch it too and fall back the same way.
  */
 export class NativeArtifactUnavailableError extends Error {}
 
@@ -326,7 +326,7 @@ export function bootNative(runnerDir, workspace, port, url, args) {
   const handle = spawnNativeDev(runnerDir, workspace, port, { stdio: "piped", env: bridgeEnv });
   streamDevLogs(handle.child, { cockpitUrl: cockpitUrlFrom(bridgeEnv.TOT_DEV_ACTIVITY_URL) });
 
-  // Heartbeat the hosted cockpit (G1) with the CLI version + this live localhost
+  // Heartbeat the hosted cockpit with the CLI version + this live localhost
   // URL while the runner runs — CLI-side, using the SAME bridge credential the
   // runner's file-save path uses (no-op in --sample, which threads no credential).
   // `cwd` (the checkout root) lets the cockpit show the FULL path to edit.
@@ -409,7 +409,7 @@ export function printSampleBanner({ url }, mode = "sample") {
  * Exported so sample/tests can drive the selection directly.
  * @param {ReturnType<typeof parseArgs>} args
  * @param {{ client?: any }} [opts] an already-authenticated MCP client (entitled path)
- * @returns {Promise<{kind:"public"|"entitled",version:string,url:string,strip:number,cacheKey:string}>}
+ * @returns {Promise<{kind:string,version:string,url:string,strip:number,cacheKey:string,integrity:string|null}>}
  */
 export async function resolveRendererSource(args, { client } = {}) {
   if (args.sample) return resolvePublicRendererSource(args);
@@ -577,6 +577,11 @@ function compareStableAsc(a, b) {
  * override with `--renderer-version` / TOT_RUNNER_VERSION. Package/registry
  * overridable via env for testing.
  */
+/**
+ * @param {any} args
+ * @param {NodeJS.ProcessEnv} [env]
+ * @param {{ declaredVersion?: string|null }} [opts]
+ */
 export async function resolvePublicRendererSource(args, env = process.env, { declaredVersion = null } = {}) {
   const pkg = env.TOT_RUNNER_PACKAGE || PUBLIC_RUNNER_PACKAGE;
   const registry = (env.TOT_NPM_REGISTRY || DEFAULT_NPM_REGISTRY).replace(/\/$/, "");
@@ -644,8 +649,9 @@ function isCompatibleMaintenancePatch(cliVersion, runnerVersion) {
 /**
  * ENTITLED source: the MCP's `dev_renderer_artifact` signed URL, gated on the
  * developer entitlement (same gate as the Docker pull token). Reuses an
- * already-authenticated `client` when provided (C1/F3), else establishes its own.
+ * already-authenticated `client` when provided, else establishes its own.
  */
+/** @param {any} args @param {{ client?: any }} [opts] */
 export async function resolveEntitledRendererSource(args, { client: providedClient } = {}) {
   const baseUrl = args.mcp || process.env.MCP_BASE_URL || process.env.TOT_MCP_URL || DEFAULT_MCP_URL;
   const client = providedClient || createMcpClient(baseUrl);
@@ -680,11 +686,13 @@ export async function resolveEntitledRendererSource(args, { client: providedClie
  * anything that should fall back to Docker (MCP unreachable, not entitled, not
  * configured, no corepack/pnpm on this host) rather than hard-failing `tot dev`.
  *
- * Exported + accepts an already-authenticated `client` (C1/F3 integration:
- * `tot start` reuses its own session and overlaps this with the checkout clone
+ * Exported + accepts an already-authenticated `client` (`tot start` reuses
+ * its own session and overlaps this with the checkout clone
  * instead of paying for a second client.initialize()+establishSession() — same
  * pattern as ensureRegistryLogin's `providedClient`). `tot dev` standalone
  * omits it and this establishes its own, as before.
+ * @param {any} args
+ * @param {{ client?: any }} [opts]
  * @returns {Promise<string>} the cached, installed runner tree's root directory.
  */
 export async function ensureRendererArtifact(args, { client: providedClient } = {}) {
@@ -865,11 +873,11 @@ export function probeRunnerVersion(runnerDir, { timeoutMs = 4000 } = {}) {
  * @returns {Promise<string>} the runner tree's root directory (has scripts/tot-dev.mjs).
  */
 export async function ensureSampleRenderer(args, ctx, { env = process.env, cacheRoot = RENDERER_CACHE_ROOT } = {}) {
-  const src = resolveLocalRendererSource({
+  const src = /** @type {any} */ (resolveLocalRendererSource({
     env,
     mode: ctx?.mode,
     repoRoot: ctx?.repoRoot,
-  });
+  }));
 
   if (src.kind === "dir") {
     if (!existsSync(join(src.dir, "scripts", "tot-dev.mjs"))) {
@@ -1063,7 +1071,7 @@ export async function installRunnerTarball(
   // of stopping a first run at an error only `rm -rf` folklore could clear.
   // Bounded to one retry so a genuinely-broken source still fails loudly.
   for (let attempt = 1; ; attempt++) {
-    const archivePath = isUrl ? join(tmpdir(), `tot-renderer-${process.pid}-${attempt}.tar.gz`) : localSource;
+    const archivePath = /** @type {string} */ (isUrl ? join(tmpdir(), `tot-renderer-${process.pid}-${attempt}.tar.gz`) : localSource);
     const stagingDir = `${runnerDir}.staging-${process.pid}`;
     try {
       if (isUrl) {
@@ -1133,7 +1141,7 @@ export async function installRunnerTarball(
             exitCode: 2,
           },
         );
-        err.permanent = true;
+        /** @type {any} */ (err).permanent = true;
         throw err;
       }
       writeCacheMarker(runnerDir, { version, integrity: contentId });
@@ -1285,7 +1293,7 @@ async function downloadFile(url, destPath) {
   if (!res.ok || !res.body) {
     throw new Error(`download failed: HTTP ${res.status} ${res.statusText}`);
   }
-  await pipeline(Readable.fromWeb(res.body), createWriteStream(destPath));
+  await pipeline(Readable.fromWeb(/** @type {any} */ (res.body)), createWriteStream(destPath));
 }
 
 /**
@@ -1334,7 +1342,8 @@ export function ensureCorepackPnpm(runnerDir, { logPath, spawnFn = spawnSync } =
     for (const args of [["enable"], ["prepare", pm, "--activate"]]) {
       const r = spawnFn("corepack", args, { stdio: ["ignore", fd ?? "ignore", fd ?? "ignore"] });
       if (fd !== null && (r.error || r.status !== 0)) {
-        writeSync(fd, `[tot] corepack ${args.join(" ")} → ${r.error?.code || r.error?.message || `exit ${r.status}`}\n`);
+        const rerr = /** @type {any} */ (r.error);
+        writeSync(fd, `[tot] corepack ${args.join(" ")} → ${rerr?.code || rerr?.message || `exit ${r.status}`}\n`);
       }
     }
   } finally {
@@ -1378,6 +1387,10 @@ function spawnAsyncResult(cmd, args, opts = {}) {
   });
 }
 
+/**
+ * @param {string} runnerDir
+ * @param {{ logPath?: string, spawnFn?: (cmd: string, args: string[], opts?: any) => any }} [opts]
+ */
 export async function runPnpmInstall(runnerDir, { logPath, spawnFn = spawnAsyncResult } = {}) {
   const fd = logPath ? openSync(logPath, "a") : null;
   const installArgs = ["install", "--config.dangerouslyAllowAllBuilds=true"];
@@ -1415,7 +1428,7 @@ export async function runPnpmInstall(runnerDir, { logPath, spawnFn = spawnAsyncR
         stdio: ["ignore", fd ?? "ignore", fd ?? "ignore"],
       });
       if (r.status === 0) return; // installed
-      if (r.error?.code === "ENOENT") {
+      if (/** @type {any} */ (r.error)?.code === "ENOENT") {
         // This launcher isn't on the machine — record it and try the next one.
         if (fd !== null) writeSync(fd, `[tot] ${cmd} not found (ENOENT) — trying the next launcher\n`);
         continue;
@@ -1446,7 +1459,7 @@ export async function runPnpmInstall(runnerDir, { logPath, spawnFn = spawnAsyncR
         (logPath ? `\n     details: ${logPath}` : ""),
       { next: "install pnpm with `npm i -g pnpm` (or `corepack enable`), then re-run `tot start`" },
     );
-    err.permanent = true;
+    /** @type {any} */ (err).permanent = true;
     throw err;
   } finally {
     if (fd !== null) closeSync(fd);
@@ -1501,6 +1514,10 @@ function missingPackage404(logPath) {
  * fs-watch HMR. Returns a handle shaped like spawnDevContainer's, so run()'s
  * auto-open-browser logic works unchanged for either runtime. Exported (and
  * `stdio` overridable) so `tot start` can pipe the logs instead of inheriting.
+ * @param {string} runnerDir
+ * @param {string} workspace
+ * @param {string} port
+ * @param {{ stdio?: any, env?: Record<string, any> }} [opts]
  */
 export function spawnNativeDev(runnerDir, workspace, port, { stdio = "inherit", env = {} } = {}) {
   const script = join(runnerDir, "scripts", "tot-dev.mjs");
@@ -1512,7 +1529,7 @@ export function spawnNativeDev(runnerDir, workspace, port, { stdio = "inherit",
   // `env` (e.g. activityBridgeEnv()) merges OVER process.env — {} is a pure
   // passthrough, identical to the old no-env-key behavior. Append `--no-warnings`
   // to NODE_OPTIONS so the runner's Node process never emits the scary
-  // `(node:NNNN) ExperimentalWarning: …` boot noise to the developer (b4);
+  // `(node:NNNN) ExperimentalWarning: …` boot noise to the developer;
   // appended (not replaced) so any host-set NODE_OPTIONS is preserved.
   const mergedEnv = { ...process.env, ...env };
   mergedEnv.NODE_OPTIONS = `${mergedEnv.NODE_OPTIONS ? `${mergedEnv.NODE_OPTIONS} ` : ""}--no-warnings`;
@@ -1521,7 +1538,7 @@ export function spawnNativeDev(runnerDir, workspace, port, { stdio = "inherit",
     [script, "--workspace", workspace, "--port", port],
     { cwd: runnerDir, stdio: stdioArr, env: mergedEnv },
   );
-  const handle = { child, exited: false, done: null };
+  const handle = { child, exited: false, done: /** @type {any} */ (null) };
   handle.done = new Promise((resolvePromise) => {
     child.on("exit", (code) => {
       handle.exited = true;
@@ -1555,7 +1572,7 @@ async function runContainer(workspace, args, ctx) {
   const handle = await spawnDevContainer(plan, args, { stdio: "piped" });
   streamDevLogs(handle.child, { cockpitUrl: cockpitUrlFrom(activityBridgeEnv().TOT_DEV_ACTIVITY_URL) });
 
-  // Heartbeat the hosted cockpit (G1) CLI-side while the container runs — the
+  // Heartbeat the hosted cockpit CLI-side while the container runs — the
   // container reports file-saves via the threaded env, but the CLI owns the
   // version + live URL. Same bridge credential (activityBridgeEnv), no-op absent.
   const stopHeartbeat = startHeartbeatFromEnv(activityBridgeEnv(), { url: plan.url, cwd: plan.workspace });
@@ -1580,7 +1597,7 @@ async function runContainer(workspace, args, ctx) {
 
 /**
  * Resolve the runner image ref the same way buildContainerPlan does — exported
- * so a caller (`tot start`, for C1) can know the image, and therefore prefetch
+ * so a caller (`tot start`) can know the image, and therefore prefetch
  * a registry login (below), before the checkout dir exists.
  */
 export function resolveDevImage(args, env = process.env) {
@@ -1676,9 +1693,9 @@ export async function spawnDevContainer(plan, args, { stdio = "inherit" } = {})
 
   const stdioArr =
     stdio === "piped" ? ["ignore", "pipe", "pipe"] : ["inherit", "inherit", "inherit"];
-  const child = spawn("docker", plan.dockerArgs, { stdio: stdioArr });
+  const child = spawn("docker", plan.dockerArgs, { stdio: /** @type {any} */ (stdioArr) });
 
-  const handle = { child, exited: false, done: null };
+  const handle = { child, exited: false, done: /** @type {any} */ (null) };
   handle.done = new Promise((resolvePromise) => {
     child.on("exit", (code) => {
       handle.exited = true;
@@ -1714,10 +1731,11 @@ export function isPrivateRegistryImage(image) {
  * the session, or the tool isn't available yet, warn softly and continue (an
  * existing `docker login`, or the docker pull error, takes over).
  *
- * Exported + accepts an already-authenticated `client` (C1: `tot start` reuses
+ * Exported + accepts an already-authenticated `client` (`tot start` reuses
  * its own session and overlaps this with the checkout clone instead of paying
  * for a second client.initialize()+establishSession() serially afterward).
  * `tot dev` standalone omits it and this establishes its own, as before.
+ * @param {string} image @param {any} args @param {{ client?: any }} [opts]
  */
 export async function ensureRegistryLogin(image, args, { client: providedClient } = {}) {
   const registry = String(image).split("/")[0];
@@ -1767,7 +1785,7 @@ export function dockerAvailable() {
  * thing `open -a` can launch unattended; other platforms report false and
  * leave it to the caller's usual next-command message). Returns true once
  * Docker answers, false if it doesn't within the wait window. Shared by
- * `tot start`'s preflight and `tot doctor --fix` (F2).
+ * `tot start`'s preflight and `tot doctor --fix`.
  */
 export async function tryStartDocker() {
   if (process.platform !== "darwin") return false;

package/src/commands/doctor.mjs

@@ -6,12 +6,12 @@
  * auth identity is available, and Docker — plus reports the detected context
  * so a developer knows which mode `tot` will use here.
  *
- * Docker is informational-only (not blocking): WS3/F3 made the native runtime
+ * Docker is informational-only (not blocking): the native runtime is
  * the default for `tot dev`/`tot start`, so a Docker that isn't running no
  * longer stops the loop — it only matters if you pass --docker or the native
  * artifact can't be fetched (see dev.mjs#NativeArtifactUnavailableError).
  *
- * `--fix` (F2) auto-remediates what it safely can, each fix announced as it
+ * `--fix` auto-remediates what it safely can, each fix announced as it
  * runs: starts Docker (macOS, opportunistically — harmless even though it's
  * no longer required), creates ~/.tot if it's missing, and signs you in when
  * there's no usable session at all. Anything it can't fix (or won't — a stale
@@ -135,9 +135,9 @@ export function collectChecks(_ctx, env = process.env) {
 
 /**
  * Auto-remediate the checks that are safely fixable without human judgment
- * (F2) — announcing each one as it runs. A stale-but-refreshable sign-in isn't
+ * — announcing each one as it runs. A stale-but-refreshable sign-in isn't
  * handled here because it isn't a failing check: the developer session refreshes
- * it silently the next time it's actually used (B4).
+ * it silently the next time it's actually used.
  */
 async function applyFixes(checks, env) {
   const totDir = join(env.TOT_HOME || homedir(), ".tot");

package/src/commands/git-credential.mjs

@@ -1,7 +1,7 @@
 /**
  * `tot git-credential` — git's own credential-helper protocol (see `git help
  * gitcredentials`), implemented over the developer's cached `tot login`
- * session (unit u10, workstream tot-merge-conflict-resolution-ux). `tot
+ * session. `tot
  * clone` configures a fresh checkout's `credential.helper` to run this (see
  * ../git-credential.mjs's CREDENTIAL_HELPER), so `git fetch`/`git push`/`git
  * pull` — run DIRECTLY by the developer, not just through `tot preview` —
@@ -93,7 +93,7 @@ export function readStdin() {
  * globally-scoped helper (or a checkout with a submodule / unrelated remote)
  * must not become a way to exfiltrate the token to an arbitrary host.
  * @param {{
- *   env?: NodeJS.ProcessEnv, cwd?: string, expectedHost?: string,
+ *   env?: NodeJS.ProcessEnv, cwd?: string, expectedHost?: string|null,
  *   createClient?: typeof createMcpClient,
  *   establish?: typeof establishSession,
  *   checkout?: typeof checkoutTenant,

package/src/commands/go-live.mjs

@@ -1,10 +1,10 @@
 /**
- * `tot go-live` — cut the apex domain over to the storefront (unit u9). The CLI
+ * `tot go-live` — cut the apex domain over to the storefront. The CLI
  * counterpart to the admin Publish tab's Domain "Connect" button: it drives the
  * SAME go-live CI/dispatch the button does (the storefront `/api/domain/dispatch`
  * → `www-domain` repository_dispatch → `cutover-dns.mjs`), gated by the SAME
  * server-authoritative readiness gate the admin display reads
- * (`GET /api/domain/readiness`, unit u9). This command CONSUMES those seams — it
+ * (`GET /api/domain/readiness`). This command CONSUMES those seams — it
  * does NOT reimplement the DNS cutover, the readiness policy, or the revert.
  *
  *   tot go-live               show apex readiness, then (if ready) connect the apex
@@ -19,7 +19,7 @@
  *      revert). Fail-closed: a CONNECT is refused unless the server reports
  *      `ready:true` — the CLI never recomputes readiness, it reads the same gate
  *      the cutover is governed by, so they cannot diverge.
- *   2. Owner-only: the server resolves owner capability (u10); a non-owner is
+ *   2. Owner-only: the server resolves owner capability; a non-owner is
  *      DENIED with the itemized reason. The CLI does not assert ownership itself.
  *   3. ALWAYS require ONE explicit [y/N] confirm (default NO). There is NO
  *      `--yes`/`--force`; in a NON-TTY (CI, piped) it REFUSES rather than
@@ -196,6 +196,9 @@ export function renderReadiness({ appDomain, readiness, action }) {
   const lines = ["", `  Apex ${action === "rollback" ? "rollback" : "cutover"} readiness for ${appDomain ?? "this store"}:`];
   for (const c of readiness.checks) {
     lines.push(`    ${c.ok ? "✓" : "✗"} ${c.label}${c.detail ? ` — ${c.detail}` : ""}`);
+    // Blocked checks carry a "how to clear this" remedy from the server gate —
+    // the same guidance the admin panel shows, so the two surfaces never diverge.
+    if (!c.ok && c.remedy) lines.push(`        → ${c.remedy}`);
   }
   if (action === "connect") {
     lines.push(
@@ -217,6 +220,7 @@ export function renderReadiness({ appDomain, readiness, action }) {
  * assuming it from the dispatch. Injectable delay/attempts. Returns the last
  * normalised run status (may still be "dispatched" if CI is slow — reported honestly).
  * @param {{ get:(path:string)=>Promise<any> }} http
+ * @param {{ attempts?: number, delayMs?: number, sleep?: Function }} [opts]
  */
 export async function pollRunTerminal(http, { attempts = 8, delayMs = 2000, sleep } = {}) {
   const wait = sleep || ((ms) => new Promise((r) => setTimeout(r, ms)));
@@ -391,7 +395,7 @@ function cap(s) {
  * ship floor. Throws on a non-2xx with the server's error message (so the caller
  * surfaces the real refusal). `fetchImpl` is injectable for tests.
  * @param {string} base
- * @param {{ token:string|undefined, owner:string, capability?:string, fetchImpl?:typeof fetch }} auth
+ * @param {{ token?:string, owner?:string, capability?:string, fetchImpl?:typeof fetch }} [auth]
  */
 export function createStorefrontHttp(base, { token, owner, capability = "ship-on-behalf", fetchImpl } = {}) {
   const root = base.replace(/\/+$/, "");
@@ -476,7 +480,7 @@ export async function run(argv, ctx) {
   const http = createStorefrontHttp(base, { token, owner });
   return await runGoLive(
     http,
-    { appDomain: owner, action: args.action, rehearsal: args.rehearsal, noOpen: args.noOpen },
+    { appDomain: owner, action: /** @type {any} */ (args.action), rehearsal: args.rehearsal, noOpen: args.noOpen },
     { openUrl: (u) => openBrowser(u) },
   );
 }

package/src/commands/grants.mjs

@@ -61,9 +61,10 @@ function parseArgs(argv) {
  *   exp: number|null, revokedAt: string|null }> }}
  */
 export function normalizeGrantRows(resp) {
-  if (resp && typeof resp === "object" && !Array.isArray(resp) && Array.isArray(resp.grants)) {
-    const activeTenant = typeof resp.activeTenant === "string" ? resp.activeTenant : null;
-    const rows = resp.grants
+  const rr = /** @type {any} */ (resp);
+  if (resp && typeof resp === "object" && !Array.isArray(resp) && Array.isArray(rr.grants)) {
+    const activeTenant = typeof rr.activeTenant === "string" ? rr.activeTenant : null;
+    const rows = rr.grants
       .map((g) => {
         const tenant = g?.tenant ?? g?.id ?? null;
         return {
@@ -83,7 +84,7 @@ export function normalizeGrantRows(resp) {
 
   // Fallback: client_list — store ids + environment + the selected marker only. No
   // grant detail is knowable here (grantActive/capability/tier/exp/revokedAt stay null).
-  const clients = Array.isArray(resp) ? resp : resp?.clients || resp?.tenants || [];
+  const clients = Array.isArray(resp) ? resp : rr?.clients || rr?.tenants || [];
   const rows = (Array.isArray(clients) ? clients : [])
     .map((c) => ({
       tenant: c?.tenant ?? c?.id ?? c?.clientId ?? c?.appDomain ?? null,
@@ -147,6 +148,7 @@ export function formatExpiry(exp, { now = Date.now() } = {}) {
 export function describeGrantRow(row, { now = Date.now() } = {}) {
   const status = grantStatus(row, { now });
   if (status === "unknown") return "grant detail unavailable (server introspection not enabled)";
+  /** @type {string[]} */
   const parts = [status];
   if (row.capability) parts.push(`capability=${row.capability}`);
   if (row.tier) parts.push(`tier=${row.tier}`);
@@ -238,7 +240,7 @@ export async function run(argv, _ctx) {
     return 1;
   }
   if (rows.length === 0) {
-    // Status-aware, like whoami/checkout (card c2): an UNLINKED identity is told to
+    // Status-aware, like whoami/checkout: an UNLINKED identity is told to
     // link, not given the "may still be propagating" copy — that's only the genuine
     // linked-but-zero-grants case.
     const g = noStoresGuidance(resp);

package/src/commands/hotfix.mjs

@@ -1,5 +1,5 @@
 /**
- * `tot hotfix` (unit b22) — the OWNER-ONLY EXCEPTION LANE: release an urgent
+ * `tot hotfix` — the OWNER-ONLY EXCEPTION LANE: release an urgent
  * production fix from `main` to live WHILE `preview` still contains other unshipped
  * work, EXCLUDING that unshipped preview head, then automatically forward-integrate
  * `main` into `preview` and re-validate.

package/src/commands/ideas.mjs

@@ -1,11 +1,11 @@
 /**
- * `tot ideas` — a gallery of copy-paste reskin prompts that reliably wow (G3).
+ * `tot ideas` — a gallery of copy-paste reskin prompts that reliably wow.
  * Not a script to run — inspiration for the AI moment: paste one into Claude
  * (after `tot start`'s "Connect Claude?" prompt, or `claude mcp add` directly)
  * and watch your store change and reload.
  *
  * IDEAS[0] doubles as the seeded first prompt `tot start` ends on and drops
- * you into (G2, see commands/start.mjs) — one list, no drift between the two.
+ * you into (see commands/start.mjs) — one list, no drift between the two.
  */
 
 /** Reskin prompts, ordered strongest-first. Pure data — exported for reuse + tests. */

package/src/commands/link.mjs

@@ -54,7 +54,7 @@ Run this when \`tot whoami\` / \`tot start\` say your identity isn't linked yet.
  * @returns {{ authUrl: string|null, pollHandle: string|null }}
  */
 export function linkBeginFields(res) {
-  const c = res && typeof res === "object" && !Array.isArray(res) ? res : {};
+  const c = /** @type {any} */ (res && typeof res === "object" && !Array.isArray(res) ? res : {});
   const authUrl =
     c.authUrl ||
     c.url ||
@@ -77,7 +77,7 @@ export function linkBeginFields(res) {
  * @returns {"linked"|"pending"|string}
  */
 export function linkPollStatus(res) {
-  const c = res && typeof res === "object" && !Array.isArray(res) ? res : {};
+  const c = /** @type {any} */ (res && typeof res === "object" && !Array.isArray(res) ? res : {});
   if (c.linked === true || c.done === true || c.complete === true) return "linked";
   const raw =
     (typeof c.status === "string" && c.status) || (typeof c.state === "string" && c.state) || "";

package/src/commands/login.mjs

@@ -11,7 +11,7 @@
  * TOT_MCP_URL, else the production MCP) so the cached token matches where it's
  * spent — point both at qa with `--mcp https://mcp.qa.tokenoftrust.com` or the env.
  *
- * B3 — `--device` forces the RFC 8628 device-code flow (headless/SSH/no-browser:
+ * `--device` forces the RFC 8628 device-code flow (headless/SSH/no-browser:
  * print a code, poll until it's approved elsewhere). It's also the automatic
  * fallback for a bare `tot login` when there's no browser opener on this box at
  * all (oauth.mjs's loopback flow would otherwise hang forever waiting for a
@@ -116,11 +116,11 @@ After signing in, run \`tot whoami\` to confirm, then \`tot clone\` / \`tot subm
  * device-code flow if `device` is set or the loopback can't be reached at
  * all) and cache the result, reusing a previously-registered client for THIS
  * MCP so we don't re-register (and burn the DCR rate limit) on every login.
- * Exported so `tot doctor --fix` (F2) can re-login as an auto-remediation
+ * Exported so `tot doctor --fix` can re-login as an auto-remediation
  * without duplicating this.
  * @returns {Promise<object>} the credentials written to disk.
  */
-export async function loginAndCache(mcpUrl, env = process.env, { log = () => {}, device = false } = {}) {
+export async function loginAndCache(mcpUrl, env = process.env, { log = /** @type {(m?: string) => void} */ (() => {}), device = false } = {}) {
   const path = defaultCredentialsPath(env);
   const prior = readCredentials(path);
   const clientId = prior && prior.mcpUrl === mcpUrl ? prior.clientId : undefined;
@@ -196,11 +196,10 @@ export async function offerSignIn(mcpUrl, env = process.env, {
  * `log` carries the fingerprint + "waiting for approval" lines to the terminal.
  * @returns {Promise<object>} the credentials written to disk.
  */
-export async function redeemAndCache(mcpUrl, code, env = process.env, { log = () => {} } = {}) {
+export async function redeemAndCache(mcpUrl, code, env = process.env, { log = /** @type {(m?: string) => void} */ (() => {}) } = {}) {
   const path = defaultCredentialsPath(env);
   const prior = readCredentials(path);
-  const clientId = prior && prior.mcpUrl === mcpUrl ? prior.clientId : undefined;
-  const creds = await rendezvousLoginFlow({ mcpUrl, clientId, code, log });
+  const creds = await rendezvousLoginFlow({ mcpUrl, code, log });
   const merged = mergeActivityBridge(prior, mcpUrl, creds);
   writeCredentials(path, merged);
   return merged;

package/src/commands/pr.mjs

@@ -7,7 +7,7 @@
  *   tot pr close <N|id>  close (reject) a candidate without merging
  *
  * A candidate PR is the reviewable unit `tot submit` creates. By default a
- * re-submit UPDATES your open candidate; `tot submit --new` forks another. This
+ * re-submit UPDATES your open candidate; `tot submit --fork-candidate` forks another. This
  * command fills the gap the raw submit loop left — a first-party way to list your
  * open candidates and to close one (candidate close was otherwise gated to
  * version-control apps only).
@@ -17,9 +17,9 @@
  * `candidate_status` / `candidate_close` tools. Dependency-free (global fetch +
  * `git`).
  *
- * OPERATOR MODE (unit U17). `tot pr list --tenant <t>` lists a tenant's OPEN
+ * OPERATOR MODE. `tot pr list --tenant <t>` lists a tenant's OPEN
  * candidate queue WITHOUT a checkout — the read-only companion to `tot ship --pr <N>
- * --tenant <t>` (U16). It reuses U16's exact transport: the SAME `GET /api/changes`
+ * --tenant <t>`. It reuses that command's exact transport: the SAME `GET /api/changes`
  * HTTP endpoint + operator-secret Bearer auth (`resolveOperatorSecret`,
  * `normalizeChangesQueue` from ship.mjs). `view`/`close` stay developer-only.
  */
@@ -28,9 +28,8 @@ import { createMcpClient } from "../mcp.mjs";
 import { establishSession, AuthUnavailableError } from "../auth.mjs";
 import { fail } from "../errors.mjs";
 import { repoNameFromRemote, currentBranch } from "./submit.mjs";
-// U17 reuses U16's operator-secret transport helpers verbatim (same env precedence,
-// same queue normalisation) so the operator `tot pr list` and `tot ship --pr` speak
-// one wire, not two.
+// `tot pr list` reuses `tot ship --pr`'s operator-secret transport helpers verbatim
+// (same env precedence, same queue normalisation) so the two speak one wire, not two.
 import { resolveOperatorSecret, normalizeChangesQueue } from "./ship.mjs";
 import {
   defaultCandidateStatePath,
@@ -71,7 +70,7 @@ const USAGE = `tot pr — see and manage candidate PRs
 
   DEVELOPER (default) — run inside your OWN store checkout: lists/manages the
   candidates \`tot submit\` opens. A re-submit updates your open one by default;
-  \`tot submit --new\` forks another.
+  \`tot submit --fork-candidate\` forks another.
 
   OPERATOR — \`tot pr list --tenant <appDomain>\` lists ANY tenant's open candidate
   queue WITHOUT a checkout (the read-only companion to \`tot ship --pr <N> --tenant\`).
@@ -135,8 +134,8 @@ export function matchCandidate(candidates, target) {
 
 /**
  * One-line candidate summary for `tot pr list` — surfaces branch ↔ PR# ↔ preview
- * URL so a dev sees, at a glance, which git branch each candidate belongs to (u4 —
- * branch-bound candidates) and where its preview lives. ONLY `previewUrl` (the
+ * URL so a dev sees, at a glance, which git branch each candidate belongs to
+ * (branch-bound candidates) and where its preview lives. ONLY `previewUrl` (the
  * storefront-owned `/preview/<tenant>/pr/<N>` link) — NEVER `url` (the forge/
  * Gitea `html_url`), which must never reach a terminal (2026-08-18 incident:
  * a raw forge PR URL reached an owner). `active` marks the one
@@ -153,10 +152,10 @@ export function formatCandidateLine(c, { active = false } = {}) {
   return `  PR ${pr}  ${branch}  ${c.changeId}  [${c.state ?? "?"}]${urlPart}${activePart}`;
 }
 
-// ─── Operator queue listing (unit U17) ──────────────────────────────────────────────
+// ─── Operator queue listing ──────────────────────────────────────────────────────────
 //
-// The read-only companion to `tot ship --pr <N> --tenant <t>` (U16): list a tenant's
-// OPEN candidate queue WITHOUT a checkout. It reuses U16's exact transport — the SAME
+// The read-only companion to `tot ship --pr <N> --tenant <t>`: list a tenant's
+// OPEN candidate queue WITHOUT a checkout. It reuses that command's exact transport — the SAME
 // `GET /api/changes` endpoint (operator accept queue) + Bearer operator-secret auth
 // (`resolveOperatorSecret` / `normalizeChangesQueue` from ship.mjs) — so a listing and
 // a ship read one wire. NO merge/deploy/side-effect; pure listing.
@@ -172,8 +171,15 @@ export function formatCandidateLine(c, { active = false } = {}) {
  *     sees it's listable but must `tot preview build` before it can ship.
  * Adapts `formatCandidateLine`'s house style to the `GET /api/changes` shape (`status`
  * not `state`; `previewUrl`; a `headSha` to short-render). Pure — unit-tested.
+ *
+ * A built row whose `evidence.pushFailed` is set (the MCP `change_report_evidence`
+ * push never landed — fb-1787938036559-ppmu4e) gets a `[evidence push failed]` tag
+ * + a `tot preview retry-evidence` hint, so the gap between "storefront thinks this
+ * is promotable" and "MCP has no evidence for it" is visible right where an
+ * operator is already looking, not just in the activity log.
  * @param {{prNumber?:number|null, status?:string|null, changeId?:string|null,
- *   headSha?:string|null, previewUrl?:string|null, built?:boolean}} c
+ *   headSha?:string|null, previewUrl?:string|null, built?:boolean,
+ *   evidence?:{pushFailed?:boolean}|null}} c
  * @returns {string}
  */
 export function formatOperatorCandidateLine(c) {
@@ -190,6 +196,13 @@ export function formatOperatorCandidateLine(c) {
   }
   const status = c.status ?? "?";
   const urlPart = c.previewUrl ? `  ${c.previewUrl}` : "";
+  if (c.evidence?.pushFailed) {
+    const retryHint =
+      typeof c.prNumber === "number"
+        ? `  → tot preview retry-evidence --pr ${c.prNumber}`
+        : "  → tot preview retry-evidence";
+    return `  PR ${pr}  [${status}]  [evidence push failed]  ${c.changeId}  ${head}${urlPart}${retryHint}`;
+  }
   return `  PR ${pr}  [${status}]  ${c.changeId}  ${head}${urlPart}`;
 }
 
@@ -210,7 +223,7 @@ export function sortQueueByPrDesc(changes) {
 /**
  * The OPERATOR `tot pr list --tenant <t>` flow: fetch the tenant's OPEN candidate
  * queue over `GET /api/changes` (Bearer operator secret + `X-Tot-Owner` +
- * `x-tot-capability: ship-on-behalf`, mirroring U16) and print each candidate one per
+ * `x-tot-capability: ship-on-behalf`) and print each candidate one per
  * line, sorted by PR number desc. Fail-closed: no secret → honest refusal (exit 2)
  * BEFORE any network. `fetch` is injected so it's unit-tested with no live network.
  *
@@ -225,8 +238,9 @@ export async function runPrListOperator({ tenant, secret, storefrontUrl = null }
   if (!secret) {
     console.error(
       fail(
-        "listing a tenant's queue is an OPERATOR action — it needs an operator secret",
-        "set PREVIEW_RECONCILE_SECRET (or GRANTS_ADMIN_SECRET / TOT_OPERATOR_SECRET), or pass --secret",
+        "no operator secret — view this tenant's queue from the storefront admin instead.",
+        `open  https://${tenant}/admin  → Publish tab to see the candidate queue and act on it. ` +
+          "Operators/CI: set PREVIEW_RECONCILE_SECRET (or GRANTS_ADMIN_SECRET / TOT_OPERATOR_SECRET), or pass --secret.",
       ),
     );
     return 2;
@@ -287,12 +301,12 @@ export async function run(argv, ctx) {
     console.log(USAGE);
     return 0;
   }
-  if (!SUBCOMMANDS.includes(args.sub)) {
+  if (!SUBCOMMANDS.includes(/** @type {any} */ (args.sub))) {
     console.error(fail(`unknown subcommand: \`tot pr ${args.sub}\``, "tot pr list | view <N> | close <N>"));
     return 2;
   }
 
-  // OPERATOR MODE (U17): `--tenant <t>` lists that tenant's OPEN candidate queue with
+  // OPERATOR MODE: `--tenant <t>` lists that tenant's OPEN candidate queue with
   // NO checkout, over the same HTTP transport `tot ship --pr` uses. Only `list` has an
   // operator path today — `view`/`close` stay developer-only (checkout-bound).
   if (args.tenant && `${args.tenant}`.trim()) {
@@ -347,7 +361,7 @@ export async function run(argv, ctx) {
   const baseUrl = args.mcp || env.MCP_BASE_URL || env.TOT_MCP_URL || DEFAULT_MCP_URL;
   const storefrontUrl = args.url || env.TOT_STOREFRONT_URL || env.STOREFRONT_BASE_URL || DEFAULT_STOREFRONT_URL;
   const statePath = defaultCandidateStatePath(env);
-  // Branch-bound (u4): the active-pointer namespace is scoped to the current git
+  // Branch-bound: the active-pointer namespace is scoped to the current git
   // branch, so the "← active" marker reflects THIS branch's candidate.
   const scope = { mcpUrl: baseUrl, repo, branch: currentBranch(gitSafe) };
   const client = createMcpClient(baseUrl);

package/src/commands/preview-build.mjs

@@ -1,10 +1,10 @@
 /**
- * `tot preview build --tenant <t> --pr <N>` — OPERATOR build-on-demand (unit U3).
+ * `tot preview build --tenant <t> --pr <N>` — OPERATOR build-on-demand.
  *
  * Materialize ANY PR's hosted preview (including one that isn't yours, and one that
  * was orphaned — its webhook never processed so it has no ReviewEnvironment). It
- * calls the session-authenticated storefront endpoint `POST /api/preview/build`
- * (unit U1), which runs the EXISTING `reconcileCandidate` against the PR head. The
+ * calls the session-authenticated storefront endpoint `POST /api/preview/build`,
+ * which runs the EXISTING `reconcileCandidate` against the PR head. The
  * CLI passes the KNOWN descriptor (the head sha it holds), so there is NO forge
  * PR-read dependency: reconcile reads the tenant files at that sha (content-addressed).
  *
@@ -22,9 +22,9 @@
  * URL) and confirms before acting (`--yes` to skip; a non-TTY without `--yes`
  * aborts rather than acting silently). Build-on-demand is INERT — it flips no shared
  * channel and is not go-live — so this is a materialize, not a deploy. The plan
- * itself is built by the SHARED plan module (`../plan.mjs`, unit U10) — the same
- * affordance every other mutating operator verb (accept/ship/retire) and the
- * `/admin` confirm dialog use, per decision `operator-verb-and-hosting-model`.
+ * itself is built by the SHARED plan module (`../plan.mjs`) — the same
+ * affordance every other mutating operator verb (accept/ship/reject) and the
+ * `/admin` confirm dialog use.
  *
  * Dependency-free (global fetch + `git` for the optional head-sha default).
  */