@tokenoftrust/cli 1.4.0 → 1.5.0

package/src/commands/revert.mjs

@@ -0,0 +1,322 @@
+/**
+ * `tot revert --preview <PR|integration-sha>` — OPERATOR verb: REMOVE
+ * already-integrated content from the protected `preview` AGGREGATE by creating a
+ * NEW auditable revert commit, then rebuilding the aggregate. It is the explicit,
+ * safe answer to "several candidates are accepted, but one must be removed"
+ * (branch-lifecycle contract): NEVER a force-reset, NEVER a branch delete — a revert
+ * is a new commit on `preview`, and the shared preview moves only when the rebuilt
+ * aggregate is green again. Full history is preserved.
+ *
+ * DISTINCT from `tot ship`: revert is NOT go-live. It touches NO `main` and NO live
+ * channel; it only rewinds the SHARED preview aggregate. The verb is `--preview`-only
+ * by construction — there is no `--main` revert. To undo something already LIVE, use
+ * `tot rollback` (a live re-point), not this.
+ *
+ * TARGET — `--preview <target>` names EITHER a PR number (`42` or `#42`) OR an exact
+ * `preview` integration SHA. A numeric target is sent as `prNumber`; anything else as
+ * `integrationSha`. The server resolves either to the exact integration commit to
+ * undo (the resolver, inside the tenant-serialized queue lock), and REFUSES a
+ * target that was never integrated or has already been reverted.
+ *
+ * TRANSPORT — `POST /api/changes/revert` (the ONE call site of
+ * `TenantIntegrationQueue.enqueueRevert`). Like `tot accept` / `tot ship`, the CLI
+ * reaches it with the OPERATOR-SECRET Bearer transport (`resolveOperatorSecret` +
+ * `X-Tot-Owner` + `x-tot-capability`). The response is the honest terminal aggregate
+ * state — `queueState` / `runState` / `pointerMoved` / `aggregateSha` /
+ * `revertedSha` / `statusMessage` — rendered VERBATIM, never a bare "reverted".
+ *
+ * HUMAN GATE — rewinding the shared preview is a decision a human makes, so this
+ * ALWAYS states the EXACT plan (a NEW revert commit, NO force-reset, NO touch to
+ * main/live) and requires an explicit confirm. `--yes` is an explicit affirmative; a
+ * non-TTY without `--yes` is refused (mirrors `tot accept` / `tot ship`).
+ *
+ * Dependency-free (global fetch + the shared plan module).
+ */
+import { fail } from "../errors.mjs";
+import { planForAction, printPlanAndConfirm } from "../plan.mjs";
+// Reuse `tot ship`'s operator-secret precedence verbatim so accept + ship + revert
+// speak ONE operator-auth contract.
+import { resolveOperatorSecret } from "./ship.mjs";
+
+const DEFAULT_STOREFRONT_URL = "https://storefront.tokenoftrust.store";
+
+const USAGE = `tot revert — remove already-integrated content from the preview aggregate (auditable)
+
+  tot revert --preview <PR|integration-sha> --tenant <t>
+
+  Creates a NEW auditable revert commit on the tenant's protected \`preview\`
+  aggregate that undoes one prior integration, then rebuilds the aggregate and
+  runs combined evidence. The shared preview advances only when it is GREEN
+  again. A revert is NEVER a force-reset and NEVER deletes commits — full history
+  is preserved. It does NOT touch main and does NOT go live.
+
+  <PR|integration-sha> is EITHER a PR number (e.g. 42 or #42) OR an exact preview
+  integration SHA. A target that was never integrated, or has already been
+  reverted, is refused before any change is made.
+
+  Rewinding the shared preview is a human decision: this ALWAYS prints the exact
+  plan and asks for an explicit confirm. A non-TTY without --yes is refused.
+
+Options:
+  --preview <PR|sha>     REQUIRED. The PR number or integration SHA to revert.
+  --tenant <appDomain>   Target tenant (e.g. tokenoftrust.com). Defaults to the
+                         current checkout's tenant when run inside one.
+  --message <msg>        Optional revert-commit message.
+  --url <origin>         storefront origin (default: env TOT_STOREFRONT_URL)
+  --secret <s>           operator secret (prefer the env vars below)
+  --yes, -y              Skip the interactive confirm (still an explicit human
+                         affirmative — there is no default-yes).
+  --help, -h             Show this help.
+
+  To undo something already LIVE, use \`tot rollback\` — not \`tot revert\`.
+
+  Operator secret (from env, first found): PREVIEW_RECONCILE_SECRET,
+  GRANTS_ADMIN_SECRET, TOT_OPERATOR_SECRET (or pass --secret).`;
+
+/** Parse `tot revert` argv. Pure — unit-testable. */
+export function parseRevertArgs(argv) {
+  const a = {
+    preview: null,
+    tenant: null,
+    message: null,
+    url: null,
+    secret: null,
+    yes: false,
+    help: false,
+  };
+  for (let i = 0; i < argv.length; i++) {
+    const t = argv[i];
+    if (t === "--preview") a.preview = argv[++i];
+    else if (t === "--tenant") a.tenant = argv[++i];
+    else if (t === "--message" || t === "-m") a.message = argv[++i];
+    else if (t === "--url") a.url = argv[++i];
+    else if (t === "--secret") a.secret = argv[++i];
+    else if (t === "--yes" || t === "-y") a.yes = true;
+    else if (t === "--help" || t === "-h") a.help = true;
+  }
+  return a;
+}
+
+/**
+ * Classify a `--preview` target into `{ prNumber }` or `{ integrationSha }`. A bare
+ * integer (optionally `#`-prefixed) is a PR number; anything else (a hex-ish SHA) is
+ * an integration SHA. Pure — unit-tested.
+ * @param {string|null} raw
+ * @returns {{ prNumber:number|null, integrationSha:string|null }}
+ */
+export function classifyRevertTarget(raw) {
+  const t = (raw || "").trim().replace(/^#/, "");
+  if (!t) return { prNumber: null, integrationSha: null };
+  if (/^\d+$/.test(t)) return { prNumber: Number(t), integrationSha: null };
+  return { prNumber: null, integrationSha: t };
+}
+
+/**
+ * Normalise a `POST /api/changes/revert` body to the honest terminal aggregate
+ * fields this verb renders. Reads defensively so a plausible field rename degrades
+ * rather than crashes. Pure — unit-tested.
+ * @param {any} data
+ */
+export function normalizeRevertResponse(data) {
+  const o = data && typeof data === "object" ? data : {};
+  return {
+    ok: o.ok === true,
+    queueState: typeof o.queueState === "string" ? o.queueState : null,
+    runState: typeof o.runState === "string" ? o.runState : null,
+    pointerMoved: o.pointerMoved === true,
+    aggregateSha: typeof o.aggregateSha === "string" ? o.aggregateSha : null,
+    revertedSha: typeof o.revertedSha === "string" ? o.revertedSha : null,
+    statusMessage: typeof o.statusMessage === "string" ? o.statusMessage : null,
+    reason: typeof o.reason === "string" ? o.reason : null,
+    changeId: typeof o.changeId === "string" ? o.changeId : null,
+    error: typeof o.error === "string" ? o.error : null,
+    raw: data,
+  };
+}
+
+/**
+ * Render the terminal aggregate status in house style — the honest queue/run state,
+ * NEVER a bare "reverted". Pure given its inputs; returns the process exit code.
+ * @param {ReturnType<typeof normalizeRevertResponse>} result
+ * @param {{ tenant:string, label:string }} ctx
+ * @returns {number}
+ */
+export function reportReverted(result, { tenant, label }) {
+  const state = `${result.queueState ?? "?"}/${result.runState ?? "—"}`;
+  if (result.ok) {
+    console.log(`\n  ✓ reverted ${label} out of ${tenant}'s preview aggregate — it is GREEN.`);
+    console.log(`  aggregate: ${state}${result.aggregateSha ? `  (${result.aggregateSha})` : ""}`);
+    if (result.revertedSha) console.log(`  reverted integration commit: ${result.revertedSha}`);
+    if (result.pointerMoved) console.log("  the shared preview pointer moved to the reverted aggregate.");
+    console.log("  → next: review the aggregate preview, then `tot ship` to publish it live.");
+    return 0;
+  }
+  // Honest non-green: the revert did NOT land in the shippable aggregate.
+  console.log(`\n  ✗ ${label} was NOT reverted out of ${tenant}'s preview aggregate.`);
+  console.log(`  aggregate: ${state}${result.reason ? `  (${result.reason})` : ""}`);
+  if (result.statusMessage) console.log(`  why: ${result.statusMessage}`);
+  if (result.reason === "target_not_found" || result.reason === "already_reverted") {
+    console.log(`  → check the target: \`tot ship\` shows the aggregate's included PRs.`);
+  } else {
+    console.log("  → the aggregate is unchanged (last green preserved); fix forward or retry.");
+  }
+  return 1;
+}
+
+/**
+ * The revert flow after args are parsed: state the exact plan, confirm, then POST
+ * `/api/changes/revert` (operator-secret transport) and render the honest terminal
+ * aggregate status. `fetch`/`confirmPlan` injected so it is unit-tested with no
+ * network/TTY.
+ *
+ * @param {{ tenant:string, prNumber:number|null, integrationSha:string|null,
+ *   message:string|null, secret:string, storefrontUrl?:string|null, yes?:boolean }} params
+ * @param {{ fetch?:typeof fetch, confirmPlan?:typeof printPlanAndConfirm }} [deps]
+ * @returns {Promise<number>} process exit code
+ */
+export async function runRevert(
+  { tenant, prNumber, integrationSha, message = null, secret, storefrontUrl = null, yes = false },
+  deps = {},
+) {
+  const fetchImpl = deps.fetch || globalThis.fetch;
+  const confirmPlan = deps.confirmPlan || printPlanAndConfirm;
+  const base = (storefrontUrl || DEFAULT_STOREFRONT_URL).trim().replace(/\/+$/, "");
+  const label = prNumber != null ? `PR #${prNumber}` : `integration ${integrationSha}`;
+
+  // 1. State the EXACT plan (shared affordance) — a NEW revert commit on
+  //    preview, NO force-reset, NO touch to main/live — and gate on a confirm.
+  const planLines = planForAction({
+    action: "revert",
+    tenant,
+    pr: prNumber,
+    integrationSha,
+  });
+  const { confirmed, reason } = await confirmPlan(planLines, {
+    yes,
+    question: `Revert ${label} out of ${tenant}'s preview aggregate (a new revert commit)?`,
+  });
+  if (!confirmed) {
+    if (reason === "non-tty") {
+      console.error(
+        fail(
+          "refusing to revert without confirmation on a non-TTY.",
+          "re-run with --yes (an explicit human affirmative), or from an interactive terminal.",
+        ),
+      );
+      return 2;
+    }
+    console.log("Aborted — nothing was reverted.");
+    return 1;
+  }
+
+  // 2. Operator-secret transport — the CLI holds no storefront cookie.
+  if (!secret) {
+    console.error(
+      fail(
+        "reverting the preview aggregate is an OPERATOR action — it needs an operator secret",
+        "set PREVIEW_RECONCILE_SECRET (or GRANTS_ADMIN_SECRET / TOT_OPERATOR_SECRET), or pass --secret",
+      ),
+    );
+    return 2;
+  }
+  const authHeaders = {
+    "content-type": "application/json",
+    authorization: `Bearer ${secret}`,
+    "x-tot-owner": tenant,
+    "x-tot-capability": "ship-on-behalf",
+  };
+  const requestBody = {
+    repo: tenant,
+    ...(prNumber != null ? { prNumber } : {}),
+    ...(integrationSha ? { integrationSha } : {}),
+    ...(message ? { message } : {}),
+  };
+
+  // 3. POST the honest revert path (queue enqueueRevert) and render terminal state.
+  let res;
+  try {
+    res = await fetchImpl(`${base}/api/changes/revert`, {
+      method: "POST",
+      headers: authHeaders,
+      body: JSON.stringify(requestBody),
+    });
+  } catch (e) {
+    console.error(
+      fail(`couldn't reach the revert endpoint 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 */
+  }
+  const result = normalizeRevertResponse(data);
+
+  // A pre-flight error (auth, unknown tenant, bad body) is an HTTP 4xx with
+  // `{ error }` and no queue verdict — surface it distinctly from a red run.
+  if (!res.ok && result.queueState == null) {
+    const msg = result.error || `HTTP ${res.status}`;
+    console.error(
+      fail(
+        `the revert request was refused: ${msg}`,
+        res.status === 401 || res.status === 403
+          ? "check the operator secret and that it's authorised for this tenant"
+          : "check --tenant / --url / --preview, then re-run",
+      ),
+    );
+    return 1;
+  }
+
+  return reportReverted(result, { tenant, label });
+}
+
+/**
+ * @param {string[]} argv
+ * @param {any} ctx
+ */
+export async function run(argv, ctx) {
+  const env = process.env;
+  const args = parseRevertArgs(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 { prNumber, integrationSha } = classifyRevertTarget(args.preview);
+  if (prNumber == null && !integrationSha) {
+    console.error(
+      fail(
+        "no revert target.",
+        "pass --preview <PR|integration-sha> (a PR number like 42, or an exact preview integration SHA).",
+      ),
+    );
+    return 2;
+  }
+
+  const storefrontUrl =
+    args.url || env.TOT_STOREFRONT_URL || env.STOREFRONT_BASE_URL || DEFAULT_STOREFRONT_URL;
+
+  return await runRevert({
+    tenant,
+    prNumber,
+    integrationSha,
+    message: (args.message || "").trim() || null,
+    secret: resolveOperatorSecret(args.secret, env),
+    storefrontUrl,
+    yes: args.yes,
+  });
+}

package/src/commands/rollback.mjs

@@ -7,17 +7,17 @@
  *   tot rollback <versionId>  re-point the live channel back to that version
  *
  * This does NOT reimplement pointer moves. Every selection and every move goes
- * through u3's MCP-side live-pointer seam (`promotion_status` /
+ * through the MCP-side live-pointer seam (`promotion_status` /
  * `promotion_rollback`, tot-mcp `src/modules/mcp/change/promotion-pointer-tools.ts`
  * + `promotion-pointer-store.ts`) — the SAME primitive `tot ship`'s eventual
- * orchestrator composes (decision storefront-atomic-accept-is-ship-orchestrator).
- * There is no dg4 ship-orchestrator service in-tree yet, so this calls the u3 seam
+ * orchestrator composes.
+ * There is no ship-orchestrator service in-tree yet, so this calls that seam
  * DIRECTLY; when the orchestrator lands it should absorb the physical
  * publish+verify this command currently leaves to it (see the seam's own
  * "NOT a live claim" caveat, echoed in `reportRolledBack` below) — a follow-on can
  * route through it instead without changing this file's UX.
  *
- * Fail-closed (decision static-publish-fails-closed-reviewed-sha): rollback selects
+ * Fail-closed: rollback selects
  * an immutable prior digest/versionId recorded by a PRIOR promote; a missing or
  * ineligible target is refused with a clear next step, never a silent no-op dressed
  * up as success. The eligibility check and the pointer move both come from the
@@ -41,7 +41,7 @@ import { startProgress } from "../progress.mjs";
 
 const DEFAULT_MCP_URL = "https://mcp.tokenoftrust.com";
 
-// The only publish channel the seam is exercised against today (see the u3 tests
+// The only publish channel the seam is exercised against today (see the tests
 // and `promotion_set`'s own default). A future multi-target store can override with
 // `--target`; nothing here assumes there's only ever one.
 const DEFAULT_TARGET = "production";
@@ -63,7 +63,9 @@ const USAGE = `tot rollback [<versionId>] — instant re-point to a prior live v
 
 /** Parse `tot rollback` argv. Pure. Deliberately NO --yes/--force (see the header). */
 export function parseRollbackArgs(argv) {
+  /** @type {{ versionId: string|null, target: string|null, mcp: string|null, identity: string|null, help: boolean }} */
   const a = { versionId: null, target: null, mcp: null, identity: null, help: false };
+  /** @type {string[]} */
   const positional = [];
   for (let i = 0; i < argv.length; i++) {
     const t = argv[i];
@@ -138,11 +140,11 @@ export function normalizeRollbackResult(r) {
   };
 }
 
-// ─── Revision links (pure, unit u5) ───────────────────────────────────────────────
+// ─── Revision links (pure) ───────────────────────────────────────────────
 
 /**
  * The immutable `/preview/<tenant>/rev/<sha>/` deep-link for a promoted
- * `versionId` — u4's route, and per `gitea-only-tenant-content-authority` the
+ * `versionId` — this route, and per `gitea-only-tenant-content-authority` the
  * `versionId` recorded by a promote IS the tenant Gitea sha, so no extra lookup
  * is needed to build it. `null` when there's no `base` (storefront origin) or no
  * `versionId` to link, so a caller can render the history line either way.
@@ -177,10 +179,10 @@ export function rollbackCandidates(history, currentVersionId) {
 }
 
 /** Render the `tot rollback` (no args) history listing — the rollback-target
- *  picker (unit u2), each entry annotated with its immutable `/rev/<sha>` link
- *  (unit u5) when a storefront origin is available. Pure — unit-tested.
- * @param {{ tenant:string, target:string, current:Record<string,unknown>|null,
- *   candidates:Record<string,unknown>[], revisionBase?:string|null }} input
+ *  picker, each entry annotated with its immutable `/rev/<sha>` link
+ *  when a storefront origin is available. Pure — unit-tested.
+ * @param {{ tenant:string, target:string, current:any,
+ *   candidates:any[], revisionBase?:string|null }} input
  * @returns {string[]}
  */
 export function renderHistory({ tenant, target, current, candidates, revisionBase }) {
@@ -209,7 +211,7 @@ export function renderHistory({ tenant, target, current, candidates, revisionBas
  */
 export function renderRollbackPreview({ tenant, target, toVersionId, preview }) {
   const lines = ["", `  This rollback will change the LIVE site for ${tenant}:`];
-  const current = preview.pointer?.current;
+  const current = /** @type {any} */ (preview.pointer?.current);
   if (current) lines.push(`    ${target}: ${current.versionId} → ${toVersionId}`);
   else lines.push(`    ${target}: → ${toVersionId}`);
   return lines;
@@ -225,7 +227,7 @@ export function renderRollbackPreview({ tenant, target, toVersionId, preview })
  * @param {{callTool:Function}} client an MCP client (real or mock)
  * @param {{ tenant:string, target:string, toVersionId:string|null,
  *   revisionBase?:string|null }} params `revisionBase` is the storefront origin
- *   the listing's `/rev/<sha>` links resolve against (unit u5); omit to list
+ *   the listing's `/rev/<sha>` links resolve against; omit to list
  *   without links.
  * @param {{ interactive?:()=>boolean, confirm?:(q:string,d:boolean)=>Promise<boolean>,
  *   progress?:boolean }} [deps]
@@ -258,7 +260,7 @@ export async function runRollback(client, { tenant, target, toVersionId, revisio
       );
       return 1;
     }
-    const candidates = rollbackCandidates(status.history, status.current?.versionId ?? null);
+    const candidates = rollbackCandidates(status.history, /** @type {any} */ (status).current?.versionId ?? null);
     for (const line of renderHistory({ tenant, target, current: status.current, candidates, revisionBase })) {
       console.log(line);
     }
@@ -375,8 +377,8 @@ export async function run(argv, ctx) {
   const tenant = ctx.tenant;
   const target = args.target?.trim() || DEFAULT_TARGET;
   const baseUrl = args.mcp || env.MCP_BASE_URL || env.TOT_MCP_URL || DEFAULT_MCP_URL;
-  // The storefront origin the listing's /rev/<sha> links resolve against (unit
-  // u5) — owner == appDomain on this platform, mirroring go-live.mjs's default.
+  // The storefront origin the listing's /rev/<sha> links resolve against
+  // — owner == appDomain on this platform, mirroring go-live.mjs's default.
   const revisionBase = env.TOT_STOREFRONT_URL || (tenant ? `https://${tenant}` : null);
   const client = createMcpClient(baseUrl);
   try {

package/src/commands/ship.mjs

@@ -1,8 +1,7 @@
 /**
  * `tot ship` — publish the tenant's CURRENT GREEN AGGREGATE to live. ONE
- * meaning (unit b10 — SUPERSEDES the retired context-dependent ship, decision
- * `ship-context-dependent-semantics`, and its developer-accept-then-deploy /
- * operator-deploy-only / ship-any-built-PR branches):
+ * meaning — SUPERSEDES the retired context-dependent ship and its
+ * developer-accept-then-deploy / operator-deploy-only / ship-any-built-PR branches:
  *
  *   tot dev        run your store locally with save→reload
  *   tot preview    push it to a reviewable preview (validate → reconcile → compliance)
@@ -11,17 +10,17 @@
  * `tot ship` NEVER takes a PR/candidate target and NEVER infers context from
  * your checkout or who's running it. There is nothing to detect: it ships the
  * tenant's shared `preview` aggregate — the batch of PRs that integrated
- * cleanly and went green (b07's queue) — full stop. The candidate-level merge
+ * cleanly and went green — full stop. The candidate-level merge
  * is the separate `tot accept` verb (`accept.mjs`); ship never merges.
  *
  * THE FLOW:
  *
- *   1. GET the read-only PLAN from `/api/changes/ship` — b09's
+ *   1. GET the read-only PLAN from `/api/changes/ship` — the
  *      `AggregateShipOrchestrator.plan()` exposed over HTTP: the pinned
  *      aggregate sha, its content-addressed artifact digest, every included
  *      PR, the rollback target (what a rollback would restore), and the
  *      go-live paywall verdict. Zero side effects.
- *   2. Print the EXACT plan via the shared U10 affordance (`../plan.mjs`) and
+ *   2. Print the EXACT plan via the shared affordance (`../plan.mjs`) and
  *      require ONE explicit confirm, defaulting to NO. `--yes` confirms
  *      non-interactively; a non-TTY WITHOUT `--yes` REFUSES — nothing ships
  *      without an explicit yes.
@@ -47,6 +46,12 @@ import { fail } from "../errors.mjs";
 import { planForAction, printPlanAndConfirm } from "../plan.mjs";
 import { startProgress } from "../progress.mjs";
 import { openBrowser } from "../open.mjs";
+import { emitActivity } from "../activity.mjs";
+// 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";
 
@@ -97,7 +102,7 @@ export function parseShipArgs(argv) {
   return a;
 }
 
-// ─── Operator-secret transport (shared with `tot pr list --tenant` / u16/u17) ────
+// ─── Operator-secret transport (shared with `tot pr list --tenant`) ────
 //
 // `resolveOperatorSecret` / `normalizeChangesQueue` are the SAME helpers the
 // retired operator-by-PR ship path minted; `tot pr list --tenant` (`pr.mjs`)
@@ -149,9 +154,10 @@ export function normalizeChangesQueue(data) {
 
 // ─── Shared with `tot accept` (`accept.mjs`) ─────────────────────────────────────
 //
-// `tot accept` merges a PR into main over the MCP `change_accept`/`change_status`
-// tools — a DISTINCT operator verb from ship (no deploy). It imports these two
-// normalisers straight from here rather than re-implementing them.
+// `tot accept` queues a PR's integration into the protected `preview` aggregate
+// (NOT a merge to main — see accept.mjs's header) — a DISTINCT operator verb from
+// ship (no deploy). It imports these two normalisers straight from here rather
+// than re-implementing them.
 
 /**
  * Normalise a `change_accept` / `change_status` result to { shipped, state,
@@ -202,7 +208,7 @@ export function liveUrlFor(tenant) {
 // ─── Response normalisation (defensive — one endpoint, but shapes may vary) ─────
 
 /**
- * Normalise a `GET /api/changes/ship` body — b09's `AggregateShipPlan` (a
+ * Normalise a `GET /api/changes/ship` body — the `AggregateShipPlan` (a
  * shippable aggregate) or `AggregateShipRefusal` (nothing shippable), read
  * defensively since it crossed the wire as JSON. Pure — unit-tested.
  * @param {any} data
@@ -243,7 +249,7 @@ export function normalizeShipPlan(data) {
 }
 
 /**
- * Normalise a `POST /api/changes/ship` body — b09's `AggregateShipResult`.
+ * Normalise a `POST /api/changes/ship` body — the `AggregateShipResult`.
  * `state` is the ONLY honest terminal-state authority: render "shipped live"
  * for `"shipped"` and nothing else. Pure — unit-tested.
  * @param {any} data
@@ -325,6 +331,14 @@ export async function runShip({ tenant, secret, storefrontUrl = null, yes = fals
     "x-tot-capability": "ship-on-behalf",
   };
 
+  // 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;
@@ -354,10 +368,13 @@ 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;
   }
 
-  // 2. Print the EXACT plan via the shared U10 affordance, then require ONE
+  // 2. Print the EXACT plan via the shared affordance, then require ONE
   //    explicit confirm (`--yes` non-interactive; a non-TTY without it refuses).
   const liveUrl = liveUrlFor(tenant);
   const planLines = planForAction({
@@ -413,7 +430,27 @@ export async function runShip({ tenant, secret, storefrontUrl = null, yes = fals
   const shipData = await readJsonSafe(shipRes);
   progress?.stop();
 
-  return reportShipResult(normalizeShipResult(shipData), { tenant, liveUrl, noOpen, openUrl: deps.openUrl });
+  const shipResult = normalizeShipResult(shipData);
+  // Emit the ship publish lifecycle event — `tot ship` does no LOCAL git op
+  // (it's HTTP-orchestrated), so this marks the outcome of the publish step
+  // itself, distinct from the outer command's invoked/result pair. Fire-and-
+  // forget best-effort: a silent no-op without a hosted-bridge credential, never
+  // awaited, never throws, never alters the ship. `errorClass` stays low-
+  // cardinality (the orchestrator's own terminal state/reason, never free text).
+  const shipped = shipResult.state === "shipped";
+  void emitActivity({
+    action: "cli.command.result",
+    outcome: {
+      status: shipped ? "succeeded" : "failed",
+      ...(shipped ? {} : { errorClass: `ship_${shipResult.state}` }),
+    },
+    scope: { tenantId: tenant },
+    payload: { args: { command: "ship", subcommand: "ship.publish" } },
+  });
+
+  const code = reportShipResult(shipResult, { tenant, liveUrl, noOpen, openUrl: deps.openUrl });
+  if (code !== 0) await surfaceDoctor();
+  return code;
 }
 
 /**