@needmoretruth/nmts-cli 0.17.2 → 0.34.1

package/dist/net-retry.d.ts

@@ -0,0 +1,38 @@
+/**
+ * How long a command goes on trying before it reports the failure.
+ *
+ * ⛔ SHORTER THAN ANYTHING ELSE, BECAUSE SOMEBODY TYPED THIS AND IS LOOKING AT IT. The long budget
+ *    is for work nobody is watching -- a page uploading in the background, which has money already
+ *    spent on it and resumes where it stopped. A terminal that sits silent is indistinguishable
+ *    from one that has hung, an agent has a deadline of its own, and running the command again
+ *    costs nothing. What this has to cover is a link that blinks, not a server that is down.
+ */
+export declare const CLI_RETRY_BUDGET_MS: number;
+/** Told before each wait, so a terminal can say the tool is waiting rather than stuck. */
+export type WaitReporter = (info: {
+    attempt: number;
+    waitMs: number;
+    error: unknown;
+}) => void;
+export interface KeepTryingOptions {
+    /** Whether this failure is worth repeating. ⛔ Required: see the header. */
+    readonly retryable: (error: unknown) => boolean;
+    readonly onWait?: WaitReporter;
+    readonly signal?: AbortSignal;
+    /** How long to keep trying, in ms. Omit for {@link CLI_RETRY_BUDGET_MS}. */
+    readonly budgetMs?: number;
+    /** Injected so a test runs a flapping link in milliseconds rather than in minutes. */
+    readonly now?: () => number;
+    readonly random?: () => number;
+    readonly sleep?: (ms: number) => Promise<void>;
+}
+/** Run `step` until it succeeds or the budget is spent. Rejects with the LAST error. */
+export declare function keepTrying<T>(step: () => Promise<T>, options: KeepTryingOptions): Promise<T>;
+/**
+ * Is this failure one that asking again could fix?
+ *
+ * ⛔ A REFUSAL IS NOT A BLIP. The server saying no -- wrong key, no credits, not found -- is an
+ *    answer, and repeating it spends the budget to hear it again later. Only the shapes that mean
+ *    "nobody answered" or "not right now" come back here as true.
+ */
+export declare function isTransient(error: unknown, status?: number): boolean;

package/dist/network.d.ts

@@ -0,0 +1,10 @@
+export declare const NETWORKS: readonly ["mainnet", "testnet"];
+export type Network = (typeof NETWORKS)[number];
+export declare const NETWORK_ENV_VAR = "NMTS_NETWORK";
+/**
+ * Decide the network for this run.
+ *
+ * `explicit` beats the environment, which beats the one inference this function is willing to
+ * make: the live server is mainnet. Anything else and it refuses.
+ */
+export declare function resolveNetwork(server: string, explicit?: string | undefined): Network;

package/dist/notice.d.ts

@@ -0,0 +1,7 @@
+/**
+ * The text shown before an NMTS key is stored on this machine.
+ *
+ * Every sentence here is a measured fact about how NMTS works, not a prediction and not a
+ * comparison. If any of it stops being true, this text is wrong and must change with the code.
+ */
+export declare function firstRunNotice(): string;

package/dist/notice.js

@@ -1,6 +1,6 @@
-// The one thing this tool says before it keeps an account code on a machine.
+// The one thing this tool says before it keeps an NMTS key on a machine.
 //
-// ⛔ WHY IT EXISTS. Handing an agent your account code is handing it the vault: in NMTS every key
+// ⛔ WHY IT EXISTS. Handing an agent your NMTS key is handing it the vault: in NMTS every key
 //    is derived from that one code — the file keys and the wallet both — so an agent that leaks it
 //    has leaked everything at once, and the account cannot be re-keyed because the account IS the
 //    code. The owner asked for this to be said out loud (2026-08-23).
@@ -17,16 +17,16 @@
 //    the moment the decision is made — when the code is first written to this machine.
 import { PRODUCT_NAME } from "./product.js";
 /**
- * The text shown before an account code is stored on this machine.
+ * The text shown before an NMTS key is stored on this machine.
  *
  * Every sentence here is a measured fact about how NMTS works, not a prediction and not a
  * comparison. If any of it stops being true, this text is wrong and must change with the code.
  */
 export function firstRunNotice() {
     return [
-        `${PRODUCT_NAME} is about to keep your account code on this machine.`,
+        `${PRODUCT_NAME} is about to keep your NMTS key on this machine.`,
         ``,
-        `  Your account code is the only key to your account. The keys that encrypt`,
+        `  Your NMTS key is the only key to your account. The keys that encrypt`,
         `  your files and the keys to your wallet are all derived from it.`,
         ``,
         `  Keeping it here is what lets this tool work while you are away. It also`,
@@ -35,8 +35,8 @@ export function firstRunNotice() {
         ``,
         `  If it leaves this machine — in a log line, in a prompt, in a repository —`,
         `  whoever holds it can read every file in the account and spend from the`,
-        `  wallet. NMTS cannot undo that: requests made with your code cannot be`,
-        `  told apart from your own, and the code cannot be changed while keeping`,
+        `  wallet. NMTS cannot undo that: requests made with your NMTS key cannot be`,
+        `  told apart from your own, and it cannot be changed while keeping`,
         `  the account.`,
         ``,
         `  Give an agent an account you would be willing to lose.`,

package/dist/product.d.ts

@@ -0,0 +1,29 @@
+/** What a person reads, and what the tool calls itself. Owner-settled 2026-08-23. */
+export declare const PRODUCT_NAME = "nmts";
+/** What an agent types. The same word: there is nothing to translate between the two. */
+export declare const BINARY_NAME = "nmts";
+/**
+ * This build's version.
+ *
+ * ⛔ Kept here rather than read from `package.json`: the published build has no package.json
+ *    beside it. Here rather than in `main.ts` because the MCP server has to say it too, and a
+ *    command importing the entry point is a cycle waiting to bite.
+ */
+export declare const VERSION = "0.34.1";
+/** Where the product lives, for messages that need to send somebody somewhere real. */
+export declare const HOME_URL = "https://nmts.me";
+/** The source, so a person holding only the built program can find what it was built from. */
+export declare const SOURCE_URL = "https://github.com/needmoretruth/nmts-cli";
+/** Who holds the copyright. One place, because it is also the answer to "who can license this". */
+export declare const COPYRIGHT = "Copyright 2026 needmoretruth";
+/**
+ * Where to write about a fault, a confusing message, or anything that got in the way.
+ *
+ * ⛔ IT IS IN THE TOOL AND NOT ONLY IN THE README, because the moment somebody wants to report
+ *    something is the moment it went wrong -- and that is exactly when nobody goes looking for a
+ *    web page. The smallest annoyance is worth an email; most of them are cheap to fix and
+ *    invisible from here.
+ */
+export declare const SUPPORT_EMAIL = "nmts@nmts.me";
+/** The document in the source repository that is written for an agent rather than for a person. */
+export declare const AGENTS_DOC = "AGENTS.md";

package/dist/product.js

@@ -18,7 +18,7 @@ export const BINARY_NAME = "nmts";
  *    beside it. Here rather than in `main.ts` because the MCP server has to say it too, and a
  *    command importing the entry point is a cycle waiting to bite.
  */
-export const VERSION = "0.17.2";
+export const VERSION = "0.34.1";
 /** Where the product lives, for messages that need to send somebody somewhere real. */
 export const HOME_URL = "https://nmts.me";
 /** The source, so a person holding only the built program can find what it was built from. */

package/dist/progress.d.ts

@@ -0,0 +1,37 @@
+/** Where a report goes. Split out so a test can drive it without a terminal. */
+export interface ProgressSink {
+    write(text: string): void;
+    /** True for a terminal that can rewrite its last line. */
+    interactive: boolean;
+}
+export declare function stderrSink(): ProgressSink;
+/** A reporter that says nothing. What `--json` gets, and what a test gets by default. */
+export declare function silentSink(): ProgressSink;
+/**
+ * Report progress through one phase.
+ *
+ * On a terminal the line rewrites in place, to a tenth of a percent — fine enough that a large
+ * upload visibly moves rather than appearing to hang. Into a pipe it prints a plain line every ten
+ * percent, which is legible in a log and small enough not to bury the result.
+ */
+export declare class Progress {
+    private readonly sink;
+    private readonly label;
+    private lastPrinted;
+    private dirty;
+    constructor(sink: ProgressSink, label: string);
+    update(done: number, total: number): void;
+    /** Finish the line, so whatever prints next starts clean. */
+    done(): void;
+}
+/**
+ * A `fetch` that counts the bytes of the request body as they go out.
+ *
+ * ⛔ THE BODY IS RE-WRAPPED, NOT RE-READ. The bytes are handed to the request as a stream that
+ *    reports each chunk on its way past, so nothing is copied and the count is what actually left
+ *    rather than what was queued.
+ *
+ * ⚠ `duplex: "half"` is required by the fetch specification for a streaming body and Node enforces
+ *   it. Without it the request throws before a single byte is sent.
+ */
+export declare function countingFetch(onSent: (sent: number, total: number) => void, chunkBytes?: number): (url: RequestInfo, init?: RequestInit) => Promise<Response>;

package/dist/prompt.d.ts

@@ -0,0 +1,31 @@
+/**
+ * Hold the terminal in raw mode across a RUN of prompts.
+ *
+ * ⛔ WITHOUT THIS, THE GAP BETWEEN TWO PROMPTS ECHOES. `promptSecret` sets raw mode for its own
+ *    question and restores it afterwards, which was right while this tool asked one thing. `login`
+ *    now asks three in a row with work in between (the code is checked before a passphrase is
+ *    asked for), and in that gap the terminal is back in line mode: it echoes what is typed, and
+ *    its line discipline holds whole lines that the next prompt then never sees. Measured through
+ *    a pty: a paste of code + passphrase + confirmation ended in "Cancelled" with both
+ *    passphrases printed on the screen.
+ *
+ * ⚠ Restoring is what the `finally` is for, including on a throw — a process that exits leaving a
+ *   terminal in raw mode leaves the person's shell unusable.
+ */
+export declare function holdTerminal<T>(body: () => Promise<T>): Promise<T>;
+export declare function stdinIsATerminal(): boolean;
+/** Ask for a secret on the terminal, echoing nothing. Ctrl-C and Ctrl-D abandon the prompt. */
+export declare function promptSecret(question: string, envVar: string): Promise<string>;
+/**
+ * Ask a question whose answer is not a secret, and echo what is typed.
+ *
+ * ⛔ NOT FOR SECRETS. `promptSecret` exists for those: it turns echo off and wipes what it read.
+ *    This one is for a choice, where seeing what you typed is the point.
+ *
+ * ⛔ IT MUST NOT BE CALLED INSIDE `holdTerminal`. That puts the terminal in raw mode, where
+ *    readline gets characters one at a time and no line ever arrives.
+ *
+ * ⚠ Returns the empty string when there is no terminal, so callers can treat "nobody was there"
+ *   as "nothing was chosen" rather than as an answer. A setup script must not hang here.
+ */
+export declare function promptLine(question: string): Promise<string>;

package/dist/prompt.js

@@ -1,6 +1,6 @@
 // Reading a secret from a terminal without putting it on the screen.
 //
-// ⛔ WHY NOT `readline`. It echoes what is typed, and an account code on screen ends up in
+// ⛔ WHY NOT `readline`. It echoes what is typed, and an NMTS key on screen ends up in
 //    scrollback, in a screen share, and in the terminal recording some agents keep. The usual
 //    workaround — swapping `process.stdout.write` for a muted one while the question is open — is
 //    a global mutation in a process that may be writing other output, and it stays broken if the

package/dist/rebuild-key-check.d.ts

@@ -0,0 +1,26 @@
+import { type CryptoGlue } from "./crypto.ts";
+import type { SourceItem } from "./rebuild.ts";
+import { type PairVerdict } from "./shared/lib/drive/rebuild-verify.ts";
+import type { ReadOptions } from "./walrus.ts";
+export interface KeyCheckInput {
+    server: string;
+    apiKey: string;
+    /** The NMTS key, used once to derive the data key that opens the wrapped file keys. */
+    accountCode: string;
+    /** Which chain's aggregators hold the bytes — `mainnet` or `testnet`. */
+    chain: string;
+    read?: ReadOptions | undefined;
+    crypt: CryptoGlue;
+}
+/**
+ * A checker for this account, plus the way to forget the key it holds.
+ *
+ * ⛔ THE DATA KEY IS DERIVED ONCE, NOT PER FILE. Deriving it is a 64 MiB Argon2id pass; doing that
+ *    per row would turn a thousand-file account into an hour of key derivation. It is held for the
+ *    length of one rebuild and wiped by `done()`, which every path out of the caller reaches.
+ */
+export interface AccountKeyCheck {
+    check(item: SourceItem): Promise<PairVerdict>;
+    done(): void;
+}
+export declare function accountKeyCheck(input: KeyCheckInput): AccountKeyCheck;

package/dist/rebuild-key-check.js

@@ -0,0 +1,90 @@
+// Showing that one rebuilt row's key opens that row's own bytes.
+//
+// The RULE — why an unchecked pair is a defect and why an unknown answer is never a pass — is
+// written once in `shared/lib/drive/rebuild-verify.ts`, which the browser and this tool share
+// byte-for-byte. This file is only HOW this tool answers the question for one row.
+//
+// ⛔ IT READS 72 BYTES PER FILE, NOT A FILE. NCF-3 §4.2 puts a key commitment in the part header
+//    and `StreamDecryptor` checks it in constant time before any chunk is touched, so constructing
+//    a decryptor over the header ALONE is the whole answer — no ciphertext, no tag, no chunk. The
+//    read is the ordinary aggregator read `nmts get` uses, with a byte range on it.
+//
+// ⛔ NOTHING NEW IS ASKED OF THE SERVER. `GET /v1/items/{id}/parts` is the descriptor a download
+//    already fetches; it is asked here WITHOUT `?for=download`, because nothing is being
+//    downloaded and the counter behind that flag is for bytes people actually take.
+//
+// ⛔ A FAILURE IS A VERDICT, NOT A REFUSAL. A dead aggregator, a part on a storage network this
+//    build cannot read, a row the server describes strangely: each one leaves that file's key off
+//    the rebuilt list and says why. None of them may stop the rebuild — an account left un-rebuilt
+//    is worse than one rebuilt with a few keys withheld, and both are far better than a list that
+//    seals a pairing nobody checked.
+import { request } from "./api.js";
+import { AAD, DERIVED } from "./crypto.js";
+import { asParts, fetchPart } from "./download-part.js";
+import { NCF3_HEADER_BYTES } from "./shared/lib/drive/rebuild-verify.js";
+export function accountKeyCheck(input) {
+    const { crypt } = input;
+    const [from, to] = DERIVED.dataKey;
+    const derived = crypt.kdf_derive(crypt.account_code_parse(input.accountCode));
+    const dataKey = derived.slice(from, to);
+    // ⛔ The whole derivation — every other key this account has — is wiped immediately. Only the
+    //    32 bytes that open wrapped file keys are kept, and only until `done()`.
+    derived.fill(0);
+    return {
+        check: (item) => checkOne(input, dataKey, item),
+        done: () => dataKey.fill(0),
+    };
+}
+async function checkOne(input, dataKey, item) {
+    const wrapped = item.dekWrapped;
+    // Answered by the shared layer already; kept so this function is total on its own input.
+    if (wrapped === undefined || wrapped === "")
+        return { ok: false, reason: "no-key" };
+    let header;
+    try {
+        // ⚠ The address is written out as a literal because the gate that compares this tool's
+        //   addresses against the server's registered routes reads literals.
+        const described = asParts(await request(input.server, `/v1/items/${encodeURIComponent(item.id)}/parts`, {
+            token: input.apiKey,
+        }));
+        // ⛔ FOUND BY ITS NUMBER, NOT BY ITS POSITION. The order the rows arrive in is the server's
+        //    choice, and not trusting the server's arrangement is the entire point of this check.
+        const first = described.parts.find((p) => p.part_index === 0);
+        if (first === undefined)
+            return { ok: false, reason: "no-parts" };
+        header = await fetchPart(first, input.chain, {
+            ...(input.read ?? {}),
+            range: { start: 0, end: NCF3_HEADER_BYTES },
+        });
+    }
+    catch {
+        // Every way the bytes did not arrive. ⛔ Not `wrong-key`: reporting a pair as wrong because an
+        // aggregator was down would tell somebody their file is unopenable when it is not.
+        return { ok: false, reason: "unreadable" };
+    }
+    if (header.length < NCF3_HEADER_BYTES)
+        return { ok: false, reason: "unreadable" };
+    let dek;
+    try {
+        dek = input.crypt.envelope_open(dataKey, new TextEncoder().encode(AAD.dekWrap), Buffer.from(wrapped, "base64url"));
+    }
+    catch {
+        // The wrapped key does not open under this account's data key at all — so whatever it is, it
+        // is not this account's key for this file.
+        return { ok: false, reason: "wrong-key" };
+    }
+    let opener;
+    try {
+        opener = new input.crypt.StreamDecryptor(dek, header.subarray(0, NCF3_HEADER_BYTES));
+    }
+    catch {
+        // The key commitment in the header did not match this key: the pair is WRONG, not unproven.
+        return { ok: false, reason: "wrong-key" };
+    }
+    finally {
+        dek.fill(0);
+    }
+    // Nothing is fed to it — the header was the question and it has been answered.
+    opener.free();
+    return { ok: true };
+}

package/dist/rebuild.d.ts

@@ -0,0 +1,87 @@
+import type { ManifestEntry } from "./shared/lib/drive/manifest-codec.ts";
+import { type PairingVerdicts, type PairVerdict, type UnverifiedPair } from "./shared/lib/drive/rebuild-verify.ts";
+/**
+ * Stand-in name for a file the server can no longer name. Deliberately not a sentence and
+ * deliberately language-neutral: it sits in the field a person's own file names sit in, and the
+ * only thing to do with it is type over it.
+ */
+export declare function placeholderName(id: string): string;
+/** One stored file, as the server still knows it. */
+export interface SourceItem {
+    id: string;
+    size: number;
+    createdAt: number;
+    updatedAt: number;
+    /** Present when the row is in the trash. */
+    deletedAt?: number;
+    /** The wrapped file key. Absent on a row committed before the server kept one. */
+    dekWrapped?: string;
+    /** The sealed whole-file hash, for verifying a download. Absent on older rows. */
+    contentHashCt?: string;
+}
+export interface RebuiltList {
+    /** The entries to seal, in the order the listings returned them. */
+    entries: ManifestEntry[];
+    /** How many came back live. */
+    live: number;
+    /** How many came back from the trash — still restorable, still stored, still charged for. */
+    trashed: number;
+    /**
+     * How many carry no wrapped key. They are still worth an entry — the row, the size and the
+     * dates are real — but nothing on any device can open their bytes, and saying so is the whole
+     * point of counting them.
+     */
+    keyless: number;
+    /** How many keys were shown to open their own file. Only these entries carry a key. */
+    verified: number;
+    /**
+     * Every file whose key was not shown to belong to it, with why, in listing order.
+     *
+     * ⛔ NOT A FAILURE ON ITS OWN. One unreadable aggregator is a file whose key is withheld until
+     *    the next rebuild; the whole account failing is a different thing, and the command tells
+     *    them apart rather than treating a bad afternoon on the network as a wrong key set.
+     */
+    unverified: readonly UnverifiedPair[];
+    /**
+     * Rows the server says it holds that this rebuild has no entry for, or null when that could not
+     * be checked. Not a failure: something thrown away before the restore window closed is exactly
+     * this, and so is a file trashed while the listings were being read.
+     */
+    unaccounted: number | null;
+}
+/**
+ * Turn the server's rows into entries.
+ *
+ * ⛔ EVERY REBUILT FILE SITS AT THE TOP OF THE DRIVE, because the server has no folder or parent
+ *    left to report and inventing one would be a guess presented as a memory.
+ *
+ * ⛔ AND NO TWO OF THEM SHARE A NAME. A placeholder is the first characters of an id, so two ids
+ *    can produce one name; in a drive addressed by path, two entries with the same path is a
+ *    lookup this tool refuses rather than resolves — a file nobody can fetch. Numbering the second
+ *    one costs nothing and the person is going to rename both anyway.
+ */
+export declare function entriesFrom(items: readonly SourceItem[], verdicts: PairingVerdicts): ManifestEntry[];
+export interface RebuildInput {
+    server: string;
+    apiKey: string;
+    /** Called as pages arrive, so a large account is not a silent wait. */
+    onProgress?: (read: number) => void;
+    /**
+     * Show that ONE row's key opens ONE row's own first sealed part — `rebuild-key-check.ts`.
+     *
+     * ⛔ REQUIRED, AND NOT OPTIONAL FOR A REASON. An optional check is a check some caller skips, and
+     *    a wrong pairing is invisible when it is written: the entry looks ordinary, seals into the
+     *    list, and is only found years later as a file that will not open.
+     */
+    verify(item: SourceItem): Promise<PairVerdict>;
+    /** Ticks while the headers are being read, so the second half is not a silent wait either. */
+    onVerifyProgress?: (checked: number, total: number) => void;
+}
+/**
+ * Read the whole account and work out the list it would be sealed as. Writes nothing.
+ *
+ * ⛔ THE TRASH IS READ SECOND AND WINS A TIE. An item thrown away between the two listings comes
+ *    back in both; the trashed row is the newer truth, and taking the live one would resurrect
+ *    something the person had just thrown away.
+ */
+export declare function rebuildFromServer(input: RebuildInput): Promise<RebuiltList>;

package/dist/rebuild.js

@@ -21,6 +21,14 @@
 //    would then agree those files do not exist — while the account goes on paying for them. An
 //    account left un-rebuilt is recoverable; a short list written over nothing is not.
 //
+// ⛔ AND NO PAIR IS WRITTEN DOWN UNCHECKED. A row's wrapped key is sealed under a fixed separator,
+//    not under the row's id, so every one of an account's keys opens under the same account key —
+//    which means a server that returned row A's key beside row B's id would produce a list whose
+//    pairs are wrong and that nothing on this side would notice. Each key is therefore tried
+//    against its own row's first sealed part (`rebuild-key-check.ts`) before the pair is sealed. A
+//    pair that does not open keeps its entry and loses its key: the entry is what says the file was
+//    there, and a key written beside the wrong file is a claim this tool cannot make.
+//
 // ⛔ THE TRASH IS PART OF IT. Trashed files are still stored, still charged for and still
 //    restorable, so a list built from the live rows alone would empty the trash of an account that
 //    rebuilt. ⚠ The server's trash view ends at the restore window: something thrown away longer
@@ -29,6 +37,7 @@
 import { request } from "./api.js";
 import { NmtsError } from "./errors.js";
 import { KIND_FILE } from "./shared/lib/drive/manifest-index.js";
+import { mayCarryKey, verifyKeyPairings, } from "./shared/lib/drive/rebuild-verify.js";
 import { uniqueFileName } from "./shared/lib/drive/unique-name.js";
 /**
  * How many pages of one listing a rebuild will read.
@@ -206,11 +215,15 @@ async function serverRowIds(base, apiKey) {
  *    lookup this tool refuses rather than resolves — a file nobody can fetch. Numbering the second
  *    one costs nothing and the person is going to rename both anyway.
  */
-export function entriesFrom(items) {
+export function entriesFrom(items, verdicts) {
     const taken = new Set();
     return items.map((item) => {
         const name = uniqueFileName(placeholderName(item.id), taken);
         taken.add(name);
+        // ⛔ THE KEY AND THE HASH TRAVEL TOGETHER OR NOT AT ALL. Both were filed beside this id by the
+        //    server, so a swap that moved one moved the other; keeping the hash without its key would
+        //    only move the failure somewhere less informative than here.
+        const paired = mayCarryKey(item.id, verdicts);
         return {
             id: item.id,
             parentId: null,
@@ -220,8 +233,8 @@ export function entriesFrom(items) {
             createdAt: item.createdAt,
             updatedAt: item.updatedAt,
             ...(item.deletedAt === undefined ? {} : { deletedAt: item.deletedAt }),
-            ...(item.dekWrapped === undefined ? {} : { dekWrapped: item.dekWrapped }),
-            ...(item.contentHashCt === undefined ? {} : { contentHashCt: item.contentHashCt }),
+            ...(!paired || item.dekWrapped === undefined ? {} : { dekWrapped: item.dekWrapped }),
+            ...(!paired || item.contentHashCt === undefined ? {} : { contentHashCt: item.contentHashCt }),
         };
     });
 }
@@ -242,7 +255,14 @@ export async function rebuildFromServer(input) {
     for (const item of trashed)
         byId.set(item.id, item);
     const items = [...byId.values()];
-    const entries = entriesFrom(items);
+    // ⛔ BEFORE ANY PAIR IS WRITTEN DOWN. Once a pairing is sealed it is carried by every later edit
+    //    and copied into the recovery list, so this is the last moment it can still be checked.
+    const verdicts = await verifyKeyPairings({
+        rows: items,
+        openFirstPartHeader: (item) => input.verify(item),
+        ...(input.onVerifyProgress === undefined ? {} : { onProgress: input.onVerifyProgress }),
+    });
+    const entries = entriesFrom(items, verdicts);
     const held = await serverRowIds(input.server, input.apiKey);
     const unaccounted = held === null ? null : [...held].filter((id) => !byId.has(id)).length;
     return {
@@ -250,6 +270,8 @@ export async function rebuildFromServer(input) {
         live: items.filter((item) => item.deletedAt === undefined).length,
         trashed: items.filter((item) => item.deletedAt !== undefined).length,
         keyless: items.filter((item) => item.dekWrapped === undefined).length,
+        verified: verdicts.verified.size,
+        unverified: verdicts.unverified,
         unaccounted,
     };
 }

package/dist/recovery-assemble.d.ts

@@ -0,0 +1,40 @@
+import { type BuiltRecoveryList } from "./recovery-build.ts";
+import { type Session } from "./session.ts";
+export interface AssembleOptions {
+    server?: string | undefined;
+    network?: string | undefined;
+    /** Ticks while the account is being read, so a large one does not look frozen. */
+    onProgress?: ((loaded: number) => void) | undefined;
+}
+export interface AssembledRecoveryList {
+    session: Session;
+    /** base64url of the 32-byte account proof. ⛔ Held for this run's requests and nothing else. */
+    proof: string;
+    built: BuiltRecoveryList;
+    /** This list's own version number. */
+    seq: number;
+    /** RFC3339, stamped before the account was read. What the server is told. */
+    capturedAt: string;
+    /** The `.nmtsmap` document and the name to offer it under. */
+    file: {
+        filename: string;
+        content: string;
+    };
+}
+export declare function assembleRecoveryList(options?: AssembleOptions): Promise<AssembledRecoveryList>;
+/**
+ * Tell the server a list was written, and what number it carries.
+ *
+ * ⛔ THE FILE FIRST, THE RECORD SECOND — so this takes the path that already exists. The record is
+ *    what makes an account screen say "your list is up to date"; saying that before the file
+ *    exists would be a claim about something that may never have been written.
+ *
+ * ⛔ `kind: "local"` AND NO BLOB ID. This tool keeps the list on the person's own disk and writes
+ *    no copy to the storage network, and the server refuses a blob id alongside `local` for
+ *    exactly that reason: a recorded address nothing was written to would let a screen advertise
+ *    a copy that does not exist.
+ *
+ * ⛔ THE ATTEMPT IS REMEMBERED WHETHER OR NOT IT LANDS. See `recovery-seq.ts`: a number the server
+ *    refused must not be the number the next run offers again, or the refusal repeats for ever.
+ */
+export declare function recordRecoveryList(assembled: AssembledRecoveryList, destination: string): Promise<void>;

package/dist/recovery-assemble.js

@@ -2,7 +2,7 @@
 //
 // ⛔ ONE PLACE, BECAUSE THE TWO COMMANDS MUST NOT DISAGREE. `recovery-list` writes the sealed list
 //    as a file of its own; `kit` writes the same document inside the one file that also carries the
-//    account code. If those were assembled twice, one of them would eventually be built from a
+//    NMTS key. If those were assembled twice, one of them would eventually be built from a
 //    check the other had dropped — and the difference would only show up in a recovery.
 //
 // ⛔ THE CAPTURE TIME IS STAMPED BEFORE ANYTHING IS READ. The server keeps it to decide which files

package/dist/recovery-build.d.ts

@@ -0,0 +1,40 @@
+import { type CryptoGlue } from "./crypto.ts";
+import { type RecoveryDocMetaDraft, type RecoveryListDoc } from "./recovery-map.ts";
+import { type SourceItem } from "./recovery-source.ts";
+import type { ManifestEntry } from "./shared/lib/drive/manifest-codec.ts";
+/** Path of the account root. Every file sits at this or below it. */
+export declare const ROOT_PATH = "/";
+/** Folder names, root-down, as the `/a/b` string the format stores. Empty means the root. */
+export declare function pathString(names: readonly string[]): string;
+export interface BuildRecoveryListInput {
+    crypt: CryptoGlue;
+    /** ⛔ BORROWED, NOT KEPT. The caller derived it and the caller wipes it. */
+    dataKey: Uint8Array;
+    accountId: string;
+    /** The account's own sealed file list, opened. */
+    entries: readonly ManifestEntry[];
+    /** Every live stored file, as the server described it. */
+    source: readonly SourceItem[];
+    /** This list's own version. Higher is newer. */
+    seq: number;
+    /** RFC3339, stamped by the caller before the walk began. */
+    generatedAt: string;
+    meta: RecoveryDocMetaDraft;
+}
+export interface BuiltRecoveryList {
+    /** The sealed list — base64url of one NCF-3 envelope. */
+    sealed: string;
+    /** The document that was sealed, so a caller can read what it says without opening anything. */
+    doc: RecoveryListDoc;
+    fileCount: number;
+    totalBytes: number;
+    /**
+     * Live files the sealed file list names that the dump did not return.
+     *
+     * ⛔ NOT A REFUSAL — a short list beats none, and the ordinary cause is a file whose upload never
+     *    committed. But a caller must not report the account as covered while this is not empty.
+     */
+    missingFromSource: readonly string[];
+}
+/** Build and seal the account's recovery list. Throws on any discrepancy; there is no partial list. */
+export declare function buildRecoveryList(input: BuildRecoveryListInput): BuiltRecoveryList;

package/dist/recovery-map-file.d.ts

@@ -0,0 +1,53 @@
+import { type ArtifactAbout } from "./artifact-about.ts";
+/** Wrapper format identifier, checked on read before anything is attempted. */
+export declare const MAP_FILE_FORMAT = "nmts-recovery-map";
+/**
+ * Wrapper version — the SHELL's version, independent of the NRM version inside.
+ *
+ * ⛔ NOT RAISED FOR ANYTHING THIS TOOL ADDS. `MAX_WRAPPER_VERSION` in the standalone program is a
+ *    CEILING: a shell numbered higher than a build knows is refused outright, unread. So a bump is
+ *    a wall in front of every reader already in somebody's hands, never a courtesy.
+ */
+export declare const MAP_FILE_VERSION = 2;
+/** Filename extension. Deliberately not the file-list copy's: the two must not be confusable. */
+export declare const MAP_FILE_EXTENSION = "nmtsmap";
+/** The version to stamp for a document declaring `nrm`. */
+export declare function minimumToolVersion(nrm: number): string;
+/** The on-disk document. */
+export interface RecoveryMapFile {
+    format: typeof MAP_FILE_FORMAT;
+    version: typeof MAP_FILE_VERSION;
+    /** NRM version of the sealed document. Read it before parsing what is inside. */
+    nrm: number;
+    /** Which list this is. Higher wins during a recovery. Version-independent. */
+    seq: number;
+    /** RFC3339 capture time, copied from inside the sealed document. */
+    generated_at: string;
+    /** Public account id, so a person holding several files knows which is which. */
+    account_id: string;
+    /** The sealed list: base64url of one NCF-3 envelope under `nmts/v3/recovery-map`. */
+    sealed: string;
+    min_tool: string;
+    note: string[];
+    about: ArtifactAbout;
+}
+export interface BuildMapFileInput {
+    accountId: string;
+    seq: number;
+    generatedAt: string;
+    /**
+     * NRM version of the document actually sealed.
+     *
+     * ⛔ NOT A CONSTANT. From NRM-3 on the number a document declares depends on what is IN it, so a
+     *    wrapper stating the newest version this build knows would mislabel every ordinary file —
+     *    and a recovery program refuses a document claiming a version it does not know without
+     *    reading a byte of it.
+     */
+    nrm: number;
+    sealed: string;
+}
+/** Build the on-disk document and the filename to offer it under. */
+export declare function buildRecoveryMapFile(input: BuildMapFileInput): {
+    filename: string;
+    content: string;
+};