npm - @tokenoftrust/cli - Versions diffs - 1.4.0-rc.1 → 1.4.0-rc.11 - Mend

@tokenoftrust/cli 1.4.0-rc.1 → 1.4.0-rc.11

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (20) hide show

package/README.md +12 -9
package/bin/tot.mjs +51 -11
package/package.json +2 -2
package/src/candidate-state.mjs +137 -0
package/src/commands/{checkout.mjs → clone.mjs} +129 -28
package/src/commands/dev.mjs +110 -15
package/src/commands/doctor.mjs +4 -3
package/src/commands/grants.mjs +8 -3
package/src/commands/link.mjs +225 -0
package/src/commands/login.mjs +19 -12
package/src/commands/pr.mjs +214 -0
package/src/commands/preview.mjs +71 -0
package/src/commands/ship.mjs +667 -0
package/src/commands/start.mjs +34 -14
package/src/commands/submit.mjs +458 -41
package/src/commands/validate.mjs +2 -2
package/src/commands/whoami.mjs +6 -2
package/src/context.mjs +2 -2
package/src/oauth.mjs +92 -42
package/src/obstacle-beacon.cjs +1 -1

package/src/commands/ship.mjs ADDED Viewed

@@ -0,0 +1,667 @@
+/**
+ * `tot ship` — promote a reconciled PREVIEW live (the deliberate ship gate).
+ *
+ * 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
+ *
+ * The contract, deliberately strict because this is the step that changes the LIVE
+ * site:
+ *
+ *   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) and
+ *      require ONE explicit [y/N] confirm, defaulting to NO. There is deliberately
+ *      NO `--yes` / `--force` bypass in v1: shipping live is a decision a human
+ *      makes at the keyboard. In a NON-TTY (CI, piped) we REFUSE rather than
+ *      auto-confirm — nothing ships without someone saying yes.
+ *   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 { isInteractive, promptYesNo } from "../prompt.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 USAGE = `tot ship — promote a reconciled preview live
+  tot ship                 promote the preview you last pushed with \`tot preview\`
+  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)
+  Ship makes your preview LIVE once it has reconciled cleanly — the deliberate step
+  AFTER \`tot preview\`. It ALWAYS shows you the diff about to go live and asks for a
+  single y/N confirmation first; there is no --yes/--force, and it refuses to run
+  without an interactive terminal. If you can't approve the ship yourself, it records
+  the request and tells you who can.`;
+/** Parse `tot ship` argv. Pure. Deliberately NO --yes/--force (see the header). */
+export function parseShipArgs(argv) {
+  const a = { mcp: null, identity: null, noOpen: false, 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 === "--help" || t === "-h") a.help = true;
+  }
+  return a;
+}
+// ─── 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,
+ *   changeSummary?:{ title?:string, body?:string[] } }} params
+ * @param {{ interactive?:()=>boolean, confirm?:(q:string,d:boolean)=>Promise<boolean>,
+ *   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, changeSummary }, deps = {}) {
+  const interactive = deps.interactive || isInteractive;
+  const confirm = deps.confirm || promptYesNo;
+  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 }));
+  // 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 require ONE explicit y/N confirm.
+  const diff = computeDiffVsLive(git, candidate.baseSha, candidate.headSha);
+  for (const line of renderDiffVsLive({ ...diff, prUrl: candidate.url })) console.log(line);
+  // NON-TTY: refuse rather than auto-confirm — nothing ships without a human yes.
+  if (!interactive()) {
+    console.error(
+      fail(
+        "`tot ship` needs an interactive terminal to confirm the live change",
+        "run it from a terminal (there is intentionally no --yes/--force)",
+      ),
+    );
+    return 2;
+  }
+  const proceed = await confirm(`\n  Ship this live to ${tenant}?`, false);
+  if (!proceed) {
+    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(
+      "you're not authorised to ship this change live yourself",
+      "the change is recorded and ready for review — an authorised approver can ship it",
+    ),
+  );
+  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;
+}
+/**
+ * @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;
+  }
+  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, changeSummary },
+      { 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;
+  }
+}