@tokenoftrust/cli 1.4.0-rc.1 → 1.4.0-rc.11

package/src/commands/submit.mjs

@@ -42,16 +42,25 @@ 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";
 import { validateTenant, ERROR } from "../validate.mjs";
 import { openBrowser } from "../open.mjs";
 import { startProgress } from "../progress.mjs";
 import { fail } from "../errors.mjs";
+import {
+  defaultCandidateStatePath,
+  readActiveChangeId,
+  writeActiveChangeId,
+  mintFreshChangeId,
+  isTerminalCandidateState,
+  isDefaultBranch,
+} from "../candidate-state.mjs";
 
 const DEFAULT_MCP_URL = "https://mcp.tokenoftrust.com";
 const DEFAULT_REF = "preview";
 
 export function parseArgs(argv) {
-  const a = { mcp: null, identity: null, ref: DEFAULT_REF, skipValidate: false, noWait: false, watch: false, noOpen: false, message: null, summary: null, help: false };
+  const a = { mcp: null, identity: null, ref: DEFAULT_REF, skipValidate: false, noWait: false, watch: false, noOpen: false, noCommit: false, message: null, summary: null, new: false, help: false };
   for (let i = 0; i < argv.length; i++) {
     const t = argv[i];
     if (t === "--mcp") a.mcp = argv[++i];
@@ -60,28 +69,48 @@ 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 === "--skip-validate") a.skipValidate = 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 === "--help" || t === "-h") a.help = true;
   }
   return a;
 }
 
-const USAGE = `tot submit — submit your store for preview
+/**
+ * Render the usage block for whichever verb invoked this flow. `preview` is the
+ * first-class verb; `submit`/`deploy` reach the same flow as teaching aliases, so
+ * the help they print names the verb the developer actually typed (see preview.mjs).
+ * @param {string} [verb]
+ */
+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} --watch            stay attached through reconcile + compliance + accept (long-poll)
+  tot ${verb} --skip-validate    push without the local lint (not recommended)
+  tot ${verb} --no-commit        don't auto-commit a dirty tree — preview only what's already committed
+  tot ${verb} --ref <name>       push ref (default: ${DEFAULT_REF})
+  tot ${verb} -m "<title>"       one-line summary of what changed (the approver sees this)
+  tot ${verb} --summary "<text>" longer description to accompany the title
+  tot ${verb} --no-wait          push and exit without polling for the reconcile result
+  tot ${verb} --no-open          don't open the preview URL in the browser on success
+  tot ${verb} --mcp <url>        MCP base URL (default: env MCP_BASE_URL / TOT_MCP_URL)
 
-  tot submit                    validate → push the preview ref → stream the result
-  tot submit --watch            stay attached through reconcile + compliance + accept (long-poll)
-  tot submit --skip-validate    push without the local lint (not recommended)
-  tot submit --ref <name>       push ref (default: ${DEFAULT_REF})
-  tot submit -m "<title>"       one-line summary of what changed (the approver sees this)
-  tot submit --summary "<text>" longer description to accompany the title
-  tot submit --no-wait          push and exit without polling for the reconcile result
-  tot submit --no-open          don't open the preview URL in the browser on success
-  tot submit --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
+  merged or closed, a re-run automatically opens a fresh one.
+
+  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
   what's live in preview) so the change record the approver reviews is never blank.`;
+}
 
 // Default bounded wait (~20s, matching the pre-E2 fixed poll's total budget) vs.
 // --watch's longer per-call long-poll + more attempts (~8 min ceiling) for a dev
@@ -123,6 +152,126 @@ function printChangeSummary({ title, body, autoTitle }) {
   if (autoTitle) console.log(`  (auto-generated from git — pass -m "…" / --summary "…" to refine)`);
 }
 
+// ─── auto-commit the known content trees (unit u2) ───────────────────────────────
+
+/**
+ * The content trees `tot preview` may auto-commit on a dirty tree — and ONLY
+ * these. A store's reviewable content lives here; anything a developer edits
+ * OUTSIDE these (src/, config, stray files) is out of scope for an automatic
+ * commit and is REFUSED rather than silently swept in. Explicit paths only —
+ * never `git add -A`/`git add .`.
+ */
+export const KNOWN_CONTENT_TREES = ["content/", "public/", ".tot/"];
+export const KNOWN_CONTENT_FILES = ["theme.json"];
+
+/** Is this repo-relative path inside a known content tree (or the one known
+ *  top-level file)? Pure — unit-tested. */
+export function isKnownContentPath(path) {
+  const p = String(path).replace(/^\.\//, "");
+  return KNOWN_CONTENT_FILES.includes(p) || KNOWN_CONTENT_TREES.some((t) => p.startsWith(t));
+}
+
+/**
+ * Flatten `git status --porcelain` (v1) output to the ordered, deduped set of
+ * dirty repo-relative paths. Each line is `XY <path>`; a rename/copy is
+ * `XY <old> -> <new>` and contributes BOTH paths (the old one is being removed
+ * from its tree too, so it's part of the scope decision). Run with
+ * `core.quotePath=false` upstream so unicode paths arrive literal. Pure —
+ * unit-tested.
+ * @param {string} text
+ * @returns {string[]}
+ */
+export function parsePorcelainPaths(text) {
+  const seen = new Set();
+  const out = [];
+  for (const line of String(text).split("\n")) {
+    if (line.length < 4) continue; // "XY p" is the shortest real entry
+    const rest = line.slice(3);
+    const parts = rest.includes(" -> ") ? rest.split(" -> ") : [rest];
+    for (const raw of parts) {
+      const p = raw.trim();
+      if (p && !seen.has(p)) {
+        seen.add(p);
+        out.push(p);
+      }
+    }
+  }
+  return out;
+}
+
+/**
+ * Partition dirty paths into the known content trees vs everything else. Pure —
+ * unit-tested.
+ * @param {string[]} paths
+ * @returns {{ known: string[], unknown: string[] }}
+ */
+export function classifyDirtyPaths(paths) {
+  const known = [];
+  const unknown = [];
+  for (const p of paths) (isKnownContentPath(p) ? known : unknown).push(p);
+  return { known, unknown };
+}
+
+/** A concise auto commit subject when the developer gave no -m — derived from the
+ *  staged files so the commit is never a blank "(untitled change)". Pure. */
+export function autoCommitSubject(files = []) {
+  if (files.length === 0) return "update store content";
+  if (files.length === 1) return `update ${files[0]}`;
+  return `update ${files.length} content files`;
+}
+
+/**
+ * The message for `tot preview`'s pre-preview auto-commit. An explicit `-m` wins
+ * as the subject; otherwise autoCommitSubject derives one from the staged files.
+ * The body (shortstat + file list) is built by the SAME buildChangeSummary the
+ * approver summary uses, so a commit and the change record it later feeds read
+ * consistently. Returns a git commit message (subject, blank line, body). Pure —
+ * unit-tested.
+ * @param {{ message?: string|null, files?: string[], statLine?: string }} input
+ * @returns {string}
+ */
+export function buildAutoCommitMessage({ message, files = [], statLine = "" } = {}) {
+  const subject = (message && message.trim()) || autoCommitSubject(files);
+  const { body } = buildChangeSummary({ message: subject, files, statLine });
+  return body.length ? `${subject}\n\n${body.join("\n")}` : subject;
+}
+
+/**
+ * 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
+ * reflects your working changes — but ONLY the known trees (content/, public/,
+ * theme.json, .tot/), staged by EXPLICIT path (never `git add -A`). If anything
+ * dirty falls OUTSIDE those, it REFUSES (out-of-scope src/config/stray edits are
+ * never silently swept into a store commit). --no-commit opts out entirely
+ * (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.
+ *
+ * @param {(cargs:string[])=>string} git  a `git -C <workspace>` runner
+ * @param {{ message?: string|null, noCommit?: boolean }} [opts]
+ */
+export function autoCommitKnownTrees(git, { message = null, noCommit = false } = {}) {
+  if (noCommit) return { skipped: true };
+  const status = git(["-c", "core.quotePath=false", "status", "--porcelain", "--untracked-files=all"]);
+  const dirty = parsePorcelainPaths(status);
+  if (dirty.length === 0) return { clean: true };
+  const { known, unknown } = classifyDirtyPaths(dirty);
+  if (unknown.length) return { refused: true, unknown, known };
+  // Stage ONLY the known dirty paths, each by explicit path — this records adds,
+  // modifications AND deletions within them, and can never reach outside the set.
+  git(["add", "--", ...known]);
+  const files = parseNameStatus(git(["diff", "--cached", "--name-status"])).map((e) => e.path);
+  const statLine = git(["diff", "--cached", "--shortstat"]).trim();
+  const msg = buildAutoCommitMessage({ message, files, statLine });
+  git(["commit", "--no-verify", "-m", msg]);
+  const sha = git(["rev-parse", "HEAD"]).trim();
+  return { committed: true, sha, files };
+}
+
 // ─── PR-backed candidate (g1b candidate_open, unit c1) ──────────────────────────
 
 /**
@@ -198,22 +347,165 @@ 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}`;
+}
+
+/**
+ * Recognise a forge auth failure (expired / invalid push token) in a failed git
+ * push's stderr, so `tot preview` can re-mint a fresh credential and retry once
+ * rather than dead-ending on a stale token (the belt-and-suspenders half of
+ * decision B). Pure — unit-tested.
+ * @param {string} text
+ * @returns {boolean}
+ */
+export function isForgeAuthError(text) {
+  return /\b40[13]\b|failed to authenticate|authentication failed|invalid credentials|access denied/i.test(
+    String(text || ""),
+  );
+}
+
+/**
+ * Derive the checkout's forge tag from its repo name (`"<tenant>-<tag>"`), so a
+ * re-mint targets the SAME repo the checkout points at. Defaults to "main" when the
+ * repo is bare (`"<tenant>"`, post-8425) or the `<tenant>-` prefix doesn't match, so
+ * the mint degrades to the clone default rather than a wrong tag. Pure —
+ * unit-tested.
+ * @param {string|null} repoName
+ * @param {string} tenant
+ * @returns {string}
+ */
+export function tagFromRepoName(repoName, tenant) {
+  const r = String(repoName || "");
+  const prefix = `${tenant}-`;
+  return r.startsWith(prefix) && r.length > prefix.length ? r.slice(prefix.length) : "main";
+}
+
+/**
+ * Push the preview ref (decision B): mint a FRESH, short-lived forge credential
+ * right before the push and hand it to git EPHEMERALLY (via `http.extraheader` on
+ * a per-invocation `-c` — never written to `.git/config`), re-minting once on an
+ * auth failure. The push credential the MCP baked into `.git/config` at clone time
+ * expires within hours; reusing that stale embedded token is the invited-dev
+ * "`tot preview` → Gitea 401 dead-end". We push over the named `origin` remote with
+ * its URL overridden to the tokenless public URL for this one invocation, so the
+ * remote-tracking ref still updates while no long-lived secret lands on disk.
+ *
+ * When the mint is unavailable (older MCP, transient failure — `mintRemote` returns
+ * null) or the minted URL carries no parseable token, it falls back to pushing over
+ * the checkout's EXISTING remote (pre-B behavior) — no regression.
+ *
+ * @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
+ * @returns {Promise<{ out: string }>}  resolves on a successful push; throws (git's error) otherwise
+ */
+export async function pushPreviewRef(git, mintRemote, { ref } = {}) {
+  const attempt = (remote) => {
+    const cred = splitAuthedRemote(remote);
+    if (!cred) {
+      // No fresh credential to hand over — push over the checkout's existing remote.
+      return git(["push", "-f", "origin", `HEAD:refs/heads/${ref}`]);
+    }
+    // Ephemeral auth: override the remote URL to the tokenless public URL and supply
+    // the credential as a one-shot Authorization header, with any OS credential
+    // helper disabled — none of this touches `.git/config`.
+    return git([
+      "-c", `remote.origin.url=${cred.publicUrl}`,
+      "-c", `http.extraheader=${basicAuthExtraHeader(cred.username, cred.token)}`,
+      "-c", "credential.helper=",
+      "push", "-f", "origin", `HEAD:refs/heads/${ref}`,
+    ]);
+  };
+
+  const remote = await mintRemote();
+  try {
+    return { out: attempt(remote) };
+  } catch (e) {
+    if (!isForgeAuthError(e?.stderr || e?.message || e)) throw e;
+    // Belt-and-suspenders: an auth failure re-mints a fresh credential and retries once.
+    return { out: attempt(await mintRemote()) };
+  }
+}
+
 /**
- * A STABLE per-developer-per-tenant candidate handle — so repeat `tot submit`
- * runs update the SAME PR instead of opening a new one each time
+ * A STABLE per-developer-per-tenant(-per-branch) candidate handle — so repeat
+ * `tot submit` runs update the SAME PR instead of opening a new one each time
  * (`candidate_open` is idempotent on `changeId`). No local state file needed:
- * it's a deterministic hash of the tenant + the acting identity, recomputed
- * fresh every run. Two different developers submitting to the same tenant get
- * two different (non-colliding) candidates. Pure — unit-tested.
+ * it's a deterministic hash of the tenant + the acting identity (+ the git branch
+ * on a non-default branch), recomputed fresh every run. Two different developers
+ * submitting to the same tenant get two different (non-colliding) candidates; so
+ * do the SAME developer on two different feature branches (u4 — branch-bound
+ * candidates), so `git checkout` acts as the PR switcher.
+ *
+ * ZERO MIGRATION: on the DEFAULT branch (main/master, or an unresolvable branch)
+ * the hash material is `tenant|actorKey` — byte-identical to the pre-u4 id — so an
+ * existing dev's current candidate keeps working untouched. A non-default branch
+ * folds the branch into the material (`tenant|actorKey|branch`) for its own id.
+ * Pure — unit-tested.
  * @param {string} tenant
  * @param {string} actorKey
+ * @param {string|null} [branch]  current git branch; default/null ⇒ today's id
  * @returns {string}
  */
-export function deriveChangeId(tenant, actorKey) {
-  const hash = createHash("sha256").update(`${tenant}|${actorKey}`).digest("hex").slice(0, 16);
+export function deriveChangeId(tenant, actorKey, branch = null) {
+  const material = isDefaultBranch(branch) ? `${tenant}|${actorKey}` : `${tenant}|${actorKey}|${branch}`;
+  const hash = createHash("sha256").update(material).digest("hex").slice(0, 16);
   return `local-${hash}`;
 }
 
+/**
+ * The current git branch in `workspace`, or null when it can't be resolved (a
+ * detached HEAD reports "HEAD", and any git failure is swallowed) — null is read
+ * by `isDefaultBranch` as the default branch, so an unresolvable branch keeps
+ * today's (branch-less) candidate rather than minting a spurious namespace. `git`
+ * is injected (a `(args:string[])=>string` runner) so it's testable. Best-effort.
+ * @param {(args:string[]) => string} git
+ * @returns {string|null}
+ */
+export function currentBranch(git) {
+  try {
+    const b = git(["rev-parse", "--abbrev-ref", "HEAD"]).trim();
+    return b && b !== "HEAD" ? b : null;
+  } catch {
+    return null;
+  }
+}
+
 /** The stable identity key behind `deriveChangeId` — the signed-in developer's
  *  email, falling back to the token, then a generic label. Single-plane: the only
  *  identity `tot` carries is the developer's own OAuth session. */
@@ -277,19 +569,26 @@ function reportCandidate(result, changeId) {
   console.log(`  ~ PR-backed candidate not opened: ${msg}`);
 }
 
-/** @param {string[]} argv @param {any} ctx */
-export async function run(argv, ctx) {
+/**
+ * The preview flow — validate, push the preview ref, open/update the PR-backed
+ * candidate, and stream back the reconcile/compliance/preview result. Reached by
+ * `tot preview` and, as teaching aliases, `tot submit` / `tot deploy` (preview.mjs
+ * wraps this and adds the verb-teaching hints). `verb` only brands the user-facing
+ * copy (usage + the not-in-checkout error) with whatever the developer typed.
+ * @param {string[]} argv @param {any} ctx @param {{ verb?: string }} [opts]
+ */
+export async function run(argv, ctx, { verb = "preview" } = {}) {
   const env = process.env;
   const args = parseArgs(argv);
   if (args.help) {
-    console.log(USAGE);
+    console.log(renderUsage(verb));
     return 0;
   }
   if (ctx.mode !== "checkout") {
     console.error(
       fail(
-        "`tot submit` runs from inside a tenant checkout",
-        "tot checkout <tenant> --clone <dir>   (then `cd` in, commit your work, and re-run)",
+        `\`tot ${verb}\` runs from inside a tenant checkout`,
+        "tot clone <tenant> <dir>   (then `cd` in, commit your work, and re-run)",
       ),
     );
     return 2;
@@ -298,6 +597,41 @@ export async function run(argv, ctx) {
   const tenant = ctx.tenant;
   const git = (cargs) => execFileSync("git", ["-C", workspace, ...cargs], { stdio: ["ignore", "pipe", "pipe"] }).toString();
 
+  // 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
+  //    `git add -A`); anything dirty outside those is refused, not silently swept in.
+  //    --no-commit opts out (preview whatever's already committed).
+  let auto;
+  try {
+    auto = autoCommitKnownTrees(git, { message: args.message, noCommit: args.noCommit });
+  } catch (e) {
+    console.error(
+      fail(
+        `auto-commit failed: ${String(e?.stderr || e?.message || e)}`,
+        "commit your content manually (git add / git commit), or re-run with --no-commit",
+      ),
+    );
+    return 1;
+  }
+  if (auto.refused) {
+    console.error(
+      fail(
+        `${auto.unknown.length} change(s) are outside the store content trees — refusing to auto-commit`,
+        "commit (or stash/revert) those yourself, then re-run — or use --no-commit to preview only what's already committed",
+      ) + "\n",
+    );
+    for (const p of auto.unknown) console.error(`  ✗ out of scope: ${p}`);
+    console.error(`\n  \`tot ${verb}\` auto-commits only: ${[...KNOWN_CONTENT_TREES, ...KNOWN_CONTENT_FILES].join(", ")}`);
+    if (auto.known.length) console.error(`  (in scope, would have been committed: ${auto.known.join(", ")})`);
+    return 1;
+  }
+  if (auto.committed) {
+    console.error(
+      `~ auto-committed ${auto.sha.slice(0, 9)} (${auto.files.length} content file(s)) — pass -m "…" to set the message, --no-commit to skip`,
+    );
+  }
+
   // 1. validate locally — refuse on errors.
   if (!args.skipValidate) {
     const { ok, findings } = validateTenant(workspace, { tenantId: tenant, scope: ctx.config?.scope });
@@ -349,10 +683,68 @@ export async function run(argv, ctx) {
   const statLine = base ? gitSafe(["diff", "--shortstat", `${base}..HEAD`]).trim() : "";
   const changeSummary = buildChangeSummary({ message: args.message, summary: args.summary, headSubject, statLine, files });
 
-  console.error(`~ pushing ${short} → ${args.ref} (origin)`);
+  // The MCP session is needed BOTH to mint a fresh forge push credential (decision
+  // B — right below) and for the candidate/preview read-back after, so establish it
+  // ONCE, up front, and reuse it for the whole flow.
+  const baseUrl = args.mcp || env.MCP_BASE_URL || env.TOT_MCP_URL || DEFAULT_MCP_URL;
+  const client = createMcpClient(baseUrl);
+  const repo = repoNameFromRemote(gitSafe(["remote", "get-url", "origin"]).trim());
+
+  let session;
+  try {
+    session = await establishSession(client, { env, prefer: args.identity || undefined });
+  } catch (e) {
+    // Not signed in / MCP unreachable — we can't mint a fresh credential, so fall
+    // back to pushing over the checkout's EXISTING embedded remote (pre-B behavior:
+    // no worse than before) and skip the read-back that needs a session. The push
+    // still lands if that embedded token is live.
+    console.error(`~ pushing ${short} → ${args.ref} (origin)`);
+    try {
+      const out = git(["push", "-f", "origin", `HEAD:refs/heads/${args.ref}`]);
+      if (out.trim()) console.error(redactUrl(out.trim()));
+    } catch (pushErr) {
+      console.error(
+        fail(
+          `push failed: ${redactUrl(String(pushErr.stderr || pushErr.message || pushErr))}`,
+          "check your commit and that the checkout's remote is reachable, then re-run",
+        ),
+      );
+      return 1;
+    }
+    console.log(`\n+ submitted ${short} to ${args.ref}.`);
+    printChangeSummary(changeSummary);
+    if (e instanceof AuthUnavailableError) {
+      console.log(`  (sign in to see the reconcile/compliance/preview result — ${e.hint || "developer sign-in pending"})`);
+    } else {
+      console.log(`  (couldn't reach Token of Trust for the result read-back: ${String(e?.message || e)})`);
+    }
+    console.log(`  Your push is in; the preview updates once reconcile completes.`);
+    return 0;
+  }
+
+  // 2. push the preview ref with a FRESHLY-MINTED, short-lived forge credential
+  //    (decision B). The token baked into `.git/config` at clone time expires within
+  //    hours, so we re-mint right before the push and hand it to git ephemerally
+  //    (never persisted to `.git/config`), re-minting once on an auth failure.
+  //    `checkoutTenant(cloneDir:null)` mints without re-cloning AND client_switch()es,
+  //    binding the tenant scope the candidate/preview read-back below reads.
+  const tag = tagFromRepoName(repo, tenant);
+  const mintRemote = async () => {
+    try {
+      const res = await checkoutTenant(client, { tenant, tag, cloneDir: null, redact: redactUrl });
+      return res.gitRemote || null;
+    } catch (e) {
+      console.error(
+        `~ couldn't mint a fresh push credential (${redactUrl(String(e?.message || e))}) — using the checkout's remote`,
+      );
+      return null;
+    }
+  };
+
+  console.error(`~ pushing ${short} → ${args.ref} (origin, fresh credential)`);
   try {
-    const out = git(["push", "-f", "origin", `HEAD:refs/heads/${args.ref}`]);
-    if (out.trim()) console.error(redactUrl(out.trim()));
+    const { out } = await pushPreviewRef(git, mintRemote, { ref: args.ref });
+    if (out && out.trim()) console.error(redactUrl(out.trim()));
   } catch (e) {
     console.error(
       fail(
@@ -366,28 +758,53 @@ export async function run(argv, ctx) {
   printChangeSummary(changeSummary);
 
   // 2b + 3. open/update the PR-backed candidate, then report reconcile +
-  // compliance + preview URL from the MCP (both graceful seams, same session).
-  const baseUrl = args.mcp || env.MCP_BASE_URL || env.TOT_MCP_URL || DEFAULT_MCP_URL;
-  const client = createMcpClient(baseUrl);
+  // compliance + preview URL from the MCP — reusing the session established above.
   let progress = null;
   try {
-    // Attach auth before the first server call (developer bearer pre-initialize,
-    // operator credential_validate post-initialize) — see establishSession.
-    const session = await establishSession(client, { env, prefer: args.identity || undefined });
-    // Set the active tenant so preview_status/candidate_open read the right scope
-    // (both key on the session's bound tenant/app — no tenant arg of their own).
+    // Bind the active tenant so preview_status/candidate_open read the right scope
+    // (idempotent — checkoutTenant already switched when the fresh mint succeeded).
     await client.callTool("client_switch", { tenant });
 
     // 2b. PR-backed candidate (g1b candidate_open, unit c1) — 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.
-    await submitCandidate(client, {
-      repo: repoNameFromRemote(gitSafe(["remote", "get-url", "origin"]).trim()),
-      changeId: deriveChangeId(tenant, actorKeyFor(session)),
-      changeSummary,
-      patchEntries,
-      readBlob: (path) => execFileSync("git", ["-C", workspace, "show", `HEAD:${path}`], { stdio: ["ignore", "pipe", "pipe"] }),
-    });
+    //
+    // Which candidate this submit lands on (gh-pr-like):
+    //   --new           → fork a FRESH candidate and remember it as active;
+    //   otherwise       → the remembered active candidate (from a prior --new /
+    //                     roll), else the STABLE per-dev-per-tenant default.
+    // If the chosen candidate turns out to be merged/closed, roll to a fresh one
+    // so a re-submit is never wedged on a dead PR. (`repo` was derived above.)
+    const readBlob = (path) => execFileSync("git", ["-C", workspace, "show", `HEAD:${path}`], { stdio: ["ignore", "pipe", "pipe"] });
+    const statePath = defaultCandidateStatePath(env);
+    // Branch-bound (u4): the candidate handle + active-pointer namespace fold in the
+    // current git branch on a non-default branch, so a feature branch gets its OWN
+    // candidate; the default branch keeps today's exact id (zero migration).
+    const branch = currentBranch(gitSafe);
+    const stableId = deriveChangeId(tenant, actorKeyFor(session), branch);
+    const active = repo ? readActiveChangeId(statePath, { mcpUrl: baseUrl, repo, branch }) : null;
+    let changeId = args.new ? mintFreshChangeId(stableId) : (active || stableId);
+    // Persist when we diverge from the stable default (a --new fork, or a
+    // previously-remembered active pointer) so the next plain submit follows it.
+    let persist = args.new || (!!active && active !== stableId);
+
+    let candidate = await submitCandidate(client, { repo, changeId, changeSummary, patchEntries, readBlob });
+
+    if (candidate && isTerminalCandidateState(candidate.state)) {
+      const rolled = mintFreshChangeId(stableId);
+      console.log(`  ~ candidate ${changeId} is ${candidate.state} — opening a fresh candidate PR instead.`);
+      changeId = rolled;
+      persist = true;
+      candidate = await submitCandidate(client, { repo, changeId, changeSummary, patchEntries, readBlob });
+    }
+
+    // Remember the active candidate only on a real, non-terminal open (best-effort;
+    // never let a state-write failure break the submit).
+    if (persist && repo && candidate && !isTerminalCandidateState(candidate.state)) {
+      try {
+        writeActiveChangeId(statePath, { mcpUrl: baseUrl, repo, branch, changeId });
+      } catch { /* best-effort local hint — a miss just re-derives the stable id */ }
+    }
 
     let status;
     if (args.noWait) {

package/src/commands/validate.mjs

@@ -68,11 +68,11 @@ export function run(argv, ctx) {
 
   const target = resolveTarget(args, ctx);
   if (target.error) {
-    console.error(fail(target.error, "tot checkout <tenant> --clone <dir>, or pass --workspace <dir>"));
+    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 checkout <tenant> --clone <dir>`"));
+    console.error(fail(`no tenant directory at ${target.dir}`, "confirm the path, or `tot clone <tenant>`"));
     return 2;
   }
 

package/src/commands/whoami.mjs

@@ -11,7 +11,7 @@
 import { defaultCredentialsPath, readCredentials, isExpired, activeProfile } from "../token-store.mjs";
 import { establishSession } from "../auth.mjs";
 import { createMcpClient } from "../mcp.mjs";
-import { normalizeStores, storeListError } from "./checkout.mjs";
+import { normalizeStores, storeListError, noStoresGuidance } from "./clone.mjs";
 import { recordServerPolicy } from "../update-check.mjs";
 
 /**
@@ -67,7 +67,11 @@ export async function run(argv, _ctx) {
     } else if (listErr) {
       console.log(`  (couldn't list your stores: ${listErr} — try \`tot login\` again)`);
     } else {
-      console.log("  (no stores resolved yet — if you were just invited, it may still be propagating)");
+      // Status-aware (card c2): an UNLINKED identity is told to link (not "may
+      // still be propagating" — that's only the genuine zero-grants case).
+      const g = noStoresGuidance(listResp);
+      console.log(`  (${g.headline})`);
+      console.log(`  → next: ${g.next}`);
     }
   } catch {
     console.log("  (couldn't reach the MCP to list your stores right now — your cached session is above)");

package/src/context.mjs

@@ -6,13 +6,13 @@
  *
  *   monorepo   — inside a full storefront checkout (pnpm-workspace.yaml +
  *                apps/storefront + tenants/). This is us / a platform dev.
- *                `tot dev` here runs the in-tree astro dev; `tot checkout`
+ *                `tot dev` here runs the in-tree astro dev; `tot clone`
  *                can suggest cloning a sibling dir.
  *   checkout   — inside a STANDALONE tenant checkout: the flat, content-only
  *                shape `content/ public/ theme.json .tot/config.json` a
  *                developer clones. The tenant is read from .tot/config.json.
  *                `tot dev` here boots the bundled runner against this dir.
- *   loose      — anywhere else. `tot checkout <tenant>` still works (it's how
+ *   loose      — anywhere else. `tot clone <tenant>` still works (it's how
  *                you GET a checkout); commands that need a workspace say so.
  *
  * Detection walks UP from the cwd so `tot` works from any subdirectory of a