@tokenoftrust/cli 1.4.0 → 1.4.1

package/src/commands/git-credential.mjs

@@ -0,0 +1,180 @@
+/**
+ * `tot git-credential` — git's own credential-helper protocol (see `git help
+ * gitcredentials`), implemented over the developer's cached `tot login`
+ * session (unit u10, workstream tot-merge-conflict-resolution-ux). `tot
+ * clone` configures a fresh checkout's `credential.helper` to run this (see
+ * ../git-credential.mjs's CREDENTIAL_HELPER), so `git fetch`/`git push`/`git
+ * pull` — run DIRECTLY by the developer, not just through `tot preview` —
+ * transparently mint a fresh forge token instead of ever needing one
+ * persisted in `.git/config`. This is the fix for the "the panel-prescribed
+ * `git fetch origin` fails even after `tot login`" dead-end: `tot login`
+ * only ever refreshed the CLI's OWN MCP session, never the token baked into
+ * a checkout's remote URL at clone time.
+ *
+ * git invokes this with ONE positional arg (`get`/`store`/`erase`) and the
+ * request on stdin (key=value lines, blank-line/EOF terminated). Only `get`
+ * does real work — this CLI never persists a forge credential of its own
+ * beyond the short-lived cache in ../git-credential.mjs, so `store`/`erase`
+ * are no-ops (git calls them after a successful/failed auth respectively; we
+ * just drain stdin and exit 0, the correct behavior for a stateless helper).
+ *
+ * FAILS SILENT, NEVER LOUD: `get` prints NOTHING and exits non-zero on any
+ * problem (not signed in, MCP unreachable, cwd isn't a recognizable tenant
+ * checkout) — git then falls through to its next configured helper or its
+ * own prompt, exactly as if this helper weren't configured. A stack trace or
+ * a malformed credential line here would otherwise corrupt EVERY git
+ * operation in the checkout. It also NEVER triggers an interactive sign-in —
+ * this runs as a non-interactive subprocess of `git`, so a missing session
+ * fails through rather than trying to open a browser mid-`git fetch`.
+ *
+ * Dependency-free (global fetch + `git`, via the same MCP client + auth
+ * module every other command uses).
+ */
+import { readFileSync } from "node:fs";
+import { execFileSync } from "node:child_process";
+import { createMcpClient } from "../mcp.mjs";
+import { establishSession } from "../auth.mjs";
+import { checkoutTenant } from "./clone.mjs";
+import { detectContext } from "../context.mjs";
+import { repoNameFromRemote, tagFromRepoName } from "./submit.mjs";
+import {
+  parseCredentialInput, formatCredentialOutput, splitAuthedRemote,
+  credentialCachePath, readCachedCredential, writeCachedCredential,
+} from "../git-credential.mjs";
+
+const DEFAULT_MCP_URL = "https://mcp.tokenoftrust.com";
+
+/** Does `remoteUrl`'s host equal `host` (case-insensitive)? An unparseable or
+ *  missing remote URL never matches — fail closed. Exported for testing. */
+export function hostMatches(remoteUrl, host) {
+  if (!remoteUrl || !host) return false;
+  try {
+    // scp-like remotes (git@host:owner/repo.git) have no scheme — synthesize one so URL can parse the host.
+    const normalized = /^[^/]+@[^/:]+:/.test(remoteUrl) ? `ssh://${remoteUrl.replace(":", "/")}` : remoteUrl;
+    return new URL(normalized).host.toLowerCase() === host.toLowerCase();
+  } catch {
+    return false;
+  }
+}
+
+/** Read the credential request git writes to stdin — blocking is correct
+ *  here: git writes the request then closes its end, so this returns as
+ *  soon as it's fully sent. Never blocks on an interactive terminal (git
+ *  NEVER attaches a TTY to a credential helper's stdin — only a human
+ *  poking at this command directly by hand would) and never throws (an
+ *  unreadable/absent stdin is treated as an empty request). Exported so a
+ *  test can inject a canned request instead of touching real fd 0. */
+export function readStdin() {
+  if (process.stdin.isTTY) return "";
+  try {
+    return readFileSync(0, "utf8");
+  } catch {
+    return "";
+  }
+}
+
+/**
+ * Mint (or reuse a cached) forge credential for the tenant the CURRENT
+ * directory checks out — the same `tenant_checkout` MCP call `tot clone`
+ * itself uses, so the credential is exactly as push-capable. Returns null on
+ * ANY failure (wrong dir, not signed in, MCP unreachable) rather than
+ * throwing — `get` treats null as "say nothing, exit non-zero".
+ *
+ * `createClient`/`establish`/`checkout` are injected (default to the real MCP
+ * client + auth + clone.mjs's checkoutTenant) purely so this is testable
+ * without a live MCP — same DI shape as chooseChangeId's injected `mint` /
+ * resolveDeveloperSession's injected `fetchImpl` elsewhere in this CLI.
+ * SCOPED TO THE CHECKOUT'S OWN REMOTE: `expectedHost` (git's requested host,
+ * from the credential-helper request) is checked against the host of this
+ * checkout's `origin` remote before a credential is ever minted or returned
+ * — a `get` for any OTHER host returns null (silent fail), never handing the
+ * tenant's forge token to a host this checkout doesn't itself push to. This
+ * matters because `credential.helper` is invoked per-URL by git, and a
+ * globally-scoped helper (or a checkout with a submodule / unrelated remote)
+ * must not become a way to exfiltrate the token to an arbitrary host.
+ * @param {{
+ *   env?: NodeJS.ProcessEnv, cwd?: string, expectedHost?: string,
+ *   createClient?: typeof createMcpClient,
+ *   establish?: typeof establishSession,
+ *   checkout?: typeof checkoutTenant,
+ * }} [opts]
+ * @returns {Promise<{username:string,password:string}|null>}
+ */
+export async function mintOrCacheCredential({
+  env = process.env, cwd = process.cwd(), expectedHost = null,
+  createClient = createMcpClient, establish = establishSession, checkout = checkoutTenant,
+} = {}) {
+  const ctx = detectContext(cwd);
+  if (ctx.mode !== "checkout" || !ctx.tenant) return null;
+
+  const git = (cargs) =>
+    execFileSync("git", ["-C", ctx.workspacePath, ...cargs], { stdio: ["ignore", "pipe", "pipe"] }).toString();
+  let originUrl = null;
+  let repoName = null;
+  try {
+    originUrl = git(["remote", "get-url", "origin"]).trim();
+    repoName = repoNameFromRemote(originUrl);
+  } catch {
+    /* fall through — tagFromRepoName degrades to "main" on a null repo name */
+  }
+  if (expectedHost && !hostMatches(originUrl, expectedHost)) return null;
+  const tag = tagFromRepoName(repoName, ctx.tenant);
+
+  const cachePath = credentialCachePath(ctx.tenant, tag, env);
+  const cached = readCachedCredential(cachePath);
+  if (cached) return { username: cached.username, password: cached.password };
+
+  const baseUrl = env.MCP_BASE_URL || env.TOT_MCP_URL || DEFAULT_MCP_URL;
+  const client = createClient(baseUrl);
+  try {
+    await establish(client, { env });
+  } catch {
+    return null; // not signed in (or session unrefreshable) — nothing this helper can do
+  }
+  try {
+    const res = await checkout(client, { tenant: ctx.tenant, tag, cloneDir: null });
+    const cred = splitAuthedRemote(res.gitRemote || "");
+    if (!cred) return null;
+    const fresh = { username: cred.username, password: cred.token };
+    writeCachedCredential(cachePath, fresh);
+    return fresh;
+  } catch {
+    return null; // MCP unreachable / tenant_checkout refused — say nothing, exit non-zero
+  }
+}
+
+const USAGE = `tot git-credential — git credential-helper protocol over your \`tot login\` session
+
+  Configured automatically by \`tot clone\` (credential.helper = !tot git-credential)
+  in every checkout it creates — you should never need to run this by hand.
+  See \`git help gitcredentials\` for the protocol this implements.`;
+
+/**
+ * @param {string[]} argv  argv[0] is git's operation: get|store|erase
+ * @param {any} _ctx  unused — this command derives its OWN context from cwd
+ *   (mintOrCacheCredential), since git invokes it with the credentialed
+ *   repo's directory as cwd, which may differ from wherever `tot` itself
+ *   was dispatched from.
+ * @param {{ env?: NodeJS.ProcessEnv, cwd?: string, readStdin?: typeof readStdin }
+ *   & Parameters<typeof mintOrCacheCredential>[0]} [opts]
+ */
+export async function run(argv, _ctx, opts = {}) {
+  const { env = process.env, readStdin: read = readStdin } = opts;
+  const op = argv[0];
+  if (!op || op === "--help" || op === "-h") {
+    console.log(USAGE);
+    return op ? 0 : 2;
+  }
+  // git always writes a request to stdin, even for store/erase — drain it either way
+  // so the subprocess exits cleanly instead of leaving git's write blocked on a full pipe.
+  const request = parseCredentialInput(read());
+
+  if (op !== "get") return 0; // store/erase: stateless, nothing to persist or drop.
+
+  const cred = await mintOrCacheCredential({ ...opts, expectedHost: request.host });
+  if (!cred) return 1; // silent — let git fall through to its next helper / its own prompt.
+  process.stdout.write(formatCredentialOutput({
+    protocol: request.protocol, host: request.host, username: cred.username, password: cred.password,
+  }));
+  return 0;
+}

package/src/commands/hotfix.mjs

@@ -0,0 +1,428 @@
+/**
+ * `tot hotfix` (unit b22) — the OWNER-ONLY EXCEPTION LANE: release an urgent
+ * production fix from `main` to live WHILE `preview` still contains other unshipped
+ * work, EXCLUDING that unshipped preview head, then automatically forward-integrate
+ * `main` into `preview` and re-validate.
+ *
+ *   tot dev / preview   build + review the fix (a `main`-based candidate)
+ *   tot hotfix --pr N   release THAT reviewed fix from main to live, bypassing preview  ← you are here
+ *
+ * This is a DELIBERATELY DISTINCT verb — NEVER a `--base main` flag on `tot ship`.
+ * `tot ship` publishes the tenant's current green PREVIEW aggregate; `tot hotfix`
+ * does the opposite in the one case that warrants it: it ships a `main`-based fix
+ * that does NOT include the in-flight preview work, and only then carries `main`
+ * forward into `preview`. Because rewinding what goes live around the normal queue
+ * is a serious exception, it ALWAYS shows the exact plan — including the unshipped
+ * preview work it BYPASSES — and requires an explicit confirm.
+ *
+ * THE FLOW (mirrors `tot ship`'s plan → confirm → act → honest-terminal-state):
+ *   1. GET the read-only PLAN from `/api/changes/hotfix` — the candidate, the
+ *      current live rollback target, the unshipped preview work bypassed, and the
+ *      paywall verdict. Zero side effects.
+ *   2. Print the EXACT plan and require ONE explicit confirm (default NO). `--yes`
+ *      confirms non-interactively; a non-TTY without `--yes` REFUSES.
+ *   3. On confirm, POST `/api/changes/hotfix` with `confirmGoLive: true`.
+ *   4. Report the orchestrator's HONEST terminal state verbatim — `shipped`
+ *      (live VERIFIED on the fix; the ONLY "shipped" state), `refused`,
+ *      `merge_failed` / `build_failed` / `promote_failed` / `record_failed`
+ *      (recoverable, never a false live) — PLUS the automatic forward-integration
+ *      outcome (green, or red + a fix-forward nudge; a red forward-integration
+ *      never un-ships the live fix).
+ *
+ * TRANSPORT: the operator-secret Bearer + `X-Tot-Owner`, the SAME transport as
+ * `tot ship` / `tot revert`. Dependency-free (global fetch + the shared plan module).
+ */
+import { fail } from "../errors.mjs";
+import { planForAction, printPlanAndConfirm } from "../plan.mjs";
+import { startProgress } from "../progress.mjs";
+import { openBrowser } from "../open.mjs";
+// Reuse `tot ship`'s operator-secret precedence + live-url derivation verbatim so
+// ship + hotfix speak ONE operator-auth contract.
+import { resolveOperatorSecret, liveUrlFor } from "./ship.mjs";
+
+const DEFAULT_STOREFRONT_URL = "https://storefront.tokenoftrust.store";
+
+const USAGE = `tot hotfix — OWNER-ONLY: release an urgent fix from main to live, bypassing preview
+
+  tot hotfix --pr <N> --tenant <t>
+  tot hotfix --change <changeId> --tenant <t>
+
+  The EXPLICIT EXCEPTION lane for an urgent production fix while \`preview\` holds
+  other unshipped work. It releases the reviewed, main-based fix to live WITHOUT the
+  unshipped preview head, then automatically forward-integrates main → preview and
+  re-validates the aggregate. It is NOT \`tot ship\` with a flag — \`tot ship\`
+  publishes the current green preview aggregate; \`tot hotfix\` deliberately excludes it.
+
+  It ALWAYS prints the exact plan — including the unshipped preview work it BYPASSES —
+  and asks for an explicit confirm. A non-TTY without --yes is refused.
+
+Options:
+  --pr <N>               The reviewed hotfix candidate's PR number.
+  --change <changeId>    The reviewed hotfix candidate's change id (alternative to --pr).
+  --tenant <appDomain>   Target tenant (e.g. tokenoftrust.com). Defaults to the
+                         current checkout's tenant when run inside one.
+  --message <msg>        Optional merge-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 affirmative).
+  --no-open              Don't open the live URL in your browser.
+  --help, -h             Show this help.
+
+  For the ordinary release of the whole green preview aggregate, use \`tot ship\`.
+  To undo something already LIVE, use \`tot rollback\`.
+
+  Operator secret (from env, first found): PREVIEW_RECONCILE_SECRET,
+  GRANTS_ADMIN_SECRET, TOT_OPERATOR_SECRET (or pass --secret).`;
+
+/** Parse `tot hotfix` argv. Pure — unit-testable. */
+export function parseHotfixArgs(argv) {
+  const a = {
+    pr: null,
+    change: null,
+    tenant: null,
+    message: null,
+    url: null,
+    secret: null,
+    yes: false,
+    noOpen: false,
+    help: false,
+  };
+  for (let i = 0; i < argv.length; i++) {
+    const t = argv[i];
+    if (t === "--pr") a.pr = argv[++i];
+    else if (t === "--change" || t === "--changeId") a.change = 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 === "--no-open") a.noOpen = true;
+    else if (t === "--help" || t === "-h") a.help = true;
+  }
+  return a;
+}
+
+/** Normalise a `?pr` value to a positive integer, or null. Pure. */
+export function parsePrNumber(raw) {
+  const t = (raw == null ? "" : `${raw}`).trim().replace(/^#/, "");
+  return /^\d+$/.test(t) ? Number(t) : null;
+}
+
+/**
+ * Normalise a `GET /api/changes/hotfix` body — the {@link HotfixReleasePlan} (an
+ * exception ready to confirm) or a refusal. Read defensively (crossed the wire as
+ * JSON). Pure — unit-tested.
+ * @param {any} data
+ */
+export function normalizeHotfixPlan(data) {
+  const o = data && typeof data === "object" ? data : {};
+  if (o.ok === true) {
+    return {
+      ok: true,
+      tenantId: typeof o.tenantId === "string" ? o.tenantId : null,
+      changeId: typeof o.changeId === "string" ? o.changeId : null,
+      prNumber: typeof o.prNumber === "number" ? o.prNumber : null,
+      bypassedPreviewSha: typeof o.bypassedPreviewSha === "string" ? o.bypassedPreviewSha : null,
+      bypassedPrs: Array.isArray(o.bypassedPrs) ? o.bypassedPrs : [],
+      rollbackTarget: o.rollbackTarget && typeof o.rollbackTarget === "object" ? o.rollbackTarget : null,
+      paywall:
+        o.paywall && typeof o.paywall === "object"
+          ? { allowed: o.paywall.allowed === true, message: typeof o.paywall.message === "string" ? o.paywall.message : null }
+          : { allowed: true, message: null },
+    };
+  }
+  return {
+    ok: false,
+    reason: typeof o.reason === "string" ? o.reason : "unknown",
+    message: typeof o.message === "string" ? o.message : "the hotfix plan was refused for an unknown reason",
+  };
+}
+
+/**
+ * Normalise a `POST /api/changes/hotfix` body — the {@link HotfixReleaseResult}.
+ * `state` is the ONLY honest terminal authority: render "shipped live" for
+ * `"shipped"` and nothing else. Pure — unit-tested.
+ * @param {any} data
+ */
+export function normalizeHotfixResult(data) {
+  const o = data && typeof data === "object" ? data : {};
+  const fwd = o.forwardIntegration && typeof o.forwardIntegration === "object" ? o.forwardIntegration : null;
+  return {
+    ok: o.ok === true,
+    state: typeof o.state === "string" ? o.state : "unknown",
+    reason: typeof o.reason === "string" ? o.reason : null,
+    message: typeof o.message === "string" ? o.message : "",
+    mainSha: typeof o.mainSha === "string" ? o.mainSha : null,
+    artifactDigest: typeof o.artifactDigest === "string" ? o.artifactDigest : null,
+    receiptId: typeof o.receiptId === "string" ? o.receiptId : null,
+    rollbackTarget: o.rollbackTarget && typeof o.rollbackTarget === "object" ? o.rollbackTarget : null,
+    forwardIntegration: fwd
+      ? {
+          ok: fwd.ok === true,
+          queueState: typeof fwd.queueState === "string" ? fwd.queueState : null,
+          runState: typeof fwd.runState === "string" ? fwd.runState : null,
+          reason: typeof fwd.reason === "string" ? fwd.reason : null,
+          aggregateSha: typeof fwd.aggregateSha === "string" ? fwd.aggregateSha : null,
+          statusMessage: typeof fwd.statusMessage === "string" ? fwd.statusMessage : null,
+        }
+      : null,
+  };
+}
+
+/** A clear next step per hotfix plan/release refusal reason. Pure. */
+export function hotfixNextStep(reason) {
+  switch (reason) {
+    case "no_candidate":
+      return "pass --pr <N> (or --change <id>) naming the reviewed hotfix candidate";
+    case "paywall":
+      return "upgrade the storefront subscription to enable go-live";
+    case "golive_unconfirmed":
+      return "re-run `tot hotfix` and confirm the plan";
+    case "digest_mismatch":
+      return "main moved under review — re-preview the hotfix against current main, then re-run `tot hotfix`";
+    default:
+      return "re-run `tot hotfix`";
+  }
+}
+
+/** Read a fetch Response body as JSON, tolerating a non-JSON/empty body. */
+async function readJsonSafe(res) {
+  try {
+    return await res.json();
+  } catch {
+    return {};
+  }
+}
+
+/**
+ * The hotfix flow: GET the plan, print it + confirm, POST to release, report the
+ * honest terminal state + the forward-integration outcome. `fetch`/`confirmPlan`/
+ * `openUrl`/`progress` are injected so it's unit-tested with no live network/TTY.
+ *
+ * @param {{ tenant:string, prNumber:number|null, changeId:string|null,
+ *   message:string|null, secret:string, storefrontUrl?:string|null,
+ *   yes?:boolean, noOpen?:boolean }} params
+ * @param {{ fetch?:typeof fetch, confirmPlan?:typeof printPlanAndConfirm,
+ *   openUrl?:(u:string)=>boolean, progress?:boolean }} [deps]
+ * @returns {Promise<number>} process exit code
+ */
+export async function runHotfix(
+  { tenant, prNumber, changeId, message = null, secret, storefrontUrl = null, yes = false, noOpen = 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}` : changeId ? changeId : "the hotfix candidate";
+
+  if (!secret) {
+    console.error(
+      fail(
+        "a hotfix is an OWNER action — it needs an operator secret",
+        "set PREVIEW_RECONCILE_SECRET (or GRANTS_ADMIN_SECRET / TOT_OPERATOR_SECRET), or pass --secret",
+      ),
+    );
+    return 2;
+  }
+
+  const authHeaders = {
+    authorization: `Bearer ${secret}`,
+    "x-tot-owner": tenant,
+    "x-tot-capability": "ship-on-behalf",
+  };
+
+  // 1. GET the read-only plan (candidate + bypassed preview work + rollback + paywall).
+  const query = prNumber != null ? `pr=${encodeURIComponent(prNumber)}` : `changeId=${encodeURIComponent(changeId || "")}`;
+  let planRes;
+  try {
+    planRes = await fetchImpl(`${base}/api/changes/hotfix?${query}`, { method: "GET", headers: authHeaders });
+  } catch (e) {
+    console.error(
+      fail(`couldn't reach the hotfix plan at ${base}: ${String(e?.message || e)}`, "check --url / your network, then re-run"),
+    );
+    return 1;
+  }
+  const planData = await readJsonSafe(planRes);
+  if (!planRes.ok && planData?.ok !== false) {
+    const msg = planData?.error || `HTTP ${planRes.status}`;
+    console.error(
+      fail(
+        `the hotfix plan was refused: ${msg}`,
+        planRes.status === 401 || planRes.status === 403
+          ? "check the operator secret and that it's authorised for this tenant"
+          : "check --tenant / --url / --pr, then re-run",
+      ),
+    );
+    return 1;
+  }
+  const plan = normalizeHotfixPlan(planData);
+  if (!plan.ok) {
+    console.error(fail(plan.message, hotfixNextStep(plan.reason)));
+    return 1;
+  }
+
+  // 2. Print the EXACT plan — including the unshipped preview work it BYPASSES —
+  //    then require ONE explicit confirm (default NO).
+  const liveUrl = liveUrlFor(tenant);
+  const planLines = planForAction({
+    action: "hotfix",
+    tenant,
+    pr: plan.prNumber,
+    changeId: plan.changeId,
+    bypassedPrs: plan.bypassedPrs,
+    bypassedPreviewSha: plan.bypassedPreviewSha,
+    rollbackTarget: plan.rollbackTarget,
+    paywall: plan.paywall,
+    targets: { live: liveUrl },
+  });
+  const { confirmed, reason } = await confirmPlan(planLines, {
+    yes,
+    question: `Release ${label} from main to live for ${tenant}, BYPASSING the unshipped preview work?`,
+  });
+  if (!confirmed) {
+    if (reason === "non-tty") {
+      console.error(
+        fail(
+          "`tot hotfix` needs an interactive terminal to confirm this live exception",
+          "run it from a terminal, or pass --yes to confirm non-interactively",
+        ),
+      );
+      return 2;
+    }
+    console.log("  Hotfix cancelled — nothing changed.");
+    return 0;
+  }
+
+  // 3. RELEASE — the human go-live gate (confirmGoLive).
+  const progress = deps.progress === false ? null : startProgress("releasing hotfix…");
+  let res;
+  try {
+    res = await fetchImpl(`${base}/api/changes/hotfix`, {
+      method: "POST",
+      headers: { "content-type": "application/json", ...authHeaders },
+      body: JSON.stringify({
+        confirmGoLive: true,
+        ...(prNumber != null ? { prNumber } : {}),
+        ...(plan.changeId ? { changeId: plan.changeId } : {}),
+        ...(message ? { message } : {}),
+      }),
+    });
+  } catch (e) {
+    progress?.stop();
+    console.error(
+      fail(`couldn't reach the hotfix endpoint at ${base}: ${String(e?.message || e)}`, "check --url / your network, then re-run"),
+    );
+    return 1;
+  }
+  const resultData = await readJsonSafe(res);
+  progress?.stop();
+
+  return reportHotfixResult(normalizeHotfixResult(resultData), { tenant, liveUrl, noOpen, openUrl: deps.openUrl });
+}
+
+/**
+ * Report the orchestrator's HONEST terminal state + the automatic forward-integration
+ * outcome. `shipped` is the ONLY state rendered as "shipped live"; a red
+ * forward-integration is surfaced as a fix-forward nudge but never un-ships live.
+ * @returns {number} process exit code
+ */
+export function reportHotfixResult(result, { tenant, liveUrl, noOpen, openUrl }) {
+  if (result.state === "shipped") {
+    console.log(`\n  ✓ shipped hotfix live for ${tenant} — the unshipped preview work was NOT included.`);
+    if (result.mainSha) console.log(`  main:    ${result.mainSha}`);
+    if (result.receiptId) console.log(`  receipt: ${result.receiptId}`);
+    if (liveUrl) {
+      console.log(`  Live: ${liveUrl}`);
+      if (!noOpen && openUrl && openUrl(liveUrl)) console.log("  (opened in your browser)");
+    }
+    // The automatic forward-integration: honest whether green or red.
+    const fwd = result.forwardIntegration;
+    if (fwd && fwd.ok) {
+      console.log(`  forward-integrated main → preview (green${fwd.aggregateSha ? `, ${fwd.aggregateSha}` : ""}).`);
+    } else if (fwd) {
+      console.log(
+        `  ⚠ forward-integration main → preview is ${fwd.queueState ?? "?"}/${fwd.runState ?? "—"}` +
+          `${fwd.reason ? `  (${fwd.reason})` : ""} — the live hotfix is fine, but preview needs a fix-forward.`,
+      );
+      if (fwd.statusMessage) console.log(`    why: ${fwd.statusMessage}`);
+      console.log("    → next: resolve preview against main, then `tot preview`.");
+    }
+    return 0;
+  }
+  if (result.state === "refused") {
+    console.error(fail(result.message || `hotfix refused (${result.reason})`, hotfixNextStep(result.reason)));
+    return 1;
+  }
+  if (
+    result.state === "merge_failed" ||
+    result.state === "build_failed" ||
+    result.state === "promote_failed" ||
+    result.state === "record_failed"
+  ) {
+    console.error(
+      fail(
+        result.message || `hotfix ${result.state.replace("_", " ")}`,
+        "re-run `tot hotfix` — the release is idempotent and safe to retry",
+      ),
+    );
+    return 1;
+  }
+  console.error(
+    fail(
+      `unexpected hotfix response (state: ${result.state})`,
+      "re-run `tot hotfix`; check the storefront logs if it persists",
+    ),
+  );
+  return 1;
+}
+
+/**
+ * @param {string[]} argv
+ * @param {any} ctx
+ */
+export async function run(argv, ctx) {
+  const env = process.env;
+  const args = parseHotfixArgs(argv);
+  if (args.help) {
+    console.log(USAGE);
+    return 0;
+  }
+
+  const tenant = (args.tenant || (ctx?.mode === "checkout" ? ctx.tenant : null) || ctx?.tenant || "").trim();
+  if (!tenant) {
+    console.error(
+      fail(
+        "`tot hotfix` needs a target tenant",
+        "pass --tenant <appDomain> (e.g. --tenant tokenoftrust.com), or run inside a store checkout.",
+      ),
+    );
+    return 2;
+  }
+
+  const prNumber = parsePrNumber(args.pr);
+  const changeId = (args.change || "").trim() || null;
+  if (prNumber == null && !changeId) {
+    console.error(
+      fail(
+        "`tot hotfix` needs the reviewed hotfix candidate",
+        "pass --pr <N> (a PR number) or --change <changeId>.",
+      ),
+    );
+    return 2;
+  }
+
+  const storefrontUrl = args.url || env.TOT_STOREFRONT_URL || env.STOREFRONT_BASE_URL || DEFAULT_STOREFRONT_URL;
+  return await runHotfix(
+    {
+      tenant,
+      prNumber,
+      changeId,
+      message: (args.message || "").trim() || null,
+      secret: resolveOperatorSecret(args.secret, env),
+      storefrontUrl,
+      yes: args.yes,
+      noOpen: args.noOpen,
+    },
+    { openUrl: (u) => openBrowser(u) },
+  );
+}

package/src/commands/pr.mjs

@@ -42,6 +42,24 @@ const DEFAULT_MCP_URL = "https://mcp.tokenoftrust.com";
 const DEFAULT_STOREFRONT_URL = "https://storefront.tokenoftrust.store";
 const SUBCOMMANDS = ["list", "view", "close"];
 
+/**
+ * The storefront-owned, shareable `/preview/<tenant>/pr/<N>` link — NEVER the
+ * forge/Gitea `url` (2026-08-18 incident: a raw forge PR URL reached an
+ * owner). `candidate_status` (the local-checkout MCP tool) has no
+ * `previewUrl` field at all, unlike the operator `GET /api/changes` path — so
+ * this constructs it the same way `runPrListOperator`'s caller resolves
+ * `storefrontUrl`, from the same env/--url override chain. Pure.
+ * @param {string} storefrontUrl
+ * @param {string} tenant
+ * @param {number|null|undefined} prNumber
+ * @returns {string|null}
+ */
+export function buildPreviewUrl(storefrontUrl, tenant, prNumber) {
+  if (typeof prNumber !== "number" || !tenant) return null;
+  const base = (storefrontUrl || DEFAULT_STOREFRONT_URL).trim().replace(/\/+$/, "");
+  return `${base}/preview/${tenant}/pr/${prNumber}`;
+}
+
 const USAGE = `tot pr — see and manage candidate PRs
 
   tot pr [list]              list your open candidate PRs for this store
@@ -118,9 +136,11 @@ export function matchCandidate(candidates, target) {
 /**
  * One-line candidate summary for `tot pr list` — surfaces branch ↔ PR# ↔ preview
  * URL so a dev sees, at a glance, which git branch each candidate belongs to (u4 —
- * branch-bound candidates) and where its preview lives. Prefers the candidate's
- * `previewUrl`, falling back to the PR `url`. `active` marks the one THIS checkout's
- * branch resolves to. Pure — unit-tested.
+ * branch-bound candidates) and where its preview lives. ONLY `previewUrl` (the
+ * storefront-owned `/preview/<tenant>/pr/<N>` link) — NEVER `url` (the forge/
+ * Gitea `html_url`), which must never reach a terminal (2026-08-18 incident:
+ * a raw forge PR URL reached an owner). `active` marks the one
+ * THIS checkout's branch resolves to. Pure — unit-tested.
  * @param {{prNumber?:number|null, branch?:string|null, changeId:string, state?:string|null,
  *   previewUrl?:string|null, url?:string|null}} c
  * @param {{ active?: boolean }} [opts]
@@ -128,8 +148,7 @@ export function matchCandidate(candidates, target) {
 export function formatCandidateLine(c, { active = false } = {}) {
   const pr = typeof c.prNumber === "number" ? `#${c.prNumber}` : "#—";
   const branch = c.branch ? c.branch : "(no branch)";
-  const previewUrl = c.previewUrl || c.url || null;
-  const urlPart = previewUrl ? `  ${previewUrl}` : "";
+  const urlPart = c.previewUrl ? `  ${c.previewUrl}` : "";
   const activePart = active ? "  ← active" : "";
   return `  PR ${pr}  ${branch}  ${c.changeId}  [${c.state ?? "?"}]${urlPart}${activePart}`;
 }
@@ -326,6 +345,7 @@ export async function run(argv, ctx) {
   }
 
   const baseUrl = args.mcp || env.MCP_BASE_URL || env.TOT_MCP_URL || DEFAULT_MCP_URL;
+  const storefrontUrl = args.url || env.TOT_STOREFRONT_URL || env.STOREFRONT_BASE_URL || DEFAULT_STOREFRONT_URL;
   const statePath = defaultCandidateStatePath(env);
   // Branch-bound (u4): the active-pointer namespace is scoped to the current git
   // branch, so the "← active" marker reflects THIS branch's candidate.
@@ -347,7 +367,8 @@ export async function run(argv, ctx) {
       const active = readActiveChangeId(statePath, scope);
       console.log(`Open candidate PRs for ${repo}:`);
       for (const c of candidates) {
-        console.log(formatCandidateLine(c, { active: !!active && c.changeId === active }));
+        const previewUrl = c.previewUrl ?? buildPreviewUrl(storefrontUrl, tenant, c.prNumber);
+        console.log(formatCandidateLine({ ...c, previewUrl }, { active: !!active && c.changeId === active }));
       }
       return 0;
     }
@@ -366,7 +387,9 @@ export async function run(argv, ctx) {
       if (match.headSha) console.log(`  head:             ${match.headSha}`);
       if (match.baseSha) console.log(`  base:             ${match.baseSha}`);
       console.log(`  mergeable (forge): ${match.mergeable ?? "?"}`);
-      if (match.url) console.log(`  ${match.url}`);
+      // ONLY the storefront-owned preview link -- never the raw forge/Gitea `url`.
+      const previewUrl = match.previewUrl ?? buildPreviewUrl(storefrontUrl, tenant, match.prNumber);
+      if (previewUrl) console.log(`  ${previewUrl}`);
       return 0;
     }