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

package/src/commands/ship.mjs

@@ -1,25 +1,36 @@
 /**
- * `tot ship` — promote a reconciled PREVIEW live (the deliberate ship gate).
+ * `tot ship` — deploy main → preview + live (decisions operator-verb-and-hosting-model
+ * + ship-context-dependent-semantics). 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
+ *   tot ship       accept + deploy (developer) / deploy (operator)                       ← you are here
  *
- * The contract, deliberately strict because this is the step that changes the LIVE
- * site:
+ * 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:
+ *
+ *   • 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`.
+ *
+ * The DEVELOPER contract, deliberately strict because this 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.
+ *   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.
@@ -50,7 +61,7 @@ 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 { planForAction, printPlanAndConfirm } from "../plan.mjs";
 import { startProgress } from "../progress.mjs";
 import { openBrowser } from "../open.mjs";
 import {
@@ -68,32 +79,138 @@ import {
 } 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: ship ANY built PR (not just your checkout)
+  tot ship --change-id <chg_…>      target an explicit change record (operator targeting)
+  tot ship --secret <s>             operator secret (prefer the env vars below)
+  tot ship --url <origin>           storefront origin (default: env TOT_STOREFRONT_URL)
+  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                 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)
+    • 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 that ISN'T your checkout (\`tot ship 4\` with no local
+      candidate, or an explicit \`--pr N --tenant t\`): ship resolves PR N → the built
+      candidate from the SHARED queue (GET /api/changes) and ships it via the atomic
+      accept (POST /api/changes/accept). This needs an OPERATOR SECRET (env below).
+      If PR N has no built candidate, build it first with \`tot preview build\`.
 
-  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.`;
+  Operator secret (from env, first found): PREVIEW_RECONCILE_SECRET,
+  GRANTS_ADMIN_SECRET, TOT_OPERATOR_SECRET (or pass --secret).
+
+  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.`;
+
+/**
+ * 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 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. Deliberately NO --yes/--force (see the header). */
+/** Parse `tot ship` argv. Pure. */
 export function parseShipArgs(argv) {
-  const a = { mcp: null, identity: null, noOpen: false, help: false };
+  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,
+    secret: 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 === "--secret") a.secret = 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) ───────────
 
 /**
@@ -434,22 +551,40 @@ export async function pollChangeShipped(client, { id, tenant }, { attempts = 6,
  *
  * @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>,
+ *   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]
+ *   resolveRecord?:typeof resolveChangeRecordId,
+ *   shipByPrFallback?:()=>Promise<number> }} [deps]
+ *   shipByPrFallback (u16) — when a POSITIONAL `tot ship <N>` finds NO candidate for
+ *   this checkout, invoke this instead of the "no active candidate" dead-end: it ships
+ *   the built PR from the shared queue (the operator-by-PR path).
  * @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;
+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
@@ -476,6 +611,16 @@ export async function runShip(client, { tenant, changeId, repo, git, noOpen, cha
     : NO_REVIEW;
   const gate = shipReadiness(candidate, review);
 
+  // u16: `tot ship <N>` in a checkout that has NO candidate matching this PR (the PR
+  // isn't yours) — fall through to the OPERATOR-by-PR queue path (resolve PR→changeId
+  // from GET /api/changes, ship via POST /api/changes/accept) instead of dead-ending on
+  // "no active candidate". Only fires for a POSITIONAL PR (expectedPr) with the fallback
+  // wired (run() supplies it). The U15 different-PR guard (step 1a) still REFUSES — this
+  // is the distinct "nothing to ship from THIS checkout" case, not a mismatch.
+  if (gate.kind === "no-candidate" && expectedPr != null && deps.shipByPrFallback) {
+    return await deps.shipByPrFallback();
+  }
+
   if (gate.kind === "unauthorized") {
     return await handleUnauthorized(client, { id, tenant, approvers: review.approvers });
   }
@@ -484,22 +629,38 @@ export async function runShip(client, { tenant, changeId, repo, git, noOpen, cha
     return 1;
   }
 
-  // 2. ALWAYS render the diff-vs-live, then require ONE explicit y/N confirm.
+  // 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);
 
-  // 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) {
+  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;
   }
@@ -580,6 +741,504 @@ function reportShipped(accept, status, { tenant, noOpen, openUrl }) {
   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-by-PR via the SHARED candidate queue (unit U16) ──────────────────
+//
+// The real user report: `tot ship 4` for a PR the operator did NOT author fails
+// `✗ no active candidate to ship for this checkout` — U15's developer path resolves
+// the candidate from the LOCAL git checkout, so it can't ship a PR that isn't yours,
+// and U15's operator path needed an explicit `--change-id` (it couldn't resolve
+// PR→changeId — the `// u9:` gap).
+//
+// The insight this unit builds on (NO forge PR-read needed): a BUILT PR already has a
+// `ReviewEnvironment` in the candidate index, and `GET /api/changes` (the operator
+// accept queue) returns the tenant's OPEN candidates — each with `changeId` +
+// `prNumber` + `headSha`. So PR N → changeId is resolvable from the QUEUE. The ship is
+// then the SAME atomic merge→main→reconcile→promote-live the `/admin` Accept button
+// drives — `POST /api/changes/accept` with `{ repo:<appDomain>, changeId,
+// expectedHeadSha }` — NOT the MCP `change_accept` (that's chg_-record-id-keyed +
+// checkout-bound). The go-live HUMAN GATE stays the confirm.
+//
+// AUTH (investigated): `resolveOwnerSession` (apps/storefront/src/lib/grants/session.ts)
+// accepts a SIGNED-IN storefront `tot_session` cookie (path 1) OR the Bearer operator
+// secret + `X-Tot-Owner` (path 2). The CLI holds NO storefront cookie — its OAuth login
+// is with the MCP, a different trust boundary — so the signed-in/OAuth path can't apply
+// here. The Bearer operator-secret path is the CLI's ONLY route, exactly mirroring
+// `tot preview build`'s transport (Bearer + `X-Tot-Owner` + `x-tot-capability`).
+
+const OPERATOR_SECRET_ENV = ["PREVIEW_RECONCILE_SECRET", "GRANTS_ADMIN_SECRET", "TOT_OPERATOR_SECRET"];
+
+/**
+ * Resolve the operator secret from an explicit `--secret` or the env (first found),
+ * matching `tot preview build`'s precedence. Pure given its env argument.
+ * @param {string|null|undefined} explicit
+ * @param {NodeJS.ProcessEnv} env
+ * @returns {string}
+ */
+export function resolveOperatorSecret(explicit, env = {}) {
+  if (explicit && `${explicit}`.trim()) return `${explicit}`.trim();
+  for (const k of OPERATOR_SECRET_ENV) {
+    const v = env[k];
+    if (v && `${v}`.trim()) return `${v}`.trim();
+  }
+  return "";
+}
+
+/**
+ * Normalise a `GET /api/changes` body to the OPEN candidate list. The endpoint
+ * answers `{ owner, capability, current, changes }` where `changes` is the open
+ * `ReviewEnvironment` queue; read defensively (tolerate a bare array or a `{ changes }`
+ * wrapper) and keep only records carrying a `changeId`. Pure — unit-tested.
+ * @param {any} data
+ * @returns {Array<{changeId:string, prNumber?:number|null, headSha?:string|null, previewUrl?:string|null}>}
+ */
+export function normalizeChangesQueue(data) {
+  const list = Array.isArray(data)
+    ? data
+    : data && Array.isArray(data.changes)
+      ? data.changes
+      : [];
+  return list.filter((c) => c && typeof c === "object" && typeof c.changeId === "string");
+}
+
+/**
+ * Find the OPEN candidate whose forge PR number === `pr` and return the descriptor
+ * the by-PR ship needs (`{ changeId, headSha, prNumber, previewUrl }`), else null when
+ * no built candidate matches. Pure — unit-tested.
+ * @param {ReturnType<typeof normalizeChangesQueue>} changes
+ * @param {number|string} pr
+ * @returns {{changeId:string, headSha:string|null, prNumber:number, previewUrl:string|null}|null}
+ */
+export function findCandidateByPr(changes, pr) {
+  const want = Number(pr);
+  if (!Number.isFinite(want)) return null;
+  for (const c of changes || []) {
+    if (c.prNumber != null && Number(c.prNumber) === want) {
+      return {
+        changeId: c.changeId,
+        headSha: c.headSha ?? null,
+        prNumber: want,
+        previewUrl: c.previewUrl ?? null,
+      };
+    }
+  }
+  return null;
+}
+
+/**
+ * Normalise a `POST /api/changes/accept` body to { shipped, pending, state, sha,
+ * message, error }. The atomic-accept endpoint reports an HONEST terminal `state`:
+ * `shipped` (and `live:true`) ONLY when the target is verified live; `publish_pending`
+ * = merged + dispatched but NOT yet verified (never a live claim). Pure — unit-tested.
+ * @param {any} data
+ */
+export function normalizeAcceptResponse(data) {
+  const o = data && typeof data === "object" ? data : {};
+  const state = typeof o.state === "string" ? o.state : null;
+  const shipped = state === "shipped" || o.live === true;
+  return {
+    shipped,
+    pending: !shipped && (state === "publish_pending" || o.merged === true),
+    state,
+    sha: typeof o.sha === "string" ? o.sha : null,
+    message: typeof o.message === "string" ? o.message : null,
+    error: typeof o.error === "string" ? o.error : null,
+    raw: data,
+  };
+}
+
+/**
+ * The OPERATOR ship-by-PR flow (unit U16). Ships ANY built PR — not just your
+ * checkout — with NO forge PR-read:
+ *
+ *   1. RESOLVE PR N → { changeId, headSha } by reading the tenant's OPEN candidate
+ *      queue (`GET /api/changes`) and matching `prNumber === N`. If N isn't in the
+ *      queue the PR has no built candidate → instruct `tot preview build` first (we
+ *      NEVER invent a changeId).
+ *   2. PLAN + CONFIRM — the go-live HUMAN GATE. `POST /api/changes/accept` is the
+ *      atomic merge→main + reconcile + promote-live, so the plan states BOTH (the
+ *      developer-context wording, mirroring the `/admin` Accept plan). `--yes` confirms
+ *      non-interactively; a non-TTY without `--yes` REFUSES — nothing merges/goes live
+ *      without an explicit yes.
+ *   3. SHIP via `POST /api/changes/accept` `{ repo:<tenant appDomain>, changeId,
+ *      expectedHeadSha }` — the SAME endpoint the `/admin` Accept button uses.
+ *
+ * Transport mirrors `tot preview build` exactly (Bearer operator secret + `X-Tot-Owner`
+ * + `x-tot-capability: ship-on-behalf`). `fetch`/confirm/openUrl/progress are injected
+ * so it's unit-tested with no network/TTY.
+ *
+ * @param {{ tenant:string, pr:number|string|null, secret:string, storefrontUrl?:string|null,
+ *   noOpen?:boolean, yes?: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 runShipByPr(
+  { tenant, pr, secret, storefrontUrl = null, noOpen = false, yes = false },
+  deps = {},
+) {
+  const fetchImpl = deps.fetch || globalThis.fetch;
+  const confirmPlan = deps.confirmPlan || printPlanAndConfirm;
+  const base = (storefrontUrl || DEFAULT_STOREFRONT_URL).trim().replace(/\/+$/, "");
+
+  const want = pr != null && `${pr}`.trim() && Number.isFinite(Number(pr)) ? Number(pr) : null;
+  if (want == null) {
+    console.error(
+      fail(
+        "operator ship needs a PR number to resolve the built candidate",
+        "pass a PR — `tot ship <N>` or `tot ship --pr <N> --tenant <appDomain>`",
+      ),
+    );
+    return 2;
+  }
+  if (!secret) {
+    console.error(
+      fail(
+        "shipping a PR that isn't your checkout is an OPERATOR action — it needs an operator secret",
+        "set PREVIEW_RECONCILE_SECRET (or GRANTS_ADMIN_SECRET / TOT_OPERATOR_SECRET), or pass --secret",
+      ),
+    );
+    return 2;
+  }
+
+  const authHeaders = {
+    authorization: `Bearer ${secret}`,
+    "x-tot-owner": tenant,
+    "x-tot-capability": "ship-on-behalf",
+  };
+
+  // 1. Resolve PR N → { changeId, headSha } from the tenant's OPEN candidate queue.
+  let queueRes;
+  try {
+    queueRes = await fetchImpl(`${base}/api/changes`, { method: "GET", headers: authHeaders });
+  } catch (e) {
+    console.error(
+      fail(`couldn't reach the candidate queue at ${base}: ${String(e?.message || e)}`, "check --url / your network, then re-run"),
+    );
+    return 1;
+  }
+  const queueData = await readJsonSafe(queueRes);
+  if (!queueRes.ok) {
+    const msg = queueData?.error || `HTTP ${queueRes.status}`;
+    console.error(
+      fail(
+        `the candidate queue refused the request: ${msg}`,
+        queueRes.status === 401 || queueRes.status === 403
+          ? "check the operator secret and that it's authorised for this tenant"
+          : "check --tenant / --url, then re-run",
+      ),
+    );
+    return 1;
+  }
+
+  const candidate = findCandidateByPr(normalizeChangesQueue(queueData), want);
+  if (!candidate) {
+    const previewUrl = previewUrlFor(base, tenant, want);
+    console.error(
+      fail(
+        `PR #${want} has no built candidate in ${tenant}'s queue — there's nothing to ship`,
+        `build it first: \`tot preview build --tenant ${tenant} --pr ${want}\`, then \`tot ship ${want} --tenant ${tenant}\``,
+      ),
+    );
+    if (previewUrl) console.error(`  Once built it appears at: ${previewUrl}`);
+    return 1;
+  }
+
+  // 2. Plan + confirm — the go-live HUMAN GATE. `POST /api/changes/accept` is the
+  //    ATOMIC merge→main + promote-live, so the plan narrates BOTH (developer-context
+  //    wording — the same "merge … then deploy" the /admin Accept plan renders).
+  const previewUrl = candidate.previewUrl || previewUrlFor(base, tenant, want);
+  const planLines = planForAction({
+    action: "ship",
+    context: "developer",
+    tenant,
+    pr: want,
+    changeId: candidate.changeId,
+    headSha: candidate.headSha,
+    targets: { preview: previewUrl, live: liveUrlFor(tenant) },
+  });
+  const { confirmed, reason } = await confirmPlan(planLines, {
+    yes,
+    question: `Ship PR #${want} live to ${tenant} (merge → main, then go live)?`,
+  });
+  if (!confirmed) {
+    if (reason === "non-tty") {
+      console.error(
+        fail(
+          "`tot ship` needs an interactive terminal to confirm this live change",
+          "re-run from a terminal, or pass --yes to confirm non-interactively",
+        ),
+      );
+      return 2;
+    }
+    console.log("  Ship cancelled — nothing changed.");
+    return 0;
+  }
+
+  // 3. Accept it via the SAME endpoint the /admin Accept button uses (repo=appDomain).
+  const progress = deps.progress === false ? null : startProgress("shipping…");
+  let acceptRes;
+  try {
+    acceptRes = await fetchImpl(`${base}/api/changes/accept`, {
+      method: "POST",
+      headers: { "content-type": "application/json", ...authHeaders },
+      body: JSON.stringify({
+        repo: tenant,
+        changeId: candidate.changeId,
+        ...(candidate.headSha ? { expectedHeadSha: candidate.headSha } : {}),
+      }),
+    });
+  } catch (e) {
+    progress?.stop();
+    console.error(
+      fail(`couldn't reach the ship endpoint at ${base}: ${String(e?.message || e)}`, "check --url / your network, then re-run"),
+    );
+    return 1;
+  }
+  const acceptData = await readJsonSafe(acceptRes);
+  progress?.stop();
+
+  const result = normalizeAcceptResponse(acceptData);
+  if (!acceptRes.ok && !result.shipped && !result.pending) {
+    const why = result.error || result.message || `HTTP ${acceptRes.status}`;
+    console.error(
+      fail(
+        `the ship gate refused this change (HTTP ${acceptRes.status}): ${why}`,
+        "check the PR reconciled cleanly (rebuild with `tot preview build`), then re-run",
+      ),
+    );
+    return 1;
+  }
+  return reportShippedByPr(result, { tenant, pr: want, previewUrl, noOpen, openUrl: deps.openUrl });
+}
+
+/** Read a fetch Response body as JSON, tolerating a non-JSON/empty body. */
+async function readJsonSafe(res) {
+  try {
+    return await res.json();
+  } catch {
+    return {};
+  }
+}
+
+/** Report the by-PR ship result — honest terminal state (never a false "shipped live"). */
+function reportShippedByPr(result, { tenant, pr, previewUrl, noOpen, openUrl }) {
+  const liveUrl = liveUrlFor(tenant);
+  if (result.shipped) {
+    console.log(`\n  ✓ shipped PR #${pr} live to ${tenant}.`);
+    if (liveUrl) {
+      console.log(`  Live: ${liveUrl}`);
+      if (!noOpen && openUrl && openUrl(liveUrl)) console.log("  (opened in your browser)");
+    }
+    return 0;
+  }
+  // Merged + dispatched but the target isn't verified live yet — honest in-flight.
+  console.log(`\n  ~ ship accepted for PR #${pr} on ${tenant}; it's going live now (not yet verified).`);
+  if (previewUrl) console.log(`  Track it here: ${previewUrl}`);
+  return 0;
+}
+
+// ─── 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;
+
+  // u16: with NO explicit change-record id, ship ANY built PR via the SHARED candidate
+  // queue — resolve PR→changeId from GET /api/changes and ship via POST
+  // /api/changes/accept (operator secret transport). This is the path that ships a PR
+  // the operator did NOT author. The explicit `--change-id` path below stays the MCP
+  // change_accept targeting (backward-compatible; distinct chg_-record namespace).
+  if (!args.changeId) {
+    return await runShipByPr(
+      {
+        tenant,
+        pr,
+        secret: resolveOperatorSecret(args.secret, env),
+        storefrontUrl,
+        noOpen: args.noOpen,
+        yes: args.yes,
+      },
+      { openUrl: (u) => openBrowser(u) },
+    );
+  }
+
+  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
@@ -591,6 +1250,23 @@ export async function run(argv, ctx) {
     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(
@@ -645,10 +1321,44 @@ export async function run(argv, ctx) {
     const headSubject = gitSafe(["log", "-1", "--format=%s"]).trim();
     const changeSummary = buildChangeSummary({ message: headSubject, headSubject });
 
+    const storefrontUrl = args.url || env.TOT_STOREFRONT_URL || env.STOREFRONT_BASE_URL || DEFAULT_STOREFRONT_URL;
     return await runShip(
       client,
-      { tenant, changeId, repo, git, noOpen: args.noOpen, changeSummary },
-      { openUrl: (u) => openBrowser(u) },
+      {
+        tenant,
+        changeId,
+        repo,
+        git,
+        noOpen: args.noOpen,
+        yes: args.yes,
+        storefrontUrl,
+        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),
+        // u16: when `tot ship <N>` names a PR that ISN'T this checkout's candidate (no
+        // local candidate resolves), fall through to the operator-by-PR queue path — so
+        // `tot ship 4` ships someone else's built PR too, using this checkout's tenant.
+        ...(args.prPositional
+          ? {
+              shipByPrFallback: () =>
+                runShipByPr(
+                  {
+                    tenant,
+                    pr: args.pr,
+                    secret: resolveOperatorSecret(args.secret, env),
+                    storefrontUrl,
+                    noOpen: args.noOpen,
+                    yes: args.yes,
+                  },
+                  { openUrl: (u) => openBrowser(u) },
+                ),
+            }
+          : {}),
+      },
     );
   } catch (e) {
     if (e instanceof AuthUnavailableError) {