@tokenoftrust/cli 1.4.0-rc.12 → 1.4.0-rc.13

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@tokenoftrust/cli",
-  "version": "1.4.0-rc.12",
+  "version": "1.4.0-rc.13",
   "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/commands/ship.mjs

@@ -86,8 +86,10 @@ const USAGE = `tot ship — deploy main → preview + live (context-dependent)
   tot ship                          ship the preview you last pushed with \`tot preview\`
   tot ship <N>                      DEVELOPER: ship PR #N from your OWN checkout
   tot ship pr/<N>                   (same — also accepts \`pr#N\`, \`#N\`)
-  tot ship --pr <N> --tenant <t>    OPERATOR: deploy a PR that isn't your checkout
+  tot ship --pr <N> --tenant <t>    OPERATOR: ship ANY built PR (not just your checkout)
   tot ship --change-id <chg_…>      target an explicit change record (operator targeting)
+  tot ship --secret <s>             operator secret (prefer the env vars below)
+  tot ship --url <origin>           storefront origin (default: env TOT_STOREFRONT_URL)
   tot ship --yes                    confirm non-interactively (skip the [y/N] prompt)
   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)
@@ -98,8 +100,14 @@ const USAGE = `tot ship — deploy main → preview + live (context-dependent)
       this branch/PR into main) AND THEN DEPLOY (main → preview + live). A POSITIONAL
       \`tot ship 4\` / \`tot ship pr/4\` names the PR to ship — same developer semantics,
       the tenant is inferred from the checkout.
-    • OPERATOR — target a \`--pr N --tenant t\` that ISN'T your checkout: ship = DEPLOY
-      only (the merge is the separate \`tot accept\` verb).
+    • OPERATOR — target a PR that ISN'T your checkout (\`tot ship 4\` with no local
+      candidate, or an explicit \`--pr N --tenant t\`): ship resolves PR N → the built
+      candidate from the SHARED queue (GET /api/changes) and ships it via the atomic
+      accept (POST /api/changes/accept). This needs an OPERATOR SECRET (env below).
+      If PR N has no built candidate, build it first with \`tot preview build\`.
+
+  Operator secret (from env, first found): PREVIEW_RECONCILE_SECRET,
+  GRANTS_ADMIN_SECRET, TOT_OPERATOR_SECRET (or pass --secret).
 
   It NEVER silently guesses: it prints the EXACT plan for THAT context and confirms
   first (\`--yes\` to confirm non-interactively; a non-TTY without \`--yes\` refuses).
@@ -136,6 +144,7 @@ export function parseShipArgs(argv) {
     changeId: null,
     headSha: null,
     url: null,
+    secret: null,
     help: false,
   };
   for (let i = 0; i < argv.length; i++) {
@@ -149,6 +158,7 @@ export function parseShipArgs(argv) {
     else if (t === "--change-id") a.changeId = argv[++i];
     else if (t === "--head-sha" || t === "--head") a.headSha = argv[++i];
     else if (t === "--url") a.url = argv[++i];
+    else if (t === "--secret") a.secret = argv[++i];
     else if (t === "--help" || t === "-h") a.help = true;
     else if (!t.startsWith("-") && a.pr == null) {
       // A POSITIONAL PR reference (`tot ship 4` / `tot ship pr/4` / `tot ship #4`).
@@ -545,7 +555,11 @@ export async function pollChangeShipped(client, { id, tenant }, { attempts = 6,
  *   changeSummary?:{ title?:string, body?:string[] }, expectedPr?:number|string|null }} params
  * @param {{ confirmPlan?:typeof printPlanAndConfirm,
  *   poll?:typeof pollChangeShipped, openUrl?:(u:string)=>boolean, progress?:boolean,
- *   resolveRecord?:typeof resolveChangeRecordId }} [deps]
+ *   resolveRecord?:typeof resolveChangeRecordId,
+ *   shipByPrFallback?:()=>Promise<number> }} [deps]
+ *   shipByPrFallback (u16) — when a POSITIONAL `tot ship <N>` finds NO candidate for
+ *   this checkout, invoke this instead of the "no active candidate" dead-end: it ships
+ *   the built PR from the shared queue (the operator-by-PR path).
  * @returns {Promise<number>} process exit code
  */
 export async function runShip(client, { tenant, changeId, repo, git, noOpen, yes = false, storefrontUrl = null, changeSummary, expectedPr = null }, deps = {}) {
@@ -597,6 +611,16 @@ export async function runShip(client, { tenant, changeId, repo, git, noOpen, yes
     : NO_REVIEW;
   const gate = shipReadiness(candidate, review);
 
+  // u16: `tot ship <N>` in a checkout that has NO candidate matching this PR (the PR
+  // isn't yours) — fall through to the OPERATOR-by-PR queue path (resolve PR→changeId
+  // from GET /api/changes, ship via POST /api/changes/accept) instead of dead-ending on
+  // "no active candidate". Only fires for a POSITIONAL PR (expectedPr) with the fallback
+  // wired (run() supplies it). The U15 different-PR guard (step 1a) still REFUSES — this
+  // is the distinct "nothing to ship from THIS checkout" case, not a mismatch.
+  if (gate.kind === "no-candidate" && expectedPr != null && deps.shipByPrFallback) {
+    return await deps.shipByPrFallback();
+  }
+
   if (gate.kind === "unauthorized") {
     return await handleUnauthorized(client, { id, tenant, approvers: review.approvers });
   }
@@ -732,6 +756,302 @@ export function liveUrlFor(tenant) {
   return t ? `https://${t}` : null;
 }
 
+// ─── Operator ship-by-PR via the SHARED candidate queue (unit U16) ──────────────────
+//
+// The real user report: `tot ship 4` for a PR the operator did NOT author fails
+// `✗ no active candidate to ship for this checkout` — U15's developer path resolves
+// the candidate from the LOCAL git checkout, so it can't ship a PR that isn't yours,
+// and U15's operator path needed an explicit `--change-id` (it couldn't resolve
+// PR→changeId — the `// u9:` gap).
+//
+// The insight this unit builds on (NO forge PR-read needed): a BUILT PR already has a
+// `ReviewEnvironment` in the candidate index, and `GET /api/changes` (the operator
+// accept queue) returns the tenant's OPEN candidates — each with `changeId` +
+// `prNumber` + `headSha`. So PR N → changeId is resolvable from the QUEUE. The ship is
+// then the SAME atomic merge→main→reconcile→promote-live the `/admin` Accept button
+// drives — `POST /api/changes/accept` with `{ repo:<appDomain>, changeId,
+// expectedHeadSha }` — NOT the MCP `change_accept` (that's chg_-record-id-keyed +
+// checkout-bound). The go-live HUMAN GATE stays the confirm.
+//
+// AUTH (investigated): `resolveOwnerSession` (apps/storefront/src/lib/grants/session.ts)
+// accepts a SIGNED-IN storefront `tot_session` cookie (path 1) OR the Bearer operator
+// secret + `X-Tot-Owner` (path 2). The CLI holds NO storefront cookie — its OAuth login
+// is with the MCP, a different trust boundary — so the signed-in/OAuth path can't apply
+// here. The Bearer operator-secret path is the CLI's ONLY route, exactly mirroring
+// `tot preview build`'s transport (Bearer + `X-Tot-Owner` + `x-tot-capability`).
+
+const OPERATOR_SECRET_ENV = ["PREVIEW_RECONCILE_SECRET", "GRANTS_ADMIN_SECRET", "TOT_OPERATOR_SECRET"];
+
+/**
+ * Resolve the operator secret from an explicit `--secret` or the env (first found),
+ * matching `tot preview build`'s precedence. Pure given its env argument.
+ * @param {string|null|undefined} explicit
+ * @param {NodeJS.ProcessEnv} env
+ * @returns {string}
+ */
+export function resolveOperatorSecret(explicit, env = {}) {
+  if (explicit && `${explicit}`.trim()) return `${explicit}`.trim();
+  for (const k of OPERATOR_SECRET_ENV) {
+    const v = env[k];
+    if (v && `${v}`.trim()) return `${v}`.trim();
+  }
+  return "";
+}
+
+/**
+ * Normalise a `GET /api/changes` body to the OPEN candidate list. The endpoint
+ * answers `{ owner, capability, current, changes }` where `changes` is the open
+ * `ReviewEnvironment` queue; read defensively (tolerate a bare array or a `{ changes }`
+ * wrapper) and keep only records carrying a `changeId`. Pure — unit-tested.
+ * @param {any} data
+ * @returns {Array<{changeId:string, prNumber?:number|null, headSha?:string|null, previewUrl?:string|null}>}
+ */
+export function normalizeChangesQueue(data) {
+  const list = Array.isArray(data)
+    ? data
+    : data && Array.isArray(data.changes)
+      ? data.changes
+      : [];
+  return list.filter((c) => c && typeof c === "object" && typeof c.changeId === "string");
+}
+
+/**
+ * Find the OPEN candidate whose forge PR number === `pr` and return the descriptor
+ * the by-PR ship needs (`{ changeId, headSha, prNumber, previewUrl }`), else null when
+ * no built candidate matches. Pure — unit-tested.
+ * @param {ReturnType<typeof normalizeChangesQueue>} changes
+ * @param {number|string} pr
+ * @returns {{changeId:string, headSha:string|null, prNumber:number, previewUrl:string|null}|null}
+ */
+export function findCandidateByPr(changes, pr) {
+  const want = Number(pr);
+  if (!Number.isFinite(want)) return null;
+  for (const c of changes || []) {
+    if (c.prNumber != null && Number(c.prNumber) === want) {
+      return {
+        changeId: c.changeId,
+        headSha: c.headSha ?? null,
+        prNumber: want,
+        previewUrl: c.previewUrl ?? null,
+      };
+    }
+  }
+  return null;
+}
+
+/**
+ * Normalise a `POST /api/changes/accept` body to { shipped, pending, state, sha,
+ * message, error }. The atomic-accept endpoint reports an HONEST terminal `state`:
+ * `shipped` (and `live:true`) ONLY when the target is verified live; `publish_pending`
+ * = merged + dispatched but NOT yet verified (never a live claim). Pure — unit-tested.
+ * @param {any} data
+ */
+export function normalizeAcceptResponse(data) {
+  const o = data && typeof data === "object" ? data : {};
+  const state = typeof o.state === "string" ? o.state : null;
+  const shipped = state === "shipped" || o.live === true;
+  return {
+    shipped,
+    pending: !shipped && (state === "publish_pending" || o.merged === true),
+    state,
+    sha: typeof o.sha === "string" ? o.sha : null,
+    message: typeof o.message === "string" ? o.message : null,
+    error: typeof o.error === "string" ? o.error : null,
+    raw: data,
+  };
+}
+
+/**
+ * The OPERATOR ship-by-PR flow (unit U16). Ships ANY built PR — not just your
+ * checkout — with NO forge PR-read:
+ *
+ *   1. RESOLVE PR N → { changeId, headSha } by reading the tenant's OPEN candidate
+ *      queue (`GET /api/changes`) and matching `prNumber === N`. If N isn't in the
+ *      queue the PR has no built candidate → instruct `tot preview build` first (we
+ *      NEVER invent a changeId).
+ *   2. PLAN + CONFIRM — the go-live HUMAN GATE. `POST /api/changes/accept` is the
+ *      atomic merge→main + reconcile + promote-live, so the plan states BOTH (the
+ *      developer-context wording, mirroring the `/admin` Accept plan). `--yes` confirms
+ *      non-interactively; a non-TTY without `--yes` REFUSES — nothing merges/goes live
+ *      without an explicit yes.
+ *   3. SHIP via `POST /api/changes/accept` `{ repo:<tenant appDomain>, changeId,
+ *      expectedHeadSha }` — the SAME endpoint the `/admin` Accept button uses.
+ *
+ * Transport mirrors `tot preview build` exactly (Bearer operator secret + `X-Tot-Owner`
+ * + `x-tot-capability: ship-on-behalf`). `fetch`/confirm/openUrl/progress are injected
+ * so it's unit-tested with no network/TTY.
+ *
+ * @param {{ tenant:string, pr:number|string|null, secret:string, storefrontUrl?:string|null,
+ *   noOpen?:boolean, yes?:boolean }} params
+ * @param {{ fetch?:typeof fetch, confirmPlan?:typeof printPlanAndConfirm,
+ *   openUrl?:(u:string)=>boolean, progress?:boolean }} [deps]
+ * @returns {Promise<number>} process exit code
+ */
+export async function runShipByPr(
+  { tenant, pr, secret, storefrontUrl = null, noOpen = false, yes = false },
+  deps = {},
+) {
+  const fetchImpl = deps.fetch || globalThis.fetch;
+  const confirmPlan = deps.confirmPlan || printPlanAndConfirm;
+  const base = (storefrontUrl || DEFAULT_STOREFRONT_URL).trim().replace(/\/+$/, "");
+
+  const want = pr != null && `${pr}`.trim() && Number.isFinite(Number(pr)) ? Number(pr) : null;
+  if (want == null) {
+    console.error(
+      fail(
+        "operator ship needs a PR number to resolve the built candidate",
+        "pass a PR — `tot ship <N>` or `tot ship --pr <N> --tenant <appDomain>`",
+      ),
+    );
+    return 2;
+  }
+  if (!secret) {
+    console.error(
+      fail(
+        "shipping a PR that isn't your checkout is an OPERATOR action — it needs an operator secret",
+        "set PREVIEW_RECONCILE_SECRET (or GRANTS_ADMIN_SECRET / TOT_OPERATOR_SECRET), or pass --secret",
+      ),
+    );
+    return 2;
+  }
+
+  const authHeaders = {
+    authorization: `Bearer ${secret}`,
+    "x-tot-owner": tenant,
+    "x-tot-capability": "ship-on-behalf",
+  };
+
+  // 1. Resolve PR N → { changeId, headSha } from the tenant's OPEN candidate queue.
+  let queueRes;
+  try {
+    queueRes = await fetchImpl(`${base}/api/changes`, { method: "GET", headers: authHeaders });
+  } catch (e) {
+    console.error(
+      fail(`couldn't reach the candidate queue at ${base}: ${String(e?.message || e)}`, "check --url / your network, then re-run"),
+    );
+    return 1;
+  }
+  const queueData = await readJsonSafe(queueRes);
+  if (!queueRes.ok) {
+    const msg = queueData?.error || `HTTP ${queueRes.status}`;
+    console.error(
+      fail(
+        `the candidate queue refused the request: ${msg}`,
+        queueRes.status === 401 || queueRes.status === 403
+          ? "check the operator secret and that it's authorised for this tenant"
+          : "check --tenant / --url, then re-run",
+      ),
+    );
+    return 1;
+  }
+
+  const candidate = findCandidateByPr(normalizeChangesQueue(queueData), want);
+  if (!candidate) {
+    const previewUrl = previewUrlFor(base, tenant, want);
+    console.error(
+      fail(
+        `PR #${want} has no built candidate in ${tenant}'s queue — there's nothing to ship`,
+        `build it first: \`tot preview build --tenant ${tenant} --pr ${want}\`, then \`tot ship ${want} --tenant ${tenant}\``,
+      ),
+    );
+    if (previewUrl) console.error(`  Once built it appears at: ${previewUrl}`);
+    return 1;
+  }
+
+  // 2. Plan + confirm — the go-live HUMAN GATE. `POST /api/changes/accept` is the
+  //    ATOMIC merge→main + promote-live, so the plan narrates BOTH (developer-context
+  //    wording — the same "merge … then deploy" the /admin Accept plan renders).
+  const previewUrl = candidate.previewUrl || previewUrlFor(base, tenant, want);
+  const planLines = planForAction({
+    action: "ship",
+    context: "developer",
+    tenant,
+    pr: want,
+    changeId: candidate.changeId,
+    headSha: candidate.headSha,
+    targets: { preview: previewUrl, live: liveUrlFor(tenant) },
+  });
+  const { confirmed, reason } = await confirmPlan(planLines, {
+    yes,
+    question: `Ship PR #${want} live to ${tenant} (merge → main, then go live)?`,
+  });
+  if (!confirmed) {
+    if (reason === "non-tty") {
+      console.error(
+        fail(
+          "`tot ship` needs an interactive terminal to confirm this live change",
+          "re-run from a terminal, or pass --yes to confirm non-interactively",
+        ),
+      );
+      return 2;
+    }
+    console.log("  Ship cancelled — nothing changed.");
+    return 0;
+  }
+
+  // 3. Accept it via the SAME endpoint the /admin Accept button uses (repo=appDomain).
+  const progress = deps.progress === false ? null : startProgress("shipping…");
+  let acceptRes;
+  try {
+    acceptRes = await fetchImpl(`${base}/api/changes/accept`, {
+      method: "POST",
+      headers: { "content-type": "application/json", ...authHeaders },
+      body: JSON.stringify({
+        repo: tenant,
+        changeId: candidate.changeId,
+        ...(candidate.headSha ? { expectedHeadSha: candidate.headSha } : {}),
+      }),
+    });
+  } catch (e) {
+    progress?.stop();
+    console.error(
+      fail(`couldn't reach the ship endpoint at ${base}: ${String(e?.message || e)}`, "check --url / your network, then re-run"),
+    );
+    return 1;
+  }
+  const acceptData = await readJsonSafe(acceptRes);
+  progress?.stop();
+
+  const result = normalizeAcceptResponse(acceptData);
+  if (!acceptRes.ok && !result.shipped && !result.pending) {
+    const why = result.error || result.message || `HTTP ${acceptRes.status}`;
+    console.error(
+      fail(
+        `the ship gate refused this change (HTTP ${acceptRes.status}): ${why}`,
+        "check the PR reconciled cleanly (rebuild with `tot preview build`), then re-run",
+      ),
+    );
+    return 1;
+  }
+  return reportShippedByPr(result, { tenant, pr: want, previewUrl, noOpen, openUrl: deps.openUrl });
+}
+
+/** Read a fetch Response body as JSON, tolerating a non-JSON/empty body. */
+async function readJsonSafe(res) {
+  try {
+    return await res.json();
+  } catch {
+    return {};
+  }
+}
+
+/** Report the by-PR ship result — honest terminal state (never a false "shipped live"). */
+function reportShippedByPr(result, { tenant, pr, previewUrl, noOpen, openUrl }) {
+  const liveUrl = liveUrlFor(tenant);
+  if (result.shipped) {
+    console.log(`\n  ✓ shipped PR #${pr} live to ${tenant}.`);
+    if (liveUrl) {
+      console.log(`  Live: ${liveUrl}`);
+      if (!noOpen && openUrl && openUrl(liveUrl)) console.log("  (opened in your browser)");
+    }
+    return 0;
+  }
+  // Merged + dispatched but the target isn't verified live yet — honest in-flight.
+  console.log(`\n  ~ ship accepted for PR #${pr} on ${tenant}; it's going live now (not yet verified).`);
+  if (previewUrl) console.log(`  Track it here: ${previewUrl}`);
+  return 0;
+}
+
 // ─── Operator ship (DEPLOY-only) ─────────────────────────────────────────────────────
 
 /**
@@ -866,6 +1186,26 @@ async function runOperatorFlow(args, ctx, env) {
   }
   const pr = args.pr != null && `${args.pr}`.trim() && Number.isFinite(Number(args.pr)) ? Number(args.pr) : args.pr;
   const storefrontUrl = args.url || env.TOT_STOREFRONT_URL || env.STOREFRONT_BASE_URL || DEFAULT_STOREFRONT_URL;
+
+  // u16: with NO explicit change-record id, ship ANY built PR via the SHARED candidate
+  // queue — resolve PR→changeId from GET /api/changes and ship via POST
+  // /api/changes/accept (operator secret transport). This is the path that ships a PR
+  // the operator did NOT author. The explicit `--change-id` path below stays the MCP
+  // change_accept targeting (backward-compatible; distinct chg_-record namespace).
+  if (!args.changeId) {
+    return await runShipByPr(
+      {
+        tenant,
+        pr,
+        secret: resolveOperatorSecret(args.secret, env),
+        storefrontUrl,
+        noOpen: args.noOpen,
+        yes: args.yes,
+      },
+      { openUrl: (u) => openBrowser(u) },
+    );
+  }
+
   const baseUrl = args.mcp || env.MCP_BASE_URL || env.TOT_MCP_URL || DEFAULT_MCP_URL;
   const client = createMcpClient(baseUrl);
   try {
@@ -981,6 +1321,7 @@ export async function run(argv, ctx) {
     const headSubject = gitSafe(["log", "-1", "--format=%s"]).trim();
     const changeSummary = buildChangeSummary({ message: headSubject, headSubject });
 
+    const storefrontUrl = args.url || env.TOT_STOREFRONT_URL || env.STOREFRONT_BASE_URL || DEFAULT_STOREFRONT_URL;
     return await runShip(
       client,
       {
@@ -990,13 +1331,34 @@ export async function run(argv, ctx) {
         git,
         noOpen: args.noOpen,
         yes: args.yes,
-        storefrontUrl: args.url || env.TOT_STOREFRONT_URL || env.STOREFRONT_BASE_URL || DEFAULT_STOREFRONT_URL,
+        storefrontUrl,
         changeSummary,
         // A positional `tot ship 4` asserts WHICH PR — passed as a safety guard so
         // ship refuses if this checkout's active candidate is a different PR.
         expectedPr: args.prPositional ? args.pr : null,
       },
-      { openUrl: (u) => openBrowser(u) },
+      {
+        openUrl: (u) => openBrowser(u),
+        // u16: when `tot ship <N>` names a PR that ISN'T this checkout's candidate (no
+        // local candidate resolves), fall through to the operator-by-PR queue path — so
+        // `tot ship 4` ships someone else's built PR too, using this checkout's tenant.
+        ...(args.prPositional
+          ? {
+              shipByPrFallback: () =>
+                runShipByPr(
+                  {
+                    tenant,
+                    pr: args.pr,
+                    secret: resolveOperatorSecret(args.secret, env),
+                    storefrontUrl,
+                    noOpen: args.noOpen,
+                    yes: args.yes,
+                  },
+                  { openUrl: (u) => openBrowser(u) },
+                ),
+            }
+          : {}),
+      },
     );
   } catch (e) {
     if (e instanceof AuthUnavailableError) {

package/src/commands/submit.mjs

@@ -3,7 +3,9 @@
  *
  * From inside a tenant checkout:
  *   1. validate locally and refuse on errors (fail fast before anything leaves the machine),
- *   2. push your committed work to the tenant repo's `preview` ref (triggers reconcile),
+ *   2. push your committed work to YOUR OWN isolated candidate ref — `candidate/<changeId>`
+ *      (b03 — no shared `preview` ref is ever force-pushed; an explicit `--ref` can still
+ *      target a literal ref name for back-compat) — which triggers reconcile,
  *   2b. open/update a PR-BACKED CANDIDATE for the same committed diff (g1b's
  *       `candidate_open`, unit c1 — the local-dev-loop half of the "PR-Backed Hosted
  *       Review Loop" milestone, symmetric with the hosted s6 draft-as-PR path), and
@@ -57,10 +59,25 @@ import {
 } from "../candidate-state.mjs";
 
 const DEFAULT_MCP_URL = "https://mcp.tokenoftrust.com";
-const DEFAULT_REF = "preview";
+
+// The git ref prefix an isolated candidate push lands under (b03 — stop
+// force-pushing the SHARED `preview` ref). ONE constant so a rename is trivial —
+// provisionally coordinated with the MCP-side candidate_open resolution (b02/b04),
+// which already names its PR-backed branch `candidate/<changeId>` (see
+// submitCandidate, below): the raw git push here and the PR-backed candidate it
+// opens always target the SAME branch, never two.
+export const CANDIDATE_REF_PREFIX = "candidate/";
+
+/** The isolated git ref a candidate's preview push lands under. Pure. */
+export function candidateRefFor(changeId) {
+  return `${CANDIDATE_REF_PREFIX}${changeId}`;
+}
 
 export function parseArgs(argv) {
-  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 };
+  // `ref: null` — an explicit `--ref` always wins; otherwise the push target is
+  // derived per-run as YOUR OWN isolated candidate ref (resolvePushRef, below),
+  // never a fixed shared default.
+  const a = { mcp: null, identity: null, ref: null, skipValidate: false, noWait: false, watch: false, noOpen: false, noCommit: false, message: null, summary: null, new: false, help: false };
   for (let i = 0; i < argv.length; i++) {
     const t = argv[i];
     if (t === "--mcp") a.mcp = argv[++i];
@@ -93,7 +110,7 @@ export function renderUsage(verb = "preview") {
   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} --ref <name>       push ref (default: your own isolated candidate ref — see \`tot pr\`)
   tot ${verb} -m "<title>"       one-line summary of what changed (the approver sees this)
   tot ${verb} --summary "<text>" longer description to accompany the title
   tot ${verb} --no-wait          push and exit without polling for the reconcile result
@@ -513,6 +530,44 @@ export function actorKeyFor(session) {
   return session?.email || session?.token || "developer";
 }
 
+/**
+ * Which candidate this submit lands on (gh-pr-like) — decided UP FRONT, before any
+ * network call, because it also determines the isolated git ref we push to
+ * (resolvePushRef, below): a re-submit updates the SAME candidate/ref by default;
+ * `--new` forks a fresh one.
+ *   --new     → fork a FRESH candidate id;
+ *   otherwise → the remembered active candidate (from a prior --new / terminal
+ *               roll), else the STABLE per-dev-per-tenant(-per-branch) default.
+ * `persist` reports whether the choice diverges from the stable default, so the
+ * caller knows whether to remember it as the new active pointer. `mint` is
+ * injected (defaults to mintFreshChangeId) so this is pure/deterministic in tests.
+ * Pure — unit-tested.
+ * @param {{ tenant: string, actorKey: string, branch?: string|null, active?: string|null,
+ *   isNew?: boolean, mint?: (baseId: string) => string }} opts
+ * @returns {{ changeId: string, stableId: string, persist: boolean }}
+ */
+export function chooseChangeId({ tenant, actorKey, branch = null, active = null, isNew = false, mint = mintFreshChangeId }) {
+  const stableId = deriveChangeId(tenant, actorKey, branch);
+  const changeId = isNew ? mint(stableId) : (active || stableId);
+  const persist = isNew || (!!active && active !== stableId);
+  return { changeId, stableId, persist };
+}
+
+/**
+ * The ref `tot preview`/`tot submit` pushes to (b03 — stop force-pushing the
+ * SHARED `preview` ref). An explicit `--ref` always wins — the escape hatch /
+ * back-compat path (e.g. `--ref preview` reproduces the old shared-ref push for
+ * any tooling that still reads it by that literal name); otherwise it's YOUR OWN
+ * isolated candidate ref, so two developers — or the same developer on two
+ * branches — never force-push over each other or each other's preview. Pure —
+ * unit-tested.
+ * @param {{ ref?: string|null, changeId: string }} opts
+ * @returns {string}
+ */
+export function resolvePushRef({ ref, changeId }) {
+  return ref || candidateRefFor(changeId);
+}
+
 /**
  * Open/update the PR-backed candidate for this submit (g1b `candidate_open`,
  * unit c1 — the local-dev-loop half of the "PR-Backed Hosted Review Loop"
@@ -663,6 +718,9 @@ export async function run(argv, ctx, { verb = "preview" } = {}) {
   // same diff (name-status, so candidate_open also knows adds/deletes/renames)
   // doubles as the source of the PR-backed candidate's file patch (step 2b, below)
   // — one git read, two consumers, so the PR always matches what's printed here.
+  // Parameterized on `ref` (b03 — isolated candidate refs): the diff base is YOUR
+  // candidate ref's own tracking ref, not a shared one, so the summary always reads
+  // "vs your own last push" once the push ref is known (computed just below).
   const gitSafe = (cargs) => {
     try {
       return git(cargs);
@@ -670,18 +728,21 @@ export async function run(argv, ctx, { verb = "preview" } = {}) {
       return "";
     }
   };
-  const headSubject = gitSafe(["log", "-1", "--format=%s"]).trim();
-  const trackingRef = `refs/remotes/origin/${args.ref}`;
-  const base = gitSafe(["rev-parse", "--verify", "--quiet", trackingRef]).trim()
-    ? trackingRef
-    : gitSafe(["rev-parse", "--verify", "--quiet", "HEAD~1"]).trim()
-      ? "HEAD~1"
-      : "";
-  const statusCmd = base ? ["diff", "--name-status", `${base}..HEAD`] : ["show", "--name-status", "--format=", "HEAD"];
-  const patchEntries = parseNameStatus(gitSafe(statusCmd));
-  const files = patchEntries.map((e) => e.path);
-  const statLine = base ? gitSafe(["diff", "--shortstat", `${base}..HEAD`]).trim() : "";
-  const changeSummary = buildChangeSummary({ message: args.message, summary: args.summary, headSubject, statLine, files });
+  function buildSummaryAndPatch(ref) {
+    const headSubject = gitSafe(["log", "-1", "--format=%s"]).trim();
+    const trackingRef = `refs/remotes/origin/${ref}`;
+    const base = gitSafe(["rev-parse", "--verify", "--quiet", trackingRef]).trim()
+      ? trackingRef
+      : gitSafe(["rev-parse", "--verify", "--quiet", "HEAD~1"]).trim()
+        ? "HEAD~1"
+        : "";
+    const statusCmd = base ? ["diff", "--name-status", `${base}..HEAD`] : ["show", "--name-status", "--format=", "HEAD"];
+    const patchEntries = parseNameStatus(gitSafe(statusCmd));
+    const files = patchEntries.map((e) => e.path);
+    const statLine = base ? gitSafe(["diff", "--shortstat", `${base}..HEAD`]).trim() : "";
+    const changeSummary = buildChangeSummary({ message: args.message, summary: args.summary, headSubject, statLine, files });
+    return { changeSummary, patchEntries };
+  }
 
   // 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
@@ -690,6 +751,15 @@ export async function run(argv, ctx, { verb = "preview" } = {}) {
   const client = createMcpClient(baseUrl);
   const repo = repoNameFromRemote(gitSafe(["remote", "get-url", "origin"]).trim());
 
+  // Branch-bound (u4) + the isolated candidate ref (b03): resolved BEFORE the push,
+  // since the push target itself depends on it — so the raw git push and the
+  // PR-backed candidate (step 2b, below) always land on the SAME branch. `active`/
+  // `statePath` are local filesystem reads (candidate-state.mjs) — no session
+  // needed — so they're available even on the no-session fallback path below.
+  const branch = currentBranch(gitSafe);
+  const statePath = defaultCandidateStatePath(env);
+  const active = repo ? readActiveChangeId(statePath, { mcpUrl: baseUrl, repo, branch }) : null;
+
   let session;
   try {
     session = await establishSession(client, { env, prefer: args.identity || undefined });
@@ -697,10 +767,15 @@ export async function run(argv, ctx, { verb = "preview" } = {}) {
     // 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)`);
+    // still lands if that embedded token is live. actorKeyFor(null) degrades to the
+    // generic "developer" key — still isolated PER BRANCH (never the shared ref),
+    // just not per-developer until sign-in succeeds.
+    const { changeId } = chooseChangeId({ tenant, actorKey: actorKeyFor(null), branch, active, isNew: args.new });
+    const ref = resolvePushRef({ ref: args.ref, changeId });
+    const { changeSummary } = buildSummaryAndPatch(ref);
+    console.error(`~ pushing ${short} → ${ref} (origin)`);
     try {
-      const out = git(["push", "-f", "origin", `HEAD:refs/heads/${args.ref}`]);
+      const out = git(["push", "-f", "origin", `HEAD:refs/heads/${ref}`]);
       if (out.trim()) console.error(redactUrl(out.trim()));
     } catch (pushErr) {
       console.error(
@@ -711,7 +786,7 @@ export async function run(argv, ctx, { verb = "preview" } = {}) {
       );
       return 1;
     }
-    console.log(`\n+ submitted ${short} to ${args.ref}.`);
+    console.log(`\n+ submitted ${short} to ${ref}.`);
     printChangeSummary(changeSummary);
     if (e instanceof AuthUnavailableError) {
       console.log(`  (sign in to see the reconcile/compliance/preview result — ${e.hint || "developer sign-in pending"})`);
@@ -722,6 +797,15 @@ export async function run(argv, ctx, { verb = "preview" } = {}) {
     return 0;
   }
 
+  // Which candidate (and therefore which isolated ref, b03) this submit targets —
+  // decided now, with a real session, so the SAME id backs both the raw git push
+  // (right below) and the PR-backed candidate (step 2b): the two never point at
+  // different branches. See chooseChangeId's doc for the --new / active-pointer
+  // rules.
+  let { changeId, stableId, persist } = chooseChangeId({ tenant, actorKey: actorKeyFor(session), branch, active, isNew: args.new });
+  const ref = resolvePushRef({ ref: args.ref, changeId });
+  const { changeSummary, patchEntries } = buildSummaryAndPatch(ref);
+
   // 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
@@ -741,9 +825,9 @@ export async function run(argv, ctx, { verb = "preview" } = {}) {
     }
   };
 
-  console.error(`~ pushing ${short} → ${args.ref} (origin, fresh credential)`);
+  console.error(`~ pushing ${short} → ${ref} (origin, fresh credential)`);
   try {
-    const { out } = await pushPreviewRef(git, mintRemote, { ref: args.ref });
+    const { out } = await pushPreviewRef(git, mintRemote, { ref });
     if (out && out.trim()) console.error(redactUrl(out.trim()));
   } catch (e) {
     console.error(
@@ -754,7 +838,7 @@ export async function run(argv, ctx, { verb = "preview" } = {}) {
     );
     return 1;
   }
-  console.log(`\n+ submitted ${short} to ${args.ref}.`);
+  console.log(`\n+ submitted ${short} to ${ref}.`);
   printChangeSummary(changeSummary);
 
   // 2b + 3. open/update the PR-backed candidate, then report reconcile +
@@ -768,25 +852,11 @@ export async function run(argv, ctx, { verb = "preview" } = {}) {
     // 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.
-    //
-    // 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.)
+    // `changeId`/`stableId`/`persist` were already decided above (they picked the
+    // push ref too); if the chosen candidate turns out to be merged/closed, roll to
+    // a fresh one so a re-submit is never wedged on a dead PR. (`repo` was derived
+    // 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 });