@tokenoftrust/cli 1.4.0 → 1.5.0

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`), 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 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");
+}
+
+// ── 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. 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;
+  }
+}
+
+/**
+ * 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 [];
+  }
+}

package/src/no-gitea-links.test.mjs

@@ -0,0 +1,55 @@
+// Regression guard: the `tot` CLI must never print/reference a raw Gitea
+// forge URL to a developer's terminal. Gitea's API returns `html_url` when a
+// PR is opened (e.g. `https://git.tokenoftrust.com/storefront/<repo>/pulls/<n>`)
+// -- the CLI must surface the storefront-owned `/preview/<tenant>/pr/<n>` link
+// instead (see apps/storefront's matching noGiteaLinks.test.ts and its header
+// for the full architecture reasoning: apps/CLI never expose the forge
+// directly, the MCP proxies every read/write). Precipitating incident
+// (2026-08-18): a raw git.tokenoftrust.com PR URL reached an owner reviewing
+// tokenoftrust.com. Test fixtures are exempt (they legitimately mock a Gitea
+// URL to test the forge client), everything else in `src` must stay clean.
+import { readdirSync, readFileSync, statSync } from "node:fs";
+import { join, relative, dirname } from "node:path";
+import { fileURLToPath } from "node:url";
+import { test } from "node:test";
+import assert from "node:assert/strict";
+
+const SELF = fileURLToPath(import.meta.url);
+const SRC_ROOT = dirname(SELF);
+
+const TEST_FILE_RE = /\.test\.[cm]?js$/;
+const FORGE_HOST_RE = /\bgit\.tokenoftrust\.com\b/i;
+const SKIP_DIRS = new Set(["node_modules", "dist", ".git"]);
+
+function walk(dir, out = []) {
+  for (const entry of readdirSync(dir)) {
+    if (SKIP_DIRS.has(entry)) continue;
+    const full = join(dir, entry);
+    const st = statSync(full);
+    if (st.isDirectory()) {
+      walk(full, out);
+    } else if (/\.[cm]?js$/.test(entry)) {
+      out.push(full);
+    }
+  }
+  return out;
+}
+
+test("no Gitea forge links in the CLI source outside test fixtures", () => {
+  const offenders = [];
+  for (const file of walk(SRC_ROOT)) {
+    if (TEST_FILE_RE.test(file)) continue;
+    if (file === SELF) continue;
+    const content = readFileSync(file, "utf8");
+    content.split("\n").forEach((line, i) => {
+      if (FORGE_HOST_RE.test(line)) {
+        offenders.push(`${relative(SRC_ROOT, file)}:${i + 1}: ${line.trim()}`);
+      }
+    });
+  }
+  assert.deepEqual(
+    offenders,
+    [],
+    `Found Gitea forge links in non-test CLI source:\n${offenders.join("\n")}`,
+  );
+});

package/src/oauth.mjs

@@ -14,7 +14,7 @@
  *   5. exchange code -> { access_token, refresh_token, expires_in } with the PKCE
  *      verifier, and hand back a credentials record the token-store persists.
  *
- * B3 adds the RFC 8628 device-authorization grant (deviceLoginFlow, below) for
+ * This adds the RFC 8628 device-authorization grant (deviceLoginFlow, below) for
  * headless/SSH/no-browser boxes where the loopback can never be reached — same
  * dynamically-registered client_id, same credentials shape, just a different
  * dance: print a code, poll the token endpoint until it's approved elsewhere.
@@ -38,7 +38,7 @@ const b64url = (buf) =>
   buf.toString("base64").replace(/\+/g, "-").replace(/\//g, "_").replace(/=+$/, "");
 
 /** Thrown by loginFlow() when no browser opener exists on this box. Callers
- * catch it to fall through to deviceLoginFlow() (B3) instead of hanging. */
+ * catch it to fall through to deviceLoginFlow() instead of hanging. */
 export class NoOpenerError extends Error {
   constructor(authorizeUrl) {
     super("no browser opener available on this machine");
@@ -84,7 +84,7 @@ export async function registerClient(
     headers: { "Content-Type": "application/json", Accept: "application/json" },
     body: JSON.stringify({
       client_name: CLIENT_NAME,
-      // Include the device-code grant: the browserless rendezvous + B3 device flows
+      // Include the device-code grant: the browserless rendezvous + device flows
       // redeem their device_code at /oauth/token with this grant, so a client
       // registered WITHOUT it gets "unauthorized_client: grant_type is invalid".
       grant_types: [
@@ -188,7 +188,7 @@ export function startLoopbackListener({ host = "127.0.0.1" } = {}) {
   let settle, reject;
   const callback = new Promise((res, rej) => { settle = res; reject = rej; });
   const server = http.createServer((req, res) => {
-    const u = new URL(req.url, `http://${host}`);
+    const u = new URL(req.url ?? "/", `http://${host}`);
     if (u.pathname !== "/callback") {
       res.writeHead(404, { "Content-Type": "text/plain" });
       res.end("not found");
@@ -204,12 +204,12 @@ export function startLoopbackListener({ host = "127.0.0.1" } = {}) {
       settle({ code: u.searchParams.get("code"), state: u.searchParams.get("state") });
     }
   });
-  const listening = new Promise((res, rej) => {
+  const listening = /** @type {Promise<void>} */ (new Promise((res, rej) => {
     server.once("error", rej);
     server.listen(0, host, () => res());
-  });
+  }));
   return {
-    async ready() { await listening; return server.address().port; },
+    async ready() { await listening; return /** @type {import("net").AddressInfo} */ (server.address()).port; },
     waitForCallback() { return callback; },
     close() { try { server.close(); } catch { /* already closed */ } },
   };
@@ -247,7 +247,7 @@ export async function loginFlow({
   clientId,
   fetchImpl = fetch,
   open = openBrowser,
-  log = () => {},
+  log = /** @type {(m?: string) => void} */ (() => {}),
   now = () => Date.now(),
 }) {
   const meta = await discoverMetadata(mcpUrl, fetchImpl);
@@ -266,8 +266,8 @@ export async function loginFlow({
     const opened = open(authorizeUrl);
     if (!opened) {
       // No opener on this box (headless/SSH) — the loopback can never be hit
-      // from here, so waiting on it would hang forever. Let the caller (B3:
-      // login.mjs#loginAndCache) fall through to deviceLoginFlow() instead.
+      // from here, so waiting on it would hang forever. Let the caller
+      // (login.mjs#loginAndCache) fall through to deviceLoginFlow() instead.
       throw new NoOpenerError(authorizeUrl);
     }
 
@@ -364,7 +364,7 @@ export async function rendezvousLoginFlow({
   mcpUrl,
   code,
   fetchImpl = fetch,
-  log = () => {},
+  log = /** @type {(m?: string) => void} */ (() => {}),
   sleep = delay,
   now = () => Date.now(),
 }) {
@@ -408,7 +408,7 @@ export async function rendezvousLoginFlow({
   });
 }
 
-// ── B3: device-code grant (RFC 8628) — headless/SSH/no-browser sign-in ────────
+// ── Device-code grant (RFC 8628) — headless/SSH/no-browser sign-in ────────
 
 /**
  * RFC 8628 §3.1 — request a device_code + user_code to display. Same request
@@ -474,11 +474,15 @@ async function deviceTokenPoll(tokenEndpoint, { deviceCode, clientId, codeVerifi
  * expires), honoring the server's `interval` and the `slow_down` backoff
  * (RFC 8628 §3.5: +5s, keep polling — not a failure). Injectable `sleep`/
  * `now` so it's testable with no real waiting.
+ * @param {string} tokenEndpoint
+ * @param {{ deviceCode: any, clientId: any, codeVerifier?: any, intervalSec?: any, expiresInSec?: any }} params
+ * @param {typeof fetch} [fetchImpl]
+ * @param {{ sleep?: Function, now?: () => number }} [timing]
  * @returns {Promise<object>} the raw token response (→ credentialsFromToken)
  */
 export async function pollDeviceToken(
   tokenEndpoint,
-  { deviceCode, clientId, codeVerifier, intervalSec, expiresInSec },
+  { deviceCode, clientId, codeVerifier = undefined, intervalSec, expiresInSec },
   fetchImpl = fetch,
   { sleep = delay, now = () => Date.now() } = {},
 ) {
@@ -505,7 +509,7 @@ export async function deviceLoginFlow({
   mcpUrl,
   clientId,
   fetchImpl = fetch,
-  log = () => {},
+  log = /** @type {(m?: string) => void} */ (() => {}),
   sleep = delay,
   now = () => Date.now(),
 }) {

package/src/obstacle-beacon.cjs

@@ -103,9 +103,9 @@ function beacon(opts, done) {
 
 /** Promise wrapper for the ESM side (src/obstacle.mjs) so a failure path can await delivery. */
 function beaconAsync(opts) {
-  return new Promise(function (resolve) {
+  return /** @type {Promise<void>} */ (new Promise(function (resolve) {
     try { beacon(opts, resolve); } catch (e) { resolve(); }
-  });
+  }));
 }
 
 module.exports = { parseActivityArgs: parseActivityArgs, beacon: beacon, beaconAsync: beaconAsync };

package/src/obstacle.mjs

@@ -19,7 +19,7 @@ import { defaultCredentialsPath, readCredentials } from "./token-store.mjs";
  * Best-effort obstacle beacon for a post-login failure. No-op (silent) when no
  * bridge credential is cached — the developer signed in with a build that didn't
  * carry the activity flags, or ran a bare `tot login`.
- * @param {"pnpm-missing"|"install-failed"|"clone-failed"} kind
+ * @param {"pnpm-missing"|"install-failed"|"clone-failed"|"renderer-native-bindings-missing"} kind
  * @param {{ have?: string, need?: string, env?: NodeJS.ProcessEnv }} [opts]
  */
 export async function emitObstacle(kind, { have, need, env = process.env } = {}) {

package/src/plan.mjs

@@ -1,11 +1,11 @@
 /**
- * The shared "operation plan" affordance (unit U10) — the load-bearing
- * cross-cutting requirement from decision `operator-verb-and-hosting-model`:
- * every MUTATING operator verb (build / accept / ship / retire) must STATE
+ * The shared "operation plan" affordance — the load-bearing
+ * cross-cutting requirement that
+ * every MUTATING operator verb (build / accept / ship / cleanup) must STATE
  * EXACTLY what it will do — which PR is queued/integrated/deployed, which
  * deploy targets (preview / live) are touched, and their URLs — and get an
  * explicit confirm before acting. (`accept` now queue-integrates a PR into the
- * `preview` aggregate — unit b08 — rather than merging it to main.) No silent multi-step mutations, in either surface (the CLI
+ * `preview` aggregate — rather than merging it to main.) No silent multi-step mutations, in either surface (the CLI
  * here, and `AdminPublishTab.astro`'s confirm dialog, which renders the same
  * shape of plan text server-side/inline).
  *
@@ -15,8 +15,8 @@
  * half — print the plan, then gate on an explicit yes (reusing `prompt.mjs`'s
  * TTY-safe `promptYesNo`; a non-TTY without `--yes` never silently proceeds).
  *
- * SHIP has ONE meaning (unit b10 — supersedes the retired context-dependent
- * ship, decision `ship-context-dependent-semantics`): it publishes the
+ * SHIP has ONE meaning (supersedes the retired context-dependent ship
+ * semantics): it publishes the
  * tenant's CURRENT GREEN AGGREGATE — the batch of PRs that integrated
  * cleanly — to live. No merge, no PR/candidate targeting, no developer-vs-
  * operator branching. The plan states the pinned aggregate sha, its
@@ -46,19 +46,23 @@ function targetLabel({ pr, changeId }) {
  * console output, no network, no prompting.
  *
  * @param {{
- *   action: "build"|"accept"|"ship"|"retire",
+ *   action: "build"|"accept"|"ship"|"revert"|"cleanup"|"hotfix",
  *   tenant: string,
  *   pr?: number|string|null,
  *   changeId?: string|null,
  *   headSha?: string|null,
+ *   integrationSha?: string|null,
  *   endpoint?: string|null,
  *   targets?: { preview?: string|null, live?: string|null },
  *   context?: "developer"|"operator",
  *   pinnedSha?: string|null,
  *   artifactDigest?: string|null,
- *   includedPrs?: Array<{ prNumber?: number|null, changeId?: string|null, headSha?: string|null }>,
+ *   includedPrs?: Array<{ prNumber?: number|null, changeId?: string|null, headSha?: string|null }>|null,
  *   rollbackTarget?: { receiptId: string, aggregateSha: string } | null,
  *   paywall?: { allowed: boolean, message?: string|null } | null,
+ *   refs?: Array<{ ref: string, sha?: string|null, reason?: string|null }>|null,
+ *   bypassedPrs?: Array<{ prNumber?: number|null, changeId?: string|null, headSha?: string|null }>|null,
+ *   bypassedPreviewSha?: string|null,
  * }} params
  * @returns {string[]} plan lines (no leading/trailing blank line)
  */
@@ -68,6 +72,7 @@ export function planForAction({
   pr = null,
   changeId = null,
   headSha = null,
+  integrationSha = null,
   endpoint = null,
   targets = {},
   context = "operator",
@@ -76,6 +81,9 @@ export function planForAction({
   includedPrs = null,
   rollbackTarget = null,
   paywall = null,
+  refs = null,
+  bypassedPrs = null,
+  bypassedPreviewSha = null,
 }) {
   void context; // retained param — no action currently branches on it (ship, the
   // last one that did, is now ONE meaning; kept so a future action can opt in).
@@ -85,6 +93,7 @@ export function planForAction({
   if (pr != null && `${pr}`.trim()) lines.push(`  PR:        #${pr}`);
   if (changeId) lines.push(`  change id: ${changeId}`);
   if (headSha) lines.push(`  head sha:  ${headSha}`);
+  if (integrationSha) lines.push(`  integration sha: ${integrationSha}`);
   if (endpoint) lines.push(`  endpoint:  POST ${endpoint}`);
 
   switch (action) {
@@ -96,7 +105,7 @@ export function planForAction({
       break;
     }
     case "accept": {
-      // Accept now means QUEUE-INTEGRATE-INTO-PREVIEW (unit b08), NOT merge-to-main:
+      // Accept now means QUEUE-INTEGRATE-INTO-PREVIEW, NOT merge-to-main:
       // the candidate lands in the protected `preview` aggregate (serialized merge →
       // rebuild → combined-evidence gate), and the aggregate goes live only later via
       // `tot ship`. So the plan states the integration, never a merge or a go-live.
@@ -107,8 +116,8 @@ export function planForAction({
       break;
     }
     case "ship": {
-      // ONE meaning (b10): publish the tenant's CURRENT GREEN AGGREGATE to live.
-      // No merge — b09's orchestrator ships the already-materialized, already-
+      // ONE meaning: publish the tenant's CURRENT GREEN AGGREGATE to live.
+      // No merge — the orchestrator ships the already-materialized, already-
       // reviewed digest. State exactly WHAT that is: the pinned sha, the
       // content-addressed artifact digest, every included PR, the rollback
       // target, and the go-live paywall verdict — so the human reviews the
@@ -136,8 +145,65 @@ export function planForAction({
       }
       break;
     }
-    case "retire": {
-      lines.push(`  effect:    evict ${label}'s preview environment + version (rebuildable).`);
+    case "cleanup": {
+      // Branch GC: delete ONLY the exact terminal refs a fresh
+      // server-side classification (candidate_list) marked eligible — never by
+      // age alone, never main/preview, never an orphan. State the exact set so
+      // the human confirms precisely what will be removed, not "some branches".
+      const list = Array.isArray(refs) ? refs : [];
+      lines.push(
+        `  effect:    delete ${list.length} terminal candidate branch(es) — never main/preview, ` +
+          "never by age alone, never a quarantined orphan.",
+      );
+      for (const r of list) {
+        const shortSha = r?.sha ? ` ${String(r.sha).slice(0, 8)}` : "";
+        lines.push(`    - ${r?.ref}${shortSha}${r?.reason ? `  — ${r.reason}` : ""}`);
+      }
+      break;
+    }
+    case "revert": {
+      // Revert: REMOVE already-integrated content from the protected `preview`
+      // aggregate by creating a NEW auditable revert commit — never a force-reset,
+      // never a branch delete. The aggregate rebuilds and ships only when green
+      // again. State exactly that: preview-only, a new commit, NO touch to main.
+      const from = tenant ? `${tenant}'s preview aggregate` : "the preview aggregate";
+      const what = integrationSha ? `integration ${integrationSha}` : label;
+      lines.push(
+        `  effect:    revert ${what} out of ${from} — a NEW revert commit, NO force-reset, NO merge to main, NO go-live.`,
+      );
+      break;
+    }
+    case "hotfix": {
+      // Hotfix: the EXPLICIT EXCEPTION lane. Release the reviewed fix from
+      // `main` to live, EXCLUDING the unshipped `preview` work — then automatically
+      // forward-integrate `main` into `preview` and re-validate. State exactly that,
+      // and — critically — list the unshipped preview work this deliberately BYPASSES,
+      // so the human confirms an unmistakable exception, not an ordinary ship.
+      lines.push(
+        `  effect:    OWNER HOTFIX — release ${label} from main to live${targets.live ? ` (${targets.live})` : ""}, ` +
+          `EXCLUDING the unshipped preview head, then forward-integrate main → preview + revalidate.`,
+      );
+      if (Array.isArray(bypassedPrs)) {
+        if (bypassedPrs.length === 0) {
+          lines.push("  bypasses:  (nothing — preview has no unshipped work)");
+        } else {
+          lines.push(`  ⚠ BYPASSES the unshipped preview work (${bypassedPrs.length}) — NOT included in this hotfix:`);
+          for (const p of bypassedPrs) {
+            const prLabel = p && p.prNumber != null ? `#${p.prNumber}` : p?.changeId || "(no PR)";
+            const shortSha = p && p.headSha ? ` ${String(p.headSha).slice(0, 8)}` : "";
+            lines.push(`    - ${prLabel}${shortSha}`);
+          }
+        }
+      }
+      if (bypassedPreviewSha) lines.push(`  preview head (bypassed): ${bypassedPreviewSha}`);
+      lines.push(
+        rollbackTarget
+          ? `  rollback to: ${rollbackTarget.aggregateSha} (receipt ${rollbackTarget.receiptId})`
+          : "  rollback to: (none — first-ever ship)",
+      );
+      if (paywall && paywall.allowed === false) {
+        lines.push(`  ⚠ paywall:   ${paywall.message || "go-live is blocked by the storefront subscription gate"}`);
+      }
       break;
     }
     default: {
@@ -148,12 +214,14 @@ export function planForAction({
   return lines;
 }
 
-/** "build" → "Build-on-demand", "accept" → "Accept", "ship" → "Ship", "retire" → "Retire". Pure. */
+/** "build" → "Build-on-demand", "accept" → "Accept", … "hotfix" → "Hotfix". Pure. */
 function titleFor(action) {
   if (action === "build") return "Build-on-demand";
   if (action === "accept") return "Accept";
   if (action === "ship") return "Ship";
-  if (action === "retire") return "Retire";
+  if (action === "revert") return "Revert";
+  if (action === "cleanup") return "Cleanup";
+  if (action === "hotfix") return "Hotfix (owner-only exception lane)";
   return action ? action[0].toUpperCase() + action.slice(1) : "Operation";
 }
 

package/src/sample.mjs

@@ -21,7 +21,7 @@
  *
  * (Earlier this borrowed a real vape merchant's identity + content to get a
  * populated catalog; that leaked private merchant IP into public npm and was
- * replaced — see the H1/H2 runner-sanitization work — with this generic sample.)
+ * replaced — see the runner-sanitization work — with this generic sample.)
  *
  * Dependency-free (node:fs + node:path only).
  */
@@ -94,7 +94,7 @@ export function pickNvmrcVersion(env = process.env) {
     const best = readdirSync(root)
       .map((name) => /^v(\d+)\.(\d+)\.(\d+)$/.exec(name))
       .filter((m) => m && nodeMeetsFloor(m.slice(1).join(".")))
-      .map((m) => m.slice(1).map(Number))
+      .map((m) => /** @type {RegExpExecArray} */ (m).slice(1).map(Number))
       .sort((a, b) => b[0] - a[0] || b[1] - a[1] || b[2] - a[2])[0];
     if (best) return best.join(".");
   } catch {
@@ -177,7 +177,7 @@ export function scaffoldSample(destDir, { force = false, log = () => {} } = {})
     const err = new Error(
       `${dir} isn't empty and isn't a sample checkout — scaffold into an empty directory (or pass a new --workspace)`,
     );
-    err.code = "ENOTEMPTY_SAMPLE";
+    /** @type {any} */ (err).code ="ENOTEMPTY_SAMPLE";
     throw err;
   }
 
@@ -187,7 +187,7 @@ export function scaffoldSample(destDir, { force = false, log = () => {} } = {})
       "the sample store isn't available in this release yet — it's coming soon. " +
         "To build a real store now: `tot login --code <invite>` then `tot start`.",
     );
-    err.code = "SAMPLE_UNAVAILABLE";
+    /** @type {any} */ (err).code ="SAMPLE_UNAVAILABLE";
     throw err;
   }