@tokenoftrust/cli 1.4.0-rc.21 → 1.4.0-rc.23

package/package.json

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

package/src/candidate-state.mjs

@@ -7,7 +7,7 @@
  * nothing here (backward-compatible with the stateless original). This file only
  * records a DIVERGENCE from that stable default:
  *
- *   - `tot submit --new` forks a fresh candidate and remembers it here, so the
+ *   - `tot submit --fork-candidate` forks a fresh candidate and remembers it here, so the
  *     NEXT plain `tot submit` keeps updating the NEW PR (like pushing more commits
  *     to a `gh pr` branch), not the old one; and
  *   - a terminal-roll (the active candidate was merged/closed) records the fresh
@@ -123,7 +123,7 @@ export function clearActiveChangeId(filePath, { mcpUrl, repo, branch }) {
 /**
  * A fresh candidate handle forked from a stable base — `<baseId>-<suffix>`, still
  * matching candidate_open's `[a-z0-9._-]` handle grammar. The suffix defaults to
- * 6 random hex chars (so two `--new` runs never collide); tests inject a fixed
+ * 6 random hex chars (so two `--fork-candidate` runs never collide); tests inject a fixed
  * suffix. Pure given `suffix`.
  */
 export function mintFreshChangeId(baseId, suffix = randomBytes(3).toString("hex")) {

package/src/commands/accept.mjs

@@ -48,6 +48,10 @@ 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";
+// C5 — 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";
@@ -531,6 +535,15 @@ export async function runIntegrate(
     authHeaders = viewer.authHeaders;
   }
 
+  // C5 — 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
   //      (`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
@@ -625,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: /** @type {string} */ (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. */

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).
@@ -71,7 +71,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\`).

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` (unit
+ * A2) — 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 (C5) 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.mjs

@@ -59,6 +59,14 @@ export async function run(argv, ctx, { alias = null } = {}) {
     return runBuild(argv.slice(1), ctx);
   }
 
+  // `tot preview doctor …` is the read-only merge DIAGNOSIS subcommand (unit C1) —
+  // 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);
+  }
+
   const verb = alias || "preview";
   const args = parseArgs(argv);
 

package/src/commands/ship.mjs

@@ -48,6 +48,11 @@ import { planForAction, printPlanAndConfirm } from "../plan.mjs";
 import { startProgress } from "../progress.mjs";
 import { openBrowser } from "../open.mjs";
 import { emitActivity } from "../activity.mjs";
+// C5 — the doctor PUSH: on a refused/failed ship (most tellingly "not green"),
+// auto-append the COMPACT summary over the SAME operator transport, so the operator
+// sees WHICH changes are keeping the aggregate from going green without a separate
+// `tot preview doctor` run.
+import { autoSurfaceDoctor } from "../merge-doctor-report.mjs";
 
 const DEFAULT_STOREFRONT_URL = "https://storefront.tokenoftrust.store";
 
@@ -327,6 +332,14 @@ export async function runShip({ tenant, secret, storefrontUrl = null, yes = fals
     "x-tot-capability": "ship-on-behalf",
   };
 
+  // C5 — auto-surface the merge-doctor on a refused/failed ship. Best-effort:
+  // fetches the hosted doctor over the SAME operator transport and prints the COMPACT
+  // summary; never throws and never touches the exit code. A clean/unreachable doctor
+  // prints nothing — so this only ever ADDS the "here's what's not green" context.
+  const surfaceDoctor = async () => {
+    for (const line of await autoSurfaceDoctor({ base, authHeaders, fetchImpl })) console.error(line);
+  };
+
   // 1. GET the read-only plan: the pinned sha + artifact digest + included PRs +
   //    rollback target + paywall verdict. Zero side effects.
   let planRes;
@@ -356,6 +369,9 @@ export async function runShip({ tenant, secret, storefrontUrl = null, yes = fals
   const plan = normalizeShipPlan(planData);
   if (!plan.ok) {
     console.error(fail(plan.message, refusalNextStep(plan.reason)));
+    // A not-green / no-passed-run refusal is exactly what the doctor diagnoses —
+    // name the changes keeping the aggregate red right here.
+    await surfaceDoctor();
     return 1;
   }
 
@@ -433,7 +449,9 @@ export async function runShip({ tenant, secret, storefrontUrl = null, yes = fals
     payload: { args: { command: "ship", subcommand: "ship.publish" } },
   });
 
-  return reportShipResult(shipResult, { tenant, liveUrl, noOpen, openUrl: deps.openUrl });
+  const code = reportShipResult(shipResult, { tenant, liveUrl, noOpen, openUrl: deps.openUrl });
+  if (code !== 0) await surfaceDoctor();
+  return code;
 }
 
 /**

package/src/commands/submit.mjs

@@ -47,6 +47,10 @@ import { setTimeout as delay } from "node:timers/promises";
 import { createMcpClient } from "../mcp.mjs";
 import { establishSession, AuthUnavailableError } from "../auth.mjs";
 import { checkoutTenant } from "./clone.mjs";
+// Reuse the operator side's `candidate_refresh` result normaliser (unit c3 — the
+// born-rebased submit rebuilds a candidate onto the current base with the SAME
+// engine `tot accept --refresh` uses, so the two read its result identically).
+import { normalizeRefreshResult } from "./accept.mjs";
 import { validateTenant, ERROR } from "../validate.mjs";
 import { openBrowser } from "../open.mjs";
 import { startProgress } from "../progress.mjs";
@@ -107,8 +111,8 @@ export function parseArgs(argv) {
   // `ref: null` — an explicit `--ref` always wins; otherwise the push target is
   // derived per-run as YOUR OWN isolated candidate ref (resolvePushRef, below),
   // never a fixed shared default.
-  /** @type {{ mcp: string|null, identity: string|null, ref: string|null, skipValidate: boolean, skipFreshness: boolean, noWait: boolean, watch: boolean, noOpen: boolean, noCommit: boolean, message: string|null, summary: string|null, summaryFile: string|null, json: boolean, new: boolean, help: boolean }} */
-  const a = { mcp: null, identity: null, ref: null, skipValidate: false, skipFreshness: false, noWait: false, watch: false, noOpen: false, noCommit: false, message: null, summary: null, summaryFile: null, json: false, new: false, help: false };
+  /** @type {{ mcp: string|null, identity: string|null, ref: string|null, skipValidate: boolean, skipFreshness: boolean, noWait: boolean, watch: boolean, noOpen: boolean, noCommit: boolean, message: string|null, summary: string|null, summaryFile: string|null, strategy: string|null, json: boolean, forkCandidate: boolean, help: boolean }} */
+  const a = { mcp: null, identity: null, ref: null, skipValidate: false, skipFreshness: false, noWait: false, watch: false, noOpen: false, noCommit: false, message: null, summary: null, summaryFile: null, strategy: null, json: false, forkCandidate: false, help: false };
   for (let i = 0; i < argv.length; i++) {
     const t = argv[i];
     if (t === "--mcp") a.mcp = argv[++i];
@@ -117,6 +121,7 @@ export function parseArgs(argv) {
     else if (t === "-m" || t === "--message") a.message = argv[++i];
     else if (t === "--summary") a.summary = argv[++i];
     else if (t === "--summary-file") a.summaryFile = argv[++i];
+    else if (t === "--strategy") a.strategy = argv[++i];
     else if (t === "--json") a.json = true;
     else if (t === "--skip-validate") a.skipValidate = true;
     else if (t === "--skip-freshness") a.skipFreshness = true;
@@ -124,7 +129,7 @@ export function parseArgs(argv) {
     else if (t === "--no-wait") a.noWait = true;
     else if (t === "--watch") a.watch = true;
     else if (t === "--no-open") a.noOpen = true;
-    else if (t === "--new") a.new = true;
+    else if (t === "--fork-candidate") a.forkCandidate = true;
     else if (t === "--help" || t === "-h") a.help = true;
   }
   return a;
@@ -140,11 +145,20 @@ export function renderUsage(verb = "preview") {
   return `tot ${verb} — submit your store for preview
 
   tot ${verb}                    validate → push the preview ref → stream the result
-  tot ${verb} --new              open a NEW candidate PR instead of updating your open one
+  tot ${verb} --fork-candidate   open a SECOND, independently-tracked candidate (a
+                                  parallel dev path). Rarely needed — a fresh git
+                                  branch already gets its own candidate automatically
+                                  (git checkout is the PR switcher); use this only to
+                                  run two candidates from ONE branch.
   tot ${verb} --watch            stay attached through reconcile + compliance + accept (long-poll)
   tot ${verb} --skip-validate    push without the local lint (not recommended)
-  tot ${verb} --skip-freshness   skip the stale-base check (not recommended — may build a
-                                  candidate rooted in an already-superseded base)
+  tot ${verb} --skip-freshness   skip the stale-base check AND the born-rebased rebuild
+                                  (not recommended — may build a candidate rooted in an
+                                  already-superseded base)
+  tot ${verb} --strategy <s>     how the born-rebased rebuild resolves a file changed on
+                                  BOTH sides when the base has moved: "merge" (real 3-way
+                                  merge, surfaces a resolve card on a genuine overlap — the
+                                  default), "ours" (keep yours), "theirs" (keep the store's)
   tot ${verb} --no-commit        don't auto-commit a dirty tree — preview only what's already committed
   tot ${verb} --ref <name>       push ref (default: your own isolated candidate ref — see \`tot pr\`)
   tot ${verb} -m "<title>"       one-line summary of what changed (the approver sees this)
@@ -162,13 +176,14 @@ export function renderUsage(verb = "preview") {
   tot ${verb} --mcp <url>        MCP base URL (default: env MCP_BASE_URL / TOT_MCP_URL)
 
   By default a re-run UPDATES your open candidate PR (like pushing more commits
-  to a GitHub PR), rather than opening a new one each time. Use --new to fork a
-  fresh candidate PR; the next plain \`tot ${verb}\` then updates THAT one. Manage your
-  open candidates with \`tot pr\` (list / view / close). If your candidate was already
+  to a GitHub PR), rather than opening a new one each time. Manage your open
+  candidates with \`tot pr\` (list / view / close). If your candidate was already
   merged or closed, a re-run automatically opens a fresh one.
 
-  Working on one thing at a time? You don't need --new, a git branch, or any
-  branch management at all — just keep editing and re-running \`tot ${verb}\`.
+  Starting a separate change? \`git checkout -b <branch>\` — a fresh branch gets its
+  own candidate automatically, and \`git checkout\` back and forth is how you switch
+  between them. --fork-candidate is an escape hatch for the rarer case of wanting a
+  SECOND candidate off the SAME branch; reach for a branch first.
 
   Once a preview reconciles cleanly, \`tot ship\` promotes it live.
 
@@ -350,7 +365,7 @@ export const FRESHNESS_BASE_BRANCH = "preview";
  * Detect a STALE local view of the base branch before minting a candidate —
  * the live-repeat incident this guards against: the checkout's `origin/preview`
  * tracking ref was stale (recorded before a just-merged PR moved it), so a
- * fresh `tot preview --new` built a candidate rooted in the OLD tip and got an
+ * fresh `tot preview --fork-candidate` built a candidate rooted in the OLD tip and got an
  * instant, entirely avoidable "not mergeable" the moment it was compared
  * against the real, already-advanced `preview`.
  *
@@ -386,6 +401,166 @@ export function detectStaleBase(git, branch) {
   return remoteSha;
 }
 
+/**
+ * How many commits the base branch has advanced since this candidate forked off it
+ * (unit c2 — the shift-left base-drift warning). Conflicts in this loop are BASE
+ * DRIFT: a candidate branches off `<base>`, sits while OTHER candidates advance
+ * `<base>`, then settles mergeable=false at Accept time. This measures that drift
+ * cheaply and LOCALLY — the merge-base (fork point) of HEAD and the base's
+ * remote-tracking tip, then how many commits separate that fork point from the tip.
+ *
+ * PURE LOCAL git — reads `refs/remotes/origin/<branch>` (the last-fetched tip),
+ * never the network; it complements detectStaleBase (which confirms that tracking
+ * ref is itself current). Returns 0 — never a false warning — when there's nothing
+ * to compare against or the drift can't be positively determined: no base tracking
+ * ref yet, unrelated histories / no merge-base, HEAD already contains the tip, or
+ * any git failure. Non-blocking by contract: the caller warns on a positive count
+ * but always proceeds. Pure git I/O via the injected runner — unit-tested.
+ * @param {(cargs:string[])=>string} git
+ * @param {string} branch
+ * @returns {number}
+ */
+export function baseCommitsBehind(git, branch) {
+  const baseTip = `refs/remotes/origin/${branch}`;
+  let tip = "";
+  try {
+    tip = git(["rev-parse", "-q", "--verify", baseTip]).trim();
+  } catch {
+    return 0; // no local tracking ref for the base — nothing to compare against
+  }
+  if (!tip) return 0;
+  let mergeBase = "";
+  try {
+    mergeBase = git(["merge-base", "HEAD", baseTip]).trim();
+  } catch {
+    return 0; // unrelated histories / no HEAD — nothing meaningful to count
+  }
+  if (!mergeBase || mergeBase === tip) return 0; // HEAD already contains the base tip
+  try {
+    const n = parseInt(git(["rev-list", "--count", `${mergeBase}..${baseTip}`]).trim(), 10);
+    return Number.isFinite(n) && n > 0 ? n : 0;
+  } catch {
+    return 0;
+  }
+}
+
+/**
+ * Resolve the git ref to diff HEAD against for the candidate's file patch (and its
+ * summary). The candidate PR is `preview + your file changes`, and `candidate_open`
+ * SERVER-CUTS the candidate branch back to the current preview tip and re-applies the
+ * patch — so the patch MUST be the FULL delta of your branch vs its fork point off
+ * `preview`, never "what changed since my last candidate push". Diffing against your
+ * own candidate tracking ref is what silently produced an empty patch (and the wrong
+ * "no file changes" skip, so no PR opened) after a push that landed but failed to open
+ * its PR: that ref already equals HEAD, so the since-last-push delta is empty even
+ * though the change vs preview is 19 files. Prefer the merge-base (fork point) with
+ * `origin/<baseBranch>`; fall back to the candidate tracking ref, then HEAD~1, then ""
+ * (single-commit `git show`) when no base ref resolves. Pure git I/O via the injected
+ * runner — unit-tested.
+ * @param {(cargs:string[])=>string} git
+ * @param {string} ref  the candidate ref (e.g. "candidate/local-abc")
+ * @param {string} [baseBranch]  the preview base branch (default FRESHNESS_BASE_BRANCH)
+ * @returns {string}
+ */
+export function resolvePatchBase(git, ref, baseBranch = FRESHNESS_BASE_BRANCH) {
+  const verify = (r) => {
+    try { return git(["rev-parse", "--verify", "--quiet", r]).trim(); } catch { return ""; }
+  };
+  const previewRef = `refs/remotes/origin/${baseBranch}`;
+  if (verify(previewRef)) {
+    try {
+      const forkPoint = git(["merge-base", "HEAD", previewRef]).trim();
+      if (forkPoint) return forkPoint;
+    } catch { /* unrelated histories — fall through */ }
+  }
+  const trackingRef = `refs/remotes/origin/${ref}`;
+  if (verify(trackingRef)) return trackingRef;
+  if (verify("HEAD~1")) return "HEAD~1";
+  return "";
+}
+
+// ─── born-rebased at submit (unit c3 — shift-left prevention #2) ─────────────────
+
+/** The three strategies the born-rebased rebuild accepts, mirroring `tot accept
+ *  --refresh` (accept.mjs) and the admin one-click resolver: `merge` (real 3-way,
+ *  refuses on a genuine overlap), `ours` (keep yours), `theirs` (keep the store's).
+ *  `merge` is the DEFAULT — auto-rebuild on pure drift, name the conflict on a real
+ *  same-line overlap, never silently clobber a side. */
+export const BORN_REBASED_STRATEGIES = ["ours", "theirs", "merge"];
+export const DEFAULT_BORN_REBASED_STRATEGY = "merge";
+
+/**
+ * Run `candidate_refresh` (the born-rebased rebuild, unit c3) over the ALREADY
+ * established MCP client — the candidate was just opened by candidate_open (step 2b)
+ * and the tenant scope is already bound, so this reuses that session rather than
+ * establishing its own (accept.mjs's runRefresh is the operator entry that does the
+ * sign-in; here the submit flow already holds the session). Rebuilds the candidate
+ * from the CURRENT base tip and re-applies its file changes under `strategy`. Returns
+ * the normalized result (status:"committed" is the only success). Best-effort: any
+ * throw — an owner-gated denial (candidate_refresh is app-owner gated), an older MCP
+ * without the tool, a transient failure — normalizes to a non-ok error result the
+ * caller submits-as-is on, NEVER blocking the push that already landed.
+ * @param {{callTool:Function}} client
+ * @param {{ repo: string, changeId: string, strategy: string }} opts
+ * @returns {Promise<ReturnType<typeof normalizeRefreshResult>>}
+ */
+export async function runBornRebased(client, { repo, changeId, strategy }) {
+  try {
+    const raw = await client.callTool("candidate_refresh", { repo, changeId, strategy });
+    return normalizeRefreshResult(raw);
+  } catch (e) {
+    return { ...normalizeRefreshResult(null), status: "error", message: String(e?.message || e) };
+  }
+}
+
+/**
+ * The born-rebased SUCCESS lines (unit c3) — printed when the candidate rebuilt
+ * cleanly onto the current base tip, so it enters the queue already mergeable rather
+ * than settling not-mergeable at Accept time. `behind` is the base-drift count that
+ * triggered the rebuild. Pure — unit-tested.
+ * @param {{ behind?: number, strategy?: string, refreshedFiles?: string[] }} input
+ * @returns {string[]}
+ */
+export function formatBornRebasedSuccess({ behind = 0, strategy = DEFAULT_BORN_REBASED_STRATEGY, refreshedFiles = [] } = {}) {
+  const drift = behind > 0 ? `${behind} commit${behind === 1 ? "" : "s"}` : "since you forked";
+  const lines = [
+    `\n  ✓ rebuilt fresh on the current store (base had advanced ${drift}, strategy ${strategy}) — your candidate enters the queue already mergeable.`,
+  ];
+  if (refreshedFiles.length) lines.push(`    reapplied: ${refreshedFiles.join(", ")}`);
+  return lines;
+}
+
+/**
+ * The born-rebased RESOLVE CARD (unit c3) — printed when the default `merge` rebuild
+ * hits a GENUINE same-line overlap with the base (not mere drift): the biggest single
+ * shift-left win is surfacing that conflict HERE, at submit, instead of letting it
+ * land as a stuck queue row someone discovers at Accept time. Names the diverged files
+ * and offers the two one-command resolutions (keep-mine / keep-store's) — `merge` is
+ * the default that just failed, so it isn't re-offered. Matches how the rest of this
+ * file reports next-steps (a `✗` headline + concrete `tot <verb> …` commands), never a
+ * raw git rebase instruction. Pure — unit-tested. `verb` brands the copy with whatever
+ * the developer typed.
+ * @param {{ unresolved?: string[] }} rr
+ * @param {string} [verb]
+ * @returns {string[]}
+ */
+export function formatBornRebasedConflict({ unresolved = [] } = {}, verb = "preview") {
+  const lines = [
+    `\n  ✗ your change conflicts with the current store on the same lines — it can't be auto-rebased.`,
+  ];
+  if (unresolved.length) {
+    lines.push(`  These files changed on both sides since you forked and need your call:`);
+    for (const f of unresolved) lines.push(`    - ${f}`);
+  }
+  lines.push(
+    `  Resolve it in one command — choose which side wins on those files:`,
+    `    tot ${verb} --strategy=ours     keep YOURS on any clash`,
+    `    tot ${verb} --strategy=theirs   keep the STORE's on any clash`,
+    `  Your push is in; the candidate is submitted but stays not-mergeable until you resolve it.`,
+  );
+  return lines;
+}
+
 // ─── auto-commit the known content trees (unit u2) ───────────────────────────────
 
 /**
@@ -783,22 +958,23 @@ export function actorKeyFor(session) {
  * Which candidate this submit lands on (gh-pr-like) — decided UP FRONT, before any
  * network call, because it also determines the isolated git ref we push to
  * (resolvePushRef, below): a re-submit updates the SAME candidate/ref by default;
- * `--new` forks a fresh one.
- *   --new     → fork a FRESH candidate id;
- *   otherwise → the remembered active candidate (from a prior --new / terminal
- *               roll), else the STABLE per-dev-per-tenant(-per-branch) default.
+ * `--fork-candidate` forks a fresh one.
+ *   forkCandidate → fork a FRESH candidate id;
+ *   otherwise     → the remembered active candidate (from a prior --fork-candidate /
+ *                   terminal roll), else the STABLE per-dev-per-tenant(-per-branch)
+ *                   default.
  * `persist` reports whether the choice diverges from the stable default, so the
  * caller knows whether to remember it as the new active pointer. `mint` is
  * injected (defaults to mintFreshChangeId) so this is pure/deterministic in tests.
  * Pure — unit-tested.
  * @param {{ tenant: string, actorKey: string, branch?: string|null, active?: string|null,
- *   isNew?: boolean, mint?: (baseId: string) => string }} opts
+ *   forkCandidate?: boolean, mint?: (baseId: string) => string }} opts
  * @returns {{ changeId: string, stableId: string, persist: boolean }}
  */
-export function chooseChangeId({ tenant, actorKey, branch = null, active = null, isNew = false, mint = mintFreshChangeId }) {
+export function chooseChangeId({ tenant, actorKey, branch = null, active = null, forkCandidate = false, mint = mintFreshChangeId }) {
   const stableId = deriveChangeId(tenant, actorKey, branch);
-  const changeId = isNew ? mint(stableId) : (active || stableId);
-  const persist = isNew || (!!active && active !== stableId);
+  const changeId = forkCandidate ? mint(stableId) : (active || stableId);
+  const persist = forkCandidate || (!!active && active !== stableId);
   return { changeId, stableId, persist };
 }
 
@@ -1019,6 +1195,15 @@ export async function run(argv, ctx, { verb = "preview" } = {}) {
     emitJson(args, buildJsonResult({ ok: false, error: msg }));
     return 2;
   }
+  // --strategy (c3 born-rebased rebuild) — validate whenever given; defaults to
+  // "merge" (auto-rebuild on drift, surface a resolve card on a genuine overlap).
+  if (args.strategy != null && !BORN_REBASED_STRATEGIES.includes(args.strategy)) {
+    const msg = `unknown --strategy "${args.strategy}"`;
+    console.error(fail(msg, `use one of: ${BORN_REBASED_STRATEGIES.join(", ")} (default "${DEFAULT_BORN_REBASED_STRATEGY}")`));
+    emitJson(args, buildJsonResult({ ok: false, error: msg }));
+    return 2;
+  }
+  const bornRebasedStrategy = args.strategy || DEFAULT_BORN_REBASED_STRATEGY;
   if (args.summaryFile) {
     let raw;
     try {
@@ -1054,6 +1239,12 @@ export async function run(argv, ctx, { verb = "preview" } = {}) {
     /* best-effort — see above */
   }
 
+  // How far the base has drifted since this candidate forked (unit c2), hoisted to the
+  // whole flow: it drives BOTH the c2 pre-push warning (below) AND the c3 born-rebased
+  // rebuild (after candidate_open). Stays 0 under --skip-freshness, so that flag opts
+  // out of the rebuild too — consistent with opting out of the warning.
+  let baseDrift = 0;
+
   // Freshness preflight (unit u16) — BEFORE minting anything: is the checkout's
   // cached view of the base branch already behind the store? A candidate built
   // on a stale base is an instant, avoidable "not mergeable" the moment the
@@ -1074,6 +1265,24 @@ export async function run(argv, ctx, { verb = "preview" } = {}) {
       emitJson(args, buildJsonResult({ ok: false, error: msg }));
       return 1;
     }
+
+    // Base-drift warning (unit c2) — a candidate rooted on a fork point the base has
+    // since moved past is what settles mergeable=false at Accept time; catch it early,
+    // right here, with a pure-LOCAL git read (no network — uses the base's
+    // remote-tracking tip, which the stale-base preflight just above confirmed is
+    // current). NON-BLOCKING: warn and submit anyway, so a work-in-progress preview
+    // is never refused over base drift. Shares --skip-freshness with the preflight.
+    try {
+      baseDrift = baseCommitsBehind(git, FRESHNESS_BASE_BRANCH);
+    } catch {
+      baseDrift = 0; // never let the warning's OWN failure disturb the submit
+    }
+    if (baseDrift > 0) {
+      console.error(`\n⚠ base is ${baseDrift} commit${baseDrift === 1 ? "" : "s"} behind — rebase before submit`);
+      console.error(
+        `  (\`${FRESHNESS_BASE_BRANCH}\` has advanced since your branch forked off it — \`tot sync\` to rebase, or --skip-freshness to silence)`,
+      );
+    }
   }
 
 
@@ -1181,12 +1390,12 @@ export async function run(argv, ctx, { verb = "preview" } = {}) {
   };
   function buildSummaryAndPatch(ref) {
     const headSubject = gitSafe(["log", "-1", "--format=%s"]).trim();
-    const trackingRef = `refs/remotes/origin/${ref}`;
-    const base = gitSafe(["rev-parse", "--verify", "--quiet", trackingRef]).trim()
-      ? trackingRef
-      : gitSafe(["rev-parse", "--verify", "--quiet", "HEAD~1"]).trim()
-        ? "HEAD~1"
-        : "";
+    // Diff against the fork point off `preview` — the FULL branch delta — so the patch
+    // is complete for candidate_open's server-cut (which resets the branch to preview
+    // and re-applies this patch). NOT the candidate's own tracking ref: after a push
+    // that landed but failed to open its PR, that ref equals HEAD → empty patch →
+    // wrong "no file changes" → no PR. See resolvePatchBase.
+    const base = resolvePatchBase(gitSafe, ref);
     const statusCmd = base ? ["diff", "--name-status", `${base}..HEAD`] : ["show", "--name-status", "--format=", "HEAD"];
     const patchEntries = parseNameStatus(gitSafe(statusCmd));
     const files = patchEntries.map((e) => e.path);
@@ -1221,7 +1430,7 @@ export async function run(argv, ctx, { verb = "preview" } = {}) {
     // still lands if that embedded token is live. actorKeyFor(null) degrades to the
     // generic "developer" key — still isolated PER BRANCH (never the shared ref),
     // just not per-developer until sign-in succeeds.
-    const { changeId } = chooseChangeId({ tenant, actorKey: actorKeyFor(null), branch, active, isNew: args.new });
+    const { changeId } = chooseChangeId({ tenant, actorKey: actorKeyFor(null), branch, active, forkCandidate: args.forkCandidate });
     const ref = resolvePushRef({ ref: args.ref, changeId });
     const { changeSummary } = buildSummaryAndPatch(ref);
     console.error(`~ pushing ${short} → ${ref} (origin)`);
@@ -1264,11 +1473,11 @@ export async function run(argv, ctx, { verb = "preview" } = {}) {
   // If it merged/closed we DROP it (and forget it on disk) so chooseChangeId falls
   // back to the stable id, rather than force-pushing onto a now-dead candidate branch
   // and opening a NEW PR that inherits a guaranteed conflict (the live incident this
-  // guards against). Skipped under --new (chooseChangeId ignores `active` there
-  // anyway). Purely diagnostic: a check that errors leaves the pointer untouched.
+  // guards against). Skipped under --fork-candidate (chooseChangeId ignores `active`
+  // there anyway). Purely diagnostic: a check that errors leaves the pointer untouched.
   // Needs the tenant scope bound for candidate_status to resolve — idempotent with
   // the later client_switch / the fresh-mint checkoutTenant.
-  if (active && repo && !args.new) {
+  if (active && repo && !args.forkCandidate) {
     try {
       await client.callTool("client_switch", { tenant });
     } catch { /* scope bind is best-effort; candidateStateFor tolerates a miss */ }
@@ -1287,9 +1496,9 @@ export async function run(argv, ctx, { verb = "preview" } = {}) {
   // Which candidate (and therefore which isolated ref, b03) this submit targets —
   // decided now, with a real session, so the SAME id backs both the raw git push
   // (right below) and the PR-backed candidate (step 2b): the two never point at
-  // different branches. See chooseChangeId's doc for the --new / active-pointer
-  // rules.
-  let { changeId, stableId, persist } = chooseChangeId({ tenant, actorKey: actorKeyFor(session), branch, active, isNew: args.new });
+  // different branches. See chooseChangeId's doc for the --fork-candidate /
+  // active-pointer rules.
+  let { changeId, stableId, persist } = chooseChangeId({ tenant, actorKey: actorKeyFor(session), branch, active, forkCandidate: args.forkCandidate });
   const ref = resolvePushRef({ ref: args.ref, changeId });
   const { changeSummary, patchEntries } = buildSummaryAndPatch(ref);
 
@@ -1357,6 +1566,61 @@ export async function run(argv, ctx, { verb = "preview" } = {}) {
       candidate = await submitCandidate(client, { repo, changeId, changeSummary, patchEntries, readBlob, quiet: args.json });
     }
 
+    // c3 — BORN-REBASED at submit (shift-left prevention #2). The candidate is open;
+    // if the base has drifted (the SAME signal c2 warned on, pre-push) rebuild it from
+    // the CURRENT base tip via candidate_refresh BEFORE finalizing, so it enters the
+    // queue already fresh instead of settling not-mergeable at Accept time.
+    //   • clean rebuild  → report it, hand back the fresh candidate's shareable URL,
+    //                       and finish (the rebuilt PR has a NEW head; polling the old
+    //                       local `commit` would read as never-dispatched, so we skip
+    //                       the reconcile poll and say the fresh preview is building);
+    //   • genuine overlap (merge_failed) → surface the resolve card right here, then
+    //                       fall through — candidate_refresh made NO changes on a real
+    //                       conflict, so the candidate's head still matches `commit`
+    //                       and the normal reconcile poll below is still valid;
+    //   • anything else (owner-gated denial, older MCP, error) → submit as-is.
+    // Best-effort throughout: candidate_refresh is app-owner gated, so an ordinary
+    // invited developer's session may be denied — that degrades to submitting as-is,
+    // never blocking the push that already landed. Gated on --skip-freshness via
+    // baseDrift (0 when skipped).
+    if (repo && baseDrift > 0 && candidate && !isTerminalCandidateState(candidate.state) && changeId) {
+      const rebased = await runBornRebased(client, { repo, changeId, strategy: bornRebasedStrategy });
+      if (rebased.ok) {
+        for (const line of formatBornRebasedSuccess({ behind: baseDrift, strategy: rebased.strategy || bornRebasedStrategy, refreshedFiles: rebased.refreshedFiles })) {
+          if (!args.json) console.log(line);
+        }
+        const freshPr = typeof rebased.prNumber === "number" ? rebased.prNumber : candidate.prNumber;
+        const freshPrUrl = typeof freshPr === "number"
+          ? shareablePrUrl(env.TOT_STOREFRONT_URL || env.STOREFRONT_BASE_URL || DEFAULT_STOREFRONT_URL, tenant, freshPr)
+          : null;
+        if (freshPrUrl && !args.json) {
+          console.log(`\n  ▸ Your fresh preview will appear at:\n      ${freshPrUrl}\n    (building on the current store — this link goes live once reconcile completes)`);
+        }
+        // The rebuild keeps the STABLE changeId, so the persisted active pointer stays
+        // valid — record it (best-effort) exactly as the normal open path does below.
+        if (persist && repo) {
+          try {
+            writeActiveChangeId(statePath, { mcpUrl: baseUrl, repo, branch, changeId });
+          } catch { /* best-effort local hint */ }
+        }
+        emitJson(args, buildJsonResult({
+          ok: true, ref, commit, changeId,
+          candidate: { ...candidate, prNumber: freshPr ?? candidate.prNumber },
+          previewPrUrl: freshPrUrl,
+          note: `born-rebased on the current base (${rebased.strategy || bornRebasedStrategy})`,
+        }));
+        return 0;
+      }
+      if (rebased.status === "merge_failed") {
+        for (const line of formatBornRebasedConflict({ unresolved: rebased.unresolved }, verb)) {
+          if (!args.json) console.log(line);
+        }
+        // fall through to the normal poll — the candidate is unchanged.
+      } else if (rebased.message && !args.json) {
+        console.log(`  ~ couldn't auto-rebase on the current base (${rebased.message}) — submitting as-is.`);
+      }
+    }
+
     // Immediate shareable URL (Vercel-style: "the URL exists before the build
     // does"). A non-terminal candidate with a real PR number means a preview
     // WILL be built at a deterministic route — so hand the developer that link

package/src/merge-doctor-report.mjs

@@ -0,0 +1,208 @@
+/**
+ * merge-doctor-report — the SHARED, pure rendering + one-GET fetch of the hosted
+ * merge-doctor seam (`GET /<tenant>/api/preview/merge-doctor`, unit A2), so every
+ * CLI surface speaks ONE doctor taxonomy:
+ *
+ *   - `tot preview doctor` (preview-doctor.mjs) — the full, ordered report on demand.
+ *   - `tot accept` / `tot ship` (accept.mjs / ship.mjs) — the C5 PUSH: on a failed
+ *     accept/integrate or a refused ship, auto-append the COMPACT summary right where
+ *     the failure already surfaced, so a developer doesn't have to remember to run the
+ *     doctor themselves.
+ *
+ * The render helpers here are a faithful PORT of the analyzer's own
+ * formatReport/attentionBanner/supportContext (mergeDoctor.ts §render / the
+ * scripts/tenant/gitea-merge-doctor.mjs mirror) — the published `@tokenoftrust/cli`
+ * is dependency-free and cannot import the app/scripts source, so this port is kept in
+ * sync with that taxonomy by hand.
+ *
+ * Dependency-light: `fail` + global fetch only. Imports NOTHING from the command
+ * modules (accept/ship/preview-doctor), so accept.mjs and ship.mjs can both depend on
+ * it without a cycle (preview-doctor.mjs already imports ship.mjs for the operator
+ * secret; routing the shared pieces through here keeps ship.mjs ⟷ preview-doctor.mjs
+ * acyclic).
+ */
+
+/** The hosted seam path — one GET, one answer (composed server-side over the SAME
+ *  reads the admin Publish tab builds, run through the shared analyzer). */
+export const DOCTOR_PATH = "/api/preview/merge-doctor";
+
+/** Who resolves a finding — the ticket-deflection axis. */
+export const OWNERSHIP = { developer: "developer", platform: "platform", operator: "operator" };
+export const SEV_GLYPH = { blocker: "✗", warn: "⚠", info: "•" };
+export const OWN_TAG = { developer: "you", platform: "on-us", operator: "housekeeping" };
+
+/**
+ * Defensively read the endpoint body into the analysis shape. The endpoint is a
+ * trust boundary, so a plausible field gap degrades rather than crashes. Pure.
+ * @param {any} data
+ * @returns {{ scopeKnown:boolean, verdict:string, findings:any[], counts:{blocker:number,warn:number,info:number} }}
+ */
+export function normalizeAnalysis(data) {
+  const o = data && typeof data === "object" ? data : {};
+  const findings = Array.isArray(o.findings) ? o.findings : [];
+  const c = o.counts && typeof o.counts === "object" ? o.counts : {};
+  const counts = {
+    blocker: Number.isFinite(c.blocker) ? c.blocker : findings.filter((f) => f?.severity === "blocker").length,
+    warn: Number.isFinite(c.warn) ? c.warn : findings.filter((f) => f?.severity === "warn").length,
+    info: Number.isFinite(c.info) ? c.info : findings.filter((f) => f?.severity === "info").length,
+  };
+  return {
+    scopeKnown: o.scopeKnown === true,
+    verdict: typeof o.verdict === "string" ? o.verdict : "(no verdict returned)",
+    findings,
+    counts,
+  };
+}
+
+/**
+ * The one-line banner shown at the top of the report — counts only
+ * DEVELOPER-actionable findings (what a person can self-serve); platform faults are
+ * narrated separately by {@link supportContext}. Pure.
+ */
+export function attentionBanner(result) {
+  const dev = result.findings.filter((f) => f.ownership === OWNERSHIP.developer && f.severity !== "info");
+  const fixable = dev.filter((f) => f.action).length;
+  if (!dev.length) {
+    const platform = result.findings.filter((f) => f.ownership === OWNERSHIP.platform && f.severity === "blocker");
+    if (platform.length) return `${platform.length} issue(s) are on us — Retry, then Report to support if they persist.`;
+    return "Nothing needs your attention.";
+  }
+  const conflicts = dev.filter((f) => f.code === "PR_CONFLICT").length;
+  const builds = dev.filter((f) => f.code === "NOT_BUILT_PR").length;
+  const bits = [];
+  if (conflicts) bits.push(`${conflicts} conflict(s)${conflicts <= fixable ? " (1-click fix)" : ""}`);
+  if (builds) bits.push(`${builds} need a build`);
+  return `${dev.length} change(s) need your attention: ${bits.join(", ") || "see below"}.`;
+}
+
+/**
+ * The PRE-FILLED support escalation, generated ONLY when there are PLATFORM-owned
+ * findings (a retry didn't clear it) — so "I'm stuck" becomes a structured report.
+ * Returns null when nothing is platform-owned. Pure.
+ */
+export function supportContext(result) {
+  const platform = result.findings.filter((f) => f.ownership === OWNERSHIP.platform);
+  if (!platform.length) return null;
+  const lines = [
+    `Tenant scope: ${result.scopeKnown ? "supplied" : "unknown"}`,
+    `Verdict: ${result.verdict}`,
+    "Platform-owned issues (a retry did not clear these — please investigate):",
+    ...platform.map((f) => `  • [${f.code}] ${f.subject} — ${f.detail}`),
+    "Next diagnostic hop: scripts/preview/pipeline-doctor.sh <tenant> --commit <headSha> (reconcile plane).",
+  ];
+  return lines.join("\n");
+}
+
+/** Render the analysis as the compact, ordered, agent-cheap report. Pure. */
+export function formatReport(result) {
+  const lines = [];
+  lines.push("== gitea-merge-doctor ==");
+  lines.push(`VERDICT: ${result.verdict}`);
+  lines.push(attentionBanner(result));
+  lines.push("");
+  for (const f of result.findings) {
+    const act = f.action ? `  [action: ${f.action.label}]` : "";
+    lines.push(`${SEV_GLYPH[f.severity] ?? "?"} [${f.code}] (${OWN_TAG[f.ownership] ?? f.ownership}) ${f.subject}${act}`);
+    lines.push(`    ${f.detail}`);
+    lines.push(`    → ${f.remedy}`);
+  }
+  lines.push("");
+  lines.push(
+    `${result.counts.blocker} blocker(s), ${result.counts.warn} warning(s), ${result.counts.info} info. First ✗/⚠ above is the thing to fix.`,
+  );
+  const support = supportContext(result);
+  if (support) {
+    lines.push("");
+    lines.push("── if a platform issue persists after Retry, escalate with this (no free-text “stuck”): ──");
+    lines.push(support);
+  }
+  return lines.join("\n");
+}
+
+// ── C5: auto-surface on failure (the PUSH) ───────────────────────────────────────
+
+/** How many findings the COMPACT summary lists before it defers the rest to the
+ *  full `tot preview doctor` report — enough to name the thing to fix, not the whole
+ *  multi-page report at a failure moment. */
+export const COMPACT_FINDING_LIMIT = 3;
+
+/**
+ * Render the COMPACT "here's what's blocking you" summary appended to a failed
+ * accept/integrate or a refused ship (C5). Unlike {@link formatReport} (the full
+ * on-demand report), this lists ONLY the actionable (blocker/warn) findings, capped
+ * at {@link COMPACT_FINDING_LIMIT}, and points at the full report for the rest. Returns
+ * an EMPTY array when there's nothing actionable to say (a clean/info-only verdict, or
+ * no analysis at all) — so a failure whose cause the doctor can't see gets NO noise
+ * appended. Pure — returns the lines to print, never prints itself.
+ * @param {ReturnType<typeof normalizeAnalysis>|null} result
+ * @param {{ limit?: number }} [opts]
+ * @returns {string[]}
+ */
+export function formatCompactSummary(result, { limit = COMPACT_FINDING_LIMIT } = {}) {
+  if (!result || !Array.isArray(result.findings)) return [];
+  const actionable = result.findings.filter((f) => f?.severity === "blocker" || f?.severity === "warn");
+  if (!actionable.length) return [];
+  const lines = [`\n  ── merge doctor — what's blocking your merges:`];
+  lines.push(`  ${attentionBanner(result)}`);
+  for (const f of actionable.slice(0, limit)) {
+    const act = f.action?.label ? `  [${f.action.label}]` : "";
+    lines.push(`    ${SEV_GLYPH[f.severity] ?? "?"} [${f.code}] (${OWN_TAG[f.ownership] ?? f.ownership}) ${f.subject}${act}`);
+    if (f.remedy) lines.push(`      → ${f.remedy}`);
+  }
+  const more = actionable.length - limit;
+  lines.push(
+    more > 0
+      ? `    …and ${more} more — run \`tot preview doctor\` for the full report.`
+      : `    Run \`tot preview doctor\` for the full report.`,
+  );
+  return lines;
+}
+
+/**
+ * One GET to the hosted merge-doctor over an ALREADY-RESOLVED transport (the SAME
+ * `base` + `authHeaders` the calling verb used to reach `/api/changes` /
+ * `/api/changes/ship`), normalized to the analysis shape. Best-effort by contract:
+ * ANY failure (unreachable, non-2xx incl. the 401/403 an auth-refused caller would
+ * also hit, non-JSON body, a throw) resolves to `null` — the doctor is a diagnostic
+ * ADD-ON at a failure moment, so it must never itself become a second failure. Pure
+ * given the injected fetch.
+ * @param {{ base:string, authHeaders:Record<string,string> }} transport
+ * @param {typeof fetch} [fetchImpl]
+ * @returns {Promise<ReturnType<typeof normalizeAnalysis>|null>}
+ */
+export async function fetchDoctorAnalysis({ base, authHeaders }, fetchImpl = globalThis.fetch) {
+  try {
+    const res = await fetchImpl(`${String(base).replace(/\/+$/, "")}${DOCTOR_PATH}`, {
+      method: "GET",
+      headers: authHeaders,
+    });
+    if (!res || !res.ok) return null;
+    let data = {};
+    try {
+      data = await res.json();
+    } catch {
+      return null;
+    }
+    return normalizeAnalysis(data);
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * C5 entry point: fetch the merge-doctor over the given transport and render the
+ * COMPACT failure summary. Returns the lines to print (or `[]` when there's nothing
+ * actionable / the doctor couldn't be reached). Never throws — a caller can
+ * `for (const l of await autoSurfaceDoctor(...)) console.error(l)` unconditionally at
+ * a failure return without touching the exit code.
+ * @param {{ base:string, authHeaders:Record<string,string>, fetchImpl?:typeof fetch, limit?:number }} opts
+ * @returns {Promise<string[]>}
+ */
+export async function autoSurfaceDoctor({ base, authHeaders, fetchImpl = globalThis.fetch, limit }) {
+  try {
+    const analysis = await fetchDoctorAnalysis({ base, authHeaders }, fetchImpl);
+    return formatCompactSummary(analysis, { limit });
+  } catch {
+    return [];
+  }
+}