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

package/src/commands/sync.mjs

@@ -0,0 +1,192 @@
+/**
+ * `tot sync` — the common candidate CONFLICT-RECOVERY path (branch-lifecycle
+ * contract, docs/architecture/branch-lifecycle-and-integration-preview.md,
+ * "Two developers touch the same file" / P1 item 12):
+ *
+ *   Both candidate previews may be green in isolation. After the first
+ *   integrates, the second may become conflicted. The queue blocks that PR
+ *   and prints the conflicting paths. The second developer syncs from
+ *   `preview`, resolves locally, reruns `tot preview`, and obtains evidence
+ *   for the new head. Prior approval is stale and must not carry forward
+ *   automatically.
+ *
+ * `tot sync` fetches the protected `preview` branch and MERGES it into the
+ * developer's current local branch — this repo's own canonical policy for
+ * bringing a protected line into a working branch (see playbook/merge.md:
+ * `git fetch` + `git merge --no-edit`, never a history-rewriting rebase of
+ * shared history). It never writes `preview`/`main` (fetch is read-only on
+ * the remote), never force-pushes anything, and never runs `git add -A` — on
+ * a conflict it stops immediately and leaves the merge in progress so the
+ * developer resolves it the normal git way (`git add <file>` + `git commit`,
+ * or `git merge --abort` to back out).
+ *
+ * Distinct from `tot preview`/`tot accept`: sync touches ONLY the developer's
+ * own local branch. It never pushes, never opens/updates a candidate, and
+ * never touches the shared `preview` aggregate or live. A successful sync
+ * moves local HEAD, which makes any prior preview/approval stale by
+ * definition (they were evidence for the OLD head) — so this always closes
+ * by pointing the developer at a fresh `tot preview`.
+ *
+ * Dependency-free (global `git`, no MCP/network beyond `git fetch`).
+ */
+import { execFileSync } from "node:child_process";
+import { fail } from "../errors.mjs";
+
+/** The protected branch `tot sync` fetches + merges from by default. */
+export const DEFAULT_SYNC_BRANCH = "preview";
+
+const USAGE = `tot sync — fetch \`preview\` and merge it into your local branch
+
+  tot sync                    fetch origin/${DEFAULT_SYNC_BRANCH} and merge it into your current branch
+  tot sync --branch <name>    sync against a different protected branch (default: ${DEFAULT_SYNC_BRANCH})
+  tot sync --help             show this help
+
+  The common conflict-recovery path: after another candidate integrates first,
+  yours may conflict on \`tot accept\`. \`tot sync\` fetches the protected
+  \`${DEFAULT_SYNC_BRANCH}\` branch and merges it into your local branch so you can resolve the
+  conflict locally, THEN re-run \`tot preview\` for a fresh candidate head.
+
+  On a conflict, sync stops SAFELY: it prints the conflicting paths and leaves
+  the merge in progress for you to resolve by hand — it never force-pushes
+  \`${DEFAULT_SYNC_BRANCH}\`/main and never runs \`git add -A\`.
+
+  A successful sync moves your local HEAD, so any prior preview/approval — it
+  was evidence for the OLD head — is now stale. Re-run \`tot preview\` before
+  your next \`tot accept\`.`;
+
+/** Parse `tot sync` argv. Pure — unit-testable. */
+export function parseArgs(argv) {
+  const a = { branch: null, help: false };
+  for (let i = 0; i < argv.length; i++) {
+    const t = argv[i];
+    if (t === "--branch") a.branch = argv[++i];
+    else if (t === "--help" || t === "-h") a.help = true;
+  }
+  return a;
+}
+
+/** Unmerged (conflicting) paths from `git diff --name-only --diff-filter=U`.
+ *  Pure — unit-tested without git. */
+export function parseConflictPaths(text) {
+  return String(text)
+    .split("\n")
+    .map((l) => l.trim())
+    .filter(Boolean);
+}
+
+/**
+ * Fetch `origin/<branch>` and merge it into the current branch. Never throws
+ * for an ordinary merge conflict — git's own nonzero exit on `merge` IS the
+ * conflict signal, and we turn it into a `"conflict"` result with the
+ * conflicting paths; a merge failure that ISN'T an ordinary conflict (no
+ * unmerged paths found) rethrows so the caller reports the real failure
+ * instead of a misleading "conflict".
+ *
+ * @param {(cargs:string[]) => string} git  a THROWING `git -C <workspace>` runner
+ *   (execFileSync-backed) — throws carry `.stderr`/`.message` like execFileSync.
+ * @param {{ branch?: string }} [opts]
+ * @returns {{ state: "up-to-date" } | { state: "synced", sha: string } | { state: "conflict", paths: string[] }}
+ */
+export function syncWithBranch(git, { branch = DEFAULT_SYNC_BRANCH } = {}) {
+  git(["fetch", "origin", branch]);
+
+  // How many commits on origin/<branch> the local branch is missing. 0 means
+  // local HEAD already contains everything from the protected branch —
+  // nothing to merge, regardless of how far ahead the local branch itself is.
+  const ahead = git(["rev-list", "--count", `HEAD..origin/${branch}`]).trim();
+  if (ahead === "0") return { state: "up-to-date" };
+
+  try {
+    git(["merge", "--no-edit", `origin/${branch}`]);
+  } catch (e) {
+    const paths = parseConflictPaths(git(["diff", "--name-only", "--diff-filter=U"]));
+    if (paths.length === 0) throw e; // not an ordinary conflict — surface the real failure
+    return { state: "conflict", paths };
+  }
+  const sha = git(["rev-parse", "HEAD"]).trim();
+  return { state: "synced", sha };
+}
+
+/** Render a `syncWithBranch` result in house style; returns the process exit
+ *  code. Pure given its inputs. */
+export function reportSync(result, { branch }) {
+  if (result.state === "up-to-date") {
+    console.log(`\n  ✓ already in sync with origin/${branch} — nothing to merge.`);
+    return 0;
+  }
+  if (result.state === "synced") {
+    console.log(`\n  ✓ synced with origin/${branch} — new HEAD ${result.sha.slice(0, 9)}.`);
+    console.log(`  → next: any prior preview/approval was evidence for the OLD head and is now stale.`);
+    console.log(`    re-run \`tot preview\` to get a fresh candidate + evidence for this head.`);
+    return 0;
+  }
+  // conflict — stop safely; the merge is left in progress for the developer.
+  console.error(fail(`sync conflicts with origin/${branch} — ${result.paths.length} file(s)`) + "\n");
+  for (const p of result.paths) console.error(`  ✗ conflict: ${p}`);
+  console.error(`\n  → next: resolve each conflict above, then \`git add <file>\` and \`git commit\` to finish the merge`);
+  console.error(`    (or \`git merge --abort\` to back out). Once resolved, re-run \`tot preview\` for a fresh candidate.`);
+  return 1;
+}
+
+/**
+ * @param {string[]} argv
+ * @param {any} ctx
+ */
+export async function run(argv, ctx) {
+  const args = parseArgs(argv);
+  if (args.help) {
+    console.log(USAGE);
+    return 0;
+  }
+  if (ctx.mode !== "checkout") {
+    console.error(
+      fail(
+        "`tot sync` runs from inside a tenant checkout",
+        "tot clone <tenant> <dir>   (then `cd` in, and re-run)",
+      ),
+    );
+    return 2;
+  }
+
+  const workspace = ctx.workspacePath;
+  const branch = (args.branch || DEFAULT_SYNC_BRANCH).trim();
+  const git = (cargs) => execFileSync("git", ["-C", workspace, ...cargs], { stdio: ["ignore", "pipe", "pipe"] }).toString();
+  const gitSafe = (cargs) => {
+    try {
+      return git(cargs);
+    } catch {
+      return "";
+    }
+  };
+
+  // Refuse a dirty tree up front — a merge on top of uncommitted edits is how
+  // local work gets silently entangled with the merge, and we never sweep
+  // anything in with `git add -A`. Commit or stash first, then re-run.
+  const status = gitSafe(["status", "--porcelain", "--untracked-files=all"]);
+  if (status.trim()) {
+    console.error(
+      fail(
+        "your working tree has uncommitted changes",
+        "commit them, or `git stash --include-untracked`, then re-run `tot sync`",
+      ) + "\n",
+    );
+    for (const line of status.trim().split("\n")) console.error(`  ${line}`);
+    return 2;
+  }
+
+  console.error(`~ fetching origin/${branch}…`);
+  let result;
+  try {
+    result = syncWithBranch(git, { branch });
+  } catch (e) {
+    console.error(
+      fail(
+        `sync failed: ${String(e.stderr || e.message || e)}`,
+        "check your network / that the checkout's remote is reachable, then re-run",
+      ),
+    );
+    return 1;
+  }
+
+  return reportSync(result, { branch });
+}

package/src/commands/validate.mjs

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

package/src/commands/whoami.mjs

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

package/src/context.mjs

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

package/src/no-gitea-links.test.mjs

@@ -0,0 +1,55 @@
+// Regression guard: the `tot` CLI must never print/reference a raw Gitea
+// forge URL to a developer's terminal. Gitea's API returns `html_url` when a
+// PR is opened (e.g. `https://git.tokenoftrust.com/storefront/<repo>/pulls/<n>`)
+// -- the CLI must surface the storefront-owned `/preview/<tenant>/pr/<n>` link
+// instead (see apps/storefront's matching noGiteaLinks.test.ts and its header
+// for the full architecture reasoning: apps/CLI never expose the forge
+// directly, the MCP proxies every read/write). Precipitating incident
+// (2026-08-18): a raw git.tokenoftrust.com PR URL reached an owner reviewing
+// tokenoftrust.com. Test fixtures are exempt (they legitimately mock a Gitea
+// URL to test the forge client), everything else in `src` must stay clean.
+import { readdirSync, readFileSync, statSync } from "node:fs";
+import { join, relative, dirname } from "node:path";
+import { fileURLToPath } from "node:url";
+import { test } from "node:test";
+import assert from "node:assert/strict";
+
+const SELF = fileURLToPath(import.meta.url);
+const SRC_ROOT = dirname(SELF);
+
+const TEST_FILE_RE = /\.test\.[cm]?js$/;
+const FORGE_HOST_RE = /\bgit\.tokenoftrust\.com\b/i;
+const SKIP_DIRS = new Set(["node_modules", "dist", ".git"]);
+
+function walk(dir, out = []) {
+  for (const entry of readdirSync(dir)) {
+    if (SKIP_DIRS.has(entry)) continue;
+    const full = join(dir, entry);
+    const st = statSync(full);
+    if (st.isDirectory()) {
+      walk(full, out);
+    } else if (/\.[cm]?js$/.test(entry)) {
+      out.push(full);
+    }
+  }
+  return out;
+}
+
+test("no Gitea forge links in the CLI source outside test fixtures", () => {
+  const offenders = [];
+  for (const file of walk(SRC_ROOT)) {
+    if (TEST_FILE_RE.test(file)) continue;
+    if (file === SELF) continue;
+    const content = readFileSync(file, "utf8");
+    content.split("\n").forEach((line, i) => {
+      if (FORGE_HOST_RE.test(line)) {
+        offenders.push(`${relative(SRC_ROOT, file)}:${i + 1}: ${line.trim()}`);
+      }
+    });
+  }
+  assert.deepEqual(
+    offenders,
+    [],
+    `Found Gitea forge links in non-test CLI source:\n${offenders.join("\n")}`,
+  );
+});

package/src/oauth.mjs

@@ -84,8 +84,15 @@ export async function registerClient(
     headers: { "Content-Type": "application/json", Accept: "application/json" },
     body: JSON.stringify({
       client_name: CLIENT_NAME,
+      // Include the device-code grant: the browserless rendezvous + B3 device flows
+      // redeem their device_code at /oauth/token with this grant, so a client
+      // registered WITHOUT it gets "unauthorized_client: grant_type is invalid".
+      grant_types: [
+        "authorization_code",
+        "refresh_token",
+        "urn:ietf:params:oauth:grant-type:device_code",
+      ],
       redirect_uris: [redirectUri],
-      grant_types: ["authorization_code", "refresh_token"],
       response_types: ["code"],
       token_endpoint_auth_method: "none",
       scope: SCOPE,
@@ -355,7 +362,6 @@ export async function attachRendezvous(attachEndpoint, { rendezvousCode, clientI
  */
 export async function rendezvousLoginFlow({
   mcpUrl,
-  clientId,
   code,
   fetchImpl = fetch,
   log = () => {},
@@ -363,7 +369,12 @@ export async function rendezvousLoginFlow({
   now = () => Date.now(),
 }) {
   const meta = await discoverMetadata(mcpUrl, fetchImpl);
-  const resolvedClientId = clientId || (await registerClient(meta.registration_endpoint, LOOPBACK_REDIRECT, fetchImpl));
+  // Always register a FRESH client for a rendezvous sign-in — do NOT reuse a cached
+  // clientId. A client cached by an older CLI build was registered without the
+  // device-code grant, so /oauth/token would reject the device grant with
+  // "unauthorized_client". Registration is cheap and a rendezvous has no consent
+  // screen to re-trigger (unlike the loopback/device flows, which reuse the cache).
+  const resolvedClientId = await registerClient(meta.registration_endpoint, LOOPBACK_REDIRECT, fetchImpl);
   const { verifier, challenge } = generatePkce();
 
   const attach = await attachRendezvous(

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.

package/src/plan.mjs

@@ -0,0 +1,262 @@
+/**
+ * The shared "operation plan" affordance (unit U10) — the load-bearing
+ * cross-cutting requirement from decision `operator-verb-and-hosting-model`:
+ * every MUTATING operator verb (build / accept / ship / retire) must STATE
+ * EXACTLY what it will do — which PR is queued/integrated/deployed, which
+ * deploy targets (preview / live) are touched, and their URLs — and get an
+ * explicit confirm before acting. (`accept` now queue-integrates a PR into the
+ * `preview` aggregate — unit b08 — rather than merging it to main.) No silent multi-step mutations, in either surface (the CLI
+ * here, and `AdminPublishTab.astro`'s confirm dialog, which renders the same
+ * shape of plan text server-side/inline).
+ *
+ * `planForAction` is PURE (no I/O, no prompt) so it's trivially unit-tested
+ * and reusable anywhere a plan needs to be rendered (CLI stdout, an admin
+ * confirm() dialog, a future dry-run flag). `printPlanAndConfirm` is the CLI
+ * half — print the plan, then gate on an explicit yes (reusing `prompt.mjs`'s
+ * TTY-safe `promptYesNo`; a non-TTY without `--yes` never silently proceeds).
+ *
+ * SHIP has ONE meaning (unit b10 — supersedes the retired context-dependent
+ * ship, decision `ship-context-dependent-semantics`): it publishes the
+ * tenant's CURRENT GREEN AGGREGATE — the batch of PRs that integrated
+ * cleanly — to live. No merge, no PR/candidate targeting, no developer-vs-
+ * operator branching. The plan states the pinned aggregate sha, its
+ * content-addressed artifact digest, every included PR, the rollback target,
+ * and the go-live paywall verdict, so the human reviews EXACTLY what "green"
+ * means before confirming.
+ *
+ * Dependency-free (no imports besides the sibling `prompt.mjs`).
+ */
+import { isInteractive, promptYesNo } from "./prompt.mjs";
+
+/**
+ * A human-readable label for the thing an action targets: "PR #N" when a PR
+ * number is known, else the change id, else a neutral fallback. Pure.
+ * @param {{ pr?: number|string|null, changeId?: string|null }} p
+ * @returns {string}
+ */
+function targetLabel({ pr, changeId }) {
+  if (pr != null && `${pr}`.trim()) return `PR #${pr}`;
+  if (changeId) return changeId;
+  return "this change";
+}
+
+/**
+ * Build the EXACT plan for a mutating operator verb — structured lines ready
+ * to print verbatim (CLI) or join for a confirm() dialog (admin). Pure: no
+ * console output, no network, no prompting.
+ *
+ * @param {{
+ *   action: "build"|"accept"|"ship"|"retire"|"revert"|"cleanup"|"hotfix",
+ *   tenant: string,
+ *   pr?: number|string|null,
+ *   changeId?: string|null,
+ *   headSha?: string|null,
+ *   integrationSha?: string|null,
+ *   endpoint?: string|null,
+ *   targets?: { preview?: string|null, live?: string|null },
+ *   context?: "developer"|"operator",
+ *   pinnedSha?: string|null,
+ *   artifactDigest?: string|null,
+ *   includedPrs?: Array<{ prNumber?: number|null, changeId?: string|null, headSha?: string|null }>,
+ *   rollbackTarget?: { receiptId: string, aggregateSha: string } | null,
+ *   paywall?: { allowed: boolean, message?: string|null } | null,
+ *   refs?: Array<{ ref: string, sha?: string|null, reason?: string|null }>,
+ *   bypassedPrs?: Array<{ prNumber?: number|null, changeId?: string|null, headSha?: string|null }>,
+ *   bypassedPreviewSha?: string|null,
+ * }} params
+ * @returns {string[]} plan lines (no leading/trailing blank line)
+ */
+export function planForAction({
+  action,
+  tenant,
+  pr = null,
+  changeId = null,
+  headSha = null,
+  integrationSha = null,
+  endpoint = null,
+  targets = {},
+  context = "operator",
+  pinnedSha = null,
+  artifactDigest = null,
+  includedPrs = null,
+  rollbackTarget = null,
+  paywall = null,
+  refs = null,
+  bypassedPrs = null,
+  bypassedPreviewSha = null,
+}) {
+  void context; // retained param — no action currently branches on it (ship, the
+  // last one that did, is now ONE meaning; kept so a future action can opt in).
+  const label = targetLabel({ pr, changeId });
+  const lines = [`${titleFor(action)} plan:`];
+  if (tenant) lines.push(`  tenant:    ${tenant}`);
+  if (pr != null && `${pr}`.trim()) lines.push(`  PR:        #${pr}`);
+  if (changeId) lines.push(`  change id: ${changeId}`);
+  if (headSha) lines.push(`  head sha:  ${headSha}`);
+  if (integrationSha) lines.push(`  integration sha: ${integrationSha}`);
+  if (endpoint) lines.push(`  endpoint:  POST ${endpoint}`);
+
+  switch (action) {
+    case "build": {
+      lines.push(
+        `  effect:    materialize ${label}'s candidate preview — NO merge, NO go-live, NO channel flip.`,
+      );
+      if (targets.preview) lines.push(`  viewable:  ${targets.preview}`);
+      break;
+    }
+    case "accept": {
+      // Accept now means QUEUE-INTEGRATE-INTO-PREVIEW (unit b08), NOT merge-to-main:
+      // the candidate lands in the protected `preview` aggregate (serialized merge →
+      // rebuild → combined-evidence gate), and the aggregate goes live only later via
+      // `tot ship`. So the plan states the integration, never a merge or a go-live.
+      const into = tenant ? `${tenant}'s preview aggregate` : "the preview aggregate";
+      lines.push(
+        `  effect:    queue ${label} for integration into ${into} — NO merge to main, NO go-live.`,
+      );
+      break;
+    }
+    case "ship": {
+      // ONE meaning (b10): publish the tenant's CURRENT GREEN AGGREGATE to live.
+      // No merge — b09's orchestrator ships the already-materialized, already-
+      // reviewed digest. State exactly WHAT that is: the pinned sha, the
+      // content-addressed artifact digest, every included PR, the rollback
+      // target, and the go-live paywall verdict — so the human reviews the
+      // real content of "green" before confirming.
+      lines.push(
+        `  effect:    publish the current green aggregate to live${targets.live ? ` (${targets.live})` : ""} — no merge.`,
+      );
+      if (pinnedSha) lines.push(`  pinned sha:      ${pinnedSha}`);
+      if (artifactDigest) lines.push(`  artifact digest: ${artifactDigest}`);
+      if (Array.isArray(includedPrs)) {
+        lines.push(`  included PRs (${includedPrs.length}):`);
+        for (const p of includedPrs) {
+          const prLabel = p && p.prNumber != null ? `#${p.prNumber}` : p?.changeId || "(no PR)";
+          const shortSha = p && p.headSha ? ` ${String(p.headSha).slice(0, 8)}` : "";
+          lines.push(`    - ${prLabel}${shortSha}`);
+        }
+      }
+      lines.push(
+        rollbackTarget
+          ? `  rollback to: ${rollbackTarget.aggregateSha} (receipt ${rollbackTarget.receiptId})`
+          : "  rollback to: (none — first-ever ship)",
+      );
+      if (paywall && paywall.allowed === false) {
+        lines.push(`  ⚠ paywall:   ${paywall.message || "go-live is blocked by the storefront subscription gate"}`);
+      }
+      break;
+    }
+    case "retire": {
+      lines.push(`  effect:    evict ${label}'s preview environment + version (rebuildable).`);
+      break;
+    }
+    case "cleanup": {
+      // Branch GC (P1 items 9/10): delete ONLY the exact terminal refs a fresh
+      // server-side classification (candidate_list) marked eligible — never by
+      // age alone, never main/preview, never an orphan. State the exact set so
+      // the human confirms precisely what will be removed, not "some branches".
+      const list = Array.isArray(refs) ? refs : [];
+      lines.push(
+        `  effect:    delete ${list.length} terminal candidate branch(es) — never main/preview, ` +
+          "never by age alone, never a quarantined orphan.",
+      );
+      for (const r of list) {
+        const shortSha = r?.sha ? ` ${String(r.sha).slice(0, 8)}` : "";
+        lines.push(`    - ${r?.ref}${shortSha}${r?.reason ? `  — ${r.reason}` : ""}`);
+      }
+      break;
+    }
+    case "revert": {
+      // Revert (b21): REMOVE already-integrated content from the protected `preview`
+      // aggregate by creating a NEW auditable revert commit — never a force-reset,
+      // never a branch delete. The aggregate rebuilds and ships only when green
+      // again. State exactly that: preview-only, a new commit, NO touch to main.
+      const from = tenant ? `${tenant}'s preview aggregate` : "the preview aggregate";
+      const what = integrationSha ? `integration ${integrationSha}` : label;
+      lines.push(
+        `  effect:    revert ${what} out of ${from} — a NEW revert commit, NO force-reset, NO merge to main, NO go-live.`,
+      );
+      break;
+    }
+    case "hotfix": {
+      // Hotfix (b22): the EXPLICIT EXCEPTION lane. Release the reviewed fix from
+      // `main` to live, EXCLUDING the unshipped `preview` work — then automatically
+      // forward-integrate `main` into `preview` and re-validate. State exactly that,
+      // and — critically — list the unshipped preview work this deliberately BYPASSES,
+      // so the human confirms an unmistakable exception, not an ordinary ship.
+      lines.push(
+        `  effect:    OWNER HOTFIX — release ${label} from main to live${targets.live ? ` (${targets.live})` : ""}, ` +
+          `EXCLUDING the unshipped preview head, then forward-integrate main → preview + revalidate.`,
+      );
+      if (Array.isArray(bypassedPrs)) {
+        if (bypassedPrs.length === 0) {
+          lines.push("  bypasses:  (nothing — preview has no unshipped work)");
+        } else {
+          lines.push(`  ⚠ BYPASSES the unshipped preview work (${bypassedPrs.length}) — NOT included in this hotfix:`);
+          for (const p of bypassedPrs) {
+            const prLabel = p && p.prNumber != null ? `#${p.prNumber}` : p?.changeId || "(no PR)";
+            const shortSha = p && p.headSha ? ` ${String(p.headSha).slice(0, 8)}` : "";
+            lines.push(`    - ${prLabel}${shortSha}`);
+          }
+        }
+      }
+      if (bypassedPreviewSha) lines.push(`  preview head (bypassed): ${bypassedPreviewSha}`);
+      lines.push(
+        rollbackTarget
+          ? `  rollback to: ${rollbackTarget.aggregateSha} (receipt ${rollbackTarget.receiptId})`
+          : "  rollback to: (none — first-ever ship)",
+      );
+      if (paywall && paywall.allowed === false) {
+        lines.push(`  ⚠ paywall:   ${paywall.message || "go-live is blocked by the storefront subscription gate"}`);
+      }
+      break;
+    }
+    default: {
+      lines.push(`  effect:    ${action} ${label}.`);
+      break;
+    }
+  }
+  return lines;
+}
+
+/** "build" → "Build-on-demand", "accept" → "Accept", … "hotfix" → "Hotfix". Pure. */
+function titleFor(action) {
+  if (action === "build") return "Build-on-demand";
+  if (action === "accept") return "Accept";
+  if (action === "ship") return "Ship";
+  if (action === "retire") return "Retire";
+  if (action === "revert") return "Revert";
+  if (action === "cleanup") return "Cleanup";
+  if (action === "hotfix") return "Hotfix (owner-only exception lane)";
+  return action ? action[0].toUpperCase() + action.slice(1) : "Operation";
+}
+
+/**
+ * Print a plan and gate on an explicit confirm — the CLI half of the shared
+ * affordance. Prints every line, a trailing blank line, then:
+ *
+ *   - `yes: true` → confirmed immediately, no prompt (the verb's `--yes`).
+ *   - a non-TTY (CI, piped) → refuses without prompting (never silently acts).
+ *   - otherwise → asks `question` via `promptYesNo` (default NO unless the
+ *     caller opts in with `defaultYes`).
+ *
+ * Returns a reason alongside the boolean so the caller can render its own
+ * house-style refusal/abort message (verbs differ: "nothing was built" vs
+ * "nothing shipped" etc.) — this helper only owns the plan + the gate.
+ *
+ * @param {string[]} planLines
+ * @param {{ yes?: boolean, question?: string, defaultYes?: boolean }} [opts]
+ * @returns {Promise<{ confirmed: boolean, reason: "yes-flag"|"confirmed"|"declined"|"non-tty" }>}
+ */
+export async function printPlanAndConfirm(planLines, { yes = false, question = "Proceed?", defaultYes = false } = {}) {
+  for (const line of planLines) console.log(line);
+  console.log("");
+
+  if (yes) return { confirmed: true, reason: "yes-flag" };
+
+  if (!isInteractive()) {
+    return { confirmed: false, reason: "non-tty" };
+  }
+
+  const ok = await promptYesNo(question, defaultYes);
+  return { confirmed: ok, reason: ok ? "confirmed" : "declined" };
+}

package/src/sample.mjs

@@ -26,7 +26,7 @@
  * Dependency-free (node:fs + node:path only).
  */
 import {
-  cpSync, existsSync, mkdirSync, readdirSync, readFileSync, statSync, writeFileSync,
+  appendFileSync, cpSync, existsSync, mkdirSync, readdirSync, readFileSync, statSync, writeFileSync,
 } from "node:fs";
 import { homedir } from "node:os";
 import { fileURLToPath } from "node:url";
@@ -41,6 +41,11 @@ const here = dirname(fileURLToPath(import.meta.url)); // packages/cli/src
  * version-manager shell hooks land on a supported Node just by cd-ing into
  * their store, and a plain `nvm use` works with no argument. Best-effort:
  * never fails the checkout.
+ *
+ * When `dir` is a git working copy (true for `tot clone`, not for the
+ * non-git sample scaffold), the dropped file is also excluded LOCALLY
+ * (`.git/info/exclude`) so it doesn't leave a fresh `tot clone` dirty —
+ * `git status` right after cloning must read clean. See `excludeLocally`.
  * @param {string} dir @param {NodeJS.ProcessEnv} [env]
  */
 export function writeNvmrc(dir, env = process.env) {
@@ -48,11 +53,32 @@ export function writeNvmrc(dir, env = process.env) {
     const p = join(dir, ".nvmrc");
     if (existsSync(p)) return; // the store repo's own pin wins
     writeFileSync(p, pickNvmrcVersion(env) + "\n");
+    excludeLocally(dir, ".nvmrc");
   } catch {
     /* a missing .nvmrc never blocks the loop */
   }
 }
 
+/**
+ * Add `pattern` to `<dir>/.git/info/exclude` — a LOCAL-only ignore list that
+ * never touches the repo's own committed `.gitignore` (so we don't mutate a
+ * tenant's tracked files just to keep our own convenience drop-in out of
+ * their way). No-op when `dir` isn't a git working copy, or `pattern` is
+ * already excluded (a repeat `tot clone` into the same dir, or the repo's
+ * own `.gitignore` already covering it — appending again would just be
+ * redundant, not wrong). Best-effort: never throws past its caller's `try`.
+ * @param {string} dir @param {string} pattern
+ */
+function excludeLocally(dir, pattern) {
+  const gitDir = join(dir, ".git");
+  if (!existsSync(gitDir) || !statSync(gitDir).isDirectory()) return; // no .git, or a submodule-style .git FILE — skip
+  const excludePath = join(gitDir, "info", "exclude");
+  const existing = existsSync(excludePath) ? readFileSync(excludePath, "utf8") : "";
+  if (existing.split("\n").some((l) => l.trim() === pattern)) return; // already excluded
+  mkdirSync(join(gitDir, "info"), { recursive: true });
+  appendFileSync(excludePath, (existing && !existing.endsWith("\n") ? "\n" : "") + pattern + "\n");
+}
+
 /**
  * The version `.nvmrc` should pin: the NEWEST Node the developer ALREADY has
  * installed under nvm that meets the floor — so `nvm use` succeeds with zero