@tokenoftrust/cli 1.4.1 → 1.5.0

package/src/commands/submit.mjs

@@ -14,9 +14,10 @@
  *
  * 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 is best-effort: `candidate_open` failing (older MCP,
- * version-control not configured, preview-access capability) is reported and
- * swallowed — it never blocks the preview push that already landed. Step 3 calls
+ * 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
  * 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 +
@@ -47,6 +48,10 @@ import { setTimeout as delay } from "node:timers/promises";
 import { createMcpClient } from "../mcp.mjs";
 import { establishSession, AuthUnavailableError } from "../auth.mjs";
 import { checkoutTenant } from "./clone.mjs";
+// Reuse the operator side's `candidate_refresh` result normaliser (unit c3 — the
+// born-rebased submit rebuilds a candidate onto the current base with the SAME
+// engine `tot accept --refresh` uses, so the two read its result identically).
+import { normalizeRefreshResult } from "./accept.mjs";
 import { validateTenant, ERROR } from "../validate.mjs";
 import { openBrowser } from "../open.mjs";
 import { startProgress } from "../progress.mjs";
@@ -92,6 +97,8 @@ export function candidateRefFor(changeId) {
  * 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).
+ * @param {string} op @param {boolean} ok
+ * @param {{ command?: string, durationMs?: number, errorClass?: string }} [opts]
  */
 function emitGitOp(op, ok, { command = "submit", durationMs, errorClass } = {}) {
   void emitActivity({
@@ -105,7 +112,8 @@ export function parseArgs(argv) {
   // `ref: null` — an explicit `--ref` always wins; otherwise the push target is
   // derived per-run as YOUR OWN isolated candidate ref (resolvePushRef, below),
   // never a fixed shared default.
-  const a = { mcp: null, identity: null, ref: null, skipValidate: false, skipFreshness: false, noWait: false, watch: false, noOpen: false, noCommit: false, message: null, summary: null, summaryFile: null, json: false, new: false, help: false };
+  /** @type {{ mcp: string|null, identity: string|null, ref: string|null, skipValidate: boolean, skipFreshness: boolean, noWait: boolean, watch: boolean, noOpen: boolean, noCommit: boolean, message: string|null, summary: string|null, summaryFile: string|null, strategy: string|null, json: boolean, forkCandidate: boolean, help: boolean }} */
+  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, strategy: null, json: false, forkCandidate: false, help: false };
   for (let i = 0; i < argv.length; i++) {
     const t = argv[i];
     if (t === "--mcp") a.mcp = argv[++i];
@@ -114,6 +122,7 @@ export function parseArgs(argv) {
     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 === "--strategy") a.strategy = 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;
@@ -121,7 +130,7 @@ export function parseArgs(argv) {
     else if (t === "--no-wait") a.noWait = true;
     else if (t === "--watch") a.watch = true;
     else if (t === "--no-open") a.noOpen = true;
-    else if (t === "--new") a.new = true;
+    else if (t === "--fork-candidate") a.forkCandidate = true;
     else if (t === "--help" || t === "-h") a.help = true;
   }
   return a;
@@ -137,11 +146,20 @@ export function renderUsage(verb = "preview") {
   return `tot ${verb} — submit your store for preview
 
   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} --fork-candidate   open a SECOND, independently-tracked candidate (a
+                                  parallel dev path). Rarely needed — a fresh git
+                                  branch already gets its own candidate automatically
+                                  (git checkout is the PR switcher); use this only to
+                                  run two candidates from ONE branch.
   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} --skip-freshness   skip the stale-base check AND the born-rebased rebuild
+                                  (not recommended — may build a candidate rooted in an
+                                  already-superseded base)
+  tot ${verb} --strategy <s>     how the born-rebased rebuild resolves a file changed on
+                                  BOTH sides when the base has moved: "merge" (real 3-way
+                                  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} -m "<title>"       one-line summary of what changed (the approver sees this)
@@ -159,13 +177,14 @@ export function renderUsage(verb = "preview") {
   tot ${verb} --mcp <url>        MCP base URL (default: env MCP_BASE_URL / TOT_MCP_URL)
 
   By default a re-run UPDATES your open candidate PR (like pushing more commits
-  to a GitHub PR), rather than opening a new one each time. Use --new to fork a
-  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
+  to a GitHub PR), rather than opening a new one each time. Manage your open
+  candidates with \`tot pr\` (list / view / close). If your candidate was already
   merged or closed, a re-run automatically opens a fresh one.
 
-  Working on one thing at a time? You don't need --new, a git branch, or any
-  branch management at all — just keep editing and re-running \`tot ${verb}\`.
+  Starting a separate change? \`git checkout -b <branch>\` — a fresh branch gets its
+  own candidate automatically, and \`git checkout\` back and forth is how you switch
+  between them. --fork-candidate is an escape hatch for the rarer case of wanting a
+  SECOND candidate off the SAME branch; reach for a branch first.
 
   Once a preview reconciles cleanly, \`tot ship\` promotes it live.
 
@@ -347,7 +366,7 @@ 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
+ * fresh `tot preview --fork-candidate` 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`.
  *
@@ -383,6 +402,166 @@ export function detectStaleBase(git, branch) {
   return remoteSha;
 }
 
+/**
+ * How many commits the base branch has advanced since this candidate forked off it
+ * (unit c2 — the shift-left base-drift warning). Conflicts in this loop are BASE
+ * DRIFT: a candidate branches off `<base>`, sits while OTHER candidates advance
+ * `<base>`, then settles mergeable=false at Accept time. This measures that drift
+ * cheaply and LOCALLY — the merge-base (fork point) of HEAD and the base's
+ * remote-tracking tip, then how many commits separate that fork point from the tip.
+ *
+ * PURE LOCAL git — reads `refs/remotes/origin/<branch>` (the last-fetched tip),
+ * never the network; it complements detectStaleBase (which confirms that tracking
+ * ref is itself current). Returns 0 — never a false warning — when there's nothing
+ * to compare against or the drift can't be positively determined: no base tracking
+ * ref yet, unrelated histories / no merge-base, HEAD already contains the tip, or
+ * any git failure. Non-blocking by contract: the caller warns on a positive count
+ * but always proceeds. Pure git I/O via the injected runner — unit-tested.
+ * @param {(cargs:string[])=>string} git
+ * @param {string} branch
+ * @returns {number}
+ */
+export function baseCommitsBehind(git, branch) {
+  const baseTip = `refs/remotes/origin/${branch}`;
+  let tip = "";
+  try {
+    tip = git(["rev-parse", "-q", "--verify", baseTip]).trim();
+  } catch {
+    return 0; // no local tracking ref for the base — nothing to compare against
+  }
+  if (!tip) return 0;
+  let mergeBase = "";
+  try {
+    mergeBase = git(["merge-base", "HEAD", baseTip]).trim();
+  } catch {
+    return 0; // unrelated histories / no HEAD — nothing meaningful to count
+  }
+  if (!mergeBase || mergeBase === tip) return 0; // HEAD already contains the base tip
+  try {
+    const n = parseInt(git(["rev-list", "--count", `${mergeBase}..${baseTip}`]).trim(), 10);
+    return Number.isFinite(n) && n > 0 ? n : 0;
+  } catch {
+    return 0;
+  }
+}
+
+/**
+ * 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
+ * `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.
+ * @param {(cargs:string[])=>string} git
+ * @param {string} ref  the candidate ref (e.g. "candidate/local-abc")
+ * @param {string} [baseBranch]  the preview base branch (default FRESHNESS_BASE_BRANCH)
+ * @returns {string}
+ */
+export function resolvePatchBase(git, ref, baseBranch = FRESHNESS_BASE_BRANCH) {
+  const verify = (r) => {
+    try { return git(["rev-parse", "--verify", "--quiet", r]).trim(); } catch { return ""; }
+  };
+  const previewRef = `refs/remotes/origin/${baseBranch}`;
+  if (verify(previewRef)) {
+    try {
+      const forkPoint = git(["merge-base", "HEAD", previewRef]).trim();
+      if (forkPoint) return forkPoint;
+    } catch { /* unrelated histories — fall through */ }
+  }
+  const trackingRef = `refs/remotes/origin/${ref}`;
+  if (verify(trackingRef)) return trackingRef;
+  if (verify("HEAD~1")) return "HEAD~1";
+  return "";
+}
+
+// ─── born-rebased at submit (unit c3 — shift-left prevention #2) ─────────────────
+
+/** The three strategies the born-rebased rebuild accepts, mirroring `tot accept
+ *  --refresh` (accept.mjs) and the admin one-click resolver: `merge` (real 3-way,
+ *  refuses on a genuine overlap), `ours` (keep yours), `theirs` (keep the store's).
+ *  `merge` is the DEFAULT — auto-rebuild on pure drift, name the conflict on a real
+ *  same-line overlap, never silently clobber a side. */
+export const BORN_REBASED_STRATEGIES = ["ours", "theirs", "merge"];
+export const DEFAULT_BORN_REBASED_STRATEGY = "merge";
+
+/**
+ * Run `candidate_refresh` (the born-rebased rebuild, unit c3) over the ALREADY
+ * established MCP client — the candidate was just opened by candidate_open (step 2b)
+ * and the tenant scope is already bound, so this reuses that session rather than
+ * establishing its own (accept.mjs's runRefresh is the operator entry that does the
+ * sign-in; here the submit flow already holds the session). Rebuilds the candidate
+ * from the CURRENT base tip and re-applies its file changes under `strategy`. Returns
+ * the normalized result (status:"committed" is the only success). Best-effort: any
+ * throw — an owner-gated denial (candidate_refresh is app-owner gated), an older MCP
+ * without the tool, a transient failure — normalizes to a non-ok error result the
+ * caller submits-as-is on, NEVER blocking the push that already landed.
+ * @param {{callTool:Function}} client
+ * @param {{ repo: string, changeId: string, strategy: string }} opts
+ * @returns {Promise<ReturnType<typeof normalizeRefreshResult>>}
+ */
+export async function runBornRebased(client, { repo, changeId, strategy }) {
+  try {
+    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) };
+  }
+}
+
+/**
+ * The born-rebased SUCCESS lines (unit c3) — printed when the candidate rebuilt
+ * cleanly onto the current base tip, so it enters the queue already mergeable rather
+ * than settling not-mergeable at Accept time. `behind` is the base-drift count that
+ * triggered the rebuild. Pure — unit-tested.
+ * @param {{ behind?: number, strategy?: string, refreshedFiles?: string[] }} input
+ * @returns {string[]}
+ */
+export function formatBornRebasedSuccess({ behind = 0, strategy = DEFAULT_BORN_REBASED_STRATEGY, refreshedFiles = [] } = {}) {
+  const drift = behind > 0 ? `${behind} commit${behind === 1 ? "" : "s"}` : "since you forked";
+  const lines = [
+    `\n  ✓ rebuilt fresh on the current store (base had advanced ${drift}, strategy ${strategy}) — your candidate enters the queue already mergeable.`,
+  ];
+  if (refreshedFiles.length) lines.push(`    reapplied: ${refreshedFiles.join(", ")}`);
+  return lines;
+}
+
+/**
+ * The born-rebased RESOLVE CARD (unit c3) — printed when the default `merge` rebuild
+ * hits a GENUINE same-line overlap with the base (not mere drift): the biggest single
+ * shift-left win is surfacing that conflict HERE, at submit, instead of letting it
+ * land as a stuck queue row someone discovers at Accept time. Names the diverged files
+ * and offers the two one-command resolutions (keep-mine / keep-store's) — `merge` is
+ * the default that just failed, so it isn't re-offered. Matches how the rest of this
+ * file reports next-steps (a `✗` headline + concrete `tot <verb> …` commands), never a
+ * raw git rebase instruction. Pure — unit-tested. `verb` brands the copy with whatever
+ * the developer typed.
+ * @param {{ unresolved?: string[] }} rr
+ * @param {string} [verb]
+ * @returns {string[]}
+ */
+export function formatBornRebasedConflict({ unresolved = [] } = {}, verb = "preview") {
+  const lines = [
+    `\n  ✗ your change conflicts with the current store on the same lines — it can't be auto-rebased.`,
+  ];
+  if (unresolved.length) {
+    lines.push(`  These files changed on both sides since you forked and need your call:`);
+    for (const f of unresolved) lines.push(`    - ${f}`);
+  }
+  lines.push(
+    `  Resolve it in one command — choose which side wins on those files:`,
+    `    tot ${verb} --strategy=ours     keep YOURS on any clash`,
+    `    tot ${verb} --strategy=theirs   keep the STORE's on any clash`,
+    `  Your push is in; the candidate is submitted but stays not-mergeable until you resolve it.`,
+  );
+  return lines;
+}
+
 // ─── auto-commit the known content trees (unit u2) ───────────────────────────────
 
 /**
@@ -599,9 +778,10 @@ export function parseNameStatus(text) {
  * @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: e.from, delete: true });
+    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;
@@ -693,7 +873,7 @@ export function tagFromRepoName(repoName, tenant) {
  *
  * @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
+ * @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 } = {}) {
@@ -779,22 +959,23 @@ export function actorKeyFor(session) {
  * 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.
+ * `--fork-candidate` forks a fresh one.
+ *   forkCandidate → fork a FRESH candidate id;
+ *   otherwise     → the remembered active candidate (from a prior --fork-candidate /
+ *                   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
+ *   forkCandidate?: 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 }) {
+export function chooseChangeId({ tenant, actorKey, branch = null, active = null, forkCandidate = false, mint = mintFreshChangeId }) {
   const stableId = deriveChangeId(tenant, actorKey, branch);
-  const changeId = isNew ? mint(stableId) : (active || stableId);
-  const persist = isNew || (!!active && active !== stableId);
+  const changeId = forkCandidate ? mint(stableId) : (active || stableId);
+  const persist = forkCandidate || (!!active && active !== stableId);
   return { changeId, stableId, persist };
 }
 
@@ -847,7 +1028,7 @@ export async function candidateStateFor(client, { repo, changeId }) {
 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 } };
+  if (isTerminalCandidateState(state)) return { active: null, dropped: { changeId: active, state: /** @type {string} */ (state) } };
   return { active };
 }
 
@@ -866,6 +1047,18 @@ export function resolvePushRef({ ref, changeId }) {
   return ref || candidateRefFor(changeId);
 }
 
+const REQUIRED_ATTRIBUTION_REFUSALS = new Set([
+  "audit_identity_unavailable",
+  "audit_unavailable",
+]);
+
+class CandidateAttributionError extends Error {
+  constructor(message) {
+    super(message);
+    this.name = "CandidateAttributionError";
+  }
+}
+
 /**
  * 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"
@@ -874,8 +1067,8 @@ export function resolvePushRef({ ref, changeId }) {
  * 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 — it never blocks the preview push that already
- * landed or the reconcile/compliance read-back that follows.
+ * 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.
  * @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,
@@ -903,9 +1096,15 @@ export async function submitCandidate(client, { repo, changeId, changeSummary, p
       body: changeSummary.body.length ? changeSummary.body.join("\n").slice(0, 4000) : undefined,
       patch,
     });
+    if (REQUIRED_ATTRIBUTION_REFUSALS.has(result?.status)) {
+      throw new CandidateAttributionError(
+        result?.message || "Candidate not created: verified actor attribution is required.",
+      );
+    }
     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.)`);
@@ -977,7 +1176,7 @@ export function buildJsonResult({ ok, ref = null, commit = null, changeId = null
     shipped: status?.shipped ?? null,
     dispatched: status?.dispatched ?? null,
     notDispatched: status?.notDispatched ?? false,
-    forwardFailed: status?.forwardFailed ?? false,
+    forwardFailed: /** @type {any} */ (status)?.forwardFailed ?? false,
     delivery: status?.delivery ?? null,
     previewPrUrl,
     ...(error ? { error } : {}),
@@ -1015,6 +1214,15 @@ export async function run(argv, ctx, { verb = "preview" } = {}) {
     emitJson(args, buildJsonResult({ ok: false, error: msg }));
     return 2;
   }
+  // --strategy (c3 born-rebased rebuild) — validate whenever given; defaults to
+  // "merge" (auto-rebuild on drift, surface a resolve card on a genuine overlap).
+  if (args.strategy != null && !BORN_REBASED_STRATEGIES.includes(args.strategy)) {
+    const msg = `unknown --strategy "${args.strategy}"`;
+    console.error(fail(msg, `use one of: ${BORN_REBASED_STRATEGIES.join(", ")} (default "${DEFAULT_BORN_REBASED_STRATEGY}")`));
+    emitJson(args, buildJsonResult({ ok: false, error: msg }));
+    return 2;
+  }
+  const bornRebasedStrategy = args.strategy || DEFAULT_BORN_REBASED_STRATEGY;
   if (args.summaryFile) {
     let raw;
     try {
@@ -1050,6 +1258,12 @@ export async function run(argv, ctx, { verb = "preview" } = {}) {
     /* best-effort — see above */
   }
 
+  // How far the base has drifted since this candidate forked (unit c2), hoisted to the
+  // whole flow: it drives BOTH the c2 pre-push warning (below) AND the c3 born-rebased
+  // rebuild (after candidate_open). Stays 0 under --skip-freshness, so that flag opts
+  // out of the rebuild too — consistent with opting out of the warning.
+  let baseDrift = 0;
+
   // 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
@@ -1070,6 +1284,24 @@ export async function run(argv, ctx, { verb = "preview" } = {}) {
       emitJson(args, buildJsonResult({ ok: false, error: msg }));
       return 1;
     }
+
+    // Base-drift warning (unit c2) — a candidate rooted on a fork point the base has
+    // since moved past is what settles mergeable=false at Accept time; catch it early,
+    // right here, with a pure-LOCAL git read (no network — uses the base's
+    // remote-tracking tip, which the stale-base preflight just above confirmed is
+    // current). NON-BLOCKING: warn and submit anyway, so a work-in-progress preview
+    // is never refused over base drift. Shares --skip-freshness with the preflight.
+    try {
+      baseDrift = baseCommitsBehind(git, FRESHNESS_BASE_BRANCH);
+    } catch {
+      baseDrift = 0; // never let the warning's OWN failure disturb the submit
+    }
+    if (baseDrift > 0) {
+      console.error(`\n⚠ base is ${baseDrift} commit${baseDrift === 1 ? "" : "s"} behind — rebase before submit`);
+      console.error(
+        `  (\`${FRESHNESS_BASE_BRANCH}\` has advanced since your branch forked off it — \`tot sync\` to rebase, or --skip-freshness to silence)`,
+      );
+    }
   }
 
 
@@ -1177,12 +1409,12 @@ export async function run(argv, ctx, { verb = "preview" } = {}) {
   };
   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"
-        : "";
+    // 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.
+    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);
@@ -1217,7 +1449,7 @@ export async function run(argv, ctx, { verb = "preview" } = {}) {
     // 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 { 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)`);
@@ -1260,11 +1492,11 @@ export async function run(argv, ctx, { verb = "preview" } = {}) {
   // 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.
+  // guards against). Skipped under --fork-candidate (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) {
+  if (active && repo && !args.forkCandidate) {
     try {
       await client.callTool("client_switch", { tenant });
     } catch { /* scope bind is best-effort; candidateStateFor tolerates a miss */ }
@@ -1283,9 +1515,9 @@ export async function run(argv, ctx, { verb = "preview" } = {}) {
   // 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 });
+  // 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);
 
@@ -1334,9 +1566,10 @@ export async function run(argv, ctx, { verb = "preview" } = {}) {
     // (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.
+    // 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
@@ -1353,6 +1586,61 @@ export async function run(argv, ctx, { verb = "preview" } = {}) {
       candidate = await submitCandidate(client, { repo, changeId, changeSummary, patchEntries, readBlob, 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
+    // queue already fresh instead of settling not-mergeable at Accept time.
+    //   • clean rebuild  → report it, hand back the fresh candidate's shareable URL,
+    //                       and finish (the rebuilt PR has a NEW head; polling the old
+    //                       local `commit` would read as never-dispatched, so we skip
+    //                       the reconcile poll and say the fresh preview is building);
+    //   • genuine overlap (merge_failed) → surface the resolve card right here, then
+    //                       fall through — candidate_refresh made NO changes on a real
+    //                       conflict, so the candidate's head still matches `commit`
+    //                       and the normal reconcile poll below is still valid;
+    //   • anything else (owner-gated denial, older MCP, error) → submit as-is.
+    // Best-effort throughout: candidate_refresh is app-owner gated, so an ordinary
+    // invited developer's session may be denied — that degrades to submitting as-is,
+    // 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) {
+      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 })) {
+          if (!args.json) console.log(line);
+        }
+        const freshPr = typeof rebased.prNumber === "number" ? rebased.prNumber : candidate.prNumber;
+        const freshPrUrl = typeof freshPr === "number"
+          ? shareablePrUrl(env.TOT_STOREFRONT_URL || env.STOREFRONT_BASE_URL || DEFAULT_STOREFRONT_URL, tenant, freshPr)
+          : null;
+        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})`,
+        }));
+        return 0;
+      }
+      if (rebased.status === "merge_failed") {
+        for (const line of formatBornRebasedConflict({ unresolved: rebased.unresolved }, verb)) {
+          if (!args.json) console.log(line);
+        }
+        // fall through to the normal poll — the candidate is unchanged.
+      } else if (rebased.message && !args.json) {
+        console.log(`  ~ couldn't auto-rebase on the current base (${rebased.message}) — submitting as-is.`);
+      }
+    }
+
     // 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
@@ -1422,6 +1710,12 @@ export async function run(argv, ctx, { verb = "preview" } = {}) {
     return status?.status === "failed" ? 1 : 0;
   } 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 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)}`;
@@ -1489,16 +1783,28 @@ export function normalizePreviewStatus(r) {
  * 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.
+ * observed. Injectable delay/attempts/waitMs/grace + a `now` clock and `sleep`
+ * fn for tests (so the fallback-sleep cadence can be asserted deterministically
+ * off the injected clock instead of real wall-clock elapsed time).
  * @param {{callTool:Function}} client
  * @param {string} commit
  * @param {{ attempts?: number, delayMs?: number, waitMs?: number, untilShipped?: boolean,
- *   notDispatchedGraceMs?: number, now?: () => number, onTick?: (s:object,i:number)=>void }} [opts]
+ *   notDispatchedGraceMs?: number, now?: () => number, sleep?: (ms:number) => Promise<void>,
+ *   onTick?: (s:object,i:number)=>void }} [opts]
  */
 export async function pollPreviewStatus(
   client,
   commit,
-  { attempts = 8, delayMs = 2500, waitMs = delayMs, untilShipped = false, notDispatchedGraceMs = 15_000, now = Date.now, onTick } = {},
+  {
+    attempts = 8,
+    delayMs = 2500,
+    waitMs = delayMs,
+    untilShipped = false,
+    notDispatchedGraceMs = 15_000,
+    now = Date.now,
+    sleep = delay,
+    onTick,
+  } = {},
 ) {
   let last = null;
   let everDispatched = false;
@@ -1533,7 +1839,7 @@ export async function pollPreviewStatus(
     if (last.status !== "pending" && !stillWatchingForShip) return last;
     if (i < attempts - 1) {
       const remaining = delayMs - (now() - startedAt);
-      if (remaining > 0) await delay(remaining);
+      if (remaining > 0) await sleep(remaining);
     }
   }
   // Budget exhausted. A still-pending result that never saw a delivery is a
@@ -1593,7 +1899,7 @@ export function shareablePrUrl(base, tenant, prNumber) {
  * @returns {string}
  */
 export function describeReadbackError(e) {
-  const msg = String(e?.message || e || "");
+  const msg = String(/** @type {any} */ (e)?.message || e || "");
   const jsonStart = msg.indexOf("{");
   if (jsonStart >= 0 && msg.includes("self_repair")) {
     try {
@@ -1649,7 +1955,7 @@ export function formatShareableUrlBlock(s, tenant) {
  * 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 {{ commit?: string|null, ref?: string|null, noChanges?: boolean }} ctx
  * @param {string} tenant @param {string} [verb]
  * @returns {string[]}
  */
@@ -1706,6 +2012,10 @@ export function formatForwardFailedBlock({ commit = null } = {}, tenant) {
  * --json — automation doesn't want a browser popping up). `commit`/`ref`/`verb`
  * feed the honest never-dispatched block.
  */
+/**
+ * @param {any} s @param {string} tenant
+ * @param {{ open?: boolean, quiet?: boolean, commit?: string|null, ref?: string|null, verb?: string, noChanges?: boolean }} [opts]
+ */
 function reportStatus(s, tenant, { open = true, quiet = false, commit = null, ref = null, verb = "preview", noChanges = false } = {}) {
   if (!s || s.status === "unknown") {
     if (!quiet) {