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

package/README.md

@@ -9,7 +9,8 @@ tot clone                    # list the stores you can build on
 tot clone <tenant> my-store  # mirrors `git clone`; dir defaults to <tenant>
 cd my-store
 tot dev                      # run it locally with save→reload — no Docker needed
-tot submit                   # (coming) submit it for preview
+tot preview                  # bundle your edits into a compliance-reviewed preview
+tot ship                     # promote a reconciled preview live (diff + one confirm)
 ```
 
 **Prerequisites: Node.js and an invite. Nothing else.** `tot dev` downloads the
@@ -23,9 +24,11 @@ be fetched.)
 | Command | Status | What it does |
 | --- | --- | --- |
 | `tot clone [<tenant>] [<dir>]` | **built** | Clone a store you're entitled to build on (mirrors `git clone`), with an authenticated remote configured. Dir defaults to `<tenant>`. No arg → list your stores. |
-| `tot validate` | next | Lint your store before you submit. |
+| `tot validate` | next | Lint your store before you preview. |
 | `tot dev` | **built** | Run your store locally with save→reload — NATIVELY (no Docker; falls back to it with `--docker` or automatically if the native artifact isn't available). |
-| `tot submit` | next | Submit your store for preview (pushes the preview ref, reports the reconcile/compliance verdict + preview URL). |
+| `tot preview` | **built** | Bundle your edits into a compliance-reviewed preview (validates, auto-commits the known content trees, pushes the preview ref, opens/updates a candidate PR, reports the reconcile/compliance verdict + preview URL). `tot submit` / `tot deploy` still work as teaching aliases for this same flow. |
+| `tot ship` | **built** | Promote a reconciled preview live: always shows a diff-vs-live and asks for one `[y/N]` confirm (no `--yes`, refuses outside a terminal); records an approval request if you're not authorised to ship yourself. |
+| `tot pr [list\|view\|close]` | **built** | See and manage the candidate PRs `tot preview` opens (`gh pr`-shaped). |
 | `tot doctor` | built | Check this machine is ready and show which context `tot` detected. |
 
 ## Context-aware
@@ -42,7 +45,7 @@ The same `tot` does the right thing wherever you run it (walks up like `git`):
 
 `tot` talks to the Token of Trust MCP (default `https://mcp.tokenoftrust.com`, override with `--mcp` or `MCP_BASE_URL`). It is **single-plane**: the only identity is **you**, signed in against the MCP over OAuth.
 
-- Run `tot login` once — it opens your browser (or falls back to a device code on a headless box), you sign in as yourself, and the session is cached at `~/.tot/credentials.json` and refreshed silently. Every later command (`tot clone`, `tot start`, `tot submit`, …) runs as you, with no re-auth. Entitlement is derived server-side from your ToT memberships.
+- Run `tot login` once — it opens your browser (or falls back to a device code on a headless box), you sign in as yourself, and the session is cached at `~/.tot/credentials.json` and refreshed silently. Every later command (`tot clone`, `tot start`, `tot preview`, `tot ship`, …) runs as you, with no re-auth. Entitlement is derived server-side from your ToT memberships.
 - Not signed in? On a terminal, `tot start` / `tot clone` **offer to sign you in right there** and continue in-flow — no "run `tot login`, then re-run".
 - The old operator env-triple (`TOT_API_KEY` / `TOT_SECRET_KEY` / `TOT_APP_DOMAIN`) **no longer signs the CLI in** — tot-mcp went OAuth-first on 2026-07-23. If those vars are set, `tot` prints a one-line advisory and uses your `tot login` session anyway; it never reads them for auth.
 

package/bin/tot.mjs

@@ -14,7 +14,7 @@
  *   tot validate              lint your store before you submit         ← built
  *   tot dev                   run your store locally with save→reload   ← built (monorepo: host astro; standalone: runs the published runner image)
  *   tot preview               push your store to a reviewable preview   ← built (validate + push preview ref; MCP preview_status read-back). `submit`/`deploy` are teaching aliases.
- *   tot ship                  promote a reconciled preview live         ← stub (registered; real ship logic lands in a later unit)
+ *   tot ship                  promote a reconciled preview live         ← built (diff-vs-live + y/N confirm → change_accept; refuses non-TTY / unreconciled)
  *   tot pr                    list / view / close your candidate PRs    ← built (candidate_status/candidate_close; gh-pr-shaped)
  *   tot doctor                check this machine is ready
  *   tot ideas                 copy-paste AI prompts that reliably wow
@@ -62,7 +62,7 @@ tot — Token of Trust developer CLI
   tot validate              lint your store before you submit
   tot dev                   run your store locally with save→reload
   tot preview               push your store to a reviewable preview
-  tot ship                  promote a reconciled preview live (coming soon)
+  tot ship                  promote a reconciled preview live (diff → confirm → ship)
   tot pr                    list / view / close your candidate PRs
   tot doctor                check this machine is ready
   tot ideas                 copy-paste AI prompts that reliably wow

package/package.json

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

package/src/candidate-state.mjs

@@ -13,8 +13,14 @@
  *   - a terminal-roll (the active candidate was merged/closed) records the fresh
  *     candidate it rolled to, so you're never wedged submitting to a dead PR.
  *
- * ONE file, `~/.tot/candidates.json`, a map keyed by `<mcpUrl>::<repo>` — a
- * different MCP or repo is a different candidate namespace. Same atomic-write
+ * ONE file, `~/.tot/candidates.json`, a map keyed by `<mcpUrl>::<repo>` on the
+ * DEFAULT branch and `<mcpUrl>::<repo>::<branch>` on any other (u4 — branch-bound
+ * candidates): a different MCP, repo, OR non-default git branch is a different
+ * candidate namespace, so a feature branch gets its OWN candidate PR instead of
+ * fighting main's over the same handle. The default branch deliberately keeps the
+ * OLD branch-less key so existing devs' state is byte-identical (zero migration),
+ * and a branch-scoped read that misses FALLS BACK to that old key so state written
+ * before the rekey (or by the default branch) is never orphaned. Same atomic-write
  * discipline as last-tenant.mjs (0600 in a 0700 dir, write-tmp-then-rename).
  * Dependency-free (node:fs/os/path). `TOT_HOME` overrides home (tests).
  */
@@ -31,11 +37,38 @@ export function defaultCandidateStatePath(env = process.env) {
   return join(home, ".tot", "candidates.json");
 }
 
-/** Namespace key for one (MCP, repo) candidate pointer. */
-function stateKey(mcpUrl, repo) {
+/**
+ * Branch names that are treated as the repo's DEFAULT — their candidates keep the
+ * OLD branch-less key (zero migration). A null/empty/detached ("HEAD") branch is
+ * treated as default too, so an environment where the branch can't be resolved
+ * degrades to exactly today's behavior rather than minting a spurious namespace.
+ */
+export const DEFAULT_BRANCHES = new Set(["main", "master"]);
+
+/** Whether `branch` should use the OLD branch-less candidate key. Pure. */
+export function isDefaultBranch(branch) {
+  return !branch || branch === "HEAD" || DEFAULT_BRANCHES.has(branch);
+}
+
+/** The legacy (branch-less) namespace key — today's exact `<mcpUrl>::<repo>`. */
+function legacyStateKey(mcpUrl, repo) {
   return `${mcpUrl}::${repo}`;
 }
 
+/**
+ * Namespace key for one (MCP, repo, branch) candidate pointer. The DEFAULT branch
+ * keeps the legacy `<mcpUrl>::<repo>` key byte-for-byte (zero migration); any other
+ * branch gets its own `<mcpUrl>::<repo>::<branch>` namespace. Pure.
+ */
+function stateKey(mcpUrl, repo, branch) {
+  return isDefaultBranch(branch) ? legacyStateKey(mcpUrl, repo) : `${mcpUrl}::${repo}::${branch}`;
+}
+
+/** Extract a usable changeId from a stored record, or null. Pure. */
+function recordChangeId(rec) {
+  return rec && typeof rec.changeId === "string" && rec.changeId ? rec.changeId : null;
+}
+
 function readMap(filePath) {
   try {
     const parsed = JSON.parse(readFileSync(filePath, "utf8"));
@@ -54,26 +87,33 @@ function writeMap(filePath, map) {
 }
 
 /**
- * The remembered active changeId for `(mcpUrl, repo)`, or null when there isn't
- * one (absent/unreadable/malformed) — a miss means "use the stable default".
- * Never throws.
+ * The remembered active changeId for `(mcpUrl, repo, branch)`, or null when there
+ * isn't one (absent/unreadable/malformed) — a miss means "use the stable default".
+ * On a non-default branch whose branch-scoped key misses, FALLS BACK to the legacy
+ * branch-less key so state written before the rekey (or by the default branch)
+ * isn't orphaned. Never throws.
  */
-export function readActiveChangeId(filePath, { mcpUrl, repo }) {
-  const rec = readMap(filePath)[stateKey(mcpUrl, repo)];
-  return rec && typeof rec.changeId === "string" && rec.changeId ? rec.changeId : null;
+export function readActiveChangeId(filePath, { mcpUrl, repo, branch }) {
+  const map = readMap(filePath);
+  const primary = recordChangeId(map[stateKey(mcpUrl, repo, branch)]);
+  if (primary) return primary;
+  // Legacy fallback: a branch-scoped miss reads the old branch-less key (a no-op
+  // when we're already on the default branch, which IS the legacy key).
+  if (!isDefaultBranch(branch)) return recordChangeId(map[legacyStateKey(mcpUrl, repo)]);
+  return null;
 }
 
-/** Remember `changeId` as the active candidate for `(mcpUrl, repo)`, atomically. */
-export function writeActiveChangeId(filePath, { mcpUrl, repo, changeId }) {
+/** Remember `changeId` as the active candidate for `(mcpUrl, repo, branch)`, atomically. */
+export function writeActiveChangeId(filePath, { mcpUrl, repo, branch, changeId }) {
   const map = readMap(filePath);
-  map[stateKey(mcpUrl, repo)] = { changeId, updatedAt: Date.now() };
+  map[stateKey(mcpUrl, repo, branch)] = { changeId, updatedAt: Date.now() };
   writeMap(filePath, map);
 }
 
-/** Forget the active candidate for `(mcpUrl, repo)` (e.g. after closing it). */
-export function clearActiveChangeId(filePath, { mcpUrl, repo }) {
+/** Forget the active candidate for `(mcpUrl, repo, branch)` (e.g. after closing it). */
+export function clearActiveChangeId(filePath, { mcpUrl, repo, branch }) {
   const map = readMap(filePath);
-  const key = stateKey(mcpUrl, repo);
+  const key = stateKey(mcpUrl, repo, branch);
   if (key in map) {
     delete map[key];
     writeMap(filePath, map);

package/src/commands/pr.mjs

@@ -21,7 +21,7 @@ import { execFileSync } from "node:child_process";
 import { createMcpClient } from "../mcp.mjs";
 import { establishSession, AuthUnavailableError } from "../auth.mjs";
 import { fail } from "../errors.mjs";
-import { repoNameFromRemote } from "./submit.mjs";
+import { repoNameFromRemote, currentBranch } from "./submit.mjs";
 import {
   defaultCandidateStatePath,
   readActiveChangeId,
@@ -79,11 +79,23 @@ export function matchCandidate(candidates, target) {
   return candidates.find((c) => c.changeId === target) ?? null;
 }
 
-/** One-line candidate summary for `tot pr list`. */
-function line(c) {
+/**
+ * One-line candidate summary for `tot pr list` — surfaces branch ↔ PR# ↔ preview
+ * URL so a dev sees, at a glance, which git branch each candidate belongs to (u4 —
+ * branch-bound candidates) and where its preview lives. Prefers the candidate's
+ * `previewUrl`, falling back to the PR `url`. `active` marks the one THIS checkout's
+ * branch resolves to. Pure — unit-tested.
+ * @param {{prNumber?:number|null, branch?:string|null, changeId:string, state?:string|null,
+ *   previewUrl?:string|null, url?:string|null}} c
+ * @param {{ active?: boolean }} [opts]
+ */
+export function formatCandidateLine(c, { active = false } = {}) {
   const pr = typeof c.prNumber === "number" ? `#${c.prNumber}` : "#—";
-  const url = c.url ? `  ${c.url}` : "";
-  return `  PR ${pr}  ${c.changeId}  [${c.state ?? "?"}]${url}`;
+  const branch = c.branch ? c.branch : "(no branch)";
+  const previewUrl = c.previewUrl || c.url || null;
+  const urlPart = previewUrl ? `  ${previewUrl}` : "";
+  const activePart = active ? "  ← active" : "";
+  return `  PR ${pr}  ${branch}  ${c.changeId}  [${c.state ?? "?"}]${urlPart}${activePart}`;
 }
 
 /** @param {string[]} argv @param {any} ctx */
@@ -128,7 +140,9 @@ export async function run(argv, ctx) {
 
   const baseUrl = args.mcp || env.MCP_BASE_URL || env.TOT_MCP_URL || DEFAULT_MCP_URL;
   const statePath = defaultCandidateStatePath(env);
-  const scope = { mcpUrl: baseUrl, repo };
+  // Branch-bound (u4): the active-pointer namespace is scoped to the current git
+  // branch, so the "← active" marker reflects THIS branch's candidate.
+  const scope = { mcpUrl: baseUrl, repo, branch: currentBranch(gitSafe) };
   const client = createMcpClient(baseUrl);
   try {
     const session = await establishSession(client, { env, prefer: args.identity || undefined });
@@ -146,7 +160,7 @@ export async function run(argv, ctx) {
       const active = readActiveChangeId(statePath, scope);
       console.log(`Open candidate PRs for ${repo}:`);
       for (const c of candidates) {
-        console.log(line(c) + (active && c.changeId === active ? "  ← active" : ""));
+        console.log(formatCandidateLine(c, { active: !!active && c.changeId === active }));
       }
       return 0;
     }

package/src/commands/ship.mjs

@@ -1,53 +1,667 @@
 /**
- * `tot ship` — promote a reconciled PREVIEW live (the ship gate).
+ * `tot ship` — promote a reconciled PREVIEW live (the deliberate ship gate).
  *
- * This is the second half of the dev → preview → ship loop:
+ * The second half of the dev → preview → ship loop:
  *
  *   tot dev        run your store locally with save→reload
  *   tot preview    push it to a reviewable preview (validate → reconcile → compliance)
  *   tot ship       promote a reconciled preview live                                     ← you are here
  *
- * STATUS: STUB — the command is registered and named so the loop reads end-to-end,
- * but the real ship logic (resolve the current candidate/change for this checkout,
- * show the diff about to go live, confirm, then `change_accept` / `candidate_accept`
- * via the MCP, and report the shipped result) lands in a later unit.
+ * The contract, deliberately strict because this is the step that changes the LIVE
+ * site:
  *
- * TODO(u3): implement the real ship flow. Symmetric with submit.mjs's preview flow —
- * it should reuse the same candidate handle (deriveChangeId / the active-candidate
- * state in candidate-state.mjs) so `tot ship` promotes the exact preview `tot preview`
- * last pushed, gate on a clean reconcile, and diff-confirm before accepting.
+ *   1. Resolve the ACTIVE candidate for this checkout (the SAME handle `tot preview`
+ *      last pushed to — see `resolveActiveChangeId`, the seam u4 rekeys to be
+ *      branch-bound) and REQUIRE it to be OPEN and RECONCILED. A merged/closed
+ *      candidate, or one whose evidence isn't green yet, is refused with a clear
+ *      next step — never shipped.
+ *   2. ALWAYS render a diff-vs-live (what this ship changes on the live site) and
+ *      require ONE explicit [y/N] confirm, defaulting to NO. There is deliberately
+ *      NO `--yes` / `--force` bypass in v1: shipping live is a decision a human
+ *      makes at the keyboard. In a NON-TTY (CI, piped) we REFUSE rather than
+ *      auto-confirm — nothing ships without someone saying yes.
+ *   3. On confirm, `change_accept` (the human ship gate) transitions the change to
+ *      shipped; we then poll `change_status` until it reports shipped and print the
+ *      live URL.
  *
- * Until then this prints a clear "not yet wired" message pointing at the reviewer
- * path that ships a change today, and exits non-zero so nothing mistakes it for a
- * completed ship. Additive + non-breaking: it performs no action.
+ * UNAUTHORISED actors don't hit a wall: if you can't approve the ship yourself we
+ * RECORD the approval request (`change_ready` queues it for review) and print WHO
+ * can approve it, so the change moves forward instead of dead-ending.
  *
- * Dependency-free.
+ * WIRE (verified server-side by u7, decision ship-path-wire-resolutions):
+ *   - A CANDIDATE and a change RECORD are DISTINCT namespaces. The candidate handle
+ *     (`changeId`, the `candidate/<changeId>` Gitea PR) is NOT the change-record id.
+ *     `change_request_review` / `change_ready` / `change_accept` resolve the record
+ *     via `getChange(tenant, id)`, where `id` is the `chg_<uuid>` minted by
+ *     `change_open` — a different id entirely.
+ *   - So ship RESOLVES a real change-record id before the gate: `resolveChangeRecordId`
+ *     opens a record for the exact reviewed commit (`change_open commit:<HEAD>`, so
+ *     u7's promote-by-digest can content-address the reviewed tree — without `commit:`
+ *     the accept fails closed `no_reviewed_commit`) and readies it against the
+ *     authoritative reconcile evidence keyed by (tenant, commit). If that commit hasn't
+ *     reconciled (no evidence), `change_ready` fails and we refuse with a clear next step.
+ *   - `change_request_review` then reads the readied record (evidence green? authorised
+ *     to promote?); `change_accept` is the commit. All key on the resolved `chg_` id.
+ *
+ * Dependency-free (global fetch via the MCP client + `git`); pure helpers are
+ * exported and unit-tested with a mock client, no network, no TTY.
  */
+import { execFileSync } from "node:child_process";
+import { createMcpClient } from "../mcp.mjs";
+import { establishSession, AuthUnavailableError } from "../auth.mjs";
 import { fail } from "../errors.mjs";
+import { isInteractive, promptYesNo } from "../prompt.mjs";
+import { startProgress } from "../progress.mjs";
+import { openBrowser } from "../open.mjs";
+import {
+  repoNameFromRemote,
+  parseNameStatus,
+  deriveChangeId,
+  actorKeyFor,
+  currentBranch,
+  buildChangeSummary,
+} from "./submit.mjs";
+import {
+  defaultCandidateStatePath,
+  readActiveChangeId,
+  isTerminalCandidateState,
+} from "../candidate-state.mjs";
+
+const DEFAULT_MCP_URL = "https://mcp.tokenoftrust.com";
 
 const USAGE = `tot ship — promote a reconciled preview live
 
-  tot ship        (coming soon) promote the preview you last pushed with \`tot preview\`
+  tot ship                 promote the preview you last pushed with \`tot preview\`
+  tot ship --identity <id> sign in as a specific identity for this ship
+  tot ship --mcp <url>     MCP base URL (default: env MCP_BASE_URL / TOT_MCP_URL)
+
+  Ship makes your preview LIVE once it has reconciled cleanly — the deliberate step
+  AFTER \`tot preview\`. It ALWAYS shows you the diff about to go live and asks for a
+  single y/N confirmation first; there is no --yes/--force, and it refuses to run
+  without an interactive terminal. If you can't approve the ship yourself, it records
+  the request and tells you who can.`;
+
+/** Parse `tot ship` argv. Pure. Deliberately NO --yes/--force (see the header). */
+export function parseShipArgs(argv) {
+  const a = { mcp: null, identity: null, noOpen: false, help: false };
+  for (let i = 0; i < argv.length; i++) {
+    const t = argv[i];
+    if (t === "--mcp") a.mcp = argv[++i];
+    else if (t === "--identity") a.identity = argv[++i];
+    else if (t === "--no-open") a.noOpen = true;
+    else if (t === "--help" || t === "-h") a.help = true;
+  }
+  return a;
+}
 
-  Ship the preview live once it has reconciled cleanly. This is the deliberate
-  step AFTER \`tot preview\` — preview makes it reviewable; ship makes it live.`;
+// ─── Response normalisation (defensive — one MCP, but shapes may vary) ───────────
 
 /**
- * @param {string[]} argv
- * @param {any} _ctx
+ * Normalise a `candidate_status` result (a single ReviewEnvironment forge slice)
+ * to the fields ship gates on. Returns null when there's no candidate to act on.
+ * Pure — unit-tested.
+ * @param {any} r
+ * @returns {{changeId?:string, state:string|null, headSha:string|null, baseSha:string|null,
+ *   prNumber:number|null, url:string|null, mergeable:unknown}|null}
  */
-export async function run(argv, _ctx) {
-  if (argv.includes("--help") || argv.includes("-h")) {
-    console.log(USAGE);
+export function normalizeCandidate(r) {
+  // `tot pr` already learned candidate_status can answer as an object, a
+  // `{candidates:[…]}` list, or a single record — reuse that tolerance here.
+  const c = Array.isArray(r)
+    ? r[0]
+    : r && Array.isArray(r.candidates)
+      ? r.candidates[0]
+      : r && Array.isArray(r.environments)
+        ? r.environments[0]
+        : r;
+  if (!c || typeof c !== "object" || typeof c.changeId !== "string") return null;
+  return {
+    changeId: c.changeId,
+    state: typeof c.state === "string" ? c.state : null,
+    headSha: c.headSha ?? null,
+    baseSha: c.baseSha ?? null,
+    prNumber: typeof c.prNumber === "number" ? c.prNumber : null,
+    url: c.url ?? null,
+    mergeable: c.mergeable,
+  };
+}
+
+/**
+ * Normalise a `change_request_review` result to the precondition signals ship
+ * needs: is the evidence green (reconciled + promotable), is THIS session allowed
+ * to promote, and — for the unauthorised path — who can. Field names are read
+ * defensively (the CLI is the first caller of this tool) so a plausible rename
+ * degrades gracefully rather than crashing the gate. `reconciled`/`authorized` are
+ * TRI-STATE-ish: they're only `true` when the server clearly says so, so an
+ * unrecognised shape fails CLOSED (we don't ship on ambiguity). Pure — unit-tested.
+ * @param {any} r
+ * @returns {{reconciled:boolean, authorized:boolean, approvers:string[],
+ *   previewUrl:string|null, detail:string|null, raw:any}}
+ */
+export function normalizeReview(r) {
+  const o = (r && typeof r === "object" ? r : {});
+  const ev = o.evidence && typeof o.evidence === "object" ? o.evidence : {};
+  // Evidence green ⇒ reconciled + promotable. Accept the several plausible flags.
+  const reconciled = firstBool([
+    o.evidenceGreen, o.green, o.promotable, ev.green, ev.ok, ev.promotable,
+    o.verdict === "green" || o.verdict === "pass" ? true : undefined,
+  ]);
+  const authorized = firstBool([
+    o.authorized, o.authorised, o.canPromote, o.canApprove, o.authorisedToPromote,
+  ]);
+  const approvers = normalizeApprovers(
+    o.approvers ?? o.eligibleApprovers ?? o.whoCanApprove ?? o.promoters ?? [],
+  );
+  return {
+    reconciled: reconciled === true,
+    authorized: authorized === true,
+    approvers,
+    previewUrl: o.previewUrl ?? ev.previewUrl ?? null,
+    detail: typeof o.detail === "string" ? o.detail : (typeof o.reason === "string" ? o.reason : null),
+    raw: r,
+  };
+}
+
+/** First non-undefined boolean in a list, else undefined. Pure. */
+function firstBool(candidates) {
+  for (const v of candidates) if (typeof v === "boolean") return v;
+  return undefined;
+}
+
+/** Coerce an approvers payload (strings, or objects with email/name) to a label list. Pure. */
+export function normalizeApprovers(list) {
+  if (!Array.isArray(list)) return [];
+  return list
+    .map((a) => (typeof a === "string" ? a : a && (a.email || a.name || a.label || a.id)))
+    .filter((s) => typeof s === "string" && s.trim())
+    .map((s) => s.trim());
+}
+
+/**
+ * Normalise a `change_accept` / `change_status` result to { shipped, state,
+ * previewUrl, shippedAt }. `shipped` is true once the record reports the shipped
+ * state (or carries a shipped stamp). Pure — unit-tested.
+ * @param {any} r
+ */
+export function normalizeChangeResult(r) {
+  const o = (r && typeof r === "object" ? r : {});
+  const state = typeof o.state === "string" ? o.state : null;
+  const shippedStamp = o.shipped && typeof o.shipped === "object" ? o.shipped : null;
+  const shipped = state === "shipped" || Boolean(o.shipped === true || shippedStamp);
+  return {
+    shipped,
+    state,
+    previewUrl: o.previewUrl ?? shippedStamp?.previewUrl ?? o.liveUrl ?? null,
+    shippedAt: shippedStamp?.shippedAt ?? o.shippedAt ?? null,
+    raw: r,
+  };
+}
+
+// ─── The candidate-resolution seam (u4 extends THIS) ─────────────────────────────
+
+/**
+ * Resolve the ACTIVE candidate's changeId for this checkout — the SAME resolution
+ * `tot preview` uses so ship promotes exactly what preview last pushed: the
+ * remembered active pointer (a prior `--new` / roll), else the STABLE
+ * per-developer-per-tenant default (`deriveChangeId`).
+ *
+ * ┌─ SEAM (u4) ────────────────────────────────────────────────────────────────┐
+ * │ This is the ONE place ship keys the candidate on (tenant, actor, branch).    │
+ * │ u4 (branch-bound candidates) keys HERE — folding in the current git branch — │
+ * │ so `tot preview` and `tot ship` resolve the SAME branch-bound candidate,     │
+ * │ WITHOUT touching the gate, diff, confirm, or accept flow below. On the       │
+ * │ default branch `branch` is null and this is byte-identical to pre-u4.         │
+ * └──────────────────────────────────────────────────────────────────────────────┘
+ * Pure given its inputs (state is read through candidate-state.mjs). Exported so a
+ * follow-on unit can wrap/replace it.
+ * @param {{ statePath:string, mcpUrl:string, repo:string, tenant:string, actorKey:string,
+ *   branch?:string|null }} keys
+ * @returns {string}
+ */
+export function resolveActiveChangeId({ statePath, mcpUrl, repo, tenant, actorKey, branch = null }) {
+  const stable = deriveChangeId(tenant, actorKey, branch);
+  const active = readActiveChangeId(statePath, { mcpUrl, repo, branch });
+  return active || stable;
+}
+
+/**
+ * Normalise a `change_open` result to its minted change-record id. `change_open`
+ * returns the record id flat in `data` (id, state); read it defensively. Pure.
+ * @param {any} r
+ * @returns {{ id: string|null, state: string|null }}
+ */
+export function normalizeOpenedChange(r) {
+  const o = r && typeof r === "object" ? r : {};
+  return {
+    id: typeof o.id === "string" && o.id ? o.id : null,
+    state: typeof o.state === "string" ? o.state : null,
+  };
+}
+
+/**
+ * Resolve the change-RECORD id (`chg_<uuid>`) that the ship gate + `change_accept`
+ * key on — a DISTINCT namespace from the candidate handle (see the module header).
+ * There is NO candidate→record lookup on the wire (`change_status` lists only
+ * id/title/state, never the head sha), so we CAPTURE the id at `change_open`, the
+ * option u7's decision (ship-path-wire-resolutions) records as supported:
+ *
+ *   1. read the reviewed commit — the local HEAD, the commit `tot preview` pushed and
+ *      the reconcile evidence is keyed on;
+ *   2. `change_open` it with `commit:` set, so u7's promote-by-digest can content-
+ *      address the exact reviewed tree (absent it, `change_accept` fails closed
+ *      `no_reviewed_commit`);
+ *   3. `change_ready` it, attaching the AUTHORITATIVE reconcile evidence keyed by
+ *      (tenant, commit). This REQUIRES that commit to have reconciled — if it hasn't,
+ *      `change_ready` throws (no authoritative evidence) and we propagate it so the
+ *      caller refuses with a "run `tot preview` first" next step (never ship a commit
+ *      whose evidence isn't in).
+ *
+ * Returns the resolved `chg_` id. Throws if the record can't be opened/readied — the
+ * caller fails CLOSED (never falls back to shipping the candidate handle or no record).
+ * The `change_*` calls go through the same client; `git` is injected.
+ * @param {{callTool:Function}} client
+ * @param {{ tenant:string, git:(args:string[])=>string,
+ *   changeSummary?:{ title?:string, body?:string[] } }} params
+ * @returns {Promise<string>}
+ */
+export async function resolveChangeRecordId(client, { tenant, git, changeSummary }) {
+  const commit = git(["rev-parse", "HEAD"]).trim();
+  if (!commit) {
+    throw new Error("couldn't read the reviewed commit (git HEAD) for this checkout");
+  }
+  const title = (changeSummary?.title || `Ship ${tenant} store change`).slice(0, 200);
+  const body = changeSummary?.body?.length ? changeSummary.body.join("\n").slice(0, 2000) : undefined;
+  const opened = normalizeOpenedChange(
+    await client.callTool("change_open", {
+      title,
+      ...(body ? { summary: body } : {}),
+      commit,
+      tenant,
+      dryRun: false,
+    }),
+  );
+  if (!opened.id) {
+    throw new Error("change_open did not return a change-record id");
+  }
+  // Ready it against the authoritative reconcile evidence for THIS exact commit —
+  // throws (no_authoritative_evidence) if the commit hasn't reconciled yet.
+  await client.callTool("change_ready", { id: opened.id, tenant, dryRun: false });
+  return opened.id;
+}
+
+/** A neutral review used only when there's no open candidate to resolve a record for
+ *  — shipReadiness reports the candidate blocker first and never reads these. */
+export const NO_REVIEW = Object.freeze({
+  reconciled: false, authorized: false, approvers: [], previewUrl: null, detail: null, raw: null,
+});
+
+// ─── The ship gate (pure) ────────────────────────────────────────────────────────
+
+/**
+ * Decide, from the resolved candidate + the review verdict, whether the ship may
+ * proceed — the correctness-critical core, kept PURE so every branch is unit-tested
+ * without a client/TTY/git. Order matters: OPEN, then RECONCILED, then AUTHORISED,
+ * so the developer always sees the most fundamental blocker first.
+ *
+ * @param {ReturnType<typeof normalizeCandidate>} candidate
+ * @param {ReturnType<typeof normalizeReview>} review
+ * @returns {{ kind: "no-candidate"|"not-open"|"not-reconciled"|"unauthorized"|"ready",
+ *   what?: string, next?: string }}
+ */
+export function shipReadiness(candidate, review) {
+  if (!candidate) {
+    return {
+      kind: "no-candidate",
+      what: "no active candidate to ship for this checkout",
+      next: "push one first with `tot preview`, then `tot ship`",
+    };
+  }
+  if (candidate.state !== "open") {
+    // Terminal (merged/closed) vs simply-not-open both mean "nothing OPEN to ship".
+    const terminal = isTerminalCandidateState(candidate.state);
+    return {
+      kind: "not-open",
+      what: terminal
+        ? `this candidate is already ${candidate.state} — there's nothing open to ship`
+        : `this candidate isn't open (state: ${candidate.state ?? "unknown"})`,
+      next: "`tot preview` to push a fresh candidate, then `tot ship`",
+    };
+  }
+  if (!review.reconciled) {
+    return {
+      kind: "not-reconciled",
+      what: `this preview hasn't reconciled cleanly yet${review.detail ? ` — ${review.detail}` : ""}`,
+      next: "run `tot preview` and wait for the green reconcile/compliance result, then `tot ship`",
+    };
+  }
+  if (!review.authorized) {
+    return { kind: "unauthorized" };
+  }
+  return { kind: "ready" };
+}
+
+// ─── Diff-vs-live (pure render + thin git compute) ───────────────────────────────
+
+/**
+ * Render the "what goes live" block from parsed name-status entries + a shortstat
+ * line. Always prints SOMETHING actionable: the changed paths when we have them,
+ * else a pointer to the candidate PR so the reviewer can read the full diff. Pure —
+ * unit-tested.
+ * @param {{ entries:{status:string,path:string,from?:string}[], statLine?:string,
+ *   prUrl?:string|null, ok:boolean }} input
+ * @returns {string[]}
+ */
+export function renderDiffVsLive({ entries, statLine, prUrl, ok }) {
+  const lines = ["", "  This ship will change the LIVE site:"];
+  if (ok && entries.length) {
+    for (const e of entries.slice(0, 40)) {
+      const label = e.status === "R" && e.from ? `${e.from} → ${e.path}` : e.path;
+      lines.push(`    ${statusGlyph(e.status)} ${label}`);
+    }
+    if (entries.length > 40) lines.push(`    … +${entries.length - 40} more file(s)`);
+    if (statLine) lines.push(`    (${statLine})`);
+  } else {
+    lines.push("    (couldn't render a local file diff for this candidate)");
+    if (prUrl) lines.push(`    review the full diff in the candidate PR: ${prUrl}`);
+  }
+  return lines;
+}
+
+/** A/M/D/R → a stable one-char glyph for the diff list. Pure. */
+function statusGlyph(status) {
+  return { A: "+", M: "~", D: "-", R: "»", C: "»" }[status] || "·";
+}
+
+/**
+ * Compute the diff-vs-live (base→head) via git in the checkout — best-effort. Tries
+ * the local objects first; if the shas aren't present it fetches once and retries;
+ * if it still can't, returns `ok:false` so the caller falls back to the PR pointer.
+ * `git` is injected (a `(args:string[])=>string` runner) so it's testable.
+ * @param {(args:string[]) => string} git
+ * @param {string|null} baseSha
+ * @param {string|null} headSha
+ * @returns {{ entries:{status:string,path:string,from?:string}[], statLine:string, ok:boolean }}
+ */
+export function computeDiffVsLive(git, baseSha, headSha) {
+  if (!baseSha || !headSha) return { entries: [], statLine: "", ok: false };
+  const range = `${baseSha}..${headSha}`;
+  const tryDiff = () => ({
+    entries: parseNameStatus(git(["diff", "--name-status", range])),
+    statLine: git(["diff", "--shortstat", range]).trim(),
+  });
+  try {
+    return { ...tryDiff(), ok: true };
+  } catch {
+    // The shas may not be local yet (base moved, head only on the remote) — one
+    // fetch, then retry. Still failing ⇒ fall back to the PR pointer.
+    try {
+      git(["fetch", "--quiet", "origin"]);
+      return { ...tryDiff(), ok: true };
+    } catch {
+      return { entries: [], statLine: "", ok: false };
+    }
+  }
+}
+
+// ─── Ship-decision poll ──────────────────────────────────────────────────────────
+
+/**
+ * Poll `change_status` until the change reports shipped (or the attempts budget
+ * runs out). `change_accept` transitions synchronously, so this usually resolves on
+ * the first read — it exists to CONFIRM the shipped state and pick up the live URL,
+ * and to tolerate a promote that lands a beat later. Injectable delay/attempts.
+ * @param {{callTool:Function}} client
+ * @param {{ id:string, tenant?:string }} target
+ * @param {{ attempts?:number, delayMs?:number, sleep?:(ms:number)=>Promise<void> }} [opts]
+ */
+export async function pollChangeShipped(client, { id, tenant }, { attempts = 6, delayMs = 1500, sleep } = {}) {
+  const wait = sleep || ((ms) => new Promise((r) => setTimeout(r, ms)));
+  let last = null;
+  for (let i = 0; i < attempts; i++) {
+    last = normalizeChangeResult(await client.callTool("change_status", { id, ...(tenant ? { tenant } : {}) }));
+    if (last.shipped) return last;
+    if (i < attempts - 1) await wait(delayMs);
+  }
+  return last;
+}
+
+// ─── Orchestration ───────────────────────────────────────────────────────────────
+
+/**
+ * The ship flow after a session is established — resolve the candidate, gate,
+ * diff-vs-live, confirm, accept, poll, report. Split out from `run` so it's driven
+ * in tests with a mock client + injected git/confirm/interactive, no network/TTY.
+ *
+ * @param {{callTool:Function}} client  an MCP client (real or mock)
+ * @param {{ tenant:string, changeId:string, repo:string,
+ *   git:(args:string[])=>string, noOpen?:boolean,
+ *   changeSummary?:{ title?:string, body?:string[] } }} params
+ * @param {{ interactive?:()=>boolean, confirm?:(q:string,d:boolean)=>Promise<boolean>,
+ *   poll?:typeof pollChangeShipped, openUrl?:(u:string)=>boolean, progress?:boolean,
+ *   resolveRecord?:typeof resolveChangeRecordId }} [deps]
+ * @returns {Promise<number>} process exit code
+ */
+export async function runShip(client, { tenant, changeId, repo, git, noOpen, changeSummary }, deps = {}) {
+  const interactive = deps.interactive || isInteractive;
+  const confirm = deps.confirm || promptYesNo;
+  const poll = deps.poll || pollChangeShipped;
+  const resolveRecord = deps.resolveRecord || resolveChangeRecordId;
+
+  // 1. Resolve the active candidate (the forge slice — open-gate + diff-vs-live).
+  const candidate = normalizeCandidate(await client.callTool("candidate_status", { repo, changeId }));
+
+  // 1b. Resolve the change-RECORD id (`chg_<uuid>`) that the gate + change_accept key
+  //     on — a DISTINCT namespace from the candidate handle (see the header). Only
+  //     meaningful for an OPEN candidate; for a missing/closed one we skip it and let
+  //     shipReadiness report that blocker first (never open a record we can't ship).
+  let id = null;
+  if (candidate && candidate.state === "open") {
+    try {
+      id = await resolveRecord(client, { tenant, git, changeSummary });
+    } catch (e) {
+      console.error(
+        fail(
+          `couldn't prepare a shipable change record: ${String(e?.message || e)}`,
+          "the commit you're shipping may not have reconciled — run `tot preview` and wait for the green result, then `tot ship`",
+        ),
+      );
+      return 1;
+    }
+  }
+
+  // 2. Read the ship-readiness verdict against the RESOLVED record (or the neutral
+  //    review when there's no open candidate — shipReadiness reports the candidate).
+  const review = id
+    ? normalizeReview(await client.callTool("change_request_review", { id, tenant }))
+    : NO_REVIEW;
+  const gate = shipReadiness(candidate, review);
+
+  if (gate.kind === "unauthorized") {
+    return await handleUnauthorized(client, { id, tenant, approvers: review.approvers });
+  }
+  if (gate.kind !== "ready") {
+    console.error(fail(gate.what, gate.next));
+    return 1;
+  }
+
+  // 2. ALWAYS render the diff-vs-live, then require ONE explicit y/N confirm.
+  const diff = computeDiffVsLive(git, candidate.baseSha, candidate.headSha);
+  for (const line of renderDiffVsLive({ ...diff, prUrl: candidate.url })) console.log(line);
+
+  // NON-TTY: refuse rather than auto-confirm — nothing ships without a human yes.
+  if (!interactive()) {
+    console.error(
+      fail(
+        "`tot ship` needs an interactive terminal to confirm the live change",
+        "run it from a terminal (there is intentionally no --yes/--force)",
+      ),
+    );
+    return 2;
+  }
+  const proceed = await confirm(`\n  Ship this live to ${tenant}?`, false);
+  if (!proceed) {
+    console.log("  Ship cancelled — nothing changed.");
     return 0;
   }
 
+  // 3. Accept (the ship gate), then poll change_status until shipped.
+  let accept;
+  try {
+    accept = normalizeChangeResult(
+      await client.callTool("change_accept", {
+        id,
+        tenant,
+        dryRun: false,
+        // Stable per (candidate, head): a re-run after a blip returns the original
+        // ship instead of double-accepting.
+        idempotencyKey: `ship-${id}-${candidate.headSha ?? "head"}`,
+      }),
+    );
+  } catch (e) {
+    console.error(
+      fail(
+        `the ship gate refused to accept this change: ${String(e?.message || e)}`,
+        "check the reconcile/compliance result with `tot preview`, then re-run `tot ship`",
+      ),
+    );
+    return 1;
+  }
+
+  const progress = deps.progress === false ? null : startProgress("shipping…");
+  let status;
+  try {
+    status = await poll(client, { id, tenant });
+  } finally {
+    progress?.stop();
+  }
+  return reportShipped(accept, status, { tenant, noOpen, openUrl: deps.openUrl });
+}
+
+/**
+ * The unauthorised path — don't just error out. The change record was already opened
+ * and moved to ready_for_review while resolving the ship (`resolveChangeRecordId`), so
+ * the review request IS recorded; we just tell the developer that and print WHO can
+ * approve. (There is no separate `change_ready` to run — re-readying a ready record is
+ * an illegal transition; the record already sits in the reviewers' queue.)
+ * @returns {Promise<number>} exit code (non-zero — the ship didn't happen)
+ */
+async function handleUnauthorized(client, { id, tenant, approvers }) {
+  void client;
+  void id;
   console.error(
     fail(
-      "`tot ship` isn't wired up yet",
-      "push your work for review with `tot preview`; a reviewer accepts it to ship it live " +
-        "(change_accept / `tot pr`). Self-serve `tot ship` is coming soon.",
+      "you're not authorised to ship this change live yourself",
+      "the change is recorded and ready for review — an authorised approver can ship it",
     ),
   );
-  return 2;
+  if (approvers.length) {
+    console.error(`  Who can approve: ${approvers.join(", ")}`);
+  } else {
+    console.error(`  Who can approve: a teammate with ship/promote authority for ${tenant}.`);
+  }
+  return 1;
 }
+
+/** Report the shipped result and open the live URL (unless suppressed). */
+function reportShipped(accept, status, { tenant, noOpen, openUrl }) {
+  const url = status?.previewUrl || accept?.previewUrl || null;
+  if (status?.shipped || accept?.shipped) {
+    console.log(`\n  ✓ shipped ${tenant} live.`);
+    if (url) {
+      console.log(`  Live: ${url}`);
+      if (!noOpen && openUrl && openUrl(url)) console.log("  (opened in your browser)");
+    }
+    return 0;
+  }
+  // Accept committed but the shipped state hasn't been observed yet (a promote may
+  // still be landing) — report honestly rather than claim a live URL.
+  console.log(`\n  ~ ship accepted for ${tenant}; it's going live now.`);
+  if (url) console.log(`  Track it here: ${url}`);
+  return 0;
+}
+
+/**
+ * @param {string[]} argv
+ * @param {any} ctx
+ */
+export async function run(argv, ctx) {
+  const env = process.env;
+  const args = parseShipArgs(argv);
+  if (args.help) {
+    console.log(USAGE);
+    return 0;
+  }
+  if (ctx.mode !== "checkout") {
+    console.error(
+      fail(
+        "`tot ship` runs from inside a tenant checkout",
+        "tot clone <tenant> <dir>   (then `cd` in, `tot preview`, and `tot ship`)",
+      ),
+    );
+    return 2;
+  }
+
+  const workspace = ctx.workspacePath;
+  const tenant = ctx.tenant;
+  const git = (cargs) =>
+    execFileSync("git", ["-C", workspace, ...cargs], { stdio: ["ignore", "pipe", "pipe"] }).toString();
+  const gitSafe = (cargs) => {
+    try {
+      return git(cargs);
+    } catch {
+      return "";
+    }
+  };
+
+  const repo = repoNameFromRemote(gitSafe(["remote", "get-url", "origin"]).trim());
+  if (!repo) {
+    console.error(
+      fail("couldn't derive the forge repo from this checkout's remote", "run this from a `tot clone`d store"),
+    );
+    return 1;
+  }
+
+  const baseUrl = args.mcp || env.MCP_BASE_URL || env.TOT_MCP_URL || DEFAULT_MCP_URL;
+  const statePath = defaultCandidateStatePath(env);
+  const client = createMcpClient(baseUrl);
+  try {
+    const session = await establishSession(client, { env, prefer: args.identity || undefined });
+    // Bind the active tenant so the candidate/change tools read the right scope.
+    await client.callTool("client_switch", { tenant });
+
+    // Resolve which candidate this checkout ships (the u4 seam) — branch-bound so
+    // ship promotes exactly the candidate `tot preview` pushed from THIS branch.
+    const changeId = resolveActiveChangeId({
+      statePath,
+      mcpUrl: baseUrl,
+      repo,
+      tenant,
+      actorKey: actorKeyFor(session),
+      branch: currentBranch(gitSafe),
+    });
+
+    // The title/body the change RECORD is opened with — from the HEAD commit subject
+    // (the reviewed commit's own message), so the approver's record isn't blank.
+    const headSubject = gitSafe(["log", "-1", "--format=%s"]).trim();
+    const changeSummary = buildChangeSummary({ message: headSubject, headSubject });
+
+    return await runShip(
+      client,
+      { tenant, changeId, repo, git, noOpen: args.noOpen, changeSummary },
+      { openUrl: (u) => openBrowser(u) },
+    );
+  } catch (e) {
+    if (e instanceof AuthUnavailableError) {
+      console.error(fail("sign in to ship", e.hint || "run `tot login`, then re-run `tot ship`"));
+      return 1;
+    }
+    console.error(
+      fail(
+        `couldn't reach the ship service: ${String(e?.message || e)}`,
+        "check your connection and that you're signed in, then re-run",
+      ),
+    );
+    return 1;
+  }
+}
+

package/src/commands/submit.mjs

@@ -42,6 +42,7 @@ 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";
@@ -52,6 +53,7 @@ import {
   writeActiveChangeId,
   mintFreshChangeId,
   isTerminalCandidateState,
+  isDefaultBranch,
 } from "../candidate-state.mjs";
 
 const DEFAULT_MCP_URL = "https://mcp.tokenoftrust.com";
@@ -345,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. */
@@ -538,10 +683,68 @@ export async function run(argv, ctx, { verb = "preview" } = {}) {
   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 {
-    const out = git(["push", "-f", "origin", `HEAD:refs/heads/${args.ref}`]);
-    if (out.trim()) console.error(redactUrl(out.trim()));
+    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 } = await pushPreviewRef(git, mintRemote, { ref: args.ref });
+    if (out && out.trim()) console.error(redactUrl(out.trim()));
   } catch (e) {
     console.error(
       fail(
@@ -555,16 +758,11 @@ export async function run(argv, ctx, { verb = "preview" } = {}) {
   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
@@ -576,12 +774,15 @@ export async function run(argv, ctx, { verb = "preview" } = {}) {
     //   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.
-    const repo = repoNameFromRemote(gitSafe(["remote", "get-url", "origin"]).trim());
+    // 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);
-    const stableId = deriveChangeId(tenant, actorKeyFor(session));
-    const active = repo ? readActiveChangeId(statePath, { mcpUrl: baseUrl, repo }) : null;
+    // 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.
@@ -601,7 +802,7 @@ export async function run(argv, ctx, { verb = "preview" } = {}) {
     // never let a state-write failure break the submit).
     if (persist && repo && candidate && !isTerminalCandidateState(candidate.state)) {
       try {
-        writeActiveChangeId(statePath, { mcpUrl: baseUrl, repo, changeId });
+        writeActiveChangeId(statePath, { mcpUrl: baseUrl, repo, branch, changeId });
       } catch { /* best-effort local hint — a miss just re-derives the stable id */ }
     }