@needmoretruth/nmts-cli 0.17.2 → 0.34.2

package/dist/commands/sweep.d.ts

@@ -0,0 +1,11 @@
+export interface SweepOptions {
+    server?: string | undefined;
+    network?: string | undefined;
+    json?: boolean;
+    /** Go ahead and drop them. Without this the run reports and changes nothing. */
+    yes?: boolean;
+    write?: (line: string) => void;
+    /** The instant to measure the thirty days against. Passed in so one run means one moment. */
+    now?: number;
+}
+export declare function sweep(options?: SweepOptions): Promise<number>;

package/dist/commands/tip.d.ts

@@ -0,0 +1,11 @@
+export interface TipOptions {
+    server?: string | undefined;
+    network?: string | undefined;
+    json?: boolean;
+    yes?: boolean;
+    write?: (line: string) => void;
+    /** Injected in tests: answers the one confirmation above the dial's end. */
+    readLine?: ((question: string) => Promise<string>) | undefined;
+    now?: number;
+}
+export declare function tip(wanted: string | undefined, options?: TipOptions): Promise<number>;

package/dist/commands/tip.js

@@ -0,0 +1,86 @@
+// `nmts tip [percent | off]` — the standing share of every storage payment sent to the developer
+// as a gift (owner 2026-09-06). Read with no argument; set with a percent; `off` is 0.
+//
+// ⛔ IT LIVES IN THE SEALED FILE LIST, like `padding`: the server must not learn it, and it follows
+//    the account, so the browser and every machine send the same share. 0 is spelled as absence.
+//
+// ⛔ THE AGREEMENT IS ASKED ONCE, AND ONLY WHEN RAISING FROM 0. Setting any share above 0 needs the
+//    `donate` unlock — that unlock's text IS the gift terms (voluntary · nothing in return · not
+//    refundable · the published address · visible on the chain) — and the first such setting
+//    writes the agreement's instant into the list, which the browser reads as the same agreement.
+//    After that, changing the share asks nothing. Above 10 % the run confirms once more, in words,
+//    that this share of EVERY payment is meant, permanently: at a terminal, or with `--yes`.
+//
+// ⛔ NOTHING IS SENT HERE. The sending happens after each payment (`standing-tip.ts`), without a
+//    question, because this is the person's standing choice.
+import { requireConsent } from "../consent.js";
+import { NmtsError } from "../errors.js";
+import { readFileList } from "../manifest.js";
+import { applyManyToList } from "../manifest-write.js";
+import { BINARY_NAME } from "../product.js";
+import { promptLine, stdinIsATerminal } from "../prompt.js";
+import { openSession } from "../session.js";
+import { TIP_DIAL_MAX_TENTHS, needsExtraConfirm, percentText, tenthsFromPercent } from "../shared/lib/wallet/tip.js";
+export async function tip(wanted, options = {}) {
+    const say = options.write ?? ((line) => process.stdout.write(`${line}\n`));
+    const session = await openSession({ server: options.server, network: options.network });
+    const list = await readFileList(session.server, session.apiKey, session.code, session.accountId);
+    const current = list.manifest?.settings?.tipTenths ?? 0;
+    const consentAt = list.manifest?.settings?.tipConsentAt;
+    if (wanted === undefined || wanted === "") {
+        if (options.json === true) {
+            say(JSON.stringify({ tipPercent: Number(percentText(current)), tipTenths: current, agreedAt: consentAt === undefined ? null : new Date(consentAt).toISOString() }));
+            return 0;
+        }
+        say(current > 0
+            ? `Every storage payment sends ${percentText(current)} % of what it paid to the developer, as a gift, in WAL — without asking.`
+            : `No standing gift: 0 % of each storage payment goes to the developer.`);
+        say(`  Set one: \`${BINARY_NAME} tip 2.5\` (in steps of 0.1 %, the dial ends at 10 %). Stop it: \`${BINARY_NAME} tip off\`.`);
+        if (consentAt !== undefined)
+            say(`  The gift terms were agreed to on ${new Date(consentAt).toISOString().slice(0, 10)}.`);
+        return 0;
+    }
+    const tenths = wanted === "off" || wanted === "0" ? 0 : tenthsFromPercent(Number(wanted));
+    if (wanted !== "off" && !/^\d+(\.\d+)?$/.test(wanted)) {
+        throw new NmtsError(`\`${BINARY_NAME} tip\` takes a percent (2.5) or off.`, { exitCode: 2 });
+    }
+    if (list.manifest === null) {
+        throw new NmtsError(`This account has no file list yet; the setting lives in the list, and there is nothing to write it into.`, {
+            exitCode: 4,
+            nextStep: `Upload once (\`${BINARY_NAME} put\`) and set it after.`,
+        });
+    }
+    // ⛔ THE AGREEMENT — the `donate` unlock — stands between 0 and anything above it, once per machine.
+    if (tenths > 0)
+        requireConsent("donate");
+    if (needsExtraConfirm(tenths) && options.yes !== true) {
+        const ask = options.readLine ?? promptLine;
+        if (options.readLine === undefined && !stdinIsATerminal()) {
+            throw new NmtsError(`A share above ${percentText(TIP_DIAL_MAX_TENTHS)} % is confirmed by a person.`, {
+                exitCode: 5,
+                nextStep: `Ask them, then run the same command with --yes.`,
+            });
+        }
+        const answer = (await ask(`Send ${percentText(tenths)} % of EVERY storage payment to the developer, permanently, until you change it? [y/N] `)).trim();
+        if (answer !== "y" && answer !== "Y") {
+            say(`Nothing changed.`);
+            return 1;
+        }
+    }
+    const patch = { tipTenths: tenths };
+    if (tenths > 0 && consentAt === undefined)
+        patch.tipConsentAt = options.now ?? Date.now();
+    const result = await applyManyToList(session, () => [], patch);
+    if (options.json === true) {
+        say(JSON.stringify({ tipPercent: Number(percentText(tenths)), tipTenths: tenths, changed: result.changed }));
+        return 0;
+    }
+    if (!result.changed)
+        say(`Already ${tenths === 0 ? "off" : `${percentText(tenths)} %`}. Nothing changed.`);
+    else if (tenths === 0)
+        say(`Standing gift set to 0 %: nothing more is sent after a payment.`);
+    else
+        say(`Standing gift set: every storage payment now sends ${percentText(tenths)} % of what it paid to the developer, in WAL, without asking.`);
+    say(`  Thank you.`);
+    return 0;
+}

package/dist/commands/trash.d.ts

@@ -0,0 +1,17 @@
+import type { ManifestEntry } from "../shared/lib/drive/manifest-codec.ts";
+export interface TrashOptions {
+    server?: string | undefined;
+    network?: string | undefined;
+    json?: boolean;
+    write?: (line: string) => void;
+}
+export declare function rm(paths: readonly string[], options?: TrashOptions): Promise<number>;
+export declare function restore(paths: readonly string[], options?: TrashOptions): Promise<number>;
+/**
+ * Every file at or under one entry.
+ *
+ * ⚠ Trashed descendants are INCLUDED HERE, and the CALLER filters. Somebody who trashed one file
+ *   last week and then trashes its folder expects the folder to be gone from the server too — so
+ *   `rm` takes this set whole. `restore` cannot: see the note at the call site.
+ */
+export declare function filesUnder(entries: readonly ManifestEntry[], rootId: string): ManifestEntry[];

package/dist/commands/trash.js

@@ -249,7 +249,7 @@ function uniqueById(files) {
  *   last week and then trashes its folder expects the folder to be gone from the server too — so
  *   `rm` takes this set whole. `restore` cannot: see the note at the call site.
  */
-function filesUnder(entries, rootId) {
+export function filesUnder(entries, rootId) {
     const root = entries.find((e) => e.id === rootId);
     if (root === undefined)
         return [];

package/dist/commands/trial.d.ts

@@ -0,0 +1,7 @@
+export interface TrialOptions {
+    server?: string | undefined;
+    network?: string | undefined;
+    json?: boolean;
+    write?: (line: string) => void;
+}
+export declare function trial(action: string | undefined, options?: TrialOptions): Promise<number>;

package/dist/commands/trial.js

@@ -17,13 +17,13 @@
 //    person — which sends an agent to make another key, the one thing that cannot help. So the
 //    standing check is asked about first, and the answer names `nmts verify`.
 //
-// ⛔ AND APPLYING ASKS FOR SOMETHING THIS TOOL CANNOT PRODUCE. `POST /v1/trial/apply` runs a
-//    fresh browser check of its own on every application — it is the one request in this API that
-//    hands out credits, so the check is made per application rather than once per session. A
-//    command line has no browser and no token, so on any deployment configured with that check
-//    the application is refused however good the credentials are. That is reported as what it is,
-//    with the place a person can apply from, rather than as a credential problem. `nmts verify`
-//    is a DIFFERENT check and does not stand in for this one.
+// ⛔ AND APPLYING ASKS FOR NO BROWSER TOKEN OF ITS OWN (2026-09-06). `POST
+//    /v1/trial/apply` used to run a fresh browser check on every application, which closed the
+//    route to this tool completely: a command line has no browser, so the application was refused
+//    however good the credentials were. The server now reads the account's four-week check as the
+//    human evidence a key carries, so applying works exactly while that check is live — the same
+//    condition the pre-check above already asks about, and the one `nmts verify` renews. Nothing
+//    here produces a token, and nothing here needs to.
 import { request, ServerError } from "../api.js";
 import { readCredentialsFile } from "../credentials.js";
 import { NmtsError } from "../errors.js";
@@ -134,18 +134,16 @@ function explain(error, week) {
         //   screen that is refusing for the same reason.
         case "TURNSTILE_FAILED":
             // ⛔ THE ADVICE `api.ts` CARRIES FOR THIS CODE IS THE WRONG ONE HERE, and that is why this
-            //    case exists. It says an API key is what waives the check — true for signing in, and
-            //    false for this route, which runs its own check on every application no matter what
-            //    credential arrived. A caller told to go and make a key would make one and be refused
-            //    again.
-            return new NmtsError("This server asks every application for a browser check, and a command line has none.", {
+            //    case exists. It says a machine credential is what waives the check; on this route what
+            //    waives it is the account's four-week check, and a caller sent to make another
+            //    credential would make one and be refused again.
+            return new NmtsError("This server asked this application for a browser check of its own.", {
                 exitCode: 4,
-                nextStep: `Nothing was taken and this account's place for week ${week.round} is untouched. The ` +
-                    `check is a puzzle solved in a browser, and it is asked for on every application ` +
-                    `rather than once, because this is the one request that hands out credits. Apply on ` +
-                    `the account screen at ` +
-                    `${HOME_URL} instead. \`${BINARY_NAME} verify\` is a different check and does not stand ` +
-                    `in for this one.`,
+                nextStep: `Nothing was taken and this account's place for week ${week.round} is untouched. ` +
+                    `Applying needs the account's four-week check to be live, and \`${BINARY_NAME} verify\` ` +
+                    `is what renews it: it prints a short code for a person to type at a browser. A server ` +
+                    `that asks for a check on every application is an older build than this expects — ` +
+                    `there, a person applies on the account screen at ${HOME_URL}.`,
             });
         case "TRIAL_FULL":
             return new NmtsError("Every place in this week is taken.", {

package/dist/commands/unlock.d.ts

@@ -0,0 +1,16 @@
+export interface UnlockOptions {
+    json?: boolean;
+    write?: (line: string) => void;
+    /** The clock. Injected so a test asserts a real timestamp rather than tolerating any string. */
+    now?: () => Date;
+    /** Injected in tests: answers the one question. Its presence also stands in for a terminal. */
+    readLine?: ((question: string) => Promise<string>) | undefined;
+    /** `unlock wallet` only — see `wallet-grant.ts`. */
+    days?: string | undefined;
+    until?: string | undefined;
+    scope?: string | undefined;
+    capWal?: string | undefined;
+    capSui?: string | undefined;
+}
+/** `unlock` · `lock` · the list. `action` is already normalised by the caller (`grant` → `unlock`). */
+export declare function unlock(action: string | undefined, target: string | undefined, options?: UnlockOptions): Promise<number>;

package/dist/commands/unlock.js

@@ -0,0 +1,159 @@
+// `nmts unlock` — what this machine's owner has opened, and the one way to open more.
+//
+// ⛔ IT IS A COMMAND AND NOT A PROMPT. A yes/no question in the middle of another command cannot be
+//    answered by anything that is not a terminal, which is most of the places this tool runs: a
+//    container, a build step, an agent's subprocess. Making the unlock its own command means the
+//    same answer works everywhere, is recorded with a date, and can be looked at afterwards.
+//
+// ⛔ A PERSON UNLOCKS, AT A TERMINAL. Opening a lock refuses when stdin is not a terminal — the way
+//    an agent's subprocess usually arrives — and prints what the lock guards before it asks. The one
+//    mode that may unlock without a terminal is skip-permissions: the person who turned it on said
+//    nothing is to ask them. Locking again is one line from anywhere: the safe direction is never
+//    harder than the risky one.
+//
+// `nmts consent` is the older name for the same thing and still works: `grant` is `unlock`, `revoke`
+// is `lock`.
+import { currentMode } from "../autonomy.js";
+import { CONSENTS, CONSENT_KEYS, grant, grantedAt, revoke } from "../consent.js";
+import { NmtsError } from "../errors.js";
+import { BINARY_NAME, SUPPORT_EMAIL, VERSION } from "../product.js";
+import { promptLine, stdinIsATerminal } from "../prompt.js";
+import { coinAmount } from "../wallet.js";
+import { parseWalletGrant, readWalletGrant, walletGrantState, writeWalletGrant } from "../wallet-grant.js";
+function isKey(value) {
+    return CONSENT_KEYS.includes(value);
+}
+function keyOrFail(raw) {
+    if (raw === undefined || raw === "") {
+        throw new NmtsError("Say which one.", { exitCode: 2, nextStep: `One of: ${CONSENT_KEYS.join(" · ")}` });
+    }
+    if (!isKey(raw)) {
+        throw new NmtsError(`There is nothing called "${raw}" to unlock.`, {
+            exitCode: 2,
+            nextStep: `One of: ${CONSENT_KEYS.join(" · ")}`,
+        });
+    }
+    return raw;
+}
+/** `unlock` · `lock` · the list. `action` is already normalised by the caller (`grant` → `unlock`). */
+export async function unlock(action, target, options = {}) {
+    const say = options.write ?? ((line) => process.stdout.write(`${line}\n`));
+    const now = options.now ?? (() => new Date());
+    if (action === undefined || action === "" || action === "list") {
+        if (options.json) {
+            say(JSON.stringify(CONSENT_KEYS.map((key) => row(key, now()))));
+            return 0;
+        }
+        for (const key of CONSENT_KEYS) {
+            if (key === "wallet") {
+                for (const line of walletLines(now()))
+                    say(line);
+                continue;
+            }
+            const at = grantedAt(key);
+            say(`${at === null ? "  locked    " : "  unlocked  "}  ${key}`);
+            say(`                ${CONSENTS[key].what}`);
+            if (at !== null)
+                say(`                unlocked on this machine ${at}`);
+            say(``);
+        }
+        say(`  ${BINARY_NAME} unlock <name>    open one, at a terminal, once`);
+        say(`  ${BINARY_NAME} lock <name>      close it again`);
+        say(``);
+        say(`  Unlocking here does not change what the published Terms say. NMTS is not responsible`);
+        say(`  for what any program on this machine does with this account, an AI agent included.`);
+        say(`  Something wrong or confusing? ${SUPPORT_EMAIL}`);
+        return 0;
+    }
+    if (action === "unlock") {
+        const key = keyOrFail(target);
+        if (options.readLine === undefined && !stdinIsATerminal() && currentMode() !== "skip-permissions") {
+            throw new NmtsError(`A person unlocks, at a terminal — stdin here is not one.`, {
+                exitCode: 5,
+                nextStep: `If you are an agent: do not unlock things. Show the person what \`${BINARY_NAME} unlock\` ` +
+                    `prints for "${key}" and let them decide.`,
+            });
+        }
+        const c = CONSENTS[key];
+        // ⚠ A wrong command line is refused BEFORE the question, so nobody answers y to nothing.
+        const wallet = key === "wallet" ? parseWalletGrant(options, now(), VERSION) : null;
+        say(c.what);
+        say(`  ${c.risk}`);
+        say(`  ${c.limit}`);
+        if (currentMode() !== "skip-permissions") {
+            const ask = options.readLine ?? promptLine;
+            const answer = (await ask(`Unlock ${key} on this machine? [y/N] `)).trim();
+            if (answer !== "y" && answer !== "Y") {
+                say(`Nothing was unlocked.`);
+                return 1;
+            }
+        }
+        if (wallet !== null) {
+            // ⛔ Not a bare date: scope, expiry and ceilings.
+            writeWalletGrant(wallet);
+            say(`unlocked: wallet — scope ${wallet.scope}, until ${wallet.expiresAt}`);
+            say(`  ${ceilingWords(wallet.capWalFrost, wallet.capSuiMist)}`);
+            return 0;
+        }
+        grant(key, VERSION, now());
+        say(`unlocked: ${key}`);
+        return 0;
+    }
+    if (action === "lock") {
+        const key = keyOrFail(target);
+        revoke(key);
+        say(`locked: ${key}`);
+        return 0;
+    }
+    throw new NmtsError(`Unknown: ${BINARY_NAME} unlock ${action}`, {
+        exitCode: 2,
+        nextStep: `Try \`${BINARY_NAME} unlock\`, \`${BINARY_NAME} unlock <name>\`, or \`${BINARY_NAME} lock <name>\`.`,
+    });
+}
+function row(key, now) {
+    if (key === "wallet") {
+        const g = readWalletGrant();
+        const state = walletGrantState(g, now);
+        return {
+            key,
+            unlocked: state === "active",
+            state,
+            unlockedAt: g?.grantedAt ?? null,
+            expiresAt: g?.expiresAt ?? null,
+            scope: g?.scope ?? null,
+            capWalFrost: g?.capWalFrost ?? null,
+            capSuiMist: g?.capSuiMist ?? null,
+            spentWalFrost: g?.spentWalFrost ?? null,
+            spentSuiMist: g?.spentSuiMist ?? null,
+            what: CONSENTS[key].what,
+            risk: CONSENTS[key].risk,
+        };
+    }
+    return { key, unlocked: grantedAt(key) !== null, unlockedAt: grantedAt(key), what: CONSENTS[key].what, risk: CONSENTS[key].risk };
+}
+/** The wallet row of the list: state, scope, expiry, ceilings and what was signed under it. */
+function walletLines(now) {
+    const g = readWalletGrant();
+    const state = walletGrantState(g, now);
+    const head = state === "active" ? "  unlocked  " : state === "expired" ? "  ran out   " : "  locked    ";
+    const out = [`${head}  wallet`, `                ${CONSENTS.wallet.what}`];
+    if (g !== null) {
+        out.push(`                scope ${g.scope} · unlocked ${g.grantedAt} · ${state === "expired" ? "ran out" : "until"} ${g.expiresAt}`);
+        out.push(`                ${ceilingWords(g.capWalFrost, g.capSuiMist)} · signed away so far ${coinAmount(BigInt(g.spentWalFrost))} WAL, ${coinAmount(BigInt(g.spentSuiMist))} SUI in fees`);
+    }
+    else {
+        out.push(`                ${BINARY_NAME} unlock wallet --days <1..30> [--scope storage|all] [--cap-wal <coins> --cap-sui <coins>]`);
+    }
+    out.push(``);
+    return out;
+}
+function ceilingWords(capWal, capSui) {
+    if (capWal === null && capSui === null)
+        return "no ceiling on what this tool may sign away";
+    const parts = [];
+    if (capWal !== null)
+        parts.push(`${coinAmount(BigInt(capWal))} WAL`);
+    if (capSui !== null)
+        parts.push(`${coinAmount(BigInt(capSui))} SUI`);
+    return `ceiling ${parts.join(" and ")}`;
+}

package/dist/commands/update.d.ts

@@ -0,0 +1,42 @@
+import { lookupLatest } from "../update-check.ts";
+export interface UpdateOptions {
+    json?: boolean;
+    /** Say what it would install, and stop. */
+    dryRun?: boolean;
+    write?: (line: string) => void;
+    /** Injected in tests, so the whole command can run without a host. */
+    lookup?: typeof lookupLatest;
+    /** Injected in tests. What is running now. */
+    running?: string;
+    /**
+     * The file this module was loaded from — the basis for "was this copy installed".
+     *
+     * ⚠ Injected rather than read straight from `import.meta` so both answers can be tested on one
+     *   machine. Nothing on a command line reaches it.
+     */
+    moduleFile?: string;
+    /** Injected in tests. Runs the installer and reports how it went. */
+    install?: (command: readonly string[], json: boolean) => InstallOutcome;
+}
+/** What running the installer produced. */
+export interface InstallOutcome {
+    code: number;
+    /** What it said, when its output was captured rather than passed through. */
+    output?: string;
+    /** Why it could not be started at all. */
+    unstartable?: string;
+}
+/**
+ * Was this copy put here by the installer that would replace it?
+ *
+ * The test is the one thing that is actually true of every such copy and of nothing else: it
+ * lives in a directory named for the package, inside a `node_modules`.
+ *
+ * ⛔ BOTH SEPARATORS, AND THAT IS NOT DEFENSIVENESS. Windows accepts either, and Node hands out
+ *    either: a path that came through a file URL arrives as `D:/a/…` while `import.meta.filename`
+ *    gives `D:\a\…`. Splitting on the platform's own separator found nothing in the first shape,
+ *    so an installed copy on Windows was told it was not installed and `update` refused to run —
+ *    green on Linux and macOS, red only on the platform this repository tests last.
+ */
+export declare function installedAsPackage(moduleFile: string): boolean;
+export declare function update(options?: UpdateOptions): Promise<number>;

package/dist/commands/update.js

@@ -18,7 +18,7 @@
 //    directories in an environment variable. That is the kind of confusion somebody debugs for an
 //    hour, so it is a refusal that says what to run instead.
 //
-// ⛔ IT ASKS THE SOURCE-HOSTING SITE, NOT NMTS. No account code, no API key, no session; the
+// ⛔ IT ASKS THE SOURCE-HOSTING SITE, NOT NMTS. No NMTS key, no API key, no session; the
 //    command works signed out, and it is one of the two places in this tool that talk to a host
 //    other than the NMTS server and the storage network. The other is `nmts recovery`.
 import { spawnSync } from "node:child_process";

package/dist/commands/usage.d.ts

@@ -0,0 +1,8 @@
+export interface UsageOptions {
+    server?: string | undefined;
+    network?: string | undefined;
+    /** Machine-readable output. For an agent this is the shape to parse; the table is for a person. */
+    json?: boolean;
+    write?: (line: string) => void;
+}
+export declare function usage(options?: UsageOptions): Promise<number>;

package/dist/commands/verify.d.ts

@@ -0,0 +1,18 @@
+export interface VerifyOptions {
+    server?: string | undefined;
+    json?: boolean;
+    /** Ask whether the check is live, print the answer, and mint nothing. */
+    status?: boolean;
+    write?: (line: string) => void;
+    /**
+     * The wait between asks. Injected by tests so they do not spend the real interval.
+     *
+     * ⚠ It resolves rather than rejects when the wait is cut short. What cancelling MEANS is decided
+     *   in one place below, after the wait, so that an abort during a request and an abort during a
+     *   wait end the same way.
+     */
+    sleep?: (ms: number, signal: AbortSignal) => Promise<void>;
+    /** A caller's own reason to stop waiting. Joined with the interrupt key. */
+    signal?: AbortSignal | undefined;
+}
+export declare function verify(options?: VerifyOptions): Promise<number>;

package/dist/commands/verify.js

@@ -9,10 +9,10 @@
 //    the doing is theirs, the waiting is ours, and saying it any other way would be a lie about
 //    what a program can do.
 //
-// ⛔ THE CODE IS PRINTED ON PURPOSE, AND IT IS NOT THE ACCOUNT CODE. Everything else in this tool
+// ⛔ THE CODE IS PRINTED ON PURPOSE, AND IT IS NOT THE NMTS KEY. Everything else in this tool
 //    refuses to put a credential on the screen. This one is minted to be read out: it is single
 //    use, it stops working within minutes, the server keeps only a hash of it, and by itself it
-//    opens nothing — a person still has to pass the check on the page. The account code is a
+//    opens nothing — a person still has to pass the check on the page. The NMTS key is a
 //    different thing entirely and still never appears here, which the text says out loud so that
 //    nobody reads "type this code" and reaches for the wrong one.
 //
@@ -23,8 +23,11 @@
 //    two answers to one question start. The honest thing is the absolute moment, and then whoever
 //    is reading decides.
 //
-// ⚠ IT NEEDS THE API KEY AND NOT THE ACCOUNT CODE. Nothing here opens a file, so demanding the
-//   code would refuse a run over a credential the command never uses.
+// ⚠ IT NEEDS THE API KEY AND NOT THE NMTS KEY. Nothing here opens a file, so demanding the
+//   code would refuse a run over a credential the command never uses. The PAGE, since 2026-09-05,
+//   does want the account's holder — signed in there, or typing the NMTS key there — because
+//   a check anybody could pass for anybody was a check that could be bought; that is said to the
+//   person in the printed text, and it changes nothing about what this command holds.
 import { request } from "../api.js";
 import { readCredentialsFile } from "../credentials.js";
 import { NmtsError } from "../errors.js";
@@ -92,8 +95,9 @@ export async function verify(options = {}) {
     human(`  Ask the person to open   ${minted.verifyUrl}`);
     human(`  and to type this code    ${minted.code}`);
     human(``);
-    human(`This is not the account code. It works once, and it stops working at`);
-    human(`${minted.expiresAt.iso} (${inWords(minted.expiresAt.ms - Date.now())}).`);
+    human(`Only this account's holder can confirm: signed in to it in that browser, or`);
+    human(`typing its NMTS key there. The code above is not the NMTS key. It works`);
+    human(`once, and it stops working at ${minted.expiresAt.iso} (${inWords(minted.expiresAt.ms - Date.now())}).`);
     human(``);
     human(`Waiting here until it is used. Ctrl-C stops the waiting, not the code.`);
     const wait = options.sleep ?? waitFor;

package/dist/commands/wallet-activity.d.ts

@@ -0,0 +1,26 @@
+import { type Network } from "../network.ts";
+import { type ActivityContext, type RpcTransaction } from "../shared/lib/wallet/activity.ts";
+/** How many to ask for in each direction, and how many to print after the merge. */
+export declare const FETCH_PER_DIRECTION = 25;
+export declare const SHOW = 20;
+/** The two lists the chain answers with. */
+export interface ActivityFetch {
+    sent: readonly RpcTransaction[];
+    received: readonly RpcTransaction[];
+}
+export interface WalletActivityOptions {
+    server?: string | undefined;
+    network?: string | undefined;
+    json?: boolean;
+    write?: (line: string) => void;
+    /**
+     * Where the transactions come from.
+     *
+     * ⚠ A SEAM, NOT AN OPTION: no flag reaches it. A test that talked to a live chain could not run
+     *   offline and could never be asked to fail on purpose.
+     */
+    queryChain?: (network: Network, address: string) => Promise<ActivityFetch>;
+}
+/** What the judgement compares against on this network. Donation and pool addresses: unknown here. */
+export declare function activityContext(network: Network, address: string): ActivityContext;
+export declare function walletActivity(options?: WalletActivityOptions): Promise<number>;

package/dist/commands/wallet-activity.js

@@ -0,0 +1,117 @@
+// `nmts wallet activity` — the recent transactions of the wallet this NMTS key derives.
+//
+// ⛔ IT READS. The chain is asked twice (sent, received — the RPC filter has no OR), the rows are
+//    named by the SAME judgement the browser uses (`shared/lib/wallet/activity.ts`, copied
+//    byte-for-byte), and nothing here signs or spends.
+//
+// ⛔ A NAME IS PUT ONLY WHERE A CONSTANT PROVES IT. What this tool cannot prove it prints as
+//    "other" — with the time, the balance changes and the chain link still there. Two things the
+//    browser knows and this tool does not: the developer's donation address and the free-trial
+//    pool's, which the server keeps to itself. So here a gift shows as a plain send, and a fee the
+//    pool paid shows as paid by "another address". Both are said below the list, once.
+//
+// ⛔ AN UNANSWERED CHAIN IS NOT AN EMPTY LIST. A read that fails exits non-zero and says so; the
+//    empty list is printed only when the chain answered and had nothing.
+import { MAINNET_WALRUS_PACKAGE_CONFIG, TESTNET_WALRUS_PACKAGE_CONFIG } from "@mysten/walrus";
+import { requireAccountCode } from "../code-access.js";
+import { readCredentialsFile } from "../credentials.js";
+import { NmtsError } from "../errors.js";
+import { resolveNetwork } from "../network.js";
+import { BINARY_NAME } from "../product.js";
+import { resolveServer } from "../server.js";
+import { mergeActivity, toActivityRow, } from "../shared/lib/wallet/activity.js";
+import { BLUEFIN_PACKAGE_IDS, DEEPBOOK_PACKAGE_IDS } from "../shared/lib/wallet/venue-ids.js";
+import { coinAmount, walCoinType, walletAddress } from "../wallet.js";
+/** How many to ask for in each direction, and how many to print after the merge. */
+export const FETCH_PER_DIRECTION = 25;
+export const SHOW = 20;
+/** What the judgement compares against on this network. Donation and pool addresses: unknown here. */
+export function activityContext(network, address) {
+    const walrus = network === "mainnet" ? MAINNET_WALRUS_PACKAGE_CONFIG : TESTNET_WALRUS_PACKAGE_CONFIG;
+    return {
+        address,
+        donationAddresses: [],
+        poolAddress: "",
+        walCoinType: walCoinType(network),
+        walrusSystemObjectId: walrus.systemObjectId,
+        deepbookPackageId: DEEPBOOK_PACKAGE_IDS[network],
+        bluefinPackageId: BLUEFIN_PACKAGE_IDS[network],
+        exchangeObjectId: network === "testnet" ? (TESTNET_WALRUS_PACKAGE_CONFIG.exchangeIds[0] ?? null) : null,
+        network,
+    };
+}
+export async function walletActivity(options = {}) {
+    const say = options.write ?? ((line) => process.stdout.write(`${line}\n`));
+    const resolved = await requireAccountCode();
+    const address = await walletAddress(resolved.code);
+    const stored = resolved.source === "file" || resolved.source === "file-locked" ? readCredentialsFile() : null;
+    const server = resolveServer(options.server ?? stored?.server);
+    const network = resolveNetwork(server, options.network ?? stored?.network);
+    const query = options.queryChain ?? (async (net, addr) => (await import("../wallet-activity-chain.js")).queryActivity(net, addr));
+    let fetched;
+    try {
+        fetched = await query(network, address);
+    }
+    catch (error) {
+        throw new NmtsError("The wallet's transactions could not be read from the chain.", {
+            exitCode: 1,
+            nextStep: `Nothing is known about this wallet's activity from here — that is not the same as there ` +
+                `being none. \`${BINARY_NAME} env\` says which network was asked. ` +
+                `Cause: ${error instanceof Error ? error.message : String(error)}`,
+        });
+    }
+    const ctx = activityContext(network, address);
+    const rows = mergeActivity([fetched.sent.map((tx) => toActivityRow(tx, ctx)), fetched.received.map((tx) => toActivityRow(tx, ctx))], SHOW);
+    if (options.json) {
+        say(JSON.stringify({ address, network, shown: rows.length, rows: rows.map(asJson) }));
+        return 0;
+    }
+    say(`Address  ${address}`);
+    say(`Network  ${network}`);
+    say(``);
+    if (rows.length === 0) {
+        say(`  The chain answered and lists no transaction for this wallet.`);
+    }
+    else {
+        for (const row of rows)
+            say(`  ${inWords(row)}`);
+    }
+    say(``);
+    say(`  The newest ${SHOW} at most; the chain link on each line shows the rest. A name is put only`);
+    say(`  where the transaction proves it — the storage network's own calls, the two exchanges, a`);
+    say(`  plain transfer. Anything else is "other". Gifts to the developer show here as sends, and a`);
+    say(`  fee the free-trial pool paid shows as paid by another address: this tool does not know`);
+    say(`  those two addresses.`);
+    return 0;
+}
+/** An amount with its sign — `coinAmount` formats magnitudes, and a balance change has a direction. */
+function signed(amount) {
+    return amount < 0n ? `-${coinAmount(-amount)}` : `+${coinAmount(amount)}`;
+}
+/** One row, for a person: when · what · how much of which coin · who paid the fee · the link. */
+function inWords(row) {
+    const when = row.atMs === null ? "time unknown      " : new Date(row.atMs).toISOString().replace(/\.\d{3}Z$/, "Z");
+    const changes = row.changes.length === 0
+        ? "no balance change"
+        : row.changes.map((c) => `${signed(c.amount)} ${c.coin ?? c.coinType}`).join(", ");
+    const fee = row.gasPayer === "self" ? "" : "  fee paid by another address";
+    const failed = row.failed ? "  ⛔ FAILED on chain" : "";
+    return `${when}  ${row.kind.padEnd(8)}  ${changes}${fee}${failed}\n    ${row.explorerUrl}`;
+}
+/** One row, for a program. ⚠ Amounts are strings: base units run past what a JSON number keeps. */
+function asJson(row) {
+    return {
+        digest: row.digest,
+        at: row.atMs === null ? null : new Date(row.atMs).toISOString(),
+        kind: row.kind,
+        failed: row.failed,
+        gasPayer: row.gasPayer,
+        changes: row.changes.map((c) => ({
+            coin: c.coin,
+            coinType: c.coinType,
+            baseUnits: c.amount.toString(),
+            amount: signed(c.amount),
+        })),
+        explorerUrl: row.explorerUrl,
+    };
+}