@tokenoftrust/cli 2.3.0 → 2.4.1

package/bin/tot.mjs

@@ -61,6 +61,7 @@ const COMMANDS = [
   { invocation: "report go-live --pages <dir>", blurb: "your store's go-live readiness report, from its page-check results" },
   { invocation: "dev", blurb: "run your store locally with save→reload" },
   { invocation: "preview", blurb: "push your store to a reviewable preview" },
+  { invocation: "status", blurb: "the pipeline verdict for your active tenant — progressing / stuck / idle, and why" },
   { invocation: "ship", blurb: "publish the tenant's current green aggregate live (plan → confirm → ship)" },
   { invocation: "accept / tot merge", blurb: "queue a PR into the preview aggregate — operator verb, no go-live (plan → confirm → integrate)" },
   { invocation: "sync", blurb: "fetch `preview` and merge it into your local branch (accept-conflict recovery)" },
@@ -201,6 +202,11 @@ async function dispatch(cmd, rest, ctx) {
     return run(rest, ctx);
   }
 
+  if (cmd === "status") {
+    const { run } = await import("../src/commands/status.mjs");
+    return run(rest, ctx);
+  }
+
   if (cmd === "submit" || cmd === "deploy") {
     const { run } = await import("../src/commands/preview.mjs");
     return run(rest, ctx, { alias: cmd });
@@ -213,8 +219,8 @@ async function dispatch(cmd, rest, ctx) {
 
   // `accept` queue-integrates a PR into the protected `preview` aggregate —
   // NO merge-to-main, NO go-live; going live is `tot ship`, which publishes the
-  // whole current GREEN AGGREGATE. Backed by POST /api/changes/integrate
-  // (TenantIntegrationQueue.enqueue); see accept.mjs's header. `merge` is a
+  // whole current GREEN AGGREGATE. Backed by POST /api/changes/integrate (an
+  // `integrate` job in the store's pipeline); 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");
@@ -239,8 +245,8 @@ async function dispatch(cmd, rest, ctx) {
   // `revert --preview <PR|change-id>` undoes an already-integrated PR out of the
   // protected `preview` aggregate by opening a NEW corrective candidate and
   // merging it through the SAME accept pipeline — NO force-reset, NO touch to
-  // main/live. Backed by POST /api/changes/revert (TenantIntegrationQueue.enqueue,
-  // the same pipeline `tot accept` drives). To undo something already LIVE,
+  // main/live. Backed by POST /api/changes/revert (a `revert` job in the store's
+  // pipeline, the same steps `tot accept` runs). 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");

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@tokenoftrust/cli",
-  "version": "2.3.0",
+  "version": "2.4.1",
   "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

@@ -18,13 +18,13 @@
  * chg-id). An explicit `--change-id` is still accepted (targets a specific record),
  * but is no longer REQUIRED — a PR number alone is enough.
  *
- * TRANSPORT — the honest accept path is `POST /api/changes/integrate` (the ONE call
- * site of `TenantIntegrationQueue.enqueue`). Like `tot ship --pr` and
- * `tot pr list --tenant`, 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".
+ * TRANSPORT — the honest accept path is `POST /api/changes/integrate`. Like `tot ship --pr`
+ * and `tot pr list --tenant`, 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 route submits an `integrate` job to the store's pipeline and answers
+ * `202 {jobId}`; this verb waits on `GET /api/pipeline/jobs/<jobId>` for the job's outcome —
+ * `jobState` / `runState` / `pointerMoved` / `aggregateSha` / `statusMessage` — and renders it
+ * VERBATIM, never a bare "merged". The job runs on the platform whether or not this waits.
  *
  * HUMAN GATE — integrating into the shared preview is a decision a human makes, so
  * this ALWAYS states the EXACT plan (shared `planForAction`: which PR,
@@ -53,6 +53,7 @@ import { resolveViewerTransport } from "../viewer-session.mjs";
 // "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";
+import { isJobAccepted, waitForPipelineJob } from "../pipeline-job.mjs";
 
 const DEFAULT_STOREFRONT_URL = "https://storefront.tokenoftrust.store";
 const DEFAULT_MCP_URL = "https://mcp.tokenoftrust.com";
@@ -150,7 +151,7 @@ export function parseAcceptArgs(argv) {
  * 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,
+ * @returns {{ ok:boolean, pending:boolean, jobId:string|null, jobState: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 }}
  */
@@ -158,7 +159,9 @@ export function normalizeIntegrateResponse(data) {
   const o = data && typeof data === "object" ? data : {};
   return {
     ok: o.ok === true,
-    queueState: typeof o.queueState === "string" ? o.queueState : null,
+    pending: o.pending === true,
+    jobId: typeof o.jobId === "string" ? o.jobId : null,
+    jobState: typeof o.jobState === "string" ? o.jobState : null,
     runState: typeof o.runState === "string" ? o.runState : null,
     pointerMoved: o.pointerMoved === true,
     aggregateSha: typeof o.aggregateSha === "string" ? o.aggregateSha : null,
@@ -388,8 +391,11 @@ async function handleNotMergeable(
   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) {
+/**
+ * POST `/api/changes/integrate`, wait on the job it submitted, and normalise the outcome.
+ * Returns { res, result } — `res.ok` is the submit's transport verdict.
+ */
+async function postIntegrate({ base, authHeaders, body }, fetchImpl, waitOpts = {}) {
   const res = await fetchImpl(`${base}/api/changes/integrate`, {
     method: "POST",
     headers: { "content-type": "application/json", ...authHeaders },
@@ -401,6 +407,11 @@ async function postIntegrate({ base, authHeaders, body }, fetchImpl) {
   } catch {
     /* non-JSON / empty body */
   }
+  if (isJobAccepted(res, data)) {
+    console.log(`  submitted as job ${data.jobId} — waiting for it to finish (it continues on the platform if you stop waiting)…`);
+    const { outcome } = await waitForPipelineJob({ base, authHeaders, jobId: data.jobId }, fetchImpl, waitOpts);
+    return { res, result: normalizeIntegrateResponse({ ...outcome, jobId: data.jobId }) };
+  }
   return { res, result: normalizeIntegrateResponse(data) };
 }
 
@@ -422,7 +433,13 @@ function integrateBody({ tenant, pr, changeId, headSha }) {
  * @returns {number}
  */
 export function reportIntegrated(result, { tenant, label }) {
-  const state = `${result.queueState ?? "?"}/${result.runState ?? "—"}`;
+  const state = `${result.jobState ?? "?"}/${result.runState ?? "—"}`;
+  if (result.pending) {
+    console.log(`\n  … ${label} is still being added to ${tenant}'s preview aggregate — it finishes on the platform.`);
+    if (result.jobId) console.log(`  job: ${result.jobId}`);
+    console.log("  → next: re-check the queue (`tot pr list --tenant " + tenant + "`) in a few minutes.");
+    return 0;
+  }
   if (result.ok) {
     console.log(`\n  ✓ queued ${label} into ${tenant}'s preview aggregate — it is GREEN.`);
     console.log(`  aggregate: ${state}${result.aggregateSha ? `  (${result.aggregateSha})` : ""}`);
@@ -458,7 +475,8 @@ export function reportIntegrated(result, { tenant, label }) {
  *   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]
+ *   resolveViewerTransport?:typeof resolveViewerTransport,
+ *   wait?:Parameters<typeof waitForPipelineJob>[2] }} [deps]
  * @returns {Promise<number>} process exit code
  */
 export async function runIntegrate(
@@ -575,6 +593,7 @@ export async function runIntegrate(
     ({ res, result } = await postIntegrate(
       { base, authHeaders, body: integrateBody({ tenant, pr: curPr, changeId: curChangeId, headSha: curHead }) },
       fetchImpl,
+      deps.wait,
     ));
   } catch (e) {
     console.error(
@@ -585,7 +604,7 @@ export async function runIntegrate(
 
   // 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) {
+  if (!res.ok) {
     return reportIntegrateHttpError(result, res, { tenant, label });
   }
 
@@ -612,6 +631,7 @@ export async function runIntegrate(
           }),
         },
         fetchImpl,
+        deps.wait,
       ));
     } catch (e) {
       console.error(
@@ -619,7 +639,7 @@ export async function runIntegrate(
       );
       return 1;
     }
-    if (!res.ok && result.queueState == null) {
+    if (!res.ok) {
       return reportIntegrateHttpError(result, res, { tenant, label });
     }
   }

package/src/commands/revert.mjs

@@ -22,15 +22,14 @@
  * anything — when there's nothing TO undo (never integrated, no longer part of
  * the current aggregate, or already undone).
  *
- * TRANSPORT — `POST /api/changes/revert` (opens the corrective candidate, then
- * runs it through the SAME `TenantIntegrationQueue.enqueue` accept pipeline
- * `tot accept` drives). Like `tot accept`, the CLI reaches it with either the
- * operator-secret Bearer transport (`resolveOperatorSecret` + `X-Tot-Owner` +
- * `x-tot-capability`) or a signed-in developer's viewer session when they hold
- * a live `ship-on-behalf` grant. The response is the honest terminal aggregate
- * state — `queueState` / `runState` / `pointerMoved` / `aggregateSha` /
- * `changeId` (the corrective candidate's own id) / `statusMessage` — rendered
- * VERBATIM, never a bare "reverted".
+ * TRANSPORT — `POST /api/changes/revert` submits a `revert` job to the store's pipeline (open
+ * the corrective candidate, then merge → build → evidence → advance the preview, exactly as
+ * `tot accept`) and answers `202 {jobId}`; this verb waits on `GET /api/pipeline/jobs/<jobId>`.
+ * Like `tot accept`, the CLI reaches it with either the operator-secret Bearer transport
+ * (`resolveOperatorSecret` + `X-Tot-Owner` + `x-tot-capability`) or a signed-in developer's
+ * viewer session when they hold a live `ship-on-behalf` grant. The outcome — `jobState` /
+ * `runState` / `pointerMoved` / `aggregateSha` / `changeId` (the corrective candidate's own id) /
+ * `statusMessage` — is rendered VERBATIM, never a bare "reverted".
  *
  * HUMAN GATE — correcting the shared preview is a decision a human makes, so
  * this ALWAYS states the EXACT plan (a NEW corrective candidate, merged through
@@ -48,6 +47,7 @@ import { resolveOperatorSecret } from "./ship.mjs";
 // No-operator-secret path: mint a viewer session from the developer's OWN `tot`
 // login. The server still gates the request on their live ship-on-behalf grant.
 import { resolveViewerTransport } from "../viewer-session.mjs";
+import { isJobAccepted, waitForPipelineJob } from "../pipeline-job.mjs";
 
 const DEFAULT_STOREFRONT_URL = "https://storefront.tokenoftrust.store";
 
@@ -163,7 +163,9 @@ export function normalizeRevertResponse(data) {
   const o = data && typeof data === "object" ? data : {};
   return {
     ok: o.ok === true,
-    queueState: typeof o.queueState === "string" ? o.queueState : null,
+    pending: o.pending === true,
+    jobId: typeof o.jobId === "string" ? o.jobId : null,
+    jobState: typeof o.jobState === "string" ? o.jobState : null,
     runState: typeof o.runState === "string" ? o.runState : null,
     pointerMoved: o.pointerMoved === true,
     aggregateSha: typeof o.aggregateSha === "string" ? o.aggregateSha : null,
@@ -184,7 +186,12 @@ export function normalizeRevertResponse(data) {
  * @returns {number}
  */
 export function reportReverted(result, { tenant, label }) {
-  const state = `${result.queueState ?? "?"}/${result.runState ?? "—"}`;
+  const state = `${result.jobState ?? "?"}/${result.runState ?? "—"}`;
+  if (result.pending) {
+    console.log(`\n  … undoing ${label} in ${tenant}'s preview aggregate is still running — it finishes on the platform.`);
+    if (result.jobId) console.log(`  job: ${result.jobId}`);
+    return 0;
+  }
   if (result.ok) {
     console.log(`\n  ✓ undid ${label} in ${tenant}'s preview aggregate — it is GREEN.`);
     console.log(`  aggregate: ${state}${result.aggregateSha ? `  (${result.aggregateSha})` : ""}`);
@@ -227,7 +234,8 @@ export function reportReverted(result, { tenant, label }) {
  *   message:string|null, secret:string, storefrontUrl?:string|null, yes?:boolean,
  *   env?:NodeJS.ProcessEnv }} params
  * @param {{ fetch?:typeof fetch, confirmPlan?:typeof printPlanAndConfirm,
- *   resolveViewerTransport?:typeof resolveViewerTransport }} [deps]
+ *   resolveViewerTransport?:typeof resolveViewerTransport,
+ *   wait?:Parameters<typeof waitForPipelineJob>[2] }} [deps]
  * @returns {Promise<number>} process exit code
  */
 export async function runRevert(
@@ -314,11 +322,16 @@ export async function runRevert(
   } catch {
     /* non-JSON / empty body */
   }
+  if (isJobAccepted(res, data)) {
+    console.log(`  submitted as job ${data.jobId} — waiting for it to finish (it continues on the platform if you stop waiting)…`);
+    const { outcome } = await waitForPipelineJob({ base, authHeaders, jobId: data.jobId }, fetchImpl, deps.wait);
+    data = { ...outcome, jobId: data.jobId };
+  }
   const result = normalizeRevertResponse(data);
 
   // A pre-flight error (auth, unknown tenant, bad body) is an HTTP 4xx with
-  // `{ error }` and no queue verdict — surface it distinctly from a red run.
-  if (!res.ok && result.queueState == null) {
+  // `{ error }` and no job outcome — surface it distinctly from a red run.
+  if (!res.ok) {
     const msg = result.error || `HTTP ${res.status}`;
     console.error(
       fail(

package/src/commands/status.mjs

@@ -0,0 +1,109 @@
+/**
+ * `tot status` — the pipeline verdict for your active tenant (migration DAG §U4):
+ * the SAME `kind`/`reason`/`nextAction` the Publish console and `tot preview`/`tot
+ * submit` print, available on its own without pushing anything. Reads
+ * `store_status` (tenant/repo-scoped, zero live Gitea calls) and prints its
+ * `verdict` field — pipeline state comes from there, never re-derived here.
+ *
+ * Dependency-free (global fetch via mcp.mjs's client).
+ */
+import { createMcpClient } from "../mcp.mjs";
+import { establishSession, AuthUnavailableError } from "../auth.mjs";
+import { fail } from "../errors.mjs";
+import { scopeToTenant } from "../tenant-scope.mjs";
+import { resolveRepoAndTenant } from "./branches.mjs";
+import { formatVerdictBlock } from "./submit.mjs";
+
+const DEFAULT_MCP_URL = "https://mcp.tokenoftrust.com";
+
+const USAGE = `tot status — the pipeline verdict for your active tenant
+
+  tot status                 verdict for the current checkout's repo
+  tot status --tenant <d>    verdict for a specific store (e.g. --tenant acme.com)
+  tot status --json          machine-readable output
+
+Options:
+  --tenant <appDomain>   the store to read (default: the current checkout / its remote)
+  --repo <repo>          an explicit repo name, when it differs from --tenant
+  --mcp <url>            override the MCP base URL
+  --json                 print the raw { verdict, ... } payload instead of prose
+`;
+
+/**
+ * @param {string[]} argv
+ * @returns {{ tenant: string|null, repo: string|null, mcp: string|null, json: boolean, help: boolean }}
+ */
+function parseStatusArgs(argv) {
+  const args = /** @type {{ tenant: string|null, repo: string|null, mcp: string|null, json: boolean, help: boolean }} */ ({
+    tenant: null, repo: null, mcp: null, json: false, help: false,
+  });
+  for (let i = 0; i < argv.length; i++) {
+    const a = argv[i];
+    if (a === "--help" || a === "-h") args.help = true;
+    else if (a === "--json") args.json = true;
+    else if (a === "--tenant") args.tenant = argv[++i] ?? null;
+    else if (a === "--repo") args.repo = argv[++i] ?? null;
+    else if (a === "--mcp") args.mcp = argv[++i] ?? null;
+  }
+  return args;
+}
+
+/** @param {string[]} argv @param {any} ctx */
+export async function run(argv, ctx) {
+  const env = process.env;
+  const args = parseStatusArgs(argv);
+  if (args.help) {
+    console.log(USAGE);
+    return 0;
+  }
+
+  const { repo, tenant, error } = resolveRepoAndTenant(args, ctx);
+  if (error) {
+    console.error(error);
+    return 2;
+  }
+
+  const baseUrl = args.mcp || env.MCP_BASE_URL || env.TOT_MCP_URL || DEFAULT_MCP_URL;
+  const client = createMcpClient(baseUrl);
+  try {
+    await establishSession(client, { env });
+    const scoped = await scopeToTenant(client, /** @type {string} */ (tenant));
+    const result = await scoped.callTool("store_status", { repo, include: ["branches"] });
+
+    if (result?.status === "error" || result?.status === "invalid_input" || result?.error) {
+      console.error(
+        fail(
+          `couldn't read status for ${repo}: ${result.error || result.message || "unknown error"}`,
+          "check --tenant / --repo, then re-run",
+        ),
+      );
+      return 1;
+    }
+
+    if (args.json) {
+      console.log(JSON.stringify({ verdict: result?.verdict ?? null, tenant: repo }, null, 2));
+      return 0;
+    }
+
+    const verdict = result?.verdict ?? null;
+    if (!verdict) {
+      console.log(`  (no pipeline verdict available for ${repo} right now.)`);
+      return 0;
+    }
+    console.log(`${repo}:`);
+    for (const line of formatVerdictBlock(verdict)) console.log(line);
+    return 0;
+  } catch (e) {
+    if (e instanceof AuthUnavailableError) {
+      console.error(fail("sign in to read status", e.hint || "run `tot login`, then re-run"));
+      return 1;
+    }
+    console.error(
+      fail(
+        `couldn't reach the status service: ${String(e?.message || e)}`,
+        "check your connection and that you're signed in, then re-run",
+      ),
+    );
+    return 1;
+  }
+}

package/src/commands/submit.mjs

@@ -962,14 +962,28 @@ export function chooseChangeId({ tenant, actorKey, branch = null, active = null,
  * @param {{ repo: string, changeId: string }} opts
  * @returns {Promise<string|null>}
  */
+/**
+ * The FULL candidate_status record for one candidate (changeId/prNumber/branch/headSha/
+ * state/…), tolerant of the same three response shapes `candidateStateFor` tolerates
+ * (a bare candidate, `{candidates:[…]}`, or a plain array). Null when the tool throws or
+ * names no matching candidate — never thrown. Shared by `candidateStateFor` (state only)
+ * and `submitCandidate`'s 502-despite-success recovery (the full record).
+ * @param {{callTool:Function}} scoped the tenant-scoped handle from `scopeToTenant` (or a mock)
+ * @param {{ repo: string, changeId: string }} opts
+ */
+export async function fetchCandidateStatus(scoped, { repo, changeId }) {
+  const r = await scoped.callTool("candidate_status", { repo, changeId });
+  const c = Array.isArray(r)
+    ? r.find((x) => x?.changeId === changeId)
+    : Array.isArray(r?.candidates)
+      ? r.candidates.find((x) => x?.changeId === changeId)
+      : r;
+  return c ?? null;
+}
+
 export async function candidateStateFor(scoped, { repo, changeId }) {
   try {
-    const r = await scoped.callTool("candidate_status", { repo, changeId });
-    const c = Array.isArray(r)
-      ? r.find((x) => x?.changeId === changeId)
-      : Array.isArray(r?.candidates)
-        ? r.candidates.find((x) => x?.changeId === changeId)
-        : r;
+    const c = await fetchCandidateStatus(scoped, { repo, changeId });
     return c && typeof c.state === "string" ? c.state : null;
   } catch (error) {
     recordDiagnostic(error, {
@@ -1086,6 +1100,28 @@ export async function submitCandidate(scoped, { repo, changeId, ref, headSha, ch
     return result;
   } catch (e) {
     if (e instanceof CandidateRegistrationError) throw e;
+    // "502 despite success" (migration DAG §U4): candidate_open's forge write is
+    // idempotent and may have LANDED even though its HTTP response never reached us
+    // (a 5xx between MCP and its own caller, a dropped connection, …). Before reporting
+    // a fatal "candidate not created," re-read it by its stable changeId — if it's
+    // already there with the exact ref/head we just pushed, this submit DID succeed;
+    // report that instead of a false failure. Purely a recovery path: any error from
+    // the re-read (including "not found," which is the ordinary case for a genuine
+    // registration failure) falls through to the original fatal error, unchanged.
+    const httpStatus = /** @type {any} */ (e)?.diagnostic?.httpStatus;
+    if (typeof httpStatus === "number" && httpStatus >= 500) {
+      const existing = await fetchCandidateStatus(scoped, { repo, changeId }).catch(() => null);
+      if (
+        existing
+        && typeof existing.prNumber === "number"
+        && existing.branch === ref
+        && existing.headSha === headSha
+        && !isTerminalCandidateState(existing.state)
+      ) {
+        reportCandidate(existing, changeId, { quiet });
+        return existing;
+      }
+    }
     throw new CandidateRegistrationError(`Candidate not created: ${describeReadbackError(e)}`, e);
   }
 }
@@ -1134,7 +1170,7 @@ function reportCandidate(result, changeId, { quiet = false } = {}) {
  *   candidate?: {prNumber?: number, number?: number, state?: string, url?: string, headSha?: string|null}|null,
  *   status?: {status?: string, reconcile?: object|null, compliance?: object|null,
  *     previewUrl?: string|null, shipped?: object|null, dispatched?: boolean|null,
- *     notDispatched?: boolean, delivery?: object|null}|null,
+ *     notDispatched?: boolean, delivery?: object|null, verdict?: object|null}|null,
  *   previewPrUrl?: string|null, error?: string|null, note?: string|null, noChanges?: boolean,
  *   degraded?: boolean, diagnosticId?: string|null }} input
  */
@@ -1160,6 +1196,7 @@ export function buildJsonResult({ ok, ref = null, commit = null, changeId = null
     notDispatched: status?.notDispatched ?? false,
     forwardFailed: /** @type {any} */ (status)?.forwardFailed ?? false,
     delivery: status?.delivery ?? null,
+    verdict: status?.verdict ?? null,
     previewPrUrl,
     ...(degraded ? { degraded: true } : {}),
     ...(diagnosticId ? { diagnosticId } : {}),
@@ -1868,6 +1905,10 @@ export function normalizePreviewStatus(r) {
     shipped: r?.shipped ?? null,
     delivery,
     dispatched: delivery != null,
+    // The ONE pipeline-status read every surface (console, `preview_status`, `tot
+    // status`) shares (migration DAG §U4) — null when it could not be read. Printed
+    // alongside the legacy fields above, never replacing them.
+    verdict: r?.verdict ?? null,
     raw: r,
   };
 }
@@ -2122,6 +2163,29 @@ export function formatForwardFailedBlock({ commit = null } = {}, tenant) {
   ];
 }
 
+/**
+ * The pipeline-verdict lines (migration DAG §U4): kind, reason, next action — the SAME
+ * verdict the Publish console and `tot status` print, so a developer never sees a
+ * different story in two places. On `stuck`, also prints the support bundle text when
+ * the caller fetched one (preview_status attaches it only when `contactSupport` is
+ * true). Pure — unit-tested. Returns `[]` when there is nothing to print (no verdict,
+ * or a verdict object that isn't shaped as expected — never throws on a malformed one).
+ * @param {any} verdict @param {string|null} [supportBundleText]
+ * @returns {string[]}
+ */
+export function formatVerdictBlock(verdict, supportBundleText = null) {
+  if (!verdict || typeof verdict !== "object" || typeof verdict.kind !== "string") return [];
+  const lines = [`\n  verdict: ${verdict.kind}${verdict.reason ? ` — ${verdict.reason}` : ""}`];
+  const next = verdict.nextAction;
+  if (next && typeof next.label === "string") {
+    lines.push(`    next: ${next.label}${next.command ? ` (${next.command})` : ""}`);
+  }
+  if (verdict.kind === "stuck" && supportBundleText) {
+    lines.push("", "  — support bundle (share this with support) —", supportBundleText);
+  }
+  return lines;
+}
+
 /**
  * Print the reconcile/compliance/preview result and, on a clean reconcile with a
  * preview URL, open it in the browser (unless opts.open === false). `quiet`
@@ -2135,6 +2199,7 @@ export function formatForwardFailedBlock({ commit = null } = {}, tenant) {
  * @param {{ open?: boolean, quiet?: boolean, commit?: string|null, ref?: string|null, verb?: string, noChanges?: boolean }} [opts]
  */
 function reportStatus(s, tenant, { open = true, quiet = false, commit = null, ref = null, verb = "preview", noChanges = false } = {}) {
+  if (!quiet) for (const line of formatVerdictBlock(s?.verdict, s?.supportBundleText)) console.log(line);
   if (!s || s.status === "unknown") {
     if (!quiet) {
       console.log(

package/src/pipeline-job.mjs

@@ -0,0 +1,63 @@
+/**
+ * Waiting on a store pipeline job. Add to release (`tot accept`) and Undo (`tot revert`) run as
+ * jobs in the store's pipeline: the route answers `202 {jobId}` at once, and the job's outcome is
+ * read from `GET /api/pipeline/jobs/<jobId>` until it is no longer pending. The job runs on the
+ * platform whether or not anything is waiting for it — stopping here (Ctrl-C, a timeout) stops
+ * only the wait.
+ *
+ * Dependency-free (global fetch).
+ */
+
+const DEFAULT_INTERVAL_MS = 3_000;
+const DEFAULT_TIMEOUT_MS = 25 * 60_000;
+
+/**
+ * Poll the job until its outcome is terminal, or `timeoutMs` passes. Resolves with
+ * `{ outcome, timedOut }` — `outcome` is the last read (`pending: true` when it timed out).
+ * Network faults between polls are retried; a non-2xx read ends the wait with that status.
+ *
+ * @param {{ base:string, authHeaders:Record<string,string>, jobId:string }} target
+ * @param {typeof fetch} fetchImpl
+ * @param {{ intervalMs?:number, timeoutMs?:number, sleep?:(ms:number)=>Promise<void>,
+ *   now?:()=>number, onPoll?:(outcome:any)=>void }} [opts]
+ */
+export async function waitForPipelineJob({ base, authHeaders, jobId }, fetchImpl, opts = {}) {
+  const intervalMs = opts.intervalMs ?? DEFAULT_INTERVAL_MS;
+  const timeoutMs = opts.timeoutMs ?? DEFAULT_TIMEOUT_MS;
+  const sleep = opts.sleep ?? ((ms) => new Promise((resolve) => setTimeout(resolve, ms)));
+  const now = opts.now ?? (() => Date.now());
+  const started = now();
+  let last = { ok: false, pending: true, jobId };
+  for (;;) {
+    let res = null;
+    try {
+      res = await fetchImpl(`${base}/api/pipeline/jobs/${encodeURIComponent(jobId)}`, {
+        method: "GET",
+        headers: { accept: "application/json", ...authHeaders },
+      });
+    } catch {
+      res = null;
+    }
+    if (res) {
+      let data = {};
+      try {
+        data = await res.json();
+      } catch {
+        data = {};
+      }
+      if (!res.ok) {
+        return { outcome: { ok: false, pending: true, jobId, error: data.error || `job read failed (${res.status})` }, timedOut: false };
+      }
+      last = data && data.outcome && typeof data.outcome === "object" ? data.outcome : last;
+      opts.onPoll?.(last);
+      if (last.pending !== true) return { outcome: last, timedOut: false };
+    }
+    if (now() - started >= timeoutMs) return { outcome: last, timedOut: true };
+    await sleep(intervalMs);
+  }
+}
+
+/** True when a submit answered with a job to wait on (`202 {jobId}`). */
+export function isJobAccepted(res, data) {
+  return Boolean(res && res.status === 202 && data && typeof data.jobId === "string");
+}

package/src/tenant-scope.mjs

@@ -51,6 +51,7 @@ export const PIN_SCOPED_TOOLS = Object.freeze(new Set([
   "candidate_list",
   "candidate_delete",
   "candidate_refresh",
+  "store_status",
 ]));
 
 /**