@tokenoftrust/cli 1.4.0-rc.9 → 1.4.1

package/src/commands/submit.mjs

@@ -3,7 +3,9 @@
  *
  * From inside a tenant checkout:
  *   1. validate locally and refuse on errors (fail fast before anything leaves the machine),
- *   2. push your committed work to the tenant repo's `preview` ref (triggers reconcile),
+ *   2. push your committed work to YOUR OWN isolated candidate ref — `candidate/<changeId>`
+ *      (b03 — no shared `preview` ref is ever force-pushed; an explicit `--ref` can still
+ *      target a literal ref name for back-compat) — which triggers reconcile,
  *   2b. open/update a PR-BACKED CANDIDATE for the same committed diff (g1b's
  *       `candidate_open`, unit c1 — the local-dev-loop half of the "PR-Backed Hosted
  *       Review Loop" milestone, symmetric with the hosted s6 draft-as-PR path), and
@@ -38,27 +40,72 @@
  * 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";
 import { establishSession, AuthUnavailableError } from "../auth.mjs";
+import { checkoutTenant } from "./clone.mjs";
 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,
 } from "../candidate-state.mjs";
 
 const DEFAULT_MCP_URL = "https://mcp.tokenoftrust.com";
-const DEFAULT_REF = "preview";
+
+// 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),
+// which already names its PR-backed branch `candidate/<changeId>` (see
+// submitCandidate, below): the raw git push here and the PR-backed candidate it
+// opens always target the SAME branch, never two.
+export const CANDIDATE_REF_PREFIX = "candidate/";
+
+/** The isolated git ref a candidate's preview push lands under. Pure. */
+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) {
-  const a = { mcp: null, identity: null, ref: DEFAULT_REF, skipValidate: false, noWait: false, watch: false, noOpen: false, message: null, summary: null, new: false, help: false };
+  // `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, 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];
@@ -66,7 +113,11 @@ 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;
     else if (t === "--no-open") a.noOpen = true;
@@ -76,27 +127,51 @@ export function parseArgs(argv) {
   return a;
 }
 
-const USAGE = `tot submit — submit your store for preview
+/**
+ * Render the usage block for whichever verb invoked this flow. `preview` is the
+ * first-class verb; `submit`/`deploy` reach the same flow as teaching aliases, so
+ * the help they print names the verb the developer actually typed (see preview.mjs).
+ * @param {string} [verb]
+ */
+export function renderUsage(verb = "preview") {
+  return `tot ${verb} — submit your store for preview
 
-  tot submit                    validate → push the preview ref → stream the result
-  tot submit --new              open a NEW candidate PR instead of updating your open one
-  tot submit --watch            stay attached through reconcile + compliance + accept (long-poll)
-  tot submit --skip-validate    push without the local lint (not recommended)
-  tot submit --ref <name>       push ref (default: ${DEFAULT_REF})
-  tot submit -m "<title>"       one-line summary of what changed (the approver sees this)
-  tot submit --summary "<text>" longer description to accompany the title
-  tot submit --no-wait          push and exit without polling for the reconcile result
-  tot submit --no-open          don't open the preview URL in the browser on success
-  tot submit --mcp <url>        MCP base URL (default: env MCP_BASE_URL / TOT_MCP_URL)
+  tot ${verb}                    validate → push the preview ref → stream the result
+  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-submit UPDATES your open candidate PR (like pushing more commits
+  By default a re-run UPDATES your open candidate PR (like pushing more commits
   to a GitHub PR), rather than opening a new one each time. Use --new to fork a
-  fresh candidate PR; the next plain \`tot submit\` then updates THAT one. Manage your
+  fresh candidate PR; the next plain \`tot ${verb}\` then updates THAT one. Manage your
   open candidates with \`tot pr\` (list / view / close). If your candidate was already
-  merged or closed, a re-submit automatically opens a fresh one.
+  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
   what's live in preview) so the change record the approver reviews is never blank.`;
+}
 
 // Default bounded wait (~20s, matching the pre-E2 fixed poll's total budget) vs.
 // --watch's longer per-call long-poll + more attempts (~8 min ceiling) for a dev
@@ -130,14 +205,362 @@ 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) ───────────────────────────────
+
+/**
+ * The content trees `tot preview` may auto-commit on a dirty tree — and ONLY
+ * these. A store's reviewable content lives here; anything a developer edits
+ * OUTSIDE these (src/, config, stray files) is out of scope for an automatic
+ * commit and is REFUSED rather than silently swept in. Explicit paths only —
+ * never `git add -A`/`git add .`.
+ */
+export const KNOWN_CONTENT_TREES = ["content/", "public/", ".tot/"];
+export const KNOWN_CONTENT_FILES = ["theme.json"];
+
+/** Is this repo-relative path inside a known content tree (or the one known
+ *  top-level file)? Pure — unit-tested. */
+export function isKnownContentPath(path) {
+  const p = String(path).replace(/^\.\//, "");
+  return KNOWN_CONTENT_FILES.includes(p) || KNOWN_CONTENT_TREES.some((t) => p.startsWith(t));
+}
+
+/**
+ * Flatten `git status --porcelain` (v1) output to the ordered, deduped set of
+ * dirty repo-relative paths. Each line is `XY <path>`; a rename/copy is
+ * `XY <old> -> <new>` and contributes BOTH paths (the old one is being removed
+ * from its tree too, so it's part of the scope decision). Run with
+ * `core.quotePath=false` upstream so unicode paths arrive literal. Pure —
+ * unit-tested.
+ * @param {string} text
+ * @returns {string[]}
+ */
+export function parsePorcelainPaths(text) {
+  const seen = new Set();
+  const out = [];
+  for (const line of String(text).split("\n")) {
+    if (line.length < 4) continue; // "XY p" is the shortest real entry
+    const rest = line.slice(3);
+    const parts = rest.includes(" -> ") ? rest.split(" -> ") : [rest];
+    for (const raw of parts) {
+      const p = raw.trim();
+      if (p && !seen.has(p)) {
+        seen.add(p);
+        out.push(p);
+      }
+    }
+  }
+  return out;
+}
+
+/**
+ * Partition dirty paths into the known content trees vs everything else. Pure —
+ * unit-tested.
+ * @param {string[]} paths
+ * @returns {{ known: string[], unknown: string[] }}
+ */
+export function classifyDirtyPaths(paths) {
+  const known = [];
+  const unknown = [];
+  for (const p of paths) (isKnownContentPath(p) ? known : unknown).push(p);
+  return { known, unknown };
+}
+
+/** A concise auto commit subject when the developer gave no -m — derived from the
+ *  staged files so the commit is never a blank "(untitled change)". Pure. */
+export function autoCommitSubject(files = []) {
+  if (files.length === 0) return "update store content";
+  if (files.length === 1) return `update ${files[0]}`;
+  return `update ${files.length} content files`;
+}
+
+/**
+ * The message for `tot preview`'s pre-preview auto-commit. An explicit `-m` wins
+ * as the subject; otherwise autoCommitSubject derives one from the staged files.
+ * The body (shortstat + file list) is built by the SAME buildChangeSummary the
+ * approver summary uses, so a commit and the change record it later feeds read
+ * consistently. Returns a git commit message (subject, blank line, body). Pure —
+ * unit-tested.
+ * @param {{ message?: string|null, files?: string[], statLine?: string }} input
+ * @returns {string}
+ */
+export function buildAutoCommitMessage({ message, files = [], statLine = "" } = {}) {
+  const subject = (message && message.trim()) || autoCommitSubject(files);
+  const { body } = buildChangeSummary({ message: subject, 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
+ * reflects your working changes — but ONLY the known trees (content/, public/,
+ * theme.json, .tot/), staged by EXPLICIT path (never `git add -A`). If anything
+ * dirty falls OUTSIDE those, it REFUSES (out-of-scope src/config/stray edits are
+ * never silently swept into a store commit). --no-commit opts out entirely
+ * (preview whatever's already committed — u1's behavior).
+ *
+ * Returns exactly one of:
+ *   { 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, workspace?: string }} [opts]
+ */
+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 };
+  const { known, unknown } = classifyDirtyPaths(dirty);
+  if (unknown.length) return { refused: true, unknown, known };
+  // Stage ONLY the known dirty paths, each by explicit path — this records adds,
+  // modifications AND deletions within them, and can never reach outside the set.
+  git(["add", "--", ...known]);
+  const files = parseNameStatus(git(["diff", "--cached", "--name-status"])).map((e) => e.path);
+  const statLine = git(["diff", "--cached", "--shortstat"]).trim();
+  const msg = buildAutoCommitMessage({ message, files, statLine });
+  git(["commit", "--no-verify", "-m", msg]);
+  const sha = git(["rev-parse", "HEAD"]).trim();
+  return { committed: true, sha, files };
+}
+
 // ─── PR-backed candidate (g1b candidate_open, unit c1) ──────────────────────────
 
 /**
@@ -185,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 }
@@ -213,22 +636,138 @@ export function repoNameFromRemote(remoteUrl) {
   }
 }
 
+// ─── fresh-forge-credential push (decision B — the invited-dev 401 dead-end) ─────
+
+// 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
+ * push's stderr, so `tot preview` can re-mint a fresh credential and retry once
+ * rather than dead-ending on a stale token (the belt-and-suspenders half of
+ * decision B). Pure — unit-tested.
+ * @param {string} text
+ * @returns {boolean}
+ */
+export function isForgeAuthError(text) {
+  return /\b40[13]\b|failed to authenticate|authentication failed|invalid credentials|access denied/i.test(
+    String(text || ""),
+  );
+}
+
+/**
+ * Derive the checkout's forge tag from its repo name (`"<tenant>-<tag>"`), so a
+ * re-mint targets the SAME repo the checkout points at. Defaults to "main" when the
+ * repo is bare (`"<tenant>"`, post-8425) or the `<tenant>-` prefix doesn't match, so
+ * the mint degrades to the clone default rather than a wrong tag. Pure —
+ * unit-tested.
+ * @param {string|null} repoName
+ * @param {string} tenant
+ * @returns {string}
+ */
+export function tagFromRepoName(repoName, tenant) {
+  const r = String(repoName || "");
+  const prefix = `${tenant}-`;
+  return r.startsWith(prefix) && r.length > prefix.length ? r.slice(prefix.length) : "main";
+}
+
 /**
- * A STABLE per-developer-per-tenant candidate handle — so repeat `tot submit`
- * runs update the SAME PR instead of opening a new one each time
+ * Push the preview ref (decision B): mint a FRESH, short-lived forge credential
+ * right before the push and hand it to git EPHEMERALLY (via `http.extraheader` on
+ * a per-invocation `-c` — never written to `.git/config`), re-minting once on an
+ * auth failure. The push credential the MCP baked into `.git/config` at clone time
+ * expires within hours; reusing that stale embedded token is the invited-dev
+ * "`tot preview` → Gitea 401 dead-end". We push over the named `origin` remote with
+ * its URL overridden to the tokenless public URL for this one invocation, so the
+ * remote-tracking ref still updates while no long-lived secret lands on disk.
+ *
+ * When the mint is unavailable (older MCP, transient failure — `mintRemote` returns
+ * null) or the minted URL carries no parseable token, it falls back to pushing over
+ * the checkout's EXISTING remote (pre-B behavior) — no regression.
+ *
+ * @param {(cargs:string[])=>string} git  throwing git runner (execFileSync-backed)
+ * @param {() => Promise<string|null>} mintRemote  mints a fresh authed gitRemote (null when unavailable)
+ * @param {{ ref: string }} opts
+ * @returns {Promise<{ out: string }>}  resolves on a successful push; throws (git's error) otherwise
+ */
+export async function pushPreviewRef(git, mintRemote, { ref } = {}) {
+  const attempt = (remote) => {
+    const cred = splitAuthedRemote(remote);
+    if (!cred) {
+      // No fresh credential to hand over — push over the checkout's existing remote.
+      return git(["push", "-f", "origin", `HEAD:refs/heads/${ref}`]);
+    }
+    // Ephemeral auth: override the remote URL to the tokenless public URL and supply
+    // the credential as a one-shot Authorization header, with any OS credential
+    // helper disabled — none of this touches `.git/config`.
+    return git([
+      "-c", `remote.origin.url=${cred.publicUrl}`,
+      "-c", `http.extraheader=${basicAuthExtraHeader(cred.username, cred.token)}`,
+      "-c", "credential.helper=",
+      "push", "-f", "origin", `HEAD:refs/heads/${ref}`,
+    ]);
+  };
+
+  const remote = await mintRemote();
+  try {
+    return { out: attempt(remote) };
+  } catch (e) {
+    if (!isForgeAuthError(e?.stderr || e?.message || e)) throw e;
+    // Belt-and-suspenders: an auth failure re-mints a fresh credential and retries once.
+    return { out: attempt(await mintRemote()) };
+  }
+}
+
+/**
+ * A STABLE per-developer-per-tenant(-per-branch) candidate handle — so repeat
+ * `tot submit` runs update the SAME PR instead of opening a new one each time
  * (`candidate_open` is idempotent on `changeId`). No local state file needed:
- * it's a deterministic hash of the tenant + the acting identity, recomputed
- * fresh every run. Two different developers submitting to the same tenant get
- * two different (non-colliding) candidates. Pure — unit-tested.
+ * it's a deterministic hash of the tenant + the acting identity (+ the git branch
+ * on a non-default branch), recomputed fresh every run. Two different developers
+ * submitting to the same tenant get two different (non-colliding) candidates; so
+ * do the SAME developer on two different feature branches (u4 — branch-bound
+ * candidates), so `git checkout` acts as the PR switcher.
+ *
+ * ZERO MIGRATION: on the DEFAULT branch (main/master, or an unresolvable branch)
+ * the hash material is `tenant|actorKey` — byte-identical to the pre-u4 id — so an
+ * existing dev's current candidate keeps working untouched. A non-default branch
+ * folds the branch into the material (`tenant|actorKey|branch`) for its own id.
+ * Pure — unit-tested.
  * @param {string} tenant
  * @param {string} actorKey
+ * @param {string|null} [branch]  current git branch; default/null ⇒ today's id
  * @returns {string}
  */
-export function deriveChangeId(tenant, actorKey) {
-  const hash = createHash("sha256").update(`${tenant}|${actorKey}`).digest("hex").slice(0, 16);
+export function deriveChangeId(tenant, actorKey, branch = null) {
+  const material = isDefaultBranch(branch) ? `${tenant}|${actorKey}` : `${tenant}|${actorKey}|${branch}`;
+  const hash = createHash("sha256").update(material).digest("hex").slice(0, 16);
   return `local-${hash}`;
 }
 
+/**
+ * The current git branch in `workspace`, or null when it can't be resolved (a
+ * detached HEAD reports "HEAD", and any git failure is swallowed) — null is read
+ * by `isDefaultBranch` as the default branch, so an unresolvable branch keeps
+ * today's (branch-less) candidate rather than minting a spurious namespace. `git`
+ * is injected (a `(args:string[])=>string` runner) so it's testable. Best-effort.
+ * @param {(args:string[]) => string} git
+ * @returns {string|null}
+ */
+export function currentBranch(git) {
+  try {
+    const b = git(["rev-parse", "--abbrev-ref", "HEAD"]).trim();
+    return b && b !== "HEAD" ? b : null;
+  } catch {
+    return null;
+  }
+}
+
 /** The stable identity key behind `deriveChangeId` — the signed-in developer's
  *  email, falling back to the token, then a generic label. Single-plane: the only
  *  identity `tot` carries is the developer's own OAuth session. */
@@ -236,6 +775,97 @@ export function actorKeyFor(session) {
   return session?.email || session?.token || "developer";
 }
 
+/**
+ * Which candidate this submit lands on (gh-pr-like) — decided UP FRONT, before any
+ * network call, because it also determines the isolated git ref we push to
+ * (resolvePushRef, below): a re-submit updates the SAME candidate/ref by default;
+ * `--new` forks a fresh one.
+ *   --new     → fork a FRESH candidate id;
+ *   otherwise → the remembered active candidate (from a prior --new / terminal
+ *               roll), else the STABLE per-dev-per-tenant(-per-branch) default.
+ * `persist` reports whether the choice diverges from the stable default, so the
+ * caller knows whether to remember it as the new active pointer. `mint` is
+ * injected (defaults to mintFreshChangeId) so this is pure/deterministic in tests.
+ * Pure — unit-tested.
+ * @param {{ tenant: string, actorKey: string, branch?: string|null, active?: string|null,
+ *   isNew?: boolean, mint?: (baseId: string) => string }} opts
+ * @returns {{ changeId: string, stableId: string, persist: boolean }}
+ */
+export function chooseChangeId({ tenant, actorKey, branch = null, active = null, isNew = false, mint = mintFreshChangeId }) {
+  const stableId = deriveChangeId(tenant, actorKey, branch);
+  const changeId = isNew ? mint(stableId) : (active || stableId);
+  const persist = isNew || (!!active && active !== stableId);
+  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 /
+ * back-compat path (e.g. `--ref preview` reproduces the old shared-ref push for
+ * any tooling that still reads it by that literal name); otherwise it's YOUR OWN
+ * isolated candidate ref, so two developers — or the same developer on two
+ * branches — never force-push over each other or each other's preview. Pure —
+ * unit-tested.
+ * @param {{ ref?: string|null, changeId: string }} opts
+ * @returns {string}
+ */
+export function resolvePushRef({ ref, changeId }) {
+  return ref || candidateRefFor(changeId);
+}
+
 /**
  * Open/update the PR-backed candidate for this submit (g1b `candidate_open`,
  * unit c1 — the local-dev-loop half of the "PR-Backed Hosted Review Loop"
@@ -248,17 +878,19 @@ export function actorKeyFor(session) {
  * 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", {
@@ -271,57 +903,244 @@ 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}`);
 }
 
-/** @param {string[]} argv @param {any} ctx */
-export async function run(argv, ctx) {
+/**
+ * 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" } = {}) {
   const env = process.env;
   const args = parseArgs(argv);
   if (args.help) {
-    console.log(USAGE);
+    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 submit` 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
+  //    `git add -A`); anything dirty outside those is refused, not silently swept in.
+  //    --no-commit opts out (preview whatever's already committed).
+  let auto;
+  try {
+    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(
+        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) {
+    console.error(
+      fail(
+        `${auto.unknown.length} change(s) are outside the store content trees — refusing to auto-commit`,
+        "commit (or stash/revert) those yourself, then re-run — or use --no-commit to preview only what's already committed",
+      ) + "\n",
+    );
+    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) {
+    console.error(
+      `~ auto-committed ${auto.sha.slice(0, 9)} (${auto.files.length} content file(s)) — pass -m "…" to set the message, --no-commit to skip`,
+    );
+  }
+
   // 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)");
@@ -332,7 +1151,9 @@ export async function run(argv, ctx) {
   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);
@@ -344,6 +1165,9 @@ export async function run(argv, ctx) {
   // same diff (name-status, so candidate_open also knows adds/deletes/renames)
   // doubles as the source of the PR-backed candidate's file patch (step 2b, below)
   // — one git read, two consumers, so the PR always matches what's printed here.
+  // Parameterized on `ref` (b03 — isolated candidate refs): the diff base is YOUR
+  // candidate ref's own tracking ref, not a shared one, so the summary always reads
+  // "vs your own last push" once the push ref is known (computed just below).
   const gitSafe = (cargs) => {
     try {
       return git(cargs);
@@ -351,83 +1175,204 @@ export async function run(argv, ctx) {
       return "";
     }
   };
-  const headSubject = gitSafe(["log", "-1", "--format=%s"]).trim();
-  const trackingRef = `refs/remotes/origin/${args.ref}`;
-  const base = gitSafe(["rev-parse", "--verify", "--quiet", trackingRef]).trim()
-    ? trackingRef
-    : gitSafe(["rev-parse", "--verify", "--quiet", "HEAD~1"]).trim()
-      ? "HEAD~1"
-      : "";
-  const statusCmd = base ? ["diff", "--name-status", `${base}..HEAD`] : ["show", "--name-status", "--format=", "HEAD"];
-  const patchEntries = parseNameStatus(gitSafe(statusCmd));
-  const files = patchEntries.map((e) => e.path);
-  const statLine = base ? gitSafe(["diff", "--shortstat", `${base}..HEAD`]).trim() : "";
-  const changeSummary = buildChangeSummary({ message: args.message, summary: args.summary, headSubject, statLine, files });
-
-  console.error(`~ pushing ${short} → ${args.ref} (origin)`);
+  function buildSummaryAndPatch(ref) {
+    const headSubject = gitSafe(["log", "-1", "--format=%s"]).trim();
+    const trackingRef = `refs/remotes/origin/${ref}`;
+    const base = gitSafe(["rev-parse", "--verify", "--quiet", trackingRef]).trim()
+      ? trackingRef
+      : gitSafe(["rev-parse", "--verify", "--quiet", "HEAD~1"]).trim()
+        ? "HEAD~1"
+        : "";
+    const statusCmd = base ? ["diff", "--name-status", `${base}..HEAD`] : ["show", "--name-status", "--format=", "HEAD"];
+    const patchEntries = parseNameStatus(gitSafe(statusCmd));
+    const files = patchEntries.map((e) => e.path);
+    const statLine = base ? gitSafe(["diff", "--shortstat", `${base}..HEAD`]).trim() : "";
+    const changeSummary = buildChangeSummary({ message: args.message, summary: args.summary, headSubject, statLine, files });
+    return { changeSummary, patchEntries };
+  }
+
+  // The MCP session is needed BOTH to mint a fresh forge push credential (decision
+  // B — right below) and for the candidate/preview read-back after, so establish it
+  // ONCE, up front, and reuse it for the whole flow.
+  const baseUrl = args.mcp || env.MCP_BASE_URL || env.TOT_MCP_URL || DEFAULT_MCP_URL;
+  const client = createMcpClient(baseUrl);
+  const repo = repoNameFromRemote(gitSafe(["remote", "get-url", "origin"]).trim());
+
+  // Branch-bound (u4) + the isolated candidate ref (b03): resolved BEFORE the push,
+  // since the push target itself depends on it — so the raw git push and the
+  // PR-backed candidate (step 2b, below) always land on the SAME branch. `active`/
+  // `statePath` are local filesystem reads (candidate-state.mjs) — no session
+  // needed — so they're available even on the no-session fallback path below.
+  const branch = currentBranch(gitSafe);
+  const statePath = defaultCandidateStatePath(env);
+  let active = repo ? readActiveChangeId(statePath, { mcpUrl: baseUrl, repo, branch }) : null;
+
+  let session;
   try {
-    const out = git(["push", "-f", "origin", `HEAD:refs/heads/${args.ref}`]);
-    if (out.trim()) console.error(redactUrl(out.trim()));
+    session = await establishSession(client, { env, prefer: args.identity || undefined });
   } 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",
-      ),
-    );
+    // Not signed in / MCP unreachable — we can't mint a fresh credential, so fall
+    // back to pushing over the checkout's EXISTING embedded remote (pre-B behavior:
+    // no worse than before) and skip the read-back that needs a session. The push
+    // still lands if that embedded token is live. actorKeyFor(null) degrades to the
+    // generic "developer" key — still isolated PER BRANCH (never the shared ref),
+    // just not per-developer until sign-in succeeds.
+    const { changeId } = chooseChangeId({ tenant, actorKey: actorKeyFor(null), branch, active, isNew: args.new });
+    const ref = resolvePushRef({ ref: args.ref, changeId });
+    const { changeSummary } = buildSummaryAndPatch(ref);
+    console.error(`~ pushing ${short} → ${ref} (origin)`);
+    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) {
+      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;
+    }
+    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.`);
+    }
+    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
+  // different branches. See chooseChangeId's doc for the --new / active-pointer
+  // rules.
+  let { changeId, stableId, persist } = chooseChangeId({ tenant, actorKey: actorKeyFor(session), branch, active, isNew: args.new });
+  const ref = resolvePushRef({ ref: args.ref, changeId });
+  const { changeSummary, patchEntries } = buildSummaryAndPatch(ref);
+
+  // 2. push the preview ref with a FRESHLY-MINTED, short-lived forge credential
+  //    (decision B). The token baked into `.git/config` at clone time expires within
+  //    hours, so we re-mint right before the push and hand it to git ephemerally
+  //    (never persisted to `.git/config`), re-minting once on an auth failure.
+  //    `checkoutTenant(cloneDir:null)` mints without re-cloning AND client_switch()es,
+  //    binding the tenant scope the candidate/preview read-back below reads.
+  const tag = tagFromRepoName(repo, tenant);
+  const mintRemote = async () => {
+    try {
+      const res = await checkoutTenant(client, { tenant, tag, cloneDir: null, redact: redactUrl });
+      return res.gitRemote || null;
+    } catch (e) {
+      console.error(
+        `~ couldn't mint a fresh push credential (${redactUrl(String(e?.message || e))}) — using the checkout's remote`,
+      );
+      return null;
+    }
+  };
+
+  console.error(`~ pushing ${short} → ${ref} (origin, fresh credential)`);
+  try {
+    const { out } = await pushPreviewRef(git, mintRemote, { ref });
+    if (out && out.trim()) console.error(redactUrl(out.trim()));
+    emitGitOp("push", true, { command: verb });
+  } catch (e) {
+    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 ${args.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 (both graceful seams, same session).
-  const baseUrl = args.mcp || env.MCP_BASE_URL || env.TOT_MCP_URL || DEFAULT_MCP_URL;
-  const client = createMcpClient(baseUrl);
+  // compliance + preview URL from the MCP — reusing the session established above.
   let progress = null;
   try {
-    // Attach auth before the first server call (developer bearer pre-initialize,
-    // operator credential_validate post-initialize) — see establishSession.
-    const session = await establishSession(client, { env, prefer: args.identity || undefined });
-    // Set the active tenant so preview_status/candidate_open read the right scope
-    // (both key on the session's bound tenant/app — no tenant arg of their own).
+    // Bind the active tenant so preview_status/candidate_open read the right scope
+    // (idempotent — checkoutTenant already switched when the fresh mint succeeded).
     await client.callTool("client_switch", { tenant });
 
     // 2b. PR-backed candidate (g1b candidate_open, unit c1) — best-effort: a
     // failure here (older MCP, VC not configured, preview-access capability) is
     // reported and swallowed, never blocking the preview push that already landed.
-    //
-    // Which candidate this submit lands on (gh-pr-like):
-    //   --new           → fork a FRESH candidate and remember it as active;
-    //   otherwise       → the remembered active candidate (from a prior --new /
-    //                     roll), else the STABLE per-dev-per-tenant default.
-    // If the chosen candidate turns out to be merged/closed, roll to a fresh one
-    // so a re-submit is never wedged on a dead PR.
-    const repo = repoNameFromRemote(gitSafe(["remote", "get-url", "origin"]).trim());
+    // `changeId`/`stableId`/`persist` were already decided above (they picked the
+    // push ref too); if the chosen candidate turns out to be merged/closed, roll to
+    // a fresh one so a re-submit is never wedged on a dead PR. (`repo` was derived
+    // above.)
     const readBlob = (path) => execFileSync("git", ["-C", workspace, "show", `HEAD:${path}`], { stdio: ["ignore", "pipe", "pipe"] });
-    const statePath = defaultCandidateStatePath(env);
-    const stableId = deriveChangeId(tenant, actorKeyFor(session));
-    const active = repo ? readActiveChangeId(statePath, { mcpUrl: baseUrl, repo }) : null;
-    let changeId = args.new ? mintFreshChangeId(stableId) : (active || stableId);
-    // Persist when we diverge from the stable default (a --new fork, or a
-    // previously-remembered active pointer) so the next plain submit follows it.
-    let persist = args.new || (!!active && active !== stableId);
 
-    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;
     // never let a state-write failure break the submit).
     if (persist && repo && candidate && !isTerminalCandidateState(candidate.state)) {
       try {
-        writeActiveChangeId(statePath, { mcpUrl: baseUrl, repo, changeId });
+        writeActiveChangeId(statePath, { mcpUrl: baseUrl, repo, branch, changeId });
       } catch { /* best-effort local hint — a miss just re-derives the stable id */ }
     }
 
@@ -440,35 +1385,51 @@ export async function run(argv, ctx) {
       // 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;
   }
 }
@@ -476,20 +1437,31 @@ export async function run(argv, ctx) {
 /**
  * Normalize a `preview_status` tool response to the contract shape the CLI reports
  * on: { status, reconcile:{ok,errors}, compliance:{verdict,detail}, previewUrl,
- * shipped }. 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,
   };
 }
@@ -506,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;
 }
 
@@ -548,43 +1558,212 @@ 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
+ * (`https://storefront.tokenoftrust.store/preview/<tenant>/pr/<N>`, built server-side
+ * by the reconcile report and threaded through as `previewUrl`) is what a developer
+ * hands to a teammate, NOT the internal Gitea PR url `reportCandidate` prints earlier
+ * in the flow (step 2b) — that one stays as-is, secondary, for the developer's own
+ * reference. Labeled prominently + paired with an honest auth caveat: the share
+ * target is a TEAMMATE WITH STORE ACCESS (member/staff of the tenant), never a
+ * public/anonymous link.
+ *
+ * Degrades gracefully when `previewUrl` isn't (yet) on the status result — an older
+ * MCP, or a reconcile that hasn't finished minting it — with a note instead of a
+ * crash or a silent blank. Pure — unit-tested.
+ * @param {{ previewUrl?: string|null, status?: string }|null} s
+ * @param {string} tenant
+ * @returns {string[]}
+ */
+export function formatShareableUrlBlock(s, tenant) {
+  if (s?.previewUrl) {
+    return [
+      `\n  ✓ Preview ready — share this with your reviewer:`,
+      `      ${s.previewUrl}`,
+      `    ℹ your reviewer needs store access (a member/staff of ${tenant}) to view it — it's not a public link.`,
+    ];
+  }
+  if (s?.status === "reconciled") {
+    return [`\n  ~ reconciled, but no shareable preview URL yet — it'll show up here once available.`];
+  }
+  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 ?? ""}`);
-    }
-  }
-  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);
+  // 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.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 (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.previewUrl) {
-    console.log(`\n  Preview: ${s.previewUrl}`);
-    if (open && s.status === "reconciled" && openBrowser(s.previewUrl)) {
-      console.log("  (opened in your browser)");
+  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);
+  }
+  if (s.previewUrl && open && s.status === "reconciled" && openBrowser(s.previewUrl)) {
+    if (!quiet) console.log("  (opened in your browser)");
   }
 }