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

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.
@@ -103,9 +103,9 @@ function beacon(opts, done) {
 
 /** Promise wrapper for the ESM side (src/obstacle.mjs) so a failure path can await delivery. */
 function beaconAsync(opts) {
-  return new Promise(function (resolve) {
+  return /** @type {Promise<void>} */ (new Promise(function (resolve) {
     try { beacon(opts, resolve); } catch (e) { resolve(); }
-  });
+  }));
 }
 
 module.exports = { parseActivityArgs: parseActivityArgs, beacon: beacon, beaconAsync: beaconAsync };

package/src/obstacle.mjs

@@ -19,7 +19,7 @@ import { defaultCredentialsPath, readCredentials } from "./token-store.mjs";
  * Best-effort obstacle beacon for a post-login failure. No-op (silent) when no
  * bridge credential is cached — the developer signed in with a build that didn't
  * carry the activity flags, or ran a bare `tot login`.
- * @param {"pnpm-missing"|"install-failed"|"clone-failed"} kind
+ * @param {"pnpm-missing"|"install-failed"|"clone-failed"|"renderer-native-bindings-missing"} kind
  * @param {{ have?: string, need?: string, env?: NodeJS.ProcessEnv }} [opts]
  */
 export async function emitObstacle(kind, { have, need, env = process.env } = {}) {

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 }>|null,
+ *   rollbackTarget?: { receiptId: string, aggregateSha: string } | null,
+ *   paywall?: { allowed: boolean, message?: string|null } | null,
+ *   refs?: Array<{ ref: string, sha?: string|null, reason?: string|null }>|null,
+ *   bypassedPrs?: Array<{ prNumber?: number|null, changeId?: string|null, headSha?: string|null }>|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
@@ -68,7 +94,7 @@ export function pickNvmrcVersion(env = process.env) {
     const best = readdirSync(root)
       .map((name) => /^v(\d+)\.(\d+)\.(\d+)$/.exec(name))
       .filter((m) => m && nodeMeetsFloor(m.slice(1).join(".")))
-      .map((m) => m.slice(1).map(Number))
+      .map((m) => /** @type {RegExpExecArray} */ (m).slice(1).map(Number))
       .sort((a, b) => b[0] - a[0] || b[1] - a[1] || b[2] - a[2])[0];
     if (best) return best.join(".");
   } catch {
@@ -151,7 +177,7 @@ export function scaffoldSample(destDir, { force = false, log = () => {} } = {})
     const err = new Error(
       `${dir} isn't empty and isn't a sample checkout — scaffold into an empty directory (or pass a new --workspace)`,
     );
-    err.code = "ENOTEMPTY_SAMPLE";
+    /** @type {any} */ (err).code ="ENOTEMPTY_SAMPLE";
     throw err;
   }
 
@@ -161,7 +187,7 @@ export function scaffoldSample(destDir, { force = false, log = () => {} } = {})
       "the sample store isn't available in this release yet — it's coming soon. " +
         "To build a real store now: `tot login --code <invite>` then `tot start`.",
     );
-    err.code = "SAMPLE_UNAVAILABLE";
+    /** @type {any} */ (err).code ="SAMPLE_UNAVAILABLE";
     throw err;
   }
 

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 };
 }
@@ -555,6 +607,10 @@ function buildPageTargetSet(contentDir, pagesDir) {
   return set;
 }
 
+/**
+ * @param {any} href @param {any} file @param {any} scope @param {any} pageTargets
+ * @param {(path: string) => boolean} [ownsPlatformRoute]
+ */
 function checkLink(href, file, scope, pageTargets, ownsPlatformRoute = () => false) {
   const out = [];
   if (!href || href.startsWith("#") || href.startsWith("mailto:") || href.startsWith("tel:")) return out;

package/src/viewer-session.mjs

@@ -0,0 +1,118 @@
+/**
+ * Viewer-session transport for the ship surface — the NO-operator-secret path.
+ *
+ * An invited developer holds a `tot login` MCP session but no operator secret and no
+ * storefront cookie, so the old ship-surface transport dead-ended on them. This mints
+ * a storefront VIEWER session from the developer's OWN MCP token (POST
+ * /api/dev/cli-session on the tenant's own host, which resolves WHO the opaque token
+ * is via the MCP and hands back a `tot_session` cookie), then hands the caller a
+ * cookie-based transport pointed at the tenant host. Authorization is still the
+ * developer's live `ship-on-behalf` grant, enforced server-side at the ship route —
+ * this only carries their identity, it grants nothing.
+ *
+ * Minted FRESH per call (no disk cache): a `tot accept` is interactive + infrequent,
+ * and minting-per-call means a revoked session/grant is never honored past its life.
+ */
+import { resolveDeveloperSession, AuthUnavailableError } from "./auth.mjs";
+
+const SESSION_COOKIE = "tot_session";
+
+/** The tenant's own storefront host — the dev-viewer admission derives the tenant
+ *  from the request host, so the session + integrate MUST target it (not the generic
+ *  storefront origin + X-Tot-Owner, which only steers the operator-secret path). */
+function tenantBase(tenant) {
+  return `https://${String(tenant || "").trim().toLowerCase()}`;
+}
+
+/** Pull `tot_session=<id>` out of a (possibly comma-folded) Set-Cookie header. The
+ *  id is base64url — no comma/semicolon — so a non-greedy stop-set is unambiguous. */
+export function parseSessionCookie(setCookie) {
+  if (!setCookie) return null;
+  const m = new RegExp(`${SESSION_COOKIE}=([^;,\\s]+)`).exec(setCookie);
+  return m ? m[1] : null;
+}
+
+/**
+ * Resolve a viewer-session transport for `tenant`. Returns
+ *   { ok:true, base, authHeaders }               — base = tenant host; cookie transport
+ *   { ok:false, message, hint }                  — a clean, actionable refusal
+ * Never throws.
+ *
+ * @param {{ tenant:string, env?:NodeJS.ProcessEnv, fetchImpl?:typeof fetch,
+ *   resolveDev?:typeof resolveDeveloperSession }} params
+ * @returns {Promise<
+ *   { ok:true, base:string, authHeaders:Record<string,string> } |
+ *   { ok:false, message:string, hint:string }
+ * >}
+ */
+export async function resolveViewerTransport({
+  tenant,
+  env = process.env,
+  fetchImpl = fetch,
+  resolveDev = resolveDeveloperSession,
+}) {
+  // The developer's OWN MCP token (read + silently refreshed by the resolver). No
+  // client needed — resolveDeveloperSession tolerates a null client.
+  let dev;
+  try {
+    dev = await resolveDev(null, env, { fetchImpl });
+  } catch (e) {
+    if (e instanceof AuthUnavailableError) {
+      return { ok: false, message: e.message, hint: e.hint || "run `tot login`, then re-run." };
+    }
+    return {
+      ok: false,
+      message: `couldn't read your Token of Trust session: ${e?.message || e}`,
+      hint: "run `tot login`, then re-run.",
+    };
+  }
+
+  const base = tenantBase(tenant);
+  let res;
+  try {
+    res = await fetchImpl(`${base}/api/dev/cli-session`, {
+      method: "POST",
+      headers: { authorization: `Bearer ${dev.token}` },
+    });
+  } catch (e) {
+    return {
+      ok: false,
+      message: `couldn't reach ${base} to start a session: ${e?.message || e}`,
+      hint: "check the --tenant domain / your network, then re-run.",
+    };
+  }
+  if (res.status === 401) {
+    return {
+      ok: false,
+      message: "your `tot` session wasn't recognized for this store.",
+      hint: "run `tot login`, then re-run.",
+    };
+  }
+  if (!res.ok) {
+    return {
+      ok: false,
+      message: `couldn't start a session at ${base} (HTTP ${res.status}).`,
+      hint: "retry shortly; if it persists, this store may not be set up for CLI publishing yet.",
+    };
+  }
+
+  const cookie = parseSessionCookie(res.headers.get("set-cookie"));
+  if (!cookie) {
+    return {
+      ok: false,
+      message: "the store started a session but returned no session cookie.",
+      hint: "re-run; if it persists, report it via `tot` feedback.",
+    };
+  }
+
+  return {
+    ok: true,
+    base,
+    authHeaders: {
+      cookie: `${SESSION_COOKIE}=${cookie}`,
+      // Matches the admin browser client; the server IGNORES this hint and re-reads
+      // the live ship-on-behalf grant, so it authorizes nothing on its own.
+      "x-tot-capability": "ship-on-behalf",
+    },
+  };
+}