@tokenoftrust/cli 2.0.11 → 2.0.14

package/src/commands/submit.mjs

@@ -4,9 +4,8 @@
  * 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 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
+ *      (b03 — no shared `preview` ref is ever force-pushed) — which triggers reconcile,
+ *   2b. register that exact ref + asserted HEAD as a PR-BACKED CANDIDATE (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
  *       print the resulting changeId/PR number/URL,
@@ -14,14 +13,12 @@
  *
  * This is submit-for-PREVIEW, not ship-to-live (`change_accept`/`candidate_accept` /
  * a future `tot ship` is the separate ship gate — this command is submit-only, never
- * accept/reject). Step 2b remains best-effort for compatibility failures (older MCP,
- * version-control not configured, preview-access capability), but an attribution
- * refusal is REQUIRED and exits non-zero with identity-recovery guidance. The preview
- * push may already have landed, but no unaudited PR is created. Step 3 calls
+ * accept/reject). Step 2b fails closed: a push without an exact, verified PR registration
+ * exits non-zero and keeps its stable retry identity. Step 3 calls
  * the MCP `preview_status` read-back: given the commit just pushed it returns
  * { status, reconcile, compliance, previewUrl } and we poll it while reconcile is
- * pending. If that tool isn't present (older MCP) the command still validates +
- * pushes and reports "reconcile pending" — degrading visibly, never a crash.
+ * pending. A later read-back failure preserves the candidate receipt and returns a
+ * successful but explicitly degraded result with a diagnostic ID.
  *
  * Polling (E2): every call carries `waitMs` so a preview_status-aware MCP long-polls
  * (blocks up to waitMs, waking immediately on arrival) instead of us sleeping blind
@@ -57,6 +54,11 @@ import { openBrowser } from "../open.mjs";
 import { startProgress } from "../progress.mjs";
 import { fail } from "../errors.mjs";
 import { emitActivity } from "../activity.mjs";
+import {
+  diagnosticReference,
+  invocationDegradedResult,
+  recordDiagnostic,
+} from "../diagnostics.mjs";
 import {
   defaultCandidateStatePath,
   readActiveChangeId,
@@ -161,7 +163,7 @@ export function renderUsage(verb = "preview") {
                                   merge, surfaces a resolve card on a genuine overlap — the
                                   default), "ours" (keep yours), "theirs" (keep the store's)
   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} --ref <name>       assert the generated candidate/<changeId> ref (custom refs are refused)
   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
@@ -446,15 +448,9 @@ export function baseCommitsBehind(git, branch) {
 }
 
 /**
- * Resolve the git ref to diff HEAD against for the candidate's file patch (and its
- * summary). The candidate PR is `preview + your file changes`, and `candidate_open`
- * SERVER-CUTS the candidate branch back to the current preview tip and re-applies the
- * patch — so the patch MUST be the FULL delta of your branch vs its fork point off
- * `preview`, never "what changed since my last candidate push". Diffing against your
- * own candidate tracking ref is what silently produced an empty patch (and the wrong
- * "no file changes" skip, so no PR opened) after a push that landed but failed to open
- * its PR: that ref already equals HEAD, so the since-last-push delta is empty even
- * though the change vs preview is 19 files. Prefer the merge-base (fork point) with
+ * Resolve the git ref used to summarize the candidate's complete delta. Diffing
+ * against the already-pushed candidate tracking ref would be empty on retry even
+ * though the change vs preview is non-empty. Prefer the merge-base (fork point) with
  * `origin/<baseBranch>`; fall back to the candidate tracking ref, then HEAD~1, then ""
  * (single-commit `git show`) when no base ref resolves. Pure git I/O via the injected
  * runner — unit-tested.
@@ -510,7 +506,13 @@ export async function runBornRebased(client, { repo, changeId, strategy }) {
     const raw = await client.callTool("candidate_refresh", { repo, changeId, strategy });
     return normalizeRefreshResult(raw);
   } catch (e) {
-    return { ...normalizeRefreshResult(null), status: "error", message: String(e?.message || e) };
+    const diagnostic = recordDiagnostic(e, {
+      command: "submit", operation: "candidate_refresh", required: false, degraded: true,
+    });
+    return {
+      ...normalizeRefreshResult(null), status: "error", message: String(e?.message || e),
+      degraded: true, diagnosticId: diagnostic.diagnosticId,
+    };
   }
 }
 
@@ -766,38 +768,6 @@ export function parseNameStatus(text) {
     .filter((e) => e.path);
 }
 
-/**
- * Build the g1b `candidate_open` FileChange[] patch from parsed name-status
- * entries — one entry per changed path, `delete:true` for removals (and a
- * rename's old path). Content is read from the committed HEAD blob via
- * `readBlob` (injected — never the working tree, so the patch matches exactly
- * what was pushed). Binary content (doesn't round-trip as clean utf8, or
- * contains a NUL) is sent base64; everything else goes as plain utf8 text.
- * @param {{status:string, path:string, from?:string}[]} entries
- * @param {(path: string) => Buffer} readBlob
- * @returns {Array<{path: string, content?: string, contentEncoding?: "base64", delete?: true}>}
- */
-export function buildFilePatch(entries, readBlob) {
-  /** @type {Array<{ path: string, content?: string, contentEncoding?: "base64", delete?: true }>} */
-  const patch = [];
-  for (const e of entries) {
-    if (e.status === "R") patch.push({ path: /** @type {string} */ (e.from), delete: true });
-    if (e.status === "D") {
-      patch.push({ path: e.path, delete: true });
-      continue;
-    }
-    const buf = readBlob(e.path);
-    const asUtf8 = buf.toString("utf8");
-    const isCleanUtf8 = !asUtf8.includes("\x00") && Buffer.from(asUtf8, "utf8").equals(buf);
-    patch.push(
-      isCleanUtf8
-        ? { path: e.path, content: asUtf8 }
-        : { path: e.path, content: buf.toString("base64"), contentEncoding: "base64" },
-    );
-  }
-  return patch;
-}
-
 /**
  * Derive the g1b forge repo name (`"<tenant>-<tag>"`, e.g. `"acme.com-main"`)
  * from the checkout's authenticated origin remote — the SAME name
@@ -1001,7 +971,10 @@ export async function candidateStateFor(client, { repo, changeId }) {
         ? r.candidates.find((x) => x?.changeId === changeId)
         : r;
     return c && typeof c.state === "string" ? c.state : null;
-  } catch {
+  } catch (error) {
+    recordDiagnostic(error, {
+      command: "submit", operation: "candidate_status", required: false, degraded: true,
+    });
     return null;
   }
 }
@@ -1034,17 +1007,18 @@ export async function resolveActivePointer(client, { repo, 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.
+ * SHARED `preview` ref). The only valid target is the exact ref derived from the
+ * stable candidate identity. `--ref` may assert that value, but cannot override it.
+ * Pure — unit-tested.
  * @param {{ ref?: string|null, changeId: string }} opts
  * @returns {string}
  */
 export function resolvePushRef({ ref, changeId }) {
-  return ref || candidateRefFor(changeId);
+  const expected = candidateRefFor(changeId);
+  if (ref && ref !== expected) {
+    throw new Error(`--ref must be exactly ${expected}; custom refs cannot be registered as this candidate.`);
+  }
+  return expected;
 }
 
 const REQUIRED_ATTRIBUTION_REFUSALS = new Set([
@@ -1052,40 +1026,32 @@ const REQUIRED_ATTRIBUTION_REFUSALS = new Set([
   "audit_unavailable",
 ]);
 
-class CandidateAttributionError extends Error {
-  constructor(message) {
-    super(message);
-    this.name = "CandidateAttributionError";
+export class CandidateRegistrationError extends Error {
+  constructor(message, cause) {
+    super(message, cause === undefined ? undefined : { cause });
+    this.name = "CandidateRegistrationError";
   }
 }
 
 /**
  * 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"
- * milestone, symmetric with the hosted s6 draft-as-PR path). Builds the patch
- * from the SAME name-status diff `buildChangeSummary` reports on, reuses its
- * title/body as the PR title/description, and prints the resulting
- * changeId/PR number/URL. Best-effort: any failure (no repo could be derived,
- * older MCP, version control not configured, preview-access capability, …) is
- * reported and swallowed — except an audit/identity refusal, which is required
- * and propagates so the command exits non-zero with the MCP's recovery guidance.
+ * milestone, symmetric with the hosted s6 draft-as-PR path). The Git-capable CLI
+ * has already pushed its real commits, so this call sends only the exact candidate
+ * ref and asserted HEAD plus PR metadata. Any registration failure is fatal: a
+ * pushed ref without a review PR is not a successful submit.
  * @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,
+ * @param {{ repo: string|null, changeId: string, ref: string, headSha: string,
+ *   changeSummary: {title:string, body:string[]}, hasChanges: boolean,
  *   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, quiet = false }) {
+export async function submitCandidate(client, { repo, changeId, ref, headSha, changeSummary, hasChanges, quiet = false }) {
   if (!repo) {
-    if (!quiet) console.log(`  ~ couldn't derive the forge repo from the checkout's remote — skipping the PR-backed candidate.`);
-    return null;
+    throw new CandidateRegistrationError("Candidate not created: couldn't derive the forge repo from origin.");
   }
+  if (!hasChanges) throw new CandidateRegistrationError("Candidate not created: no content changes were found.");
   try {
-    const patch = buildFilePatch(patchEntries, readBlob);
-    if (patch.length === 0) {
-      if (!quiet) console.log(`  ~ no file changes to open a PR-backed candidate for.`);
-      return null;
-    }
     const result = await client.callTool("candidate_open", {
       repo,
       changeId,
@@ -1094,22 +1060,33 @@ export async function submitCandidate(client, { repo, changeId, changeSummary, p
       // truncated PR title/body instead of an entirely-avoidable tool refusal.
       title: changeSummary.title.slice(0, 200),
       body: changeSummary.body.length ? changeSummary.body.join("\n").slice(0, 4000) : undefined,
-      patch,
+      ref,
+      headSha,
+      idempotencyKey: `candidate-open:${repo}:${changeId}:${headSha}`,
     });
-    if (REQUIRED_ATTRIBUTION_REFUSALS.has(result?.status)) {
-      throw new CandidateAttributionError(
-        result?.message || "Candidate not created: verified actor attribution is required.",
+    if (REQUIRED_ATTRIBUTION_REFUSALS.has(result?.status) || result?.status === "error") {
+      throw new CandidateRegistrationError(
+        result?.message || "Candidate not created: the MCP refused registration.",
+      );
+    }
+    if (typeof result?.prNumber !== "number") {
+      throw new CandidateRegistrationError(
+        result?.message || "Candidate not created: candidate_open returned no pull request.",
+      );
+    }
+    if (result.branch !== ref || result.headSha !== headSha) {
+      throw new CandidateRegistrationError(
+        `Candidate not created: MCP registered ${result.branch || "an unknown ref"}@${result.headSha || "unknown"}, expected ${ref}@${headSha}.`,
       );
     }
+    if (isTerminalCandidateState(result.state)) {
+      throw new CandidateRegistrationError(`Candidate not created: candidate_open returned terminal state ${result.state}.`);
+    }
     reportCandidate(result, changeId, { quiet });
     return result;
   } catch (e) {
-    if (e instanceof CandidateAttributionError) throw e;
-    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;
+    if (e instanceof CandidateRegistrationError) throw e;
+    throw new CandidateRegistrationError(`Candidate not created: ${describeReadbackError(e)}`, e);
   }
 }
 
@@ -1158,9 +1135,10 @@ function reportCandidate(result, changeId, { quiet = false } = {}) {
  *   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, noChanges?: boolean }} input
+ *   previewPrUrl?: string|null, error?: string|null, note?: string|null, noChanges?: boolean,
+ *   degraded?: boolean, diagnosticId?: string|null }} input
  */
-export function buildJsonResult({ ok, ref = null, commit = null, changeId = null, candidate = null, status = null, previewPrUrl = null, error = null, note = null, noChanges = false }) {
+export function buildJsonResult({ ok, ref = null, commit = null, changeId = null, candidate = null, status = null, previewPrUrl = null, error = null, note = null, noChanges = false, degraded = false, diagnosticId = null }) {
   return {
     ok,
     ref,
@@ -1183,6 +1161,8 @@ export function buildJsonResult({ ok, ref = null, commit = null, changeId = null
     forwardFailed: /** @type {any} */ (status)?.forwardFailed ?? false,
     delivery: status?.delivery ?? null,
     previewPrUrl,
+    ...(degraded ? { degraded: true } : {}),
+    ...(diagnosticId ? { diagnosticId } : {}),
     // Honest-diagnosis parity with the human-readable formatNotDispatchedBlock: a
     // `--json` caller gets the SAME "why" signal a human sees on the console. Without
     // this, `candidate:null, notDispatched:true, delivery:null` reads identically for
@@ -1195,6 +1175,45 @@ export function buildJsonResult({ ok, ref = null, commit = null, changeId = null
   };
 }
 
+export function candidateFailureOutcome({
+  error, candidateRequired, candidate, operation, command, env,
+  ref, commit, changeId, previewPrUrl,
+}) {
+  const required = candidateRequired && !candidate;
+  const diagnostic = recordDiagnostic(error, {
+    command, operation, required, degraded: !required,
+  }, env);
+  if (required) {
+    const detail = error instanceof CandidateRegistrationError
+      ? error.message
+      : String(error?.message || error);
+    const note = `push succeeded but no review candidate was created: ${detail}`;
+    return {
+      required,
+      exitCode: 1,
+      note,
+      diagnostic,
+      result: buildJsonResult({
+        ok: false, ref, commit, changeId, candidate: null, error: note,
+        diagnosticId: diagnostic.diagnosticId,
+      }),
+    };
+  }
+  const note = error instanceof AuthUnavailableError
+    ? `candidate created; sign in to read its reconcile/compliance result — ${error.hint || "developer sign-in pending"}`
+    : `candidate created; result read-back is degraded: ${describeReadbackError(error)}`;
+  return {
+    required,
+    exitCode: 0,
+    note,
+    diagnostic,
+    result: buildJsonResult({
+      ok: true, ref, commit, changeId, candidate, previewPrUrl, note,
+      degraded: true, diagnosticId: diagnostic.diagnosticId,
+    }),
+  };
+}
+
 /**
  * The sha `preview_status` actually resolves against. The candidate the forge opened
  * may carry a DIFFERENT head than the commit you pushed (it is rebuilt onto the
@@ -1247,10 +1266,18 @@ function emitJson(args, payload) {
  * `--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]
+ * @param {string[]} argv @param {any} ctx
+ * @param {{ verb?: string, env?: NodeJS.ProcessEnv,
+ *   createClient?: typeof createMcpClient, establish?: typeof establishSession,
+ *   checkout?: typeof checkoutTenant }} [opts]
  */
-export async function run(argv, ctx, { verb = "preview" } = {}) {
-  const env = process.env;
+export async function run(argv, ctx, {
+  verb = "preview",
+  env = process.env,
+  createClient = createMcpClient,
+  establish = establishSession,
+  checkout = checkoutTenant,
+} = {}) {
   const args = parseArgs(argv);
   if (args.help) {
     console.log(renderUsage(verb));
@@ -1302,8 +1329,10 @@ export async function run(argv, ctx, { verb = "preview" } = {}) {
   // expired. Best-effort — never blocks the actual preview on a migration hiccup.
   try {
     ensureTokenlessRemote(git);
-  } catch {
-    /* best-effort — see above */
+  } catch (error) {
+    recordDiagnostic(error, {
+      command: verb, operation: "credential_helper_install", required: false, degraded: true,
+    }, env);
   }
 
   // How far the base has drifted since this candidate forked (unit c2), hoisted to the
@@ -1441,9 +1470,7 @@ export async function run(argv, ctx, { verb = "preview" } = {}) {
   // push, because `git push` fast-forwards the local origin/<ref> tracking ref and
   // would zero out the "vs what's live in preview" diff. Explicit -m/--summary win;
   // otherwise it's generated from git so the change record is never blank. This
-  // 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.
+  // same diff supplies the PR summary and the pre-push no-change gate.
   // 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).
@@ -1454,85 +1481,54 @@ export async function run(argv, ctx, { verb = "preview" } = {}) {
       return "";
     }
   };
-  function buildSummaryAndPatch(ref) {
+  function buildSubmitSummary(ref) {
     const headSubject = gitSafe(["log", "-1", "--format=%s"]).trim();
-    // Diff against the fork point off `preview` — the FULL branch delta — so the patch
-    // is complete for candidate_open's server-cut (which resets the branch to preview
-    // and re-applies this patch). NOT the candidate's own tracking ref: after a push
-    // that landed but failed to open its PR, that ref equals HEAD → empty patch →
-    // wrong "no file changes" → no PR. See resolvePatchBase.
+    // Diff against the fork point off `preview` so retries keep the complete summary
+    // even when the previously pushed candidate tracking ref already equals HEAD.
     const base = resolvePatchBase(gitSafe, ref);
     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 changedEntries = parseNameStatus(gitSafe(statusCmd));
+    const files = changedEntries.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 };
+    return { changeSummary, changedEntries };
   }
 
   // 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 client = createClient(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.
+  // needed — so they're available before any remote write.
   const branch = currentBranch(gitSafe);
   const statePath = defaultCandidateStatePath(env);
   let active = repo ? readActiveChangeId(statePath, { mcpUrl: baseUrl, repo, branch }) : null;
 
   let session;
   try {
-    session = await establishSession(client, { env, prefer: args.identity || undefined });
+    session = await establish(client, { env, prefer: args.identity || undefined });
   } catch (e) {
-    // 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, forkCandidate: args.forkCandidate });
-    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 diagnostic = recordDiagnostic(e, {
+      command: verb, operation: "session_establish", required: true, degraded: false,
+    }, env);
     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)}`;
+      ? `Candidate not created: ${e.hint || "developer sign-in is required"}.`
+      : `Candidate not created: couldn't reach Token of Trust (${describeReadbackError(e)}).`;
     if (!args.json) {
-      console.log(`  (${note})`);
-      console.log(`  Your push is in; the preview updates once reconcile completes.`);
+      console.error(fail(note, "run `tot login`, then re-run; no candidate ref was pushed"));
+      console.error(`  → ${diagnosticReference(diagnostic, env)}`);
     }
-    emitJson(args, buildJsonResult({ ok: true, ref, commit, changeId, note }));
-    return 0;
+    emitJson(args, buildJsonResult({
+      ok: false, commit, candidate: null, error: note,
+      diagnosticId: diagnostic.diagnosticId,
+    }));
+    return 1;
   }
 
   // u17 — before REUSING a remembered active pointer, confirm its PR is still open.
@@ -1546,7 +1542,11 @@ export async function run(argv, ctx, { verb = "preview" } = {}) {
   if (active && repo && !args.forkCandidate) {
     try {
       await client.callTool("client_switch", { tenant });
-    } catch { /* scope bind is best-effort; candidateStateFor tolerates a miss */ }
+    } catch (error) {
+      recordDiagnostic(error, {
+        command: verb, operation: "client_switch", required: false, degraded: true,
+      }, env);
+    }
     const resolved = await resolveActivePointer(client, { repo, active });
     if (resolved.dropped) {
       console.error(
@@ -1564,9 +1564,49 @@ export async function run(argv, ctx, { verb = "preview" } = {}) {
   // (right below) and the PR-backed candidate (step 2b): the two never point at
   // different branches. See chooseChangeId's doc for the --fork-candidate /
   // active-pointer rules.
-  let { changeId, stableId, persist } = chooseChangeId({ tenant, actorKey: actorKeyFor(session), branch, active, forkCandidate: args.forkCandidate });
-  const ref = resolvePushRef({ ref: args.ref, changeId });
-  const { changeSummary, patchEntries } = buildSummaryAndPatch(ref);
+  const { changeId } = chooseChangeId({ tenant, actorKey: actorKeyFor(session), branch, active, forkCandidate: args.forkCandidate });
+  let ref;
+  try {
+    ref = resolvePushRef({ ref: args.ref, changeId });
+  } catch (e) {
+    const note = String(e?.message || e);
+    if (!args.json) console.error(fail(note, "omit --ref and re-run"));
+    emitJson(args, buildJsonResult({ ok: false, commit, changeId, error: note }));
+    return 1;
+  }
+  const { changeSummary, changedEntries } = buildSubmitSummary(ref);
+  if (changedEntries.length === 0) {
+    const note = "Candidate not created: no content changes were found.";
+    if (!args.json) console.error(fail(note, "commit a content/public/theme.json change, then re-run"));
+    emitJson(args, buildJsonResult({ ok: false, ref, commit, changeId, error: note, noChanges: true }));
+    return 1;
+  }
+
+  // Persist the chosen identity before any remote write. A failed push or MCP
+  // registration therefore retries the same candidate/ref instead of minting an
+  // orphan. Failing to persist a forked identity is itself unsafe, so refuse.
+  if (!repo) {
+    const note = "Candidate not created: couldn't derive the forge repo from origin.";
+    if (!args.json) console.error(fail(note, "run this command inside a `tot clone` checkout"));
+    emitJson(args, buildJsonResult({ ok: false, ref, commit, changeId, error: note }));
+    return 1;
+  }
+  try {
+    writeActiveChangeId(statePath, { mcpUrl: baseUrl, repo, branch, changeId });
+  } catch (error) {
+    const note = "Candidate not created: couldn't persist retry identity.";
+    const diagnostic = recordDiagnostic(error, {
+      command: verb, operation: "candidate_pointer_write", required: true, degraded: false,
+    }, env);
+    if (!args.json) {
+      console.error(fail(note, "fix ~/.tot permissions, then re-run; no candidate ref was pushed"));
+      console.error(`  → ${diagnosticReference(diagnostic, env)}`);
+    }
+    emitJson(args, buildJsonResult({
+      ok: false, ref, commit, changeId, error: note, diagnosticId: diagnostic.diagnosticId,
+    }));
+    return 1;
+  }
 
   // 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
@@ -1577,9 +1617,12 @@ export async function run(argv, ctx, { verb = "preview" } = {}) {
   const tag = tagFromRepoName(repo, tenant);
   const mintRemote = async () => {
     try {
-      const res = await checkoutTenant(client, { tenant, tag, cloneDir: null, redact: redactUrl });
+      const res = await checkout(client, { tenant, tag, cloneDir: null, redact: redactUrl });
       return res.gitRemote || null;
     } catch (e) {
+      recordDiagnostic(e, {
+        command: verb, operation: "tenant_checkout", required: false, degraded: true,
+      }, env);
       console.error(
         `~ couldn't mint a fresh push credential (${redactUrl(String(e?.message || e))}) — using the checkout's remote`,
       );
@@ -1598,8 +1641,14 @@ export async function run(argv, ctx, { verb = "preview" } = {}) {
       errorClass: isForgeAuthError(e?.stderr || e?.message || e) ? "forge_auth" : "git_push_failed",
     });
     const msg = `push failed: ${redactUrl(String(e.stderr || e.message || e))}`;
+    const diagnostic = recordDiagnostic(new Error(msg, { cause: e }), {
+      command: verb, operation: "git_push", required: true, degraded: false,
+    }, env);
     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 }));
+    if (!args.json) console.error(`  → ${diagnosticReference(diagnostic, env)}`);
+    emitJson(args, buildJsonResult({
+      ok: false, ref, commit, changeId, error: msg, diagnosticId: diagnostic.diagnosticId,
+    }));
     return 1;
   }
   if (!args.json) console.log(`\n+ submitted ${short} to ${ref}.`);
@@ -1608,31 +1657,30 @@ export async function run(argv, ctx, { verb = "preview" } = {}) {
   // 2b + 3. open/update the PR-backed candidate, then report reconcile +
   // compliance + preview URL from the MCP — reusing the session established above.
   let progress = null;
+  let candidate = null;
+  let previewPrUrl = null;
+  let operation = "client_switch";
+  const candidateRequired = changedEntries.length > 0;
   try {
     // 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). Compatibility and
-    // capability failures remain best-effort, but the MCP's audit/identity refusals
-    // propagate and make this command fail: an unaudited PR is never an acceptable
-    // successful submit.
-    // `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"] });
-
-    let candidate = await submitCandidate(client, { repo, changeId, changeSummary, patchEntries, readBlob, quiet: args.json });
-
-    if (candidate && isTerminalCandidateState(candidate.state)) {
-      const rolled = mintFreshChangeId(stableId);
-      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, quiet: args.json });
+    try {
+      await client.callTool("client_switch", { tenant });
+    } catch (e) {
+      throw new CandidateRegistrationError(
+        `Candidate not created: tenant scope could not be bound (${describeReadbackError(e)}).`,
+        e,
+      );
     }
 
+    // 2b. Register the exact ref and asserted commit that git just pushed. No file
+    // bytes cross MCP and the server does not reconstruct or replace these commits.
+    operation = "candidate_open";
+    candidate = await submitCandidate(client, {
+      repo, changeId, ref, headSha: commit, changeSummary,
+      hasChanges: changedEntries.length > 0, quiet: args.json,
+    });
+
     // c3 — BORN-REBASED at submit (shift-left prevention #2). The candidate is open;
     // if the base has drifted (the SAME signal c2 warned on, pre-push) rebuild it from
     // the CURRENT base tip via candidate_refresh BEFORE finalizing, so it enters the
@@ -1651,6 +1699,7 @@ export async function run(argv, ctx, { verb = "preview" } = {}) {
     // never blocking the push that already landed. Gated on --skip-freshness via
     // baseDrift (0 when skipped).
     if (repo && baseDrift > 0 && candidate && !isTerminalCandidateState(candidate.state) && changeId) {
+      operation = "candidate_refresh";
       const rebased = await runBornRebased(client, { repo, changeId, strategy: bornRebasedStrategy });
       if (rebased.ok) {
         for (const line of formatBornRebasedSuccess({ behind: baseDrift, strategy: rebased.strategy || bornRebasedStrategy, refreshedFiles: rebased.refreshedFiles })) {
@@ -1663,18 +1712,12 @@ export async function run(argv, ctx, { verb = "preview" } = {}) {
         if (freshPrUrl && !args.json) {
           console.log(`\n  ▸ Your fresh preview will appear at:\n      ${freshPrUrl}\n    (building on the current store — this link goes live once reconcile completes)`);
         }
-        // The rebuild keeps the STABLE changeId, so the persisted active pointer stays
-        // valid — record it (best-effort) exactly as the normal open path does below.
-        if (persist && repo) {
-          try {
-            writeActiveChangeId(statePath, { mcpUrl: baseUrl, repo, branch, changeId });
-          } catch { /* best-effort local hint */ }
-        }
         emitJson(args, buildJsonResult({
           ok: true, ref, commit, changeId,
           candidate: { ...candidate, prNumber: freshPr ?? candidate.prNumber },
           previewPrUrl: freshPrUrl,
           note: `born-rebased on the current base (${rebased.strategy || bornRebasedStrategy})`,
+          ...invocationDegradedResult(),
         }));
         return 0;
       }
@@ -1695,7 +1738,7 @@ export async function run(argv, ctx, { verb = "preview" } = {}) {
     // 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 =
+    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;
@@ -1703,14 +1746,6 @@ export async function run(argv, ctx, { verb = "preview" } = {}) {
       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, branch, changeId });
-      } catch { /* best-effort local hint — a miss just re-derives the stable id */ }
-    }
-
     // Poll the sha `preview_status` actually resolves against — the candidate head, not
     // the local commit, whenever the candidate names its own. Printed first (when they
     // differ) so the developer reads the result against the right sha.
@@ -1721,6 +1756,7 @@ export async function run(argv, ctx, { verb = "preview" } = {}) {
     }
 
     let status;
+    operation = "preview_status";
     if (args.noWait) {
       status = normalizePreviewStatus(await client.callTool("preview_status", { commit: statusSha }));
     } else {
@@ -1763,27 +1799,41 @@ export async function run(argv, ctx, { verb = "preview" } = {}) {
     // — automation doesn't want a browser popping up.
     // `commit: statusSha` — the diagnostic blocks name the sha that was actually polled,
     // so a "never dispatched" hint points at a sha `preview_status` knows about.
-    const noChanges = patchEntries.length === 0;
+    const noChanges = changedEntries.length === 0;
     reportStatus(status, tenant, { open: !args.noOpen && !args.json, quiet: args.json, commit: statusSha, ref, verb, noChanges });
-    emitJson(args, buildJsonResult({ ok: status?.status !== "failed", ref, commit, changeId, candidate, status, previewPrUrl, noChanges }));
-    return status?.status === "failed" ? 1 : 0;
+    const ok = previewSubmitSucceeded(status);
+    const degradation = invocationDegradedResult();
+    if (degradation.degraded && !args.json) {
+      console.log(`  ~ completed with degraded optional diagnostics — ${diagnosticReference({ diagnosticId: degradation.diagnosticId }, env)}`);
+    }
+    emitJson(args, buildJsonResult({
+      ok, ref, commit, changeId, candidate, status,
+      previewPrUrl, noChanges, ...degradation,
+    }));
+    return ok ? 0 : 1;
   } catch (e) {
     progress?.stop();
-    if (e instanceof CandidateAttributionError) {
-      const note = `${e.message} Your preview push is in, but no review PR was created.`;
-      if (!args.json) console.error(fail(note, "follow the identity guidance above, then re-run `tot submit`"));
-      emitJson(args, buildJsonResult({ ok: false, ref, commit, changeId, error: note }));
-      return 1;
+    const outcome = candidateFailureOutcome({
+      error: e, candidateRequired, candidate, operation, command: verb, env,
+      ref, commit, changeId, previewPrUrl,
+    });
+    if (outcome.required) {
+      if (!args.json) {
+        const next = e instanceof CandidateRegistrationError
+          ? `re-run \`tot ${verb}\`; retry will reuse ${ref}`
+          : `fix the reported MCP failure, then re-run \`tot ${verb}\``;
+        console.error(fail(outcome.note, next));
+        console.error(`  → ${diagnosticReference(outcome.diagnostic, env)}`);
+      }
+      emitJson(args, outcome.result);
+      return outcome.exitCode;
     }
-    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(`  (${outcome.note})`);
+      console.log(`  ${diagnosticReference(outcome.diagnostic, env)}`);
     }
-    emitJson(args, buildJsonResult({ ok: true, ref, commit, changeId, note }));
-    return 0;
+    emitJson(args, outcome.result);
+    return outcome.exitCode;
   }
 }
 
@@ -1819,6 +1869,12 @@ export function normalizePreviewStatus(r) {
   };
 }
 
+/** A submit succeeds only when reconcile has neither failed nor failed to start. */
+export function previewSubmitSucceeded(status) {
+  const knownSuccessState = status?.status === "pending" || status?.status === "reconciled";
+  return knownSuccessState && !status?.notDispatched && !status?.forwardFailed;
+}
+
 /**
  * Poll `preview_status` while reconcile is pending (and, with untilShipped, while
  * reconciled-but-not-yet-shipped). E2: every call carries `waitMs` so a
@@ -2026,7 +2082,7 @@ export function formatNotDispatchedBlock({ commit = null, ref = null, noChanges
   // 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\`),`]
+      ? [`      • your submit contained NO content changes — a candidate with no diff opens no PR and builds nothing (make and commit an edit, then re-run \`tot ${verb}\`),`]
       : []),
     `      • 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.`,