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

package/src/commands/submit.mjs

@@ -40,7 +40,8 @@
  * 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";
@@ -55,6 +56,7 @@ import {
   defaultCandidateStatePath,
   readActiveChangeId,
   writeActiveChangeId,
+  clearActiveChangeId,
   mintFreshChangeId,
   isTerminalCandidateState,
   isDefaultBranch,
@@ -90,6 +92,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 +107,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, json: boolean, new: 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, json: false, new: false, help: false };
   for (let i = 0; i < argv.length; i++) {
     const t = argv[i];
     if (t === "--mcp") a.mcp = argv[++i];
@@ -114,6 +119,7 @@ export function parseArgs(argv) {
     else if (t === "--summary-file") a.summaryFile = argv[++i];
     else if (t === "--json") a.json = true;
     else if (t === "--skip-validate") a.skipValidate = true;
+    else if (t === "--skip-freshness") a.skipFreshness = true;
     else if (t === "--no-commit") a.noCommit = true;
     else if (t === "--no-wait") a.noWait = true;
     else if (t === "--watch") a.watch = true;
@@ -137,6 +143,8 @@ export function renderUsage(verb = "preview") {
   tot ${verb} --new              open a NEW candidate PR instead of updating your open one
   tot ${verb} --watch            stay attached through reconcile + compliance + accept (long-poll)
   tot ${verb} --skip-validate    push without the local lint (not recommended)
+  tot ${verb} --skip-freshness   skip the stale-base check (not recommended — may build a
+                                  candidate rooted in an already-superseded base)
   tot ${verb} --no-commit        don't auto-commit a dirty tree — preview only what's already committed
   tot ${verb} --ref <name>       push ref (default: your own isolated candidate ref — see \`tot pr\`)
   tot ${verb} -m "<title>"       one-line summary of what changed (the approver sees this)
@@ -159,6 +167,9 @@ export function renderUsage(verb = "preview") {
   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}\`.
+
   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 +337,55 @@ 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 --new` built a candidate rooted in the OLD tip and got an
+ * instant, entirely avoidable "not mergeable" the moment it was compared
+ * against the real, already-advanced `preview`.
+ *
+ * Compares what the LOCAL checkout believes the base's tip is
+ * (`refs/remotes/origin/<branch>`, only as fresh as the last explicit fetch)
+ * against its ACTUAL current tip on the forge (`git ls-remote`, a lightweight
+ * single-ref read — no full fetch, no local ref mutated). Returns the live
+ * remote sha when local's cached view is behind it, or `null` when: the two
+ * already agree, there is no local tracking ref to compare against yet (a
+ * checkout that has simply never fetched this branch — never a false block on
+ * that), or the remote can't be reached right now (a network hiccup must
+ * never block a submit that would otherwise succeed; the push itself is the
+ * real connectivity test). Pure git I/O via the injected runner — unit-tested.
+ * @param {(cargs:string[])=>string} git
+ * @param {string} branch
+ * @returns {string|null}
+ */
+export function detectStaleBase(git, branch) {
+  let localSha = "";
+  try {
+    localSha = git(["rev-parse", "-q", "--verify", `refs/remotes/origin/${branch}`]).trim();
+  } catch {
+    return null; // never fetched this branch locally — nothing cached to be stale
+  }
+  if (!localSha) return null;
+  let remoteSha = "";
+  try {
+    remoteSha = (git(["ls-remote", "origin", branch]).split(/\s+/)[0] || "").trim();
+  } catch {
+    return null; // can't reach the remote right now — don't block on a network hiccup
+  }
+  if (!remoteSha || remoteSha === localSha) return null;
+  return remoteSha;
+}
+
 // ─── auto-commit the known content trees (unit u2) ───────────────────────────────
 
 /**
@@ -410,6 +470,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 +533,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 +602,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 +642,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 +697,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 } = {}) {
@@ -710,6 +802,59 @@ export function chooseChangeId({ tenant, actorKey, branch = null, active = null,
   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 +981,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 } : {}),
@@ -899,6 +1044,39 @@ 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 */
+  }
+
+  // Freshness preflight (unit u16) — BEFORE minting anything: is the checkout's
+  // cached view of the base branch already behind the store? A candidate built
+  // on a stale base is an instant, avoidable "not mergeable" the moment the
+  // forge compares it against the real (already-advanced) base. --skip-freshness
+  // opts out (e.g. offline/CI, or a deliberate re-run against a known-good tip).
+  if (!args.skipFreshness) {
+    let staleTip = null;
+    try {
+      staleTip = detectStaleBase(git, FRESHNESS_BASE_BRANCH);
+    } catch {
+      staleTip = null; // never block a submit on the preflight's OWN failure
+    }
+    if (staleTip) {
+      const msg = `your checkout is behind the store — "${FRESHNESS_BASE_BRANCH}" has moved since your last sync`;
+      console.error(
+        fail(msg, `tot sync   (fetches the latest ${FRESHNESS_BASE_BRANCH} + merges it into your branch, then re-run \`tot ${verb}\`) — or re-run with --skip-freshness to build anyway`),
+      );
+      emitJson(args, buildJsonResult({ ok: false, error: msg }));
+      return 1;
+    }
+  }
+
+
   // 0. auto-commit the known content trees (unit u2) — on a dirty tree, commit your
   //    content edits BEFORE previewing so the preview reflects your working changes.
   //    Only content/, public/, theme.json, .tot/ (staged by explicit path, never
@@ -906,7 +1084,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 +1093,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 +1129,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 +1209,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 {
@@ -1059,6 +1260,30 @@ 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 --new (chooseChangeId ignores `active` there
+  // anyway). Purely diagnostic: a check that errors leaves the pointer untouched.
+  // Needs the tenant scope bound for candidate_status to resolve — idempotent with
+  // the later client_switch / the fresh-mint checkoutTenant.
+  if (active && repo && !args.new) {
+    try {
+      await client.callTool("client_switch", { tenant });
+    } catch { /* scope bind is best-effort; candidateStateFor tolerates a miss */ }
+    const resolved = await resolveActivePointer(client, { repo, active });
+    if (resolved.dropped) {
+      console.error(
+        `~ remembered candidate ${resolved.dropped.changeId} is ${resolved.dropped.state} — dropping it and submitting fresh (a ${resolved.dropped.state} PR can't be reused).`,
+      );
+      try {
+        clearActiveChangeId(statePath, { mcpUrl: baseUrl, repo, branch });
+      } catch { /* best-effort local cleanup — a miss just re-checks next run */ }
+    }
+    active = resolved.active;
+  }
+
   // Which candidate (and therefore which isolated ref, b03) this submit targets —
   // decided now, with a real session, so the SAME id backs both the raw git push
   // (right below) and the PR-backed candidate (step 2b): the two never point at
@@ -1372,7 +1597,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 +1653,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 +1710,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) {

package/src/commands/sync.mjs

@@ -31,6 +31,7 @@
  */
 import { execFileSync } from "node:child_process";
 import { fail } from "../errors.mjs";
+import { ensureTokenlessRemote } from "../git-credential.mjs";
 
 /** The protected branch `tot sync` fetches + merges from by default. */
 export const DEFAULT_SYNC_BRANCH = "preview";
@@ -159,6 +160,16 @@ export async function run(argv, ctx) {
     }
   };
 
+  // Self-heal a LEGACY checkout (unit u10, absorbs u7): `tot login` refreshes
+  // this CLI's own session, never the token baked into a checkout's remote at
+  // clone time — the exact reason a stale checkout's `git fetch origin` (below)
+  // used to 401 even right after signing back in. Best-effort, never blocks sync.
+  try {
+    ensureTokenlessRemote(git);
+  } catch {
+    /* best-effort — see above */
+  }
+
   // Refuse a dirty tree up front — a merge on top of uncommitted edits is how
   // local work gets silently entangled with the merge, and we never sweep
   // anything in with `git add -A`. Commit or stash first, then re-run.

package/src/commands/validate.mjs

@@ -71,12 +71,13 @@ export function run(argv, ctx) {
     console.error(fail(target.error, "tot clone <tenant>, or pass --workspace <dir>"));
     return 2;
   }
-  if (!existsSync(target.dir)) {
-    console.error(fail(`no tenant directory at ${target.dir}`, "confirm the path, or `tot clone <tenant>`"));
+  const dir = /** @type {string} */ (target.dir);
+  if (!existsSync(dir)) {
+    console.error(fail(`no tenant directory at ${dir}`, "confirm the path, or `tot clone <tenant>`"));
     return 2;
   }
 
-  const { ok, findings } = validateTenant(target.dir, {
+  const { ok, findings } = validateTenant(dir, {
     tenantId: target.tenantId ?? undefined,
     scope: target.scope ?? undefined,
     // A checkout / bare-tenant target is served by the ToT storefront platform, so
@@ -92,7 +93,12 @@ export function run(argv, ctx) {
 
   const errors = findings.filter((f) => f.level === ERROR);
   const warns = findings.filter((f) => f.level === WARN);
-  console.log(`\ntot validate — ${target.tenantId ?? target.dir}\n`);
+  // Never present the checkout PATH as if it were the tenant name — when the
+  // tenant couldn't be resolved (e.g. an invalid/missing .tot/config.json),
+  // the findings below say why; the header should say so too, not disguise
+  // a directory as a domain.
+  const label = target.tenantId ? target.tenantId : `(tenant unresolved) ${target.dir}`;
+  console.log(`\ntot validate — ${label}\n`);
   for (const f of findings) {
     const tag = f.level === ERROR ? "✗" : "⚠";
     console.log(`  ${tag} [${f.rule}] ${f.file}\n      ${f.message}${f.fix ? `\n      → ${f.fix}` : ""}`);

package/src/dev-heartbeat.mjs

@@ -35,7 +35,8 @@ const OS_INFO = { os: os.platform(), osVersion: os.release(), arch: os.arch() };
  * an activity URL and a bearer token. Never throws — a failed/offline hosted
  * worker just means the cockpit doesn't light up this beat.
  * @param {{ activityUrl?: string, token?: string, url?: string,
- *   cliVersion?: string, runnerVersion?: string|null, editor?: string|null }} args
+ *   cliVersion?: string, runnerVersion?: string|null, editor?: string|null,
+ *   cwd?: string|null }} args
  */
 export function postHeartbeat({ activityUrl, token, url, cliVersion, runnerVersion, editor, cwd } = {}) {
   if (!activityUrl || !token) return undefined;

package/src/errors.mjs

@@ -32,13 +32,17 @@ function versionFooter() {
 
 /**
  * A failure worth surfacing with a concrete next step.
+ * @typedef {object} CliErrorOpts
+ * @property {string} [next]     - the exact command (or one-line instruction) to run next.
+ * @property {number} [exitCode] - process exit code to use (default 1).
+ * @property {unknown} [cause]
+ *
  * @param {string} what   - what went wrong, in plain words.
- * @param {{ next?: string, exitCode?: number, cause?: unknown }} [opts]
- *   next     - the exact command (or one-line instruction) to run next.
- *   exitCode - process exit code to use (default 1).
+ * @param {CliErrorOpts} [opts]
  */
 export class CliError extends Error {
-  constructor(what, { next, exitCode = 1, cause } = {}) {
+  constructor(what, opts = {}) {
+    const { next, exitCode = 1, cause } = opts;
     super(what);
     this.name = "CliError";
     this.what = what;