@tokenoftrust/cli 1.4.0 → 1.4.1

package/src/commands/sync.mjs

@@ -0,0 +1,203 @@
+/**
+ * `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";
+import { ensureTokenlessRemote } from "../git-credential.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 "";
+    }
+  };
+
+  // Self-heal a LEGACY checkout (unit u10, absorbs u7): `tot login` refreshes
+  // this CLI's own session, never the token baked into a checkout's remote at
+  // clone time — the exact reason a stale checkout's `git fetch origin` (below)
+  // used to 401 even right after signing back in. Best-effort, never blocks sync.
+  try {
+    ensureTokenlessRemote(git);
+  } catch {
+    /* best-effort — see above */
+  }
+
+  // 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

@@ -92,7 +92,12 @@ export function run(argv, ctx) {
 
   const errors = findings.filter((f) => f.level === ERROR);
   const warns = findings.filter((f) => f.level === WARN);
-  console.log(`\ntot validate — ${target.tenantId ?? target.dir}\n`);
+  // Never present the checkout PATH as if it were the tenant name — when the
+  // tenant couldn't be resolved (e.g. an invalid/missing .tot/config.json),
+  // the findings below say why; the header should say so too, not disguise
+  // a directory as a domain.
+  const label = target.tenantId ? target.tenantId : `(tenant unresolved) ${target.dir}`;
+  console.log(`\ntot validate — ${label}\n`);
   for (const f of findings) {
     const tag = f.level === ERROR ? "✗" : "⚠";
     console.log(`  ${tag} [${f.rule}] ${f.file}\n      ${f.message}${f.fix ? `\n      → ${f.fix}` : ""}`);

package/src/git-credential.mjs

@@ -0,0 +1,184 @@
+/**
+ * Shared plumbing for `tot` acting as a git credential helper (unit u10,
+ * workstream tot-merge-conflict-resolution-ux — absorbs u7's `tot fetch`
+ * self-heal idea) — so a checkout never needs a LIVE forge token baked into
+ * `.git/config`'s remote URL. `tot clone` configures a fresh checkout's
+ * `credential.helper` to `CREDENTIAL_HELPER` (git's own extension point for
+ * exactly this — see `git help gitcredentials`), which git then invokes with
+ * `get`/`store`/`erase` on every network operation instead of reading a
+ * persisted secret. This module holds the pieces BOTH the `git-credential`
+ * command (src/commands/git-credential.mjs, which mints fresh tokens via the
+ * MCP) and the self-heal migration (called at the top of every command that
+ * touches git — submit/sync/… — so ANY CLI touch of a legacy checkout
+ * migrates it) share: parsing/formatting git's credential protocol, the
+ * on-disk credential cache, and rewriting a checkout's remote to drop its
+ * embedded token.
+ *
+ * Dependency-free — node:fs/os/path/crypto only. The MCP mint itself (real
+ * network I/O) lives in the command layer, which this module never imports.
+ */
+import { homedir } from "node:os";
+import { createHash } from "node:crypto";
+import { join } from "node:path";
+import { readCredentials, writeCredentials } from "./token-store.mjs";
+
+/** The git config value that routes credential requests through `tot` — the
+ *  `!` tells git to run this as a shell command (git appends the operation,
+ *  e.g. `get`, as the final argument) — the same convention `gh auth
+ *  git-credential` uses. Repo-LOCAL only (never --global): a checkout not
+ *  built with `tot` must never have its credential resolution silently
+ *  redirected. */
+export const CREDENTIAL_HELPER = "!tot git-credential";
+
+/** How long a minted credential is trusted before `tot git-credential get`
+ *  mints a fresh one — comfortably under the forge push token's own
+ *  multi-hour expiry (see pushPreviewRef in submit.mjs), so a long-running
+ *  session still self-refreshes well before the cached one goes stale. */
+export const CREDENTIAL_TTL_MS = 20 * 60 * 1000;
+
+/**
+ * Split an authenticated forge remote URL (basic-auth `user:token@host`, as
+ * the MCP mints it via `tenant_checkout`) into its tokenless public URL +
+ * the embedded credential, so the token can be handed to git EPHEMERALLY for
+ * one operation instead of being persisted in `.git/config`. Returns null
+ * when the URL won't parse or carries no token — the caller then falls back
+ * to the checkout's existing remote. Pure — unit-tested.
+ * @param {string} remoteUrl
+ * @returns {{ publicUrl: string, username: string, token: string }|null}
+ */
+export function splitAuthedRemote(remoteUrl) {
+  try {
+    const u = new URL(String(remoteUrl));
+    const token = u.password ? decodeURIComponent(u.password) : "";
+    if (!token) return null;
+    const username = u.username ? decodeURIComponent(u.username) : "";
+    return { publicUrl: `${u.protocol}//${u.host}${u.pathname}`, username, token };
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * The `http.extraheader` value that hands a basic-auth credential to a
+ * SINGLE git invocation (base64 of `user:token`) — so a freshly-minted forge
+ * token authenticates one operation without ever being written to
+ * `.git/config`. Pure — unit-tested.
+ * @param {string} username
+ * @param {string} token
+ * @returns {string}
+ */
+export function basicAuthExtraHeader(username, token) {
+  const b64 = Buffer.from(`${username}:${token}`, "utf8").toString("base64");
+  return `Authorization: Basic ${b64}`;
+}
+
+/**
+ * Parse git's credential-helper protocol (key=value lines, terminated by a
+ * blank line or EOF) into a plain object. A malformed line is skipped rather
+ * than throwing — git's own helpers are lenient the same way. Pure.
+ * @param {string} text
+ * @returns {Record<string,string>}
+ */
+export function parseCredentialInput(text) {
+  const out = {};
+  for (const line of String(text).split("\n")) {
+    const trimmed = line.trim();
+    if (!trimmed) continue;
+    const i = trimmed.indexOf("=");
+    if (i <= 0) continue;
+    out[trimmed.slice(0, i)] = trimmed.slice(i + 1);
+  }
+  return out;
+}
+
+/**
+ * Format a credential response for git's `get` operation — only the fields
+ * present are emitted (git only needs `username`/`password` filled in;
+ * echoing `protocol`/`host` back is harmless and conventional). Pure.
+ * @param {Record<string,string|undefined|null>} fields
+ * @returns {string}
+ */
+export function formatCredentialOutput(fields) {
+  const lines = [];
+  for (const key of ["protocol", "host", "path", "username", "password"]) {
+    if (fields[key] !== undefined && fields[key] !== null) lines.push(`${key}=${fields[key]}`);
+  }
+  return `${lines.join("\n")}\n`;
+}
+
+/** A filesystem-safe, collision-resistant cache key for one (tenant, tag) —
+ *  hashed (not the raw tenant string) so an unusual tenant name can never
+ *  escape `~/.tot/git-credentials/` or collide across tags. Pure. */
+export function credentialCacheKey(tenant, tag) {
+  return createHash("sha256").update(`${tenant}|${tag}`).digest("hex").slice(0, 32);
+}
+
+/** Absolute path to one (tenant, tag)'s cached credential — same `~/.tot`
+ *  root (and `TOT_HOME` override) as the OAuth session cache. */
+export function credentialCachePath(tenant, tag, env = process.env) {
+  const home = env.TOT_HOME || homedir();
+  return join(home, ".tot", "git-credentials", `${credentialCacheKey(tenant, tag)}.json`);
+}
+
+/** Is a cached credential still trusted? A cache with no `mintedAt` is
+ *  treated as stale (mint fresh rather than trust an unknown age). Pure. */
+export function isFreshCredential(cred, { now = Date.now(), ttlMs = CREDENTIAL_TTL_MS } = {}) {
+  return Boolean(cred && cred.username && cred.password && cred.mintedAt && now - cred.mintedAt < ttlMs);
+}
+
+/** Read a cached credential (reusing token-store.mjs's generic reader), or
+ *  null if absent/unreadable/malformed/stale. Never throws. */
+export function readCachedCredential(filePath, opts = {}) {
+  const cred = readCredentials(filePath);
+  return isFreshCredential(cred, opts) ? cred : null;
+}
+
+/** Cache a freshly-minted credential — atomic write, owner-only permissions
+ *  (0600 in a 0700 dir, via token-store.mjs's writer): this file holds a LIVE
+ *  forge push token, same security bar as the OAuth session cache. */
+export function writeCachedCredential(filePath, { username, password }, { now = Date.now() } = {}) {
+  writeCredentials(filePath, { username, password, mintedAt: now });
+}
+
+/**
+ * Self-heal a LEGACY checkout: if `origin`'s remote still carries an
+ * embedded token (the pre-u10 `tot clone` shape, or one predating `tot
+ * login` entirely), strip it — rewriting the remote to the tokenless public
+ * URL — and install the credential helper so future git operations mint
+ * fresh creds through `tot` instead of relying on a token that silently
+ * expires. Meant to be called at the top of every command that touches git,
+ * best-effort (the caller decides how to handle a thrown error — this never
+ * blocks the actual command on a migration hiccup). A no-op on an
+ * already-migrated, tokenless, or non-http(s) (e.g. ssh) remote.
+ * @param {(cargs:string[])=>string} git  a `git -C <workspace>` runner
+ * @returns {{ migrated: boolean }}
+ */
+export function ensureTokenlessRemote(git) {
+  let remote;
+  try {
+    remote = git(["remote", "get-url", "origin"]).trim();
+  } catch {
+    return { migrated: false }; // no `origin` (or not a git repo) — nothing to migrate
+  }
+  let migrated = false;
+  try {
+    const u = new URL(remote);
+    if (u.password) {
+      git(["remote", "set-url", "origin", `${u.protocol}//${u.host}${u.pathname}`]);
+      migrated = true;
+    }
+  } catch {
+    return { migrated }; // not a parseable URL (e.g. an ssh remote) — leave it alone entirely
+  }
+  let helper = "";
+  try {
+    helper = git(["config", "--local", "--get", "credential.helper"]).trim();
+  } catch {
+    /* unset — falls through to configuring it below */
+  }
+  if (helper !== CREDENTIAL_HELPER) {
+    git(["config", "--local", "credential.helper", CREDENTIAL_HELPER]);
+    migrated = true;
+  }
+  return { migrated };
+}

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/plan.mjs

@@ -46,11 +46,12 @@ function targetLabel({ pr, changeId }) {
  * console output, no network, no prompting.
  *
  * @param {{
- *   action: "build"|"accept"|"ship"|"retire",
+ *   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",
@@ -59,6 +60,9 @@ function targetLabel({ pr, changeId }) {
  *   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)
  */
@@ -68,6 +72,7 @@ export function planForAction({
   pr = null,
   changeId = null,
   headSha = null,
+  integrationSha = null,
   endpoint = null,
   targets = {},
   context = "operator",
@@ -76,6 +81,9 @@ export function planForAction({
   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).
@@ -85,6 +93,7 @@ export function planForAction({
   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) {
@@ -140,6 +149,67 @@ export function planForAction({
       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;
@@ -148,12 +218,15 @@ export function planForAction({
   return lines;
 }
 
-/** "build" → "Build-on-demand", "accept" → "Accept", "ship" → "Ship", "retire" → "Retire". Pure. */
+/** "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";
 }
 

package/src/validate.mjs

@@ -27,6 +27,38 @@ function mk(level, rule, file, message, fix) {
   return { level, rule, file, message, fix };
 }
 
+// --- git conflict markers ----------------------------------------------------
+// A half-resolved merge/rebase can commit literal conflict markers into content
+// (the incident: `<<<<<<<`/`=======`/`>>>>>>>` in content/home.html slipped past
+// preview as "validated"). These are the default and diff3 marker lines, anchored
+// at line start and exactly 7 chars with a trailing boundary — precise enough that
+// real content never matches. `=======` / `|||||||` ALONE are NOT flagged (a lone
+// `=======` is a common markdown/prose horizontal rule); only the START (`<<<<<<<`)
+// and END (`>>>>>>>`) markers trigger — either one is a near-certain conflict, so
+// we err false-negative-averse and flag on either.
+const CONFLICT_START = /^<{7}(?=[ \t]|$)/;
+const CONFLICT_END = /^>{7}(?=[ \t]|$)/;
+
+/**
+ * Line numbers (1-based) of git conflict markers in `content`. Empty ⇒ none.
+ * Pure — exported for focused testing.
+ * @param {string} content
+ * @returns {number[]}
+ */
+export function detectConflictMarkers(content) {
+  if (typeof content !== "string" || (!content.includes("<<<<<<<") && !content.includes(">>>>>>>"))) return [];
+  const lines = content.split(/\r?\n/);
+  const hits = [];
+  for (let i = 0; i < lines.length; i++) {
+    if (CONFLICT_START.test(lines[i]) || CONFLICT_END.test(lines[i])) hits.push(i + 1);
+  }
+  return hits;
+}
+
+// Text artifacts a conflict marker can hide in (images/fonts live in public/, not scanned).
+const CONFLICT_SCAN_EXT = new Set([".html", ".htm", ".json", ".md", ".txt", ".css", ".js", ".mjs", ".svg", ".xml"]);
+const hasScanExt = (p) => CONFLICT_SCAN_EXT.has((p.match(/\.[^./\\]+$/) || [""])[0].toLowerCase());
+
 // --- canonical `.tot/config.json` shape (the #24/#25 regression guard) --------
 const KNOWN_KINDS = new Set(["file", "tree"]);
 const REQUIRED_WORKSPACES = ["content/", "public/", "theme.json"];
@@ -539,6 +571,26 @@ export function validateTenant(tenantDir, opts = {}) {
     }
   }
 
+  // 5. git conflict markers — advisory (never blocks), but LOUD: a half-resolved
+  // merge/rebase must not slip past as "validated". Scans text artifacts under
+  // content/ plus the root config files.
+  const conflictScanFiles = [
+    ...walk(contentDir, hasScanExt),
+    ...["theme.json", "capabilities.json", "scripts.json", join(".tot", "config.json")]
+      .map((f) => join(tenantDir, f))
+      .filter((p) => existsSync(p)),
+  ];
+  for (const p of conflictScanFiles) {
+    const lines = detectConflictMarkers(readFileSync(p, "utf8"));
+    if (lines.length) {
+      findings.push(
+        mk(WARN, "git-conflict-markers", rel(p),
+          `git conflict markers at line(s) ${lines.join(", ")} — looks like an unfinished merge/rebase (the page would still build/serve broken)`,
+          "resolve the conflict and remove the <<<<<<< / ======= / >>>>>>> lines before submitting"),
+      );
+    }
+  }
+
   const ok = !findings.some((f) => f.level === ERROR);
   return { ok, findings };
 }