@needmoretruth/nmts-cli 0.17.2

package/dist/api.js

@@ -0,0 +1,271 @@
+// Talking to the NMTS server.
+//
+// ⛔ THIS DOES NOT RETRY THE HUMAN CHECK. The browser's client answers a CLEARANCE_REQUIRED by
+//    fetching a fresh captcha token and trying once more. In Node there is no captcha to fetch, so
+//    that path posts an empty token, fails again, and the whole thing surfaces as "the API rejects
+//    everything" with no mention of the real cause. Here a clearance refusal is returned as itself,
+//    named, with the reason a command-line tool cannot satisfy it.
+//
+// ⛔ EVERY REQUEST HAS A DEADLINE. An agent runs this in a loop with no person watching; a request
+//    that hangs forever is worse than one that fails, because nothing ever reports it.
+//
+// ⛔ THE TOKEN IS NEVER IN A MESSAGE, A URL OR A LOG. It goes in one header and nowhere else.
+import { NmtsError } from "./errors.js";
+import { isTransient, keepTrying } from "./net-retry.js";
+/** Default deadline for a request that is not moving file bytes. */
+export const DEFAULT_TIMEOUT_MS = 30_000;
+/** A refusal the server explained. Carries its code so a caller can branch without string matching. */
+export class ServerError extends NmtsError {
+    status;
+    code;
+    constructor(status, refusal, nextStep) {
+        super(refusal.message, { exitCode: 1, nextStep });
+        this.name = "ServerError";
+        this.status = status;
+        this.code = refusal.code;
+    }
+}
+/** What a caller does next about a refusal, when the tool knows something the message does not. */
+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 account code, not an API key. The code never goes to the server; it stays " +
+                "on this machine and opens the files. Put the code in NMTS_ACCOUNT_CODE and the 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.");
+        // ⛔ 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.
+        //
+        // ⚠ 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 on this machine can accept them. Ask the person to open " +
+                "the account screen at nmts.me and accept there. 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 account code as well as the key, and what was sent was " +
+                "missing or did not match. Check that the code this machine is holding belongs to the " +
+                "same account as the 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. Check the key rather than the account code — " +
+                "the code never goes to the server and cannot be the cause.");
+        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.");
+        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 "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;
+    }
+}
+function isRefusal(value) {
+    if (typeof value !== "object" || value === null || !("error" in value))
+        return false;
+    const error = Reflect.get(value, "error");
+    if (typeof error !== "object" || error === null)
+        return false;
+    return typeof Reflect.get(error, "code") === "string" && typeof Reflect.get(error, "message") === "string";
+}
+/**
+ * One request to the NMTS server, returning parsed JSON or throwing a named refusal.
+ *
+ * `path` starts with `/v1/`. It is joined to the base without any normalising, so a caller cannot
+ * accidentally send a request to a different host by passing an absolute URL.
+ */
+export async function request(base, path, options = {}) {
+    if (!path.startsWith("/"))
+        throw new NmtsError(`A request path must start with "/": ${path}`);
+    // ⛔ REPEATED ONLY WHERE REPEATING IS THE SAME REQUEST. A read always is. A write is only when it
+    //    carries an idempotency key, because a request that reached the server and died on the way
+    //    back looks exactly like one that never arrived -- and guessing wrong there spends money
+    //    twice. Everything else fails once and says so, exactly as it did before.
+    const safeToRepeat = options.method === undefined ||
+        options.method === "GET" ||
+        options.idempotencyKey !== undefined;
+    if (!safeToRepeat)
+        return await once(base, path, options);
+    return await keepTrying(() => once(base, path, options), {
+        retryable: (error) => isTransient(error, error instanceof ServerError ? error.status : undefined),
+        ...(options.onWait === undefined ? {} : { onWait: options.onWait }),
+        ...(options.signal === undefined ? {} : { signal: options.signal }),
+        ...(options.retryBudgetMs === undefined ? {} : { budgetMs: options.retryBudgetMs }),
+    });
+}
+/** One attempt. `request` above decides whether there may be another. */
+async function once(base, path, options) {
+    const { method = "GET", body, token, timeoutMs = DEFAULT_TIMEOUT_MS } = options;
+    const controller = new AbortController();
+    const deadline = setTimeout(() => controller.abort(), timeoutMs);
+    if (options.signal)
+        options.signal.addEventListener("abort", () => controller.abort(), { once: true });
+    const headers = { accept: "application/json" };
+    if (body !== undefined)
+        headers["content-type"] = "application/json";
+    if (token !== undefined && token.length > 0)
+        headers["authorization"] = `Bearer ${token}`;
+    if (options.idempotencyKey !== undefined)
+        headers["idempotency-key"] = options.idempotencyKey;
+    // ⛔ THE HEADER NAME IS THE SERVER'S, spelled once. It is enforced inside `from_request_parts`,
+    //    which sees headers and never a body — which is why the proof is a header and not a field.
+    if (options.accountProof !== undefined)
+        headers["x-nmts-account-proof"] = options.accountProof;
+    let response;
+    try {
+        // ⛔ Built conditionally rather than passing `body: undefined`: with exactOptionalPropertyTypes
+        //    the two are different, and a GET carrying an explicit undefined body is not the same
+        //    request as a GET with no body at all.
+        const init = { method, headers, signal: controller.signal };
+        if (body !== undefined)
+            init.body = JSON.stringify(body);
+        response = await fetch(`${base}${path}`, init);
+    }
+    catch (error) {
+        // ⛔ The cause is named, not swallowed: "fetch failed" alone sends an agent looking at its own
+        //    code. A timeout and a refused connection are different problems with different fixes.
+        const timedOut = controller.signal.aborted;
+        throw new NmtsError(timedOut ? `The server did not answer within ${timeoutMs}ms.` : `Could not reach ${base}.`, {
+            exitCode: 1,
+            nextStep: timedOut
+                ? "The server may be slow or unreachable. Try again."
+                : `Check the address and the network. Cause: ${error instanceof Error ? error.message : String(error)}`,
+        });
+    }
+    finally {
+        clearTimeout(deadline);
+    }
+    const text = await response.text();
+    let parsed = null;
+    if (text.length > 0) {
+        try {
+            parsed = JSON.parse(text);
+        }
+        catch {
+            // A non-JSON body from an NMTS route means something in front of it answered — a proxy, an
+            // access page, an error page. Saying "invalid JSON" would point at the wrong thing.
+            throw new NmtsError(`${base} answered ${response.status} with something that is not JSON.`, {
+                exitCode: 1,
+                nextStep: "Something in front of the server answered. Check the address.",
+            });
+        }
+    }
+    if (!response.ok) {
+        if (isRefusal(parsed)) {
+            throw new ServerError(response.status, parsed.error, adviseFor(parsed.error.code));
+        }
+        throw new NmtsError(`${base} answered ${response.status}.`, { exitCode: 1 });
+    }
+    return parsed;
+}

package/dist/args.js

@@ -0,0 +1,137 @@
+// Turning argv into a command and its options.
+//
+// ⛔ NO SECRET IS EVER AN OPTION. There is no --code and no --api-key, and adding one would undo
+//    the reason the credentials module exists: on Linux any process can read another's command
+//    line, and the shell records it. A test asserts that no option name here looks like a secret.
+//
+// ⛔ AN UNKNOWN OPTION IS AN ERROR, NOT A SHRUG. Ignoring it means `--serverr https://…` silently
+//    talks to the live server, and an agent retrying with a typo would never learn why.
+//
+// ⛔ THE OPTIONS ARE A TABLE, NOT A LADDER OF `if`s. Every option used to be written three times —
+//    once in the list a test reads, once as `--x value` and once as `--x=value` — and adding one
+//    meant remembering all three. Now the table below is the only place, so an option cannot exist
+//    in one spelling and not the other.
+import { NmtsError } from "./errors.js";
+/** Which field a value-taking option fills. */
+const VALUE_OPTIONS = {
+    "--server": "server",
+    "--network": "network",
+    "--out": "out",
+    "--name": "name",
+    "--to": "to",
+    "--part-size": "partSize",
+    "--on-collision": "onCollision",
+    "--find": "find",
+    "--sort": "sort",
+    "--epochs": "epochs",
+    "--port": "port",
+    "--accept-terms": "acceptTerms",
+    "--accept-privacy": "acceptPrivacy",
+};
+/** Which field a flag sets to true. */
+const FLAG_OPTIONS = {
+    "--help": "help",
+    "-h": "help",
+    "--version": "version",
+    "-V": "version",
+    "--json": "json",
+    "--all": "all",
+    "--force": "force",
+    "--dry-run": "dryRun",
+    "--yes": "yes",
+    "-y": "yes",
+    "--publish": "publish",
+    "--plain": "plain",
+    "--env": "env",
+    "--status": "status",
+    "--i-accept-the-risk": "iAcceptTheRisk",
+    "--desc": "desc",
+    "--hidden": "hidden",
+};
+// ⛔ Derived from the tables, not written again. A hand-kept list is how an option ends up tested
+//    for one property and accepted with another.
+export const OPTIONS_TAKING_A_VALUE = Object.keys(VALUE_OPTIONS);
+export const FLAGS = Object.keys(FLAG_OPTIONS);
+function isValueOption(token) {
+    return Object.hasOwn(VALUE_OPTIONS, token);
+}
+function isFlag(token) {
+    return Object.hasOwn(FLAG_OPTIONS, token);
+}
+export function parseArgs(argv) {
+    const parsed = {
+        command: null,
+        operands: [],
+        help: false,
+        version: false,
+        json: false,
+        all: false,
+        force: false,
+        publish: false,
+        dryRun: false,
+        yes: false,
+        plain: false,
+        env: false,
+        status: false,
+        iAcceptTheRisk: false,
+        desc: false,
+        hidden: false,
+    };
+    let index = 0;
+    // ⛔ EVERYTHING AFTER `--` IS A NAME, NOT AN OPTION. Files in a drive are named by people and by
+    //    other programs, and a name is allowed to start with a dash. Without this, `nmts rm -h`
+    //    printed the help text and EXITED 0 — a silent false success on a deletion, for a path
+    //    `nmts ls --json` had just handed the caller (2026-08-23).
+    let optionsEnded = false;
+    while (index < argv.length) {
+        const token = argv[index];
+        if (token === undefined)
+            break;
+        index += 1;
+        if (optionsEnded) {
+            parsed.operands.push(token);
+            continue;
+        }
+        if (token === "--") {
+            optionsEnded = true;
+            continue;
+        }
+        if (isFlag(token)) {
+            parsed[FLAG_OPTIONS[token]] = true;
+            continue;
+        }
+        if (isValueOption(token)) {
+            const value = argv[index];
+            // ⛔ A LONE `-` IS A VALUE, NOT AN OPTION. It is how every tool spells "the standard
+            //    streams", and `--out -` is what sends a fetched file to stdout instead of the disk.
+            //    The rest of the test is unchanged and still catches `--out --force`, which is a
+            //    missing value; this is the same exception the unknown-option check below already
+            //    makes for a bare dash.
+            if (value === undefined || (value.startsWith("-") && value !== "-")) {
+                throw new NmtsError(`${token} needs a value after it.`, { exitCode: 2 });
+            }
+            index += 1;
+            parsed[VALUE_OPTIONS[token]] = value;
+            continue;
+        }
+        const equals = token.indexOf("=");
+        if (equals > 0) {
+            const head = token.slice(0, equals);
+            if (isValueOption(head)) {
+                parsed[VALUE_OPTIONS[head]] = token.slice(equals + 1);
+                continue;
+            }
+        }
+        if (token.startsWith("-") && token !== "-") {
+            throw new NmtsError(`Unknown option: ${token}`, {
+                exitCode: 2,
+                nextStep: `Run with --help to see the options this version accepts.`,
+            });
+        }
+        if (parsed.command === null)
+            parsed.command = token;
+        else
+            parsed.operands.push(token);
+    }
+    return parsed;
+}

package/dist/artifact-about.js

@@ -0,0 +1,70 @@
+// WHAT THIS FILE IS · WHAT OPENS IT · WHERE TO GET THAT · WHO WROTE IT — the block every recovery
+// artefact this tool writes carries in its plaintext header.
+//
+// ⛔ WHY IT IS WORTH BYTES. Three artefacts leave this tool and live in an ordinary folder rather
+//    than on the storage network: the recovery list (`.nmtsmap`), this machine's copy of the file
+//    list (`.nmtslist`), and the recovery kit (`.txt`). Nothing around them supplies context — no
+//    address, no account screen, no site. Years later the only question that matters is whether
+//    the person holding one can act on it alone, and these fields are what answer it: which
+//    product wrote it, which program reads it, where to get that program, and where the format is
+//    written down.
+//
+// ⛔ TWO LAYERS, AND THE SPLIT IS A PRIVACY RULE. This is the PLAINTEXT layer, so it carries only
+//    what a reader needs BEFORE opening anything: never a file name, never a count, never a total.
+//    A leaked wrapper must not say what is inside it, or even how much. Everything here is a
+//    constant of the product plus the version of the program that wrote the file.
+//
+// ⚠ EVERY FIELD IS A CLAIM, NEVER A REQUIREMENT. No reader can check them and none should refuse a
+//   file over them — a URL can die and a repository can move. They are here to save a person a
+//   search, not to decide whether a recovery may proceed.
+//
+// ⚠ MIRRORS `web/src/lib/recovery/provenance.ts`, which this package cannot import: the two trees
+//   share no code by design. The VALUES are taken from the modules that already own them
+//   (`product.ts`, `recovery-release.ts`) so a rename lands here without a second edit.
+import { HOME_URL, VERSION } from "./product.js";
+import { RECOVERY_TOOL, RECOVERY_TOOL_URL } from "./recovery-release.js";
+/** The product these artefacts come from, spelled as the formats carry it. */
+export const PRODUCT = "NMTS";
+/** Where the recovery list's format is written down, in the copy anybody can reach. */
+export const RECOVERY_SPEC_URL = `${RECOVERY_TOOL_URL}/blob/main/docs/RECOVERY-MANIFEST.md`;
+/** Where the envelope format is — key derivation, header layout, domain separators. */
+export const CRYPTO_SPEC_URL = `${RECOVERY_TOOL_URL}/blob/main/docs/CRYPTO-FORMAT-NCF3.md`;
+/**
+ * Which build wrote the file.
+ *
+ * ⚠ A CLAIM, NEVER A REQUIREMENT. It names THIS PROGRAM rather than the site release, because that
+ *   is the field's own contract — what the writer says about itself — and a person holding two
+ *   copies of one account's artefacts can then tell which program made each.
+ */
+export const WRITTEN_BY = `nmts-cli ${VERSION}`;
+/** The NCF-3 domain separator each sealed artefact uses. */
+const SEALED_CONTEXT = {
+    "recovery-list": "nmts/v3/recovery-map",
+    "file-list": "nmts/v3/file-list",
+};
+/** The block for one wrapper. */
+export function artifactAbout(artifact) {
+    const about = {
+        product: PRODUCT,
+        product_url: HOME_URL,
+        app_version: WRITTEN_BY,
+        artifact,
+        tool: RECOVERY_TOOL,
+        tool_url: RECOVERY_TOOL_URL,
+        spec_url: artifact === "file-list" ? CRYPTO_SPEC_URL : RECOVERY_SPEC_URL,
+    };
+    if (artifact === "recovery-kit") {
+        // ⛔ Said out loud because this is the artefact that is dangerous to hold. A reader — a person
+        //    or a program — must be able to tell from the header alone that this file carries the code.
+        about.contains = ["account-code", "recovery-list"];
+        return about;
+    }
+    about.sealed = {
+        format: "ncf3",
+        context: SEALED_CONTEXT[artifact],
+        encoding: "base64url",
+        opened_with: "nmts-account-code",
+        spec_url: CRYPTO_SPEC_URL,
+    };
+    return about;
+}

package/dist/autonomy.js

@@ -0,0 +1,98 @@
+// How much this machine's owner has said an agent may decide on its own.
+//
+// ⛔ THIS IS A DIFFERENT AXIS FROM CONSENT, and mixing the two would make both harder to reason
+//    about. A consent key says "this machine agreed that this tool may do X" -- it is about the
+//    CAPABILITY, it is recorded, and it stands until it is revoked. A mode says "an agent driving
+//    this tool may decide for me" -- it is about WHO CHOOSES, and it changes nothing about what
+//    the tool is able to do. They are stored in different files for that reason: a mode is not a
+//    sixth consent, and the count of consents is a number this package deliberately holds down.
+//
+// ⛔ NOTHING IS ON BY DEFAULT, AND TURNING ONE ON TAKES A FLAG THAT SAYS SO. The person is the one
+//    who bears what an unattended agent does with their files and their money, so the sentence
+//    that turns it on has to be one nobody types by accident.
+//
+// ⛔ WHAT A MODE DOES NOT DO: it does not grant a consent, and it cannot grant itself. Every
+//    capability that costs money or cannot be undone is still recorded as its own agreement. What
+//    `skip-permissions` changes is WHO MAY RECORD IT -- with it on, an agent may run the grant
+//    command, which without it the instructions forbid. The record still says what was agreed and
+//    when, so a person reading it afterwards sees the same thing either way.
+//
+// ⚠ AND WHAT NO COMMAND-LINE TOOL CAN DO: tell whether a person or a program typed this. The
+//   protection here is that the choice is explicit, written down, dated, and announced on every
+//   run that uses it -- not that it cannot be automated.
+import { existsSync, mkdirSync, readFileSync, rmSync, writeFileSync, chmodSync } from "node:fs";
+import { join } from "node:path";
+import { configDir, modesAreEnforced } from "./credentials.js";
+export const AUTONOMY_MODES = ["off", "auto", "skip-permissions"];
+/** What each mode means, in the words the tool prints. One line each, no more. */
+export const MODE_MEANS = {
+    off: "The agent asks you before anything that has not been agreed to. This is the default.",
+    auto: "The agent decides whether you asked for it, or whether it is fine to do unasked, and goes ahead.",
+    "skip-permissions": "The agent goes ahead. There is no judgement step and nothing waits for you.",
+};
+/** The flag that has to be typed to turn a mode on. Spelled out so nobody types it by accident. */
+export const RISK_FLAG = "--i-accept-the-risk";
+function path() {
+    return join(configDir(), "autonomy.json");
+}
+function isMode(value) {
+    return typeof value === "string" && AUTONOMY_MODES.includes(value);
+}
+/**
+ * What this machine is set to.
+ *
+ * ⛔ Unreadable counts as `off`. The fail-safe direction for "I do not know" is the one where
+ *    somebody is still asked -- a file that switches autonomy on when it cannot be parsed is worse
+ *    than no file at all.
+ */
+export function currentMode() {
+    try {
+        const parsed = JSON.parse(readFileSync(path(), "utf8"));
+        if (typeof parsed !== "object" || parsed === null)
+            return "off";
+        const mode = Reflect.get(parsed, "mode");
+        return isMode(mode) ? mode : "off";
+    }
+    catch {
+        return "off";
+    }
+}
+/** When it was set, or null when it is off or unreadable. */
+export function setAt() {
+    try {
+        const parsed = JSON.parse(readFileSync(path(), "utf8"));
+        if (typeof parsed !== "object" || parsed === null)
+            return null;
+        const at = Reflect.get(parsed, "setAt");
+        return typeof at === "string" ? at : null;
+    }
+    catch {
+        return null;
+    }
+}
+/** Write the choice down, with the date and the version that was asked. */
+export function setMode(mode, version, now) {
+    if (mode === "off") {
+        if (existsSync(path()))
+            rmSync(path(), { force: true });
+        return;
+    }
+    const body = { mode, setAt: now.toISOString(), byVersion: version };
+    mkdirSync(configDir(), { recursive: true, mode: 0o700 });
+    writeFileSync(path(), `${JSON.stringify(body, null, 2)}\n`, { mode: 0o600 });
+    if (modesAreEnforced())
+        chmodSync(path(), 0o600);
+}
+/**
+ * The line every run prints when a mode is on.
+ *
+ * ⛔ IT IS PRINTED EVERY TIME, not once. A setting that stops announcing itself is a setting people
+ *    forget they turned on, and this one decides whether anybody is asked before money is spent.
+ *    ⚠ It goes to stderr: stdout belongs to whatever is reading this tool's output.
+ */
+export function announcement(mode) {
+    if (mode === "off")
+        return null;
+    return `${BANNER_PREFIX}${mode} — ${MODE_MEANS[mode]} Turn it off with \`nmts mode off\`.`;
+}
+const BANNER_PREFIX = "nmts: autonomy is ";

package/dist/code-access.js

@@ -0,0 +1,76 @@
+// Getting the account code this run should actually use — including opening a sealed one.
+//
+// ⛔ WHY IT IS NOT IN `credentials.ts`. That module answers "where is the code"; this one answers
+//    "may this run have it, and can it be opened". Putting the second question in the first module
+//    would make `credentials.ts` import `consent.ts`, which already imports `credentials.ts` for
+//    the config directory — a cycle that works until the day it does not.
+//
+// ⚠ EVERY COMMAND THAT USES THE CODE GOES THROUGH `openAccountCode` — with ONE exception, and it
+//   is written here rather than left to be discovered. `login` does not: it is the command that
+//   RECEIVES a code rather than one that uses a stored one, so it reads the ways in for itself
+//   (`commands/login.ts`, `readTheCode`). It asks for the same `plain-env` agreement at that
+//   point, because an adversarial review found that it did not, and two commands were then enough
+//   to launder a code from the environment into a store that asks for nothing.
+//
+// ⛔ THAT EXCEPTION IS THE WHOLE RISK OF THIS SHAPE. A rule enforced at each call site has as many
+//   holes as there are call sites, and the hole is always the newest one.
+import { requireConsent } from "./consent.js";
+import { unlockCode } from "./code-vault.js";
+import { CODE_ENV_VAR, PASSPHRASE_ENV_VAR, credentialsPath, resolveAccountCode, } from "./credentials.js";
+import { NmtsError, NotLoggedInError } from "./errors.js";
+import { promptSecret, stdinIsATerminal } from "./prompt.js";
+import { BINARY_NAME } from "./product.js";
+export async function openAccountCode(options = {}) {
+    const found = resolveAccountCode();
+    if (found === null)
+        return null;
+    if (found.source === "env") {
+        // ⛔ The one credential path that asks first. See the `plain-env` entry in consent.ts — the
+        //    variable is readable in ways a file is not, and the person gets to decide that once.
+        requireConsent("plain-env");
+        return { code: found.code, source: "env" };
+    }
+    if (found.source !== "file-locked")
+        return { code: found.code, source: found.source };
+    const passphrase = await readPassphrase(options.allowPrompt !== false);
+    return { code: unlockCode(found.locked, passphrase), source: "file-locked" };
+}
+/**
+ * Where the passphrase comes from: the environment first, then a terminal.
+ *
+ * ⛔ THE ENVIRONMENT WINS so that an unattended agent works at all. It is a weaker arrangement and
+ *    `consent.ts` says why; refusing it would not make anybody safer, it would make them write a
+ *    wrapper that types the passphrase in, which is worse and invisible.
+ */
+async function readPassphrase(allowPrompt) {
+    const fromEnv = process.env[PASSPHRASE_ENV_VAR];
+    if (fromEnv !== undefined && fromEnv.length > 0)
+        return fromEnv;
+    if (!allowPrompt || !stdinIsATerminal()) {
+        throw new NmtsError(`The stored account code is sealed with a passphrase.`, {
+            exitCode: 3,
+            nextStep: [
+                allowPrompt
+                    ? `There is no terminal to type it into, so one of these has to supply it:`
+                    : `This command reads its own protocol from the terminal, so it cannot ask. Supply it:`,
+                `  · set ${PASSPHRASE_ENV_VAR} for this run`,
+                `  · name a file holding the code instead: NMTS_ACCOUNT_CODE_FILE=/path`,
+                `  · store it unsealed: ${BINARY_NAME} login --plain  (this asks for an agreement first)`,
+                ``,
+                `The sealed file is ${credentialsPath()}.`,
+            ].join("\n"),
+        });
+    }
+    return promptSecret(`Passphrase for the stored account code: `, PASSPHRASE_ENV_VAR);
+}
+/**
+ * The code, or a refusal naming what to do about it. For commands that cannot proceed without it.
+ *
+ * ⛔ The message never mentions the code itself, only where one could come from.
+ */
+export async function requireAccountCode(options = {}) {
+    const opened = await openAccountCode(options);
+    if (opened === null)
+        throw new NotLoggedInError(BINARY_NAME, CODE_ENV_VAR);
+    return opened;
+}