@tokenoftrust/cli 1.4.0 → 1.5.0

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,
@@ -42,6 +41,24 @@ const DEFAULT_MCP_URL = "https://mcp.tokenoftrust.com";
 const DEFAULT_STOREFRONT_URL = "https://storefront.tokenoftrust.store";
 const SUBCOMMANDS = ["list", "view", "close"];
 
+/**
+ * The storefront-owned, shareable `/preview/<tenant>/pr/<N>` link — NEVER the
+ * forge/Gitea `url` (2026-08-18 incident: a raw forge PR URL reached an
+ * owner). `candidate_status` (the local-checkout MCP tool) has no
+ * `previewUrl` field at all, unlike the operator `GET /api/changes` path — so
+ * this constructs it the same way `runPrListOperator`'s caller resolves
+ * `storefrontUrl`, from the same env/--url override chain. Pure.
+ * @param {string} storefrontUrl
+ * @param {string} tenant
+ * @param {number|null|undefined} prNumber
+ * @returns {string|null}
+ */
+export function buildPreviewUrl(storefrontUrl, tenant, prNumber) {
+  if (typeof prNumber !== "number" || !tenant) return null;
+  const base = (storefrontUrl || DEFAULT_STOREFRONT_URL).trim().replace(/\/+$/, "");
+  return `${base}/preview/${tenant}/pr/${prNumber}`;
+}
+
 const USAGE = `tot pr — see and manage candidate PRs
 
   tot pr [list]              list your open candidate PRs for this store
@@ -53,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\`).
@@ -117,10 +134,12 @@ 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. Prefers the candidate's
- * `previewUrl`, falling back to the PR `url`. `active` marks the one THIS checkout's
- * branch resolves to. Pure — unit-tested.
+ * 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
+ * THIS checkout's branch resolves to. Pure — unit-tested.
  * @param {{prNumber?:number|null, branch?:string|null, changeId:string, state?:string|null,
  *   previewUrl?:string|null, url?:string|null}} c
  * @param {{ active?: boolean }} [opts]
@@ -128,16 +147,15 @@ export function matchCandidate(candidates, target) {
 export function formatCandidateLine(c, { active = false } = {}) {
   const pr = typeof c.prNumber === "number" ? `#${c.prNumber}` : "#—";
   const branch = c.branch ? c.branch : "(no branch)";
-  const previewUrl = c.previewUrl || c.url || null;
-  const urlPart = previewUrl ? `  ${previewUrl}` : "";
+  const urlPart = c.previewUrl ? `  ${c.previewUrl}` : "";
   const activePart = active ? "  ← active" : "";
   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.
@@ -153,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) {
@@ -171,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}`;
 }
 
@@ -191,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.
  *
@@ -206,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;
@@ -268,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()) {
@@ -326,8 +359,9 @@ 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);
@@ -347,7 +381,8 @@ export async function run(argv, ctx) {
       const active = readActiveChangeId(statePath, scope);
       console.log(`Open candidate PRs for ${repo}:`);
       for (const c of candidates) {
-        console.log(formatCandidateLine(c, { active: !!active && c.changeId === active }));
+        const previewUrl = c.previewUrl ?? buildPreviewUrl(storefrontUrl, tenant, c.prNumber);
+        console.log(formatCandidateLine({ ...c, previewUrl }, { active: !!active && c.changeId === active }));
       }
       return 0;
     }
@@ -366,7 +401,9 @@ export async function run(argv, ctx) {
       if (match.headSha) console.log(`  head:             ${match.headSha}`);
       if (match.baseSha) console.log(`  base:             ${match.baseSha}`);
       console.log(`  mergeable (forge): ${match.mergeable ?? "?"}`);
-      if (match.url) console.log(`  ${match.url}`);
+      // ONLY the storefront-owned preview link -- never the raw forge/Gitea `url`.
+      const previewUrl = match.previewUrl ?? buildPreviewUrl(storefrontUrl, tenant, match.prNumber);
+      if (previewUrl) console.log(`  ${previewUrl}`);
       return 0;
     }
 

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).
  */

package/src/commands/preview-doctor.mjs

@@ -0,0 +1,225 @@
+/**
+ * `tot preview doctor --tenant <t>` — the merge self-serve DIAGNOSIS in the terminal.
+ *
+ * Calls the hosted merge-doctor seam `GET /<tenant>/api/preview/merge-doctor`
+ * — which composes the SAME two server-side reads the admin Publish tab builds
+ * (`GET /api/changes` + `GET /api/changes/branches`) through the PURE `analyzeMerge`
+ * taxonomy — and prints its `{ scopeKnown, verdict, findings, counts }` as the compact,
+ * ordered (blocker → warn → info) report, each finding carrying who-owns-it and its
+ * remedy/action. It composes NO per-PR forge calls of its own: one GET, one answer.
+ *
+ * READ-ONLY — it mutates nothing, so there is NO plan/confirm gate (unlike `tot
+ * accept` / `tot preview build`). It just answers "what's blocking my merges, and
+ * what do I do about it?" in seconds.
+ *
+ * AUTH — the endpoint is session-gated exactly like `GET /api/changes`, so this
+ * reaches it by EITHER of the two transports `tot accept` already speaks:
+ *   - OPERATOR SECRET (operators / headless CI): Bearer + `X-Tot-Owner` on the
+ *     generic storefront origin (from PREVIEW_RECONCILE_SECRET / GRANTS_ADMIN_SECRET
+ *     / TOT_OPERATOR_SECRET, or `--secret`).
+ *   - VIEWER SESSION (an invited developer with no secret): mint a `tot_session`
+ *     from their own `tot login` on the tenant's own host (`resolveViewerTransport`).
+ * A caller who cannot see the accept queue cannot get a diagnosis of it — an auth
+ * refusal (401/403) is relayed as a clean house-style failure, not a wrapped verdict.
+ *
+ * EXIT CODE — mirrors the `scripts/tenant/gitea-merge-doctor.mjs` driver: a report
+ * with any blocker exits 1 (so a CI gate fails on a blocked merge), otherwise 0.
+ *
+ * The rendering helpers are the SHARED port in `../merge-doctor-report.mjs` (a
+ * faithful PORT of the analyzer's own `formatReport`/`attentionBanner`/
+ * `supportContext` — mergeDoctor.ts §render / the gitea-merge-doctor.mjs mirror);
+ * this package is the dependency-free published `@tokenoftrust/cli`, so it cannot
+ * import the app/scripts source, and the port is kept in sync with that taxonomy by
+ * hand. They live in their own module so `tot accept` / `tot ship` can reuse the same
+ * fetch + compact render without a cycle back through this command's transports.
+ *
+ * Dependency-free (global fetch + the shared viewer/operator transports).
+ */
+import { fail } from "../errors.mjs";
+import { resolveOperatorSecret } from "./ship.mjs";
+import { resolveViewerTransport } from "../viewer-session.mjs";
+import {
+  DOCTOR_PATH,
+  normalizeAnalysis,
+  attentionBanner,
+  supportContext,
+  formatReport,
+} from "../merge-doctor-report.mjs";
+
+const DEFAULT_STOREFRONT_URL = "https://storefront.tokenoftrust.store";
+
+const USAGE = `tot preview doctor — diagnose what's blocking this tenant's merges
+
+  tot preview doctor                    diagnose the current checkout's tenant
+  tot preview doctor --tenant <t>       diagnose <t> (works without a checkout)
+  tot preview doctor --json             emit the raw { scopeKnown, verdict, findings, counts }
+
+  Calls the hosted merge-doctor (GET /api/preview/merge-doctor), which composes the
+  SAME reads the admin Publish tab builds and runs them through the shared analyzer,
+  and prints the ordered report: blockers first, then warnings, then info — each
+  finding names who resolves it (you / on-us / housekeeping) and the exact remedy.
+  Read-only: it mutates nothing and needs no confirmation.
+
+  Exit code: 1 if the report has any blocker (so it can gate CI), else 0.
+
+Options:
+  --tenant <appDomain>   Target tenant (e.g. tokenoftrust.com). Defaults to the
+                         current checkout's tenant when run inside one.
+  --url <origin>         Storefront origin for the operator-secret path
+                         (default: env TOT_STOREFRONT_URL or ${DEFAULT_STOREFRONT_URL}).
+  --secret <s>           Operator secret (prefer the env vars below).
+  --json                 Print the raw analysis JSON instead of the report.
+  --help, -h             Show this help.
+
+  Operator secret (from env, first found): PREVIEW_RECONCILE_SECRET,
+  GRANTS_ADMIN_SECRET, TOT_OPERATOR_SECRET (or pass --secret). Without one, an
+  invited developer's own \`tot login\` session is used.`;
+
+/** Parse `tot preview doctor` argv. Pure — unit-testable. */
+export function parsePreviewDoctorArgs(argv) {
+  const a = { tenant: null, url: null, secret: null, json: false, help: false };
+  for (let i = 0; i < argv.length; i++) {
+    const t = argv[i];
+    if (t === "--tenant") a.tenant = argv[++i];
+    else if (t === "--url") a.url = argv[++i];
+    else if (t === "--secret") a.secret = argv[++i];
+    else if (t === "--json") a.json = true;
+    else if (t === "--help" || t === "-h") a.help = true;
+  }
+  return a;
+}
+
+// The render/normalize helpers (normalizeAnalysis / attentionBanner /
+// supportContext / formatReport) are the shared port in ../merge-doctor-report.mjs,
+// imported at the top of this file.
+
+// ── run ────────────────────────────────────────────────────────────────────────
+
+/**
+ * Fetch + render the merge-doctor report for one tenant. Resolves the SAME two
+ * transports `tot accept` uses (operator secret → generic origin + X-Tot-Owner;
+ * else viewer session → tenant host + cookie), GETs the hosted seam, and prints the
+ * ordered report (or raw JSON). `fetch`/`resolveViewerTransport` are injected so it
+ * is unit-tested with no network. Returns the process exit code (blocker → 1).
+ *
+ * @param {{ tenant:string, secret:string, storefrontUrl?:string|null,
+ *   json?:boolean, env?:NodeJS.ProcessEnv }} params
+ * @param {{ fetch?:typeof fetch, resolveViewerTransport?:typeof resolveViewerTransport }} [deps]
+ * @returns {Promise<number>}
+ */
+export async function runDoctor(
+  { tenant, secret, storefrontUrl = null, json = false, env = process.env },
+  deps = {},
+) {
+  const fetchImpl = deps.fetch || globalThis.fetch;
+  const resolveViewer = deps.resolveViewerTransport || resolveViewerTransport;
+
+  // Resolve the transport — operator secret preferred, else the developer's own
+  // viewer session on the tenant host.
+  let base;
+  let authHeaders;
+  if (secret) {
+    base = (storefrontUrl || DEFAULT_STOREFRONT_URL).trim().replace(/\/+$/, "");
+    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;
+    authHeaders = viewer.authHeaders;
+  }
+
+  let res;
+  try {
+    res = await fetchImpl(`${base}${DOCTOR_PATH}`, { method: "GET", headers: authHeaders });
+  } catch (e) {
+    console.error(
+      fail(
+        `couldn't reach the merge-doctor at ${base}: ${String(e?.message || e)}`,
+        "check --url / your network, then re-run",
+      ),
+    );
+    return 1;
+  }
+
+  let data = {};
+  try {
+    data = await res.json();
+  } catch {
+    /* non-JSON / empty body */
+  }
+
+  // Session gating: the endpoint relays the queue read's auth refusal verbatim, so a
+  // caller who cannot see the accept queue cannot diagnose it.
+  if (res.status === 401 || res.status === 403) {
+    console.error(
+      fail(
+        `not authorized to diagnose ${tenant}'s merges: ${data?.error || `HTTP ${res.status}`}`,
+        "you need a live ship-on-behalf grant on this tenant (ask the store owner), or an operator secret authorised for it — then re-run",
+      ),
+    );
+    return 2;
+  }
+
+  if (!res.ok) {
+    console.error(
+      fail(
+        `the merge-doctor did not answer for ${tenant}: ${data?.error || `HTTP ${res.status}`}`,
+        "check --tenant / --url, then re-run",
+      ),
+    );
+    return 1;
+  }
+
+  const analysis = normalizeAnalysis(data);
+
+  if (json) {
+    console.log(JSON.stringify(analysis, null, 2));
+  } else {
+    console.log(formatReport(analysis));
+  }
+
+  // Mirror the scripts driver: any blocker fails the run so a CI gate catches it.
+  return analysis.counts.blocker > 0 ? 1 : 0;
+}
+
+/**
+ * @param {string[]} argv
+ * @param {any} ctx — detected CLI context (ctx.tenant when in a checkout)
+ */
+export async function run(argv, ctx) {
+  const env = process.env;
+  const args = parsePreviewDoctorArgs(argv);
+  if (args.help) {
+    console.log(USAGE);
+    return 0;
+  }
+
+  const tenant = (args.tenant || ctx?.tenant || "").trim();
+  if (!tenant) {
+    console.error(
+      fail(
+        "no target tenant.",
+        "pass --tenant <appDomain> (e.g. --tenant tokenoftrust.com), or run inside a store checkout.",
+      ),
+    );
+    return 2;
+  }
+
+  const storefrontUrl =
+    args.url || env.TOT_STOREFRONT_URL || env.STOREFRONT_BASE_URL || DEFAULT_STOREFRONT_URL;
+
+  return await runDoctor({
+    tenant,
+    secret: resolveOperatorSecret(args.secret, env),
+    storefrontUrl,
+    json: args.json,
+    env,
+  });
+}

package/src/commands/preview-retry-evidence.mjs

@@ -0,0 +1,156 @@
+/**
+ * `tot preview retry-evidence --tenant <t> --pr <N>` — OPERATOR recovery verb.
+ *
+ * Re-push evidence for an ALREADY-BUILT candidate whose `change_report_evidence`
+ * push to MCP failed (surfaced as `evidence.pushFailed` on the candidate — see
+ * `formatOperatorCandidateLine`'s `[evidence push failed]` tag in `tot pr list
+ * --tenant`). Calls the session-authenticated `POST
+ * /api/changes/candidate-evidence-retry`, which recomputes + re-pushes evidence
+ * for the candidate's EXISTING version — no rebuild, no new content, safe to
+ * run repeatedly.
+ *
+ * DISTINCT FROM `tot preview build`: build re-runs the full reconcile against a
+ * head sha (for an orphaned/never-built PR). This targets an ALREADY-ready
+ * candidate whose content is fine but whose evidence never reached MCP — a
+ * narrower, cheaper fix for fb-1787938036559-ppmu4e.
+ *
+ * AUTH — same headless Bearer-operator-secret path as `tot preview build`:
+ * `Authorization: Bearer <secret>`, `X-Tot-Owner: <tenant>`,
+ * `X-Tot-Capability: ship-on-behalf`.
+ *
+ * Non-destructive + idempotent — no confirmation prompt.
+ *
+ * Dependency-free (global fetch).
+ */
+const DEFAULT_STOREFRONT_URL = "https://storefront.tokenoftrust.store";
+
+/** Parse `tot preview retry-evidence` argv. Pure — unit-testable. */
+export function parseRetryEvidenceArgs(argv) {
+  const a = { tenant: null, pr: null, changeId: null, url: null, secret: null, help: false };
+  for (let i = 0; i < argv.length; i++) {
+    const t = argv[i];
+    if (t === "--tenant") a.tenant = argv[++i];
+    else if (t === "--pr") a.pr = argv[++i];
+    else if (t === "--change-id") a.changeId = argv[++i];
+    else if (t === "--url") a.url = argv[++i];
+    else if (t === "--secret") a.secret = argv[++i];
+    else if (t === "--help" || t === "-h") a.help = true;
+  }
+  return a;
+}
+
+export function renderUsage() {
+  return `tot preview retry-evidence — operator recovery: re-push a candidate's evidence to MCP
+
+Usage:
+  tot preview retry-evidence --tenant <appDomain> --pr <N> [options]
+  tot preview retry-evidence --tenant <appDomain> --change-id <id> [options]
+
+Re-computes and re-pushes evidence for an ALREADY-BUILT candidate whose MCP
+push failed (shown as "[evidence push failed]" in \`tot pr list --tenant\`).
+Does NOT rebuild or change content — safe to run repeatedly.
+
+Options:
+  --tenant <appDomain>   Target tenant (e.g. tokenoftrust.com). Defaults to the
+                         current checkout's tenant when run inside one.
+  --pr <N>               PR number to retry evidence for.
+  --change-id <id>       Optional explicit candidate id (defaults to pr-<N>).
+  --url <origin>         Storefront origin. Defaults to $TOT_STOREFRONT_URL or
+                         ${DEFAULT_STOREFRONT_URL}.
+  --secret <s>           Operator secret. Prefer the env vars below.
+  --help, -h             Show this help.
+
+Auth (operator secret, from env, first found):
+  PREVIEW_RECONCILE_SECRET, GRANTS_ADMIN_SECRET, TOT_OPERATOR_SECRET`;
+}
+
+/**
+ * @param {string[]} argv
+ * @param {any} ctx — detected CLI context (ctx.tenant when in a checkout)
+ */
+export async function run(argv, ctx) {
+  const args = parseRetryEvidenceArgs(argv);
+  if (args.help) {
+    console.log(renderUsage());
+    return 0;
+  }
+
+  const base = (args.url || process.env.TOT_STOREFRONT_URL || process.env.STOREFRONT_BASE_URL || DEFAULT_STOREFRONT_URL)
+    .trim()
+    .replace(/\/+$/, "");
+
+  const tenant = (args.tenant || ctx?.tenant || "").trim();
+  if (!tenant) {
+    console.error(
+      "✗ no target tenant.\n\n  → next: pass --tenant <appDomain> (e.g. --tenant tokenoftrust.com), " +
+        "or run inside a store checkout.",
+    );
+    return 2;
+  }
+
+  const prRaw = args.pr;
+  const pr = prRaw != null && `${prRaw}`.trim() && Number.isFinite(Number(prRaw)) ? Number(prRaw) : null;
+  const changeId = (args.changeId || "").trim() || null;
+  if (pr == null && !changeId) {
+    console.error(
+      "✗ no candidate to retry evidence for.\n\n  → next: pass --pr <N> (the PR number), or --change-id <id>.",
+    );
+    return 2;
+  }
+
+  const secret = (args.secret || process.env.PREVIEW_RECONCILE_SECRET || process.env.GRANTS_ADMIN_SECRET || process.env.TOT_OPERATOR_SECRET || "").trim();
+  if (!secret) {
+    console.error(
+      "✗ no operator secret.\n\n  → next: set PREVIEW_RECONCILE_SECRET (or GRANTS_ADMIN_SECRET / " +
+        "TOT_OPERATOR_SECRET) in the environment.",
+    );
+    return 2;
+  }
+
+  const body = {
+    ...(pr != null ? { pr } : {}),
+    ...(changeId ? { changeId } : {}),
+  };
+
+  let res;
+  try {
+    res = await fetch(`${base}/api/changes/candidate-evidence-retry`, {
+      method: "POST",
+      headers: {
+        "content-type": "application/json",
+        authorization: `Bearer ${secret}`,
+        "x-tot-owner": tenant,
+        "x-tot-capability": "ship-on-behalf",
+      },
+      body: JSON.stringify(body),
+    });
+  } catch (e) {
+    console.error(`✗ could not reach ${base}: ${e?.message || e}\n\n  → next: check --url / your network.`);
+    return 1;
+  }
+
+  let data = {};
+  try {
+    data = await res.json();
+  } catch {
+    /* non-JSON error body */
+  }
+
+  const label = pr != null ? `PR #${pr}` : changeId;
+
+  if (res.ok && data?.ok && data?.pushed) {
+    console.log(`✓ Evidence re-pushed for ${label} on ${tenant} (promotable: ${data.promotable}).`);
+    return 0;
+  }
+  if (res.ok && data?.ok && !data?.pushed) {
+    console.error(`✗ Evidence push still failed for ${label} on ${tenant}.`);
+    if (data.error) console.error(`  • ${data.error}`);
+    console.error("\n  → next: check MCP reachability, then re-run this command.");
+    return 1;
+  }
+
+  const message = data?.error || `HTTP ${res.status}`;
+  console.error(`✗ Retry did not succeed (HTTP ${res.status}).`);
+  console.error(`  • ${message}`);
+  return 1;
+}

package/src/commands/preview.mjs

@@ -5,7 +5,7 @@
  *
  *   tot dev        run your store locally with save→reload
  *   tot preview    push it to a reviewable preview (validate → reconcile → compliance)  ← you are here
- *   tot ship       promote a reconciled preview live                                     ← unit u3
+ *   tot ship       promote a reconciled preview live
  *
  * The whole preview flow (validate, push the preview ref, open/update the PR-backed
  * candidate, stream the reconcile/compliance/preview result) lives in submit.mjs — this
@@ -45,12 +45,12 @@ export function postRunHint(code, alias) {
 /**
  * @param {string[]} argv
  * @param {any} ctx
- * @param {{ alias?: string|null }} [opts] — `alias` is the old verb the developer typed
+ * @param {{ alias?: string|null }} [opts] - `alias` is the old verb the developer typed
  *   (`"submit"` / `"deploy"`) when this flow is reached as a teaching alias; null/omitted
  *   for the first-class `tot preview`.
  */
 export async function run(argv, ctx, { alias = null } = {}) {
-  // `tot preview build …` is the OPERATOR build-on-demand subcommand (unit U3) —
+  // `tot preview build …` is the OPERATOR build-on-demand subcommand —
   // a distinct verb from the developer preview flow, so it's dispatched BEFORE the
   // submit-flow arg parse. Only the first-class `tot preview` carries it (not the
   // `submit`/`deploy` teaching aliases, which are the push-your-checkout flow).
@@ -59,6 +59,22 @@ export async function run(argv, ctx, { alias = null } = {}) {
     return runBuild(argv.slice(1), ctx);
   }
 
+  // `tot preview doctor …` is the read-only merge DIAGNOSIS subcommand —
+  // a distinct verb from the developer preview flow, dispatched before the submit-
+  // flow arg parse (like `build`). Only the first-class `tot preview` carries it.
+  if (!alias && argv[0] === "doctor") {
+    const { run: runDoctor } = await import("./preview-doctor.mjs");
+    return runDoctor(argv.slice(1), ctx);
+  }
+
+  // `tot preview retry-evidence …` is the OPERATOR recovery subcommand for a
+  // candidate whose evidence push to MCP failed (fb-1787938036559-ppmu4e) —
+  // dispatched before the submit-flow arg parse, like `build`/`doctor`.
+  if (!alias && argv[0] === "retry-evidence") {
+    const { run: runRetryEvidence } = await import("./preview-retry-evidence.mjs");
+    return runRetryEvidence(argv.slice(1), ctx);
+  }
+
   const verb = alias || "preview";
   const args = parseArgs(argv);