@tokenoftrust/cli 1.4.0-rc.20 → 1.4.0-rc.22

package/src/commands/submit.mjs

@@ -40,12 +40,17 @@
  * Dependency-free (global fetch + `git`).
  */
 import { execFileSync } from "node:child_process";
-import { readFileSync } from "node:fs";
+import { readFileSync, existsSync } from "node:fs";
+import { resolve as resolvePath } from "node:path";
 import { createHash } from "node:crypto";
 import { setTimeout as delay } from "node:timers/promises";
 import { createMcpClient } from "../mcp.mjs";
 import { establishSession, AuthUnavailableError } from "../auth.mjs";
 import { checkoutTenant } from "./clone.mjs";
+// 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";
@@ -55,6 +60,7 @@ import {
   defaultCandidateStatePath,
   readActiveChangeId,
   writeActiveChangeId,
+  clearActiveChangeId,
   mintFreshChangeId,
   isTerminalCandidateState,
   isDefaultBranch,
@@ -90,6 +96,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({
@@ -103,7 +111,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, 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];
@@ -112,13 +121,15 @@ 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;
     else if (t === "--no-commit") a.noCommit = true;
     else if (t === "--no-wait") a.noWait = true;
     else if (t === "--watch") a.watch = true;
     else if (t === "--no-open") a.noOpen = true;
-    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;
@@ -134,9 +145,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 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)
@@ -154,11 +176,15 @@ 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.
 
+  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.
 
   If you omit -m, a summary is generated from git (commit subject + the diff vs
@@ -326,6 +352,180 @@ export function readSummaryFileContent(pathOrDash) {
   return readFileSync(pathOrDash, "utf8");
 }
 
+// ─── stale-base freshness preflight (unit u16) ──────────────────────────────────
+
+/** The candidate base branch every submit targets (mirrors tot-mcp's own
+ *  `DEFAULT_CANDIDATE_BASE` and sync.mjs's `DEFAULT_SYNC_BRANCH` — the SAME
+ *  protected branch by three different names in three different modules; kept
+ *  a local constant here, not imported, since this file already resolves its
+ *  own defaults independently of sync.mjs and candidate_open's server default). */
+export const FRESHNESS_BASE_BRANCH = "preview";
+
+/**
+ * Detect a STALE local view of the base branch before minting a candidate —
+ * the live-repeat incident this guards against: the checkout's `origin/preview`
+ * tracking ref was stale (recorded before a just-merged PR moved it), so a
+ * fresh `tot preview --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`.
+ *
+ * Compares what the LOCAL checkout believes the base's tip is
+ * (`refs/remotes/origin/<branch>`, only as fresh as the last explicit fetch)
+ * against its ACTUAL current tip on the forge (`git ls-remote`, a lightweight
+ * single-ref read — no full fetch, no local ref mutated). Returns the live
+ * remote sha when local's cached view is behind it, or `null` when: the two
+ * already agree, there is no local tracking ref to compare against yet (a
+ * checkout that has simply never fetched this branch — never a false block on
+ * that), or the remote can't be reached right now (a network hiccup must
+ * never block a submit that would otherwise succeed; the push itself is the
+ * real connectivity test). Pure git I/O via the injected runner — unit-tested.
+ * @param {(cargs:string[])=>string} git
+ * @param {string} branch
+ * @returns {string|null}
+ */
+export function detectStaleBase(git, branch) {
+  let localSha = "";
+  try {
+    localSha = git(["rev-parse", "-q", "--verify", `refs/remotes/origin/${branch}`]).trim();
+  } catch {
+    return null; // never fetched this branch locally — nothing cached to be stale
+  }
+  if (!localSha) return null;
+  let remoteSha = "";
+  try {
+    remoteSha = (git(["ls-remote", "origin", branch]).split(/\s+/)[0] || "").trim();
+  } catch {
+    return null; // can't reach the remote right now — don't block on a network hiccup
+  }
+  if (!remoteSha || remoteSha === localSha) return null;
+  return remoteSha;
+}
+
+/**
+ * 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;
+  }
+}
+
+// ─── 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) ───────────────────────────────
 
 /**
@@ -410,6 +610,59 @@ export function buildAutoCommitMessage({ message, files = [], statLine = "" } =
   return body.length ? `${subject}\n\n${body.join("\n")}` : subject;
 }
 
+/**
+ * Detect an in-progress rebase, merge, or cherry-pick in the workspace (unit u8) —
+ * `tot preview`/`tot submit` must NEVER auto-commit over one of these. A rebase that
+ * stopped at "Could not apply" (or a merge/cherry-pick left with real conflicts) IS
+ * a dirty tree from `git status`'s point of view, so `autoCommitKnownTrees` would
+ * otherwise stage + commit the half-resolved content straight into a plain "content
+ * update" commit — silently finishing the git operation WRONG and losing whatever
+ * edit was still sitting in conflict markers or unresolved hunks (the live incident
+ * this guards against: a stalled rebase was never continued, `tot preview` ran
+ * anyway, and the developer's own edit was gone). Detection is worktree-safe:
+ * MERGE_HEAD/CHERRY_PICK_HEAD via plumbing refs (no direct `.git` path assumption),
+ * and rebase-merge/rebase-apply via `--git-path` (a linked worktree's git-dir lives
+ * OUTSIDE `<workspace>/.git`, so a literal `.git/rebase-merge` check would miss it).
+ * Returns which operation is in progress, or null when the tree is clean of one.
+ * @param {(cargs:string[])=>string} git  a `git -C <workspace>` runner
+ * @param {string} workspace  absolute path `git` runs `-C` against — `--git-path`'s
+ *   output may be relative, and Node's `existsSync` resolves relative paths against
+ *   the CLI process's own cwd, not the checkout, so this pins the resolution base.
+ * @returns {"rebase"|"merge"|"cherry-pick"|null}
+ */
+export function detectInProgressGitOperation(git, workspace) {
+  const hasRef = (name) => {
+    try {
+      return git(["rev-parse", "-q", "--verify", name]).trim().length > 0;
+    } catch {
+      return false;
+    }
+  };
+  if (hasRef("MERGE_HEAD")) return "merge";
+  if (hasRef("CHERRY_PICK_HEAD")) return "cherry-pick";
+  const hasGitPath = (name) => {
+    try {
+      const p = git(["rev-parse", "--git-path", name]).trim();
+      // An empty result should never happen for a real `--git-path` (it always
+      // echoes SOME path, existing or not) — but treat it as "absent" rather than
+      // resolving it, since `resolvePath(workspace, "")` degrades to `workspace`
+      // itself, which trivially always exists (a false "rebase in progress" on
+      // every call, not just an occasional false negative).
+      return p.length > 0 && existsSync(resolvePath(workspace, p));
+    } catch {
+      return false;
+    }
+  };
+  if (hasGitPath("rebase-merge") || hasGitPath("rebase-apply")) return "rebase";
+  return null;
+}
+
+/** The abort command that recovers from each in-progress git operation, so the
+ *  refusal below can tell a developer exactly what to run. Pure. */
+export function abortCommandFor(op) {
+  return op === "merge" ? "git merge --abort" : op === "cherry-pick" ? "git cherry-pick --abort" : "git rebase --abort";
+}
+
 /**
  * Auto-commit the known content trees before previewing (unit u2). On a DIRTY
  * tree `tot preview` commits your content edits for you, so a preview always
@@ -420,16 +673,21 @@ export function buildAutoCommitMessage({ message, files = [], statLine = "" } =
  * (preview whatever's already committed — u1's behavior).
  *
  * Returns exactly one of:
- *   { skipped: true }               — --no-commit.
- *   { clean: true }                 — nothing dirty; preview HEAD as-is.
- *   { refused, unknown, known }     — out-of-scope dirt; caller refuses + hints.
- *   { committed: true, sha, files } — staged the known dirty paths and committed.
+ *   { skipped: true }                 — --no-commit.
+ *   { inProgress: "rebase"|… }        — a rebase/merge/cherry-pick is unresolved;
+ *                                       caller refuses rather than auto-committing
+ *                                       over the developer's own half-resolved tree.
+ *   { clean: true }                   — nothing dirty; preview HEAD as-is.
+ *   { refused, unknown, known }       — out-of-scope dirt; caller refuses + hints.
+ *   { committed: true, sha, files }   — staged the known dirty paths and committed.
  *
  * @param {(cargs:string[])=>string} git  a `git -C <workspace>` runner
- * @param {{ message?: string|null, noCommit?: boolean }} [opts]
+ * @param {{ message?: string|null, noCommit?: boolean, workspace?: string }} [opts]
  */
-export function autoCommitKnownTrees(git, { message = null, noCommit = false } = {}) {
+export function autoCommitKnownTrees(git, { message = null, noCommit = false, workspace = "." } = {}) {
   if (noCommit) return { skipped: true };
+  const inProgress = detectInProgressGitOperation(git, workspace);
+  if (inProgress) return { inProgress };
   const status = git(["-c", "core.quotePath=false", "status", "--porcelain", "--untracked-files=all"]);
   const dirty = parsePorcelainPaths(status);
   if (dirty.length === 0) return { clean: true };
@@ -484,16 +742,17 @@ 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;
     }
     const buf = readBlob(e.path);
     const asUtf8 = buf.toString("utf8");
-    const isCleanUtf8 = !asUtf8.includes("") && Buffer.from(asUtf8, "utf8").equals(buf);
+    const isCleanUtf8 = !asUtf8.includes("\x00") && Buffer.from(asUtf8, "utf8").equals(buf);
     patch.push(
       isCleanUtf8
         ? { path: e.path, content: asUtf8 }
@@ -523,41 +782,14 @@ export function repoNameFromRemote(remoteUrl) {
 
 // ─── fresh-forge-credential push (decision B — the invited-dev 401 dead-end) ─────
 
-/**
- * Split an authenticated forge remote URL (basic-auth `user:token@host`, as the
- * MCP mints it via `tenant_checkout`) into its tokenless public URL + the embedded
- * credential, so the token can be handed to git EPHEMERALLY for one push instead of
- * being persisted in `.git/config`. Returns null when the URL won't parse or carries
- * no token — the caller then falls back to the checkout's existing remote. Pure —
- * unit-tested.
- * @param {string} remoteUrl
- * @returns {{ publicUrl: string, username: string, token: string }|null}
- */
-export function splitAuthedRemote(remoteUrl) {
-  try {
-    const u = new URL(String(remoteUrl));
-    const token = u.password ? decodeURIComponent(u.password) : "";
-    if (!token) return null;
-    const username = u.username ? decodeURIComponent(u.username) : "";
-    return { publicUrl: `${u.protocol}//${u.host}${u.pathname}`, username, token };
-  } catch {
-    return null;
-  }
-}
-
-/**
- * The `http.extraheader` value that hands a basic-auth credential to a SINGLE git
- * invocation (base64 of `user:token`) — so a freshly-minted forge token
- * authenticates one push without ever being written to `.git/config`. Pure —
- * unit-tested.
- * @param {string} username
- * @param {string} token
- * @returns {string}
- */
-export function basicAuthExtraHeader(username, token) {
-  const b64 = Buffer.from(`${username}:${token}`, "utf8").toString("base64");
-  return `Authorization: Basic ${b64}`;
-}
+// splitAuthedRemote / basicAuthExtraHeader now live in ../git-credential.mjs (unit
+// u10) — a dependency-free module BOTH this file and clone.mjs/commands/
+// git-credential.mjs need, so they moved out of here to avoid a submit.mjs ↔
+// clone.mjs import cycle. Re-exported so every existing import of these two names
+// FROM submit.mjs (this file's own callers below, plus tests) keeps working
+// unchanged.
+export { splitAuthedRemote, basicAuthExtraHeader } from "../git-credential.mjs";
+import { splitAuthedRemote, basicAuthExtraHeader, ensureTokenlessRemote } from "../git-credential.mjs";
 
 /**
  * Recognise a forge auth failure (expired / invalid push token) in a failed git
@@ -605,7 +837,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 } = {}) {
@@ -691,25 +923,79 @@ 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 };
 }
 
+/**
+ * The forge state of ONE candidate (`"open"`/`"merged"`/`"closed"`/…), read by
+ * changeId via `candidate_status`, or null when it can't be POSITIVELY determined —
+ * the candidate isn't found, carries no state, or the read throws. null ("couldn't
+ * tell") is the deliberately SAFE answer: the caller (resolveActivePointer) then
+ * behaves exactly as if the pointer were still live, so a purely-diagnostic check
+ * that can't run never blocks, changes, or crashes a submit (u17 acceptance #3).
+ * Tolerates the tool returning a bare candidate, a `{candidates:[…]}` list, or a
+ * plain array. Injectable client for tests.
+ * @param {{callTool:Function}} client
+ * @param {{ repo: string, changeId: string }} opts
+ * @returns {Promise<string|null>}
+ */
+export async function candidateStateFor(client, { repo, changeId }) {
+  try {
+    const r = await client.callTool("candidate_status", { repo, changeId });
+    const c = Array.isArray(r)
+      ? r.find((x) => x?.changeId === changeId)
+      : Array.isArray(r?.candidates)
+        ? r.candidates.find((x) => x?.changeId === changeId)
+        : r;
+    return c && typeof c.state === "string" ? c.state : null;
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * u17 — before REUSING a remembered active-candidate pointer, confirm its PR is
+ * still open. The live incident this guards against: after a candidate PR merged, a
+ * plain `tot preview` reused the remembered pointer, force-pushed onto the now-DEAD
+ * candidate branch (stale old-base history), and `candidate_open` opened a NEW PR
+ * from it — inheriting a guaranteed conflict from the very first commit. When the
+ * pointer's PR has gone terminal (merged/closed) we DROP it here, so `chooseChangeId`
+ * falls back to the stable per-branch id exactly as if no pointer existed.
+ *
+ * PURELY DIAGNOSTIC — never blocks a submit over the check itself: no pointer, no
+ * repo, or a check that errors / can't positively confirm terminal all resolve to
+ * `{ active }` UNCHANGED (behave exactly as before). Only a POSITIVELY terminal
+ * state drops the pointer. When it does, `dropped` carries the old changeId + the
+ * terminal state so the caller can tell the operator and forget the on-disk pointer.
+ * Injectable client for tests.
+ * @param {{callTool:Function}} client
+ * @param {{ repo: string|null, active: string|null }} opts
+ * @returns {Promise<{ active: string|null, dropped?: { changeId: string, state: string } }>}
+ */
+export async function resolveActivePointer(client, { repo, active }) {
+  if (!active || !repo) return { active };
+  const state = await candidateStateFor(client, { repo, changeId: active });
+  if (isTerminalCandidateState(state)) return { active: null, dropped: { changeId: active, state: /** @type {string} */ (state) } };
+  return { active };
+}
+
 /**
  * The ref `tot preview`/`tot submit` pushes to (b03 — stop force-pushing the
  * SHARED `preview` ref). An explicit `--ref` always wins — the escape hatch /
@@ -836,7 +1122,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 } : {}),
@@ -874,6 +1160,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 {
@@ -899,6 +1194,63 @@ export async function run(argv, ctx, { verb = "preview" } = {}) {
   const tenant = ctx.tenant;
   const git = (cargs) => execFileSync("git", ["-C", workspace, ...cargs], { stdio: ["ignore", "pipe", "pipe"] }).toString();
 
+  // Self-heal a LEGACY checkout (unit u10): strip any token still embedded in
+  // `origin`'s URL and install the credential helper, so this run (and every one
+  // after) mints fresh creds through `tot` instead of relying on one that quietly
+  // expired. Best-effort — never blocks the actual preview on a migration hiccup.
+  try {
+    ensureTokenlessRemote(git);
+  } catch {
+    /* best-effort — see above */
+  }
+
+  // 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
+  // forge compares it against the real (already-advanced) base. --skip-freshness
+  // opts out (e.g. offline/CI, or a deliberate re-run against a known-good tip).
+  if (!args.skipFreshness) {
+    let staleTip = null;
+    try {
+      staleTip = detectStaleBase(git, FRESHNESS_BASE_BRANCH);
+    } catch {
+      staleTip = null; // never block a submit on the preflight's OWN failure
+    }
+    if (staleTip) {
+      const msg = `your checkout is behind the store — "${FRESHNESS_BASE_BRANCH}" has moved since your last sync`;
+      console.error(
+        fail(msg, `tot sync   (fetches the latest ${FRESHNESS_BASE_BRANCH} + merges it into your branch, then re-run \`tot ${verb}\`) — or re-run with --skip-freshness to build anyway`),
+      );
+      emitJson(args, buildJsonResult({ ok: false, error: msg }));
+      return 1;
+    }
+
+    // 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)`,
+      );
+    }
+  }
+
+
   // 0. auto-commit the known content trees (unit u2) — on a dirty tree, commit your
   //    content edits BEFORE previewing so the preview reflects your working changes.
   //    Only content/, public/, theme.json, .tot/ (staged by explicit path, never
@@ -906,7 +1258,7 @@ export async function run(argv, ctx, { verb = "preview" } = {}) {
   //    --no-commit opts out (preview whatever's already committed).
   let auto;
   try {
-    auto = autoCommitKnownTrees(git, { message: args.message, noCommit: args.noCommit });
+    auto = autoCommitKnownTrees(git, { message: args.message, noCommit: args.noCommit, workspace });
   } catch (e) {
     emitGitOp("commit", false, { command: verb, errorClass: "git_commit_failed" });
     const msg = `auto-commit failed: ${String(e?.stderr || e?.message || e)}`;
@@ -915,6 +1267,20 @@ export async function run(argv, ctx, { verb = "preview" } = {}) {
     return 1;
   }
   if (auto.committed) emitGitOp("commit", true, { command: verb });
+  if (auto.inProgress) {
+    const abortCmd = abortCommandFor(auto.inProgress);
+    const msg = `a ${auto.inProgress} is still in progress here`;
+    console.error(
+      fail(
+        msg,
+        `finish it (resolve + continue) or back out (\`${abortCmd}\`), then re-run \`tot ${verb}\` — `
+          + "auto-committing over an unresolved rebase/merge/cherry-pick would fold your half-resolved "
+          + "tree into a plain content commit and can lose whatever edit was still unresolved",
+      ),
+    );
+    emitJson(args, buildJsonResult({ ok: false, error: msg }));
+    return 1;
+  }
   if (auto.refused) {
     console.error(
       fail(
@@ -937,6 +1303,15 @@ export async function run(argv, ctx, { verb = "preview" } = {}) {
   // 1. validate locally — refuse on errors.
   if (!args.skipValidate) {
     const { ok, findings } = validateTenant(workspace, { tenantId: tenant, scope: ctx.config?.scope });
+    // Advisory but LOUD: git conflict markers must never slip past as "validated"
+    // (the half-resolved-rebase incident). Surfaced on the ok path too — warnings
+    // are otherwise swallowed here — but they never block the submit.
+    const conflicts = findings.filter((f) => f.rule === "git-conflict-markers");
+    if (conflicts.length) {
+      console.error(`\n⚠ git conflict markers in submitted content (${conflicts.length} file(s)) — an unfinished merge/rebase?`);
+      for (const f of conflicts) console.error(`  ⚠ ${f.file} — ${f.message}`);
+      console.error("  The preview will still build, but it will serve the broken markers. Resolve before shipping.\n");
+    }
     if (!ok) {
       const errs = findings.filter((f) => f.level === ERROR);
       console.error(
@@ -1008,7 +1383,7 @@ export async function run(argv, ctx, { verb = "preview" } = {}) {
   // needed — so they're available even on the no-session fallback path below.
   const branch = currentBranch(gitSafe);
   const statePath = defaultCandidateStatePath(env);
-  const active = repo ? readActiveChangeId(statePath, { mcpUrl: baseUrl, repo, branch }) : null;
+  let active = repo ? readActiveChangeId(statePath, { mcpUrl: baseUrl, repo, branch }) : null;
 
   let session;
   try {
@@ -1020,7 +1395,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)`);
@@ -1059,12 +1434,36 @@ export async function run(argv, ctx, { verb = "preview" } = {}) {
     return 0;
   }
 
+  // u17 — before REUSING a remembered active pointer, confirm its PR is still open.
+  // If it merged/closed we DROP it (and forget it on disk) so chooseChangeId falls
+  // back to the stable id, rather than force-pushing onto a now-dead candidate branch
+  // and opening a NEW PR that inherits a guaranteed conflict (the live incident this
+  // guards against). Skipped under --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.forkCandidate) {
+    try {
+      await client.callTool("client_switch", { tenant });
+    } catch { /* scope bind is best-effort; candidateStateFor tolerates a miss */ }
+    const resolved = await resolveActivePointer(client, { repo, active });
+    if (resolved.dropped) {
+      console.error(
+        `~ remembered candidate ${resolved.dropped.changeId} is ${resolved.dropped.state} — dropping it and submitting fresh (a ${resolved.dropped.state} PR can't be reused).`,
+      );
+      try {
+        clearActiveChangeId(statePath, { mcpUrl: baseUrl, repo, branch });
+      } catch { /* best-effort local cleanup — a miss just re-checks next run */ }
+    }
+    active = resolved.active;
+  }
+
   // Which candidate (and therefore which isolated ref, b03) this submit targets —
   // decided now, with a real session, so the SAME id backs both the raw git push
   // (right below) and the PR-backed candidate (step 2b): the two never point at
-  // different branches. See chooseChangeId's doc for the --new / active-pointer
-  // rules.
-  let { changeId, stableId, persist } = chooseChangeId({ tenant, actorKey: actorKeyFor(session), branch, active, isNew: args.new });
+  // 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);
 
@@ -1132,6 +1531,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
@@ -1372,7 +1826,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 {
@@ -1428,7 +1882,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[]}
  */
@@ -1485,6 +1939,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) {