@tokenoftrust/cli 1.4.0 → 1.4.1

package/src/commands/submit.mjs

@@ -40,6 +40,8 @@
  * Dependency-free (global fetch + `git`).
  */
 import { execFileSync } from "node:child_process";
+import { readFileSync, existsSync } from "node:fs";
+import { resolve as resolvePath } from "node:path";
 import { createHash } from "node:crypto";
 import { setTimeout as delay } from "node:timers/promises";
 import { createMcpClient } from "../mcp.mjs";
@@ -49,10 +51,12 @@ import { validateTenant, ERROR } from "../validate.mjs";
 import { openBrowser } from "../open.mjs";
 import { startProgress } from "../progress.mjs";
 import { fail } from "../errors.mjs";
+import { emitActivity } from "../activity.mjs";
 import {
   defaultCandidateStatePath,
   readActiveChangeId,
   writeActiveChangeId,
+  clearActiveChangeId,
   mintFreshChangeId,
   isTerminalCandidateState,
   isDefaultBranch,
@@ -60,6 +64,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),
@@ -73,11 +84,28 @@ export function candidateRefFor(changeId) {
   return `${CANDIDATE_REF_PREFIX}${changeId}`;
 }
 
+/**
+ * D3: emit a git-op lifecycle event for `tot submit`/`tot preview` — one per git
+ * operation (commit / push), carrying its own success/failure, so the timeline sees
+ * the individual git steps, not just the outer command's invoked/result pair. Uses
+ * the `cli.command.result` catalog key with a `git.<op>` subcommand (a fixed, safe
+ * value). Fire-and-forget best-effort: a silent no-op without a hosted-bridge
+ * credential, never awaited, never throws, never alters the command. `errorClass` is
+ * a low-cardinality class (never a raw git stderr, which can carry a token/path).
+ */
+function emitGitOp(op, ok, { command = "submit", durationMs, errorClass } = {}) {
+  void emitActivity({
+    action: "cli.command.result",
+    outcome: { status: ok ? "succeeded" : "failed", ...(durationMs != null ? { durationMs } : {}), ...(errorClass ? { errorClass } : {}) },
+    payload: { args: { command, subcommand: `git.${op}`, ...(durationMs != null ? { durationMs } : {}) } },
+  });
+}
+
 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, skipFreshness: 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,7 +113,10 @@ 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 === "--skip-freshness") a.skipFreshness = true;
     else if (t === "--no-commit") a.noCommit = true;
     else if (t === "--no-wait") a.noWait = true;
     else if (t === "--watch") a.watch = true;
@@ -109,12 +140,22 @@ export function renderUsage(verb = "preview") {
   tot ${verb} --new              open a NEW candidate PR instead of updating your open one
   tot ${verb} --watch            stay attached through reconcile + compliance + accept (long-poll)
   tot ${verb} --skip-validate    push without the local lint (not recommended)
+  tot ${verb} --skip-freshness   skip the stale-base check (not recommended — may build a
+                                  candidate rooted in an already-superseded base)
   tot ${verb} --no-commit        don't auto-commit a dirty tree — preview only what's already committed
   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
@@ -123,6 +164,9 @@ export function renderUsage(verb = "preview") {
   open candidates with \`tot pr\` (list / view / close). If your candidate was already
   merged or closed, a re-run automatically opens a fresh one.
 
+  Working on one thing at a time? You don't need --new, a git branch, or any
+  branch management at all — just keep editing and re-running \`tot ${verb}\`.
+
   Once a preview reconciles cleanly, \`tot ship\` promotes it live.
 
   If you omit -m, a summary is generated from git (commit subject + the diff vs
@@ -161,14 +205,184 @@ 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");
+}
+
+// ─── stale-base freshness preflight (unit u16) ──────────────────────────────────
+
+/** The candidate base branch every submit targets (mirrors tot-mcp's own
+ *  `DEFAULT_CANDIDATE_BASE` and sync.mjs's `DEFAULT_SYNC_BRANCH` — the SAME
+ *  protected branch by three different names in three different modules; kept
+ *  a local constant here, not imported, since this file already resolves its
+ *  own defaults independently of sync.mjs and candidate_open's server default). */
+export const FRESHNESS_BASE_BRANCH = "preview";
+
+/**
+ * Detect a STALE local view of the base branch before minting a candidate —
+ * the live-repeat incident this guards against: the checkout's `origin/preview`
+ * tracking ref was stale (recorded before a just-merged PR moved it), so a
+ * fresh `tot preview --new` built a candidate rooted in the OLD tip and got an
+ * instant, entirely avoidable "not mergeable" the moment it was compared
+ * against the real, already-advanced `preview`.
+ *
+ * Compares what the LOCAL checkout believes the base's tip is
+ * (`refs/remotes/origin/<branch>`, only as fresh as the last explicit fetch)
+ * against its ACTUAL current tip on the forge (`git ls-remote`, a lightweight
+ * single-ref read — no full fetch, no local ref mutated). Returns the live
+ * remote sha when local's cached view is behind it, or `null` when: the two
+ * already agree, there is no local tracking ref to compare against yet (a
+ * checkout that has simply never fetched this branch — never a false block on
+ * that), or the remote can't be reached right now (a network hiccup must
+ * never block a submit that would otherwise succeed; the push itself is the
+ * real connectivity test). Pure git I/O via the injected runner — unit-tested.
+ * @param {(cargs:string[])=>string} git
+ * @param {string} branch
+ * @returns {string|null}
+ */
+export function detectStaleBase(git, branch) {
+  let localSha = "";
+  try {
+    localSha = git(["rev-parse", "-q", "--verify", `refs/remotes/origin/${branch}`]).trim();
+  } catch {
+    return null; // never fetched this branch locally — nothing cached to be stale
+  }
+  if (!localSha) return null;
+  let remoteSha = "";
+  try {
+    remoteSha = (git(["ls-remote", "origin", branch]).split(/\s+/)[0] || "").trim();
+  } catch {
+    return null; // can't reach the remote right now — don't block on a network hiccup
+  }
+  if (!remoteSha || remoteSha === localSha) return null;
+  return remoteSha;
+}
+
 // ─── auto-commit the known content trees (unit u2) ───────────────────────────────
 
 /**
@@ -253,6 +467,59 @@ export function buildAutoCommitMessage({ message, files = [], statLine = "" } =
   return body.length ? `${subject}\n\n${body.join("\n")}` : subject;
 }
 
+/**
+ * Detect an in-progress rebase, merge, or cherry-pick in the workspace (unit u8) —
+ * `tot preview`/`tot submit` must NEVER auto-commit over one of these. A rebase that
+ * stopped at "Could not apply" (or a merge/cherry-pick left with real conflicts) IS
+ * a dirty tree from `git status`'s point of view, so `autoCommitKnownTrees` would
+ * otherwise stage + commit the half-resolved content straight into a plain "content
+ * update" commit — silently finishing the git operation WRONG and losing whatever
+ * edit was still sitting in conflict markers or unresolved hunks (the live incident
+ * this guards against: a stalled rebase was never continued, `tot preview` ran
+ * anyway, and the developer's own edit was gone). Detection is worktree-safe:
+ * MERGE_HEAD/CHERRY_PICK_HEAD via plumbing refs (no direct `.git` path assumption),
+ * and rebase-merge/rebase-apply via `--git-path` (a linked worktree's git-dir lives
+ * OUTSIDE `<workspace>/.git`, so a literal `.git/rebase-merge` check would miss it).
+ * Returns which operation is in progress, or null when the tree is clean of one.
+ * @param {(cargs:string[])=>string} git  a `git -C <workspace>` runner
+ * @param {string} workspace  absolute path `git` runs `-C` against — `--git-path`'s
+ *   output may be relative, and Node's `existsSync` resolves relative paths against
+ *   the CLI process's own cwd, not the checkout, so this pins the resolution base.
+ * @returns {"rebase"|"merge"|"cherry-pick"|null}
+ */
+export function detectInProgressGitOperation(git, workspace) {
+  const hasRef = (name) => {
+    try {
+      return git(["rev-parse", "-q", "--verify", name]).trim().length > 0;
+    } catch {
+      return false;
+    }
+  };
+  if (hasRef("MERGE_HEAD")) return "merge";
+  if (hasRef("CHERRY_PICK_HEAD")) return "cherry-pick";
+  const hasGitPath = (name) => {
+    try {
+      const p = git(["rev-parse", "--git-path", name]).trim();
+      // An empty result should never happen for a real `--git-path` (it always
+      // echoes SOME path, existing or not) — but treat it as "absent" rather than
+      // resolving it, since `resolvePath(workspace, "")` degrades to `workspace`
+      // itself, which trivially always exists (a false "rebase in progress" on
+      // every call, not just an occasional false negative).
+      return p.length > 0 && existsSync(resolvePath(workspace, p));
+    } catch {
+      return false;
+    }
+  };
+  if (hasGitPath("rebase-merge") || hasGitPath("rebase-apply")) return "rebase";
+  return null;
+}
+
+/** The abort command that recovers from each in-progress git operation, so the
+ *  refusal below can tell a developer exactly what to run. Pure. */
+export function abortCommandFor(op) {
+  return op === "merge" ? "git merge --abort" : op === "cherry-pick" ? "git cherry-pick --abort" : "git rebase --abort";
+}
+
 /**
  * Auto-commit the known content trees before previewing (unit u2). On a DIRTY
  * tree `tot preview` commits your content edits for you, so a preview always
@@ -263,16 +530,21 @@ export function buildAutoCommitMessage({ message, files = [], statLine = "" } =
  * (preview whatever's already committed — u1's behavior).
  *
  * Returns exactly one of:
- *   { skipped: true }               — --no-commit.
- *   { clean: true }                 — nothing dirty; preview HEAD as-is.
- *   { refused, unknown, known }     — out-of-scope dirt; caller refuses + hints.
- *   { committed: true, sha, files } — staged the known dirty paths and committed.
+ *   { skipped: true }                 — --no-commit.
+ *   { inProgress: "rebase"|… }        — a rebase/merge/cherry-pick is unresolved;
+ *                                       caller refuses rather than auto-committing
+ *                                       over the developer's own half-resolved tree.
+ *   { clean: true }                   — nothing dirty; preview HEAD as-is.
+ *   { refused, unknown, known }       — out-of-scope dirt; caller refuses + hints.
+ *   { committed: true, sha, files }   — staged the known dirty paths and committed.
  *
  * @param {(cargs:string[])=>string} git  a `git -C <workspace>` runner
- * @param {{ message?: string|null, noCommit?: boolean }} [opts]
+ * @param {{ message?: string|null, noCommit?: boolean, workspace?: string }} [opts]
  */
-export function autoCommitKnownTrees(git, { message = null, noCommit = false } = {}) {
+export function autoCommitKnownTrees(git, { message = null, noCommit = false, workspace = "." } = {}) {
   if (noCommit) return { skipped: true };
+  const inProgress = detectInProgressGitOperation(git, workspace);
+  if (inProgress) return { inProgress };
   const status = git(["-c", "core.quotePath=false", "status", "--porcelain", "--untracked-files=all"]);
   const dirty = parsePorcelainPaths(status);
   if (dirty.length === 0) return { clean: true };
@@ -336,7 +608,7 @@ export function buildFilePatch(entries, readBlob) {
     }
     const buf = readBlob(e.path);
     const asUtf8 = buf.toString("utf8");
-    const isCleanUtf8 = !asUtf8.includes("") && Buffer.from(asUtf8, "utf8").equals(buf);
+    const isCleanUtf8 = !asUtf8.includes("\x00") && Buffer.from(asUtf8, "utf8").equals(buf);
     patch.push(
       isCleanUtf8
         ? { path: e.path, content: asUtf8 }
@@ -366,41 +638,14 @@ export function repoNameFromRemote(remoteUrl) {
 
 // ─── fresh-forge-credential push (decision B — the invited-dev 401 dead-end) ─────
 
-/**
- * Split an authenticated forge remote URL (basic-auth `user:token@host`, as the
- * MCP mints it via `tenant_checkout`) into its tokenless public URL + the embedded
- * credential, so the token can be handed to git EPHEMERALLY for one push instead of
- * being persisted in `.git/config`. Returns null when the URL won't parse or carries
- * no token — the caller then falls back to the checkout's existing remote. Pure —
- * unit-tested.
- * @param {string} remoteUrl
- * @returns {{ publicUrl: string, username: string, token: string }|null}
- */
-export function splitAuthedRemote(remoteUrl) {
-  try {
-    const u = new URL(String(remoteUrl));
-    const token = u.password ? decodeURIComponent(u.password) : "";
-    if (!token) return null;
-    const username = u.username ? decodeURIComponent(u.username) : "";
-    return { publicUrl: `${u.protocol}//${u.host}${u.pathname}`, username, token };
-  } catch {
-    return null;
-  }
-}
-
-/**
- * The `http.extraheader` value that hands a basic-auth credential to a SINGLE git
- * invocation (base64 of `user:token`) — so a freshly-minted forge token
- * authenticates one push without ever being written to `.git/config`. Pure —
- * unit-tested.
- * @param {string} username
- * @param {string} token
- * @returns {string}
- */
-export function basicAuthExtraHeader(username, token) {
-  const b64 = Buffer.from(`${username}:${token}`, "utf8").toString("base64");
-  return `Authorization: Basic ${b64}`;
-}
+// splitAuthedRemote / basicAuthExtraHeader now live in ../git-credential.mjs (unit
+// u10) — a dependency-free module BOTH this file and clone.mjs/commands/
+// git-credential.mjs need, so they moved out of here to avoid a submit.mjs ↔
+// clone.mjs import cycle. Re-exported so every existing import of these two names
+// FROM submit.mjs (this file's own callers below, plus tests) keeps working
+// unchanged.
+export { splitAuthedRemote, basicAuthExtraHeader } from "../git-credential.mjs";
+import { splitAuthedRemote, basicAuthExtraHeader, ensureTokenlessRemote } from "../git-credential.mjs";
 
 /**
  * Recognise a forge auth failure (expired / invalid push token) in a failed git
@@ -553,6 +798,59 @@ export function chooseChangeId({ tenant, actorKey, branch = null, active = null,
   return { changeId, stableId, persist };
 }
 
+/**
+ * The forge state of ONE candidate (`"open"`/`"merged"`/`"closed"`/…), read by
+ * changeId via `candidate_status`, or null when it can't be POSITIVELY determined —
+ * the candidate isn't found, carries no state, or the read throws. null ("couldn't
+ * tell") is the deliberately SAFE answer: the caller (resolveActivePointer) then
+ * behaves exactly as if the pointer were still live, so a purely-diagnostic check
+ * that can't run never blocks, changes, or crashes a submit (u17 acceptance #3).
+ * Tolerates the tool returning a bare candidate, a `{candidates:[…]}` list, or a
+ * plain array. Injectable client for tests.
+ * @param {{callTool:Function}} client
+ * @param {{ repo: string, changeId: string }} opts
+ * @returns {Promise<string|null>}
+ */
+export async function candidateStateFor(client, { repo, changeId }) {
+  try {
+    const r = await client.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 && typeof c.state === "string" ? c.state : null;
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * u17 — before REUSING a remembered active-candidate pointer, confirm its PR is
+ * still open. The live incident this guards against: after a candidate PR merged, a
+ * plain `tot preview` reused the remembered pointer, force-pushed onto the now-DEAD
+ * candidate branch (stale old-base history), and `candidate_open` opened a NEW PR
+ * from it — inheriting a guaranteed conflict from the very first commit. When the
+ * pointer's PR has gone terminal (merged/closed) we DROP it here, so `chooseChangeId`
+ * falls back to the stable per-branch id exactly as if no pointer existed.
+ *
+ * PURELY DIAGNOSTIC — never blocks a submit over the check itself: no pointer, no
+ * repo, or a check that errors / can't positively confirm terminal all resolve to
+ * `{ active }` UNCHANGED (behave exactly as before). Only a POSITIVELY terminal
+ * state drops the pointer. When it does, `dropped` carries the old changeId + the
+ * terminal state so the caller can tell the operator and forget the on-disk pointer.
+ * Injectable client for tests.
+ * @param {{callTool:Function}} client
+ * @param {{ repo: string|null, active: string|null }} opts
+ * @returns {Promise<{ active: string|null, dropped?: { changeId: string, state: string } }>}
+ */
+export async function resolveActivePointer(client, { repo, active }) {
+  if (!active || !repo) return { active };
+  const state = await candidateStateFor(client, { repo, changeId: active });
+  if (isTerminalCandidateState(state)) return { active: null, dropped: { changeId: active, state } };
+  return { active };
+}
+
 /**
  * The ref `tot preview`/`tot submit` pushes to (b03 — stop force-pushing the
  * SHARED `preview` ref). An explicit `--ref` always wins — the escape hatch /
@@ -580,17 +878,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 +903,103 @@ 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,
+    forwardFailed: status?.forwardFailed ?? 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,19 +1009,70 @@ 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;
   const tenant = ctx.tenant;
   const git = (cargs) => execFileSync("git", ["-C", workspace, ...cargs], { stdio: ["ignore", "pipe", "pipe"] }).toString();
 
+  // Self-heal a LEGACY checkout (unit u10): strip any token still embedded in
+  // `origin`'s URL and install the credential helper, so this run (and every one
+  // after) mints fresh creds through `tot` instead of relying on one that quietly
+  // expired. Best-effort — never blocks the actual preview on a migration hiccup.
+  try {
+    ensureTokenlessRemote(git);
+  } catch {
+    /* best-effort — see above */
+  }
+
+  // Freshness preflight (unit u16) — BEFORE minting anything: is the checkout's
+  // cached view of the base branch already behind the store? A candidate built
+  // on a stale base is an instant, avoidable "not mergeable" the moment the
+  // forge compares it against the real (already-advanced) base. --skip-freshness
+  // opts out (e.g. offline/CI, or a deliberate re-run against a known-good tip).
+  if (!args.skipFreshness) {
+    let staleTip = null;
+    try {
+      staleTip = detectStaleBase(git, FRESHNESS_BASE_BRANCH);
+    } catch {
+      staleTip = null; // never block a submit on the preflight's OWN failure
+    }
+    if (staleTip) {
+      const msg = `your checkout is behind the store — "${FRESHNESS_BASE_BRANCH}" has moved since your last sync`;
+      console.error(
+        fail(msg, `tot sync   (fetches the latest ${FRESHNESS_BASE_BRANCH} + merges it into your branch, then re-run \`tot ${verb}\`) — or re-run with --skip-freshness to build anyway`),
+      );
+      emitJson(args, buildJsonResult({ ok: false, error: msg }));
+      return 1;
+    }
+  }
+
+
   // 0. auto-commit the known content trees (unit u2) — on a dirty tree, commit your
   //    content edits BEFORE previewing so the preview reflects your working changes.
   //    Only content/, public/, theme.json, .tot/ (staged by explicit path, never
@@ -659,14 +1080,27 @@ export async function run(argv, ctx, { verb = "preview" } = {}) {
   //    --no-commit opts out (preview whatever's already committed).
   let auto;
   try {
-    auto = autoCommitKnownTrees(git, { message: args.message, noCommit: args.noCommit });
+    auto = autoCommitKnownTrees(git, { message: args.message, noCommit: args.noCommit, workspace });
   } catch (e) {
+    emitGitOp("commit", false, { command: verb, errorClass: "git_commit_failed" });
+    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.committed) emitGitOp("commit", true, { command: verb });
+  if (auto.inProgress) {
+    const abortCmd = abortCommandFor(auto.inProgress);
+    const msg = `a ${auto.inProgress} is still in progress here`;
     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",
+        msg,
+        `finish it (resolve + continue) or back out (\`${abortCmd}\`), then re-run \`tot ${verb}\` — `
+          + "auto-committing over an unresolved rebase/merge/cherry-pick would fold your half-resolved "
+          + "tree into a plain content commit and can lose whatever edit was still unresolved",
       ),
     );
+    emitJson(args, buildJsonResult({ ok: false, error: msg }));
     return 1;
   }
   if (auto.refused) {
@@ -679,6 +1113,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) {
@@ -690,12 +1125,22 @@ export async function run(argv, ctx, { verb = "preview" } = {}) {
   // 1. validate locally — refuse on errors.
   if (!args.skipValidate) {
     const { ok, findings } = validateTenant(workspace, { tenantId: tenant, scope: ctx.config?.scope });
+    // Advisory but LOUD: git conflict markers must never slip past as "validated"
+    // (the half-resolved-rebase incident). Surfaced on the ok path too — warnings
+    // are otherwise swallowed here — but they never block the submit.
+    const conflicts = findings.filter((f) => f.rule === "git-conflict-markers");
+    if (conflicts.length) {
+      console.error(`\n⚠ git conflict markers in submitted content (${conflicts.length} file(s)) — an unfinished merge/rebase?`);
+      for (const f of conflicts) console.error(`  ⚠ ${f.file} — ${f.message}`);
+      console.error("  The preview will still build, but it will serve the broken markers. Resolve before shipping.\n");
+    }
     if (!ok) {
       const errs = findings.filter((f) => f.level === ERROR);
       console.error(
         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 +1151,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);
@@ -758,7 +1205,7 @@ export async function run(argv, ctx, { verb = "preview" } = {}) {
   // needed — so they're available even on the no-session fallback path below.
   const branch = currentBranch(gitSafe);
   const statePath = defaultCandidateStatePath(env);
-  const active = repo ? readActiveChangeId(statePath, { mcpUrl: baseUrl, repo, branch }) : null;
+  let active = repo ? readActiveChangeId(statePath, { mcpUrl: baseUrl, repo, branch }) : null;
 
   let session;
   try {
@@ -777,26 +1224,62 @@ export async function run(argv, ctx, { verb = "preview" } = {}) {
     try {
       const out = git(["push", "-f", "origin", `HEAD:refs/heads/${ref}`]);
       if (out.trim()) console.error(redactUrl(out.trim()));
+      emitGitOp("push", true, { command: verb });
     } 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",
-        ),
-      );
+      emitGitOp("push", false, {
+        command: verb,
+        errorClass: isForgeAuthError(pushErr?.stderr || pushErr?.message || pushErr) ? "forge_auth" : "git_push_failed",
+      });
+      const msg = `push failed: ${redactUrl(String(pushErr.stderr || pushErr.message || pushErr))}`;
+      // This is the NO-SESSION path pushing the clone-time embedded credential —
+      // which rotation kills the moment any fresh mint happens elsewhere. An auth
+      // failure here is therefore almost always "you're not signed in IN THIS
+      // SHELL", not a network problem; the old remote-is-reachable hint sent a
+      // human down the wrong path live (Trello-13075 polish).
+      const hint = isForgeAuthError(pushErr?.stderr || pushErr?.message || pushErr)
+        ? "you're not signed in in this shell, and the checkout's embedded credential has likely been rotated — run `tot login` (check TOT_PROFILE if you use per-terminal identities), then re-run"
+        : "check your commit and that the checkout's remote is reachable, then re-run";
+      console.error(fail(msg, hint));
+      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: ${describeReadbackError(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;
   }
 
+  // u17 — before REUSING a remembered active pointer, confirm its PR is still open.
+  // If it merged/closed we DROP it (and forget it on disk) so chooseChangeId falls
+  // back to the stable id, rather than force-pushing onto a now-dead candidate branch
+  // and opening a NEW PR that inherits a guaranteed conflict (the live incident this
+  // guards against). Skipped under --new (chooseChangeId ignores `active` there
+  // anyway). Purely diagnostic: a check that errors leaves the pointer untouched.
+  // Needs the tenant scope bound for candidate_status to resolve — idempotent with
+  // the later client_switch / the fresh-mint checkoutTenant.
+  if (active && repo && !args.new) {
+    try {
+      await client.callTool("client_switch", { tenant });
+    } catch { /* scope bind is best-effort; candidateStateFor tolerates a miss */ }
+    const resolved = await resolveActivePointer(client, { repo, active });
+    if (resolved.dropped) {
+      console.error(
+        `~ remembered candidate ${resolved.dropped.changeId} is ${resolved.dropped.state} — dropping it and submitting fresh (a ${resolved.dropped.state} PR can't be reused).`,
+      );
+      try {
+        clearActiveChangeId(statePath, { mcpUrl: baseUrl, repo, branch });
+      } catch { /* best-effort local cleanup — a miss just re-checks next run */ }
+    }
+    active = resolved.active;
+  }
+
   // Which candidate (and therefore which isolated ref, b03) this submit targets —
   // decided now, with a real session, so the SAME id backs both the raw git push
   // (right below) and the PR-backed candidate (step 2b): the two never point at
@@ -829,17 +1312,19 @@ export async function run(argv, ctx, { verb = "preview" } = {}) {
   try {
     const { out } = await pushPreviewRef(git, mintRemote, { ref });
     if (out && out.trim()) console.error(redactUrl(out.trim()));
+    emitGitOp("push", true, { command: verb });
   } 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",
-      ),
-    );
+    emitGitOp("push", false, {
+      command: verb,
+      errorClass: isForgeAuthError(e?.stderr || e?.message || e) ? "forge_auth" : "git_push_failed",
+    });
+    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 +1343,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 +1385,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, noChanges: patchEntries.length === 0 });
+    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: ${describeReadbackError(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 +1437,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 +1478,67 @@ 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);
+    // Terminally-failed forward: the delivery record settled with forwarded:false
+    // (and it isn't the at-receipt `pending` marker) — the control plane could not
+    // deliver this commit to the reconciler, and polling longer cannot change that.
+    // Only a NEW push produces a new delivery. Stop and say so (Trello-13075
+    // honesty discipline: never spin on a state that cannot progress).
+    if (
+      last.status === "pending" &&
+      last.delivery?.actual &&
+      last.delivery.actual.forwarded === false &&
+      !last.delivery.actual.pending
+    ) {
+      return { ...last, forwardFailed: true };
+    }
+    // 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 +1558,58 @@ 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}`;
+}
+
+/**
+ * Humanize a result-read-back failure. MCP auth errors arrive as a JSON blob
+ * whose `data.self_repair` carries a summary + step list — dumping that raw
+ * into the terminal (observed live: a wall of escaped JSON mid-submit) buries
+ * the one thing the developer needs: sign in again. Detect that shape and
+ * reduce it to the summary's first sentence + the concrete next step; anything
+ * else passes through unchanged. Pure — unit-tested.
+ * @param {unknown} e
+ * @returns {string}
+ */
+export function describeReadbackError(e) {
+  const msg = String(e?.message || e || "");
+  const jsonStart = msg.indexOf("{");
+  if (jsonStart >= 0 && msg.includes("self_repair")) {
+    try {
+      const body = JSON.parse(msg.slice(jsonStart));
+      const repair = body?.data?.self_repair;
+      const summaryFirst = String(repair?.summary || body?.message || "").split(/(?<=\.)\s/)[0];
+      if (summaryFirst) {
+        return `${summaryFirst} Next: run \`tot login\` in this shell (check TOT_PROFILE), then re-run.`;
+      }
+    } catch {
+      // Not the shape we thought — fall through to the raw message.
+    }
+  }
+  return msg;
+}
+
 /**
  * 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 +1642,128 @@ 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, noChanges = false } = {}, tenant, verb = "preview") {
+  const short = commit ? commit.slice(0, 9) : "(unknown commit)";
+  // Empty-diff cause FIRST when we know it applies (live-testing finding: an
+  // empty candidate submit structurally CANNOT build — no diff → no candidate PR
+  // → no pull_request webhook — and blaming webhooks/scope for it sent a human
+  // down two wrong debugging paths).
+  const causes = [
+    ...(noChanges
+      ? [`      • your submit contained NO content changes — a candidate with no diff opens no PR and builds nothing (make an edit, or move the shared ref: \`tot ${verb} --ref preview\`),`]
+      : []),
+    `      • 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.`,
+  ];
+  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:`,
+    ...causes,
+    `    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}` : ""}.`,
+  ];
+}
+
+/**
+ * The honest "the delivery FAILED to forward" block — the delivery record settled
+ * `forwarded: false` (not the at-receipt pending marker), so the control plane
+ * could not deliver this commit to the reconciler; polling longer cannot change
+ * that, and ONLY a new push produces a new delivery. Distinct from
+ * `formatNotDispatchedBlock` (nothing was ever dispatched) — here the plumbing
+ * fired and died in transit, so the recovery differs. Pure — unit-tested.
+ * @param {{ commit?: string|null }} ctx @param {string} tenant
+ * @returns {string[]}
+ */
+export function formatForwardFailedBlock({ commit = null } = {}, tenant) {
+  const short = commit ? commit.slice(0, 9) : "(unknown commit)";
+  return [
+    `\n  ⚠ The reconcile delivery for ${short} on ${tenant} FAILED in transit (network/timeout at the control plane).`,
+    `    Waiting longer will not help — only a NEW push produces a new delivery.`,
+    `    Next: commit again (an empty commit works: git commit --allow-empty -m retry) and re-push;`,
+    `    if it fails the same way twice, share this with support: commit ${short}, tenant ${tenant}.`,
+  ];
+}
+
 /**
  * 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", noChanges = false } = {}) {
   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\`).`);
+  // Terminally-failed forward — the delivery fired and died in transit; a re-push
+  // (new delivery) is the only recovery. Checked BEFORE notDispatched: a settled
+  // failed forward IS a dispatch, just a doomed one.
+  if (s.forwardFailed) {
+    if (!quiet) for (const line of formatForwardFailedBlock({ commit }, tenant)) 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 ?? ""}`);
-    }
+  // Never-dispatched dead-end — the honest replacement for false "still reconciling".
+  if (s.notDispatched) {
+    if (!quiet) for (const line of formatNotDispatchedBlock({ commit, ref, noChanges }, tenant, verb)) console.log(line);
+    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.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.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)");
   }
 }