@tokenoftrust/cli 1.4.1 → 2.0.0

package/src/commands/sync.mjs

@@ -1,7 +1,7 @@
 /**
  * `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):
+ * "Two developers touch the same file"):
  *
  *   Both candidate previews may be green in isolation. After the first
  *   integrates, the second may become conflicted. The queue blocks that PR
@@ -160,7 +160,7 @@ export async function run(argv, ctx) {
     }
   };
 
-  // Self-heal a LEGACY checkout (unit u10, absorbs u7): `tot login` refreshes
+  // Self-heal a LEGACY checkout: `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.

package/src/commands/validate.mjs

@@ -71,12 +71,13 @@ export function run(argv, ctx) {
     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 clone <tenant>`"));
+  const dir = /** @type {string} */ (target.dir);
+  if (!existsSync(dir)) {
+    console.error(fail(`no tenant directory at ${dir}`, "confirm the path, or `tot clone <tenant>`"));
     return 2;
   }
 
-  const { ok, findings } = validateTenant(target.dir, {
+  const { ok, findings } = validateTenant(dir, {
     tenantId: target.tenantId ?? undefined,
     scope: target.scope ?? undefined,
     // A checkout / bare-tenant target is served by the ToT storefront platform, so

package/src/commands/whoami.mjs

@@ -67,7 +67,7 @@ export async function run(argv, _ctx) {
     } else if (listErr) {
       console.log(`  (couldn't list your stores: ${listErr} — try \`tot login\` again)`);
     } else {
-      // Status-aware (card c2): an UNLINKED identity is told to link (not "may
+      // Status-aware: 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})`);

package/src/dev-heartbeat.mjs

@@ -1,5 +1,5 @@
 /**
- * CLI-side heartbeat for the local→hosted activity bridge (G1).
+ * CLI-side heartbeat for the local→hosted activity bridge.
  *
  * While `tot dev` / `tot start` is running, the CLI (which knows its own
  * version, the resolved runner version, the port + tenant, and the cached
@@ -35,7 +35,8 @@ const OS_INFO = { os: os.platform(), osVersion: os.release(), arch: os.arch() };
  * an activity URL and a bearer token. Never throws — a failed/offline hosted
  * worker just means the cockpit doesn't light up this beat.
  * @param {{ activityUrl?: string, token?: string, url?: string,
- *   cliVersion?: string, runnerVersion?: string|null, editor?: string|null }} args
+ *   cliVersion?: string, runnerVersion?: string|null, editor?: string|null,
+ *   cwd?: string|null }} args
  */
 export function postHeartbeat({ activityUrl, token, url, cliVersion, runnerVersion, editor, cwd } = {}) {
   if (!activityUrl || !token) return undefined;

package/src/dev-logs.mjs

@@ -18,7 +18,7 @@ import { milestoneBanner, DEVELOPER_COCKPIT } from "./banner.mjs";
  * noise, and pass anything else through (indented) so nothing important is
  * hidden. Ctrl-C still tears the server down (the child owns the TTY signals).
  *
- * The FIRST save→reload is the aha milestone (u2): with a `cockpitUrl` it's a
+ * The FIRST save→reload is the aha milestone: with a `cockpitUrl` it's a
  * PROMINENT banner that sends the developer back to their Developer Cockpit to
  * see the change; every reload after that is the quiet "↻ your store reloaded"
  * line so a working dev loop doesn't get spammed with banners.
@@ -35,7 +35,7 @@ export function streamDevLogs(
   // the runner/Vite "HH:MM:SS " timestamp prefix (see `body` below), so a
   // timestamped internal line like "10:50:17 [vite] connected" is still dropped.
   // The node:* / ExperimentalWarning / (node:NNNN) / "--trace-warnings" and the
-  // boot "fatal: not a git repository" lines are dropped too (b4) — scary,
+  // boot "fatal: not a git repository" lines are dropped too — scary,
   // non-actionable boot noise that reads as a broken first run.
   const NOISE =
     /^(\[vite\]|\[types\]|\[@astrojs|\[WARN\]|▲|┃|astro\s+v[\d.]|(Local|Network)\s+http|watching for file changes|Scope: all \d|copy-tenant-assets:|.*dependency optimized|.*optimized dependencies changed|.*program reload|\d+ deprecated|Packages:\s*\+|Progress:\s*resolved|Downloading @|node_modules\/|devDependencies:|\+\s+\w+@|Done in \d|\(node:\d+\)|ExperimentalWarning|node:internal\/|\(Use `node --trace-warnings|fatal: not a git repository)/i;

package/src/errors.mjs

@@ -32,13 +32,20 @@ function versionFooter() {
 
 /**
  * A failure worth surfacing with a concrete next step.
+ * @typedef {object} CliErrorOpts
+ * @property {string} [next]     - the exact command (or one-line instruction) to run next.
+ * @property {number} [exitCode] - process exit code to use (default 1).
+ * @property {unknown} [cause]
+ *
  * @param {string} what   - what went wrong, in plain words.
- * @param {{ next?: string, exitCode?: number, cause?: unknown }} [opts]
- *   next     - the exact command (or one-line instruction) to run next.
- *   exitCode - process exit code to use (default 1).
+ * @param {CliErrorOpts} [opts]
  */
 export class CliError extends Error {
-  constructor(what, { next, exitCode = 1, cause } = {}) {
+  /** True when retrying the operation cannot change its outcome. */
+  permanent;
+
+  constructor(what, opts = {}) {
+    const { next, exitCode = 1, cause } = opts;
     super(what);
     this.name = "CliError";
     this.what = what;

package/src/git-credential.mjs

@@ -19,7 +19,8 @@
  */
 import { homedir } from "node:os";
 import { createHash } from "node:crypto";
-import { join } from "node:path";
+import { join, dirname } from "node:path";
+import { mkdirSync, writeFileSync, chmodSync } from "node:fs";
 import { readCredentials, writeCredentials } from "./token-store.mjs";
 
 /** The git config value that routes credential requests through `tot` — the
@@ -80,6 +81,7 @@ export function basicAuthExtraHeader(username, token) {
  * @returns {Record<string,string>}
  */
 export function parseCredentialInput(text) {
+  /** @type {Record<string,string>} */
   const out = {};
   for (const line of String(text).split("\n")) {
     const trimmed = line.trim();
@@ -140,20 +142,98 @@ export function writeCachedCredential(filePath, { username, password }, { now =
   writeCredentials(filePath, { username, password, mintedAt: now });
 }
 
+/** Single-quote a string for safe interpolation into the /bin/sh shim. Pure. */
+function shq(s) {
+  return `'${String(s).replace(/'/g, `'\\''`)}'`;
+}
+
+/** Absolute path to the stable, node-version-independent credential-helper shim
+ *  under `~/.tot/bin` (honors `TOT_HOME`). A checkout's git config points at THIS by
+ *  absolute path — never a bare `!tot` — so `nvm use` (which swaps the per-node `tot`)
+ *  can't silently redirect forge auth to an older/missing CLI. Pure. */
+export function forgeShimPath(env = process.env) {
+  const home = env.TOT_HOME || homedir();
+  return join(home, ".tot", "bin", "tot-git-credential");
+}
+
+/** The shim's contents: pin the ABSOLUTE node + CLI entry active at write time, with a
+ *  PATH-search fallback for node, and FAIL LOUD to stderr (never silently) when no node
+ *  is found — so a broken helper says how to fix itself instead of yielding an opaque
+ *  "Repository not found". Pure — unit-tested. */
+export function renderForgeShim(nodePath, entryPath) {
+  return [
+    "#!/bin/sh",
+    "# Managed by tot — stable forge credential helper (regenerated each run; do not edit).",
+    "# Decouples git auth from which node/tot is active in the shell (nvm-proof).",
+    `NODE=${shq(nodePath)}`,
+    '[ -x "$NODE" ] || NODE="$(command -v node 2>/dev/null)"',
+    'if [ -z "$NODE" ]; then',
+    '  echo "tot: no node runtime for the git credential helper — reinstall: npm i -g @tokenoftrust/cli@latest" >&2',
+    "  exit 1",
+    "fi",
+    `exec "$NODE" ${shq(entryPath)} git-credential "$@"`,
+    "",
+  ].join("\n");
+}
+
+/** Write/refresh the shim (0700 dir, 0755 file). Best-effort — returns the shim path,
+ *  or "" if it couldn't be written (caller then falls back to the bare `!tot` helper). */
+export function writeForgeShim(env = process.env, nodePath = process.execPath, entryPath = process.argv[1]) {
+  try {
+    if (!nodePath || !entryPath) return "";
+    const p = forgeShimPath(env);
+    mkdirSync(dirname(p), { recursive: true, mode: 0o700 });
+    writeFileSync(p, renderForgeShim(nodePath, entryPath), { mode: 0o755 });
+    chmodSync(p, 0o755);
+    return p;
+  } catch {
+    return "";
+  }
+}
+
+/**
+ * Install (or refresh) the HOST-SCOPED forge credential helper on a checkout so that:
+ *  - it runs the stable `~/.tot` shim by ABSOLUTE path (nvm-proof), not a bare `!tot`;
+ *  - a leading EMPTY reset value clears any inherited GLOBAL helper for this host — the
+ *    fix for `credential.helper = osxkeychain` (every Mac dev) running first, returning
+ *    a stale forge cred, and shadowing our helper so `git pull` 404s even after login.
+ * Idempotent: a no-op when the host-scoped list is already `["", <ourHelper>]`. Returns
+ * whether it changed anything. `writeShim` is injected for tests. Pure git I/O otherwise.
+ * @param {(cargs: string[]) => string} git
+ * @param {{ host?: string, env?: NodeJS.ProcessEnv, nodePath?: string, entryPath?: string, writeShim?: typeof writeForgeShim }} [options]
+ * @returns {boolean} changed
+ */
+export function installForgeCredentialHelper(git, {
+  host, env = process.env, nodePath = process.execPath, entryPath = process.argv[1],
+  writeShim = writeForgeShim,
+} = {}) {
+  if (!host) return false;
+  const shim = writeShim(env, nodePath, entryPath);
+  const helperValue = shim ? `!${shim}` : CREDENTIAL_HELPER;
+  const key = `credential.https://${host}.helper`;
+  let raw = null;
+  try { raw = git(["config", "--local", "--get-all", key]); } catch { raw = null; }
+  // git prints one value per line (an empty value = an empty line); our desired list is
+  // ["", helperValue] → "\n<helperValue>". Already correct ⇒ nothing to do.
+  if (raw !== null && raw.replace(/\n+$/, "") === `\n${helperValue}`) return false;
+  try { git(["config", "--local", "--unset-all", key]); } catch { /* none set yet */ }
+  git(["config", "--local", "--add", key, ""]);            // reset: clear inherited (osxkeychain) for this host
+  git(["config", "--local", "--add", key, helperValue]);   // our helper is now the sole one
+  return true;
+}
+
 /**
- * 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.
+ * Self-heal a LEGACY checkout, best-effort: strip any embedded token from `origin`
+ * (the pre-u10 shape whose token silently expires), then install the stable, host-scoped
+ * credential helper (see installForgeCredentialHelper) so future git ops mint fresh creds
+ * through the `~/.tot` shim — nvm-proof and un-shadowable by osxkeychain. Called at the top
+ * of every command that touches git. A no-op on an already-migrated remote; leaves a
+ * non-http(s) (e.g. ssh) remote entirely alone. Never blocks the command on a hiccup.
  * @param {(cargs:string[])=>string} git  a `git -C <workspace>` runner
+ * @param {{ env?: NodeJS.ProcessEnv, nodePath?: string, entryPath?: string, writeShim?: typeof writeForgeShim }} [opts]
  * @returns {{ migrated: boolean }}
  */
-export function ensureTokenlessRemote(git) {
+export function ensureTokenlessRemote(git, opts = {}) {
   let remote;
   try {
     remote = git(["remote", "get-url", "origin"]).trim();
@@ -161,8 +241,10 @@ export function ensureTokenlessRemote(git) {
     return { migrated: false }; // no `origin` (or not a git repo) — nothing to migrate
   }
   let migrated = false;
+  let host = "";
   try {
     const u = new URL(remote);
+    host = u.host;
     if (u.password) {
       git(["remote", "set-url", "origin", `${u.protocol}//${u.host}${u.pathname}`]);
       migrated = true;
@@ -170,15 +252,6 @@ export function ensureTokenlessRemote(git) {
   } 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;
-  }
+  if (installForgeCredentialHelper(git, { ...opts, host })) migrated = true;
   return { migrated };
 }

package/src/last-tenant.mjs

@@ -1,5 +1,5 @@
 /**
- * The "last tenant" cache for `tot start` (A4 — smart zero-arg default). After
+ * The "last tenant" cache for `tot start` (smart zero-arg default). After
  * a multi-store identity picks (or is told) a tenant, remember it here so a
  * bare `tot start` on the next run just goes instead of re-prompting.
  *

package/src/mcp.mjs

@@ -142,7 +142,12 @@ export function createMcpClient(baseUrl, opts = {}) {
     return parsed?.result;
   }
 
-  /** Call an MCP tool and unwrap its structured / text result to a plain object. */
+  /**
+   * Call an MCP tool and unwrap its structured / text result to a plain object.
+   * @param {string} name
+   * @param {unknown} [args]
+   * @returns {Promise<any>}
+   */
   async function callTool(name, args) {
     const r = await callRaw("tools/call", { name, arguments: args });
     if (r?.structuredContent) return r.structuredContent;

package/src/merge-doctor-report.mjs

@@ -0,0 +1,208 @@
+/**
+ * merge-doctor-report — the SHARED, pure rendering + one-GET fetch of the hosted
+ * merge-doctor seam (`GET /<tenant>/api/preview/merge-doctor`), so every
+ * CLI surface speaks ONE doctor taxonomy:
+ *
+ *   - `tot preview doctor` (preview-doctor.mjs) — the full, ordered report on demand.
+ *   - `tot accept` / `tot ship` (accept.mjs / ship.mjs) — the PUSH: on a failed
+ *     accept/integrate or a refused ship, auto-append the COMPACT summary right where
+ *     the failure already surfaced, so a developer doesn't have to remember to run the
+ *     doctor themselves.
+ *
+ * The render helpers here are a faithful PORT of the analyzer's own
+ * formatReport/attentionBanner/supportContext (mergeDoctor.ts §render / the
+ * scripts/tenant/gitea-merge-doctor.mjs mirror) — the published `@tokenoftrust/cli`
+ * is dependency-free and cannot import the app/scripts source, so this port is kept in
+ * sync with that taxonomy by hand.
+ *
+ * Dependency-light: `fail` + global fetch only. Imports NOTHING from the command
+ * modules (accept/ship/preview-doctor), so accept.mjs and ship.mjs can both depend on
+ * it without a cycle (preview-doctor.mjs already imports ship.mjs for the operator
+ * secret; routing the shared pieces through here keeps ship.mjs ⟷ preview-doctor.mjs
+ * acyclic).
+ */
+
+/** The hosted seam path — one GET, one answer (composed server-side over the SAME
+ *  reads the admin Publish tab builds, run through the shared analyzer). */
+export const DOCTOR_PATH = "/api/preview/merge-doctor";
+
+/** Who resolves a finding — the ticket-deflection axis. */
+export const OWNERSHIP = { developer: "developer", platform: "platform", operator: "operator" };
+export const SEV_GLYPH = { blocker: "✗", warn: "⚠", info: "•" };
+export const OWN_TAG = { developer: "you", platform: "on-us", operator: "housekeeping" };
+
+/**
+ * Defensively read the endpoint body into the analysis shape. The endpoint is a
+ * trust boundary, so a plausible field gap degrades rather than crashes. Pure.
+ * @param {any} data
+ * @returns {{ scopeKnown:boolean, verdict:string, findings:any[], counts:{blocker:number,warn:number,info:number} }}
+ */
+export function normalizeAnalysis(data) {
+  const o = data && typeof data === "object" ? data : {};
+  const findings = Array.isArray(o.findings) ? o.findings : [];
+  const c = o.counts && typeof o.counts === "object" ? o.counts : {};
+  const counts = {
+    blocker: Number.isFinite(c.blocker) ? c.blocker : findings.filter((f) => f?.severity === "blocker").length,
+    warn: Number.isFinite(c.warn) ? c.warn : findings.filter((f) => f?.severity === "warn").length,
+    info: Number.isFinite(c.info) ? c.info : findings.filter((f) => f?.severity === "info").length,
+  };
+  return {
+    scopeKnown: o.scopeKnown === true,
+    verdict: typeof o.verdict === "string" ? o.verdict : "(no verdict returned)",
+    findings,
+    counts,
+  };
+}
+
+/**
+ * The one-line banner shown at the top of the report — counts only
+ * DEVELOPER-actionable findings (what a person can self-serve); platform faults are
+ * narrated separately by {@link supportContext}. Pure.
+ */
+export function attentionBanner(result) {
+  const dev = result.findings.filter((f) => f.ownership === OWNERSHIP.developer && f.severity !== "info");
+  const fixable = dev.filter((f) => f.action).length;
+  if (!dev.length) {
+    const platform = result.findings.filter((f) => f.ownership === OWNERSHIP.platform && f.severity === "blocker");
+    if (platform.length) return `${platform.length} issue(s) are on us — Retry, then Report to support if they persist.`;
+    return "Nothing needs your attention.";
+  }
+  const conflicts = dev.filter((f) => f.code === "PR_CONFLICT").length;
+  const builds = dev.filter((f) => f.code === "NOT_BUILT_PR").length;
+  const bits = [];
+  if (conflicts) bits.push(`${conflicts} conflict(s)${conflicts <= fixable ? " (1-click fix)" : ""}`);
+  if (builds) bits.push(`${builds} need a build`);
+  return `${dev.length} change(s) need your attention: ${bits.join(", ") || "see below"}.`;
+}
+
+/**
+ * The PRE-FILLED support escalation, generated ONLY when there are PLATFORM-owned
+ * findings (a retry didn't clear it) — so "I'm stuck" becomes a structured report.
+ * Returns null when nothing is platform-owned. Pure.
+ */
+export function supportContext(result) {
+  const platform = result.findings.filter((f) => f.ownership === OWNERSHIP.platform);
+  if (!platform.length) return null;
+  const lines = [
+    `Tenant scope: ${result.scopeKnown ? "supplied" : "unknown"}`,
+    `Verdict: ${result.verdict}`,
+    "Platform-owned issues (a retry did not clear these — please investigate):",
+    ...platform.map((f) => `  • [${f.code}] ${f.subject} — ${f.detail}`),
+    "Next diagnostic hop: scripts/preview/pipeline-doctor.sh <tenant> --commit <headSha> (reconcile plane).",
+  ];
+  return lines.join("\n");
+}
+
+/** Render the analysis as the compact, ordered, agent-cheap report. Pure. */
+export function formatReport(result) {
+  const lines = [];
+  lines.push("== gitea-merge-doctor ==");
+  lines.push(`VERDICT: ${result.verdict}`);
+  lines.push(attentionBanner(result));
+  lines.push("");
+  for (const f of result.findings) {
+    const act = f.action ? `  [action: ${f.action.label}]` : "";
+    lines.push(`${SEV_GLYPH[f.severity] ?? "?"} [${f.code}] (${OWN_TAG[f.ownership] ?? f.ownership}) ${f.subject}${act}`);
+    lines.push(`    ${f.detail}`);
+    lines.push(`    → ${f.remedy}`);
+  }
+  lines.push("");
+  lines.push(
+    `${result.counts.blocker} blocker(s), ${result.counts.warn} warning(s), ${result.counts.info} info. First ✗/⚠ above is the thing to fix.`,
+  );
+  const support = supportContext(result);
+  if (support) {
+    lines.push("");
+    lines.push("── if a platform issue persists after Retry, escalate with this (no free-text “stuck”): ──");
+    lines.push(support);
+  }
+  return lines.join("\n");
+}
+
+// ── Auto-surface on failure (the PUSH) ───────────────────────────────────────
+
+/** How many findings the COMPACT summary lists before it defers the rest to the
+ *  full `tot preview doctor` report — enough to name the thing to fix, not the whole
+ *  multi-page report at a failure moment. */
+export const COMPACT_FINDING_LIMIT = 3;
+
+/**
+ * Render the COMPACT "here's what's blocking you" summary appended to a failed
+ * accept/integrate or a refused ship. Unlike {@link formatReport} (the full
+ * on-demand report), this lists ONLY the actionable (blocker/warn) findings, capped
+ * at {@link COMPACT_FINDING_LIMIT}, and points at the full report for the rest. Returns
+ * an EMPTY array when there's nothing actionable to say (a clean/info-only verdict, or
+ * no analysis at all) — so a failure whose cause the doctor can't see gets NO noise
+ * appended. Pure — returns the lines to print, never prints itself.
+ * @param {ReturnType<typeof normalizeAnalysis>|null} result
+ * @param {{ limit?: number }} [opts]
+ * @returns {string[]}
+ */
+export function formatCompactSummary(result, { limit = COMPACT_FINDING_LIMIT } = {}) {
+  if (!result || !Array.isArray(result.findings)) return [];
+  const actionable = result.findings.filter((f) => f?.severity === "blocker" || f?.severity === "warn");
+  if (!actionable.length) return [];
+  const lines = [`\n  ── merge doctor — what's blocking your merges:`];
+  lines.push(`  ${attentionBanner(result)}`);
+  for (const f of actionable.slice(0, limit)) {
+    const act = f.action?.label ? `  [${f.action.label}]` : "";
+    lines.push(`    ${SEV_GLYPH[f.severity] ?? "?"} [${f.code}] (${OWN_TAG[f.ownership] ?? f.ownership}) ${f.subject}${act}`);
+    if (f.remedy) lines.push(`      → ${f.remedy}`);
+  }
+  const more = actionable.length - limit;
+  lines.push(
+    more > 0
+      ? `    …and ${more} more — run \`tot preview doctor\` for the full report.`
+      : `    Run \`tot preview doctor\` for the full report.`,
+  );
+  return lines;
+}
+
+/**
+ * One GET to the hosted merge-doctor over an ALREADY-RESOLVED transport (the SAME
+ * `base` + `authHeaders` the calling verb used to reach `/api/changes` /
+ * `/api/changes/ship`), normalized to the analysis shape. Best-effort by contract:
+ * ANY failure (unreachable, non-2xx incl. the 401/403 an auth-refused caller would
+ * also hit, non-JSON body, a throw) resolves to `null` — the doctor is a diagnostic
+ * ADD-ON at a failure moment, so it must never itself become a second failure. Pure
+ * given the injected fetch.
+ * @param {{ base:string, authHeaders:Record<string,string> }} transport
+ * @param {typeof fetch} [fetchImpl]
+ * @returns {Promise<ReturnType<typeof normalizeAnalysis>|null>}
+ */
+export async function fetchDoctorAnalysis({ base, authHeaders }, fetchImpl = globalThis.fetch) {
+  try {
+    const res = await fetchImpl(`${String(base).replace(/\/+$/, "")}${DOCTOR_PATH}`, {
+      method: "GET",
+      headers: authHeaders,
+    });
+    if (!res || !res.ok) return null;
+    let data = {};
+    try {
+      data = await res.json();
+    } catch {
+      return null;
+    }
+    return normalizeAnalysis(data);
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * Entry point: fetch the merge-doctor over the given transport and render the
+ * COMPACT failure summary. Returns the lines to print (or `[]` when there's nothing
+ * actionable / the doctor couldn't be reached). Never throws — a caller can
+ * `for (const l of await autoSurfaceDoctor(...)) console.error(l)` unconditionally at
+ * a failure return without touching the exit code.
+ * @param {{ base:string, authHeaders:Record<string,string>, fetchImpl?:typeof fetch, limit?:number }} opts
+ * @returns {Promise<string[]>}
+ */
+export async function autoSurfaceDoctor({ base, authHeaders, fetchImpl = globalThis.fetch, limit }) {
+  try {
+    const analysis = await fetchDoctorAnalysis({ base, authHeaders }, fetchImpl);
+    return formatCompactSummary(analysis, { limit });
+  } catch {
+    return [];
+  }
+}

package/src/oauth.mjs

@@ -14,7 +14,7 @@
  *   5. exchange code -> { access_token, refresh_token, expires_in } with the PKCE
  *      verifier, and hand back a credentials record the token-store persists.
  *
- * B3 adds the RFC 8628 device-authorization grant (deviceLoginFlow, below) for
+ * This adds the RFC 8628 device-authorization grant (deviceLoginFlow, below) for
  * headless/SSH/no-browser boxes where the loopback can never be reached — same
  * dynamically-registered client_id, same credentials shape, just a different
  * dance: print a code, poll the token endpoint until it's approved elsewhere.
@@ -38,7 +38,7 @@ const b64url = (buf) =>
   buf.toString("base64").replace(/\+/g, "-").replace(/\//g, "_").replace(/=+$/, "");
 
 /** Thrown by loginFlow() when no browser opener exists on this box. Callers
- * catch it to fall through to deviceLoginFlow() (B3) instead of hanging. */
+ * catch it to fall through to deviceLoginFlow() instead of hanging. */
 export class NoOpenerError extends Error {
   constructor(authorizeUrl) {
     super("no browser opener available on this machine");
@@ -84,7 +84,7 @@ 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
+      // Include the device-code grant: the browserless rendezvous + 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: [
@@ -188,7 +188,7 @@ export function startLoopbackListener({ host = "127.0.0.1" } = {}) {
   let settle, reject;
   const callback = new Promise((res, rej) => { settle = res; reject = rej; });
   const server = http.createServer((req, res) => {
-    const u = new URL(req.url, `http://${host}`);
+    const u = new URL(req.url ?? "/", `http://${host}`);
     if (u.pathname !== "/callback") {
       res.writeHead(404, { "Content-Type": "text/plain" });
       res.end("not found");
@@ -204,12 +204,12 @@ export function startLoopbackListener({ host = "127.0.0.1" } = {}) {
       settle({ code: u.searchParams.get("code"), state: u.searchParams.get("state") });
     }
   });
-  const listening = new Promise((res, rej) => {
+  const listening = /** @type {Promise<void>} */ (new Promise((res, rej) => {
     server.once("error", rej);
     server.listen(0, host, () => res());
-  });
+  }));
   return {
-    async ready() { await listening; return server.address().port; },
+    async ready() { await listening; return /** @type {import("net").AddressInfo} */ (server.address()).port; },
     waitForCallback() { return callback; },
     close() { try { server.close(); } catch { /* already closed */ } },
   };
@@ -247,7 +247,7 @@ export async function loginFlow({
   clientId,
   fetchImpl = fetch,
   open = openBrowser,
-  log = () => {},
+  log = /** @type {(m?: string) => void} */ (() => {}),
   now = () => Date.now(),
 }) {
   const meta = await discoverMetadata(mcpUrl, fetchImpl);
@@ -266,8 +266,8 @@ export async function loginFlow({
     const opened = open(authorizeUrl);
     if (!opened) {
       // No opener on this box (headless/SSH) — the loopback can never be hit
-      // from here, so waiting on it would hang forever. Let the caller (B3:
-      // login.mjs#loginAndCache) fall through to deviceLoginFlow() instead.
+      // from here, so waiting on it would hang forever. Let the caller
+      // (login.mjs#loginAndCache) fall through to deviceLoginFlow() instead.
       throw new NoOpenerError(authorizeUrl);
     }
 
@@ -364,7 +364,7 @@ export async function rendezvousLoginFlow({
   mcpUrl,
   code,
   fetchImpl = fetch,
-  log = () => {},
+  log = /** @type {(m?: string) => void} */ (() => {}),
   sleep = delay,
   now = () => Date.now(),
 }) {
@@ -408,7 +408,7 @@ export async function rendezvousLoginFlow({
   });
 }
 
-// ── B3: device-code grant (RFC 8628) — headless/SSH/no-browser sign-in ────────
+// ── Device-code grant (RFC 8628) — headless/SSH/no-browser sign-in ────────
 
 /**
  * RFC 8628 §3.1 — request a device_code + user_code to display. Same request
@@ -474,11 +474,15 @@ async function deviceTokenPoll(tokenEndpoint, { deviceCode, clientId, codeVerifi
  * expires), honoring the server's `interval` and the `slow_down` backoff
  * (RFC 8628 §3.5: +5s, keep polling — not a failure). Injectable `sleep`/
  * `now` so it's testable with no real waiting.
+ * @param {string} tokenEndpoint
+ * @param {{ deviceCode: any, clientId: any, codeVerifier?: any, intervalSec?: any, expiresInSec?: any }} params
+ * @param {typeof fetch} [fetchImpl]
+ * @param {{ sleep?: Function, now?: () => number }} [timing]
  * @returns {Promise<object>} the raw token response (→ credentialsFromToken)
  */
 export async function pollDeviceToken(
   tokenEndpoint,
-  { deviceCode, clientId, codeVerifier, intervalSec, expiresInSec },
+  { deviceCode, clientId, codeVerifier = undefined, intervalSec, expiresInSec },
   fetchImpl = fetch,
   { sleep = delay, now = () => Date.now() } = {},
 ) {
@@ -505,7 +509,7 @@ export async function deviceLoginFlow({
   mcpUrl,
   clientId,
   fetchImpl = fetch,
-  log = () => {},
+  log = /** @type {(m?: string) => void} */ (() => {}),
   sleep = delay,
   now = () => Date.now(),
 }) {

package/src/obstacle-beacon.cjs

@@ -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 } = {}) {