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

package/src/commands/app/index.mjs

@@ -23,11 +23,11 @@ export async function run(argv, ctx) {
 
   if (sub === "scaffold") {
     const { run: runScaffold } = await import("./scaffold.mjs");
-    return runScaffold(rest, ctx);
+    return /** @type {any} */ (runScaffold)(rest, ctx);
   }
   if (sub === "dev") {
     const { run: runDev } = await import("./dev.mjs");
-    return runDev(rest, ctx);
+    return /** @type {any} */ (runDev)(rest, ctx);
   }
 
   console.error(fail(`unknown \`tot app\` subcommand: ${sub}`, "tot app --help"));

package/src/commands/branches.mjs

@@ -58,6 +58,7 @@ Options:
 
 /** Parse `tot branches` argv. Pure — unit-testable. */
 export function parseBranchesArgs(argv) {
+  /** @type {{ tenant: string|null, repo: string|null, staleAfterDays: number|null, mcp: string|null, identity: string|null, json: boolean, help: boolean }} */
   const a = {
     tenant: null,
     repo: null,

package/src/commands/cleanup.mjs

@@ -65,6 +65,7 @@ Options:
 
 /** Parse `tot cleanup` argv. Pure — unit-testable. */
 export function parseCleanupArgs(argv) {
+  /** @type {{ tenant: string|null, repo: string|null, staleAfterDays: number|null, ref: string|null, dryRun: boolean, yes: boolean, mcp: string|null, identity: string|null, help: boolean }} */
   const a = {
     tenant: null,
     repo: null,
@@ -206,7 +207,7 @@ export async function run(argv, ctx) {
 
     const planLines = planForAction({
       action: "cleanup",
-      tenant: tenant || repo,
+      tenant: /** @type {string} */ (tenant || repo),
       refs: eligible.map((b) => ({ ref: b.ref, sha: b.sha, reason: b.reason })),
     });
     const { confirmed, reason } = await printPlanAndConfirm(planLines, {

package/src/commands/clone.mjs

@@ -54,12 +54,14 @@ import { offerSignIn } from "./login.mjs";
 import { CliError, fail, formatError } from "../errors.mjs";
 import { writeNvmrc } from "../sample.mjs";
 import { emitObstacle } from "../obstacle.mjs";
+import { CREDENTIAL_HELPER, splitAuthedRemote, basicAuthExtraHeader } from "../git-credential.mjs";
 
 const execFileP = promisify(execFile);
 
 const DEFAULT_MCP_URL = "https://mcp.tokenoftrust.com";
 
 function parseArgs(argv) {
+  /** @type {{ tenant: string|null, dir: string|null, tag: string, pr: string|null, remoteOnly: boolean, mcp: string|null, printRemote: boolean, help: boolean }} */
   const a = {
     tenant: null,
     dir: null,
@@ -244,9 +246,9 @@ export async function run(argv, ctx) {
 
     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(`\nYour local working clone is at ${res.dir}.`);
       console.log(`  cd ${res.dir} && tot dev            # run it locally with save→reload`);
-      console.log(`  (the minted token lives in .git/config; a later clone rotates it)`);
+      console.log(`  (origin has no token — \`tot\` mints one fresh at fetch/push time)`);
       return 0;
     }
 
@@ -323,17 +325,38 @@ export async function checkoutTenant(client, { tenant, tag = "main", cloneDir =
 }
 
 /**
- * git clone the authenticated remote into `dir`. Throws CliError on failure.
- * Runs git as a NON-BLOCKING child process (promisified execFile) so the clone
- * doesn't stall the Node event loop — `tot start` runs this inside a
- * `Promise.all([...])` alongside the renderer prefetch, and a synchronous clone
- * would serialize what's meant to overlap.
+ * git clone the authenticated remote into `dir` — WITHOUT ever writing the
+ * live token to `.git/config` (unit u10). The MCP mints `gitRemote` as a
+ * basic-auth URL (`user:token@host`); rather than passing that straight to
+ * `git clone` (which records exactly the URL it was given as `origin`, token
+ * and all — the pre-u10 shape this fixes), the token is handed to git
+ * EPHEMERALLY via a one-shot `http.extraheader` (same mechanism
+ * pushPreviewRef in submit.mjs uses for a push) while the clone SOURCE is
+ * already the tokenless public URL — so `origin` comes out tokenless from
+ * the very first commit. The new checkout's `credential.helper` is then
+ * configured to `tot git-credential`, so every later fetch/push mints a
+ * fresh token through the CLI's own login session instead of ever needing
+ * one persisted on disk (a later clone no longer needs to "rotate" anything
+ * — the old flow's `.git/config` token is simply never written).
+ *
+ * Runs git as a NON-BLOCKING child process (promisified execFile) so the
+ * clone doesn't stall the Node event loop — `tot start` runs this inside a
+ * `Promise.all([...])` alongside the renderer prefetch, and a synchronous
+ * clone would serialize what's meant to overlap. Throws CliError on failure.
  */
 async function cloneRepo(gitRemote, dir, redact) {
   const git = async (cargs) => (await execFileP("git", cargs)).stdout.toString();
   console.log(`+ git clone → ${dir}`);
+  const cred = splitAuthedRemote(gitRemote);
+  const cloneArgs = cred
+    ? [
+        "-c", `http.extraheader=${basicAuthExtraHeader(cred.username, cred.token)}`,
+        "-c", "credential.helper=",
+        "clone", cred.publicUrl, dir,
+      ]
+    : ["clone", gitRemote, dir]; // no embedded token (e.g. already public) — clone as given
   try {
-    await git(["clone", gitRemote, dir]);
+    await git(cloneArgs);
   } catch (e) {
     // Beacon the cockpit before we surface the error — covers this path for both
     // `tot clone` and `tot start` (which clones through here). Awaited so the
@@ -343,6 +366,12 @@ async function cloneRepo(gitRemote, dir, redact) {
       next: `check the target dir is empty and you can reach the remote, then re-run`,
     });
   }
+  try {
+    await git(["-C", dir, "config", "--local", "credential.helper", CREDENTIAL_HELPER]);
+  } catch {
+    // Best-effort — a checkout missing the helper still WORKS (the token just
+    // isn't self-healing yet); the next `tot preview`/`tot sync` migrates it.
+  }
   const head = (await git(["-C", dir, "log", "-1", "--oneline"])).trim();
   writeNvmrc(dir); // version-manager hooks land on a supported Node on cd
   return { dir, head };
@@ -446,7 +475,7 @@ export async function cloneRepoAtPrRef(gitRemote, dir, pr, redact, deps = {}) {
  * @returns {{ message: string, next: string }|null}
  */
 export function readCredentialError(minted) {
-  const c = minted && typeof minted === "object" && !Array.isArray(minted) ? minted : null;
+  const c = /** @type {any} */ (minted && typeof minted === "object" && !Array.isArray(minted) ? minted : null);
   if (c && Array.isArray(c.repos) && c.repos.some((r) => r && r.gitRemote)) return null;
   const msg =
     (c && (c.message || (typeof c.error === "string" ? c.error : c.error?.message))) ||
@@ -493,7 +522,7 @@ export function readCredentialError(minted) {
  * @returns {{ message: string, next: string }|null}
  */
 export function checkoutError(checkout) {
-  const c = checkout && typeof checkout === "object" && !Array.isArray(checkout) ? checkout : null;
+  const c = /** @type {any} */ (checkout && typeof checkout === "object" && !Array.isArray(checkout) ? checkout : null);
   if (c && c.gitRemote) return null; // a usable checkout — never an error
   const msg =
     (c && (c.message || (typeof c.error === "string" ? c.error : c.error?.message))) ||
@@ -536,7 +565,8 @@ export function checkoutError(checkout) {
  * @returns {Array<{ id: string, name: string, raw: any }>}
  */
 export function normalizeStores(list) {
-  const rows = Array.isArray(list) ? list : list?.clients || list?.tenants || [];
+  const l = /** @type {any} */ (list);
+  const rows = Array.isArray(l) ? l : l?.clients || l?.tenants || [];
   if (!Array.isArray(rows)) return [];
   return rows
     .map((r) => ({
@@ -562,18 +592,19 @@ export function normalizeStores(list) {
  */
 export function storeListError(list) {
   if (list == null || typeof list !== "object" || Array.isArray(list)) return null;
+  const l = /** @type {any} */ (list);
   // A resolvable store array present → it succeeded, never an error.
-  if (Array.isArray(list.clients) || Array.isArray(list.tenants)) return null;
+  if (Array.isArray(l.clients) || Array.isArray(l.tenants)) return null;
   const msg =
-    list.message ||
-    (typeof list.error === "string" ? list.error : list.error?.message) ||
+    l.message ||
+    (typeof l.error === "string" ? l.error : l.error?.message) ||
     null;
-  if (list.isError) return msg || "the store list request returned an error";
-  if (typeof list.status === "string" && !/^(ok|success)$/i.test(list.status)) {
-    return msg || `the store list request returned status "${list.status}"`;
+  if (l.isError) return msg || "the store list request returned an error";
+  if (typeof l.status === "string" && !/^(ok|success)$/i.test(l.status)) {
+    return msg || `the store list request returned status "${l.status}"`;
   }
-  if (list.error) return msg || "the store list request returned an error";
-  if (typeof list.raw === "string" && list.raw.trim()) return list.raw.trim();
+  if (l.error) return msg || "the store list request returned an error";
+  if (typeof l.raw === "string" && l.raw.trim()) return l.raw.trim();
   return null;
 }
 
@@ -592,7 +623,7 @@ export function storeListError(list) {
  * @returns {{ brokerStatus: string|null, nextAction: string|null }}
  */
 export function brokerRemediation(list) {
-  const c = list && typeof list === "object" && !Array.isArray(list) ? list : null;
+  const c = /** @type {any} */ (list && typeof list === "object" && !Array.isArray(list) ? list : null);
   const brokerStatus = c && typeof c.brokerStatus === "string" ? c.brokerStatus : null;
   const nextAction =
     c && typeof c.nextAction === "string" && c.nextAction.trim() ? c.nextAction.trim() : null;

package/src/commands/dev.mjs

@@ -409,7 +409,7 @@ export function printSampleBanner({ url }, mode = "sample") {
  * Exported so sample/tests can drive the selection directly.
  * @param {ReturnType<typeof parseArgs>} args
  * @param {{ client?: any }} [opts] an already-authenticated MCP client (entitled path)
- * @returns {Promise<{kind:"public"|"entitled",version:string,url:string,strip:number,cacheKey:string}>}
+ * @returns {Promise<{kind:string,version:string,url:string,strip:number,cacheKey:string,integrity:string|null}>}
  */
 export async function resolveRendererSource(args, { client } = {}) {
   if (args.sample) return resolvePublicRendererSource(args);
@@ -576,6 +576,11 @@ function compareStableAsc(a, b) {
  * override with `--renderer-version` / TOT_RUNNER_VERSION. Package/registry
  * overridable via env for testing.
  */
+/**
+ * @param {any} args
+ * @param {NodeJS.ProcessEnv} [env]
+ * @param {{ declaredVersion?: string|null }} [opts]
+ */
 export async function resolvePublicRendererSource(args, env = process.env, { declaredVersion = null } = {}) {
   const pkg = env.TOT_RUNNER_PACKAGE || PUBLIC_RUNNER_PACKAGE;
   const registry = (env.TOT_NPM_REGISTRY || DEFAULT_NPM_REGISTRY).replace(/\/$/, "");
@@ -635,6 +640,7 @@ export async function resolvePublicRendererSource(args, env = process.env, { dec
  * developer entitlement (same gate as the Docker pull token). Reuses an
  * already-authenticated `client` when provided (C1/F3), else establishes its own.
  */
+/** @param {any} args @param {{ client?: any }} [opts] */
 export async function resolveEntitledRendererSource(args, { client: providedClient } = {}) {
   const baseUrl = args.mcp || process.env.MCP_BASE_URL || process.env.TOT_MCP_URL || DEFAULT_MCP_URL;
   const client = providedClient || createMcpClient(baseUrl);
@@ -674,6 +680,8 @@ export async function resolveEntitledRendererSource(args, { client: providedClie
  * instead of paying for a second client.initialize()+establishSession() — same
  * pattern as ensureRegistryLogin's `providedClient`). `tot dev` standalone
  * omits it and this establishes its own, as before.
+ * @param {any} args
+ * @param {{ client?: any }} [opts]
  * @returns {Promise<string>} the cached, installed runner tree's root directory.
  */
 export async function ensureRendererArtifact(args, { client: providedClient } = {}) {
@@ -854,11 +862,11 @@ export function probeRunnerVersion(runnerDir, { timeoutMs = 4000 } = {}) {
  * @returns {Promise<string>} the runner tree's root directory (has scripts/tot-dev.mjs).
  */
 export async function ensureSampleRenderer(args, ctx, { env = process.env, cacheRoot = RENDERER_CACHE_ROOT } = {}) {
-  const src = resolveLocalRendererSource({
+  const src = /** @type {any} */ (resolveLocalRendererSource({
     env,
     mode: ctx?.mode,
     repoRoot: ctx?.repoRoot,
-  });
+  }));
 
   if (src.kind === "dir") {
     if (!existsSync(join(src.dir, "scripts", "tot-dev.mjs"))) {
@@ -1048,7 +1056,7 @@ export async function installRunnerTarball(
   // of stopping a first run at an error only `rm -rf` folklore could clear.
   // Bounded to one retry so a genuinely-broken source still fails loudly.
   for (let attempt = 1; ; attempt++) {
-    const archivePath = isUrl ? join(tmpdir(), `tot-renderer-${process.pid}-${attempt}.tar.gz`) : localSource;
+    const archivePath = /** @type {string} */ (isUrl ? join(tmpdir(), `tot-renderer-${process.pid}-${attempt}.tar.gz`) : localSource);
     const stagingDir = `${runnerDir}.staging-${process.pid}`;
     try {
       if (isUrl) {
@@ -1118,7 +1126,7 @@ export async function installRunnerTarball(
             exitCode: 2,
           },
         );
-        err.permanent = true;
+        /** @type {any} */ (err).permanent = true;
         throw err;
       }
       writeCacheMarker(runnerDir, { version, integrity: contentId });
@@ -1270,7 +1278,7 @@ async function downloadFile(url, destPath) {
   if (!res.ok || !res.body) {
     throw new Error(`download failed: HTTP ${res.status} ${res.statusText}`);
   }
-  await pipeline(Readable.fromWeb(res.body), createWriteStream(destPath));
+  await pipeline(Readable.fromWeb(/** @type {any} */ (res.body)), createWriteStream(destPath));
 }
 
 /**
@@ -1319,7 +1327,8 @@ export function ensureCorepackPnpm(runnerDir, { logPath, spawnFn = spawnSync } =
     for (const args of [["enable"], ["prepare", pm, "--activate"]]) {
       const r = spawnFn("corepack", args, { stdio: ["ignore", fd ?? "ignore", fd ?? "ignore"] });
       if (fd !== null && (r.error || r.status !== 0)) {
-        writeSync(fd, `[tot] corepack ${args.join(" ")} → ${r.error?.code || r.error?.message || `exit ${r.status}`}\n`);
+        const rerr = /** @type {any} */ (r.error);
+        writeSync(fd, `[tot] corepack ${args.join(" ")} → ${rerr?.code || rerr?.message || `exit ${r.status}`}\n`);
       }
     }
   } finally {
@@ -1363,6 +1372,10 @@ function spawnAsyncResult(cmd, args, opts = {}) {
   });
 }
 
+/**
+ * @param {string} runnerDir
+ * @param {{ logPath?: string, spawnFn?: (cmd: string, args: string[], opts?: any) => any }} [opts]
+ */
 export async function runPnpmInstall(runnerDir, { logPath, spawnFn = spawnAsyncResult } = {}) {
   const fd = logPath ? openSync(logPath, "a") : null;
   const installArgs = ["install", "--config.dangerouslyAllowAllBuilds=true"];
@@ -1400,7 +1413,7 @@ export async function runPnpmInstall(runnerDir, { logPath, spawnFn = spawnAsyncR
         stdio: ["ignore", fd ?? "ignore", fd ?? "ignore"],
       });
       if (r.status === 0) return; // installed
-      if (r.error?.code === "ENOENT") {
+      if (/** @type {any} */ (r.error)?.code === "ENOENT") {
         // This launcher isn't on the machine — record it and try the next one.
         if (fd !== null) writeSync(fd, `[tot] ${cmd} not found (ENOENT) — trying the next launcher\n`);
         continue;
@@ -1425,7 +1438,7 @@ export async function runPnpmInstall(runnerDir, { logPath, spawnFn = spawnAsyncR
         (logPath ? `\n     details: ${logPath}` : ""),
       { next: "install pnpm with `npm i -g pnpm` (or `corepack enable`), then re-run `tot start`" },
     );
-    err.permanent = true;
+    /** @type {any} */ (err).permanent = true;
     throw err;
   } finally {
     if (fd !== null) closeSync(fd);
@@ -1470,6 +1483,10 @@ function pnpmFailureHint(logPath) {
  * fs-watch HMR. Returns a handle shaped like spawnDevContainer's, so run()'s
  * auto-open-browser logic works unchanged for either runtime. Exported (and
  * `stdio` overridable) so `tot start` can pipe the logs instead of inheriting.
+ * @param {string} runnerDir
+ * @param {string} workspace
+ * @param {string} port
+ * @param {{ stdio?: any, env?: Record<string, any> }} [opts]
  */
 export function spawnNativeDev(runnerDir, workspace, port, { stdio = "inherit", env = {} } = {}) {
   const script = join(runnerDir, "scripts", "tot-dev.mjs");
@@ -1490,7 +1507,7 @@ export function spawnNativeDev(runnerDir, workspace, port, { stdio = "inherit",
     [script, "--workspace", workspace, "--port", port],
     { cwd: runnerDir, stdio: stdioArr, env: mergedEnv },
   );
-  const handle = { child, exited: false, done: null };
+  const handle = { child, exited: false, done: /** @type {any} */ (null) };
   handle.done = new Promise((resolvePromise) => {
     child.on("exit", (code) => {
       handle.exited = true;
@@ -1645,9 +1662,9 @@ export async function spawnDevContainer(plan, args, { stdio = "inherit" } = {})
 
   const stdioArr =
     stdio === "piped" ? ["ignore", "pipe", "pipe"] : ["inherit", "inherit", "inherit"];
-  const child = spawn("docker", plan.dockerArgs, { stdio: stdioArr });
+  const child = spawn("docker", plan.dockerArgs, { stdio: /** @type {any} */ (stdioArr) });
 
-  const handle = { child, exited: false, done: null };
+  const handle = { child, exited: false, done: /** @type {any} */ (null) };
   handle.done = new Promise((resolvePromise) => {
     child.on("exit", (code) => {
       handle.exited = true;
@@ -1687,6 +1704,7 @@ export function isPrivateRegistryImage(image) {
  * its own session and overlaps this with the checkout clone instead of paying
  * for a second client.initialize()+establishSession() serially afterward).
  * `tot dev` standalone omits it and this establishes its own, as before.
+ * @param {string} image @param {any} args @param {{ client?: any }} [opts]
  */
 export async function ensureRegistryLogin(image, args, { client: providedClient } = {}) {
   const registry = String(image).split("/")[0];

package/src/commands/git-credential.mjs

@@ -0,0 +1,180 @@
+/**
+ * `tot git-credential` — git's own credential-helper protocol (see `git help
+ * gitcredentials`), implemented over the developer's cached `tot login`
+ * session (unit u10, workstream tot-merge-conflict-resolution-ux). `tot
+ * clone` configures a fresh checkout's `credential.helper` to run this (see
+ * ../git-credential.mjs's CREDENTIAL_HELPER), so `git fetch`/`git push`/`git
+ * pull` — run DIRECTLY by the developer, not just through `tot preview` —
+ * transparently mint a fresh forge token instead of ever needing one
+ * persisted in `.git/config`. This is the fix for the "the panel-prescribed
+ * `git fetch origin` fails even after `tot login`" dead-end: `tot login`
+ * only ever refreshed the CLI's OWN MCP session, never the token baked into
+ * a checkout's remote URL at clone time.
+ *
+ * git invokes this with ONE positional arg (`get`/`store`/`erase`) and the
+ * request on stdin (key=value lines, blank-line/EOF terminated). Only `get`
+ * does real work — this CLI never persists a forge credential of its own
+ * beyond the short-lived cache in ../git-credential.mjs, so `store`/`erase`
+ * are no-ops (git calls them after a successful/failed auth respectively; we
+ * just drain stdin and exit 0, the correct behavior for a stateless helper).
+ *
+ * FAILS SILENT, NEVER LOUD: `get` prints NOTHING and exits non-zero on any
+ * problem (not signed in, MCP unreachable, cwd isn't a recognizable tenant
+ * checkout) — git then falls through to its next configured helper or its
+ * own prompt, exactly as if this helper weren't configured. A stack trace or
+ * a malformed credential line here would otherwise corrupt EVERY git
+ * operation in the checkout. It also NEVER triggers an interactive sign-in —
+ * this runs as a non-interactive subprocess of `git`, so a missing session
+ * fails through rather than trying to open a browser mid-`git fetch`.
+ *
+ * Dependency-free (global fetch + `git`, via the same MCP client + auth
+ * module every other command uses).
+ */
+import { readFileSync } from "node:fs";
+import { execFileSync } from "node:child_process";
+import { createMcpClient } from "../mcp.mjs";
+import { establishSession } from "../auth.mjs";
+import { checkoutTenant } from "./clone.mjs";
+import { detectContext } from "../context.mjs";
+import { repoNameFromRemote, tagFromRepoName } from "./submit.mjs";
+import {
+  parseCredentialInput, formatCredentialOutput, splitAuthedRemote,
+  credentialCachePath, readCachedCredential, writeCachedCredential,
+} from "../git-credential.mjs";
+
+const DEFAULT_MCP_URL = "https://mcp.tokenoftrust.com";
+
+/** Does `remoteUrl`'s host equal `host` (case-insensitive)? An unparseable or
+ *  missing remote URL never matches — fail closed. Exported for testing. */
+export function hostMatches(remoteUrl, host) {
+  if (!remoteUrl || !host) return false;
+  try {
+    // scp-like remotes (git@host:owner/repo.git) have no scheme — synthesize one so URL can parse the host.
+    const normalized = /^[^/]+@[^/:]+:/.test(remoteUrl) ? `ssh://${remoteUrl.replace(":", "/")}` : remoteUrl;
+    return new URL(normalized).host.toLowerCase() === host.toLowerCase();
+  } catch {
+    return false;
+  }
+}
+
+/** Read the credential request git writes to stdin — blocking is correct
+ *  here: git writes the request then closes its end, so this returns as
+ *  soon as it's fully sent. Never blocks on an interactive terminal (git
+ *  NEVER attaches a TTY to a credential helper's stdin — only a human
+ *  poking at this command directly by hand would) and never throws (an
+ *  unreadable/absent stdin is treated as an empty request). Exported so a
+ *  test can inject a canned request instead of touching real fd 0. */
+export function readStdin() {
+  if (process.stdin.isTTY) return "";
+  try {
+    return readFileSync(0, "utf8");
+  } catch {
+    return "";
+  }
+}
+
+/**
+ * Mint (or reuse a cached) forge credential for the tenant the CURRENT
+ * directory checks out — the same `tenant_checkout` MCP call `tot clone`
+ * itself uses, so the credential is exactly as push-capable. Returns null on
+ * ANY failure (wrong dir, not signed in, MCP unreachable) rather than
+ * throwing — `get` treats null as "say nothing, exit non-zero".
+ *
+ * `createClient`/`establish`/`checkout` are injected (default to the real MCP
+ * client + auth + clone.mjs's checkoutTenant) purely so this is testable
+ * without a live MCP — same DI shape as chooseChangeId's injected `mint` /
+ * resolveDeveloperSession's injected `fetchImpl` elsewhere in this CLI.
+ * SCOPED TO THE CHECKOUT'S OWN REMOTE: `expectedHost` (git's requested host,
+ * from the credential-helper request) is checked against the host of this
+ * checkout's `origin` remote before a credential is ever minted or returned
+ * — a `get` for any OTHER host returns null (silent fail), never handing the
+ * tenant's forge token to a host this checkout doesn't itself push to. This
+ * matters because `credential.helper` is invoked per-URL by git, and a
+ * globally-scoped helper (or a checkout with a submodule / unrelated remote)
+ * must not become a way to exfiltrate the token to an arbitrary host.
+ * @param {{
+ *   env?: NodeJS.ProcessEnv, cwd?: string, expectedHost?: string|null,
+ *   createClient?: typeof createMcpClient,
+ *   establish?: typeof establishSession,
+ *   checkout?: typeof checkoutTenant,
+ * }} [opts]
+ * @returns {Promise<{username:string,password:string}|null>}
+ */
+export async function mintOrCacheCredential({
+  env = process.env, cwd = process.cwd(), expectedHost = null,
+  createClient = createMcpClient, establish = establishSession, checkout = checkoutTenant,
+} = {}) {
+  const ctx = detectContext(cwd);
+  if (ctx.mode !== "checkout" || !ctx.tenant) return null;
+
+  const git = (cargs) =>
+    execFileSync("git", ["-C", ctx.workspacePath, ...cargs], { stdio: ["ignore", "pipe", "pipe"] }).toString();
+  let originUrl = null;
+  let repoName = null;
+  try {
+    originUrl = git(["remote", "get-url", "origin"]).trim();
+    repoName = repoNameFromRemote(originUrl);
+  } catch {
+    /* fall through — tagFromRepoName degrades to "main" on a null repo name */
+  }
+  if (expectedHost && !hostMatches(originUrl, expectedHost)) return null;
+  const tag = tagFromRepoName(repoName, ctx.tenant);
+
+  const cachePath = credentialCachePath(ctx.tenant, tag, env);
+  const cached = readCachedCredential(cachePath);
+  if (cached) return { username: cached.username, password: cached.password };
+
+  const baseUrl = env.MCP_BASE_URL || env.TOT_MCP_URL || DEFAULT_MCP_URL;
+  const client = createClient(baseUrl);
+  try {
+    await establish(client, { env });
+  } catch {
+    return null; // not signed in (or session unrefreshable) — nothing this helper can do
+  }
+  try {
+    const res = await checkout(client, { tenant: ctx.tenant, tag, cloneDir: null });
+    const cred = splitAuthedRemote(res.gitRemote || "");
+    if (!cred) return null;
+    const fresh = { username: cred.username, password: cred.token };
+    writeCachedCredential(cachePath, fresh);
+    return fresh;
+  } catch {
+    return null; // MCP unreachable / tenant_checkout refused — say nothing, exit non-zero
+  }
+}
+
+const USAGE = `tot git-credential — git credential-helper protocol over your \`tot login\` session
+
+  Configured automatically by \`tot clone\` (credential.helper = !tot git-credential)
+  in every checkout it creates — you should never need to run this by hand.
+  See \`git help gitcredentials\` for the protocol this implements.`;
+
+/**
+ * @param {string[]} argv  argv[0] is git's operation: get|store|erase
+ * @param {any} _ctx  unused — this command derives its OWN context from cwd
+ *   (mintOrCacheCredential), since git invokes it with the credentialed
+ *   repo's directory as cwd, which may differ from wherever `tot` itself
+ *   was dispatched from.
+ * @param {{ env?: NodeJS.ProcessEnv, cwd?: string, readStdin?: typeof readStdin }
+ *   & Parameters<typeof mintOrCacheCredential>[0]} [opts]
+ */
+export async function run(argv, _ctx, opts = {}) {
+  const { env = process.env, readStdin: read = readStdin } = opts;
+  const op = argv[0];
+  if (!op || op === "--help" || op === "-h") {
+    console.log(USAGE);
+    return op ? 0 : 2;
+  }
+  // git always writes a request to stdin, even for store/erase — drain it either way
+  // so the subprocess exits cleanly instead of leaving git's write blocked on a full pipe.
+  const request = parseCredentialInput(read());
+
+  if (op !== "get") return 0; // store/erase: stateless, nothing to persist or drop.
+
+  const cred = await mintOrCacheCredential({ ...opts, expectedHost: request.host });
+  if (!cred) return 1; // silent — let git fall through to its next helper / its own prompt.
+  process.stdout.write(formatCredentialOutput({
+    protocol: request.protocol, host: request.host, username: cred.username, password: cred.password,
+  }));
+  return 0;
+}

package/src/commands/go-live.mjs

@@ -196,6 +196,9 @@ export function renderReadiness({ appDomain, readiness, action }) {
   const lines = ["", `  Apex ${action === "rollback" ? "rollback" : "cutover"} readiness for ${appDomain ?? "this store"}:`];
   for (const c of readiness.checks) {
     lines.push(`    ${c.ok ? "✓" : "✗"} ${c.label}${c.detail ? ` — ${c.detail}` : ""}`);
+    // Blocked checks carry a "how to clear this" remedy from the server gate —
+    // the same guidance the admin panel shows, so the two surfaces never diverge.
+    if (!c.ok && c.remedy) lines.push(`        → ${c.remedy}`);
   }
   if (action === "connect") {
     lines.push(
@@ -217,6 +220,7 @@ export function renderReadiness({ appDomain, readiness, action }) {
  * assuming it from the dispatch. Injectable delay/attempts. Returns the last
  * normalised run status (may still be "dispatched" if CI is slow — reported honestly).
  * @param {{ get:(path:string)=>Promise<any> }} http
+ * @param {{ attempts?: number, delayMs?: number, sleep?: Function }} [opts]
  */
 export async function pollRunTerminal(http, { attempts = 8, delayMs = 2000, sleep } = {}) {
   const wait = sleep || ((ms) => new Promise((r) => setTimeout(r, ms)));
@@ -391,7 +395,7 @@ function cap(s) {
  * ship floor. Throws on a non-2xx with the server's error message (so the caller
  * surfaces the real refusal). `fetchImpl` is injectable for tests.
  * @param {string} base
- * @param {{ token:string|undefined, owner:string, capability?:string, fetchImpl?:typeof fetch }} auth
+ * @param {{ token?:string, owner?:string, capability?:string, fetchImpl?:typeof fetch }} [auth]
  */
 export function createStorefrontHttp(base, { token, owner, capability = "ship-on-behalf", fetchImpl } = {}) {
   const root = base.replace(/\/+$/, "");
@@ -476,7 +480,7 @@ export async function run(argv, ctx) {
   const http = createStorefrontHttp(base, { token, owner });
   return await runGoLive(
     http,
-    { appDomain: owner, action: args.action, rehearsal: args.rehearsal, noOpen: args.noOpen },
+    { appDomain: owner, action: /** @type {any} */ (args.action), rehearsal: args.rehearsal, noOpen: args.noOpen },
     { openUrl: (u) => openBrowser(u) },
   );
 }

package/src/commands/grants.mjs

@@ -61,9 +61,10 @@ function parseArgs(argv) {
  *   exp: number|null, revokedAt: string|null }> }}
  */
 export function normalizeGrantRows(resp) {
-  if (resp && typeof resp === "object" && !Array.isArray(resp) && Array.isArray(resp.grants)) {
-    const activeTenant = typeof resp.activeTenant === "string" ? resp.activeTenant : null;
-    const rows = resp.grants
+  const rr = /** @type {any} */ (resp);
+  if (resp && typeof resp === "object" && !Array.isArray(resp) && Array.isArray(rr.grants)) {
+    const activeTenant = typeof rr.activeTenant === "string" ? rr.activeTenant : null;
+    const rows = rr.grants
       .map((g) => {
         const tenant = g?.tenant ?? g?.id ?? null;
         return {
@@ -83,7 +84,7 @@ export function normalizeGrantRows(resp) {
 
   // Fallback: client_list — store ids + environment + the selected marker only. No
   // grant detail is knowable here (grantActive/capability/tier/exp/revokedAt stay null).
-  const clients = Array.isArray(resp) ? resp : resp?.clients || resp?.tenants || [];
+  const clients = Array.isArray(resp) ? resp : rr?.clients || rr?.tenants || [];
   const rows = (Array.isArray(clients) ? clients : [])
     .map((c) => ({
       tenant: c?.tenant ?? c?.id ?? c?.clientId ?? c?.appDomain ?? null,
@@ -147,6 +148,7 @@ export function formatExpiry(exp, { now = Date.now() } = {}) {
 export function describeGrantRow(row, { now = Date.now() } = {}) {
   const status = grantStatus(row, { now });
   if (status === "unknown") return "grant detail unavailable (server introspection not enabled)";
+  /** @type {string[]} */
   const parts = [status];
   if (row.capability) parts.push(`capability=${row.capability}`);
   if (row.tier) parts.push(`tier=${row.tier}`);

package/src/commands/link.mjs

@@ -54,7 +54,7 @@ Run this when \`tot whoami\` / \`tot start\` say your identity isn't linked yet.
  * @returns {{ authUrl: string|null, pollHandle: string|null }}
  */
 export function linkBeginFields(res) {
-  const c = res && typeof res === "object" && !Array.isArray(res) ? res : {};
+  const c = /** @type {any} */ (res && typeof res === "object" && !Array.isArray(res) ? res : {});
   const authUrl =
     c.authUrl ||
     c.url ||
@@ -77,7 +77,7 @@ export function linkBeginFields(res) {
  * @returns {"linked"|"pending"|string}
  */
 export function linkPollStatus(res) {
-  const c = res && typeof res === "object" && !Array.isArray(res) ? res : {};
+  const c = /** @type {any} */ (res && typeof res === "object" && !Array.isArray(res) ? res : {});
   if (c.linked === true || c.done === true || c.complete === true) return "linked";
   const raw =
     (typeof c.status === "string" && c.status) || (typeof c.state === "string" && c.state) || "";

package/src/commands/login.mjs

@@ -120,7 +120,7 @@ After signing in, run \`tot whoami\` to confirm, then \`tot clone\` / \`tot subm
  * without duplicating this.
  * @returns {Promise<object>} the credentials written to disk.
  */
-export async function loginAndCache(mcpUrl, env = process.env, { log = () => {}, device = false } = {}) {
+export async function loginAndCache(mcpUrl, env = process.env, { log = /** @type {(m?: string) => void} */ (() => {}), device = false } = {}) {
   const path = defaultCredentialsPath(env);
   const prior = readCredentials(path);
   const clientId = prior && prior.mcpUrl === mcpUrl ? prior.clientId : undefined;
@@ -196,11 +196,10 @@ export async function offerSignIn(mcpUrl, env = process.env, {
  * `log` carries the fingerprint + "waiting for approval" lines to the terminal.
  * @returns {Promise<object>} the credentials written to disk.
  */
-export async function redeemAndCache(mcpUrl, code, env = process.env, { log = () => {} } = {}) {
+export async function redeemAndCache(mcpUrl, code, env = process.env, { log = /** @type {(m?: string) => void} */ (() => {}) } = {}) {
   const path = defaultCredentialsPath(env);
   const prior = readCredentials(path);
-  const clientId = prior && prior.mcpUrl === mcpUrl ? prior.clientId : undefined;
-  const creds = await rendezvousLoginFlow({ mcpUrl, clientId, code, log });
+  const creds = await rendezvousLoginFlow({ mcpUrl, code, log });
   const merged = mergeActivityBridge(prior, mcpUrl, creds);
   writeCredentials(path, merged);
   return merged;