@needmoretruth/nmts-cli 0.17.2 → 0.34.1

package/dist/registration.d.ts

@@ -0,0 +1,30 @@
+/** What `POST /v1/accounts` is told about a new account. Both values are public or one-way. */
+export interface RegistrationProof {
+    /** Base64url of the 16 bytes the server will know this account by. */
+    accountId: string;
+    /** Base64url of the 32 bytes the server stores a verifier of. Sent once; never stored here. */
+    authSecret: string;
+}
+/**
+ * A brand-new NMTS key, from the engine.
+ *
+ * ⛔ THE RETURNED STRING IS THE ONLY COPY THAT WILL EVER EXIST. The server keeps a verifier of a
+ *    value derived from it and nothing else, so a caller that loses this has destroyed an account
+ *    and nobody — not the holder, not NMTS — can bring it back. Every caller of this owes the
+ *    person a way to keep it before anything else happens.
+ *
+ * ⛔ AND THE RANDOMNESS IS THE ENGINE'S, NEVER NODE'S — the reason `generate_dek` gives, with more
+ *    at stake. These twenty bytes are the seed every key in an account descends from, so a second
+ *    source of them would be a source the conformance vectors say nothing about, in the one place
+ *    where a weak draw loses an entire account rather than one file. `crypto.ts` declares the
+ *    engine call; this is the only thing in the program that makes it.
+ */
+export declare function newAccountCode(): Promise<string>;
+/**
+ * The pair the server is told about a code, derived here and nowhere else.
+ *
+ * ⚠ It re-parses the code rather than taking bytes: the parser checks the trailing check symbol,
+ *   so a code that arrived through anything but `newAccountCode` is refused before it is used to
+ *   claim an account id.
+ */
+export declare function registrationProofOf(code: string): Promise<RegistrationProof>;

package/dist/registration.js

@@ -8,7 +8,7 @@
 //    for that would have made a promise false everywhere it is read; a separate module keeps the
 //    exception in one file, next to the reason for it.
 //
-// ⛔ `authSecret` IS NOT THE ACCOUNT CODE AND CANNOT BE TURNED BACK INTO ONE. It is 32 bytes out
+// ⛔ `authSecret` IS NOT THE NMTS KEY AND CANNOT BE TURNED BACK INTO ONE. It is 32 bytes out
 //    of a one-way derivation (NCF-3 §1.2), it opens no file, and the same value goes over the
 //    wire on every sign-in the browser makes. What it can do is prove ownership, so it is built
 //    here, sent once, and never written down, printed or returned to a caller that did not ask.
@@ -20,7 +20,7 @@
 import { DERIVED, loadCrypto } from "./crypto.js";
 import { NmtsError } from "./errors.js";
 /**
- * A brand-new account code, from the engine.
+ * A brand-new NMTS key, from the engine.
  *
  * ⛔ THE RETURNED STRING IS THE ONLY COPY THAT WILL EVER EXIST. The server keeps a verifier of a
  *    value derived from it and nothing else, so a caller that loses this has destroyed an account
@@ -39,7 +39,7 @@ export async function newAccountCode() {
     if (typeof code !== "string" || code.length === 0) {
         // ⛔ Refused rather than passed on. An empty code would be registered as a real account, and
         //    the failure would surface much later as an account nobody can open.
-        throw new NmtsError("The NMTS crypto engine did not produce an account code.", {
+        throw new NmtsError("The NMTS crypto engine did not produce an NMTS key.", {
             exitCode: 1,
             nextStep: "Nothing was created. Reinstall the package and try again.",
         });
@@ -61,8 +61,8 @@ export async function registrationProofOf(code) {
     }
     catch {
         // ⛔ The engine's own message is not repeated: it can contain the input, and the input is the
-        //    account code.
-        throw new NmtsError("That is not a valid NMTS account code.", {
+        //    NMTS key.
+        throw new NmtsError("That is not a valid NMTS key.", {
             exitCode: 2,
             nextStep: "The last character is a check symbol, and it does not match the rest.",
         });

package/dist/risk.d.ts

@@ -0,0 +1,380 @@
+import type { ParsedArgs } from "./args.ts";
+import type { ConsentKey } from "./consent.ts";
+export type Tier = "none" | "low" | "medium" | "high" | "ultra-high";
+export interface Act {
+    tier: Tier;
+    /** What the gate asks about, in the second person. Absent for `none`. */
+    what?: string;
+    /** The unlock this act sits behind. Only high acts have one. */
+    lock?: ConsentKey;
+    /**
+     * The command prints its own review and takes its own yes (`--yes`, a typed sentence, a version
+     * string). The gate then decides only whether a yes is NEEDED, and the command asks.
+     */
+    asksItself?: true;
+    /**
+     * The unlock is itself the standing consent, so a run under it is not asked again: wallet acts
+     * under the `wallet` grant (scope, expiry, ceiling), and the two ways of keeping the code outside
+     * the sealed file, where unlocking IS the decision the command carries out.
+     */
+    standing?: true;
+}
+export declare const ACTS: {
+    readonly login: {
+        readonly tier: "none";
+    };
+    readonly logout: {
+        readonly tier: "none";
+    };
+    readonly whoami: {
+        readonly tier: "none";
+    };
+    readonly ls: {
+        readonly tier: "none";
+    };
+    readonly usage: {
+        readonly tier: "none";
+    };
+    readonly balance: {
+        readonly tier: "none";
+    };
+    readonly credits: {
+        readonly tier: "none";
+    };
+    readonly trial: {
+        readonly tier: "none";
+    };
+    readonly expiring: {
+        readonly tier: "none";
+    };
+    readonly losses: {
+        readonly tier: "none";
+    };
+    readonly "public-code": {
+        readonly tier: "none";
+    };
+    readonly wallet: {
+        readonly tier: "none";
+    };
+    readonly get: {
+        readonly tier: "none";
+    };
+    readonly pull: {
+        readonly tier: "none";
+    };
+    readonly receive: {
+        readonly tier: "none";
+    };
+    readonly shares: {
+        readonly tier: "none";
+    };
+    readonly listfile: {
+        readonly tier: "none";
+    };
+    readonly "recovery-list": {
+        readonly tier: "none";
+    };
+    readonly recovery: {
+        readonly tier: "none";
+    };
+    readonly mkdir: {
+        readonly tier: "none";
+    };
+    readonly mv: {
+        readonly tier: "none";
+    };
+    readonly rename: {
+        readonly tier: "none";
+    };
+    readonly star: {
+        readonly tier: "none";
+    };
+    readonly unstar: {
+        readonly tier: "none";
+    };
+    readonly pin: {
+        readonly tier: "none";
+    };
+    readonly unpin: {
+        readonly tier: "none";
+    };
+    readonly label: {
+        readonly tier: "none";
+    };
+    readonly unlabel: {
+        readonly tier: "none";
+    };
+    readonly devices: {
+        readonly tier: "none";
+    };
+    readonly key: {
+        readonly tier: "none";
+    };
+    readonly env: {
+        readonly tier: "none";
+    };
+    readonly mode: {
+        readonly tier: "none";
+    };
+    readonly unlock: {
+        readonly tier: "none";
+    };
+    readonly lock: {
+        readonly tier: "none";
+    };
+    readonly consent: {
+        readonly tier: "none";
+    };
+    readonly "on-collision": {
+        readonly tier: "none";
+    };
+    readonly padding: {
+        readonly tier: "none";
+    };
+    readonly deposit: {
+        readonly tier: "none";
+    };
+    readonly notices: {
+        readonly tier: "none";
+    };
+    readonly terms: {
+        readonly tier: "none";
+    };
+    readonly privacy: {
+        readonly tier: "none";
+    };
+    readonly verify: {
+        readonly tier: "none";
+    };
+    readonly support: {
+        readonly tier: "none";
+    };
+    readonly mcp: {
+        readonly tier: "none";
+    };
+    readonly "accept-terms": {
+        readonly tier: "none";
+    };
+    readonly rm: {
+        readonly tier: "low";
+        readonly what: "Move these to the trash, restorable for 30 days.";
+    };
+    readonly restore: {
+        readonly tier: "low";
+        readonly what: "Bring these back out of the trash.";
+    };
+    readonly unshare: {
+        readonly tier: "low";
+        readonly what: "Withdraw this share. Whoever had it cannot download it again.";
+    };
+    readonly tip: {
+        readonly tier: "none";
+    };
+    readonly "tip.set": {
+        readonly tier: "none";
+    };
+    readonly "on-collision.set": {
+        readonly tier: "low";
+        readonly what: "Change what an upload does when its name is already taken.";
+    };
+    readonly "padding.set": {
+        readonly tier: "low";
+        readonly what: "Change how file sizes are hidden for the next uploads.";
+    };
+    readonly "deposit.set": {
+        readonly tier: "low";
+        readonly what: "Change how many credits the next uploads set aside as a deposit.";
+    };
+    readonly update: {
+        readonly tier: "low";
+        readonly what: "Replace this program with the newest published release.";
+    };
+    readonly "trial.apply": {
+        readonly tier: "low";
+        readonly what: "Ask for this week's free credits.";
+    };
+    readonly "support.send": {
+        readonly tier: "low";
+        readonly what: "Send this message to the developer of NMTS.";
+        readonly asksItself: true;
+    };
+    readonly s3: {
+        readonly tier: "medium";
+        readonly what: "Serve the drive to S3 programs on this machine. Uploads through it spend credits.";
+    };
+    readonly put: {
+        readonly tier: "medium";
+        readonly what: "Upload this file and spend credits on its storage. Credits are not refundable.";
+    };
+    readonly push: {
+        readonly tier: "medium";
+        readonly what: "Upload this directory and spend credits on its storage. Credits are not refundable.";
+    };
+    readonly sweep: {
+        readonly tier: "medium";
+        readonly what: "Drop trash entries whose 30 days have run out.";
+        readonly asksItself: true;
+    };
+    readonly "key.list": {
+        readonly tier: "none";
+    };
+    readonly "key.new": {
+        readonly tier: "medium";
+        readonly what: "Make a new API key for this machine.";
+    };
+    readonly "key.revoke": {
+        readonly tier: "medium";
+        readonly what: "Revoke an API key. Whatever used it stops working.";
+    };
+    readonly "public-code.publish": {
+        readonly tier: "medium";
+        readonly what: "Publish this account's public code. Publishing cannot be undone.";
+    };
+    readonly "losses.dismiss": {
+        readonly tier: "medium";
+        readonly what: "Put this loss notice down. It will not be shown again.";
+    };
+    readonly "credits.transfer": {
+        readonly tier: "medium";
+        readonly what: "Move credits to another account of your own.";
+    };
+    readonly rebuild: {
+        readonly tier: "medium";
+        readonly what: "Build a file list from the server's rows and write it as this account's list.";
+    };
+    readonly share: {
+        readonly tier: "high";
+        readonly lock: "share";
+        readonly what: "Give another account this file.";
+        readonly asksItself: true;
+    };
+    readonly "login.plain": {
+        readonly tier: "high";
+        readonly lock: "unsafe-code-storage";
+        readonly what: "Store the NMTS key in the clear.";
+        readonly standing: true;
+    };
+    readonly "login.env": {
+        readonly tier: "high";
+        readonly lock: "plain-env";
+        readonly what: "Print the NMTS key for an environment variable.";
+        readonly standing: true;
+    };
+    readonly extend: {
+        readonly tier: "high";
+        readonly lock: "wallet";
+        readonly what: "Sign a transaction that spends WAL from the wallet.";
+        readonly standing: true;
+    };
+    readonly "put.wallet": {
+        readonly tier: "high";
+        readonly lock: "wallet";
+        readonly what: "Sign a transaction that spends WAL and SUI from the wallet.";
+        readonly standing: true;
+    };
+    readonly "push.wallet": {
+        readonly tier: "high";
+        readonly lock: "wallet";
+        readonly what: "Sign transactions that spend WAL and SUI from the wallet.";
+        readonly standing: true;
+    };
+    readonly "wallet.send": {
+        readonly tier: "high";
+        readonly lock: "wallet";
+        readonly what: "Send coins out of the wallet.";
+        readonly asksItself: true;
+    };
+    readonly "wallet.swap": {
+        readonly tier: "high";
+        readonly lock: "wallet";
+        readonly what: "Swap one coin for the other on a public venue.";
+        readonly asksItself: true;
+    };
+    readonly "devices.sign-out": {
+        readonly tier: "high";
+        readonly lock: "sign-out";
+        readonly what: "Sign a device out of this account.";
+        readonly asksItself: true;
+    };
+    readonly rollback: {
+        readonly tier: "high";
+        readonly lock: "rollback";
+        readonly what: "Put the previous file list back in place of the current one.";
+        readonly asksItself: true;
+    };
+    readonly "whoami.reveal": {
+        readonly tier: "high";
+        readonly lock: "reveal";
+        readonly what: "Print the NMTS key on this screen.";
+    };
+    readonly kit: {
+        readonly tier: "high";
+        readonly lock: "kit";
+        readonly what: "Write the NMTS key into a recovery kit file on this disk.";
+    };
+    readonly create: {
+        readonly tier: "high";
+        readonly what: "Create a new account under the Terms in force.";
+        readonly asksItself: true;
+    };
+    readonly "accept-terms.accept": {
+        readonly tier: "high";
+        readonly what: "Accept a new version of the Terms for this account.";
+        readonly asksItself: true;
+    };
+    readonly "delete-account": {
+        readonly tier: "ultra-high";
+        readonly what: "Erase this account's server record, permanently.";
+        readonly asksItself: true;
+    };
+    readonly erase: {
+        readonly tier: "ultra-high";
+        readonly what: "Erase files for good: the server's record and this account's key to them.";
+        readonly asksItself: true;
+    };
+    readonly "erase.release": {
+        readonly tier: "ultra-high";
+        readonly lock: "release-storage";
+        readonly what: "Erase files for good AND destroy the storage bought with credits under them.";
+        readonly asksItself: true;
+    };
+    readonly "wallet.donate": {
+        readonly tier: "high";
+        readonly lock: "donate";
+        readonly what: "Send a gift to the developer from the wallet.";
+        readonly asksItself: true;
+    };
+    readonly "wallet.hall": {
+        readonly tier: "none";
+    };
+    readonly "wallet.hall.set": {
+        readonly tier: "medium";
+        readonly what: "Publish this name beside your wallet's address in the gift hall of fame.";
+    };
+    readonly "wallet.storage.reshape": {
+        readonly tier: "high";
+        readonly lock: "wallet";
+        readonly what: "Cut or join a storage resource the wallet holds — a signed transaction.";
+        readonly asksItself: true;
+    };
+    readonly "wallet.storage.give": {
+        readonly tier: "high";
+        readonly lock: "wallet";
+        readonly what: "Hand a storage resource to another address — signed, and not undoable.";
+        readonly asksItself: true;
+    };
+};
+export type ActId = keyof typeof ACTS;
+export declare const ACT_IDS: ActId[];
+/**
+ * Which act this command line performs. `null` only for a command the entry point does not know,
+ * which it refuses on its own.
+ */
+export declare function actOf(args: ParsedArgs): ActId | null;
+/**
+ * The hook `main.ts` calls once per run: find the act, pass it through the gate, and when the
+ * gate itself has taken the yes, hand the command a `--yes` so it does not ask twice.
+ * ⚠ The gate is loaded only when there is an act: this file is on every run's path
+ *    (`check:cli-startup`), and the gate reaches the consent and prompt modules.
+ */
+export declare function gateArgs(args: ParsedArgs): Promise<void>;

package/dist/risk.js

@@ -0,0 +1,206 @@
+// Every act this tool performs, and the risk tier it carries — the one table the gate reads.
+//
+// ⛔ WHY ONE TABLE (owner, 2026-09-06). Before it, each command decided for itself whether to ask,
+//    whether a mode may run it and whether a person had to be present, and no two decided the same
+//    way. Now a command names its ACT and the tier does the rest: `gate.ts` refuses, asks or waves
+//    through by tier and mode, the same way every time, and the instructions can describe the rule
+//    in one table instead of once per command.
+//
+// ⛔ AN ACT IS FINER THAN A COMMAND. `devices` reads; `devices --sign-out` ends a session. The tier
+//    belongs to what is DONE, so `actOf` looks at the flags and operands, not only the command word.
+//
+// ⛔ EVERY COMMAND THE ENTRY POINT KNOWS HAS AN ACT, and a test holds the two lists together: a
+//    command that reaches `main.ts` without a row here fails the build, because a command with no
+//    tier is a command nobody decided about.
+//
+// The tiers, and what a mode does with each (the full table is AGENTS.md and the spec):
+//   none        reads and reversible tidying — runs everywhere.
+//   low         reversible, but a change a person should know about — auto runs it, default asks.
+//   medium      hard to undo or costs money, within a ceiling — auto is the agent's own call,
+//               default asks.
+//   high        irreversible, unbounded money, or something reaching a third party — LOCKED until
+//               a person unlocks it, and asked about on every run in every mode but skip.
+//   ultra-high  permanent destruction — a person at the terminal types a sentence; an auto mode
+//               never; skip-permissions with a written --reason.
+export const ACTS = {
+    // ── none: reads and reversible tidying ──
+    login: { tier: "none" },
+    logout: { tier: "none" },
+    whoami: { tier: "none" },
+    ls: { tier: "none" },
+    usage: { tier: "none" },
+    balance: { tier: "none" },
+    // The bare word does nothing but name its one verb; the verb itself is `credits.transfer` below.
+    credits: { tier: "none" },
+    trial: { tier: "none" },
+    expiring: { tier: "none" },
+    losses: { tier: "none" },
+    "public-code": { tier: "none" },
+    wallet: { tier: "none" },
+    get: { tier: "none" },
+    pull: { tier: "none" },
+    receive: { tier: "none" },
+    shares: { tier: "none" },
+    listfile: { tier: "none" },
+    "recovery-list": { tier: "none" },
+    recovery: { tier: "none" },
+    mkdir: { tier: "none" },
+    mv: { tier: "none" },
+    rename: { tier: "none" },
+    star: { tier: "none" },
+    unstar: { tier: "none" },
+    pin: { tier: "none" },
+    unpin: { tier: "none" },
+    label: { tier: "none" },
+    unlabel: { tier: "none" },
+    devices: { tier: "none" },
+    key: { tier: "none" },
+    env: { tier: "none" },
+    mode: { tier: "none" },
+    unlock: { tier: "none" },
+    lock: { tier: "none" },
+    consent: { tier: "none" },
+    "on-collision": { tier: "none" },
+    padding: { tier: "none" },
+    deposit: { tier: "none" },
+    notices: { tier: "none" },
+    terms: { tier: "none" },
+    privacy: { tier: "none" },
+    verify: { tier: "none" },
+    support: { tier: "none" },
+    mcp: { tier: "none" },
+    "accept-terms": { tier: "none" },
+    // ── low ──
+    rm: { tier: "low", what: "Move these to the trash, restorable for 30 days." },
+    restore: { tier: "low", what: "Bring these back out of the trash." },
+    unshare: { tier: "low", what: "Withdraw this share. Whoever had it cannot download it again." },
+    tip: { tier: "none" },
+    "tip.set": { tier: "none" },
+    "on-collision.set": { tier: "low", what: "Change what an upload does when its name is already taken." },
+    "padding.set": { tier: "low", what: "Change how file sizes are hidden for the next uploads." },
+    "deposit.set": { tier: "low", what: "Change how many credits the next uploads set aside as a deposit." },
+    update: { tier: "low", what: "Replace this program with the newest published release." },
+    "trial.apply": { tier: "low", what: "Ask for this week's free credits." },
+    "support.send": { tier: "low", what: "Send this message to the developer of NMTS.", asksItself: true },
+    s3: { tier: "medium", what: "Serve the drive to S3 programs on this machine. Uploads through it spend credits." },
+    // ── medium ──
+    put: { tier: "medium", what: "Upload this file and spend credits on its storage. Credits are not refundable." },
+    push: { tier: "medium", what: "Upload this directory and spend credits on its storage. Credits are not refundable." },
+    sweep: { tier: "medium", what: "Drop trash entries whose 30 days have run out.", asksItself: true },
+    "key.list": { tier: "none" },
+    "key.new": { tier: "medium", what: "Make a new API key for this machine." },
+    "key.revoke": { tier: "medium", what: "Revoke an API key. Whatever used it stops working." },
+    "public-code.publish": { tier: "medium", what: "Publish this account's public code. Publishing cannot be undone." },
+    "losses.dismiss": { tier: "medium", what: "Put this loss notice down. It will not be shown again." },
+    // ⛔ MEDIUM AND NOT HIGH. It moves value, so it is not `low`; but it moves it INSIDE one person's
+    //    own family of accounts — nothing reaches a third party, nothing is spent, and the same
+    //    command in the other direction puts it back. `high` is where a stranger or the chain is.
+    "credits.transfer": { tier: "medium", what: "Move credits to another account of your own." },
+    rebuild: { tier: "medium", what: "Build a file list from the server's rows and write it as this account's list." },
+    // ── high: locked until a person unlocks, asked on every run ──
+    share: { tier: "high", lock: "share", what: "Give another account this file.", asksItself: true },
+    "login.plain": { tier: "high", lock: "unsafe-code-storage", what: "Store the NMTS key in the clear.", standing: true },
+    "login.env": { tier: "high", lock: "plain-env", what: "Print the NMTS key for an environment variable.", standing: true },
+    extend: { tier: "high", lock: "wallet", what: "Sign a transaction that spends WAL from the wallet.", standing: true },
+    "put.wallet": { tier: "high", lock: "wallet", what: "Sign a transaction that spends WAL and SUI from the wallet.", standing: true },
+    "push.wallet": { tier: "high", lock: "wallet", what: "Sign transactions that spend WAL and SUI from the wallet.", standing: true },
+    "wallet.send": { tier: "high", lock: "wallet", what: "Send coins out of the wallet.", asksItself: true },
+    "wallet.swap": { tier: "high", lock: "wallet", what: "Swap one coin for the other on a public venue.", asksItself: true },
+    "devices.sign-out": { tier: "high", lock: "sign-out", what: "Sign a device out of this account.", asksItself: true },
+    rollback: { tier: "high", lock: "rollback", what: "Put the previous file list back in place of the current one.", asksItself: true },
+    "whoami.reveal": { tier: "high", lock: "reveal", what: "Print the NMTS key on this screen." },
+    kit: { tier: "high", lock: "kit", what: "Write the NMTS key into a recovery kit file on this disk." },
+    create: { tier: "high", what: "Create a new account under the Terms in force.", asksItself: true },
+    "accept-terms.accept": { tier: "high", what: "Accept a new version of the Terms for this account.", asksItself: true },
+    // ── ultra-high: permanent destruction ──
+    "delete-account": { tier: "ultra-high", what: "Erase this account's server record, permanently.", asksItself: true },
+    erase: { tier: "ultra-high", what: "Erase files for good: the server's record and this account's key to them.", asksItself: true },
+    "erase.release": {
+        tier: "ultra-high",
+        lock: "release-storage",
+        what: "Erase files for good AND destroy the storage bought with credits under them.",
+        asksItself: true,
+    },
+    "wallet.donate": { tier: "high", lock: "donate", what: "Send a gift to the developer from the wallet.", asksItself: true },
+    // ⛔ READING THE HALL IS `none` AND LISTING A NAME IS `medium`. The read signs nothing and asks
+    //    nobody's wallet a question; setting a name PUBLISHES a name beside an address on a public
+    //    page, which is undone by one more run of the same command but cannot be unseen.
+    "wallet.hall": { tier: "none" },
+    "wallet.hall.set": { tier: "medium", what: "Publish this name beside your wallet's address in the gift hall of fame." },
+    "wallet.storage.reshape": { tier: "high", lock: "wallet", what: "Cut or join a storage resource the wallet holds — a signed transaction.", asksItself: true },
+    "wallet.storage.give": { tier: "high", lock: "wallet", what: "Hand a storage resource to another address — signed, and not undoable.", asksItself: true },
+};
+export const ACT_IDS = Object.keys(ACTS);
+/**
+ * Which act this command line performs. `null` only for a command the entry point does not know,
+ * which it refuses on its own.
+ */
+export function actOf(args) {
+    const c = args.command;
+    const sub = args.operands[0] ?? "";
+    switch (c) {
+        case null:
+            return null;
+        case "login":
+            return args.plain ? "login.plain" : args.env ? "login.env" : "login";
+        case "whoami":
+            return args.reveal ? "whoami.reveal" : "whoami";
+        case "devices":
+            return args.signOut !== undefined ? "devices.sign-out" : "devices";
+        case "wallet":
+            if (sub === "storage") {
+                const what = args.operands[1] ?? "";
+                return what === "transfer" ? "wallet.storage.give" : what === "split" || what === "merge" ? "wallet.storage.reshape" : "wallet";
+            }
+            // ⛔ `hall` READS UNTIL A NAME IS NAMED. `--name` and `--remove` both write the listing, so
+            //    both land on the act that publishes; the bare command is a read like `wallet` itself.
+            if (sub === "hall")
+                return args.name !== undefined || args.remove ? "wallet.hall.set" : "wallet.hall";
+            return sub === "send" ? "wallet.send" : sub === "swap" ? "wallet.swap" : sub === "donate" ? "wallet.donate" : "wallet";
+        case "put":
+            return args.pay === "wallet" ? "put.wallet" : "put";
+        case "push":
+            return args.pay === "wallet" ? "push.wallet" : "push";
+        case "key":
+            return sub === "new" ? "key.new" : sub === "revoke" ? "key.revoke" : "key";
+        case "trial":
+            return sub === "apply" ? "trial.apply" : "trial";
+        case "credits":
+            return sub === "transfer" ? "credits.transfer" : "credits";
+        case "losses":
+            return args.dismiss !== undefined ? "losses.dismiss" : "losses";
+        case "public-code":
+            return args.publish ? "public-code.publish" : "public-code";
+        case "support":
+            return sub === "send" || sub === "reply" ? "support.send" : "support";
+        case "on-collision":
+            return sub === "" ? "on-collision" : "on-collision.set";
+        case "padding":
+            return sub === "" ? "padding" : "padding.set";
+        case "deposit":
+            return sub === "" ? "deposit" : "deposit.set";
+        case "erase":
+            return args.releaseStorage ? "erase.release" : "erase";
+        case "tip":
+            return sub === "" ? "tip" : "tip.set";
+        case "accept-terms":
+            return args.status ? "accept-terms" : "accept-terms.accept";
+        default:
+            return ACT_IDS.includes(c) ? c : null;
+    }
+}
+/**
+ * The hook `main.ts` calls once per run: find the act, pass it through the gate, and when the
+ * gate itself has taken the yes, hand the command a `--yes` so it does not ask twice.
+ * ⚠ The gate is loaded only when there is an act: this file is on every run's path
+ *    (`check:cli-startup`), and the gate reaches the consent and prompt modules.
+ */
+export async function gateArgs(args) {
+    const act = actOf(args);
+    if (act === null || args.dryRun)
+        return;
+    const { gate } = await import("./gate.js");
+    const passage = await gate(act, args);
+    if (!passage.ask)
+        args.yes = true;
+}