@tokenoftrust/cli 1.4.0-rc.14 → 1.4.0-rc.16

package/bin/tot.mjs

@@ -14,10 +14,13 @@
  *   tot validate              lint your store before you submit         ← built
  *   tot dev                   run your store locally with save→reload   ← built (monorepo: host astro; standalone: runs the published runner image)
  *   tot preview               push your store to a reviewable preview   ← built (validate + push preview ref; MCP preview_status read-back). `submit`/`deploy` are teaching aliases.
- *   tot ship                  promote a reconciled preview live         ← built (diff-vs-live + y/N confirm → change_accept; refuses non-TTY / unreconciled)
- *   tot accept / tot merge    merge a PR into main (operator verb)      ← built (plan + y/N confirm → the SAME change_accept ship uses; no deploy; refuses non-TTY without --yes)
+ *   tot ship                  publish the current green aggregate live  ← built (GET/POST /api/changes/ship → b09 orchestrator; exact plan + y/N confirm; waits for VERIFIED live truth)
+ *   tot accept / tot merge    queue a PR into the preview aggregate      ← built (b08: plan + y/N confirm → POST /api/changes/integrate = b07 queue enqueue; NO merge-to-main, NO go-live; refuses non-TTY without --yes)
+ *   tot sync                  fetch `preview` + merge it into your branch ← built (b16: the common accept-conflict recovery path; local-only, stops safely on conflict)
  *   tot rollback [<version>]  instant re-point to a prior live version  ← built (u3 promotion_status/promotion_rollback seam; diff + y/N confirm; refuses non-TTY / ineligible)
  *   tot pr                    list / view / close your candidate PRs    ← built (candidate_status/candidate_close; gh-pr-shaped)
+ *   tot branches              full branch-cleanup report (every branch, not just open PRs)  ← built (b14: candidate_list)
+ *   tot cleanup               owner-confirmed branch GC (deletes terminal branches only)     ← built (b14: candidate_list + candidate_delete; --dry-run classifies only)
  *   tot doctor                check this machine is ready
  *   tot ideas                 copy-paste AI prompts that reliably wow
  *   tot feedback              send a note to ToT + your recent CLI activity  ← built (activity-log.mjs → feedback_submit MCP tool)
@@ -64,12 +67,17 @@ tot — Token of Trust developer CLI
   tot validate              lint your store before you submit
   tot dev                   run your store locally with save→reload
   tot preview               push your store to a reviewable preview
-  tot ship                  promote a reconciled preview live (diff → confirm → ship)
-  tot accept / tot merge    merge a PR into main — operator verb, no deploy (plan → confirm → merge)
+  tot ship                  publish the tenant's current green aggregate live (plan → confirm → ship)
+  tot accept / tot merge    queue a PR into the preview aggregate — operator verb, no go-live (plan → confirm → integrate)
+  tot sync                  fetch \`preview\` and merge it into your local branch (accept-conflict recovery)
   tot rollback [<version>]  instant re-point to a prior live version (list → confirm → rollback)
+  tot revert --preview <PR|sha>  remove already-integrated content from the preview aggregate via a new revert commit — no force-reset (plan → confirm → revert)
+  tot hotfix --pr <N>       OWNER-ONLY exception: release an urgent fix from main to live, bypassing unshipped preview work (plan → confirm → release → auto forward-integrate)
   tot retire                evict a candidate PR's preview to reclaim space — operator verb, rebuildable (plan → confirm → evict)
   tot go-live               cut the apex domain over to the storefront (readiness → confirm → cutover)
   tot pr                    list / view / close your candidate PRs
+  tot branches              full branch-cleanup report — every branch, any PR state, cleanup eligibility
+  tot cleanup               owner-confirmed branch GC (--dry-run to classify only; deletes terminal branches only)
   tot doctor                check this machine is ready
   tot ideas                 copy-paste AI prompts that reliably wow
   tot feedback "<msg>"      send feedback to Token of Trust (attaches recent activity)
@@ -174,20 +182,52 @@ async function dispatch(cmd, rest, ctx) {
     return run(rest, ctx);
   }
 
-  // `accept` merges a PR into main (no deploy) — a DISTINCT operator verb from
-  // `ship`, backed by the SAME change_accept pipeline (see accept.mjs's header).
-  // `merge` is a first-class alias, not a teaching nudge: both dispatch straight
-  // to the same command.
+  // `accept` queue-integrates a PR into the protected `preview` aggregate (b08) —
+  // NO merge-to-main, NO go-live; going live is `tot ship`, which publishes the
+  // whole current GREEN AGGREGATE (b10). Backed by POST /api/changes/integrate
+  // (b07's TenantIntegrationQueue.enqueue); see accept.mjs's header. `merge` is a
+  // first-class alias, not a teaching nudge: both dispatch straight to the same command.
   if (cmd === "accept" || cmd === "merge") {
     const { run } = await import("../src/commands/accept.mjs");
     return run(rest, ctx);
   }
 
+  // `sync` is the common accept-conflict recovery path (P1 item 12): fetches the
+  // protected `preview` branch and merges it into the developer's local branch so
+  // they can resolve locally, then re-`tot preview`. Purely local — no push, no
+  // MCP call, never touches the shared `preview`/`main` refs themselves. See
+  // sync.mjs's header for the full contract.
+  if (cmd === "sync") {
+    const { run } = await import("../src/commands/sync.mjs");
+    return run(rest, ctx);
+  }
+
   if (cmd === "rollback") {
     const { run } = await import("../src/commands/rollback.mjs");
     return run(rest, ctx);
   }
 
+  // `revert --preview <PR|integration-sha>` removes already-integrated content from
+  // the protected `preview` aggregate via a NEW auditable revert commit (b21) — NO
+  // force-reset, NO touch to main/live. Backed by POST /api/changes/revert (b07's
+  // TenantIntegrationQueue.enqueueRevert). To undo something already LIVE, that's
+  // `tot rollback`, not this. See revert.mjs's header.
+  if (cmd === "revert") {
+    const { run } = await import("../src/commands/revert.mjs");
+    return run(rest, ctx);
+  }
+
+  // `hotfix --pr <N>` is the OWNER-ONLY EXCEPTION lane (b22): release an urgent fix
+  // from `main` to live while `preview` still holds other unshipped work, EXCLUDING
+  // that unshipped preview head, then automatically forward-integrate main → preview
+  // and re-validate. It is DELIBERATELY a distinct verb — never a `--base main` flag
+  // on `tot ship` (which publishes the whole green preview aggregate). Backed by
+  // GET/POST /api/changes/hotfix → b22's HotfixOrchestrator. See hotfix.mjs's header.
+  if (cmd === "hotfix") {
+    const { run } = await import("../src/commands/hotfix.mjs");
+    return run(rest, ctx);
+  }
+
   // `retire` evicts a candidate PR's hosted preview to reclaim space (unit U7) —
   // a DISTINCT operator verb from `accept`/reject: retire touches no change
   // lifecycle and is reversible-by-rebuild (`tot preview build`). See retire.mjs.
@@ -206,6 +246,24 @@ async function dispatch(cmd, rest, ctx) {
     return run(rest, ctx);
   }
 
+  // `branches` is the FULL branch-cleanup report (every branch, any PR state) —
+  // distinct from `tot pr list`, which only shows OPEN PRs (P1 item 9). Read-only;
+  // always safe to run, and the report `tot cleanup` reuses before deleting anything.
+  if (cmd === "branches") {
+    const { run } = await import("../src/commands/branches.mjs");
+    return run(rest, ctx);
+  }
+
+  // `cleanup` is owner-confirmed BRANCH GC (P1 items 9/10) — an irreversible git-ref
+  // delete, distinct from `tot retire`'s hosted-preview eviction (rebuildable, no
+  // branch touched). `--dry-run` classifies and prints; it never deletes. Age alone
+  // never makes a branch eligible; main/preview are always kept; orphans are
+  // quarantined, never auto-deleted. See cleanup.mjs's header.
+  if (cmd === "cleanup") {
+    const { run } = await import("../src/commands/cleanup.mjs");
+    return run(rest, ctx);
+  }
+
   if (cmd === "app") {
     const { run } = await import("../src/commands/app/index.mjs");
     return run(rest, ctx);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@tokenoftrust/cli",
-  "version": "1.4.0-rc.14",
+  "version": "1.4.0-rc.16",
   "description": "Token of Trust developer CLI — clone a tenant store, run it locally with save→reload, and submit it for preview. Installs the `tot` command.",
   "license": "Apache-2.0",
   "author": "Token of Trust",

package/src/commands/accept.mjs

@@ -1,84 +1,78 @@
 /**
- * `tot accept --tenant <t> --pr <N>` (alias: `tot merge`) — OPERATOR verb: MERGE
- * a PR into main. DISTINCT from `tot ship`: per board decision
- * `operator-verb-and-hosting-model`, accepting a PR merges it into main; main
- * becomes default-hosted on preview + live only after the NEXT `tot ship` /
- * deploy — accept itself does not deploy. (`tot ship` run by the developer in
- * their own checkout stays accept-THEN-deploy in one gated step — see
- * `ship-context-dependent-semantics` in `../plan.mjs`; this verb is the
- * explicit, deploy-free half of that, for an operator who just wants the merge.)
+ * `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.
  *
- * TRANSPORT — reuses the EXISTING accept pipeline `tot ship` already drives over
- * MCP (merge → reconcile → promote → verify): the SAME `change_accept` tool,
- * the SAME session/auth pattern (`createMcpClient` + `establishSession`), and
- * the SAME result normaliser/poll (`normalizeChangeResult` / `pollChangeShipped`,
- * imported straight from `./ship.mjs` rather than re-implemented). No new
- * transport, no new wire contract.
+ * 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, but there is no
- * PR→change-record lookup on the wire, and even if there were, this CLI's own
- * identity may not have cross-tenant forge read access to resolve one for a PR
- * that isn't the developer's own (`resolveChangeRecordId` in ship.mjs only works
- * because it reads the DEVELOPER'S OWN local git HEAD — an operator targeting an
- * arbitrary PR has no local checkout of it to read). So this verb requires the
- * change-RECORD id explicitly via `--change-id` (the `chg_<uuid>` a prior
- * change_open/change_ready minted — e.g. from the PR author's own `tot ship`
- * review step, or the `/admin` confirm flow) and an optional `--head-sha`
- * (passed through as `expectedHeadSha` — an optimistic-concurrency guard so
- * accept refuses if the PR moved since the operator looked at it).
+ * 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.
  *
- *   // u9: auto-resolve PR→changeId via forge PR-read (candidate_status), so an
- *   // operator who DOES have forge access can omit --change-id and pass --pr
- *   // alone. Not implemented here — deliberately out of scope for this unit.
+ * 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 — merging to main is a decision a human makes at the keyboard, so
- * this verb ALWAYS states the EXACT plan (shared `planForAction`, unit U10:
- * which PR, which tenant, "merge into main", plus a note that live/preview
- * don't move until the next ship/deploy) and requires an explicit confirm.
- * `--yes` is still an explicit affirmative supplied on the command line — there
- * is deliberately NO default-yes, and a non-TTY without `--yes` is refused
- * rather than silently proceeding (mirrors `tot ship`'s non-TTY refusal).
+ * 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 (the MCP client + the shared plan module).
+ * Dependency-free (global fetch + the shared plan module).
  */
-import { createMcpClient } from "../mcp.mjs";
-import { establishSession, AuthUnavailableError } from "../auth.mjs";
 import { fail } from "../errors.mjs";
 import { planForAction, printPlanAndConfirm } from "../plan.mjs";
-import { normalizeChangeResult, pollChangeShipped } from "./ship.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";
 
-const DEFAULT_MCP_URL = "https://mcp.tokenoftrust.com";
+const DEFAULT_STOREFRONT_URL = "https://storefront.tokenoftrust.store";
 
-const USAGE = `tot accept — merge a PR into main (alias: tot merge)
+const USAGE = `tot accept — queue a PR's integration into the preview aggregate (alias: tot merge)
 
-  tot accept --tenant <t> --pr <N> --change-id <chg_...>
-  tot merge   --tenant <t> --pr <N> --change-id <chg_...>   (same command)
+  tot accept --tenant <t> --pr <N>
+  tot merge   --tenant <t> --pr <N>   (same command)
 
-  Merges the given PR into main via the existing accept pipeline (merge →
-  reconcile → promote → verify) — the SAME gate \`tot ship\` uses. Distinct
-  from \`tot ship\`: accepting does NOT deploy. Main becomes default-hosted on
-  preview + live only after the next \`tot ship\` / deploy.
+  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\`.
 
-  Merge-to-main 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.
+  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.
 
 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 merge (for the plan text / labeling).
-  --change-id <id>       The change-record id (chg_...) to accept. REQUIRED —
-                         there is no PR→changeId auto-resolution yet (u9); pass
-                         the id a prior change_open/change_ready minted (e.g.
-                         from the author's own \`tot ship\` review step, or the
-                         /admin confirm flow).
+  --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.
-  --mcp <url>            MCP base URL (default: env MCP_BASE_URL / TOT_MCP_URL)
-  --identity <id>        sign in as a specific identity for this accept
+  --url <origin>         storefront origin (default: env TOT_STOREFRONT_URL)
+  --secret <s>           operator secret (prefer the env vars below)
   --yes, -y              Skip the interactive confirm (still an explicit human
                          affirmative — there is no default-yes).
-  --help, -h             Show this help.`;
+  --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) {
@@ -87,7 +81,8 @@ export function parseAcceptArgs(argv) {
     pr: null,
     changeId: null,
     headSha: null,
-    mcp: null,
+    url: null,
+    secret: null,
     identity: null,
     yes: false,
     help: false,
@@ -98,7 +93,8 @@ export function parseAcceptArgs(argv) {
     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 === "--mcp") a.mcp = argv[++i];
+    else if (t === "--url") a.url = argv[++i];
+    else if (t === "--secret") a.secret = argv[++i];
     else if (t === "--identity") a.identity = argv[++i];
     else if (t === "--yes" || t === "-y") a.yes = true;
     else if (t === "--help" || t === "-h") a.help = true;
@@ -106,22 +102,162 @@ export function parseAcceptArgs(argv) {
   return a;
 }
 
-/** Report the accept result in house style. Pure given its inputs. */
-function reportAccepted(accept, status, { tenant, pr, changeId }) {
+/**
+ * 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,
+  };
+}
+
+/**
+ * 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;
+  }
+  // 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 }} params
+ * @param {{ fetch?:typeof fetch, confirmPlan?:typeof printPlanAndConfirm }} [deps]
+ * @returns {Promise<number>} process exit code
+ */
+export async function runIntegrate(
+  { tenant, pr, changeId, headSha, secret, storefrontUrl = null, yes = false },
+  deps = {},
+) {
+  const fetchImpl = deps.fetch || globalThis.fetch;
+  const confirmPlan = deps.confirmPlan || printPlanAndConfirm;
+  const base = (storefrontUrl || DEFAULT_STOREFRONT_URL).trim().replace(/\/+$/, "");
   const label = pr != null ? `PR #${pr}` : changeId;
-  const merged = Boolean(status?.shipped || accept?.shipped);
-  if (merged) {
-    console.log(`\n  ✓ merged ${label} into main for ${tenant}.`);
-    console.log(
-      "  → next: `tot ship` (or an operator `tot ship`/deploy) to promote main to preview + live.",
+
+  // 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: `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. Operator-secret transport — the CLI holds no storefront cookie, so the
+  //    Bearer + X-Tot-Owner path is its route (same as `tot ship --pr`).
+  if (!secret) {
+    console.error(
+      fail(
+        "integrating a PR is an OPERATOR action — it needs an operator secret",
+        "set PREVIEW_RECONCILE_SECRET (or GRANTS_ADMIN_SECRET / TOT_OPERATOR_SECRET), or pass --secret",
+      ),
     );
-    return 0;
+    return 2;
   }
-  // The accept committed but the terminal state hasn't been observed yet (the
-  // pipeline may still be landing reconcile/promote/verify) — report honestly.
-  console.log(`\n  ~ accept committed for ${label} on ${tenant}; the merge is landing now.`);
-  console.log("  → next: re-check shortly, then `tot ship` / deploy to go live.");
-  return 0;
+  const authHeaders = {
+    "content-type": "application/json",
+    authorization: `Bearer ${secret}`,
+    "x-tot-owner": tenant,
+    "x-tot-capability": "ship-on-behalf",
+  };
+  const requestBody = {
+    repo: tenant,
+    ...(pr != null ? { prNumber: pr } : {}),
+    ...(changeId ? { changeId } : {}),
+    ...(headSha ? { expectedHeadSha: headSha } : {}),
+  };
+
+  // 3. POST the honest accept path (b07 queue enqueue) and render the terminal state.
+  let res;
+  try {
+    res = await fetchImpl(`${base}/api/changes/integrate`, {
+      method: "POST",
+      headers: authHeaders,
+      body: JSON.stringify(requestBody),
+    });
+  } 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;
+  }
+
+  let data = {};
+  try {
+    data = await res.json();
+  } catch {
+    /* non-JSON / empty body */
+  }
+  const result = normalizeIntegrateResponse(data);
+
+  // 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) {
+    const msg = result.error || `HTTP ${res.status}`;
+    console.error(
+      fail(
+        `the integration queue refused the request: ${msg}`,
+        res.status === 401 || res.status === 403
+          ? "check the operator secret and that it's authorised for this tenant"
+          : 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;
+  }
+
+  return reportIntegrated(result, { tenant, label });
 }
 
 /**
@@ -148,100 +284,30 @@ export async function run(argv, ctx) {
   }
 
   const prRaw = args.pr;
-  const pr = prRaw != null && `${prRaw}`.trim() && Number.isFinite(Number(prRaw)) ? Number(prRaw) : null;
-  if (pr == null && !args.changeId) {
-    console.error(
-      fail("no PR or change to accept.", "pass --pr <N> (the PR number to merge) and --change-id <chg_...>."),
-    );
-    return 2;
-  }
-
-  const changeId = (args.changeId || "").trim();
-  if (!changeId) {
-    // u9: auto-resolve PR→changeId via forge PR-read (candidate_status) — until
-    // then an operator targeting a specific PR must supply the change-record id
-    // directly (there's no cross-tenant forge lookup this CLI can do for a PR
-    // that isn't the caller's own checkout).
+  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 --change-id for PR #${pr} — can't auto-resolve it yet.`,
-        "pass --change-id <chg_...> (the change record a prior review step opened/readied), " +
-          "or run `tot ship` from the PR author's own checkout instead.",
+        "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;
 
-  // Self-declaring: state the EXACT plan before acting (the shared plan module,
-  // unit U10) plus the accept-specific caveat that main doesn't go live/preview
-  // until the next ship/deploy.
-  const planLines = [
-    ...planForAction({ action: "accept", tenant, pr, changeId, headSha }),
-    "  note:      main becomes default-hosted on preview + live only after the next `tot ship` / deploy.",
-  ];
-  const { confirmed, reason } = await printPlanAndConfirm(planLines, {
+  return await runIntegrate({
+    tenant,
+    pr,
+    changeId,
+    headSha,
+    secret: resolveOperatorSecret(args.secret, env),
+    storefrontUrl,
     yes: args.yes,
-    question: "Merge this into main?",
   });
-  if (!confirmed) {
-    if (reason === "non-tty") {
-      console.error(
-        fail(
-          "refusing to merge 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 merged.");
-    return 1;
-  }
-
-  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 });
-    // Bind the active tenant so change_accept/change_status read the right scope.
-    await client.callTool("client_switch", { tenant });
-
-    let accept;
-    try {
-      accept = normalizeChangeResult(
-        await client.callTool("change_accept", {
-          id: changeId,
-          tenant,
-          dryRun: false,
-          ...(headSha ? { expectedHeadSha: headSha } : {}),
-          // Stable per (changeId, head): a re-run after a blip returns the
-          // original accept instead of double-merging.
-          idempotencyKey: `accept-${changeId}-${headSha || pr || "pr"}`,
-        }),
-      );
-    } catch (e) {
-      console.error(
-        fail(
-          `the accept pipeline refused to merge this change: ${String(e?.message || e)}`,
-          "check its review/reconcile status, then re-run `tot accept`",
-        ),
-      );
-      return 1;
-    }
-
-    const status = await pollChangeShipped(client, { id: changeId, tenant });
-    return reportAccepted(accept, status, { tenant, pr, changeId });
-  } catch (e) {
-    if (e instanceof AuthUnavailableError) {
-      console.error(fail("sign in to accept a change", e.hint || "run `tot login`, then re-run `tot accept`"));
-      return 1;
-    }
-    console.error(
-      fail(
-        `couldn't reach the accept service: ${String(e?.message || e)}`,
-        "check your connection and that you're signed in, then re-run",
-      ),
-    );
-    return 1;
-  }
 }