@tokenoftrust/cli 1.4.0-rc.15 → 1.4.0-rc.17

package/src/commands/submit.mjs

@@ -40,6 +40,7 @@
  * Dependency-free (global fetch + `git`).
  */
 import { execFileSync } from "node:child_process";
+import { readFileSync } from "node:fs";
 import { createHash } from "node:crypto";
 import { setTimeout as delay } from "node:timers/promises";
 import { createMcpClient } from "../mcp.mjs";
@@ -60,6 +61,13 @@ import {
 
 const DEFAULT_MCP_URL = "https://mcp.tokenoftrust.com";
 
+// The public storefront origin a shareable preview PR URL is composed against
+// (see shareablePrUrl, below) — the SAME default `tot ship` uses (ship.mjs's
+// DEFAULT_STOREFRONT_URL), so a preview link and a ship link always agree on
+// which storefront they point at even though submit.mjs and ship.mjs never
+// import from each other.
+const DEFAULT_STOREFRONT_URL = "https://storefront.tokenoftrust.store";
+
 // The git ref prefix an isolated candidate push lands under (b03 — stop
 // force-pushing the SHARED `preview` ref). ONE constant so a rename is trivial —
 // provisionally coordinated with the MCP-side candidate_open resolution (b02/b04),
@@ -77,7 +85,7 @@ export function parseArgs(argv) {
   // `ref: null` — an explicit `--ref` always wins; otherwise the push target is
   // derived per-run as YOUR OWN isolated candidate ref (resolvePushRef, below),
   // never a fixed shared default.
-  const a = { mcp: null, identity: null, ref: null, skipValidate: false, noWait: false, watch: false, noOpen: false, noCommit: false, message: null, summary: null, new: false, help: false };
+  const a = { mcp: null, identity: null, ref: null, skipValidate: false, noWait: false, watch: false, noOpen: false, noCommit: false, message: null, summary: null, summaryFile: null, json: false, new: false, help: false };
   for (let i = 0; i < argv.length; i++) {
     const t = argv[i];
     if (t === "--mcp") a.mcp = argv[++i];
@@ -85,6 +93,8 @@ export function parseArgs(argv) {
     else if (t === "--ref") a.ref = argv[++i];
     else if (t === "-m" || t === "--message") a.message = argv[++i];
     else if (t === "--summary") a.summary = argv[++i];
+    else if (t === "--summary-file") a.summaryFile = argv[++i];
+    else if (t === "--json") a.json = true;
     else if (t === "--skip-validate") a.skipValidate = true;
     else if (t === "--no-commit") a.noCommit = true;
     else if (t === "--no-wait") a.noWait = true;
@@ -113,8 +123,16 @@ export function renderUsage(verb = "preview") {
   tot ${verb} --ref <name>       push ref (default: your own isolated candidate ref — see \`tot pr\`)
   tot ${verb} -m "<title>"       one-line summary of what changed (the approver sees this)
   tot ${verb} --summary "<text>" longer description to accompany the title
+  tot ${verb} --summary-file <path>  structured summary from a file — JSON
+                                  {intent,effect,verification,risk} or the labeled
+                                  Intent / User-visible effect / Verification /
+                                  Risk-rollback text block; pass "-" to read stdin
+                                  (mutually exclusive with --summary)
   tot ${verb} --no-wait          push and exit without polling for the reconcile result
   tot ${verb} --no-open          don't open the preview URL in the browser on success
+  tot ${verb} --json             machine-readable result on stdout (candidate id, PR,
+                                  head SHA, preview URL, reconcile/compliance evidence)
+                                  — implies --no-open, no spinner
   tot ${verb} --mcp <url>        MCP base URL (default: env MCP_BASE_URL / TOT_MCP_URL)
 
   By default a re-run UPDATES your open candidate PR (like pushing more commits
@@ -161,14 +179,135 @@ export function buildChangeSummary({ message, summary, headSubject = "", statLin
 
 /** Print the change summary block — the SAME title/body carried into `candidate_open`
  *  (below) as the PR title/description, so what the approver reads in the PR matches
- *  what's printed here. */
-function printChangeSummary({ title, body, autoTitle }) {
+ *  what's printed here. `quiet` (--json) suppresses the human-readable print — the
+ *  same data reaches the caller via the JSON result instead (see buildJsonResult). */
+function printChangeSummary({ title, body, autoTitle }, { quiet = false } = {}) {
+  if (quiet) return;
   console.log(`\n  Change summary (for the approver / the change record):`);
   console.log(`    ${title}`);
   for (const l of body) console.log(`      ${l}`);
   if (autoTitle) console.log(`  (auto-generated from git — pass -m "…" / --summary "…" to refine)`);
 }
 
+// ─── structured candidate summary (--summary-file / stdin, P2 item 14) ──────────
+
+/**
+ * The four fields the candidate body prefers (see
+ * docs/architecture/branch-lifecycle-and-integration-preview.md §"Change
+ * descriptions and AI assistance") — `key` is the JSON key, `label` the
+ * canonical text-block heading, `match` the label spellings
+ * parseLabeledSummary recognizes for that field (case-insensitive).
+ */
+const STRUCTURED_FIELDS = [
+  { key: "intent", label: "Intent", match: /^intent$/i },
+  { key: "effect", label: "User-visible effect", match: /^(user-visible effect|effect)$/i },
+  { key: "verification", label: "Verification", match: /^verification$/i },
+  { key: "risk", label: "Risk / rollback", match: /^(risk\s*\/?\s*rollback|risk-rollback|risk)$/i },
+];
+
+/**
+ * Parse the labeled four-field text block (`Intent: …` / `User-visible effect: …`
+ * / `Verification: …` / `Risk / rollback: …`) into `{intent, effect, verification,
+ * risk}` — a field's value continues across following lines until the next
+ * recognized label, so multi-line prose under one label is preserved. Unlabeled
+ * leading text (and anything before the first recognized label) is dropped —
+ * callers fall back to treating the whole file as freeform body when nothing
+ * matches at all. Pure — unit-tested.
+ * @param {string} text
+ * @returns {{intent?: string, effect?: string, verification?: string, risk?: string}}
+ */
+export function parseLabeledSummary(text) {
+  const fields = {};
+  let current = null;
+  let buf = [];
+  const flush = () => {
+    if (current) fields[current] = buf.join("\n").trim();
+    buf = [];
+  };
+  for (const line of String(text).split(/\r?\n/)) {
+    const m = /^([A-Za-z][A-Za-z /-]*?)\s*:\s*(.*)$/.exec(line);
+    const field = m && STRUCTURED_FIELDS.find((f) => f.match.test(m[1].trim()));
+    if (field) {
+      flush();
+      current = field.key;
+      buf = m[2] ? [m[2]] : [];
+    } else if (current) {
+      buf.push(line);
+    }
+  }
+  flush();
+  return fields;
+}
+
+/**
+ * Parse `--summary-file` content as JSON — `{intent, effect, verification, risk}`
+ * (extra keys ignored, each value trimmed, blank/non-string values dropped).
+ * Returns null when the text isn't a JSON object at all, so the caller falls
+ * back to the labeled-text parser rather than treating a JSON parse error as
+ * "no fields". Pure — unit-tested.
+ * @param {string} text
+ * @returns {{intent?: string, effect?: string, verification?: string, risk?: string}|null}
+ */
+export function parseJsonSummary(text) {
+  let obj;
+  try {
+    obj = JSON.parse(text);
+  } catch {
+    return null;
+  }
+  if (!obj || typeof obj !== "object" || Array.isArray(obj)) return null;
+  const fields = {};
+  for (const { key } of STRUCTURED_FIELDS) {
+    if (typeof obj[key] === "string" && obj[key].trim()) fields[key] = obj[key].trim();
+  }
+  return fields;
+}
+
+/**
+ * Render recognized structured fields back to the canonical labeled block — the
+ * SAME shape the contract prescribes — so a JSON or labeled-text `--summary-file`
+ * produces an identical PR/candidate body to a human writing
+ * `--summary "Intent: …"` by hand. Only fields actually present are emitted.
+ * Pure — unit-tested.
+ * @param {{intent?: string, effect?: string, verification?: string, risk?: string}} fields
+ * @returns {string[]}
+ */
+export function formatStructuredSummary(fields) {
+  return STRUCTURED_FIELDS.filter(({ key }) => fields[key]).map(({ key, label }) => `${label}: ${fields[key]}`);
+}
+
+/**
+ * Resolve `--summary-file`/stdin content to `--summary`'s body text (so it
+ * flows through buildChangeSummary/candidate_open exactly like an inline
+ * `--summary`, per the "preserve -m/--summary unchanged" requirement — this is
+ * purely an alternate SOURCE for the same body string). JSON wins if the
+ * content parses as an object with at least one recognized field; else the
+ * labeled text block; else — no recognized structure at all — the raw content
+ * is used verbatim as freeform summary text, so automation isn't forced into
+ * the four-field shape. Pure — unit-tested.
+ * @param {string} text
+ * @returns {string}
+ */
+export function summaryFromStructuredText(text) {
+  const trimmed = String(text ?? "").trim();
+  if (!trimmed) return "";
+  const json = parseJsonSummary(trimmed);
+  if (json && Object.keys(json).length) return formatStructuredSummary(json).join("\n");
+  const labeled = parseLabeledSummary(trimmed);
+  if (Object.keys(labeled).length) return formatStructuredSummary(labeled).join("\n");
+  return trimmed;
+}
+
+/** Read `--summary-file <path>` content — `"-"` reads stdin (fd 0), the same
+ *  dash-means-stdin convention `tot app` uses (see app/dev.mjs readInput), so
+ *  an LLM/automation caller can pipe the structured summary in without a temp
+ *  file. Throws on a real read failure (missing file, permissions) — the
+ *  caller reports it. */
+export function readSummaryFileContent(pathOrDash) {
+  if (pathOrDash === "-") return readFileSync(0, "utf8");
+  return readFileSync(pathOrDash, "utf8");
+}
+
 // ─── auto-commit the known content trees (unit u2) ───────────────────────────────
 
 /**
@@ -580,17 +719,19 @@ export function resolvePushRef({ ref, changeId }) {
  * landed or the reconcile/compliance read-back that follows.
  * @param {ReturnType<import("../mcp.mjs").createMcpClient>} client
  * @param {{ repo: string|null, changeId: string, changeSummary: {title:string, body:string[]},
- *   patchEntries: {status:string, path:string, from?:string}[], readBlob: (path:string)=>Buffer }} opts
+ *   patchEntries: {status:string, path:string, from?:string}[], readBlob: (path:string)=>Buffer,
+ *   quiet?: boolean }} opts  `quiet` (--json) suppresses the human print; the same
+ *   result is still returned for the caller's JSON payload.
  */
-export async function submitCandidate(client, { repo, changeId, changeSummary, patchEntries, readBlob }) {
+export async function submitCandidate(client, { repo, changeId, changeSummary, patchEntries, readBlob, quiet = false }) {
   if (!repo) {
-    console.log(`  ~ couldn't derive the forge repo from the checkout's remote — skipping the PR-backed candidate.`);
+    if (!quiet) console.log(`  ~ couldn't derive the forge repo from the checkout's remote — skipping the PR-backed candidate.`);
     return null;
   }
   try {
     const patch = buildFilePatch(patchEntries, readBlob);
     if (patch.length === 0) {
-      console.log(`  ~ no file changes to open a PR-backed candidate for.`);
+      if (!quiet) console.log(`  ~ no file changes to open a PR-backed candidate for.`);
       return null;
     }
     const result = await client.callTool("candidate_open", {
@@ -603,33 +744,102 @@ export async function submitCandidate(client, { repo, changeId, changeSummary, p
       body: changeSummary.body.length ? changeSummary.body.join("\n").slice(0, 4000) : undefined,
       patch,
     });
-    reportCandidate(result, changeId);
+    reportCandidate(result, changeId, { quiet });
     return result;
   } catch (e) {
-    console.log(`  ~ couldn't open/update the PR-backed candidate: ${String(e?.message || e)}`);
-    console.log(`    (best-effort — your push is still in; this doesn't block reconcile.)`);
+    if (!quiet) {
+      console.log(`  ~ couldn't open/update the PR-backed candidate: ${String(e?.message || e)}`);
+      console.log(`    (best-effort — your push is still in; this doesn't block reconcile.)`);
+    }
     return null;
   }
 }
 
 /** Print the candidate_open result: the PR the approver reviews, or the MCP's own
- *  refusal message when it couldn't open/update one. */
-function reportCandidate(result, changeId) {
+ *  refusal message when it couldn't open/update one. `quiet` (--json) suppresses it.
+ *  Deliberately does NOT print `result.url` — that's the INTERNAL forge (Gitea) PR
+ *  link, plumbing a developer never needs to see (DZ, 2026-08-15); the product
+ *  surface is the shareable /preview/<tenant>/pr/<N> URL printed right after
+ *  (shareablePrUrl). The forge URL still rides the --json payload for tooling. */
+function reportCandidate(result, changeId, { quiet = false } = {}) {
+  if (quiet) return;
   if (result && typeof result.prNumber === "number") {
     console.log(`\n  ✓ candidate ${result.changeId || changeId} — PR #${result.prNumber} (${result.state || "open"})`);
-    if (result.url) console.log(`    ${result.url}`);
     return;
   }
   const msg = result?.message || (result?.raw && String(result.raw)) || JSON.stringify(result ?? null);
   console.log(`  ~ PR-backed candidate not opened: ${msg}`);
 }
 
+/**
+ * Build the `--json` result object (P2 item 14): candidate id, PR, head SHA,
+ * shareable preview URL, and reconcile/compliance evidence — so an
+ * LLM/automation caller can consume structured data instead of scraping
+ * human-readable stdout. `ok` mirrors the process exit code (0 ⇒ true) so a
+ * caller can branch on one field.
+ *
+ * Also carries the honest-dispatch triad (the "never dispatched" fix) so
+ * automation gets the SAME truth the human-readable path does, never a
+ * prettier lie: `dispatched` (was a webhook delivery ever observed for this
+ * commit?), `notDispatched` (the permanent-dead-end tag from
+ * pollPreviewStatus — re-running will not help), and `delivery` (the raw
+ * observability triad, or null when nothing was ever seen). All three
+ * default to their "nothing known yet" value when `status` is absent/older,
+ * so a caller can branch on `notDispatched` unconditionally without a
+ * presence check.
+ *
+ * `previewPrUrl` (P2 item — the immediate Vercel-style shareable link, see
+ * shareablePrUrl) is threaded through separately from `previewUrl`: the
+ * latter is the server-minted, reconcile-confirmed link (null until reconcile
+ * actually lands); the former is composed client-side the instant the
+ * candidate PR opens and may point at a preview that's still building.
+ * Defaults to null when no numeric PR number was known at result-build time.
+ * Pure — unit-tested.
+ * @param {{ ok: boolean, ref?: string|null, commit?: string|null, changeId?: string|null,
+ *   candidate?: {prNumber?: number, number?: number, state?: string, url?: string}|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,
+ *   previewPrUrl?: string|null, error?: string|null, note?: string|null }} input
+ */
+export function buildJsonResult({ ok, ref = null, commit = null, changeId = null, candidate = null, status = null, previewPrUrl = null, error = null, note = null }) {
+  return {
+    ok,
+    ref,
+    commit,
+    changeId,
+    candidate: candidate
+      ? { number: candidate.prNumber ?? candidate.number ?? null, state: candidate.state ?? null, url: candidate.url ?? null }
+      : null,
+    status: status?.status ?? null,
+    reconcile: status?.reconcile ?? null,
+    compliance: status?.compliance ?? null,
+    previewUrl: status?.previewUrl ?? null,
+    shipped: status?.shipped ?? null,
+    dispatched: status?.dispatched ?? null,
+    notDispatched: status?.notDispatched ?? false,
+    delivery: status?.delivery ?? null,
+    previewPrUrl,
+    ...(error ? { error } : {}),
+    ...(note ? { note } : {}),
+  };
+}
+
+/** Print the `--json` result as one pretty-printed object on stdout — a no-op
+ *  unless `args.json` was passed, so call sites can invoke it unconditionally. */
+function emitJson(args, payload) {
+  if (args.json) console.log(JSON.stringify(payload, null, 2));
+}
+
 /**
  * The preview flow — validate, push the preview ref, open/update the PR-backed
  * candidate, and stream back the reconcile/compliance/preview result. Reached by
  * `tot preview` and, as teaching aliases, `tot submit` / `tot deploy` (preview.mjs
  * wraps this and adds the verb-teaching hints). `verb` only brands the user-facing
  * copy (usage + the not-in-checkout error) with whatever the developer typed.
+ * `--json` (args.json) suppresses the human-readable stdout narration in favor of
+ * one structured result object at the end (see buildJsonResult) — stderr
+ * diagnostics (fail(), `~ …` progress lines) still print either way.
  * @param {string[]} argv @param {any} ctx @param {{ verb?: string }} [opts]
  */
 export async function run(argv, ctx, { verb = "preview" } = {}) {
@@ -639,13 +849,31 @@ export async function run(argv, ctx, { verb = "preview" } = {}) {
     console.log(renderUsage(verb));
     return 0;
   }
+  if (args.summary && args.summaryFile) {
+    const msg = "--summary and --summary-file are mutually exclusive";
+    console.error(fail(msg, "pass one or the other"));
+    emitJson(args, buildJsonResult({ ok: false, error: msg }));
+    return 2;
+  }
+  if (args.summaryFile) {
+    let raw;
+    try {
+      raw = readSummaryFileContent(args.summaryFile);
+    } catch (e) {
+      const msg = `couldn't read --summary-file ${args.summaryFile}: ${String(e?.message || e)}`;
+      console.error(fail(msg, `check the path (or pass "-" to read stdin)`));
+      emitJson(args, buildJsonResult({ ok: false, error: msg }));
+      return 2;
+    }
+    // Feeds --summary's body unchanged from here on (buildChangeSummary etc.) —
+    // --summary-file is purely an alternate SOURCE for the same string, per the
+    // "preserve -m/--summary unchanged" requirement.
+    args.summary = summaryFromStructuredText(raw);
+  }
   if (ctx.mode !== "checkout") {
-    console.error(
-      fail(
-        `\`tot ${verb}\` runs from inside a tenant checkout`,
-        "tot clone <tenant> <dir>   (then `cd` in, commit your work, and re-run)",
-      ),
-    );
+    const msg = `\`tot ${verb}\` runs from inside a tenant checkout`;
+    console.error(fail(msg, "tot clone <tenant> <dir>   (then `cd` in, commit your work, and re-run)"));
+    emitJson(args, buildJsonResult({ ok: false, error: msg }));
     return 2;
   }
   const workspace = ctx.workspacePath;
@@ -661,12 +889,9 @@ export async function run(argv, ctx, { verb = "preview" } = {}) {
   try {
     auto = autoCommitKnownTrees(git, { message: args.message, noCommit: args.noCommit });
   } catch (e) {
-    console.error(
-      fail(
-        `auto-commit failed: ${String(e?.stderr || e?.message || e)}`,
-        "commit your content manually (git add / git commit), or re-run with --no-commit",
-      ),
-    );
+    const msg = `auto-commit failed: ${String(e?.stderr || e?.message || e)}`;
+    console.error(fail(msg, "commit your content manually (git add / git commit), or re-run with --no-commit"));
+    emitJson(args, buildJsonResult({ ok: false, error: msg }));
     return 1;
   }
   if (auto.refused) {
@@ -679,6 +904,7 @@ export async function run(argv, ctx, { verb = "preview" } = {}) {
     for (const p of auto.unknown) console.error(`  ✗ out of scope: ${p}`);
     console.error(`\n  \`tot ${verb}\` auto-commits only: ${[...KNOWN_CONTENT_TREES, ...KNOWN_CONTENT_FILES].join(", ")}`);
     if (auto.known.length) console.error(`  (in scope, would have been committed: ${auto.known.join(", ")})`);
+    emitJson(args, buildJsonResult({ ok: false, error: `${auto.unknown.length} change(s) outside the store content trees` }));
     return 1;
   }
   if (auto.committed) {
@@ -696,6 +922,7 @@ export async function run(argv, ctx, { verb = "preview" } = {}) {
         fail(`${errs.length} validation error(s)`, "fix these (below), or re-run with --skip-validate") + "\n",
       );
       for (const f of errs) console.error(`  ✗ [${f.rule}] ${f.file} — ${f.message}`);
+      emitJson(args, buildJsonResult({ ok: false, error: `${errs.length} validation error(s)` }));
       return 1;
     }
     console.error("~ validated (no errors)");
@@ -706,7 +933,9 @@ export async function run(argv, ctx, { verb = "preview" } = {}) {
   try {
     commit = git(["rev-parse", "HEAD"]).trim();
   } catch {
-    console.error(fail("no commits here yet", "git add <files> && git commit -m '…', then re-run"));
+    const msg = "no commits here yet";
+    console.error(fail(msg, "git add <files> && git commit -m '…', then re-run"));
+    emitJson(args, buildJsonResult({ ok: false, error: msg }));
     return 1;
   }
   const short = commit.slice(0, 9);
@@ -778,22 +1007,21 @@ export async function run(argv, ctx, { verb = "preview" } = {}) {
       const out = git(["push", "-f", "origin", `HEAD:refs/heads/${ref}`]);
       if (out.trim()) console.error(redactUrl(out.trim()));
     } catch (pushErr) {
-      console.error(
-        fail(
-          `push failed: ${redactUrl(String(pushErr.stderr || pushErr.message || pushErr))}`,
-          "check your commit and that the checkout's remote is reachable, then re-run",
-        ),
-      );
+      const msg = `push failed: ${redactUrl(String(pushErr.stderr || pushErr.message || pushErr))}`;
+      console.error(fail(msg, "check your commit and that the checkout's remote is reachable, then re-run"));
+      emitJson(args, buildJsonResult({ ok: false, ref, commit, changeId, error: msg }));
       return 1;
     }
-    console.log(`\n+ submitted ${short} to ${ref}.`);
-    printChangeSummary(changeSummary);
-    if (e instanceof AuthUnavailableError) {
-      console.log(`  (sign in to see the reconcile/compliance/preview result — ${e.hint || "developer sign-in pending"})`);
-    } else {
-      console.log(`  (couldn't reach Token of Trust for the result read-back: ${String(e?.message || e)})`);
+    if (!args.json) console.log(`\n+ submitted ${short} to ${ref}.`);
+    printChangeSummary(changeSummary, { quiet: args.json });
+    const note = e instanceof AuthUnavailableError
+      ? `sign in to see the reconcile/compliance/preview result — ${e.hint || "developer sign-in pending"}`
+      : `couldn't reach Token of Trust for the result read-back: ${String(e?.message || e)}`;
+    if (!args.json) {
+      console.log(`  (${note})`);
+      console.log(`  Your push is in; the preview updates once reconcile completes.`);
     }
-    console.log(`  Your push is in; the preview updates once reconcile completes.`);
+    emitJson(args, buildJsonResult({ ok: true, ref, commit, changeId, note }));
     return 0;
   }
 
@@ -830,16 +1058,13 @@ export async function run(argv, ctx, { verb = "preview" } = {}) {
     const { out } = await pushPreviewRef(git, mintRemote, { ref });
     if (out && out.trim()) console.error(redactUrl(out.trim()));
   } catch (e) {
-    console.error(
-      fail(
-        `push failed: ${redactUrl(String(e.stderr || e.message || e))}`,
-        "check your commit and that the checkout's remote is reachable, then re-run",
-      ),
-    );
+    const msg = `push failed: ${redactUrl(String(e.stderr || e.message || e))}`;
+    console.error(fail(msg, "check your commit and that the checkout's remote is reachable, then re-run"));
+    emitJson(args, buildJsonResult({ ok: false, ref, commit, changeId, error: msg }));
     return 1;
   }
-  console.log(`\n+ submitted ${short} to ${ref}.`);
-  printChangeSummary(changeSummary);
+  if (!args.json) console.log(`\n+ submitted ${short} to ${ref}.`);
+  printChangeSummary(changeSummary, { quiet: args.json });
 
   // 2b + 3. open/update the PR-backed candidate, then report reconcile +
   // compliance + preview URL from the MCP — reusing the session established above.
@@ -858,14 +1083,29 @@ export async function run(argv, ctx, { verb = "preview" } = {}) {
     // above.)
     const readBlob = (path) => execFileSync("git", ["-C", workspace, "show", `HEAD:${path}`], { stdio: ["ignore", "pipe", "pipe"] });
 
-    let candidate = await submitCandidate(client, { repo, changeId, changeSummary, patchEntries, readBlob });
+    let candidate = await submitCandidate(client, { repo, changeId, changeSummary, patchEntries, readBlob, quiet: args.json });
 
     if (candidate && isTerminalCandidateState(candidate.state)) {
       const rolled = mintFreshChangeId(stableId);
-      console.log(`  ~ candidate ${changeId} is ${candidate.state} — opening a fresh candidate PR instead.`);
+      if (!args.json) console.log(`  ~ candidate ${changeId} is ${candidate.state} — opening a fresh candidate PR instead.`);
       changeId = rolled;
       persist = true;
-      candidate = await submitCandidate(client, { repo, changeId, changeSummary, patchEntries, readBlob });
+      candidate = await submitCandidate(client, { repo, changeId, changeSummary, patchEntries, readBlob, quiet: args.json });
+    }
+
+    // Immediate shareable URL (Vercel-style: "the URL exists before the build
+    // does"). A non-terminal candidate with a real PR number means a preview
+    // WILL be built at a deterministic route — so hand the developer that link
+    // right now, before reconcile even starts, rather than making them wait for
+    // the server-minted `previewUrl` (formatShareableUrlBlock) that only shows
+    // up once reconcile actually completes. Honest framing: it's printed as
+    // "building", never as "ready".
+    const previewPrUrl =
+      candidate && !isTerminalCandidateState(candidate.state) && typeof candidate.prNumber === "number"
+        ? shareablePrUrl(env.TOT_STOREFRONT_URL || env.STOREFRONT_BASE_URL || DEFAULT_STOREFRONT_URL, tenant, candidate.prNumber)
+        : null;
+    if (previewPrUrl && !args.json) {
+      console.log(`\n  ▸ Your preview will appear at:\n      ${previewPrUrl}\n    (building — this link goes live once reconcile completes)`);
     }
 
     // Remember the active candidate only on a real, non-terminal open (best-effort;
@@ -885,35 +1125,51 @@ export async function run(argv, ctx, { verb = "preview" } = {}) {
       // as live, not as a growing wall of "(1)…(8)" lines. The counter keeps
       // ticking on its own 90ms timer even while a single poll long-polls for
       // waitMs, so elapsed time is real wall-clock, not the attempt count.
+      // --json is for automation: no interactive spinner (stays silent — the
+      // JSON result carries the same status at the end).
+      // Honest opening label (the incident this fixes: a job may never actually
+      // get dispatched — see pollPreviewStatus's notDispatched short-circuit — so
+      // the INITIAL text must not assert a reconcile job exists before one has
+      // been observed). Once a tick confirms `s.dispatched === true` the 45s
+      // stage text ("still reconciling…") IS truthful and is left as-is below.
       let phase = "reconcile";
-      progress = startProgress(`reconcile running for ${short}…`, {
-        stages: [{ afterMs: 45_000, text: `still reconciling ${short}… (larger changes take longer)` }],
-      });
+      if (!args.json) {
+        progress = startProgress(`waiting for reconcile of ${short}…`, {
+          stages: [{ afterMs: 45_000, text: `still reconciling ${short}… (larger changes take longer)` }],
+        });
+      }
       status = await pollPreviewStatus(client, commit, {
         ...(args.watch ? WATCH_POLL : DEFAULT_POLL),
         onTick: (s) => {
           // Reconcile is done but we're still waiting on a ship decision (--watch):
           // swap the label so the single line reflects the new phase, timer resets.
-          if (s.status === "reconciled" && !s.shipped && phase !== "ship") {
+          if (!args.json && s.status === "reconciled" && !s.shipped && phase !== "ship") {
             phase = "ship";
             progress.stop();
             progress = startProgress(`reconciled ${short} — waiting for a ship decision…`);
           }
         },
       });
-      progress.stop();
-      progress = null;
+      if (progress) {
+        progress.stop();
+        progress = null;
+      }
     }
-    reportStatus(status, tenant, { open: !args.noOpen });
+    // --json also skips the browser auto-open (open: !args.noOpen && !args.json)
+    // — automation doesn't want a browser popping up.
+    reportStatus(status, tenant, { open: !args.noOpen && !args.json, quiet: args.json, commit, ref, verb });
+    emitJson(args, buildJsonResult({ ok: status?.status !== "failed", ref, commit, changeId, candidate, status, previewPrUrl }));
     return status?.status === "failed" ? 1 : 0;
   } catch (e) {
     progress?.stop();
-    if (e instanceof AuthUnavailableError) {
-      console.log(`  (sign in to see the reconcile/compliance/preview result — ${e.hint || "developer sign-in pending"})`);
-    } else {
-      console.log(`  (reconcile is running — the result read-back isn't available yet: ${String(e?.message || e)})`);
+    const note = e instanceof AuthUnavailableError
+      ? `sign in to see the reconcile/compliance/preview result — ${e.hint || "developer sign-in pending"}`
+      : `reconcile is running — the result read-back isn't available yet: ${String(e?.message || e)}`;
+    if (!args.json) {
+      console.log(`  (${note})`);
+      console.log(`  Your push is in; the preview updates once reconcile completes.`);
     }
-    console.log(`  Your push is in; the preview updates once reconcile completes.`);
+    emitJson(args, buildJsonResult({ ok: true, ref, commit, changeId, note }));
     return 0;
   }
 }
@@ -921,20 +1177,31 @@ export async function run(argv, ctx, { verb = "preview" } = {}) {
 /**
  * Normalize a `preview_status` tool response to the contract shape the CLI reports
  * on: { status, reconcile:{ok,errors}, compliance:{verdict,detail}, previewUrl,
- * shipped }. 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. Pure — unit-tested.
+ * shipped, delivery, dispatched }. 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.
+ *
+ * `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
+ * webhook delivery was observed for this (tenant, commit). `dispatched` distills that
+ * to a boolean: a `pending` status with `dispatched === false` means the reconcile
+ * was NEVER DISPATCHED (no webhook fired — e.g. an unregistered hook, or a commit
+ * 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) {
   const status = r?.status;
   const known = status === "pending" || status === "reconciled" || status === "failed";
+  const delivery = r?.delivery ?? null;
   return {
     status: known ? status : "unknown",
     reconcile: r?.reconcile ?? null,
     compliance: r?.compliance ?? null,
     previewUrl: r?.previewUrl ?? null,
     shipped: r?.shipped ?? null,
+    delivery,
+    dispatched: delivery != null,
     raw: r,
   };
 }
@@ -951,29 +1218,54 @@ export function normalizePreviewStatus(r) {
  * the pre-E2 fixed-interval poll — no version check needed, the fallback is
  * automatic. Stops as soon as status resolves to "failed"/"unknown" (a failed
  * reconcile can't ship), or resolves to "reconciled" AND (not untilShipped, or
- * already shipped). Injectable delay/attempts/waitMs for tests.
+ * already shipped).
+ *
+ * NEVER-DISPATCHED short-circuit (the "still reconciling forever" fix): a `pending`
+ * status with NO delivery ever observed for this commit means no reconcile job was
+ * ever dispatched (unregistered webhook, or a tenant-scope mismatch on the read) —
+ * it will never resolve. Rather than walk the whole (~8 min under --watch) budget
+ * lying about progress, once we're past a short startup grace (`notDispatchedGraceMs`
+ * — long enough for a real delivery record to land after the push) with the delivery
+ * still absent, we stop and return the honest state tagged `notDispatched: true`. If
+ * a delivery IS seen we keep polling as before (dispatched, just slow), and a plain
+ * timeout while still pending is tagged `notDispatched` only when a delivery was never
+ * observed. Injectable delay/attempts/waitMs/grace + a `now` clock for tests.
  * @param {{callTool:Function}} client
  * @param {string} commit
- * @param {{ attempts?: number, delayMs?: number, waitMs?: number, untilShipped?: boolean, onTick?: (s:object,i:number)=>void }} [opts]
+ * @param {{ attempts?: number, delayMs?: number, waitMs?: number, untilShipped?: boolean,
+ *   notDispatchedGraceMs?: number, now?: () => number, onTick?: (s:object,i:number)=>void }} [opts]
  */
 export async function pollPreviewStatus(
   client,
   commit,
-  { attempts = 8, delayMs = 2500, waitMs = delayMs, untilShipped = false, onTick } = {},
+  { attempts = 8, delayMs = 2500, waitMs = delayMs, untilShipped = false, notDispatchedGraceMs = 15_000, now = Date.now, onTick } = {},
 ) {
   let last = null;
+  let everDispatched = false;
+  const pollStart = now();
   for (let i = 0; i < attempts; i++) {
-    const startedAt = Date.now();
+    const startedAt = now();
     const args = waitMs ? { commit, waitMs } : { commit };
     last = normalizePreviewStatus(await client.callTool("preview_status", args));
+    if (last.dispatched) everDispatched = true;
+    last.everDispatched = everDispatched;
     if (onTick) onTick(last, i);
+    // Never-dispatched dead-end: still pending, no delivery has EVER been observed
+    // for this commit, and we're past the startup grace — the reconcile will never
+    // arrive. Return honestly instead of continuing to show "still reconciling".
+    if (last.status === "pending" && !everDispatched && now() - pollStart >= notDispatchedGraceMs) {
+      return { ...last, notDispatched: true };
+    }
     const stillWatchingForShip = untilShipped && last.status === "reconciled" && !last.shipped;
     if (last.status !== "pending" && !stillWatchingForShip) return last;
     if (i < attempts - 1) {
-      const remaining = delayMs - (Date.now() - startedAt);
+      const remaining = delayMs - (now() - startedAt);
       if (remaining > 0) await delay(remaining);
     }
   }
+  // Budget exhausted. A still-pending result that never saw a delivery is a
+  // never-dispatched dead-end (honest), not "still working".
+  if (last) return { ...last, everDispatched, notDispatched: last.status === "pending" && !everDispatched };
   return last;
 }
 
@@ -993,6 +1285,30 @@ function reportComplianceCheck(c) {
   if (c.hint) console.log(`        → fix: ${c.hint}`);
 }
 
+/**
+ * The IMMEDIATE shareable preview URL (Vercel-style: "the URL exists before the
+ * build does") — composed client-side, deterministically, from the tenant + PR
+ * number the candidate_open call just returned, so a developer gets a link to
+ * paste to a reviewer the INSTANT the candidate opens, not minutes later once
+ * reconcile finishes and the MCP mints `previewUrl` server-side (that's
+ * formatShareableUrlBlock's job, above — the two are deliberately redundant:
+ * this one is available immediately but "building", that one is authoritative
+ * once reconcile actually lands). Same route shape as the server-minted one
+ * (`/preview/<tenant>/pr/<N>`) by construction — see
+ * docs/architecture/preview-candidate-workflow.md — so the link doesn't change
+ * out from under the reviewer once the build completes; it just starts
+ * resolving.
+ * Trims a trailing slash off `base` so a `TOT_STOREFRONT_URL` set WITH or
+ * without one composes identically. Pure — unit-tested.
+ * @param {string} base  storefront origin, e.g. https://storefront.tokenoftrust.store
+ * @param {string} tenant
+ * @param {number} prNumber
+ * @returns {string}
+ */
+export function shareablePrUrl(base, tenant, prNumber) {
+  return `${String(base).replace(/\/+$/, "")}/preview/${tenant}/pr/${prNumber}`;
+}
+
 /**
  * Build the printed lines for the headline "share this with your reviewer" block —
  * the whole point of U14: on a successful preview, the SHAREABLE deep link
@@ -1025,41 +1341,91 @@ export function formatShareableUrlBlock(s, tenant) {
   return [];
 }
 
+/**
+ * The honest "no reconcile job was dispatched" block — printed when a preview stays
+ * `pending` with no webhook delivery ever observed for the commit (pollPreviewStatus
+ * tagged it `notDispatched`). This replaces the old "reconcile still running — check
+ * back / re-submit" lie for the dead-end case: re-submitting cannot help, so we say
+ * what actually happened and what to do, and never recommend another submit. Pure —
+ * unit-tested. `verb` brands the copy with whatever the developer typed.
+ * @param {{ commit?: string|null, ref?: string|null }} ctx
+ * @param {string} tenant @param {string} [verb]
+ * @returns {string[]}
+ */
+export function formatNotDispatchedBlock({ commit = null, ref = null } = {}, tenant, verb = "preview") {
+  const short = commit ? commit.slice(0, 9) : "(unknown commit)";
+  return [
+    `\n  ⚠ No reconcile was dispatched for ${short} on ${tenant}.`,
+    `    Your push landed${ref ? ` on ${ref}` : ""}, but nothing picked it up to build a preview —`,
+    `    re-running \`tot ${verb}\` will NOT change that. This usually means one of:`,
+    `      • the store's reconcile webhook isn't registered yet (an operator must (re-)provision it), or`,
+    `      • your session is scoped to a different store than the one you pushed.`,
+    `    Next:`,
+    `      • \`tot grants\` — confirm ${tenant} is active for you;`,
+    `      • check the preview dashboard for ${tenant} (it will read "Last reconcile: never" until a job runs);`,
+    `      • if it stays "never", share this with support: commit ${short}, tenant ${tenant}${ref ? `, ref ${ref}` : ""}.`,
+  ];
+}
+
 /**
  * Print the reconcile/compliance/preview result and, on a clean reconcile with a
- * preview URL, open it in the browser (unless opts.open === false).
+ * preview URL, open it in the browser (unless opts.open === false). `quiet`
+ * (--json) suppresses ALL printing here — the browser open still runs unless
+ * the caller also passes `open: false` (run() passes `open: false` under
+ * --json — automation doesn't want a browser popping up). `commit`/`ref`/`verb`
+ * feed the honest never-dispatched block.
  */
-function reportStatus(s, tenant, { open = true } = {}) {
+function reportStatus(s, tenant, { open = true, quiet = false, commit = null, ref = null, verb = "preview" } = {}) {
   if (!s || s.status === "unknown") {
-    console.log(
-      `  (this MCP doesn't return the per-commit reconcile result yet — your push is in;\n` +
-        `   the preview updates once reconcile runs. Check the preview dashboard.)`,
-    );
+    if (!quiet) {
+      console.log(
+        `  (this MCP doesn't return the per-commit reconcile result yet — your push is in;\n` +
+          `   the preview updates once reconcile runs. Check the preview dashboard.)`,
+      );
+    }
     return;
   }
-  if (s.status === "pending") {
-    console.log(`  reconcile still running for ${tenant} — check back shortly (re-run \`tot submit --no-wait\`).`);
+  // Never-dispatched dead-end — the honest replacement for false "still reconciling".
+  if (s.notDispatched) {
+    if (!quiet) for (const line of formatNotDispatchedBlock({ commit, ref }, tenant, verb)) console.log(line);
     return;
   }
-  const rc = s.reconcile;
-  if (rc) {
-    if (rc.ok) console.log(`  ✓ reconcile ok`);
-    else {
-      console.log(`  ✗ reconcile failed:`);
-      for (const e of rc.errors ?? []) console.log(`      [${e.rule ?? "?"}] ${e.message ?? ""}`);
+  if (s.status === "pending") {
+    if (!quiet) {
+      // Dispatched but not yet reported (real slow reconcile) vs. no job seen yet on
+      // a --no-wait snapshot — say which, and never claim progress we can't see.
+      if (s.dispatched === false) {
+        console.log(`  no reconcile job seen yet for ${tenant} — if it doesn't appear shortly, run \`tot grants\` / check the dashboard.`);
+      } else {
+        console.log(`  reconcile still running for ${tenant} — check back shortly (re-run \`tot submit --no-wait\`).`);
+        if (s.delivery?.drift) {
+          console.log(`  ⚠ a reconcile report exists for a DIFFERENT commit than you pushed — possible tenant-scope mismatch (\`tot grants\` to check your active store).`);
+        }
+      }
     }
+    return;
   }
-  if (s.compliance?.verdict) {
-    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.`);
+  if (!quiet) {
+    const rc = s.reconcile;
+    if (rc) {
+      if (rc.ok) console.log(`  ✓ reconcile ok`);
+      else {
+        console.log(`  ✗ reconcile failed:`);
+        for (const e of rc.errors ?? []) console.log(`      [${e.rule ?? "?"}] ${e.message ?? ""}`);
+      }
+    }
+    if (s.compliance?.verdict) {
+      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.`);
+    }
+    for (const line of formatShareableUrlBlock(s, tenant)) console.log(line);
   }
-  for (const line of formatShareableUrlBlock(s, tenant)) console.log(line);
   if (s.previewUrl && open && s.status === "reconciled" && openBrowser(s.previewUrl)) {
-    console.log("  (opened in your browser)");
+    if (!quiet) console.log("  (opened in your browser)");
   }
 }