@tokenoftrust/cli 1.4.0-rc.2 → 1.4.0-rc.21

package/src/commands/accept.mjs

@@ -0,0 +1,736 @@
+/**
+ * `tot accept --tenant <t> --pr <N>` (alias: `tot merge`) — OPERATOR verb: QUEUE a
+ * PR's integration into the protected `preview` AGGREGATE. This SUPERSEDES the
+ * retired `tot accept` = merge-PR→main semantics (operator-console U5): accepting a
+ * change no longer merges it to main — it enqueues it into the tenant's shared
+ * `preview` aggregate, where b07's tenant-serialized queue merges it (b06
+ * `candidate_accept`, preview-base only), rebuilds the aggregate, and moves the
+ * shared preview pointer ONLY when combined evidence is green.
+ *
+ * DISTINCT from `tot ship`: accept is NOT go-live. It touches NO `main` and NO live
+ * channel; a green aggregate is promoted live only by a later `tot ship`. And it is
+ * NOT `tot preview build` (which materializes ONE candidate's own preview in
+ * isolation) — accept lands the candidate into the SHARED aggregate other reviewers
+ * see.
+ *
+ * TARGET RESOLUTION — `--pr N --tenant t` names the PR; the server resolves it to its
+ * candidate from the tenant's ReviewEnvironment index (unit b04 — tenant + PR, NO
+ * chg-id). An explicit `--change-id` is still accepted (targets a specific record),
+ * but is no longer REQUIRED — the whole point of b08 is that a PR number is enough.
+ *
+ * TRANSPORT — the honest accept path is `POST /api/changes/integrate` (the ONE call
+ * site of b07's `TenantIntegrationQueue.enqueue`). Like `tot ship --pr` (U16) and
+ * `tot pr list --tenant` (U17), the CLI reaches it with the OPERATOR-SECRET Bearer
+ * transport (`resolveOperatorSecret` + `X-Tot-Owner` + `x-tot-capability`), since the
+ * CLI holds no storefront cookie. The response is the honest `IntegrateOutcome` —
+ * `queueState` / `runState` / `pointerMoved` / `aggregateSha` / `statusMessage` —
+ * which this verb renders VERBATIM, never a bare "merged".
+ *
+ * HUMAN GATE — integrating into the shared preview is a decision a human makes, so
+ * this ALWAYS states the EXACT plan (shared `planForAction`, unit U10: which PR,
+ * which tenant, "queue for integration into the preview aggregate — NO merge, NO
+ * go-live") and requires an explicit confirm. `--yes` is an explicit affirmative; a
+ * non-TTY without `--yes` is refused (mirrors `tot ship`'s non-TTY refusal).
+ *
+ * Dependency-free (global fetch + the shared plan module).
+ */
+import { fail } from "../errors.mjs";
+import { planForAction, printPlanAndConfirm } from "../plan.mjs";
+// Reuse `tot ship`'s operator-secret precedence verbatim so accept + ship + pr-list
+// speak ONE operator-auth contract, not three.
+import { resolveOperatorSecret } from "./ship.mjs";
+// Automate-first conflict recovery (workstream tot-merge-conflict-resolution-ux, unit
+// u5): the ONE-CLICK `--refresh` path calls the `candidate_refresh` MCP tool (u1) —
+// which has NO operator-secret HTTP route, so it is reached over the MCP client the
+// same way `tot pr` reaches `candidate_status`/`candidate_close`.
+import { createMcpClient } from "../mcp.mjs";
+import { establishSession, AuthUnavailableError } from "../auth.mjs";
+// No-operator-secret path: mint a viewer session from the developer's OWN `tot`
+// login and integrate as themselves (server gates on their live ship-on-behalf grant).
+import { resolveViewerTransport } from "../viewer-session.mjs";
+
+const DEFAULT_STOREFRONT_URL = "https://storefront.tokenoftrust.store";
+const DEFAULT_MCP_URL = "https://mcp.tokenoftrust.com";
+
+// The three refresh strategies `candidate_refresh` (u1) accepts, mirroring the admin
+// panel's one-click resolver (keep-mine / keep-current / smart-merge). `merge` is the
+// DEFAULT: a real forge three-way merge that refuses cleanly (with the diverged file
+// list) on a genuine same-line overlap rather than silently clobbering either side —
+// exactly the automate-first posture (auto-resolve where safe, name the conflict when
+// not, never a raw rebase instruction).
+export const REFRESH_STRATEGIES = ["ours", "theirs", "merge"];
+const DEFAULT_REFRESH_STRATEGY = "merge";
+
+const USAGE = `tot accept — queue a PR's integration into the preview aggregate (alias: tot merge)
+
+  tot accept --tenant <t> --pr <N>
+  tot merge   --tenant <t> --pr <N>   (same command)
+
+  Queues the given PR for integration into the tenant's protected \`preview\`
+  aggregate: the serialized queue merges it into \`preview\` (preview-base only),
+  rebuilds the aggregate, runs combined evidence, and moves the shared preview
+  pointer ONLY when green. Accepting does NOT merge to main and does NOT go live —
+  a green aggregate is promoted live later by \`tot ship\`.
+
+  Integrating into the shared preview is a human decision: this ALWAYS prints the
+  exact plan and asks for an explicit confirm. There is no default-yes; a non-TTY
+  without --yes is refused rather than silently proceeding.
+
+  If the preview branch has moved under your change so it is no longer mergeable,
+  accept does NOT hand you a rebase — it offers to REBUILD the change on the current
+  preview tip for you. Pass --refresh to do it in one step (no local git), choosing
+  how to resolve any file that changed on both sides with --strategy.
+
+Options:
+  --tenant <appDomain>   Target tenant (e.g. tokenoftrust.com). Defaults to the
+                         current checkout's tenant when run inside one.
+  --pr <N>               PR number to integrate. The server resolves it to its
+                         candidate from the tenant's queue (no --change-id needed).
+  --change-id <id>       Target a specific change record instead of a PR number.
+  --head-sha <sha>       Optional expected PR head sha (expectedHeadSha) — an
+                         optimistic-concurrency guard against a PR that moved.
+  --refresh              If the candidate isn't mergeable, rebuild it on the current
+                         preview tip (via candidate_refresh) and then integrate — no
+                         local rebase. Needs your \`tot login\` sign-in + promote access.
+  --strategy <s>         How --refresh resolves a file changed on BOTH sides:
+                         "merge" (real 3-way merge, refuses on a genuine conflict —
+                         the default), "ours" (keep your version), "theirs" (keep
+                         preview's version).
+  --url <origin>         storefront origin (default: env TOT_STOREFRONT_URL)
+  --mcp <url>            MCP base URL for --refresh (default: env TOT_MCP_URL)
+  --secret <s>           operator secret (prefer the env vars below)
+  --yes, -y              Skip the interactive confirm (still an explicit human
+                         affirmative — there is no default-yes).
+  --help, -h             Show this help.
+
+  Operator secret (from env, first found): PREVIEW_RECONCILE_SECRET,
+  GRANTS_ADMIN_SECRET, TOT_OPERATOR_SECRET (or pass --secret).`;
+
+/** Parse `tot accept` / `tot merge` argv. Pure — unit-testable. */
+export function parseAcceptArgs(argv) {
+  const a = {
+    tenant: null,
+    pr: null,
+    changeId: null,
+    headSha: null,
+    url: null,
+    mcp: null,
+    secret: null,
+    identity: null,
+    refresh: false,
+    strategy: null,
+    yes: false,
+    help: false,
+  };
+  for (let i = 0; i < argv.length; i++) {
+    const t = argv[i];
+    if (t === "--tenant") a.tenant = argv[++i];
+    else if (t === "--pr") a.pr = 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 === "--mcp") a.mcp = argv[++i];
+    else if (t === "--secret") a.secret = argv[++i];
+    else if (t === "--identity") a.identity = argv[++i];
+    else if (t === "--refresh") a.refresh = true;
+    else if (t === "--strategy") a.strategy = argv[++i];
+    else if (t === "--yes" || t === "-y") a.yes = true;
+    else if (t === "--help" || t === "-h") a.help = true;
+  }
+  return a;
+}
+
+/**
+ * Normalise a `POST /api/changes/integrate` body to the honest terminal aggregate
+ * fields this verb renders. Reads defensively so a plausible field rename degrades
+ * rather than crashes. Pure — unit-tested.
+ * @param {any} data
+ * @returns {{ ok:boolean, queueState:string|null, runState:string|null,
+ *   pointerMoved:boolean, aggregateSha:string|null, statusMessage:string|null,
+ *   reason:string|null, changeId:string|null, prNumber:number|null, error:string|null, raw:any }}
+ */
+export function normalizeIntegrateResponse(data) {
+  const o = data && typeof data === "object" ? data : {};
+  return {
+    ok: o.ok === true,
+    queueState: typeof o.queueState === "string" ? o.queueState : null,
+    runState: typeof o.runState === "string" ? o.runState : null,
+    pointerMoved: o.pointerMoved === true,
+    aggregateSha: typeof o.aggregateSha === "string" ? o.aggregateSha : null,
+    statusMessage: typeof o.statusMessage === "string" ? o.statusMessage : null,
+    reason: typeof o.reason === "string" ? o.reason : null,
+    changeId: typeof o.changeId === "string" ? o.changeId : null,
+    prNumber: typeof o.prNumber === "number" ? o.prNumber : null,
+    error: typeof o.error === "string" ? o.error : null,
+    raw: data,
+  };
+}
+
+/** A human label for a candidate: its PR number when known, else its changeId. Pure. */
+function candidateLabel(pr, changeId) {
+  return pr != null ? `PR #${pr}` : `change ${changeId}`;
+}
+
+/**
+ * Read the forge `mergeable` verdict for a candidate out of a `GET /api/changes`
+ * body (b07's operator queue — its BUILT entries carry the full ReviewEnvironment
+ * shape, incl. `mergeable`). This is the mergeable PREFLIGHT source: one read over the
+ * SAME operator-secret transport accept already uses, so a not-mergeable candidate is
+ * caught BEFORE a doomed integrate round-trips to the forge. Best-effort by design —
+ * `known:false` (proceed as normal) whenever the candidate isn't found or isn't built
+ * yet (no `mergeable`), so this never turns a transient listing gap into a false
+ * refusal. Pure — unit-tested.
+ * @param {any} data
+ * @param {{ pr:number|null, changeId:string|null }} target
+ * @returns {{ known:boolean, mergeable:boolean|null, changeId:string|null, prNumber:number|null }}
+ */
+export function readCandidateVerdict(data, { pr, changeId }) {
+  const list = Array.isArray(data)
+    ? data
+    : data && Array.isArray(data.changes)
+      ? data.changes
+      : [];
+  const wantPr =
+    typeof pr === "number"
+      ? pr
+      : pr != null && `${pr}`.trim() && Number.isFinite(Number(pr))
+        ? Number(pr)
+        : null;
+  const wantId = typeof changeId === "string" && changeId ? changeId : null;
+  const match =
+    list.find(
+      (c) =>
+        c &&
+        typeof c === "object" &&
+        ((wantId && c.changeId === wantId) || (wantPr != null && c.prNumber === wantPr)),
+    ) || null;
+  if (!match) return { known: false, mergeable: null, changeId: wantId, prNumber: wantPr };
+  const mergeable = match.mergeable === true ? true : match.mergeable === false ? false : null;
+  return {
+    known: mergeable !== null,
+    mergeable,
+    changeId: typeof match.changeId === "string" ? match.changeId : wantId,
+    prNumber: typeof match.prNumber === "number" ? match.prNumber : wantPr,
+  };
+}
+
+/**
+ * Normalise a `candidate_refresh` (u1) result read back over the MCP client.
+ * `status:"committed"` is the ONLY success (the candidate was rebuilt and is now
+ * mergeable); a `merge_failed` refusal carries `unresolved` (the diverged files);
+ * any other status is an honest refusal/error surfaced by its `message`. Reads
+ * defensively — a plausible field rename degrades, never crashes. Pure — unit-tested.
+ * @param {any} data
+ */
+export function normalizeRefreshResult(data) {
+  const o = data && typeof data === "object" ? data : {};
+  const ok = o.status === "committed";
+  return {
+    ok,
+    status: typeof o.status === "string" ? o.status : ok ? "committed" : "error",
+    changeId: typeof o.changeId === "string" ? o.changeId : null,
+    prNumber: typeof o.prNumber === "number" ? o.prNumber : null,
+    mergeable: typeof o.mergeable === "boolean" ? o.mergeable : null,
+    strategy: typeof o.strategy === "string" ? o.strategy : null,
+    refreshedFiles: Array.isArray(o.refreshedFiles)
+      ? o.refreshedFiles.filter((x) => typeof x === "string")
+      : [],
+    unresolved: Array.isArray(o.unresolved)
+      ? o.unresolved.filter((x) => typeof x === "string")
+      : [],
+    message: typeof o.message === "string" ? o.message : null,
+  };
+}
+
+/**
+ * The automate-first OFFER printed when a candidate isn't mergeable and --refresh was
+ * NOT passed: the one-click rebuild, never a raw git/rebase instruction and never the
+ * banned "resolve the conflict, then retry". Pure — returns the lines to print.
+ * @param {string} tenant
+ * @param {{ pr:number|null, changeId:string|null }} target
+ * @returns {string[]}
+ */
+export function notMergeableOfferLines(tenant, { pr, changeId }) {
+  const sel = pr != null ? `--pr ${pr}` : `--change-id ${changeId}`;
+  const cmd = `tot accept --tenant ${tenant} ${sel}`;
+  return [
+    "  Rebuild it automatically on the current preview tip — no local checkout, one command:",
+    `    ${cmd} --refresh                    smart 3-way merge (the default)`,
+    `    ${cmd} --refresh --strategy=ours    keep your version on any clash`,
+    `    ${cmd} --refresh --strategy=theirs  take preview's version on any clash`,
+    "  Nothing was integrated.",
+  ];
+}
+
+/**
+ * Run `candidate_refresh` (u1) over the MCP client — the ONE-CLICK rebuild of a
+ * not-mergeable candidate onto the current preview tip. `candidate_refresh` has no
+ * operator-secret HTTP route, so this reaches it exactly as `tot pr` reaches
+ * `candidate_status`: an OAuth developer session (`tot login`) + `client_switch` to
+ * bind the tenant scope. `createClient`/`establishSession` are injected so it's
+ * unit-tested with no live MCP.
+ *
+ * @param {{ tenant:string, changeId:string, strategy:string, mcpUrl?:string|null,
+ *   identity?:string|null, env?:NodeJS.ProcessEnv }} params
+ * @param {{ createClient?:typeof createMcpClient, establishSession?:typeof establishSession }} [deps]
+ * @returns {Promise<ReturnType<typeof normalizeRefreshResult> & { hint?:string|null }>}
+ */
+export async function runRefresh(
+  { tenant, changeId, strategy, mcpUrl = null, identity = null, env = process.env },
+  deps = {},
+) {
+  const create = deps.createClient || createMcpClient;
+  const establish = deps.establishSession || establishSession;
+  const baseUrl = mcpUrl || env.MCP_BASE_URL || env.TOT_MCP_URL || DEFAULT_MCP_URL;
+  const client = create(baseUrl);
+  try {
+    await establish(client, { env, prefer: identity || undefined });
+    // Bind the active tenant so candidate_refresh resolves the right scope (mirrors
+    // `tot pr`). Best-effort — the tool also takes `repo` explicitly.
+    try {
+      await client.callTool("client_switch", { tenant });
+    } catch {
+      /* best-effort scope bind */
+    }
+    const raw = await client.callTool("candidate_refresh", { repo: tenant, changeId, strategy });
+    return normalizeRefreshResult(raw);
+  } catch (e) {
+    if (e instanceof AuthUnavailableError) {
+      return { ...normalizeRefreshResult(null), status: "auth", message: e.message, hint: e.hint };
+    }
+    return { ...normalizeRefreshResult(null), status: "error", message: String(e?.message || e) };
+  }
+}
+
+/**
+ * Render a `candidate_refresh` FAILURE in the automate-first house style — a genuine
+ * conflict names the diverged files and offers the ours/theirs escape hatch; an auth
+ * gap points to `tot login`; any other refusal surfaces the MCP's own message. NEVER
+ * prints raw git/rebase or the banned "resolve the conflict, then retry". Returns the
+ * process exit code (always 1). Pure given console.
+ */
+function reportRefreshFailure(rr, { tenant, pr, changeId, strategy }) {
+  const sel = pr != null ? `--pr ${pr}` : `--change-id ${changeId}`;
+  const cmd = `tot accept --tenant ${tenant} ${sel}`;
+  if (rr.status === "auth") {
+    console.error(
+      fail(
+        "auto-refresh needs your Token of Trust sign-in",
+        rr.hint || "run `tot login`, then re-run with --refresh",
+      ),
+    );
+    return 1;
+  }
+  if (rr.status === "merge_failed") {
+    console.log(
+      `\n  ✗ couldn't auto-merge ${candidateLabel(pr, changeId)} onto ${tenant}'s current preview with --strategy=${strategy}.`,
+    );
+    if (rr.unresolved.length) {
+      console.log("  These files changed on both sides and need your call:");
+      for (const f of rr.unresolved) console.log(`    - ${f}`);
+    }
+    console.log("  Re-run choosing which side wins on those files:");
+    console.log(`    ${cmd} --refresh --strategy=ours     keep your version`);
+    console.log(`    ${cmd} --refresh --strategy=theirs   take preview's version`);
+    console.log("  Nothing was integrated.");
+    return 1;
+  }
+  // Any other refusal (not_found / not_open / base_not_found / a capability guard /
+  // an unexpected error): surface the MCP's own message honestly — never dressed up.
+  console.error(
+    fail(
+      rr.message || `couldn't refresh ${candidateLabel(pr, changeId)} (${rr.status})`,
+      "check the candidate is open and that you have promote access for this store",
+    ),
+  );
+  return 1;
+}
+
+/**
+ * Decide + act on a NOT-mergeable candidate (the automate-first fork): without
+ * --refresh, print the one-click offer and stop (never a rebase); with --refresh,
+ * rebuild via `candidate_refresh` and, on success, hand back the (possibly new) PR
+ * handle so the caller integrates the rebuilt candidate. Returns
+ * `{ integrate:false, code }` to stop, or `{ integrate:true, pr, changeId }` to
+ * proceed.
+ */
+async function handleNotMergeable(
+  { tenant, pr, changeId, strategy, refresh, mcpUrl, identity, env },
+  deps,
+) {
+  if (!refresh) {
+    console.log(
+      `\n  ✗ ${candidateLabel(pr, changeId)} isn't mergeable into ${tenant}'s preview — the preview branch moved under it.`,
+    );
+    for (const line of notMergeableOfferLines(tenant, { pr, changeId })) console.log(line);
+    return { integrate: false, code: 1 };
+  }
+  if (!changeId) {
+    // candidate_refresh keys off the stable changeId; a bare PR number we couldn't
+    // resolve to one (not built yet / listing gap) can't be auto-rebuilt.
+    console.error(
+      fail(
+        `can't auto-refresh ${candidateLabel(pr, changeId)} — its change id isn't resolved yet`,
+        `check it's built (\`tot pr list --tenant ${tenant}\`), or pass --change-id`,
+      ),
+    );
+    return { integrate: false, code: 1 };
+  }
+  const rr = await runRefresh({ tenant, changeId, strategy, mcpUrl, identity, env }, deps);
+  if (!rr.ok) {
+    return { integrate: false, code: reportRefreshFailure(rr, { tenant, pr, changeId, strategy }) };
+  }
+  console.log(
+    `\n  ✓ rebuilt ${candidateLabel(rr.prNumber ?? pr, changeId)} on ${tenant}'s current preview (${rr.strategy ?? strategy}) — now mergeable.`,
+  );
+  if (rr.refreshedFiles.length) console.log(`  reapplied: ${rr.refreshedFiles.join(", ")}`);
+  // The rebuild opens a FRESH PR (prNumber may change; changeId is stable), so
+  // integrate by the new PR number + changeId and drop the now-stale head sha.
+  return { integrate: true, pr: rr.prNumber ?? pr, changeId };
+}
+
+/** POST `/api/changes/integrate` and normalise the outcome. Returns { res, result }. */
+async function postIntegrate({ base, authHeaders, body }, fetchImpl) {
+  const res = await fetchImpl(`${base}/api/changes/integrate`, {
+    method: "POST",
+    headers: { "content-type": "application/json", ...authHeaders },
+    body: JSON.stringify(body),
+  });
+  let data = {};
+  try {
+    data = await res.json();
+  } catch {
+    /* non-JSON / empty body */
+  }
+  return { res, result: normalizeIntegrateResponse(data) };
+}
+
+/** The integrate request body for a target. Pure. */
+function integrateBody({ tenant, pr, changeId, headSha }) {
+  return {
+    repo: tenant,
+    ...(pr != null ? { prNumber: pr } : {}),
+    ...(changeId ? { changeId } : {}),
+    ...(headSha ? { expectedHeadSha: headSha } : {}),
+  };
+}
+
+/**
+ * Render the terminal aggregate status in house style — the honest queue/run state,
+ * NEVER a bare "merged". Pure given its inputs; returns the process exit code.
+ * @param {ReturnType<typeof normalizeIntegrateResponse>} result
+ * @param {{ tenant:string, label:string }} ctx
+ * @returns {number}
+ */
+export function reportIntegrated(result, { tenant, label }) {
+  const state = `${result.queueState ?? "?"}/${result.runState ?? "—"}`;
+  if (result.ok) {
+    console.log(`\n  ✓ queued ${label} into ${tenant}'s preview aggregate — it is GREEN.`);
+    console.log(`  aggregate: ${state}${result.aggregateSha ? `  (${result.aggregateSha})` : ""}`);
+    if (result.pointerMoved) console.log("  the shared preview pointer moved to this aggregate.");
+    console.log("  → next: `tot ship` to promote this green aggregate live.");
+    return 0;
+  }
+  // Already integrated (candidate_not_open): the PR merged before this attempt —
+  // a SUCCESS the operator is re-hearing, not a failure. Never render the
+  // fix-and-retry template for it (live confusion, 2026-08-20: it told an
+  // operator to re-submit a change that had already landed). Exit 0 — the
+  // desired end state ("this change is in the aggregate") already holds.
+  if (result.reason === "candidate_not_open") {
+    console.log(`\n  ✓ ${label} was ALREADY integrated into ${tenant}'s preview aggregate — nothing left to accept.`);
+    console.log("  → next: `tot ship` to promote the aggregate live, or `tot revert` to pull the change back out.");
+    return 0;
+  }
+  // Honest non-green: the candidate did NOT land in the shippable aggregate.
+  console.log(`\n  ✗ ${label} did NOT integrate into ${tenant}'s preview aggregate.`);
+  console.log(`  aggregate: ${state}${result.reason ? `  (${result.reason})` : ""}`);
+  if (result.statusMessage) console.log(`  why: ${result.statusMessage}`);
+  console.log("  → next: fix the candidate (re-`tot preview`), then re-run `tot accept`.");
+  return 1;
+}
+
+/**
+ * The accept-means-integrate flow after args are parsed: state the exact plan,
+ * confirm, then POST `/api/changes/integrate` (operator-secret transport) and render
+ * the honest terminal aggregate status. `fetch`/`confirmPlan` injected so it is
+ * unit-tested with no network/TTY.
+ *
+ * @param {{ tenant:string, pr:number|null, changeId:string|null, headSha:string|null,
+ *   secret:string, storefrontUrl?:string|null, yes?:boolean, refresh?:boolean,
+ *   strategy?:string, mcpUrl?:string|null, identity?:string|null, env?:NodeJS.ProcessEnv }} params
+ * @param {{ fetch?:typeof fetch, confirmPlan?:typeof printPlanAndConfirm,
+ *   resolveViewerTransport?:typeof resolveViewerTransport }} [deps]
+ * @returns {Promise<number>} process exit code
+ */
+export async function runIntegrate(
+  {
+    tenant,
+    pr,
+    changeId,
+    headSha,
+    secret,
+    storefrontUrl = null,
+    yes = false,
+    refresh = false,
+    strategy = DEFAULT_REFRESH_STRATEGY,
+    mcpUrl = null,
+    identity = null,
+    env = process.env,
+  },
+  deps = {},
+) {
+  const fetchImpl = deps.fetch || globalThis.fetch;
+  const confirmPlan = deps.confirmPlan || printPlanAndConfirm;
+  const resolveViewer = deps.resolveViewerTransport || resolveViewerTransport;
+  let base = (storefrontUrl || DEFAULT_STOREFRONT_URL).trim().replace(/\/+$/, "");
+  const label = pr != null ? `PR #${pr}` : changeId;
+
+  // 1. State the EXACT plan (shared U10 affordance) — queue-integrate-into-preview,
+  //    NO merge, NO go-live — and gate on an explicit confirm.
+  const planLines = planForAction({ action: "accept", tenant, pr, changeId, headSha });
+  const { confirmed, reason } = await confirmPlan(planLines, {
+    yes,
+    question: refresh
+      ? `Queue ${label} for integration into ${tenant}'s preview aggregate (rebuilding it first if the preview moved)?`
+      : `Queue ${label} for integration into ${tenant}'s preview aggregate?`,
+  });
+  if (!confirmed) {
+    if (reason === "non-tty") {
+      console.error(
+        fail(
+          "refusing to integrate without confirmation on a non-TTY.",
+          "re-run with --yes (an explicit human affirmative), or from an interactive terminal.",
+        ),
+      );
+      return 2;
+    }
+    console.log("Aborted — nothing was integrated.");
+    return 1;
+  }
+
+  // 2. Resolve the transport. Two routes to the SAME `/api/changes/integrate`:
+  //    - OPERATOR SECRET (operators/CI): Bearer + X-Tot-Owner on the generic host.
+  //    - VIEWER SESSION (an invited developer, no secret): mint a `tot_session` from
+  //      their OWN `tot` login on the TENANT'S host and send it as a cookie. The
+  //      server authorizes on their live ship-on-behalf grant either way.
+  //    No `content-type` here: it's added per-POST; the mergeable preflight GET wants none.
+  let authHeaders;
+  if (secret) {
+    authHeaders = {
+      authorization: `Bearer ${secret}`,
+      "x-tot-owner": tenant,
+      "x-tot-capability": "ship-on-behalf",
+    };
+  } else {
+    const viewer = await resolveViewer({ tenant, env, fetchImpl });
+    if (!viewer.ok) {
+      console.error(fail(viewer.message, viewer.hint));
+      return 2;
+    }
+    base = viewer.base; // the tenant's own host — the dev-viewer admission is host-scoped
+    authHeaders = viewer.authHeaders;
+  }
+
+  // 2.5. MERGEABLE PREFLIGHT — read the candidate's forge verdict from b07's queue
+  //      (`GET /api/changes`, SAME transport) so a doomed accept never round-trips to
+  //      the forge. Best-effort: on any listing gap it's `known:false` → proceed as
+  //      normal. When it KNOWS the candidate isn't mergeable, take the automate-first
+  //      fork (offer/do --refresh) instead of a raw rebase.
+  let curPr = pr;
+  let curChangeId = changeId;
+  let curHead = headSha;
+  const verdict = await preflightMergeable({ base, authHeaders, pr, changeId }, fetchImpl);
+  if (verdict.mergeable === false) {
+    const handled = await handleNotMergeable(
+      {
+        tenant,
+        pr: verdict.prNumber ?? curPr,
+        changeId: verdict.changeId ?? curChangeId,
+        strategy,
+        refresh,
+        mcpUrl,
+        identity,
+        env,
+      },
+      deps,
+    );
+    if (!handled.integrate) return /** @type {number} */ (handled.code);
+    curPr = handled.pr ?? curPr;
+    curChangeId = handled.changeId ?? curChangeId;
+    curHead = null; // the rebuilt PR has a fresh head; let the server re-resolve.
+  }
+
+  // 3. POST the honest accept path (b07 queue enqueue) and render the terminal state.
+  let res;
+  let result;
+  try {
+    ({ res, result } = await postIntegrate(
+      { base, authHeaders, body: integrateBody({ tenant, pr: curPr, changeId: curChangeId, headSha: curHead }) },
+      fetchImpl,
+    ));
+  } catch (e) {
+    console.error(
+      fail(`couldn't reach the integration queue at ${base}: ${String(e?.message || e)}`, "check --url / your network, then re-run"),
+    );
+    return 1;
+  }
+
+  // A pre-flight error (auth, unknown tenant, candidate not found) is an HTTP 4xx
+  // with `{ error }` and no queue verdict — surface it distinctly from a red run.
+  if (!res.ok && result.queueState == null) {
+    return reportIntegrateHttpError(result, res, { tenant, label });
+  }
+
+  // 4. A not_mergeable outcome the preflight MISSED (listing gap / a race between
+  //    read and enqueue): take the same automate-first fork rather than the generic
+  //    "fix the candidate" copy. Guarded by `!verdict.known` so a candidate the
+  //    preflight already routed through --refresh can't loop here.
+  if (!result.ok && result.reason === "not_mergeable" && !verdict.known) {
+    const handled = await handleNotMergeable(
+      { tenant, pr: curPr, changeId: result.changeId ?? curChangeId, strategy, refresh, mcpUrl, identity, env },
+      deps,
+    );
+    if (!handled.integrate) return /** @type {number} */ (handled.code);
+    try {
+      ({ res, result } = await postIntegrate(
+        {
+          base,
+          authHeaders,
+          body: integrateBody({
+            tenant,
+            pr: handled.pr ?? curPr,
+            changeId: handled.changeId ?? curChangeId,
+            headSha: null,
+          }),
+        },
+        fetchImpl,
+      ));
+    } catch (e) {
+      console.error(
+        fail(`couldn't reach the integration queue at ${base}: ${String(e?.message || e)}`, "check --url / your network, then re-run"),
+      );
+      return 1;
+    }
+    if (!res.ok && result.queueState == null) {
+      return reportIntegrateHttpError(result, res, { tenant, label });
+    }
+  }
+
+  // A not_mergeable that survived a refresh attempt (or arrived with --refresh unset
+  // on the preflight-known path): the honest one-click offer, never a raw rebase.
+  if (!result.ok && result.reason === "not_mergeable") {
+    console.log(
+      `\n  ✗ ${label} still isn't mergeable into ${tenant}'s preview.`,
+    );
+    for (const line of notMergeableOfferLines(tenant, { pr: curPr, changeId: curChangeId })) {
+      console.log(line);
+    }
+    return 1;
+  }
+
+  return reportIntegrated(result, { tenant, label: /** @type {string} */ (label) });
+}
+
+/** The mergeable PREFLIGHT read (best-effort). See readCandidateVerdict. */
+async function preflightMergeable({ base, authHeaders, pr, changeId }, fetchImpl) {
+  try {
+    const res = await fetchImpl(`${base}/api/changes`, { method: "GET", headers: authHeaders });
+    if (!res || !res.ok) {
+      return { known: false, mergeable: null, changeId: changeId ?? null, prNumber: pr ?? null };
+    }
+    let data = {};
+    try {
+      data = await res.json();
+    } catch {
+      return { known: false, mergeable: null, changeId: changeId ?? null, prNumber: pr ?? null };
+    }
+    return readCandidateVerdict(data, { pr, changeId });
+  } catch {
+    return { known: false, mergeable: null, changeId: changeId ?? null, prNumber: pr ?? null };
+  }
+}
+
+/** Surface an integrate HTTP pre-flight error (4xx, no queue verdict). Returns exit 1. */
+function reportIntegrateHttpError(result, res, { tenant, label }) {
+  const msg = result.error || `HTTP ${res.status}`;
+  console.error(
+    fail(
+      `the integration queue refused the request: ${msg}`,
+      res.status === 401 || res.status === 403
+        ? "you need a live ship-on-behalf grant on this tenant (ask the store owner) — or an operator secret authorised for it"
+        : res.status === 404
+          ? `check that ${label} has a built candidate in ${tenant}'s queue (\`tot pr list --tenant ${tenant}\`)`
+          : "check --tenant / --url / --pr, then re-run",
+    ),
+  );
+  return 1;
+}
+
+/**
+ * @param {string[]} argv
+ * @param {any} ctx
+ */
+export async function run(argv, ctx) {
+  const env = process.env;
+  const args = parseAcceptArgs(argv);
+  if (args.help) {
+    console.log(USAGE);
+    return 0;
+  }
+
+  const tenant = (args.tenant || ctx?.tenant || "").trim();
+  if (!tenant) {
+    console.error(
+      fail(
+        "no target tenant.",
+        "pass --tenant <appDomain> (e.g. --tenant tokenoftrust.com), or run inside a store checkout.",
+      ),
+    );
+    return 2;
+  }
+
+  const prRaw = args.pr;
+  const pr =
+    prRaw != null && `${prRaw}`.trim() && Number.isFinite(Number(prRaw)) ? Number(prRaw) : null;
+  const changeId = (args.changeId || "").trim() || null;
+  if (pr == null && !changeId) {
+    console.error(
+      fail(
+        "no PR or change to integrate.",
+        "pass --pr <N> (the PR number to queue), or --change-id <id> to target a specific record.",
+      ),
+    );
+    return 2;
+  }
+
+  const headSha = (args.headSha || "").trim() || null;
+  const storefrontUrl =
+    args.url || env.TOT_STOREFRONT_URL || env.STOREFRONT_BASE_URL || DEFAULT_STOREFRONT_URL;
+
+  // --strategy only means something with --refresh; validate its value whenever given.
+  const strategy = (args.strategy || DEFAULT_REFRESH_STRATEGY).trim();
+  if (args.strategy != null && !REFRESH_STRATEGIES.includes(strategy)) {
+    console.error(
+      fail(
+        `unknown --strategy "${args.strategy}"`,
+        `use one of: ${REFRESH_STRATEGIES.join(", ")} (default "${DEFAULT_REFRESH_STRATEGY}")`,
+      ),
+    );
+    return 2;
+  }
+
+  return await runIntegrate({
+    tenant,
+    pr,
+    changeId,
+    headSha,
+    secret: resolveOperatorSecret(args.secret, env),
+    storefrontUrl,
+    yes: args.yes,
+    refresh: args.refresh,
+    strategy,
+    mcpUrl: args.mcp || env.MCP_BASE_URL || env.TOT_MCP_URL || DEFAULT_MCP_URL,
+    identity: args.identity || null,
+    env,
+  });
+}