@tokenoftrust/cli 1.4.0-rc.10 → 1.4.0-rc.12

package/src/commands/ship.mjs

@@ -1,53 +1,1015 @@
 /**
- * `tot ship` — promote a reconciled PREVIEW live (the ship gate).
+ * `tot ship` — deploy main → preview + live (decisions operator-verb-and-hosting-model
+ * + ship-context-dependent-semantics). The deliberate ship gate.
  *
- * This is the second half of the dev → preview → ship loop:
+ * The second half of the dev → preview → ship loop:
  *
  *   tot dev        run your store locally with save→reload
  *   tot preview    push it to a reviewable preview (validate → reconcile → compliance)
- *   tot ship       promote a reconciled preview live                                     ← you are here
+ *   tot ship       accept + deploy (developer) / deploy (operator)                       ← you are here
  *
- * STATUS: STUB — the command is registered and named so the loop reads end-to-end,
- * but the real ship logic (resolve the current candidate/change for this checkout,
- * show the diff about to go live, confirm, then `change_accept` / `candidate_accept`
- * via the MCP, and report the shipped result) lands in a later unit.
+ * SHIP IS CONTEXT-DEPENDENT (decision ship-context-dependent-semantics). It NEVER
+ * silently guesses — it detects the context (`detectShipContext`), prints the EXACT
+ * plan for THAT context via the SHARED affordance (`../plan.mjs`, unit U10 — the same
+ * `planForAction` + `printPlanAndConfirm` every mutating operator verb and the `/admin`
+ * confirm dialog use), and confirms before acting:
  *
- * TODO(u3): implement the real ship flow. Symmetric with submit.mjs's preview flow —
- * it should reuse the same candidate handle (deriveChangeId / the active-candidate
- * state in candidate-state.mjs) so `tot ship` promotes the exact preview `tot preview`
- * last pushed, gate on a clean reconcile, and diff-confirm before accepting.
+ *   • DEVELOPER — run in your OWN store checkout on a branch: ship = ACCEPT (merge this
+ *     branch/PR into main) AND THEN DEPLOY (main → preview + live). This is `runShip`.
+ *   • OPERATOR — target a `--pr N --tenant t` that ISN'T your checkout: ship = DEPLOY
+ *     only; the merge is the separate `tot accept` verb. This is `runShipOperator`.
  *
- * Until then this prints a clear "not yet wired" message pointing at the reviewer
- * path that ships a change today, and exits non-zero so nothing mistakes it for a
- * completed ship. Additive + non-breaking: it performs no action.
+ * The DEVELOPER contract, deliberately strict because this changes the LIVE site:
  *
- * Dependency-free.
+ *   1. Resolve the ACTIVE candidate for this checkout (the SAME handle `tot preview`
+ *      last pushed to — see `resolveActiveChangeId`, the seam u4 rekeys to be
+ *      branch-bound) and REQUIRE it to be OPEN and RECONCILED. A merged/closed
+ *      candidate, or one whose evidence isn't green yet, is refused with a clear
+ *      next step — never shipped.
+ *   2. ALWAYS render a diff-vs-live (what this ship changes on the live site), then
+ *      print the EXACT plan and require ONE explicit confirm, defaulting to NO. `--yes`
+ *      confirms non-interactively (the operator's explicit go); a NON-TTY WITHOUT
+ *      `--yes` REFUSES rather than auto-confirm — nothing ships without an explicit yes.
+ *      Merge-to-main / go-live / deploy stay HUMAN GATES.
+ *   3. On confirm, `change_accept` (the human ship gate) transitions the change to
+ *      shipped; we then poll `change_status` until it reports shipped and print the
+ *      live URL.
+ *
+ * UNAUTHORISED actors don't hit a wall: if you can't approve the ship yourself we
+ * RECORD the approval request (`change_ready` queues it for review) and print WHO
+ * can approve it, so the change moves forward instead of dead-ending.
+ *
+ * WIRE (verified server-side by u7, decision ship-path-wire-resolutions):
+ *   - A CANDIDATE and a change RECORD are DISTINCT namespaces. The candidate handle
+ *     (`changeId`, the `candidate/<changeId>` Gitea PR) is NOT the change-record id.
+ *     `change_request_review` / `change_ready` / `change_accept` resolve the record
+ *     via `getChange(tenant, id)`, where `id` is the `chg_<uuid>` minted by
+ *     `change_open` — a different id entirely.
+ *   - So ship RESOLVES a real change-record id before the gate: `resolveChangeRecordId`
+ *     opens a record for the exact reviewed commit (`change_open commit:<HEAD>`, so
+ *     u7's promote-by-digest can content-address the reviewed tree — without `commit:`
+ *     the accept fails closed `no_reviewed_commit`) and readies it against the
+ *     authoritative reconcile evidence keyed by (tenant, commit). If that commit hasn't
+ *     reconciled (no evidence), `change_ready` fails and we refuse with a clear next step.
+ *   - `change_request_review` then reads the readied record (evidence green? authorised
+ *     to promote?); `change_accept` is the commit. All key on the resolved `chg_` id.
+ *
+ * Dependency-free (global fetch via the MCP client + `git`); pure helpers are
+ * exported and unit-tested with a mock client, no network, no TTY.
  */
+import { execFileSync } from "node:child_process";
+import { createMcpClient } from "../mcp.mjs";
+import { establishSession, AuthUnavailableError } from "../auth.mjs";
 import { fail } from "../errors.mjs";
+import { planForAction, printPlanAndConfirm } from "../plan.mjs";
+import { startProgress } from "../progress.mjs";
+import { openBrowser } from "../open.mjs";
+import {
+  repoNameFromRemote,
+  parseNameStatus,
+  deriveChangeId,
+  actorKeyFor,
+  currentBranch,
+  buildChangeSummary,
+} from "./submit.mjs";
+import {
+  defaultCandidateStatePath,
+  readActiveChangeId,
+  isTerminalCandidateState,
+} from "../candidate-state.mjs";
+
+const DEFAULT_MCP_URL = "https://mcp.tokenoftrust.com";
+const DEFAULT_STOREFRONT_URL = "https://storefront.tokenoftrust.store";
+
+const USAGE = `tot ship — deploy main → preview + live (context-dependent)
+
+  tot ship                          ship the preview you last pushed with \`tot preview\`
+  tot ship <N>                      DEVELOPER: ship PR #N from your OWN checkout
+  tot ship pr/<N>                   (same — also accepts \`pr#N\`, \`#N\`)
+  tot ship --pr <N> --tenant <t>    OPERATOR: deploy a PR that isn't your checkout
+  tot ship --change-id <chg_…>      target an explicit change record (operator targeting)
+  tot ship --yes                    confirm non-interactively (skip the [y/N] prompt)
+  tot ship --identity <id>          sign in as a specific identity for this ship
+  tot ship --mcp <url>              MCP base URL (default: env MCP_BASE_URL / TOT_MCP_URL)
 
-const USAGE = `tot ship — promote a reconciled preview live
+  \`tot ship\` is CONTEXT-DEPENDENT (decision ship-context-dependent-semantics):
 
-  tot ship        (coming soon) promote the preview you last pushed with \`tot preview\`
+    • DEVELOPER — run in your OWN store checkout on a branch: ship = ACCEPT (merge
+      this branch/PR into main) AND THEN DEPLOY (main → preview + live). A POSITIONAL
+      \`tot ship 4\` / \`tot ship pr/4\` names the PR to ship — same developer semantics,
+      the tenant is inferred from the checkout.
+    • OPERATOR — target a \`--pr N --tenant t\` that ISN'T your checkout: ship = DEPLOY
+      only (the merge is the separate \`tot accept\` verb).
 
-  Ship the preview live once it has reconciled cleanly. This is the deliberate
-  step AFTER \`tot preview\` — preview makes it reviewable; ship makes it live.`;
+  It NEVER silently guesses: it prints the EXACT plan for THAT context and confirms
+  first (\`--yes\` to confirm non-interactively; a non-TTY without \`--yes\` refuses).
+  Merge-to-main / go-live / deploy stay HUMAN GATES. If you can't approve the ship
+  yourself, it records the request and tells you who can.`;
 
 /**
- * @param {string[]} argv
- * @param {any} _ctx
+ * Parse a POSITIONAL PR token — `4`, `pr/4`, `pr#4`, `pr-4`, `#4`, `PR/4` — to the
+ * PR number as a string, or null when the token isn't a PR reference. Pure. Used so
+ * `tot ship 4` / `tot ship pr/4` name a PR positionally, the same value the `--pr`
+ * flag carries (but developer-context — see `detectShipContext`).
+ * @param {string} token
+ * @returns {string|null}
  */
-export async function run(argv, _ctx) {
-  if (argv.includes("--help") || argv.includes("-h")) {
-    console.log(USAGE);
+export function parsePrToken(token) {
+  if (typeof token !== "string") return null;
+  const m = token.trim().match(/^(?:pr)?[/#-]?(\d+)$/i);
+  return m ? m[1] : null;
+}
+
+/** Parse `tot ship` argv. Pure. */
+export function parseShipArgs(argv) {
+  const a = {
+    mcp: null,
+    identity: null,
+    noOpen: false,
+    yes: false,
+    pr: null,
+    // True when `pr` came from a POSITIONAL token (`tot ship 4`) rather than the
+    // `--pr` flag. A positional PR in your OWN checkout is DEVELOPER intent (ship my
+    // own PR — accept+deploy); the `--pr` flag stays OPERATOR targeting (deploy-only).
+    prPositional: false,
+    tenant: null,
+    changeId: null,
+    headSha: null,
+    url: null,
+    help: false,
+  };
+  for (let i = 0; i < argv.length; i++) {
+    const t = argv[i];
+    if (t === "--mcp") a.mcp = argv[++i];
+    else if (t === "--identity") a.identity = argv[++i];
+    else if (t === "--no-open") a.noOpen = true;
+    else if (t === "--yes" || t === "-y") a.yes = true;
+    else if (t === "--pr") a.pr = argv[++i];
+    else if (t === "--tenant") a.tenant = argv[++i];
+    else if (t === "--change-id") a.changeId = argv[++i];
+    else if (t === "--head-sha" || t === "--head") a.headSha = argv[++i];
+    else if (t === "--url") a.url = argv[++i];
+    else if (t === "--help" || t === "-h") a.help = true;
+    else if (!t.startsWith("-") && a.pr == null) {
+      // A POSITIONAL PR reference (`tot ship 4` / `tot ship pr/4` / `tot ship #4`).
+      // Only the first one wins; an explicit `--pr` flag (set above) takes precedence.
+      const n = parsePrToken(t);
+      if (n != null) {
+        a.pr = n;
+        a.prPositional = true;
+      }
+    }
+  }
+  return a;
+}
+
+/**
+ * Decide ship's CONTEXT (decision ship-context-dependent-semantics). Pure — no I/O.
+ *
+ *  - "developer": run inside your OWN store checkout with no cross-target flags →
+ *    ship = ACCEPT (merge this branch/PR into main) AND THEN DEPLOY (main → preview
+ *    + live). This is the happy-path `tot ship` with no flags.
+ *  - "operator": you're targeting a specific `--pr`/`--tenant` that ISN'T your active
+ *    checkout → ship = DEPLOY only (the merge is the separate `tot accept` verb).
+ *
+ * Ship NEVER silently guesses which it is — this classifies from the EXPLICIT signals
+ * (an explicit `--pr`, a `--tenant` that differs from the checkout, or a `--tenant`
+ * named from outside any checkout), and the caller then prints the concrete plan for
+ * THAT context and confirms.
+ *
+ * A POSITIONAL PR (`tot ship 4`) is the exception the `--pr` FLAG is not: it names the
+ * developer's OWN PR to ship from their OWN checkout, so — absent any cross-target
+ * signal (a differing `--tenant`, or being named from outside a checkout) — it stays
+ * DEVELOPER (accept+deploy). The `--pr` flag remains OPERATOR targeting (deploy-only),
+ * per its documented "a PR that isn't your checkout" contract.
+ *
+ * @param {{ pr?: number|string|null, prPositional?: boolean, tenant?: string|null,
+ *   ctxTenant?: string|null, ctxMode?: string|null }} p
+ * @returns {"developer"|"operator"}
+ */
+export function detectShipContext({ pr = null, prPositional = false, tenant = null, ctxTenant = null, ctxMode = null } = {}) {
+  const hasPr = pr != null && `${pr}`.trim() !== "";
+  const t = (tenant || "").trim();
+  const ct = (ctxTenant || "").trim();
+  const tenantDiffers = Boolean(t && ct && t !== ct);
+  const targetingFromOutside = Boolean(t && ctxMode !== "checkout");
+  // A positional `tot ship 4` inside your OWN checkout, with no cross-target flags, is
+  // the developer shipping their own PR — accept+deploy, NOT operator deploy-only.
+  const positionalOwnPr = hasPr && prPositional && ctxMode === "checkout" && !tenantDiffers && !targetingFromOutside;
+  if (positionalOwnPr) return "developer";
+  if (hasPr || tenantDiffers || targetingFromOutside) return "operator";
+  return "developer";
+}
+
+// ─── Response normalisation (defensive — one MCP, but shapes may vary) ───────────
+
+/**
+ * Normalise a `candidate_status` result (a single ReviewEnvironment forge slice)
+ * to the fields ship gates on. Returns null when there's no candidate to act on.
+ * Pure — unit-tested.
+ * @param {any} r
+ * @returns {{changeId?:string, state:string|null, headSha:string|null, baseSha:string|null,
+ *   prNumber:number|null, url:string|null, mergeable:unknown}|null}
+ */
+export function normalizeCandidate(r) {
+  // `tot pr` already learned candidate_status can answer as an object, a
+  // `{candidates:[…]}` list, or a single record — reuse that tolerance here.
+  const c = Array.isArray(r)
+    ? r[0]
+    : r && Array.isArray(r.candidates)
+      ? r.candidates[0]
+      : r && Array.isArray(r.environments)
+        ? r.environments[0]
+        : r;
+  if (!c || typeof c !== "object" || typeof c.changeId !== "string") return null;
+  return {
+    changeId: c.changeId,
+    state: typeof c.state === "string" ? c.state : null,
+    headSha: c.headSha ?? null,
+    baseSha: c.baseSha ?? null,
+    prNumber: typeof c.prNumber === "number" ? c.prNumber : null,
+    url: c.url ?? null,
+    mergeable: c.mergeable,
+  };
+}
+
+/**
+ * Normalise a `change_request_review` result to the precondition signals ship
+ * needs: is the evidence green (reconciled + promotable), is THIS session allowed
+ * to promote, and — for the unauthorised path — who can. Field names are read
+ * defensively (the CLI is the first caller of this tool) so a plausible rename
+ * degrades gracefully rather than crashing the gate. `reconciled`/`authorized` are
+ * TRI-STATE-ish: they're only `true` when the server clearly says so, so an
+ * unrecognised shape fails CLOSED (we don't ship on ambiguity). Pure — unit-tested.
+ * @param {any} r
+ * @returns {{reconciled:boolean, authorized:boolean, approvers:string[],
+ *   previewUrl:string|null, detail:string|null, raw:any}}
+ */
+export function normalizeReview(r) {
+  const o = (r && typeof r === "object" ? r : {});
+  const ev = o.evidence && typeof o.evidence === "object" ? o.evidence : {};
+  // Evidence green ⇒ reconciled + promotable. Accept the several plausible flags.
+  const reconciled = firstBool([
+    o.evidenceGreen, o.green, o.promotable, ev.green, ev.ok, ev.promotable,
+    o.verdict === "green" || o.verdict === "pass" ? true : undefined,
+  ]);
+  const authorized = firstBool([
+    o.authorized, o.authorised, o.canPromote, o.canApprove, o.authorisedToPromote,
+  ]);
+  const approvers = normalizeApprovers(
+    o.approvers ?? o.eligibleApprovers ?? o.whoCanApprove ?? o.promoters ?? [],
+  );
+  return {
+    reconciled: reconciled === true,
+    authorized: authorized === true,
+    approvers,
+    previewUrl: o.previewUrl ?? ev.previewUrl ?? null,
+    detail: typeof o.detail === "string" ? o.detail : (typeof o.reason === "string" ? o.reason : null),
+    raw: r,
+  };
+}
+
+/** First non-undefined boolean in a list, else undefined. Pure. */
+function firstBool(candidates) {
+  for (const v of candidates) if (typeof v === "boolean") return v;
+  return undefined;
+}
+
+/** Coerce an approvers payload (strings, or objects with email/name) to a label list. Pure. */
+export function normalizeApprovers(list) {
+  if (!Array.isArray(list)) return [];
+  return list
+    .map((a) => (typeof a === "string" ? a : a && (a.email || a.name || a.label || a.id)))
+    .filter((s) => typeof s === "string" && s.trim())
+    .map((s) => s.trim());
+}
+
+/**
+ * Normalise a `change_accept` / `change_status` result to { shipped, state,
+ * previewUrl, shippedAt }. `shipped` is true once the record reports the shipped
+ * state (or carries a shipped stamp). Pure — unit-tested.
+ * @param {any} r
+ */
+export function normalizeChangeResult(r) {
+  const o = (r && typeof r === "object" ? r : {});
+  const state = typeof o.state === "string" ? o.state : null;
+  const shippedStamp = o.shipped && typeof o.shipped === "object" ? o.shipped : null;
+  const shipped = state === "shipped" || Boolean(o.shipped === true || shippedStamp);
+  return {
+    shipped,
+    state,
+    previewUrl: o.previewUrl ?? shippedStamp?.previewUrl ?? o.liveUrl ?? null,
+    shippedAt: shippedStamp?.shippedAt ?? o.shippedAt ?? null,
+    raw: r,
+  };
+}
+
+// ─── The candidate-resolution seam (u4 extends THIS) ─────────────────────────────
+
+/**
+ * Resolve the ACTIVE candidate's changeId for this checkout — the SAME resolution
+ * `tot preview` uses so ship promotes exactly what preview last pushed: the
+ * remembered active pointer (a prior `--new` / roll), else the STABLE
+ * per-developer-per-tenant default (`deriveChangeId`).
+ *
+ * ┌─ SEAM (u4) ────────────────────────────────────────────────────────────────┐
+ * │ This is the ONE place ship keys the candidate on (tenant, actor, branch).    │
+ * │ u4 (branch-bound candidates) keys HERE — folding in the current git branch — │
+ * │ so `tot preview` and `tot ship` resolve the SAME branch-bound candidate,     │
+ * │ WITHOUT touching the gate, diff, confirm, or accept flow below. On the       │
+ * │ default branch `branch` is null and this is byte-identical to pre-u4.         │
+ * └──────────────────────────────────────────────────────────────────────────────┘
+ * Pure given its inputs (state is read through candidate-state.mjs). Exported so a
+ * follow-on unit can wrap/replace it.
+ * @param {{ statePath:string, mcpUrl:string, repo:string, tenant:string, actorKey:string,
+ *   branch?:string|null }} keys
+ * @returns {string}
+ */
+export function resolveActiveChangeId({ statePath, mcpUrl, repo, tenant, actorKey, branch = null }) {
+  const stable = deriveChangeId(tenant, actorKey, branch);
+  const active = readActiveChangeId(statePath, { mcpUrl, repo, branch });
+  return active || stable;
+}
+
+/**
+ * Normalise a `change_open` result to its minted change-record id. `change_open`
+ * returns the record id flat in `data` (id, state); read it defensively. Pure.
+ * @param {any} r
+ * @returns {{ id: string|null, state: string|null }}
+ */
+export function normalizeOpenedChange(r) {
+  const o = r && typeof r === "object" ? r : {};
+  return {
+    id: typeof o.id === "string" && o.id ? o.id : null,
+    state: typeof o.state === "string" ? o.state : null,
+  };
+}
+
+/**
+ * Resolve the change-RECORD id (`chg_<uuid>`) that the ship gate + `change_accept`
+ * key on — a DISTINCT namespace from the candidate handle (see the module header).
+ * There is NO candidate→record lookup on the wire (`change_status` lists only
+ * id/title/state, never the head sha), so we CAPTURE the id at `change_open`, the
+ * option u7's decision (ship-path-wire-resolutions) records as supported:
+ *
+ *   1. read the reviewed commit — the local HEAD, the commit `tot preview` pushed and
+ *      the reconcile evidence is keyed on;
+ *   2. `change_open` it with `commit:` set, so u7's promote-by-digest can content-
+ *      address the exact reviewed tree (absent it, `change_accept` fails closed
+ *      `no_reviewed_commit`);
+ *   3. `change_ready` it, attaching the AUTHORITATIVE reconcile evidence keyed by
+ *      (tenant, commit). This REQUIRES that commit to have reconciled — if it hasn't,
+ *      `change_ready` throws (no authoritative evidence) and we propagate it so the
+ *      caller refuses with a "run `tot preview` first" next step (never ship a commit
+ *      whose evidence isn't in).
+ *
+ * Returns the resolved `chg_` id. Throws if the record can't be opened/readied — the
+ * caller fails CLOSED (never falls back to shipping the candidate handle or no record).
+ * The `change_*` calls go through the same client; `git` is injected.
+ * @param {{callTool:Function}} client
+ * @param {{ tenant:string, git:(args:string[])=>string,
+ *   changeSummary?:{ title?:string, body?:string[] } }} params
+ * @returns {Promise<string>}
+ */
+export async function resolveChangeRecordId(client, { tenant, git, changeSummary }) {
+  const commit = git(["rev-parse", "HEAD"]).trim();
+  if (!commit) {
+    throw new Error("couldn't read the reviewed commit (git HEAD) for this checkout");
+  }
+  const title = (changeSummary?.title || `Ship ${tenant} store change`).slice(0, 200);
+  const body = changeSummary?.body?.length ? changeSummary.body.join("\n").slice(0, 2000) : undefined;
+  const opened = normalizeOpenedChange(
+    await client.callTool("change_open", {
+      title,
+      ...(body ? { summary: body } : {}),
+      commit,
+      tenant,
+      dryRun: false,
+    }),
+  );
+  if (!opened.id) {
+    throw new Error("change_open did not return a change-record id");
+  }
+  // Ready it against the authoritative reconcile evidence for THIS exact commit —
+  // throws (no_authoritative_evidence) if the commit hasn't reconciled yet.
+  await client.callTool("change_ready", { id: opened.id, tenant, dryRun: false });
+  return opened.id;
+}
+
+/** A neutral review used only when there's no open candidate to resolve a record for
+ *  — shipReadiness reports the candidate blocker first and never reads these. */
+export const NO_REVIEW = Object.freeze({
+  reconciled: false, authorized: false, approvers: [], previewUrl: null, detail: null, raw: null,
+});
+
+// ─── The ship gate (pure) ────────────────────────────────────────────────────────
+
+/**
+ * Decide, from the resolved candidate + the review verdict, whether the ship may
+ * proceed — the correctness-critical core, kept PURE so every branch is unit-tested
+ * without a client/TTY/git. Order matters: OPEN, then RECONCILED, then AUTHORISED,
+ * so the developer always sees the most fundamental blocker first.
+ *
+ * @param {ReturnType<typeof normalizeCandidate>} candidate
+ * @param {ReturnType<typeof normalizeReview>} review
+ * @returns {{ kind: "no-candidate"|"not-open"|"not-reconciled"|"unauthorized"|"ready",
+ *   what?: string, next?: string }}
+ */
+export function shipReadiness(candidate, review) {
+  if (!candidate) {
+    return {
+      kind: "no-candidate",
+      what: "no active candidate to ship for this checkout",
+      next: "push one first with `tot preview`, then `tot ship`",
+    };
+  }
+  if (candidate.state !== "open") {
+    // Terminal (merged/closed) vs simply-not-open both mean "nothing OPEN to ship".
+    const terminal = isTerminalCandidateState(candidate.state);
+    return {
+      kind: "not-open",
+      what: terminal
+        ? `this candidate is already ${candidate.state} — there's nothing open to ship`
+        : `this candidate isn't open (state: ${candidate.state ?? "unknown"})`,
+      next: "`tot preview` to push a fresh candidate, then `tot ship`",
+    };
+  }
+  if (!review.reconciled) {
+    return {
+      kind: "not-reconciled",
+      what: `this preview hasn't reconciled cleanly yet${review.detail ? ` — ${review.detail}` : ""}`,
+      next: "run `tot preview` and wait for the green reconcile/compliance result, then `tot ship`",
+    };
+  }
+  if (!review.authorized) {
+    return { kind: "unauthorized" };
+  }
+  return { kind: "ready" };
+}
+
+// ─── Diff-vs-live (pure render + thin git compute) ───────────────────────────────
+
+/**
+ * Render the "what goes live" block from parsed name-status entries + a shortstat
+ * line. Always prints SOMETHING actionable: the changed paths when we have them,
+ * else a pointer to the candidate PR so the reviewer can read the full diff. Pure —
+ * unit-tested.
+ * @param {{ entries:{status:string,path:string,from?:string}[], statLine?:string,
+ *   prUrl?:string|null, ok:boolean }} input
+ * @returns {string[]}
+ */
+export function renderDiffVsLive({ entries, statLine, prUrl, ok }) {
+  const lines = ["", "  This ship will change the LIVE site:"];
+  if (ok && entries.length) {
+    for (const e of entries.slice(0, 40)) {
+      const label = e.status === "R" && e.from ? `${e.from} → ${e.path}` : e.path;
+      lines.push(`    ${statusGlyph(e.status)} ${label}`);
+    }
+    if (entries.length > 40) lines.push(`    … +${entries.length - 40} more file(s)`);
+    if (statLine) lines.push(`    (${statLine})`);
+  } else {
+    lines.push("    (couldn't render a local file diff for this candidate)");
+    if (prUrl) lines.push(`    review the full diff in the candidate PR: ${prUrl}`);
+  }
+  return lines;
+}
+
+/** A/M/D/R → a stable one-char glyph for the diff list. Pure. */
+function statusGlyph(status) {
+  return { A: "+", M: "~", D: "-", R: "»", C: "»" }[status] || "·";
+}
+
+/**
+ * Compute the diff-vs-live (base→head) via git in the checkout — best-effort. Tries
+ * the local objects first; if the shas aren't present it fetches once and retries;
+ * if it still can't, returns `ok:false` so the caller falls back to the PR pointer.
+ * `git` is injected (a `(args:string[])=>string` runner) so it's testable.
+ * @param {(args:string[]) => string} git
+ * @param {string|null} baseSha
+ * @param {string|null} headSha
+ * @returns {{ entries:{status:string,path:string,from?:string}[], statLine:string, ok:boolean }}
+ */
+export function computeDiffVsLive(git, baseSha, headSha) {
+  if (!baseSha || !headSha) return { entries: [], statLine: "", ok: false };
+  const range = `${baseSha}..${headSha}`;
+  const tryDiff = () => ({
+    entries: parseNameStatus(git(["diff", "--name-status", range])),
+    statLine: git(["diff", "--shortstat", range]).trim(),
+  });
+  try {
+    return { ...tryDiff(), ok: true };
+  } catch {
+    // The shas may not be local yet (base moved, head only on the remote) — one
+    // fetch, then retry. Still failing ⇒ fall back to the PR pointer.
+    try {
+      git(["fetch", "--quiet", "origin"]);
+      return { ...tryDiff(), ok: true };
+    } catch {
+      return { entries: [], statLine: "", ok: false };
+    }
+  }
+}
+
+// ─── Ship-decision poll ──────────────────────────────────────────────────────────
+
+/**
+ * Poll `change_status` until the change reports shipped (or the attempts budget
+ * runs out). `change_accept` transitions synchronously, so this usually resolves on
+ * the first read — it exists to CONFIRM the shipped state and pick up the live URL,
+ * and to tolerate a promote that lands a beat later. Injectable delay/attempts.
+ * @param {{callTool:Function}} client
+ * @param {{ id:string, tenant?:string }} target
+ * @param {{ attempts?:number, delayMs?:number, sleep?:(ms:number)=>Promise<void> }} [opts]
+ */
+export async function pollChangeShipped(client, { id, tenant }, { attempts = 6, delayMs = 1500, sleep } = {}) {
+  const wait = sleep || ((ms) => new Promise((r) => setTimeout(r, ms)));
+  let last = null;
+  for (let i = 0; i < attempts; i++) {
+    last = normalizeChangeResult(await client.callTool("change_status", { id, ...(tenant ? { tenant } : {}) }));
+    if (last.shipped) return last;
+    if (i < attempts - 1) await wait(delayMs);
+  }
+  return last;
+}
+
+// ─── Orchestration ───────────────────────────────────────────────────────────────
+
+/**
+ * The ship flow after a session is established — resolve the candidate, gate,
+ * diff-vs-live, confirm, accept, poll, report. Split out from `run` so it's driven
+ * in tests with a mock client + injected git/confirm/interactive, no network/TTY.
+ *
+ * @param {{callTool:Function}} client  an MCP client (real or mock)
+ * @param {{ tenant:string, changeId:string, repo:string,
+ *   git:(args:string[])=>string, noOpen?:boolean, yes?:boolean, storefrontUrl?:string|null,
+ *   changeSummary?:{ title?:string, body?:string[] }, expectedPr?:number|string|null }} params
+ * @param {{ confirmPlan?:typeof printPlanAndConfirm,
+ *   poll?:typeof pollChangeShipped, openUrl?:(u:string)=>boolean, progress?:boolean,
+ *   resolveRecord?:typeof resolveChangeRecordId }} [deps]
+ * @returns {Promise<number>} process exit code
+ */
+export async function runShip(client, { tenant, changeId, repo, git, noOpen, yes = false, storefrontUrl = null, changeSummary, expectedPr = null }, deps = {}) {
+  const confirmPlan = deps.confirmPlan || printPlanAndConfirm;
+  const poll = deps.poll || pollChangeShipped;
+  const resolveRecord = deps.resolveRecord || resolveChangeRecordId;
+
+  // 1. Resolve the active candidate (the forge slice — open-gate + diff-vs-live).
+  const candidate = normalizeCandidate(await client.callTool("candidate_status", { repo, changeId }));
+
+  // 1a. If the developer named a PR positionally (`tot ship 4`), that number is a
+  //     SAFETY assertion of WHICH PR ships — refuse (before opening any change record)
+  //     if the checkout's resolved branch-bound candidate is a DIFFERENT PR, so
+  //     `tot ship 4` can never silently ship PR #7. Only guards when both are known.
+  const want = expectedPr != null && `${expectedPr}`.trim() ? Number(expectedPr) : null;
+  if (want != null && candidate && candidate.prNumber != null && Number(candidate.prNumber) !== want) {
+    console.error(
+      fail(
+        `you asked to ship PR #${want}, but this checkout's active candidate is PR #${candidate.prNumber}`,
+        `switch to the branch whose PR is #${want} (or run \`tot ship\` with no number to ship this checkout's candidate)`,
+      ),
+    );
+    return 1;
+  }
+
+  // 1b. Resolve the change-RECORD id (`chg_<uuid>`) that the gate + change_accept key
+  //     on — a DISTINCT namespace from the candidate handle (see the header). Only
+  //     meaningful for an OPEN candidate; for a missing/closed one we skip it and let
+  //     shipReadiness report that blocker first (never open a record we can't ship).
+  let id = null;
+  if (candidate && candidate.state === "open") {
+    try {
+      id = await resolveRecord(client, { tenant, git, changeSummary });
+    } catch (e) {
+      console.error(
+        fail(
+          `couldn't prepare a shipable change record: ${String(e?.message || e)}`,
+          "the commit you're shipping may not have reconciled — run `tot preview` and wait for the green result, then `tot ship`",
+        ),
+      );
+      return 1;
+    }
+  }
+
+  // 2. Read the ship-readiness verdict against the RESOLVED record (or the neutral
+  //    review when there's no open candidate — shipReadiness reports the candidate).
+  const review = id
+    ? normalizeReview(await client.callTool("change_request_review", { id, tenant }))
+    : NO_REVIEW;
+  const gate = shipReadiness(candidate, review);
+
+  if (gate.kind === "unauthorized") {
+    return await handleUnauthorized(client, { id, tenant, approvers: review.approvers });
+  }
+  if (gate.kind !== "ready") {
+    console.error(fail(gate.what, gate.next));
+    return 1;
+  }
+
+  // 2. ALWAYS render the diff-vs-live, then print the EXACT plan and gate on ONE
+  //    explicit confirm via the SHARED affordance (plan.mjs). DEVELOPER context =
+  //    accept-then-deploy (merge this PR into main, THEN deploy main → preview + live).
+  const diff = computeDiffVsLive(git, candidate.baseSha, candidate.headSha);
+  for (const line of renderDiffVsLive({ ...diff, prUrl: candidate.url })) console.log(line);
+
+  const previewUrl = review.previewUrl || candidate.url || previewUrlFor(storefrontUrl, tenant, candidate.prNumber);
+  const planLines = planForAction({
+    action: "ship",
+    context: "developer",
+    tenant,
+    pr: candidate.prNumber,
+    changeId: id,
+    headSha: candidate.headSha,
+    targets: { preview: previewUrl, live: liveUrlFor(tenant) },
+  });
+  // `--yes` confirms non-interactively; a non-TTY WITHOUT `--yes` refuses (never
+  // auto-confirm a live change). Default answer is NO on an interactive prompt.
+  const { confirmed, reason } = await confirmPlan(planLines, {
+    yes,
+    question: `Ship this live to ${tenant}?`,
+  });
+  if (!confirmed) {
+    if (reason === "non-tty") {
+      console.error(
+        fail(
+          "`tot ship` needs an interactive terminal to confirm the live change",
+          "run it from a terminal, or pass --yes to confirm non-interactively",
+        ),
+      );
+      return 2;
+    }
+    console.log("  Ship cancelled — nothing changed.");
     return 0;
   }
 
+  // 3. Accept (the ship gate), then poll change_status until shipped.
+  let accept;
+  try {
+    accept = normalizeChangeResult(
+      await client.callTool("change_accept", {
+        id,
+        tenant,
+        dryRun: false,
+        // Stable per (candidate, head): a re-run after a blip returns the original
+        // ship instead of double-accepting.
+        idempotencyKey: `ship-${id}-${candidate.headSha ?? "head"}`,
+      }),
+    );
+  } catch (e) {
+    console.error(
+      fail(
+        `the ship gate refused to accept this change: ${String(e?.message || e)}`,
+        "check the reconcile/compliance result with `tot preview`, then re-run `tot ship`",
+      ),
+    );
+    return 1;
+  }
+
+  const progress = deps.progress === false ? null : startProgress("shipping…");
+  let status;
+  try {
+    status = await poll(client, { id, tenant });
+  } finally {
+    progress?.stop();
+  }
+  return reportShipped(accept, status, { tenant, noOpen, openUrl: deps.openUrl });
+}
+
+/**
+ * The unauthorised path — don't just error out. The change record was already opened
+ * and moved to ready_for_review while resolving the ship (`resolveChangeRecordId`), so
+ * the review request IS recorded; we just tell the developer that and print WHO can
+ * approve. (There is no separate `change_ready` to run — re-readying a ready record is
+ * an illegal transition; the record already sits in the reviewers' queue.)
+ * @returns {Promise<number>} exit code (non-zero — the ship didn't happen)
+ */
+async function handleUnauthorized(client, { id, tenant, approvers }) {
+  void client;
+  void id;
   console.error(
     fail(
-      "`tot ship` isn't wired up yet",
-      "push your work for review with `tot preview`; a reviewer accepts it to ship it live " +
-        "(change_accept / `tot pr`). Self-serve `tot ship` is coming soon.",
+      "you're not authorised to ship this change live yourself",
+      "the change is recorded and ready for review — an authorised approver can ship it",
     ),
   );
-  return 2;
+  if (approvers.length) {
+    console.error(`  Who can approve: ${approvers.join(", ")}`);
+  } else {
+    console.error(`  Who can approve: a teammate with ship/promote authority for ${tenant}.`);
+  }
+  return 1;
+}
+
+/** Report the shipped result and open the live URL (unless suppressed). */
+function reportShipped(accept, status, { tenant, noOpen, openUrl }) {
+  const url = status?.previewUrl || accept?.previewUrl || null;
+  if (status?.shipped || accept?.shipped) {
+    console.log(`\n  ✓ shipped ${tenant} live.`);
+    if (url) {
+      console.log(`  Live: ${url}`);
+      if (!noOpen && openUrl && openUrl(url)) console.log("  (opened in your browser)");
+    }
+    return 0;
+  }
+  // Accept committed but the shipped state hasn't been observed yet (a promote may
+  // still be landing) — report honestly rather than claim a live URL.
+  console.log(`\n  ~ ship accepted for ${tenant}; it's going live now.`);
+  if (url) console.log(`  Track it here: ${url}`);
+  return 0;
+}
+
+// ─── URL derivation (pure) ─────────────────────────────────────────────────────────
+
+/** The hosted preview URL for a tenant's PR, or null when the PR/base is unknown. Pure. */
+export function previewUrlFor(base, tenant, pr) {
+  const origin = (base || DEFAULT_STOREFRONT_URL).trim().replace(/\/+$/, "");
+  if (pr == null || `${pr}`.trim() === "" || !tenant) return null;
+  return `${origin}/preview/${encodeURIComponent(tenant)}/pr/${pr}`;
+}
+
+/** The live site URL for a tenant (the tenant IS its apex domain, e.g. tokenoftrust.com). Pure. */
+export function liveUrlFor(tenant) {
+  const t = (tenant || "").trim();
+  return t ? `https://${t}` : null;
+}
+
+// ─── Operator ship (DEPLOY-only) ─────────────────────────────────────────────────────
+
+/**
+ * The OPERATOR ship flow (decision ship-context-dependent-semantics): the caller is
+ * targeting a `--pr N --tenant t` that ISN'T their checkout, so ship means DEPLOY
+ * (main → preview + live) — NOT merge. The merge is the separate `tot accept` verb.
+ *
+ * We STATE the exact deploy plan (the shared `planForAction`/`printPlanAndConfirm`
+ * affordance) and confirm before acting (`--yes` to confirm non-interactively; a
+ * non-TTY without `--yes` refuses).
+ *
+ * ┌─ CROSS-TENANT/CROSS-PR TARGETING (the app-bound-identity constraint) ────────────┐
+ * │ Resolving a TARGETED PR's change-record id / head sha from the forge needs a      │
+ * │ `candidate_status` read the CLI's user identity may NOT be allowed (it's           │
+ * │ app-bound). So we take the change-record id (and head sha) via EXPLICIT flags      │
+ * │ (`--change-id` / `--head-sha`) rather than blocking — mirroring U3's descriptor    │
+ * │ flags. See the `u9` marker below for the auto-resolution follow-on.                │
+ * └───────────────────────────────────────────────────────────────────────────────────┘
+ *
+ * @param {{callTool:Function}} client  an MCP client (real or mock)
+ * @param {{ tenant:string, pr?:number|string|null, changeId?:string|null,
+ *   headSha?:string|null, storefrontUrl?:string|null, noOpen?:boolean, yes?:boolean }} params
+ * @param {{ confirmPlan?:typeof printPlanAndConfirm, poll?:typeof pollChangeShipped,
+ *   openUrl?:(u:string)=>boolean, progress?:boolean }} [deps]
+ * @returns {Promise<number>} process exit code
+ */
+export async function runShipOperator(
+  client,
+  { tenant, pr = null, changeId = null, headSha = null, storefrontUrl = null, noOpen = false, yes = false },
+  deps = {},
+) {
+  const confirmPlan = deps.confirmPlan || printPlanAndConfirm;
+  const poll = deps.poll || pollChangeShipped;
+
+  // u9: auto-resolve targeted PR descriptor (changeId/headSha) via forge PR-read —
+  // the CLI's app-bound user identity may not be allowed the candidate_status read for
+  // a cross-tenant/cross-PR target, so today the operator supplies these via flags.
+  const previewUrl = previewUrlFor(storefrontUrl, tenant, pr);
+  const planLines = planForAction({
+    action: "ship",
+    context: "operator",
+    tenant,
+    pr,
+    changeId,
+    headSha,
+    targets: { preview: previewUrl, live: liveUrlFor(tenant) },
+  });
+  const { confirmed, reason } = await confirmPlan(planLines, {
+    yes,
+    question: `Deploy ${tenant} live now (main → preview + live)?`,
+  });
+  if (!confirmed) {
+    if (reason === "non-tty") {
+      console.error(
+        fail(
+          "`tot ship` needs an interactive terminal to confirm this deploy",
+          "re-run from a terminal, or pass --yes to confirm non-interactively",
+        ),
+      );
+      return 2;
+    }
+    console.log("  Ship cancelled — nothing deployed.");
+    return 0;
+  }
+
+  // We can't auto-resolve the targeted PR's change record from the forge (see above),
+  // so the operator must name it explicitly to promote it.
+  if (!changeId) {
+    console.error(
+      fail(
+        "operator ship needs the target change-record id to deploy",
+        "pass --change-id <chg_…> (u9 will auto-resolve it from --pr via a forge PR-read)",
+      ),
+    );
+    return 2;
+  }
+
+  // TODO(u9): operator ship is DEPLOY-only (the merge is the separate `tot accept`),
+  // but a DISTINCT deploy-only trigger separate from `change_accept` is NOT yet wired.
+  // Until it is, this uses the EXISTING promote path — `change_accept` (u7's
+  // promote-by-digest, keyed on the resolved change-record id) — which is the same
+  // mechanism the developer path calls. Adding a new deploy path is out of scope for u4.
+  let accept;
+  try {
+    accept = normalizeChangeResult(
+      await client.callTool("change_accept", {
+        id: changeId,
+        tenant,
+        dryRun: false,
+        idempotencyKey: `ship-${changeId}-${headSha ?? "head"}`,
+      }),
+    );
+  } catch (e) {
+    console.error(
+      fail(
+        `the deploy gate refused this change: ${String(e?.message || e)}`,
+        "check the change is merged to main and reconciled, then re-run `tot ship`",
+      ),
+    );
+    return 1;
+  }
+
+  const progress = deps.progress === false ? null : startProgress("deploying…");
+  let status;
+  try {
+    status = await poll(client, { id: changeId, tenant });
+  } finally {
+    progress?.stop();
+  }
+  return reportShipped(accept, status, { tenant, noOpen, openUrl: deps.openUrl });
+}
+
+/**
+ * The `run` wrapper for OPERATOR ship — establish a session, bind the target tenant,
+ * and drive `runShipOperator`. Split from `run` for the same reason the developer half
+ * is split from `runShip`: this half does the I/O (auth + tenant switch), the pure flow
+ * is unit-tested with a mock client.
+ * @param {ReturnType<typeof parseShipArgs>} args
+ * @param {any} ctx
+ * @param {NodeJS.ProcessEnv} env
+ */
+async function runOperatorFlow(args, ctx, env) {
+  const tenant = (args.tenant || (ctx.mode === "checkout" ? ctx.tenant : null) || "").trim();
+  if (!tenant) {
+    console.error(
+      fail(
+        "operator ship needs a target tenant",
+        "pass --tenant <appDomain> (e.g. --tenant tokenoftrust.com) with --pr <N>",
+      ),
+    );
+    return 2;
+  }
+  const pr = args.pr != null && `${args.pr}`.trim() && Number.isFinite(Number(args.pr)) ? Number(args.pr) : args.pr;
+  const storefrontUrl = args.url || env.TOT_STOREFRONT_URL || env.STOREFRONT_BASE_URL || DEFAULT_STOREFRONT_URL;
+  const baseUrl = args.mcp || env.MCP_BASE_URL || env.TOT_MCP_URL || DEFAULT_MCP_URL;
+  const client = createMcpClient(baseUrl);
+  try {
+    await establishSession(client, { env, prefer: args.identity || undefined });
+    await client.callTool("client_switch", { tenant });
+    return await runShipOperator(
+      client,
+      {
+        tenant,
+        pr,
+        changeId: args.changeId,
+        headSha: args.headSha,
+        storefrontUrl,
+        noOpen: args.noOpen,
+        yes: args.yes,
+      },
+      { openUrl: (u) => openBrowser(u) },
+    );
+  } catch (e) {
+    if (e instanceof AuthUnavailableError) {
+      console.error(fail("sign in to ship", e.hint || "run `tot login`, then re-run `tot ship`"));
+      return 1;
+    }
+    console.error(
+      fail(
+        `couldn't reach the ship service: ${String(e?.message || e)}`,
+        "check your connection and that you're signed in, then re-run",
+      ),
+    );
+    return 1;
+  }
 }
+
+/**
+ * @param {string[]} argv
+ * @param {any} ctx
+ */
+export async function run(argv, ctx) {
+  const env = process.env;
+  const args = parseShipArgs(argv);
+  if (args.help) {
+    console.log(USAGE);
+    return 0;
+  }
+
+  // Context-dependent (decision ship-context-dependent-semantics): targeting a
+  // `--pr`/`--tenant` that isn't your checkout → OPERATOR (deploy-only); otherwise,
+  // inside your own checkout → DEVELOPER (accept + deploy). Never guessed silently —
+  // both branches print the concrete plan for THAT context and confirm.
+  const ctxTenant = ctx.mode === "checkout" ? ctx.tenant : null;
+  const context = detectShipContext({
+    pr: args.pr,
+    prPositional: args.prPositional,
+    tenant: args.tenant,
+    ctxTenant,
+    ctxMode: ctx.mode,
+  });
+  if (context === "operator") {
+    return await runOperatorFlow(args, ctx, env);
+  }
+
+  if (ctx.mode !== "checkout") {
+    console.error(
+      fail(
+        "`tot ship` runs from inside a tenant checkout",
+        "tot clone <tenant> <dir>   (then `cd` in, `tot preview`, and `tot ship`)",
+      ),
+    );
+    return 2;
+  }
+
+  const workspace = ctx.workspacePath;
+  const tenant = ctx.tenant;
+  const git = (cargs) =>
+    execFileSync("git", ["-C", workspace, ...cargs], { stdio: ["ignore", "pipe", "pipe"] }).toString();
+  const gitSafe = (cargs) => {
+    try {
+      return git(cargs);
+    } catch {
+      return "";
+    }
+  };
+
+  const repo = repoNameFromRemote(gitSafe(["remote", "get-url", "origin"]).trim());
+  if (!repo) {
+    console.error(
+      fail("couldn't derive the forge repo from this checkout's remote", "run this from a `tot clone`d store"),
+    );
+    return 1;
+  }
+
+  const baseUrl = args.mcp || env.MCP_BASE_URL || env.TOT_MCP_URL || DEFAULT_MCP_URL;
+  const statePath = defaultCandidateStatePath(env);
+  const client = createMcpClient(baseUrl);
+  try {
+    const session = await establishSession(client, { env, prefer: args.identity || undefined });
+    // Bind the active tenant so the candidate/change tools read the right scope.
+    await client.callTool("client_switch", { tenant });
+
+    // Resolve which candidate this checkout ships (the u4 seam) — branch-bound so
+    // ship promotes exactly the candidate `tot preview` pushed from THIS branch.
+    const changeId = resolveActiveChangeId({
+      statePath,
+      mcpUrl: baseUrl,
+      repo,
+      tenant,
+      actorKey: actorKeyFor(session),
+      branch: currentBranch(gitSafe),
+    });
+
+    // The title/body the change RECORD is opened with — from the HEAD commit subject
+    // (the reviewed commit's own message), so the approver's record isn't blank.
+    const headSubject = gitSafe(["log", "-1", "--format=%s"]).trim();
+    const changeSummary = buildChangeSummary({ message: headSubject, headSubject });
+
+    return await runShip(
+      client,
+      {
+        tenant,
+        changeId,
+        repo,
+        git,
+        noOpen: args.noOpen,
+        yes: args.yes,
+        storefrontUrl: args.url || env.TOT_STOREFRONT_URL || env.STOREFRONT_BASE_URL || DEFAULT_STOREFRONT_URL,
+        changeSummary,
+        // A positional `tot ship 4` asserts WHICH PR — passed as a safety guard so
+        // ship refuses if this checkout's active candidate is a different PR.
+        expectedPr: args.prPositional ? args.pr : null,
+      },
+      { openUrl: (u) => openBrowser(u) },
+    );
+  } catch (e) {
+    if (e instanceof AuthUnavailableError) {
+      console.error(fail("sign in to ship", e.hint || "run `tot login`, then re-run `tot ship`"));
+      return 1;
+    }
+    console.error(
+      fail(
+        `couldn't reach the ship service: ${String(e?.message || e)}`,
+        "check your connection and that you're signed in, then re-run",
+      ),
+    );
+    return 1;
+  }
+}
+