@tokenoftrust/cli 2.0.11 → 2.0.12

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@tokenoftrust/cli",
-  "version": "2.0.11",
+  "version": "2.0.12",
   "description": "Token of Trust developer CLI — clone a tenant store, run it locally with save→reload, and submit it for preview. Installs the `tot` command.",
   "license": "Apache-2.0",
   "author": "Token of Trust",

package/src/candidate-state.mjs

@@ -3,9 +3,10 @@
  * updates, per forge repo.
  *
  * `tot submit` is idempotent on a STABLE changeId (`deriveChangeId`) so a re-submit
- * updates the same PR by default — the common case needs NO state and writes
- * nothing here (backward-compatible with the stateless original). This file only
- * records a DIVERGENCE from that stable default:
+ * updates the same PR by default. Every chosen identity is persisted before its
+ * ref is pushed, which makes a failed push or MCP registration retry the same ref.
+ * The stored pointer is especially important when the chosen id diverges from the
+ * stable default:
  *
  *   - `tot submit --fork-candidate` forks a fresh candidate and remembers it here, so the
  *     NEXT plain `tot submit` keeps updating the NEW PR (like pushing more commits
@@ -18,14 +19,13 @@
  * candidates): a different MCP, repo, OR non-default git branch is a different
  * candidate namespace, so a feature branch gets its OWN candidate PR instead of
  * fighting main's over the same handle. The default branch deliberately keeps the
- * OLD branch-less key so existing devs' state is byte-identical (zero migration),
- * and a branch-scoped read that misses FALLS BACK to that old key so state written
- * before the rekey (or by the default branch) is never orphaned. Same atomic-write
- * discipline as last-tenant.mjs (0600 in a 0700 dir, write-tmp-then-rename).
+ * branch-less key. Non-default branches never inherit that pointer. Updates hold an
+ * exclusive lock across read-modify-write so concurrent submits cannot lose either
+ * identity. Files use mode 0600 in a 0700 directory.
  * Dependency-free (node:fs/os/path). `TOT_HOME` overrides home (tests).
  */
 import {
-  readFileSync, writeFileSync, mkdirSync, renameSync, chmodSync,
+  readFileSync, writeFileSync, mkdirSync, renameSync, chmodSync, rmdirSync, statSync,
 } from "node:fs";
 import { homedir } from "node:os";
 import { join, dirname } from "node:path";
@@ -79,45 +79,70 @@ function readMap(filePath) {
 }
 
 function writeMap(filePath, map) {
-  mkdirSync(dirname(filePath), { recursive: true, mode: 0o700 });
-  const tmp = `${filePath}.tmp`;
+  const tmp = `${filePath}.${process.pid}.${randomBytes(6).toString("hex")}.tmp`;
   writeFileSync(tmp, `${JSON.stringify(map, null, 2)}\n`, { mode: 0o600 });
   renameSync(tmp, filePath);
   chmodSync(filePath, 0o600);
 }
 
+const LOCK_RETRY_MS = 10;
+const LOCK_ATTEMPTS = 200;
+const STALE_LOCK_MS = 30_000;
+const lockWait = new Int32Array(new SharedArrayBuffer(4));
+
+function updateMap(filePath, mutate) {
+  mkdirSync(dirname(filePath), { recursive: true, mode: 0o700 });
+  const lockPath = `${filePath}.lock`;
+  let locked = false;
+  for (let attempt = 0; attempt < LOCK_ATTEMPTS && !locked; attempt += 1) {
+    try {
+      mkdirSync(lockPath, { mode: 0o700 });
+      locked = true;
+    } catch (error) {
+      if (error?.code !== "EEXIST") throw error;
+      try {
+        if (Date.now() - statSync(lockPath).mtimeMs > STALE_LOCK_MS) rmdirSync(lockPath);
+      } catch (staleError) {
+        if (staleError?.code !== "ENOENT" && staleError?.code !== "ENOTEMPTY") throw staleError;
+      }
+      if (!locked) Atomics.wait(lockWait, 0, 0, LOCK_RETRY_MS);
+    }
+  }
+  if (!locked) throw new Error(`Candidate state is busy: ${lockPath}`);
+  try {
+    const map = readMap(filePath);
+    if (mutate(map)) writeMap(filePath, map);
+  } finally {
+    rmdirSync(lockPath);
+  }
+}
+
 /**
  * The remembered active changeId for `(mcpUrl, repo, branch)`, or null when there
  * isn't one (absent/unreadable/malformed) — a miss means "use the stable default".
- * On a non-default branch whose branch-scoped key misses, FALLS BACK to the legacy
- * branch-less key so state written before the rekey (or by the default branch)
- * isn't orphaned. Never throws.
+ * Non-default branches never read the default branch's pointer. Never throws.
  */
 export function readActiveChangeId(filePath, { mcpUrl, repo, branch }) {
   const map = readMap(filePath);
-  const primary = recordChangeId(map[stateKey(mcpUrl, repo, branch)]);
-  if (primary) return primary;
-  // Legacy fallback: a branch-scoped miss reads the old branch-less key (a no-op
-  // when we're already on the default branch, which IS the legacy key).
-  if (!isDefaultBranch(branch)) return recordChangeId(map[legacyStateKey(mcpUrl, repo)]);
-  return null;
+  return recordChangeId(map[stateKey(mcpUrl, repo, branch)]);
 }
 
 /** Remember `changeId` as the active candidate for `(mcpUrl, repo, branch)`, atomically. */
 export function writeActiveChangeId(filePath, { mcpUrl, repo, branch, changeId }) {
-  const map = readMap(filePath);
-  map[stateKey(mcpUrl, repo, branch)] = { changeId, updatedAt: Date.now() };
-  writeMap(filePath, map);
+  updateMap(filePath, (map) => {
+    map[stateKey(mcpUrl, repo, branch)] = { changeId, updatedAt: Date.now() };
+    return true;
+  });
 }
 
 /** Forget the active candidate for `(mcpUrl, repo, branch)` (e.g. after closing it). */
 export function clearActiveChangeId(filePath, { mcpUrl, repo, branch }) {
-  const map = readMap(filePath);
-  const key = stateKey(mcpUrl, repo, branch);
-  if (key in map) {
+  updateMap(filePath, (map) => {
+    const key = stateKey(mcpUrl, repo, branch);
+    if (!(key in map)) return false;
     delete map[key];
-    writeMap(filePath, map);
-  }
+    return true;
+  });
 }
 
 /**

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,11 @@
  *
  * 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 read-back failure after the candidate exists is reported separately.
  *
  * 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
@@ -161,7 +157,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 +442,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.
@@ -766,38 +756,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
@@ -1034,17 +992,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 +1011,32 @@ const REQUIRED_ATTRIBUTION_REFUSALS = new Set([
   "audit_unavailable",
 ]);
 
-class CandidateAttributionError extends Error {
+export class CandidateRegistrationError extends Error {
   constructor(message) {
     super(message);
-    this.name = "CandidateAttributionError";
+    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 +1045,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)}`);
   }
 }
 
@@ -1247,10 +1209,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));
@@ -1441,9 +1411,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 +1422,45 @@ 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 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;
+      ? `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.error(fail(note, "run `tot login`, then re-run; no candidate ref was pushed"));
+    emitJson(args, buildJsonResult({ ok: false, commit, error: note }));
+    return 1;
   }
 
   // u17 — before REUSING a remembered active pointer, confirm its PR is still open.
@@ -1564,9 +1492,41 @@ 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 {
+    const note = "Candidate not created: couldn't persist retry identity.";
+    if (!args.json) console.error(fail(note, "fix ~/.tot permissions, then re-run; no candidate ref was pushed"));
+    emitJson(args, buildJsonResult({ ok: false, ref, commit, changeId, error: note }));
+    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,7 +1537,7 @@ 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) {
       console.error(
@@ -1611,28 +1571,19 @@ export async function run(argv, ctx, { verb = "preview" } = {}) {
   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)}).`);
     }
 
+    // 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.
+    const 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
@@ -1663,13 +1614,6 @@ 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 },
@@ -1703,14 +1647,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.
@@ -1763,27 +1699,25 @@ 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);
+    emitJson(args, buildJsonResult({ ok, ref, commit, changeId, candidate, status, previewPrUrl, noChanges }));
+    return ok ? 0 : 1;
   } catch (e) {
     progress?.stop();
-    if (e instanceof CandidateAttributionError) {
+    if (e instanceof CandidateRegistrationError) {
       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`"));
+      if (!args.json) console.error(fail(note, `re-run \`tot submit\`; retry will reuse ${ref}`));
       emitJson(args, buildJsonResult({ ok: false, ref, commit, changeId, error: note }));
       return 1;
     }
     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.`);
-    }
-    emitJson(args, buildJsonResult({ ok: true, ref, commit, changeId, note }));
-    return 0;
+      ? `Preview result unavailable: ${e.hint || "developer sign-in is required"}.`
+      : `Preview result unavailable: ${describeReadbackError(e)}.`;
+    if (!args.json) console.error(fail(note, `the candidate ref remains at ${ref}; fix the error and re-run`));
+    emitJson(args, buildJsonResult({ ok: false, ref, commit, changeId, error: note }));
+    return 1;
   }
 }
 
@@ -1819,6 +1753,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 +1966,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.`,