@tokenoftrust/cli 1.4.0-rc.20 → 1.4.0-rc.22

package/src/commands/accept.mjs

@@ -39,8 +39,31 @@ 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";
+// C5 — the doctor PUSH: on a failed accept/integrate, auto-append the COMPACT
+// "here's what's blocking you" summary over the SAME transport we just used, so a
+// developer doesn't have to remember to run `tot preview doctor` themselves.
+import { autoSurfaceDoctor } from "../merge-doctor-report.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)
 
@@ -57,6 +80,11 @@ const USAGE = `tot accept — queue a PR's integration into the preview aggregat
   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.
@@ -65,7 +93,15 @@ Options:
   --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).
@@ -82,8 +118,11 @@ export function parseAcceptArgs(argv) {
     changeId: null,
     headSha: null,
     url: null,
+    mcp: null,
     secret: null,
     identity: null,
+    refresh: false,
+    strategy: null,
     yes: false,
     help: false,
   };
@@ -94,8 +133,11 @@ export function parseAcceptArgs(argv) {
     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;
   }
@@ -128,6 +170,255 @@ export function normalizeIntegrateResponse(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.
@@ -144,6 +435,16 @@ export function reportIntegrated(result, { tenant, label }) {
     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})` : ""}`);
@@ -159,17 +460,33 @@ export function reportIntegrated(result, { tenant, label }) {
  * 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]
+ *   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 },
+  {
+    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 base = (storefrontUrl || DEFAULT_STOREFRONT_URL).trim().replace(/\/+$/, "");
+  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,
@@ -177,7 +494,9 @@ export async function runIntegrate(
   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?`,
+    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") {
@@ -193,38 +512,75 @@ export async function runIntegrate(
     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 2;
+  // 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;
   }
-  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 } : {}),
+
+  // C5 — auto-surface the merge-doctor on a failed accept. Best-effort: fetches the
+  // hosted doctor over the SAME transport we just resolved and prints the COMPACT
+  // summary; never throws and never touches the exit code (it's called AFTER the
+  // outcome is decided, purely to append diagnostic context to where the failure
+  // already surfaced). A clean/unreachable doctor prints nothing.
+  const surfaceDoctor = async () => {
+    for (const line of await autoSurfaceDoctor({ base, authHeaders, fetchImpl })) console.error(line);
   };
 
+  // 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 = await fetchImpl(`${base}/api/changes/integrate`, {
-      method: "POST",
-      headers: authHeaders,
-      body: JSON.stringify(requestBody),
-    });
+    ({ 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"),
@@ -232,32 +588,98 @@ export async function runIntegrate(
     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 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);
+    }
+    await surfaceDoctor();
     return 1;
   }
 
-  return reportIntegrated(result, { tenant, label });
+  const code = reportIntegrated(result, { tenant, label: /** @type {string} */ (label) });
+  if (code !== 0) await surfaceDoctor();
+  return code;
+}
+
+/** 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;
 }
 
 /**
@@ -301,6 +723,18 @@ export async function run(argv, ctx) {
   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,
@@ -309,5 +743,10 @@ export async function run(argv, ctx) {
     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,
   });
 }

package/src/commands/app/dev.mjs

@@ -49,7 +49,10 @@ function randHex(bytes) {
   return Buffer.from(crypto.getRandomValues(new Uint8Array(bytes))).toString("hex");
 }
 
-/** Load or create the app's throwaway RS256 keypair at `<appDir>/.tot/dev-keys.json`. */
+/**
+ * Load or create the app's throwaway RS256 keypair at `<appDir>/.tot/dev-keys.json`.
+ * @param {string} appDir @param {{ kid?: string }} [opts]
+ */
 export async function ensureDevKeys(appDir, { kid } = {}) {
   const keysPath = join(appDir, ".tot", "dev-keys.json");
   const alg = { name: "RSASSA-PKCS1-v1_5", hash: "SHA-256" };
@@ -107,8 +110,9 @@ function runValidate(argv, { appDir }) {
     console.log(`✔ ${manifestPath} is a valid tot-app.json (contract v${result.manifest.contractVersion})`);
     return 0;
   }
-  console.log(`✖ ${manifestPath} — ${result.errors.length} error(s):`);
-  for (const e of result.errors) console.log(`  - ${e}`);
+  const errs = result.errors || [];
+  console.log(`✖ ${manifestPath} — ${errs.length} error(s):`);
+  for (const e of errs) console.log(`  - ${e}`);
   return 1;
 }