@tokenoftrust/cli 1.4.0 → 1.5.0

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"):
+ *
+ *   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: `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

@@ -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
@@ -92,7 +93,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/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

@@ -0,0 +1,257 @@
+/**
+ * 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, 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
+ *  `!` 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) {
+  /** @type {Record<string,string>} */
+  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 });
+}
+
+/** 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, 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, opts = {}) {
+  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;
+  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;
+    }
+  } catch {
+    return { migrated }; // not a parseable URL (e.g. an ssh remote) — leave it alone entirely
+  }
+  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;