@tokenoftrust/cli 2.1.2 → 2.2.0

package/bin/tot.mjs

@@ -55,6 +55,7 @@ const COMMANDS = [
   { invocation: "link", blurb: "link your identity so your stores resolve" },
   { invocation: "grants", blurb: "capability/tier/expiry per store you can act on" },
   { invocation: "clone [<tenant>]", blurb: "clone a store you can build on" },
+  { invocation: "clone agency-kit [dir]", blurb: "clone the Agency Kit, read-only (needs agency access from Token of Trust)" },
   { invocation: "validate", blurb: "lint your store before you submit" },
   { invocation: "capabilities", blurb: "what the platform supports, refuses, and has not built yet" },
   { invocation: "report go-live --pages <dir>", blurb: "your store's go-live readiness report, from its page-check results" },

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@tokenoftrust/cli",
-  "version": "2.1.2",
+  "version": "2.2.0",
   "description": "Token of Trust developer CLI — clone a tenant store, run it locally with save→reload, and submit it for preview. Installs the `tot` command.",
   "license": "Apache-2.0",
   "author": "Token of Trust",

package/src/commands/clone.mjs

@@ -10,6 +10,12 @@
  *   tot clone <tenant>           clone into ./<tenant> (authenticated remote configured)
  *   tot clone <tenant> <dir>     clone into <dir>
  *   tot clone <tenant> --remote-only   just mint + print the remote, don't materialize
+ *   tot clone agency-kit [dir]   READ-ONLY clone of the Agency Kit (ADR 0037)
+ *
+ * AGENCY KIT. `agency-kit` is an alias, not a tenant: it mints through
+ * `repo_read_credential` (see READ_ONLY_ALIASES / kitReadCredentialInput) and skips
+ * every store-only step. The checkout records its kind in local git config so
+ * `tot git-credential` re-mints it the same way.
  *
  * This is the SAME MCP code path a developer gets when they switch to a tenant:
  * sign-in → client_switch(tenant) → tenant_checkout, where the MCP derives your
@@ -54,7 +60,9 @@ import { offerSignIn } from "./login.mjs";
 import { CliError, fail, formatError } from "../errors.mjs";
 import { writeNvmrc } from "../sample.mjs";
 import { emitObstacle } from "../obstacle.mjs";
-import { splitAuthedRemote, basicAuthExtraHeader, installForgeCredentialHelper } from "../git-credential.mjs";
+import {
+  splitAuthedRemote, basicAuthExtraHeader, installForgeCredentialHelper, recordReadOnlyKitCheckout,
+} from "../git-credential.mjs";
 import { recordDiagnostic } from "../diagnostics.mjs";
 
 const execFileP = promisify(execFile);
@@ -115,6 +123,8 @@ const USAGE = `tot clone — clone a tenant store you can build on (mirrors \`gi
                                 (works even on a tenant you don't own/aren't a
                                 member of, when authorized; dir defaults to
                                 <tenant>-pr<N>)
+  tot clone agency-kit [dir]   clone the Agency Kit, READ-ONLY, into ./agency-kit
+                                (needs agency access — ask Token of Trust)
 
 Options:
   --tag <tag>       deprecated compatibility input; tenant repos use the bare domain.
@@ -140,14 +150,22 @@ function makeRedactor(env) {
  * @param {string[]} argv - args AFTER `checkout`
  * @param {import("../context.mjs").detectContext extends (...a:any)=>infer R ? R : any} ctx
  */
-export async function run(argv, ctx) {
-  const env = process.env;
+export async function run(argv, ctx, deps = {}) {
+  const {
+    env = process.env, createClient = createMcpClient, establish = establishSession,
+    signIn = offerSignIn, cloneDeps = {},
+  } = deps;
   const args = parseArgs(argv);
   if (args.help) {
     console.log(USAGE);
     return 0;
   }
 
+  const alias = resolveReadOnlyAlias(args.tenant);
+  if (alias) {
+    return runReadOnlyAlias(alias, args, { env, createClient, establish, signIn, cloneDeps });
+  }
+
   // Infer the tenant from a standalone checkout when run without one.
   if (!args.tenant && ctx.mode === "checkout" && ctx.tenant) {
     args.tenant = ctx.tenant;
@@ -169,24 +187,10 @@ export async function run(argv, ctx) {
 
   const baseUrl = args.mcp || env.MCP_BASE_URL || env.TOT_MCP_URL || DEFAULT_MCP_URL;
   const redact = makeRedactor(env);
-  const client = createMcpClient(baseUrl);
+  const client = createClient(baseUrl);
 
   try {
-    // Attach auth in the right order relative to the handshake (developer bearer
-    // BEFORE initialize) — see establishSession. When there's no session yet and
-    // we're on a TTY, offer to sign in inline and retry once, so a not-signed-in
-    // developer isn't dead-ended at "run tot login, then re-run".
-    try {
-      await establishSession(client, { env });
-    } catch (e) {
-      if (e instanceof AuthUnavailableError && e.reason === "missing") {
-        const signedIn = await offerSignIn(client.mcpUrl, env, {});
-        if (!signedIn) throw e; // declined/non-TTY → the crisp error below
-        await establishSession(client, { env }); // retry once, in-flow
-      } else {
-        throw e;
-      }
-    }
+    await signInOrOffer(client, { env, establish, signIn });
     console.error(`~ signed in → ${client.mcpUrl}`);
 
     // No tenant → list the stores this identity can build on and stop.
@@ -262,17 +266,80 @@ export async function run(argv, ctx) {
     }
     return 0;
   } catch (e) {
-    if (e instanceof AuthUnavailableError) {
-      console.error(formatError(e));
-      return 1;
-    }
-    if (e instanceof CliError) {
-      console.error(formatError(e));
-      return e.exitCode ?? 1;
+    return reportFailure(e, redact);
+  }
+}
+
+/**
+ * Attach auth in the right order relative to the handshake (developer bearer BEFORE
+ * initialize) — see establishSession. When there's no session yet and we're on a TTY,
+ * offer to sign in inline and retry once, so a not-signed-in developer isn't dead-ended
+ * at "run tot login, then re-run".
+ */
+async function signInOrOffer(client, { env, establish, signIn }) {
+  try {
+    await establish(client, { env });
+  } catch (e) {
+    if (e instanceof AuthUnavailableError && e.reason === "missing") {
+      const signedIn = await signIn(client.mcpUrl, env, {});
+      if (!signedIn) throw e; // declined/non-TTY → the crisp error below
+      await establish(client, { env }); // retry once, in-flow
+    } else {
+      throw e;
     }
-    console.error(fail(`checkout failed: ${redact(String(e?.message || e))}`));
+  }
+}
+
+/** Map a thrown error to the CLI's exit + message, the same way for every clone path. */
+function reportFailure(e, redact) {
+  if (e instanceof AuthUnavailableError) {
+    console.error(formatError(e));
     return 1;
   }
+  if (e instanceof CliError) {
+    console.error(formatError(e));
+    return e.exitCode ?? 1;
+  }
+  console.error(fail(`checkout failed: ${redact(String(/** @type {any} */ (e)?.message || e))}`));
+  return 1;
+}
+
+/**
+ * `tot clone <alias> [dir]` for a read-only alias (the agency kit). Only the steps a
+ * non-store repo needs: sign-in, the read mint, the token-free clone, the helper. No store
+ * listing, client_switch, identity_bind, tenant_checkout, tenant inference, `.nvmrc` or
+ * `tot dev` guidance.
+ */
+async function runReadOnlyAlias(alias, args, { env, createClient, establish, signIn, cloneDeps }) {
+  const redact = makeRedactor(env);
+  if (args.pr) {
+    console.error(fail(`\`--pr\` does not apply to ${alias.repo}`, `tot clone ${alias.repo} [dir]`));
+    return 2;
+  }
+  const cloneDir = args.remoteOnly ? null : args.dir || alias.defaultDir;
+  const baseUrl = args.mcp || env.MCP_BASE_URL || env.TOT_MCP_URL || DEFAULT_MCP_URL;
+  const client = createClient(baseUrl);
+  try {
+    await signInOrOffer(client, { env, establish, signIn });
+    console.error(`~ signed in → ${client.mcpUrl}`);
+    console.error(`~ repo_read_credential (${alias.target}) — MCP mints a read-only credential`);
+    const res = await cloneReadOnlyAlias(client, { alias, cloneDir, redact }, cloneDeps);
+    console.log(`\n+ ready (read-only). repo: ${res.publicUrl}`);
+    if (res.cloned) {
+      console.log(`+ cloned. HEAD: ${res.head}`);
+      console.log(`\nYour read-only ${alias.repo} checkout is at ${res.dir}.`);
+      console.log(`  (it can pull, never push — \`git pull\` mints a fresh read credential each time)`);
+      return 0;
+    }
+    console.log(`\nPublic clone URL (no credential): ${res.publicUrl}`);
+    console.log(`Drop --remote-only to clone ${alias.repo} with the read-only remote configured.`);
+    if (args.printRemote) {
+      console.log(`\nREAD-ONLY remote (contains a live token — handle carefully):\n${res.gitRemote}`);
+    }
+    return 0;
+  } catch (e) {
+    return reportFailure(e, redact);
+  }
 }
 
 /**
@@ -428,8 +495,25 @@ export async function checkoutTenant(client, { tenant, tag = "main", cloneDir =
  * `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();
+/**
+ * @param {string} gitRemote
+ * @param {string} dir
+ * @param {(s: string) => string} redact
+ * @param {{
+ *   store?: boolean,
+ *   git?: (cargs: string[]) => Promise<string>,
+ *   gitSync?: (cargs: string[]) => string,
+ *   installHelper?: (git: (cargs: string[]) => string, opts: { host?: string }) => boolean,
+ *   record?: ((gitSync: (cargs: string[]) => string) => void) | null,
+ * }} [opts]
+ */
+async function cloneRepo(gitRemote, dir, redact, {
+  store = true,
+  git = async (/** @type {string[]} */ cargs) => (await execFileP("git", cargs)).stdout.toString(),
+  gitSync = (/** @type {string[]} */ cargs) => execFileSync("git", ["-C", dir, ...cargs], { encoding: "utf8" }),
+  installHelper = installForgeCredentialHelper,
+  record = null,
+} = {}) {
   console.log(`+ git clone → ${dir}`);
   const cred = splitAuthedRemote(gitRemote);
   const cloneArgs = cred
@@ -458,9 +542,7 @@ async function cloneRepo(gitRemote, dir, redact) {
   // like a missing repo rather than a credential problem. The host-scoped form writes
   // ["", <helper>]: the empty reset clears the inherited helper for this host only.
   try {
-    const gitSync = (/** @type {string[]} */ cargs) =>
-      execFileSync("git", ["-C", dir, ...cargs], { encoding: "utf8" });
-    installForgeCredentialHelper(gitSync, { host: new URL(gitRemote).host });
+    installHelper(gitSync, { host: new URL(gitRemote).host });
   } catch (error) {
     // Best-effort — never fail a good clone over credential plumbing. The next
     // `tot preview`/`tot sync` installs it, and the fetch that needs it says why.
@@ -468,11 +550,136 @@ async function cloneRepo(gitRemote, dir, redact) {
       command: "clone", operation: "credential_helper_install", required: false, degraded: true,
     });
   }
+  if (record) {
+    // Not best-effort: without the record, the credential helper cannot tell what this
+    // checkout is, so every later fetch would fail with nothing to say why.
+    try {
+      record(gitSync);
+    } catch (e) {
+      throw new CliError(`couldn't record the checkout kind in ${dir}: ${redact(String(e?.message || e))}`, {
+        next: `remove ${dir} and re-run`,
+        cause: e,
+      });
+    }
+  }
   const head = (await git(["-C", dir, "log", "-1", "--oneline"])).trim();
-  writeNvmrc(dir); // version-manager hooks land on a supported Node on cd
+  if (store) writeNvmrc(dir); // version-manager hooks land on a supported Node on cd
   return { dir, head };
 }
 
+// ─── read-only aliases: `tot clone agency-kit` ─────────────────────────────────
+
+/**
+ * Repos `tot clone` resolves by NAME rather than as a tenant store. Each is a read-only
+ * checkout minted through `repo_read_credential`; the server maps the target to its repo
+ * (ADR 0037), so the CLI never names an owner or an org. `repo` is what the minted
+ * credential must be for — anything else is refused rather than cloned.
+ */
+export const READ_ONLY_ALIASES = Object.freeze({
+  "agency-kit": Object.freeze({ target: "agency-kit", repo: "agency-kit", defaultDir: "agency-kit" }),
+});
+
+/** @param {string|null|undefined} name */
+export function resolveReadOnlyAlias(name) {
+  return name && Object.hasOwn(READ_ONLY_ALIASES, name) ? READ_ONLY_ALIASES[name] : null;
+}
+
+/** The `repo_read_credential` input for a read-only alias. The one place the wire shape
+ *  lives. `alias` is the ONLY key: the server refuses it alongside `tenant`/`repo`, and a
+ *  key the server does not declare is dropped by the MCP SDK, which then mints the caller's
+ *  own store. */
+export function kitReadCredentialInput(target) {
+  return { alias: target };
+}
+
+export const KIT_DENIED_MESSAGE = "your agency does not have kit access; ask Token of Trust";
+export const KIT_INVALID_MESSAGE = "the kit could not be requested";
+
+/** Did the server REFUSE the request (as opposed to a transport fault or an outage)?
+ *  Returns `"forbidden"`, `"invalid_input"`, or null. Reads the tool's typed status, from a
+ *  thrown tool error or a returned result; message text is never the signal. Pure. */
+export function readRefusal(source) {
+  const e = /** @type {any} */ (source);
+  if (!e) return null;
+  const category = e?.diagnostic?.category ?? e?.category;
+  if (category && category !== "tool_error") return null;
+  const status = e?.diagnostic?.serverStatus ?? e?.serverStatus ?? e?.status;
+  return status === "forbidden" || status === "invalid_input" ? status : null;
+}
+
+/** The server's own words from a failed mint, never an invented reason. */
+function serverReason(error) {
+  const e = /** @type {any} */ (error);
+  const m = e?.diagnostic?.message ?? e?.message ?? (typeof e?.error === "string" ? e.error : e?.error?.message);
+  return typeof m === "string" && m.trim() ? m.trim() : null;
+}
+
+/**
+ * Mint a read-only credential for a read-only alias. Calls ONLY `repo_read_credential` —
+ * no store tool — and refuses anything that is not a credential for the alias's own repo
+ * (a server that dropped the `alias` key would otherwise hand back the caller's own store).
+ * The server reports no expiry — it reaps the reader token after ~24h — so the helper's TTL
+ * and erase→re-mint are what bound a cached copy.
+ * @param {{ callTool: (name: string, args: unknown) => Promise<any> }} client
+ * @param {{ target: string, repo: string }} alias
+ * @param {(s: string) => string} [redact]
+ * @returns {Promise<{ gitRemote: string, publicUrl: string }>}
+ */
+export async function mintReadOnlyAlias(client, alias, redact = (s) => s) {
+  /** @param {unknown} source  the thrown error or the returned non-mint result */
+  const fail = (source, cause) => {
+    const reason = serverReason(source);
+    const said = reason ? `Token of Trust said: ${redact(reason)}` : undefined;
+    const refusal = readRefusal(source);
+    if (refusal === "forbidden") return new CliError(KIT_DENIED_MESSAGE, { next: said, cause });
+    if (refusal === "invalid_input") return new CliError(KIT_INVALID_MESSAGE, { next: said, cause });
+    return new CliError(`the ${alias.repo} credential couldn't be minted${reason ? `: ${redact(reason)}` : ""}`, {
+      next: "check your connection and `tot whoami`, then re-run",
+      cause,
+    });
+  };
+  let minted;
+  try {
+    minted = await client.callTool("repo_read_credential", kitReadCredentialInput(alias.target));
+  } catch (e) {
+    throw fail(e, e);
+  }
+  const m = /** @type {any} */ (minted && typeof minted === "object" ? minted : {});
+  const repos = Array.isArray(m.repos) ? m.repos : [];
+  if (!repos.some((r) => r && r.gitRemote)) throw fail(m, undefined);
+  const target = repos.find((r) => r && r.repo === alias.repo && r.gitRemote);
+  if (!target) {
+    throw new CliError(`Token of Trust returned no credential for ${alias.repo}`, {
+      next: "this server may not support kit checkout yet — ask Token of Trust",
+    });
+  }
+  const gitRemote = String(target.gitRemote);
+  const u = new URL(gitRemote);
+  return {
+    gitRemote,
+    publicUrl: `${u.protocol}//${u.host}${u.pathname}`,
+  };
+}
+
+/**
+ * `tot clone agency-kit [dir]`: mint the read-only credential, clone token-free through a
+ * one-shot `http.extraheader`, install the host-scoped credential helper, and record the
+ * checkout as a read-only kit clone so the helper re-mints it the same way.
+ * @param {{ callTool: (name: string, args: unknown) => Promise<any> }} client
+ * @param {{ alias: { target: string, repo: string }, cloneDir?: string|null, redact?: (s:string)=>string }} opts
+ * @param {Parameters<typeof cloneRepo>[3]} [deps]
+ */
+export async function cloneReadOnlyAlias(client, { alias, cloneDir = null, redact = (s) => s }, deps = {}) {
+  const { gitRemote, publicUrl } = await mintReadOnlyAlias(client, alias, redact);
+  if (!cloneDir) return { gitRemote, publicUrl, cloned: false, dir: null, head: null };
+  const { dir, head } = await cloneRepo(gitRemote, cloneDir, redact, {
+    ...deps,
+    store: false,
+    record: (gitSync) => recordReadOnlyKitCheckout(gitSync, alias.target),
+  });
+  return { gitRemote, publicUrl, cloned: true, dir, head };
+}
+
 /**
  * The cross-tenant PR-clone core, composable in-process exactly like
  * `checkoutTenant`: mint a READ-ONLY credential via `repo_read_credential`, then

package/src/commands/git-credential.mjs

@@ -12,11 +12,15 @@
  * 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).
+ * request on stdin (key=value lines, blank-line/EOF terminated). `get` mints
+ * (or reuses the short-lived cache in ../git-credential.mjs); `erase`, which git
+ * sends when the forge rejected the credential, drops that cache so the next
+ * `get` re-mints; `store` is a no-op.
+ *
+ * Two checkout kinds: a tenant store (its `.tot/config.json`) mints a push
+ * credential through `tenant_checkout`; a read-only kit clone (recorded in local
+ * git config by `tot clone agency-kit`) mints through `repo_read_credential`,
+ * cached under a key a store's can never take.
  *
  * 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
@@ -34,12 +38,13 @@ 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 { checkoutTenant, mintReadOnlyAlias, resolveReadOnlyAlias } from "./clone.mjs";
 import { detectContext } from "../context.mjs";
 import { repoNameFromRemote, tagFromRepoName } from "./submit.mjs";
 import {
   parseCredentialInput, formatCredentialOutput, splitAuthedRemote,
   credentialCachePath, readCachedCredential, writeCachedCredential,
+  kitCredentialCachePath, dropCachedCredential, readCheckoutKind, READ_ONLY_KIT_KIND,
 } from "../git-credential.mjs";
 
 const DEFAULT_MCP_URL = "https://mcp.tokenoftrust.com";
@@ -97,13 +102,38 @@ export function readStdin() {
  *   createClient?: typeof createMcpClient,
  *   establish?: typeof establishSession,
  *   checkout?: typeof checkoutTenant,
+ *   mintReadOnly?: typeof mintReadOnlyAlias,
  * }} [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,
+  mintReadOnly = mintReadOnlyAlias,
 } = {}) {
+  const kit = kitCheckout(cwd);
+  if (kit) {
+    if (expectedHost && !hostMatches(kit.originUrl, expectedHost)) return null;
+    const alias = resolveReadOnlyAlias(kit.target);
+    if (!alias) return null; // a recorded target this CLI does not know — never guess a mint
+    const cachePath = kitCredentialCachePath(alias.target, 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 });
+      const res = await mintReadOnly(client, alias);
+      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; // not signed in / MCP unreachable / no kit access — say nothing
+    }
+  }
+
   const ctx = detectContext(cwd);
   if (ctx.mode !== "checkout" || !ctx.tenant) return null;
 
@@ -143,6 +173,52 @@ export async function mintOrCacheCredential({
   }
 }
 
+/**
+ * The read-only kit checkout `cwd` is in, from the kind `tot clone` recorded, or null when
+ * it is not one (a store, a loose dir, not a repo). Never throws.
+ * @param {string} cwd
+ * @returns {{ target: string, originUrl: string|null }|null}
+ */
+export function kitCheckout(cwd) {
+  const git = (cargs) =>
+    execFileSync("git", ["-C", cwd, ...cargs], { stdio: ["ignore", "pipe", "pipe"] }).toString();
+  const kind = readCheckoutKind(git);
+  if (kind.kind !== READ_ONLY_KIT_KIND) return null;
+  let originUrl = null;
+  try { originUrl = git(["remote", "get-url", "origin"]).trim(); } catch { /* host check fails closed */ }
+  return { target: kind.target, originUrl };
+}
+
+/**
+ * git reported the credential rejected (`erase`): drop this checkout's cached credential so
+ * the next `get` mints a fresh one instead of replaying the rejected token. Scoped to the
+ * checkout's own origin host, like `get`. Never throws.
+ * @param {{ env?: NodeJS.ProcessEnv, cwd?: string, expectedHost?: string|null }} [opts]
+ */
+export function forgetCredential({ env = process.env, cwd = process.cwd(), expectedHost = null } = {}) {
+  try {
+    const kit = kitCheckout(cwd);
+    if (kit) {
+      if (expectedHost && !hostMatches(kit.originUrl, expectedHost)) return;
+      dropCachedCredential(kitCredentialCachePath(kit.target, env));
+      return;
+    }
+    const ctx = detectContext(cwd);
+    if (ctx.mode !== "checkout" || !ctx.tenant || !ctx.workspacePath) return;
+    let originUrl = null;
+    try {
+      originUrl = execFileSync("git", ["-C", ctx.workspacePath, "remote", "get-url", "origin"], {
+        stdio: ["ignore", "pipe", "pipe"],
+      }).toString().trim();
+    } catch { /* no origin */ }
+    if (expectedHost && !hostMatches(originUrl, expectedHost)) return;
+    const tag = tagFromRepoName(originUrl ? repoNameFromRemote(originUrl) : null, ctx.tenant);
+    dropCachedCredential(credentialCachePath(ctx.tenant, tag, env));
+  } catch {
+    /* erase is advisory — never fail git over it */
+  }
+}
+
 const USAGE = `tot git-credential — git credential-helper protocol over your \`tot login\` session
 
   Configured automatically by \`tot clone\` (credential.helper = !tot git-credential)
@@ -169,7 +245,12 @@ export async function run(argv, _ctx, opts = {}) {
   // 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.
+  if (op === "erase") {
+    // git rejected the credential it was given: forget it, so the next `get` re-mints.
+    forgetCredential({ env, cwd: opts.cwd, expectedHost: request.host });
+    return 0;
+  }
+  if (op !== "get") return 0; // store: stateless, nothing to persist.
 
   const cred = await mintOrCacheCredential({ ...opts, expectedHost: request.host });
   if (!cred) return 1; // silent — let git fall through to its next helper / its own prompt.

package/src/commands/report.mjs

@@ -27,7 +27,7 @@ import { validateTenant, ERROR } from "../validate.mjs";
 import { fail } from "../errors.mjs";
 import { tenantDirSegments } from "../tenant-dirs.mjs";
 
-export const TEASER = "Site-wide validation with triage across every page, and the full migration method, are in the Agency Kit.";
+export const TEASER = "Site-wide validation with triage across every page, and the full migration method, are in the Agency Kit. To get it, ask Token of Trust for agency access, then run `tot clone agency-kit`.";
 
 export const USAGE = `tot report go-live — the go-live readiness report for your store
 

package/src/git-credential.mjs

@@ -20,7 +20,7 @@
 import { homedir } from "node:os";
 import { createHash } from "node:crypto";
 import { join, dirname } from "node:path";
-import { mkdirSync, writeFileSync, chmodSync } from "node:fs";
+import { mkdirSync, writeFileSync, chmodSync, rmSync } from "node:fs";
 import { readCredentials, writeCredentials } from "./token-store.mjs";
 
 /** The git config value that routes credential requests through `tot` — the
@@ -122,12 +122,69 @@ export function credentialCachePath(tenant, tag, env = process.env) {
   return join(home, ".tot", "git-credentials", `${credentialCacheKey(tenant, tag)}.json`);
 }
 
+/** Cache key for a READ-ONLY kit checkout's credential. The `kit-` prefix is the
+ *  separation: a tenant store's key is always 32 bare hex characters, so no tenant or tag
+ *  (however named) can produce a file name this function produces, or the reverse. Pure. */
+export function kitCredentialCacheKey(target) {
+  return `kit-${createHash("sha256").update(`kit|${target}`).digest("hex").slice(0, 32)}`;
+}
+
+/** Absolute path to a read-only kit checkout's cached credential. */
+export function kitCredentialCachePath(target, env = process.env) {
+  const home = env.TOT_HOME || homedir();
+  return join(home, ".tot", "git-credentials", `${kitCredentialCacheKey(target)}.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);
 }
 
+/** Drop a cached credential (git reported it rejected). Never throws. */
+export function dropCachedCredential(filePath) {
+  try {
+    rmSync(filePath, { force: true });
+  } catch {
+    /* nothing cached, or unremovable — the next `get` re-mints either way */
+  }
+}
+
+/** The checkout kinds `tot` records in a checkout's local git config. A tenant store
+ *  carries none (it is recognized by its `.tot/config.json`); a read-only kit clone is
+ *  recorded explicitly, because nothing else in it says what to mint. */
+export const CHECKOUT_KIND_KEY = "tot.checkoutKind";
+export const READ_TARGET_KEY = "tot.readTarget";
+export const READ_ONLY_KIT_KIND = "read-only-kit";
+
+/**
+ * Record in a freshly cloned checkout that it is a read-only kit clone of `target`, so
+ * `tot git-credential` re-mints it through `repo_read_credential` instead of treating it
+ * as a store. Throws on a git failure (the caller decides how loud to be).
+ * @param {(cargs: string[]) => unknown} git  a `git -C <checkout>` runner
+ * @param {string} target
+ */
+export function recordReadOnlyKitCheckout(git, target) {
+  git(["config", "--local", CHECKOUT_KIND_KEY, READ_ONLY_KIT_KIND]);
+  git(["config", "--local", READ_TARGET_KEY, target]);
+}
+
+/**
+ * Read which kind of checkout `git` runs in: `{ kind: "read-only-kit", target }` for a
+ * recorded kit clone, else `{ kind: "store" }` (the default; the store path then applies
+ * its own checks). An unrecorded or unreadable config is a store, never a kit.
+ * @param {(cargs: string[]) => string} git
+ * @returns {{ kind: "read-only-kit", target: string } | { kind: "store" }}
+ */
+export function readCheckoutKind(git) {
+  const get = (key) => {
+    try { return String(git(["config", "--local", "--get", key])).trim(); } catch { return ""; }
+  };
+  if (get(CHECKOUT_KIND_KEY) !== READ_ONLY_KIT_KIND) return { kind: "store" };
+  const target = get(READ_TARGET_KEY);
+  return target ? { kind: READ_ONLY_KIT_KIND, target } : { kind: "store" };
+}
+
 /** 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 = {}) {

package/src/mcp.mjs

@@ -315,6 +315,9 @@ export function createMcpClient(baseUrl, opts = {}) {
       throw diagnosticError(`${name} failed: ${message}`, {
         operation: name, category: "tool_error",
         serverCode: payload?.code || payload?.error?.code,
+        // The tool's own outcome (`forbidden`, `unauthenticated`, …) — the typed signal a
+        // caller classifies a refusal by, instead of matching message text.
+        serverStatus: typeof payload?.status === "string" ? payload.status : undefined,
         message,
         traceId: payload?.traceId || responseContext.traceId,
         requestId: payload?.requestId || responseContext.requestId,