@tokenoftrust/cli 2.4.0 → 2.4.2

package/bin/tot.mjs

@@ -219,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");
@@ -245,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.4.0",
+  "version": "2.4.2",
   "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/submit.mjs

@@ -28,11 +28,12 @@
  * needed. `--watch` just raises the budget (longer waitMs, more attempts) so an
  * attached dev can stay and watch reconcile+compliance resolve live.
  *
- * Watching through to accept (E1b): `--watch` also sets untilShipped, so once
- * reconcile resolves cleanly the loop keeps going (preview_status reuses the
- * SAME waitMs budget server-side to long-poll for a ship decision too — one
- * poll axis, not two) until change_accept ships it or the attempts budget
- * runs out. A failed reconcile never waits for ship — it can't have shipped.
+ * Watching through to live (E1b): `--watch` also sets untilShipped, so once
+ * reconcile resolves cleanly the loop keeps going until the pipeline verdict
+ * (`preview_status.verdict`) shows this commit live — on Cloudflare once the
+ * pointer flip is proven, on CloudFront once the CI publish is confirmed — or the
+ * attempts budget runs out. A failed reconcile never waits for ship — it can't
+ * have shipped.
  * Detached devs get the E1 email instead; this is the attached half.
  *
  * Dependency-free (global fetch + `git`).
@@ -1798,7 +1799,7 @@ export async function run(argv, ctx, {
     let status;
     operation = "preview_status";
     if (args.noWait) {
-      status = normalizePreviewStatus(await scoped.callTool("preview_status", { commit: statusSha }));
+      status = normalizePreviewStatus(await scoped.callTool("preview_status", { commit: statusSha }), statusSha);
     } else {
       // One in-place status line (TTY: a spinner with an elapsed-seconds counter;
       // non-TTY: a ~10s heartbeat) instead of a newline per poll — the wait reads
@@ -1880,10 +1881,10 @@ export async function run(argv, ctx, {
 /**
  * Normalize a `preview_status` tool response to the contract shape the CLI reports
  * on: { status, reconcile:{ok,errors}, compliance:{verdict,detail}, previewUrl,
- * shipped, delivery, dispatched }. A live tool always returns status
+ * shipped, delivery, dispatched, verdict }. A live tool always returns status
  * pending|reconciled|failed; anything else (an older MCP without the tool's flat
  * fields) normalizes to "unknown" so the CLI degrades visibly instead of pretending
- * it reconciled. `shipped` (E1b) is null until change_accept ships this exact commit.
+ * it reconciled. `shipped` (E1b) is derived from the verdict: null until this commit is live.
  *
  * `delivery` is the MCP's reconcile-observability triad for the Gitea webhook that
  * fired on this commit ({ target, actual, evidence, drift? }) — or null when NO
@@ -1893,7 +1894,11 @@ export async function run(argv, ctx, {
  * read under a different tenant scope than it was pushed to), which is a permanent
  * dead-end the CLI must not report as "still reconciling". Pure — unit-tested.
  */
-export function normalizePreviewStatus(r) {
+/**
+ * @param {any} r  the `preview_status` response
+ * @param {string|null} [commit]  the sha the status was asked for (what `shipped` is decided against)
+ */
+export function normalizePreviewStatus(r, commit = null) {
   const status = r?.status;
   const known = status === "pending" || status === "reconciled" || status === "failed";
   const delivery = r?.delivery ?? null;
@@ -1902,7 +1907,7 @@ export function normalizePreviewStatus(r) {
     reconcile: r?.reconcile ?? null,
     compliance: r?.compliance ?? null,
     previewUrl: r?.previewUrl ?? null,
-    shipped: r?.shipped ?? null,
+    shipped: shippedFromVerdict(r?.verdict ?? null, commit),
     delivery,
     dispatched: delivery != null,
     // The ONE pipeline-status read every surface (console, `preview_status`, `tot
@@ -1913,6 +1918,26 @@ export function normalizePreviewStatus(r) {
   };
 }
 
+/**
+ * Whether the pipeline verdict shows `commit` live, and where: the live release IS this commit, or
+ * the live release is the next release this commit's change was merged into (its membership names
+ * the commit as a change head). Per provider, the verdict's live release is recorded only once
+ * delivery is proven — the Cloudflare pointer flip read back, or the CloudFront CI publish
+ * confirmed. Null when not live (or no verdict). Pure — unit-tested.
+ * @param {any} verdict  @param {string|null} commit
+ * @returns {{ sha: string, receiptId: string|null, provider: string|null, provedAt: string|null }|null}
+ */
+export function shippedFromVerdict(verdict, commit) {
+  if (!commit || verdict?.kind !== "idle" || !verdict.live?.sha) return null;
+  const live = verdict.live;
+  const merged =
+    verdict.preview?.sha === live.sha &&
+    Array.isArray(verdict.preview?.membership) &&
+    verdict.preview.membership.some((m) => m?.headSha === commit);
+  if (live.sha !== commit && !merged) return null;
+  return { sha: live.sha, receiptId: live.receiptId ?? null, provider: live.provider ?? null, provedAt: live.provedAt ?? null };
+}
+
 /** A submit succeeds only when reconcile has neither failed nor failed to start. */
 export function previewSubmitSucceeded(status) {
   const knownSuccessState = status?.status === "pending" || status?.status === "reconciled";
@@ -1971,7 +1996,7 @@ export async function pollPreviewStatus(
   for (let i = 0; i < attempts; i++) {
     const startedAt = now();
     const args = waitMs ? { commit, waitMs } : { commit };
-    last = normalizePreviewStatus(await scoped.callTool("preview_status", args));
+    last = normalizePreviewStatus(await scoped.callTool("preview_status", args), commit);
     if (last.dispatched) everDispatched = true;
     last.everDispatched = everDispatched;
     if (onTick) onTick(last, i);
@@ -2194,6 +2219,25 @@ export function formatVerdictBlock(verdict, supportBundleText = null) {
  * --json — automation doesn't want a browser popping up). `commit`/`ref`/`verb`
  * feed the honest never-dispatched block.
  */
+/**
+ * The ship line after a watched submit: where this commit is live (per provider) once the verdict
+ * shows it, or that a reviewer still has to accept it. Null when reconcile has not settled. Pure.
+ * @param {{ status?: string, shipped?: { sha: string, receiptId: string|null, provider: string|null, provedAt: string|null }|null }} s
+ */
+export function formatShipLine(s) {
+  if (s?.shipped) {
+    const where =
+      s.shipped.provider === "s3-overwrite" ? "CloudFront" : s.shipped.provider === "worker-r2-pointer" ? "Cloudflare" : "your live site";
+    return (
+      `\n  ✓ shipped — live at ${s.shipped.sha.slice(0, 9)} on ${where}` +
+      (s.shipped.receiptId ? ` (receipt ${s.shipped.receiptId})` : "") +
+      (s.shipped.provedAt ? `, proven ${s.shipped.provedAt}` : "")
+    );
+  }
+  if (s?.status === "reconciled") return `\n  ~ not yet shipped — a reviewer still needs to run change_accept.`;
+  return null;
+}
+
 /**
  * @param {any} s @param {string} tenant
  * @param {{ open?: boolean, quiet?: boolean, commit?: string|null, ref?: string|null, verb?: string, noChanges?: boolean }} [opts]
@@ -2249,11 +2293,8 @@ function reportStatus(s, tenant, { open = true, quiet = false, commit = null, re
       console.log(`  compliance: ${s.compliance.verdict}${s.compliance.detail ? ` — ${s.compliance.detail}` : ""}`);
       for (const c of s.compliance.checks ?? []) reportComplianceCheck(c);
     }
-    if (s.shipped) {
-      console.log(`\n  ✓ shipped — change ${s.shipped.changeId} accepted at ${s.shipped.shippedAt}`);
-    } else if (s.status === "reconciled") {
-      console.log(`\n  ~ not yet shipped — a reviewer still needs to run change_accept.`);
-    }
+    const shipLine = formatShipLine(s);
+    if (shipLine) console.log(shipLine);
     for (const line of formatShareableUrlBlock(s, tenant)) console.log(line);
   }
   if (s.previewUrl && open && s.status === "reconciled" && openBrowser(s.previewUrl)) {

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");
+}