@tokenoftrust/cli 1.4.0-rc.7 → 1.4.0-rc.9

package/README.md

@@ -5,8 +5,8 @@ One command to go from a Token of Trust invite to a running store.
 ```sh
 npm i -g @tokenoftrust/cli
 
-tot checkout                 # list the stores you can build on
-tot checkout <tenant> --clone ./my-store
+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
@@ -22,7 +22,7 @@ be fetched.)
 
 | Command | Status | What it does |
 | --- | --- | --- |
-| `tot checkout [<tenant>]` | **built** | Clone a store you're entitled to build on, with an authenticated remote configured. No arg → list your stores. |
+| `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 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). |
@@ -34,7 +34,7 @@ The same `tot` does the right thing wherever you run it (walks up like `git`):
 
 - **storefront monorepo** — a full platform checkout;
 - **tenant checkout** — a standalone `content/ public/ theme.json .tot/config.json` clone (tenant read from `.tot/config.json`);
-- **loose** — anywhere else; `tot checkout <tenant> --clone <dir>` gets you a checkout.
+- **loose** — anywhere else; `tot clone <tenant>` gets you a checkout.
 
 `tot doctor` prints the detected context.
 
@@ -42,8 +42,8 @@ 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 checkout`, `tot start`, `tot submit`, …) 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 checkout` **offer to sign you in right there** and continue in-flow — no "run `tot login`, then re-run".
+- 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.
+- 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.
 
 ### Optional: multiple identities at once (`TOT_PROFILE`)

package/bin/tot.mjs

@@ -10,10 +10,11 @@
  *   tot whoami                who you're signed in as                    ← built
  *   tot link                  link your identity to the ToT broker (resolve store scope)  ← built
  *   tot grants                capability/tier/expiry per store you can act on  ← built (introspection diagnostics)
- *   tot checkout [<tenant>]   clone a store you can build on            ← built
+ *   tot clone [<tenant>]      clone a store you can build on            ← built
  *   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 submit                submit your store for preview             ← built (validate + push preview ref; MCP preview_status read-back)
+ *   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
  *   tot feedback              send a note to ToT + your recent CLI activity  ← built (activity-log.mjs → feedback_submit MCP tool)
@@ -25,7 +26,7 @@
  * from anywhere else. Every command receives the detected context.
  *
  * This package is `@tokenoftrust/cli` (bin `tot`). Its heaviest command, `tot dev`,
- * fetches the published storefront runner; `tot checkout/validate/submit` are
+ * fetches the published storefront runner; `tot clone/validate/submit` are
  * pure Node. Dependency-free by design so `npm i -g @tokenoftrust/cli` stays light.
  */
 import "../src/ensure-node.mjs"; // hard Node-version gate — must stay first (see the module doc)
@@ -35,7 +36,7 @@ import { printError } from "../src/errors.mjs";
 import { recordActivity, redactArgs } from "../src/activity-log.mjs";
 import { maybeNotifyUpdate } from "../src/update-check.mjs";
 
-const BUILD_ORDER = ["checkout", "validate", "dev", "submit"];
+const BUILD_ORDER = ["clone", "validate", "dev", "submit"];
 
 // CLI version (stamped into the activity log). Read from our own package.json; best-effort.
 const VERSION = (() => {
@@ -56,10 +57,11 @@ tot — Token of Trust developer CLI
   tot whoami                show who you're signed in as
   tot link                  link your identity so your stores resolve
   tot grants                capability/tier/expiry per store you can act on
-  tot checkout [<tenant>]   clone a store you can build on
+  tot clone [<tenant>]      clone a store you can build on
   tot validate              lint your store before you submit
   tot dev                   run your store locally with save→reload
   tot submit                submit your store for preview
+  tot pr                    list / view / close your candidate PRs
   tot doctor                check this machine is ready
   tot ideas                 copy-paste AI prompts that reliably wow
   tot feedback "<msg>"      send feedback to Token of Trust (attaches recent activity)
@@ -131,8 +133,8 @@ async function dispatch(cmd, rest, ctx) {
     return run(rest, ctx);
   }
 
-  if (cmd === "checkout") {
-    const { run } = await import("../src/commands/checkout.mjs");
+  if (cmd === "clone") {
+    const { run } = await import("../src/commands/clone.mjs");
     return run(rest, ctx);
   }
 
@@ -151,15 +153,31 @@ async function dispatch(cmd, rest, ctx) {
     return run(rest, ctx);
   }
 
+  if (cmd === "pr") {
+    const { run } = await import("../src/commands/pr.mjs");
+    return run(rest, ctx);
+  }
+
   if (cmd === "app") {
     const { run } = await import("../src/commands/app/index.mjs");
     return run(rest, ctx);
   }
 
+  // `checkout` was deliberately freed up: it's no longer a tot verb precisely so it
+  // can mean what it means in git. Point both ways rather than a bare "unknown".
+  if (cmd === "checkout") {
+    console.error(
+      "`tot checkout` isn't a tot command — `checkout` now means what it does in git.\n\n" +
+        "  • switch branches / restore files in your store:  git checkout <ref>\n" +
+        "  • clone a store you can build on:                 tot clone <tenant>\n",
+    );
+    return 2;
+  }
+
   if (BUILD_ORDER.includes(cmd)) {
     console.error(
       `\`tot ${cmd}\` isn't built yet.\n\n` +
-        `Build order: ${BUILD_ORDER.map((c) => (c === "checkout" ? `${c}✓` : c)).join(" → ")}.\n` +
+        `Build order: ${BUILD_ORDER.map((c) => (c === "clone" ? `${c}✓` : c)).join(" → ")}.\n` +
         `Inside a storefront checkout you can use the in-repo scripts today ` +
         `(e.g. \`pnpm tot ${cmd}\`).`,
     );

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@tokenoftrust/cli",
-  "version": "1.4.0-rc.7",
-  "description": "Token of Trust developer CLI — check out a tenant store, run it locally with save→reload, and submit it for preview. Installs the `tot` command.",
+  "version": "1.4.0-rc.9",
+  "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",
   "homepage": "https://www.tokenoftrust.com",

package/src/candidate-state.mjs

@@ -0,0 +1,97 @@
+/**
+ * The "active candidate" pointer — which open candidate PR a plain `tot submit`
+ * updates, per forge repo.
+ *
+ * `tot submit` is idempotent on a STABLE changeId (`deriveChangeId`) so a re-submit
+ * updates the same PR by default — the common case needs NO state and writes
+ * nothing here (backward-compatible with the stateless original). This file only
+ * records a DIVERGENCE from that stable default:
+ *
+ *   - `tot submit --new` forks a fresh candidate and remembers it here, so the
+ *     NEXT plain `tot submit` keeps updating the NEW PR (like pushing more commits
+ *     to a `gh pr` branch), not the old one; and
+ *   - 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
+ * 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).
+ */
+import {
+  readFileSync, writeFileSync, mkdirSync, renameSync, chmodSync,
+} from "node:fs";
+import { homedir } from "node:os";
+import { join, dirname } from "node:path";
+import { randomBytes } from "node:crypto";
+
+/** Absolute path to the active-candidate map for this machine. */
+export function defaultCandidateStatePath(env = process.env) {
+  const home = env.TOT_HOME || homedir();
+  return join(home, ".tot", "candidates.json");
+}
+
+/** Namespace key for one (MCP, repo) candidate pointer. */
+function stateKey(mcpUrl, repo) {
+  return `${mcpUrl}::${repo}`;
+}
+
+function readMap(filePath) {
+  try {
+    const parsed = JSON.parse(readFileSync(filePath, "utf8"));
+    return parsed && typeof parsed === "object" ? parsed : {};
+  } catch {
+    return {};
+  }
+}
+
+function writeMap(filePath, map) {
+  mkdirSync(dirname(filePath), { recursive: true, mode: 0o700 });
+  const tmp = `${filePath}.tmp`;
+  writeFileSync(tmp, `${JSON.stringify(map, null, 2)}\n`, { mode: 0o600 });
+  renameSync(tmp, filePath);
+  chmodSync(filePath, 0o600);
+}
+
+/**
+ * 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.
+ */
+export function readActiveChangeId(filePath, { mcpUrl, repo }) {
+  const rec = readMap(filePath)[stateKey(mcpUrl, repo)];
+  return rec && typeof rec.changeId === "string" && rec.changeId ? rec.changeId : null;
+}
+
+/** Remember `changeId` as the active candidate for `(mcpUrl, repo)`, atomically. */
+export function writeActiveChangeId(filePath, { mcpUrl, repo, changeId }) {
+  const map = readMap(filePath);
+  map[stateKey(mcpUrl, repo)] = { 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 }) {
+  const map = readMap(filePath);
+  const key = stateKey(mcpUrl, repo);
+  if (key in map) {
+    delete map[key];
+    writeMap(filePath, map);
+  }
+}
+
+/**
+ * A fresh candidate handle forked from a stable base — `<baseId>-<suffix>`, still
+ * matching candidate_open's `[a-z0-9._-]` handle grammar. The suffix defaults to
+ * 6 random hex chars (so two `--new` runs never collide); tests inject a fixed
+ * suffix. Pure given `suffix`.
+ */
+export function mintFreshChangeId(baseId, suffix = randomBytes(3).toString("hex")) {
+  const safe = String(suffix).toLowerCase().replace(/[^a-z0-9]/g, "").slice(0, 12) || "new";
+  return `${baseId}-${safe}`;
+}
+
+/** Whether a forge candidate state means "no open PR to update" (rolled past). */
+export function isTerminalCandidateState(state) {
+  return state === "merged" || state === "closed";
+}

package/src/commands/{checkout.mjs → clone.mjs}

@@ -1,16 +1,23 @@
 /**
- * `tot checkout` — clone the tenant store you're entitled to build on, with an
- * authenticated remote already configured, ready for the local loop.
+ * `tot clone` — clone the tenant store you're entitled to build on, with an
+ * authenticated remote already configured, ready for the local loop. Mirrors
+ * `git clone <repo> [dir]`: the tenant is the repo, the dir defaults to the
+ * tenant name. (Named `clone`, not `checkout`, so it means what `git clone`
+ * means — materialize a local working copy — and never collides with the
+ * unrelated `git checkout` = switch-refs verb.)
  *
- *   tot checkout                      list the stores you can build on
- *   tot checkout <tenant>             show the checkout for <tenant>
- *   tot checkout <tenant> --clone DIR clone it to DIR with an authed remote
+ *   tot clone                    list the stores you can build on
+ *   tot clone <tenant>           clone into ./<tenant> (authenticated remote configured)
+ *   tot clone <tenant> <dir>     clone into <dir>
+ *   tot clone <tenant> --remote-only   just mint + print the remote, don't materialize
  *
  * This is the SAME MCP code path a developer gets when they switch to a tenant:
  * sign-in → client_switch(tenant) → tenant_checkout, where the MCP derives your
  * per-tenant Git user and mints a FRESH, single-active, repo-scoped push
- * credential (a later checkout for the same tenant rotates it). `tot` performs NO
- * privileged forge work itself — the MCP owns that.
+ * credential (a later clone for the same tenant rotates it). `tot` performs NO
+ * privileged forge work itself — the MCP owns that. ("checkout" survives only as
+ * the domain/lease term: the `tenant_checkout` MCP tool + the on-disk noun for a
+ * materialized store dir — never as a developer-facing verb.)
  *
  * Auth is the developer's own ToT identity (the cached `tot login` session,
  * resolved via src/auth.mjs). When there's no session yet and we're on a TTY, we
@@ -34,8 +41,9 @@ const DEFAULT_MCP_URL = "https://mcp.tokenoftrust.com";
 function parseArgs(argv) {
   const a = {
     tenant: null,
+    dir: null,
     tag: "main",
-    clone: null,
+    remoteOnly: false,
     mcp: null,
     printRemote: false,
     help: false,
@@ -43,27 +51,32 @@ function parseArgs(argv) {
   for (let i = 0; i < argv.length; i++) {
     const t = argv[i];
     if (t === "--tag") a.tag = argv[++i];
-    else if (t === "--clone") a.clone = argv[++i];
+    else if (t === "--remote-only") a.remoteOnly = true;
     else if (t === "--mcp") a.mcp = argv[++i];
     else if (t === "--print-remote") a.printRemote = true;
     else if (t === "--help" || t === "-h") a.help = true;
-    else if (!t.startsWith("--") && !a.tenant) a.tenant = t;
+    // Positional, git-clone style: `tot clone <tenant> [<dir>]`.
+    else if (!t.startsWith("--")) {
+      if (!a.tenant) a.tenant = t;
+      else if (!a.dir) a.dir = t;
+    }
   }
   return a;
 }
 
-const USAGE = `tot checkout — clone a tenant store you can build on
+const USAGE = `tot clone — clone a tenant store you can build on (mirrors \`git clone\`)
 
-  tot checkout                        list the stores you can build on
-  tot checkout <tenant>               show the checkout for <tenant>
-  tot checkout <tenant> --clone <dir> clone it locally (authenticated remote configured)
+  tot clone                    list the stores you can build on
+  tot clone <tenant>           clone into ./<tenant> (authenticated remote configured)
+  tot clone <tenant> <dir>     clone into <dir>
 
 Options:
   --tag <tag>       which repo (repo = "<tenant>-<tag>"). Default: main.
-  --clone <dir>     git clone the authenticated remote into <dir>.
+  --remote-only     don't clone; just mint + print the clone URL for <tenant>.
   --mcp <url>       MCP base URL. Default: env MCP_BASE_URL / TOT_MCP_URL, else
                     ${DEFAULT_MCP_URL}.
-  --print-remote    also print the authenticated remote (contains a live token!).`;
+  --print-remote    with --remote-only, also print the authenticated remote
+                    (contains a live token!).`;
 
 /** Redact known secrets from any string before it hits the terminal. */
 function makeRedactor(env) {
@@ -92,6 +105,11 @@ export async function run(argv, ctx) {
     args.tenant = ctx.tenant;
   }
 
+  // git-clone semantics: unless you explicitly asked for --remote-only, cloning
+  // is the default, and the target dir defaults to the tenant name (like
+  // `git clone <url>` deriving the dir from the repo basename).
+  const cloneDir = args.remoteOnly ? null : args.dir || args.tenant;
+
   const baseUrl = args.mcp || env.MCP_BASE_URL || env.TOT_MCP_URL || DEFAULT_MCP_URL;
   const redact = makeRedactor(env);
   const client = createMcpClient(baseUrl);
@@ -128,21 +146,21 @@ export async function run(argv, ctx) {
     const res = await checkoutTenant(client, {
       tenant: args.tenant,
       tag: args.tag,
-      cloneDir: args.clone || null,
+      cloneDir,
       redact,
     });
-    console.log(`\n+ checkout ready. repo: ${res.cloneUrl || res.publicUrl}`);
+    console.log(`\n+ ready. repo: ${res.cloneUrl || res.publicUrl}`);
 
     if (res.cloned) {
       console.log(`+ cloned. HEAD: ${res.head}`);
       console.log(`\nYour local working clone is at ${res.dir} with an authenticated remote.`);
       console.log(`  cd ${res.dir} && tot dev            # run it locally with save→reload`);
-      console.log(`  (the minted token lives in .git/config; a later checkout rotates it)`);
+      console.log(`  (the minted token lives in .git/config; a later clone rotates it)`);
       return 0;
     }
 
     console.log(`\nPublic clone URL (no credential): ${res.publicUrl}`);
-    console.log(`Re-run with --clone <dir> to clone with the authenticated remote configured.`);
+    console.log(`Drop --remote-only to clone with the authenticated remote configured.`);
     if (args.printRemote) {
       console.log(
         `\nAUTHENTICATED remote (contains a live token — handle carefully):\n${res.gitRemote}`,
@@ -164,7 +182,7 @@ export async function run(argv, ctx) {
 }
 
 /**
- * The privileged checkout core, composable in-process (used by `tot checkout`
+ * The privileged checkout core, composable in-process (used by `tot clone`
  * and by `tot start`): client_switch → tenant_checkout → optionally clone. The
  * MCP mints a fresh, repo-scoped push credential each time. Assumes `client` is
  * already initialized + has a validated session.
@@ -211,7 +229,7 @@ async function cloneRepo(gitRemote, dir, redact) {
     await git(["clone", gitRemote, dir]);
   } catch (e) {
     // Beacon the cockpit before we surface the error — covers this path for both
-    // `tot checkout` and `tot start` (which clones through here). Awaited so the
+    // `tot clone` and `tot start` (which clones through here). Awaited so the
     // packet lands before the process prints + exits; swallowed either way.
     await emitObstacle("clone-failed");
     throw new CliError(`clone failed: ${redact(String(e.stderr || e.message || e))}`, {
@@ -255,13 +273,13 @@ export function checkoutError(checkout) {
   }
   return {
     message: msg || "the store checkout couldn't be completed",
-    next: "confirm you're entitled to this store — `tot checkout` (lists your stores)",
+    next: "confirm you're entitled to this store — `tot clone` (lists your stores)",
   };
 }
 
 /**
  * Normalize the (shape-varying) `client_list` response into a plain, sorted
- * list of the stores this identity can build on. Shared by `tot checkout`'s
+ * list of the stores this identity can build on. Shared by `tot clone`'s
  * listing and `tot start`'s auto-pick so both read the same fields.
  * @param {unknown} list
  * @returns {Array<{ id: string, name: string, raw: any }>}
@@ -409,5 +427,5 @@ function printClientList(list) {
   for (const s of stores) {
     console.log(`  ${s.id}${s.name ? `  — ${s.name}` : ""}`);
   }
-  console.log(`\nNext:  tot checkout <tenant> --clone <dir>`);
+  console.log(`\nNext:  tot clone <tenant>`);
 }

package/src/commands/dev.mjs

@@ -138,7 +138,7 @@ export async function run(argv, ctx) {
     console.error(
       fail(
         "nothing to run — you're not inside a tenant checkout",
-        "tot checkout <tenant> --clone <dir>   (then `cd` in and re-run), pass --workspace <dir>, or try `tot dev --sample`",
+        "tot clone <tenant>   (then `cd` in and re-run), pass --workspace <dir>, or try `tot dev --sample`",
       ),
     );
     return 2;
@@ -194,7 +194,7 @@ async function runNativePublic(workspace, args, ctx) {
   const cfg = readWorkspaceConfig(workspace);
   if (!cfg) {
     throw new CliError(`${workspace} isn't a tenant checkout (no readable .tot/config.json)`, {
-      next: "tot checkout <tenant> --clone <dir>   (produces a runnable checkout)",
+      next: "tot clone <tenant>   (produces a runnable checkout)",
       exitCode: 2,
     });
   }
@@ -280,7 +280,7 @@ async function runNative(workspace, args, ctx) {
   const cfg = readWorkspaceConfig(workspace);
   if (!cfg) {
     throw new CliError(`${workspace} isn't a tenant checkout (no readable .tot/config.json)`, {
-      next: "tot checkout <tenant> --clone <dir>   (produces a runnable checkout)",
+      next: "tot clone <tenant>   (produces a runnable checkout)",
       exitCode: 2,
     });
   }
@@ -1240,7 +1240,7 @@ export function buildContainerPlan(workspace, args, _ctx) {
   const cfg = readWorkspaceConfig(workspace);
   if (!cfg) {
     throw new CliError(`${workspace} isn't a tenant checkout (no readable .tot/config.json)`, {
-      next: "tot checkout <tenant> --clone <dir>   (produces a runnable checkout)",
+      next: "tot clone <tenant>   (produces a runnable checkout)",
       exitCode: 2,
     });
   }

package/src/commands/doctor.mjs

@@ -1,7 +1,7 @@
 /**
  * `tot doctor` — is this machine ready to run the loop?
  *
- * Standalone (unlike the in-monorepo doctor): checks the things `tot checkout`
+ * Standalone (unlike the in-monorepo doctor): checks the things `tot clone`
  * and `tot dev`/`tot start` actually need — Node, git, an MCP URL, whether an
  * auth identity is available, and Docker — plus reports the detected context
  * so a developer knows which mode `tot` will use here.
@@ -187,7 +187,7 @@ export async function run(argv, ctx) {
   }
   console.log(
     failed === 0
-      ? "\n✔ Ready. Try: tot start   (checks out your store and runs it), or tot checkout\n"
+      ? "\n✔ Ready. Try: tot start   (checks out your store and runs it), or tot clone\n"
       : args.fix
         ? `\n✖ ${failed} check(s) still failing — see the exact next command(s) above, then re-run \`tot doctor\`.\n`
         : `\n✖ ${failed} check(s) failed — try \`tot doctor --fix\`, or fix the above, then re-run \`tot doctor\`.\n`,
@@ -199,5 +199,5 @@ function describeContext(ctx) {
   if (ctx.mode === "monorepo") return `storefront monorepo (${ctx.repoRoot})`;
   if (ctx.mode === "checkout")
     return `tenant checkout${ctx.tenant ? ` for "${ctx.tenant}"` : ""} (${ctx.workspacePath})`;
-  return "loose (not inside a checkout — `tot checkout <tenant> --clone <dir>` to get one)";
+  return "loose (not inside a checkout — `tot clone <tenant>` to get one)";
 }

package/src/commands/grants.mjs

@@ -26,7 +26,7 @@
 import { defaultCredentialsPath, readCredentials } from "../token-store.mjs";
 import { establishSession, AuthUnavailableError } from "../auth.mjs";
 import { createMcpClient } from "../mcp.mjs";
-import { storeListError, noStoresGuidance } from "./checkout.mjs";
+import { storeListError, noStoresGuidance } from "./clone.mjs";
 import { offerSignIn } from "./login.mjs";
 import { recordServerPolicy } from "../update-check.mjs";
 

package/src/commands/link.mjs

@@ -4,7 +4,7 @@
  *
  * Some developers sign in fine (a valid ToT OAuth session) but their identity
  * isn't yet linked to the broker that maps a person → the tenants they can build
- * on — so `tot start` / `tot checkout` / `tot whoami` resolve ZERO stores. That's
+ * on — so `tot start` / `tot clone` / `tot whoami` resolve ZERO stores. That's
  * NOT a "you weren't invited" problem and NOT "the invite is still propagating";
  * it's a one-time link step. This command drives it end-to-end from the terminal:
  *
@@ -24,7 +24,7 @@ import { establishSession, AuthUnavailableError } from "../auth.mjs";
 import { offerSignIn } from "./login.mjs";
 import { openBrowser } from "../open.mjs";
 import { CliError, fail, formatError } from "../errors.mjs";
-import { normalizeStores } from "./checkout.mjs";
+import { normalizeStores } from "./clone.mjs";
 
 const DEFAULT_MCP_URL = "https://mcp.tokenoftrust.com";
 
@@ -168,7 +168,7 @@ export async function run(argv, _ctx) {
       const stores = normalizeStores(list);
       if (stores.length) {
         console.log(`  stores you can build on: ${stores.map((s) => s.id).join(", ")}`);
-        console.log("  Next: `tot start` (or `tot checkout <tenant>`).");
+        console.log("  Next: `tot start` (or `tot clone <tenant>`).");
       } else {
         console.log("  Next: `tot start` — if it still shows no stores, ask your ToT contact for a store invite.");
       }

package/src/commands/login.mjs

@@ -4,7 +4,7 @@
  * Runs the MCP OAuth 2.1 PKCE loopback (the same ceremony `claude mcp add` runs):
  * opens the browser to the MCP's authorize page, the developer signs in with their
  * ToT identity + approves, and the loopback catches the code and exchanges it for a
- * token cached at ~/.tot/credentials.json. Every later command (`tot checkout`,
+ * token cached at ~/.tot/credentials.json. Every later command (`tot clone`,
  * `tot submit`, …) then runs as that developer with NO re-auth.
  *
  * The MCP defaults to the same target `tot submit` talks to (env MCP_BASE_URL /
@@ -109,7 +109,7 @@ const USAGE = `tot login — sign in to Token of Trust
   link a later \`tot feedback\` report to your invite + session) — not meant to be
   typed by hand.
 
-After signing in, run \`tot whoami\` to confirm, then \`tot checkout\` / \`tot submit\`.`;
+After signing in, run \`tot whoami\` to confirm, then \`tot clone\` / \`tot submit\`.`;
 
 /**
  * The core of `tot login`: run the OAuth ceremony (browser loopback, or the
@@ -270,7 +270,7 @@ export async function run(argv, _ctx) {
       cacheTraceId(env, args.traceId);
       cacheEmailHint(env, args.emailHint);
       console.log(`\n+ signed in. Session cached to ${defaultCredentialsPath(env)}.`);
-      console.log("  Next: `tot whoami` to confirm, or `tot checkout` / `tot submit` to build.");
+      console.log("  Next: `tot whoami` to confirm, or `tot clone` / `tot submit` to build.");
       return 0;
     } catch (e) {
       console.error(
@@ -288,7 +288,7 @@ export async function run(argv, _ctx) {
     await loginAndCache(mcpUrl, env, { log: (m) => console.error(m), device: args.device });
     cacheTraceId(env, args.traceId);
     console.log(`\n+ signed in. Session cached to ${defaultCredentialsPath(env)}.`);
-    console.log("  Next: `tot whoami` to confirm, or `tot checkout` / `tot submit` to build.");
+    console.log("  Next: `tot whoami` to confirm, or `tot clone` / `tot submit` to build.");
     return 0;
   } catch (e) {
     console.error(

package/src/commands/pr.mjs

@@ -0,0 +1,200 @@
+/**
+ * `tot pr` — see and manage the candidate PRs `tot submit` opens, mirroring
+ * `gh pr`.
+ *
+ *   tot pr [list]        list your OPEN candidate PRs for this store
+ *   tot pr view <N|id>   show one candidate (by PR number or changeId)
+ *   tot pr close <N|id>  close (reject) a candidate without merging
+ *
+ * A candidate PR is the reviewable unit `tot submit` creates. By default a
+ * re-submit UPDATES your open candidate; `tot submit --new` forks another. This
+ * command fills the gap the raw submit loop left — a first-party way to list your
+ * open candidates and to close one (candidate close was otherwise gated to
+ * version-control apps only).
+ *
+ * Runs from inside a tenant checkout (it derives the forge repo from the
+ * checkout's origin remote, exactly as `tot submit` does) and reads over the MCP
+ * `candidate_status` / `candidate_close` tools. Dependency-free (global fetch +
+ * `git`).
+ */
+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 {
+  defaultCandidateStatePath,
+  readActiveChangeId,
+  clearActiveChangeId,
+} from "../candidate-state.mjs";
+
+const DEFAULT_MCP_URL = "https://mcp.tokenoftrust.com";
+const SUBCOMMANDS = ["list", "view", "close"];
+
+const USAGE = `tot pr — see and manage your candidate PRs
+
+  tot pr [list]              list your open candidate PRs for this store
+  tot pr view <N|id>         show one candidate PR (by PR number or changeId)
+  tot pr close <N|id>        close (reject) a candidate PR without merging
+  tot pr close <N|id> --reason "<why>"   record why it was closed (audit note)
+  tot pr --mcp <url>         MCP base URL (default: env MCP_BASE_URL / TOT_MCP_URL)
+
+  A candidate PR is what \`tot submit\` opens for review. A re-submit updates your
+  open one by default; \`tot submit --new\` forks another. Use these to see and
+  manage them.`;
+
+/** Parse `tot pr` argv into { sub, target, reason, mcp, identity, help }. Pure. */
+export function parsePrArgs(argv) {
+  const a = { sub: null, target: null, reason: null, mcp: null, identity: null, help: false };
+  const positional = [];
+  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 === "--reason") a.reason = argv[++i];
+    else if (t === "--help" || t === "-h") a.help = true;
+    else positional.push(t);
+  }
+  a.sub = positional[0] || "list";
+  a.target = positional[1] ?? null;
+  return a;
+}
+
+/** Normalize the `candidate_status` list response to a flat candidate array. Pure. */
+export function extractCandidates(result) {
+  if (Array.isArray(result)) return result;
+  if (result && Array.isArray(result.candidates)) return result.candidates;
+  if (result && Array.isArray(result.environments)) return result.environments;
+  if (result && typeof result.changeId === "string") return [result];
+  return [];
+}
+
+/** Find a candidate by PR number (all-digits target) or exact changeId. Pure. */
+export function matchCandidate(candidates, target) {
+  if (target == null) return null;
+  if (/^\d+$/.test(target)) {
+    const n = Number(target);
+    return candidates.find((c) => c.prNumber === n) ?? null;
+  }
+  return candidates.find((c) => c.changeId === target) ?? null;
+}
+
+/** One-line candidate summary for `tot pr list`. */
+function line(c) {
+  const pr = typeof c.prNumber === "number" ? `#${c.prNumber}` : "#—";
+  const url = c.url ? `  ${c.url}` : "";
+  return `  PR ${pr}  ${c.changeId}  [${c.state ?? "?"}]${url}`;
+}
+
+/** @param {string[]} argv @param {any} ctx */
+export async function run(argv, ctx) {
+  const env = process.env;
+  const args = parsePrArgs(argv);
+  if (args.help) {
+    console.log(USAGE);
+    return 0;
+  }
+  if (!SUBCOMMANDS.includes(args.sub)) {
+    console.error(fail(`unknown subcommand: \`tot pr ${args.sub}\``, "tot pr list | view <N> | close <N>"));
+    return 2;
+  }
+  if (ctx.mode !== "checkout") {
+    console.error(
+      fail("`tot pr` runs from inside a tenant checkout", "tot clone <tenant> <dir>   (then `cd` in and re-run)"),
+    );
+    return 2;
+  }
+  if ((args.sub === "view" || args.sub === "close") && !args.target) {
+    console.error(fail(`\`tot pr ${args.sub}\` needs a PR number or changeId`, `tot pr ${args.sub} <N>`));
+    return 2;
+  }
+
+  const workspace = ctx.workspacePath;
+  const tenant = ctx.tenant;
+  const gitSafe = (cargs) => {
+    try {
+      return execFileSync("git", ["-C", workspace, ...cargs], { stdio: ["ignore", "pipe", "pipe"] }).toString();
+    } 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 scope = { mcpUrl: baseUrl, repo };
+  const client = createMcpClient(baseUrl);
+  try {
+    const session = await establishSession(client, { env, prefer: args.identity || undefined });
+    void session;
+    // Bind the active tenant so candidate_status/close read the right scope.
+    await client.callTool("client_switch", { tenant });
+
+    const candidates = extractCandidates(await client.callTool("candidate_status", { repo }));
+
+    if (args.sub === "list") {
+      if (!candidates.length) {
+        console.log(`No open candidate PRs for ${repo}. Run \`tot submit\` to open one.`);
+        return 0;
+      }
+      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" : ""));
+      }
+      return 0;
+    }
+
+    const match = matchCandidate(candidates, args.target);
+    if (!match) {
+      console.error(fail(`no open candidate matches "${args.target}"`, "tot pr list   (to see your open candidates)"));
+      return 1;
+    }
+
+    if (args.sub === "view") {
+      const active = readActiveChangeId(statePath, scope);
+      console.log(`PR ${typeof match.prNumber === "number" ? `#${match.prNumber}` : "#—"} — ${match.changeId}${match.changeId === active ? "  (active)" : ""}`);
+      console.log(`  state:            ${match.state ?? "?"}`);
+      if (match.branch) console.log(`  branch:           ${match.branch}`);
+      if (match.headSha) console.log(`  head:             ${match.headSha}`);
+      if (match.baseSha) console.log(`  base:             ${match.baseSha}`);
+      console.log(`  mergeable (forge): ${match.mergeable ?? "?"}`);
+      if (match.url) console.log(`  ${match.url}`);
+      return 0;
+    }
+
+    // close
+    await client.callTool("candidate_close", {
+      repo,
+      changeId: match.changeId,
+      ...(args.reason ? { reason: args.reason } : {}),
+    });
+    console.log(`✓ closed candidate ${match.changeId}${typeof match.prNumber === "number" ? ` (PR #${match.prNumber})` : ""}.`);
+    // If we just closed the remembered active candidate, forget it so the next
+    // plain `tot submit` starts a fresh one rather than resurrecting this handle.
+    if (readActiveChangeId(statePath, scope) === match.changeId) {
+      try {
+        clearActiveChangeId(statePath, scope);
+      } catch { /* best-effort */ }
+    }
+    return 0;
+  } catch (e) {
+    if (e instanceof AuthUnavailableError) {
+      console.error(fail("sign in to manage candidate PRs", e.hint || "run `tot login`, then re-run"));
+      return 1;
+    }
+    console.error(
+      fail(
+        `couldn't reach the candidate service: ${String(e?.message || e)}`,
+        "check your connection and that you're signed in, then re-run",
+      ),
+    );
+    return 1;
+  }
+}

package/src/commands/start.mjs

@@ -59,7 +59,7 @@ import { startProgress } from "../progress.mjs";
 import { defaultLastTenantPath, readLastTenant, writeLastTenant } from "../last-tenant.mjs";
 import { readCredentials, defaultCredentialsPath } from "../token-store.mjs";
 import { collectChecks } from "./doctor.mjs";
-import { normalizeStores, storeListError, checkoutTenant, noStoresGuidance } from "./checkout.mjs";
+import { normalizeStores, storeListError, checkoutTenant, noStoresGuidance } from "./clone.mjs";
 import {
   buildContainerPlan, spawnDevContainer, dockerAvailable, tryStartDocker,
   resolveDevImage, isPrivateRegistryImage, ensureRegistryLogin,
@@ -633,7 +633,7 @@ async function ensureCheckout(client, tenant, dir, env) {
       console.log(`  ✓ reusing existing checkout ./${tenant}`);
       return;
     }
-    throw new CliError(`./${tenant} already exists and isn't a tot checkout`, {
+    throw new CliError(`./${tenant} already exists and isn't a store checkout`, {
       next: `remove it (or run \`tot start\` from an empty directory)`,
       exitCode: 2,
     });

package/src/commands/submit.mjs

@@ -46,12 +46,19 @@ import { validateTenant, ERROR } from "../validate.mjs";
 import { openBrowser } from "../open.mjs";
 import { startProgress } from "../progress.mjs";
 import { fail } from "../errors.mjs";
+import {
+  defaultCandidateStatePath,
+  readActiveChangeId,
+  writeActiveChangeId,
+  mintFreshChangeId,
+  isTerminalCandidateState,
+} from "../candidate-state.mjs";
 
 const DEFAULT_MCP_URL = "https://mcp.tokenoftrust.com";
 const DEFAULT_REF = "preview";
 
 export function parseArgs(argv) {
-  const a = { mcp: null, identity: null, ref: DEFAULT_REF, skipValidate: false, noWait: false, watch: false, noOpen: false, message: null, summary: null, help: false };
+  const a = { mcp: null, identity: null, ref: DEFAULT_REF, skipValidate: false, noWait: false, watch: false, noOpen: false, 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];
@@ -63,6 +70,7 @@ export function parseArgs(argv) {
     else if (t === "--no-wait") a.noWait = true;
     else if (t === "--watch") a.watch = true;
     else if (t === "--no-open") a.noOpen = true;
+    else if (t === "--new") a.new = true;
     else if (t === "--help" || t === "-h") a.help = true;
   }
   return a;
@@ -71,6 +79,7 @@ export function parseArgs(argv) {
 const USAGE = `tot submit — submit your store for preview
 
   tot submit                    validate → push the preview ref → stream the result
+  tot submit --new              open a NEW candidate PR instead of updating your open one
   tot submit --watch            stay attached through reconcile + compliance + accept (long-poll)
   tot submit --skip-validate    push without the local lint (not recommended)
   tot submit --ref <name>       push ref (default: ${DEFAULT_REF})
@@ -80,6 +89,12 @@ const USAGE = `tot submit — submit your store for preview
   tot submit --no-open          don't open the preview URL in the browser on success
   tot submit --mcp <url>        MCP base URL (default: env MCP_BASE_URL / TOT_MCP_URL)
 
+  By default a re-submit UPDATES your open candidate PR (like pushing more commits
+  to a GitHub PR), rather than opening a new one each time. Use --new to fork a
+  fresh candidate PR; the next plain \`tot submit\` then updates THAT one. Manage your
+  open candidates with \`tot pr\` (list / view / close). If your candidate was already
+  merged or closed, a re-submit automatically opens a fresh one.
+
   If you omit -m, a summary is generated from git (commit subject + the diff vs
   what's live in preview) so the change record the approver reviews is never blank.`;
 
@@ -289,7 +304,7 @@ export async function run(argv, ctx) {
     console.error(
       fail(
         "`tot submit` runs from inside a tenant checkout",
-        "tot checkout <tenant> --clone <dir>   (then `cd` in, commit your work, and re-run)",
+        "tot clone <tenant> <dir>   (then `cd` in, commit your work, and re-run)",
       ),
     );
     return 2;
@@ -381,13 +396,40 @@ export async function run(argv, ctx) {
     // 2b. PR-backed candidate (g1b candidate_open, unit c1) — best-effort: a
     // failure here (older MCP, VC not configured, preview-access capability) is
     // reported and swallowed, never blocking the preview push that already landed.
-    await submitCandidate(client, {
-      repo: repoNameFromRemote(gitSafe(["remote", "get-url", "origin"]).trim()),
-      changeId: deriveChangeId(tenant, actorKeyFor(session)),
-      changeSummary,
-      patchEntries,
-      readBlob: (path) => execFileSync("git", ["-C", workspace, "show", `HEAD:${path}`], { stdio: ["ignore", "pipe", "pipe"] }),
-    });
+    //
+    // Which candidate this submit lands on (gh-pr-like):
+    //   --new           → fork a FRESH candidate and remember it as active;
+    //   otherwise       → the remembered active candidate (from a prior --new /
+    //                     roll), else the STABLE per-dev-per-tenant default.
+    // If the chosen candidate turns out to be merged/closed, roll to a fresh one
+    // so a re-submit is never wedged on a dead PR.
+    const repo = repoNameFromRemote(gitSafe(["remote", "get-url", "origin"]).trim());
+    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;
+    let changeId = args.new ? mintFreshChangeId(stableId) : (active || stableId);
+    // Persist when we diverge from the stable default (a --new fork, or a
+    // previously-remembered active pointer) so the next plain submit follows it.
+    let persist = args.new || (!!active && active !== stableId);
+
+    let candidate = await submitCandidate(client, { repo, changeId, changeSummary, patchEntries, readBlob });
+
+    if (candidate && isTerminalCandidateState(candidate.state)) {
+      const rolled = mintFreshChangeId(stableId);
+      console.log(`  ~ candidate ${changeId} is ${candidate.state} — opening a fresh candidate PR instead.`);
+      changeId = rolled;
+      persist = true;
+      candidate = await submitCandidate(client, { repo, changeId, changeSummary, patchEntries, readBlob });
+    }
+
+    // Remember the active candidate only on a real, non-terminal open (best-effort;
+    // never let a state-write failure break the submit).
+    if (persist && repo && candidate && !isTerminalCandidateState(candidate.state)) {
+      try {
+        writeActiveChangeId(statePath, { mcpUrl: baseUrl, repo, changeId });
+      } catch { /* best-effort local hint — a miss just re-derives the stable id */ }
+    }
 
     let status;
     if (args.noWait) {

package/src/commands/validate.mjs

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

package/src/commands/whoami.mjs

@@ -11,7 +11,7 @@
 import { defaultCredentialsPath, readCredentials, isExpired, activeProfile } from "../token-store.mjs";
 import { establishSession } from "../auth.mjs";
 import { createMcpClient } from "../mcp.mjs";
-import { normalizeStores, storeListError, noStoresGuidance } from "./checkout.mjs";
+import { normalizeStores, storeListError, noStoresGuidance } from "./clone.mjs";
 import { recordServerPolicy } from "../update-check.mjs";
 
 /**

package/src/context.mjs

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

package/src/obstacle-beacon.cjs

@@ -1,6 +1,6 @@
 /**
  * The obstacle beacon — a fire-and-forget POST that tells the hosted cockpit a
- * `tot start` / `tot checkout` failed, so it can show the exact fix in the bridge
+ * `tot start` / `tot clone` failed, so it can show the exact fix in the bridge
  * strip (obstacle lane, server side already shipped). Best-effort telemetry that
  * rides ALONGSIDE the house-style `✗ … → next:` error; it must NEVER change,
  * delay past its timeout, or fail that error path.