@needmoretruth/nmts-cli 0.17.2 → 0.34.1

package/dist/account-proof.d.ts

@@ -0,0 +1,29 @@
+import type { CredentialSource } from "./credentials.ts";
+/**
+ * The proof value for one NMTS key, base64url of 32 bytes.
+ *
+ * ⛔ NO POLICY HERE. Whether this run may build one is decided by `accountProofFor` below; keeping
+ *    the arithmetic separate from the permission is what lets a test drive each without the other.
+ */
+export declare function accountProof(code: string): Promise<string>;
+/** A run's NMTS key together with where this machine got it from. */
+export interface CodeInHand {
+    code: string;
+    source: CredentialSource;
+}
+/**
+ * The proof for this run — asked for, never assumed.
+ *
+ * ⛔ THE AGREEMENT IS `plain-env`, AND IT IS THE ONE THAT ALREADY COVERS THIS. Its words are
+ *    exactly "use the NMTS key from a plain environment variable", which is what a run does
+ *    when it turns `NMTS_ACCOUNT_CODE` into a value it sends. A sixth consent key is not the
+ *    answer: `consent.ts` says in its header why the count is five and that adding to it is a
+ *    decision rather than a tidy-up, and the bar it sets — undoable, costly, or the code somewhere
+ *    that is not this tool's sealed file — is met by the existing key rather than by a new one.
+ *
+ * ⛔ ASKED HERE AND NOT ONLY WHERE THE CODE WAS READ. `code-access.ts` does require it when it
+ *    reads that variable, and its own header says why a rule enforced at each call site has as
+ *    many holes as there are call sites. This is the call site that SENDS something, so it asks
+ *    for itself; an already-granted agreement costs a file read and no question.
+ */
+export declare function accountProofFor(held: CodeInHand): Promise<string>;

package/dist/account-proof.js

@@ -1,4 +1,4 @@
-// Proving possession of the account code to a server that already trusts this machine's API key.
+// Proving possession of the NMTS key to a server that already trusts this machine's API key.
 //
 // ⛔ WHY A SECOND PROOF EXISTS AT ALL. Three routes rebuild an account's disaster-recovery
 //    artefacts — the dump every recovery list is assembled from, and the two records that say a
@@ -8,7 +8,7 @@
 //
 // ⛔ WHAT THE VALUE IS, AND WHY SENDING IT IS SAFE. It is `authSecret` — bytes [16,48) of the
 //    derivation (NCF-3 §1), the SAME 32 bytes every sign-in sends, over TLS, for the server to
-//    check against the argon2id verifier it stores. It is not the account code and it decrypts
+//    check against the argon2id verifier it stores. It is not the NMTS key and it decrypts
 //    nothing: `dataKey`, the file keys, the file-list key and the wallet root are different slices
 //    of the same output and none of them reach this or any other request. Deriving it is one-way,
 //    so a server that holds it cannot work back to the code.
@@ -20,14 +20,14 @@
 //    module returns a string, no caller stores it, and `api.ts` puts it in one header and nowhere
 //    else — not a URL, not a message, not a log line.
 //
-// ⛔ THE ACCOUNT CODE ITSELF STAYS HERE. It is not an argument to anything, it is not in the
+// ⛔ THE NMTS KEY ITSELF STAYS HERE. It is not an argument to anything, it is not in the
 //    header, and the buffers the derivation produces are wiped on every path out — including the
 //    failing one. The derivation output is not an account id: it is every key in the account.
 import { requireConsent } from "./consent.js";
 import { DERIVED, loadCrypto } from "./crypto.js";
 import { NmtsError } from "./errors.js";
 /**
- * The proof value for one account code, base64url of 32 bytes.
+ * The proof value for one NMTS key, base64url of 32 bytes.
  *
  * ⛔ NO POLICY HERE. Whether this run may build one is decided by `accountProofFor` below; keeping
  *    the arithmetic separate from the permission is what lets a test drive each without the other.
@@ -40,7 +40,7 @@ export async function accountProof(code) {
     }
     catch {
         // ⛔ The engine's own message is not repeated: it can contain the input.
-        throw new NmtsError("That is not a valid NMTS account code.", {
+        throw new NmtsError("That is not a valid NMTS key.", {
             exitCode: 2,
             nextStep: "Check for a mistyped or missing character. The last character is a check symbol.",
         });
@@ -60,7 +60,7 @@ export async function accountProof(code) {
  * The proof for this run — asked for, never assumed.
  *
  * ⛔ THE AGREEMENT IS `plain-env`, AND IT IS THE ONE THAT ALREADY COVERS THIS. Its words are
- *    exactly "use the account code from a plain environment variable", which is what a run does
+ *    exactly "use the NMTS key from a plain environment variable", which is what a run does
  *    when it turns `NMTS_ACCOUNT_CODE` into a value it sends. A sixth consent key is not the
  *    answer: `consent.ts` says in its header why the count is five and that adding to it is a
  *    decision rather than a tidy-up, and the bar it sets — undoable, costly, or the code somewhere

package/dist/account.d.ts

@@ -0,0 +1,18 @@
+export interface AccountIdentity {
+    /** Base64url of the 16 bytes the server knows this account by. Public. */
+    accountId: string;
+    /** The address other people use to share with this account. Public. */
+    publicCode: string;
+    /** The NMTS key as it is meant to be read, in groups. NOT printed by default. */
+    displayCode: string;
+}
+/**
+ * Check that a string is a real NMTS key.
+ *
+ * ⛔ This is the engine's own parser, which verifies the trailing check symbol. A typo therefore
+ *    fails HERE, offline, instead of becoming a sign-in failure the person cannot tell apart from
+ *    a wrong password, a network problem or a suspended account.
+ */
+export declare function assertUsableCode(code: string): Promise<void>;
+/** Derive the public facts about an account from its code. */
+export declare function identityOf(code: string): Promise<AccountIdentity>;

package/dist/account.js

@@ -1,4 +1,4 @@
-// What an account code says about itself, computed on this machine and nowhere else.
+// What an NMTS key says about itself, computed on this machine and nowhere else.
 //
 // ⛔ EVERY VALUE HERE IS DERIVED LOCALLY. None of it is asked of a server, and none of it needs
 //    one: that is the property the whole product rests on, and it is why `whoami` can answer
@@ -12,7 +12,7 @@
 // ⚠ TWO OTHER MODULES DERIVE `authSecret`, AND THEY ARE NAMED HERE SO THIS PARAGRAPH STAYS TRUE.
 //   `registration.ts` builds it for the single call that CREATES an account, because the server
 //   has to be given it once to store a verifier of it. `account-proof.ts` builds it for the three
-//   recovery routes that ask a key to prove the account code as well — the same value a sign-in
+//   recovery routes that ask a key to prove the NMTS key as well — the same value a sign-in
 //   sends, and its own header says why sending it is safe and what it can still do if it is
 //   stolen. Neither returns it to anything else, and nothing here changed: this module still does
 //   not hand it out. ⚠ `dataKey` is a different matter and is NOT returned by anything, here or
@@ -21,7 +21,7 @@
 import { DERIVED, loadCrypto } from "./crypto.js";
 import { NmtsError } from "./errors.js";
 /**
- * Check that a string is a real account code.
+ * Check that a string is a real NMTS key.
  *
  * ⛔ This is the engine's own parser, which verifies the trailing check symbol. A typo therefore
  *    fails HERE, offline, instead of becoming a sign-in failure the person cannot tell apart from
@@ -34,7 +34,7 @@ export async function assertUsableCode(code) {
     }
     catch {
         // ⛔ The engine's own message is not repeated: it can contain the input.
-        throw new NmtsError("That is not a valid NMTS account code.", {
+        throw new NmtsError("That is not a valid NMTS key.", {
             exitCode: 2,
             nextStep: "Check for a mistyped or missing character. The last character is a check symbol.",
         });
@@ -48,7 +48,7 @@ export async function identityOf(code) {
         bytes = glue.account_code_parse(code);
     }
     catch {
-        throw new NmtsError("That is not a valid NMTS account code.", {
+        throw new NmtsError("That is not a valid NMTS key.", {
             exitCode: 2,
             nextStep: "Check for a mistyped or missing character. The last character is a check symbol.",
         });

package/dist/agent-host.d.ts

@@ -0,0 +1,71 @@
+/** The hosts this version knows by name. Anything else is reported as unrecognised, never guessed. */
+export type HostId = "claude-code" | "codex" | "opencode" | "hermes" | "openclaw";
+/** What a host calls itself where a person would see it. */
+export declare const HOST_NAMES: Readonly<Record<HostId, string>>;
+export interface HostSighting {
+    id: HostId;
+    /**
+     * `parent` — this host is on the other end of the pipe. `ancestor` — this host is somewhere above
+     * us, possibly several processes up. ⛔ Never collapse the two: the second is what an inherited
+     * environment variable can honestly claim, and treating it as the first is how a tool running
+     * inside two agents names the wrong one.
+     */
+    relation: "parent" | "ancestor";
+    /** The marker that was found, named so the reader can check it. */
+    by: string;
+    /** The host's own version where the signal carried a usable one. */
+    version: string | null;
+}
+/**
+ * Does this host wash the environment when it starts an MCP server?
+ *
+ * ⛔ MEASURED FROM EACH PROJECT'S SOURCE, not from behaviour we hope for:
+ *      · Codex `env_clear()` then an eleven-name allow-list (`rmcp-client/src/utils.rs`).
+ *      · Hermes an eight-name `_SAFE_ENV_KEYS` (`tools/mcp_tool.py`), documented as deliberate.
+ *      · OpenClaw the MCP SDK's own six-name default (`agents/mcp-stdio-transport.ts`).
+ *      · Claude Code and opencode pass the parent environment through.
+ *    ⚠ The two that pass it through do so BY CHOICE — the SDK default they build on is the same
+ *      six names. This says what they do today, and nothing about what they promise.
+ */
+export declare const WASHES_ENVIRONMENT: Readonly<Record<HostId, boolean>>;
+/**
+ * Every host whose marker is in this environment.
+ *
+ * ⛔ A LIST, NOT AN ANSWER. Markers accumulate: an agent inside an agent leaves both, and that was
+ *    seen while measuring (`OPENCODE=1` and `CLAUDECODE=1` arrived together). Returning the first
+ *    match would name whichever host this function happens to test first.
+ */
+export declare function hostsInEnvironment(env?: NodeJS.ProcessEnv): HostSighting[];
+/** What an MCP client sends about itself in `initialize`. Only these two fields are ever read. */
+export interface ClientInfo {
+    name?: unknown;
+    version?: unknown;
+}
+/**
+ * Who is on the other end of this MCP pipe.
+ *
+ * ⛔ `mcp` IS NOT A HOST. It is the Python MCP SDK's default name, so every client built on that
+ *    SDK that does not set its own arrives calling itself that — Hermes among them. Reading it as
+ *    a host name would put a confident wrong name on the screen, which is worse than an empty one.
+ */
+export declare function hostFromClientInfo(info: ClientInfo | undefined): HostSighting | null;
+/**
+ * Hermes, and only on Linux.
+ *
+ * ⛔ IT IS THE ONLY HOST WITH NO MARKER OF ITS OWN IN EITHER OTHER PLACE. It washes the environment
+ *    and it never sets `clientInfo`, so what is left is the shape of the process that started us:
+ *    on POSIX it inserts a watchdog written in Python between itself and the server. Windows gets
+ *    no wrapper and therefore no signal — `null` there is "not measurable", not "not Hermes".
+ */
+export declare function hermesFromParent(readParentCommand?: () => string | null): HostSighting | null;
+/** The parent's command line on Linux, or `null` anywhere the question cannot be asked. */
+export declare function readLinuxParentCommand(): string | null;
+/**
+ * The one thing an agent has to know before it plans anything: can a secret reach this process
+ * through the environment at all?
+ *
+ * Returns the hosts that would have washed it away, or an empty list when nothing here washes.
+ */
+export declare function washingHosts(sightings: readonly HostSighting[]): HostId[];
+/** One sighting in the words the `env` command prints. */
+export declare function describeSighting(s: HostSighting): string;

package/dist/agent-host.js

@@ -0,0 +1,169 @@
+// Which agent is running this tool, measured rather than assumed.
+//
+// ⛔ WHY IT MATTERS AND IS NOT COSMETIC. Three of the five hosts below CLEAR THE ENVIRONMENT before
+//    they start an MCP server and put back only a fixed allow-list. `NMTS_ACCOUNT_CODE`,
+//    `NMTS_ACCOUNT_CODE_FILE` and the passphrase variable are not on any of those lists, so under
+//    Codex, Hermes and OpenClaw they DO NOT ARRIVE — however carefully the person exported them.
+//    That is a fact worth saying before the first upload rather than after it.
+//
+// ⛔ TWO DIFFERENT QUESTIONS, AND THEY HAVE DIFFERENT ANSWERS.
+//      · An environment marker says "one of my ancestors is this host". It is inherited by every
+//        descendant, so an agent that starts a shell that starts another agent leaves both markers
+//        standing. It never proves who started US.
+//      · MCP `initialize` carries `clientInfo`, which comes from the process on the other end of
+//        this pipe. That one IS the direct parent, and it survives the washing above because it
+//        travels over the protocol rather than in the environment.
+//    So the two are reported separately and never merged into one confident answer.
+//
+// ⛔ NOTHING HERE IS A SECURITY BOUNDARY. Every marker below can be set by anything, and one of
+//    them (Codex's `CODEX_PERMISSION_PROFILE`) says so in its own source comment. This tells an
+//    agent what to expect; it never decides what is allowed.
+//
+// ⚠ MEASURED 2026-08-31 against Claude Code 2.1.251, Codex 0.151.0, opencode 1.18.25,
+//   Hermes 0.20.6 and OpenClaw 2026.8.1 — each from that project's own source or documentation.
+//   A host that changes its markers will simply stop being recognised, which is the safe direction:
+//   an unrecognised host reports nothing rather than reporting the wrong name.
+import { readFileSync } from "node:fs";
+import { platform } from "node:os";
+/** What a host calls itself where a person would see it. */
+export const HOST_NAMES = {
+    "claude-code": "Claude Code",
+    codex: "Codex",
+    opencode: "opencode",
+    hermes: "Hermes",
+    openclaw: "OpenClaw",
+};
+/**
+ * Does this host wash the environment when it starts an MCP server?
+ *
+ * ⛔ MEASURED FROM EACH PROJECT'S SOURCE, not from behaviour we hope for:
+ *      · Codex `env_clear()` then an eleven-name allow-list (`rmcp-client/src/utils.rs`).
+ *      · Hermes an eight-name `_SAFE_ENV_KEYS` (`tools/mcp_tool.py`), documented as deliberate.
+ *      · OpenClaw the MCP SDK's own six-name default (`agents/mcp-stdio-transport.ts`).
+ *      · Claude Code and opencode pass the parent environment through.
+ *    ⚠ The two that pass it through do so BY CHOICE — the SDK default they build on is the same
+ *      six names. This says what they do today, and nothing about what they promise.
+ */
+export const WASHES_ENVIRONMENT = {
+    "claude-code": false,
+    codex: true,
+    opencode: false,
+    hermes: true,
+    openclaw: true,
+};
+/**
+ * Claude Code writes its version into `AI_AGENT` with the dots turned into hyphens
+ * (`claude-code_2-1-251_harness`). Reading it back is worth doing only when the value still starts
+ * with that host's own prefix — Claude Code leaves an outer host's `AI_AGENT` alone, so any other
+ * shape belongs to somebody else and its middle field is not a Claude Code version.
+ */
+function claudeVersionFrom(aiAgent) {
+    if (aiAgent === undefined || !aiAgent.startsWith("claude-code_"))
+        return null;
+    const middle = aiAgent.split("_")[1];
+    if (middle === undefined || !/^[0-9]+(-[0-9]+)*$/.test(middle))
+        return null;
+    return middle.replaceAll("-", ".");
+}
+/**
+ * Every host whose marker is in this environment.
+ *
+ * ⛔ A LIST, NOT AN ANSWER. Markers accumulate: an agent inside an agent leaves both, and that was
+ *    seen while measuring (`OPENCODE=1` and `CLAUDECODE=1` arrived together). Returning the first
+ *    match would name whichever host this function happens to test first.
+ */
+export function hostsInEnvironment(env = process.env) {
+    const out = [];
+    const seen = (id, by, version = null) => out.push({ id, relation: "ancestor", by, version });
+    if (env["CLAUDECODE"] === "1")
+        seen("claude-code", "CLAUDECODE=1", claudeVersionFrom(env["AI_AGENT"]));
+    // ⛔ `CODEX_SANDBOX` is NOT here: Codex sets it only when a sandbox is in use, so its absence
+    //    means nothing at all. These two are set for every child of the shell tool.
+    if ((env["CODEX_THREAD_ID"] ?? "") !== "")
+        seen("codex", "CODEX_THREAD_ID");
+    else if ((env["CODEX_SESSION_ID"] ?? "") !== "")
+        seen("codex", "CODEX_SESSION_ID");
+    if (env["OPENCODE"] === "1")
+        seen("opencode", "OPENCODE=1");
+    if (env["HERMES_AGENT"] === "true")
+        seen("hermes", "HERMES_AGENT=true");
+    else if ((env["HERMES_SESSION_ID"] ?? "") !== "")
+        seen("hermes", "HERMES_SESSION_ID");
+    if (env["OPENCLAW_CLI"] === "1")
+        seen("openclaw", "OPENCLAW_CLI=1");
+    else if ((env["OPENCLAW_SHELL"] ?? "") !== "")
+        seen("openclaw", "OPENCLAW_SHELL");
+    // ⛔ `AI_AGENT` on its own is deliberately not read. Claude Code and Hermes both write it with
+    //    `${AI_AGENT:-…}`, so it holds the OUTERMOST host's name and answers a question nobody asked.
+    return out;
+}
+/**
+ * Who is on the other end of this MCP pipe.
+ *
+ * ⛔ `mcp` IS NOT A HOST. It is the Python MCP SDK's default name, so every client built on that
+ *    SDK that does not set its own arrives calling itself that — Hermes among them. Reading it as
+ *    a host name would put a confident wrong name on the screen, which is worse than an empty one.
+ */
+export function hostFromClientInfo(info) {
+    const name = typeof info?.name === "string" ? info.name : "";
+    if (name === "")
+        return null;
+    const version = typeof info?.version === "string" && info.version !== "" ? info.version : null;
+    const at = (id, useVersion) => ({ id, relation: "parent", by: `clientInfo.name=${name}`, version: useVersion ? version : null });
+    if (name === "claude-code")
+        return at("claude-code", true);
+    // The crate that speaks MCP is versioned separately from the Codex release, so its number is not
+    // the version a person would recognise and is left out rather than shown as one.
+    if (name === "codex-mcp-client")
+        return at("codex", false);
+    if (name === "opencode")
+        return at("opencode", true);
+    // ⛔ Pinned to "0.0.0" in OpenClaw's main path, so the field is present and meaningless.
+    if (name.startsWith("openclaw-"))
+        return at("openclaw", false);
+    return null;
+}
+/**
+ * Hermes, and only on Linux.
+ *
+ * ⛔ IT IS THE ONLY HOST WITH NO MARKER OF ITS OWN IN EITHER OTHER PLACE. It washes the environment
+ *    and it never sets `clientInfo`, so what is left is the shape of the process that started us:
+ *    on POSIX it inserts a watchdog written in Python between itself and the server. Windows gets
+ *    no wrapper and therefore no signal — `null` there is "not measurable", not "not Hermes".
+ */
+export function hermesFromParent(readParentCommand = readLinuxParentCommand) {
+    const command = readParentCommand();
+    if (command === null || !command.includes("mcp_stdio_watchdog.py"))
+        return null;
+    return { id: "hermes", relation: "parent", by: "the parent process runs mcp_stdio_watchdog.py", version: null };
+}
+/** The parent's command line on Linux, or `null` anywhere the question cannot be asked. */
+export function readLinuxParentCommand() {
+    if (platform() !== "linux")
+        return null;
+    try {
+        return readFileSync(`/proc/${process.ppid}/cmdline`, "utf8").replaceAll("\0", " ").trim();
+    }
+    catch {
+        return null;
+    }
+}
+/**
+ * The one thing an agent has to know before it plans anything: can a secret reach this process
+ * through the environment at all?
+ *
+ * Returns the hosts that would have washed it away, or an empty list when nothing here washes.
+ */
+export function washingHosts(sightings) {
+    const ids = new Set();
+    for (const s of sightings)
+        if (WASHES_ENVIRONMENT[s.id])
+            ids.add(s.id);
+    return [...ids];
+}
+/** One sighting in the words the `env` command prints. */
+export function describeSighting(s) {
+    const version = s.version === null ? "" : ` ${s.version}`;
+    const relation = s.relation === "parent" ? "started this server" : "is running somewhere above this process";
+    return `${HOST_NAMES[s.id]}${version} ${relation} (${s.by})`;
+}

package/dist/api-advice.d.ts

@@ -0,0 +1,2 @@
+/** What a caller does next about a refusal, when the tool knows something the message does not. */
+export declare function adviseFor(code: string): string | null;

package/dist/api-advice.js

@@ -0,0 +1,210 @@
+// What a caller does next about a refusal the server explained.
+//
+// ⛔ IT LIVES BESIDE `api.ts` RATHER THAN INSIDE IT. This is one table with one job — a code in, a
+//    sentence out — and it had grown to be most of the file it sat in, which is why the request
+//    path there had no room left to learn anything new. Splitting on this line leaves each file
+//    readable as one thing.
+//
+// ⛔ `check:advice` READS THIS FILE'S SWITCH and compares it, as a set, against every code
+//    `api/src/error.rs` can send. A code in neither this table nor that gate's SILENT list is not
+//    a decision, it is an oversight — so moving this table means moving what the gate reads, and
+//    both moved together.
+//
+// ⛔ EACH SENTENCE NAMES ONE NEXT STEP, OR SAYS THERE IS NONE. "Unauthorized" tells an agent
+//    nothing it can act on; "this key was revoked — make a new one" tells it whether to retry, to
+//    ask a person, or to stop. Several entries exist only to stop an agent from retrying the one
+//    remedy that cannot possibly work.
+/** What a caller does next about a refusal, when the tool knows something the message does not. */
+export function adviseFor(code) {
+    switch (code) {
+        case "CLEARANCE_REQUIRED":
+        case "TURNSTILE_FAILED":
+            return ("This account needs a human check, which a command-line tool cannot pass. An API key " +
+                "made on the account screen is what waives it — put it in NMTS_API_KEY. If that screen " +
+                "has no place to make one, this server does not have API keys switched on.");
+        case "UNAUTHORIZED":
+            return "The credential is missing or expired. Check NMTS_API_KEY, or make a new key.";
+        // ⛔ Each of these says something different on purpose, because the remedies are different
+        //    and a program that cannot tell them apart will retry the one thing that cannot work.
+        case "SESSION_REVOKED":
+            return "That is a browser session somebody ended from another device, not an API key. A key is what a program should carry; NMTS_API_KEY is where it goes.";
+        case "API_KEY_REVOKED":
+            return "Somebody revoked this key. It will not start working again — make a new one.";
+        case "API_KEY_EXPIRED":
+            return "This key reached the end of the lifetime it was given. Make a new one.";
+        case "API_KEY_SCOPE":
+            return ("The key is valid and was not given permission for this. Nothing here will succeed with " +
+                "it — a key with the right permissions has to be made on the account screen.");
+        case "API_KEY_MALFORMED":
+            return ("What was sent is not a well-formed key. Check that the whole string was copied, with " +
+                "no quotes or line break — it is one line of exactly 65 characters.");
+        case "ACCOUNT_CODE_NOT_A_CREDENTIAL":
+            return ("That was an NMTS key, not an API key. An NMTS key never goes to the server; it stays " +
+                "on this machine and opens the files. Put the NMTS key in NMTS_ACCOUNT_CODE and the API key in " +
+                "NMTS_API_KEY.");
+        case "AGENT_VERIFY_REQUIRED":
+            return ("This was refused because nothing has checked lately that a person is behind this " +
+                "account's key. Ask the person to run `nmts verify` and to follow what it prints — it " +
+                "gives them a code to type at a browser, and nothing here can pass that check for them.");
+        case "SUPPORT_DUPLICATE":
+            return ("The same message reached the developer within the last day, so this one was not filed " +
+                "twice — nothing was lost. Sending it again will be refused again: say something the " +
+                "first message did not, or read the reply on the thread that is already open.");
+        // ⛔ THE REFUSAL IS CORRECT AND THERE IS NOTHING HERE TO WORK AROUND. Accepting terms is a
+        //    person reading a document and agreeing to it; a program doing it for them would be
+        //    signing on somebody else's behalf, and this tool holds an API key, not a person. So the
+        //    only thing missing was the advice — without it an agent gets a bare 403 and starts
+        //    trying credentials, which is the one thing that cannot be the cause.
+        // ⭐ 2026-09-06: the person no longer needs a browser for it. `nmts accept-terms`
+        //    is refused in mode auto and asks them to type the version, so the advice names it — an
+        //    agent still cannot run it, and the sentence says so.
+        //
+        // ⚠ It does not say WHICH requests are refused. The server gates some and not others (reading
+        //   and deleting are not gated today), that line has moved twice, and a sentence here naming
+        //   the list would be a copy of it that nothing keeps true.
+        case "TERMS_ACCEPTANCE_REQUIRED":
+            return ("This account has not accepted the terms now in force, and the server refuses this " +
+                "request until it does. Nothing an agent runs can accept them. Ask the person to run " +
+                "`nmts accept-terms` themselves (it is refused in mode auto), or to accept on the " +
+                "account screen at nmts.me. Other requests may still work in the meantime.");
+        // ⛔ A KEY IS NOT ENOUGH HERE AND NEVER WILL BE. These routes rebuild what makes the account
+        //    recoverable without NMTS, and the owner's rule is that the code is re-entered for them.
+        //    An agent that reads this as "my key is wrong" starts making new keys, which is the one
+        //    remedy that cannot work.
+        case "ACCOUNT_PROOF_REQUIRED":
+            return ("This request needs proof of the NMTS key as well as the API key, and what was sent was " +
+                "missing or did not match. Check that the NMTS key this machine is holding belongs to the " +
+                "same account as the API key. Wrong attempts are counted, and three of them lock these " +
+                "routes for a while.");
+        case "ACCOUNT_BANNED":
+            return "This account is suspended. Nothing here will succeed until that is lifted.";
+        // ── Getting to the starting line ──────────────────────────────────────────────────────────
+        case "ACCOUNT_EXISTS":
+            return "An account already exists for that. Use the one you have rather than making another.";
+        case "ALPHA_NOT_OPEN":
+            return ("This build asks the server for a channel it does not open. This is not something to " +
+                "retry or to fix with a different credential — use a release build.");
+        case "API_KEY_CAP":
+            return ("The account holds as many live keys as it is allowed. Nothing here can raise the limit: " +
+                "the person has to revoke a key they no longer use, on the account screen at nmts.me.");
+        case "API_KEY_CHANNEL":
+            return ("This account is enrolled on a preview build, and keys are not issued while it is. Ask " +
+                "the person to leave the preview on the account screen, then make the key.");
+        case "INVALID_CREDENTIALS":
+            return ("The server did not accept what was sent. For an API key: check that key. For `key new`: the " +
+                "server checked the proof derived from the NMTS key, and it did not match a registered " +
+                "account — the NMTS key itself never goes to the server.");
+        case "LOCKED_OUT":
+            return ("Too many failed attempts, so this is shut for a while. Retrying now makes it longer, " +
+                "not shorter. The refusal carries the moment it lifts; wait for it.");
+        case "RATE_LIMITED":
+            return ("Too many requests too quickly. Wait and send fewer — the refusal carries how long. This " +
+                "is not a credential problem, so changing keys will not help.");
+        case "SURFACE_MISMATCH":
+            return ("This account acts through a different build than the one calling. The refusal names " +
+                "which; nothing on this machine can change it, and the person switches it at nmts.me.");
+        // ── The terms ─────────────────────────────────────────────────────────────────────────────
+        case "TERMS_VERSION_MISMATCH":
+            return ("The versions sent are not the ones in force; the refusal carries the ones that are. " +
+                "This is a stale copy, not a refusal to serve — read the current versions and send those.");
+        case "TERMS_NOT_IN_FORCE":
+            return ("There is nothing to accept, so accepting cannot be what is missing. This is a server " +
+                "condition; report it rather than retrying.");
+        // ── Credits and the free trial ────────────────────────────────────────────────────────────
+        case "CREDIT_FILE_CAP":
+            return ("One file may cost at most the published cap in credits, and this one costs more. The " +
+                "refusal carries both numbers. Splitting the file is the way through; more credits is not.");
+        case "CREDIT_DAILY_CAP":
+            return ("The account has spent its allowance for today. The refusal carries the cap and what is " +
+                "spent. Waiting for the day to turn is the only remedy — buying credits does not lift it.");
+        // ⛔ FOUR CODES, FOUR REMEDIES, and that is why the server did not send one. They are cleared
+        //    by four different acts — name an account of your own · name a different one · send less ·
+        //    send some — and a retry loop that could not tell them apart would do the wrong one.
+        case "CREDIT_TRANSFER_OUTSIDE_FAMILY":
+            return ("Credits move between one person's own accounts — the account they made and every account " +
+                "under it — and nowhere else. The recipient named is not one of them, or does not exist: " +
+                "the server answers both the same way, so this cannot be used to find out which " +
+                "identifiers are real. Nothing was moved, and no credential changes this.");
+        case "CREDIT_TRANSFER_SELF":
+            return "The recipient named is the account sending. Name another account of the same family. Nothing was moved.";
+        case "CREDIT_TRANSFER_INSUFFICIENT":
+            return ("The sending account cannot cover that amount; the refusal carries what was needed and " +
+                "what it can spend. Nothing was moved and nothing is held. Send the smaller number, or " +
+                "get credits into that account first (`nmts trial`, or a funded wallet).");
+        case "CREDIT_TRANSFER_ZERO":
+            return "The transfer named no credits. Send a whole number above zero; nothing was moved.";
+        case "TRIAL_CLOSED":
+            return "The free trial is not open at all right now. Credits have to come from a funded wallet.";
+        case "TRIAL_FULL":
+            return "This week's free-trial places are taken. Applying again this week cannot succeed; next week can.";
+        case "TRIAL_ALREADY":
+            return "This account already took the free trial this week. It comes round weekly, not once.";
+        case "TRIAL_HELD":
+            return "Free-trial applications are paused pending review. Retrying does not move it.";
+        case "TRIAL_LINE_CAPPED":
+            return ("This internet connection has taken its share of this week's places today — the limit is " +
+                "on the connection, not on the account, so another account here hits it too.");
+        // ── Storage, the chain, and what is safe to retry ─────────────────────────────────────────
+        // ⛔ THE THREE OUTCOMES ARE DIFFERENT AND AN AGENT MUST NOT COLLAPSE THEM. Refused means it did
+        //    not happen. Failed means it did not finish. Uncertain means nobody knows — and that is the
+        //    one where retrying blindly can spend money twice.
+        case "CHAIN_REQUEST_REFUSED":
+            return ("The storage service refused the request itself, so nothing was spent and nothing was " +
+                "stored. Retrying the same request will be refused the same way.");
+        case "CHAIN_REGISTER_FAILED":
+            return "Registering the storage did not go through. Nothing is stored; the upload can be tried again.";
+        case "CHAIN_CERTIFY_FAILED":
+            return ("The bytes went out but the storage was never certified, so the file is not safely stored. " +
+                "Try the upload again.");
+        case "CHAIN_UNCERTAIN":
+            return ("⛔ Nobody knows whether the storage was registered. Do NOT simply retry: doing so can pay " +
+                "twice for the same file. Run `nmts ls` first and see whether the file is there.");
+        case "CHAIN_SPEND_CAP":
+            return ("The service has stopped spending on storage for today. This is not about this account " +
+                "and no credential or credit changes it. Try tomorrow.");
+        case "CHAIN_DELETE_FAILED":
+            return ("The storage could not be released. The file's record is gone from this side either way, " +
+                "so nothing here is stuck — the storage runs out on its own when its time is up.");
+        case "RELEASE_NOT_SPONSORED":
+            return ("This file's storage was not paid for with credits, so it is not the server's to release. " +
+                "Storage bought from a wallet is released by that wallet.");
+        case "SPONSORED_STATE":
+            return ("The upload is not at the step that call belongs to — the steps have an order and one was " +
+                "skipped or already done. Start the upload again rather than repeating this call.");
+        // ── Two callers, one drive ────────────────────────────────────────────────────────────────
+        case "MANIFEST_TOO_LARGE":
+            return ("The sealed file list is over the server's ceiling (16 MiB), so this save was refused and " +
+                "nothing changed. The list is stored as a small index plus chunks, and the index holds one " +
+                "short row per chunk — so an account reaches this only with a list that is not in chunks. " +
+                "Save once more to convert it; the ceiling is then the account's chunk allowance, which " +
+                "grows with confirmed files (details.allowed on MANIFEST_CHUNKS_EXCEEDED).");
+        // ── The chunked file list (NCF-3 §6.3) ────────────────────────────────────────────────────
+        case "MANIFEST_CHUNK_HASH":
+            return ("The name in the path is not the SHA-256 of the `ct` string being sent, so the server " +
+                "refused to store it under that name. Hash the base64url text exactly as it travels, not " +
+                "the bytes it decodes to, and send it under that name.");
+        case "MANIFEST_CHUNK_TOO_LARGE":
+            return ("One chunk of the file list is over the server's 4 MiB ceiling of sealed bytes. Pack " +
+                "fewer entries per chunk — the format's own bound is on the plaintext, so a chunk built " +
+                "to it is always under this — and send the same index again.");
+        case "MANIFEST_CHUNK_MISSING":
+            return ("The index names chunks this account has not stored. The refusal lists them in " +
+                "details.missing: write exactly those chunks, then send the same index again. Nothing " +
+                "changed and the version did not move.");
+        case "MANIFEST_CHUNKS_EXCEEDED":
+            return ("The account is at its chunk allowance (details.allowed). It is a base allowance plus " +
+                "one chunk for every details.per_verified_items files the storage network has confirmed, " +
+                "so it grows as files are stored; deleting files or packing the list into fewer chunks is " +
+                "what brings this write inside it.");
+        case "VERSION_CONFLICT":
+            return ("Something else changed the drive since this was read. Nothing is lost and nothing is " +
+                "wrong with the credential: read the current state and apply the change to that.");
+        case "ERASE_BLOCKED":
+            return ("The account cannot be erased while retained records still point at it. This will not " +
+                "clear by retrying; the records have their own retention and it has to run out.");
+        case "CREDITS_SHORT":
+            return "The account does not have enough credits for this upload.";
+        default:
+            return null;
+    }
+}