@defdone/annon 0.1.0-alpha.1 → 0.1.0-alpha.3

package/CHANGELOG.md

@@ -1,5 +1,31 @@
 # @defdone/annon
 
+## 0.1.0-alpha.3
+
+### Patch Changes
+
+- edb0ec2: Bound approval session shutdown and resume polling after accepted approvals. Keep completed review snapshots read only and clarify that the tab should stay open.
+- 5d871b7: Keep accepted browser approvals successful after session shutdown and show completed approvals as read-only collapsible steps.
+- f607080: The CLI is easier to use by hand. `annon` with no arguments in a terminal (or `annon shell`) starts
+  an interactive session that runs the usual commands without the prefix until `exit`. In a terminal
+  the commands print short text in place of JSON: a login line, a numbered catalog table, the buy
+  terms and next step, one or two lines for status and open. `--json`, piped output and agent mode
+  keep the JSON envelope unchanged.
+  
+  `annon buy` takes a catalog row number (`buy 2 --shop demo`) and `--open <file>`, which waits for
+  acceptance and writes the file. `annon status` and `annon open` without an ID use the latest
+  purchase saved for the configured contract and network, and accept an ID prefix of 8 or more hex
+  digits for purchases saved for it. The `next` text of a NEAR or Base buy no
+  longer talks about a deposit.
+
+## 0.1.0-alpha.2
+
+### Patch Changes
+
+- Add `BrowserPurchaseController.reconcile()` so a purchase that 1Click reported as failed can be checked again. Under the purchase lease it keeps the same purchase, deposit and recovery identity, checks NEAR acceptance and reads the existing deposit's 1Click status once. Accepted moves to `accepted`, `SUCCESS` to `accepting` and `REFUNDED` to `refunded`; anything else stays `failed` with the new status saved. If the saved deposit address or memo, the restored purchase's deposit and the saved polling checkpoint disagree, it refuses before any read or write. It never creates, starts or pays for a purchase.
+- Bare `annon init` creates the CLI backup secret at `~/.config/annon/backup-secret`: 32 random bytes as hex, mode 0600 from the first write, published with a hard link so it never appears half-written and never replaces an existing file. Running it again only validates the file. It refuses to create a new secret while saved records or backups exist, never prints the secret, and sends its one-time notice to stderr. `--backup-secret-file`, `ANNON_BACKUP_SECRET_FILE` and `ANNON_BACKUP_SECRET` keep their precedence; the default file is read only when none is set, and a selected source that fails never falls back. Other commands, agent mode and MCP read the default but never create it. Reading the default checks that `~/.config/annon` is a private directory you own, refuses symlinks, FIFOs and other non-regular files without blocking, and never repairs anything. Bare `init` reports an unreadable config as a setup error (exit 2). A pending `status` now uses the default file too. `annon --version` (or `-v`) prints the installed version. The quickstart replaces the manual secret recipe with `annon init` and explains backup and restore.
+- The CLI wallet approval page shows a readable summary of exactly what the wallet signs: a title per action, the pairing code to compare, amounts in USDC or NEAR, receiver, account, expiry and what signing does, with the CLI's terms shown apart and the raw request under Technical details (the NEP-413 nonce as hex). Each click opens at most one wallet window, so Meteor's web popup is no longer blocked: NEP-413 messages are signed without a sign-in, and transactions connect first and then send. After a closed, blocked or declined wallet window the page explains it and allows another try until the request expires. The terminal prints a waiting line with the expiry, the reported wallet failure and a specific final error (`cancelled`, `rejected` or `wallet_error`) instead of `operation_failed`. Once the page has called the wallet's send for a transaction, the request is never attempted again: the CLI records the send start before the wallet is called, the request ends as `transaction_uncertain` with a warning not to pay again, the saved purchase keeps that state without inventing a transaction hash, and it blocks a plain rerun of `annon buy` until it is accepted or `--force` is used. A result the CLI cannot verify after the send start also ends as uncertain, keeping a valid transaction hash when there is one. An uncertain `annon buy` exits 4, and `annon status` reports `submission: "uncertain"` with a warning not to pay again. The NEAR wallet is chosen in a styled, keyboard-accessible list instead of the browser's native menu.
+
 ## 0.1.0-alpha.1
 
 ### Patch Changes

package/CLI.md

@@ -2,9 +2,38 @@
 
 Build with `pnpm build`. The `@defdone/annon` package ships the `annon` bin;
 in this checkout run `node packages/annon/dist/node/main.js` in its place.
-Run `annon --help` for all flags. All commands return JSON; `--json` uses one compact
-JSON line and disables interactive prompts. Success is `{ "ok": true, "result": ... }`;
-errors are `{ "ok": false, "error": { "code": ..., "message": ... } }`.
+Run `annon --help` for all flags and `annon --version` (or `-v`) for the installed version; with
+`--json` the version is `{ "ok": true, "result": { "version": ... } }`. It loads no config, wallet
+or secret and also works in agent mode. With `--json` every command prints one compact JSON line
+and asks nothing. Success is `{ "ok": true, "result": ... }`;
+errors are `{ "ok": false, "error": { "code": ..., "message": ... } }`. Without `--json` the same
+envelope is printed indented whenever standard output is not a terminal, and always in agent mode,
+so scripts and pipes read JSON either way. In a terminal a person gets short text instead: one or
+two lines per command, `catalog` as a numbered table, errors as `Error: message (code)`. Exit codes
+are the same in every mode. Text from shops and hosts is shown with control characters removed.
+
+## Interactive session
+
+`annon` with no arguments in a terminal, or `annon shell`, starts a session. It prints the version,
+network, signed-in account and whether the configured contract is trusted, then reads commands at
+`annon>` until `exit`, `quit` or Ctrl-D. Commands are the ones on this page without the `annon`
+prefix; Tab completes names and flags, `help` lists them. Each line runs the same code as the
+one-shot command, with the same trust prompt, price cap, purchase guard and confirmation, and the
+session keeps no wallet, config or secret between commands.
+
+- `catalog` numbers its rows; `buy 2` buys row 2 of the last listing shown.
+- After a NEAR or Base payment `buy` waits for acceptance, then asks where to save the file.
+- `status` and `open --output <file>` without an ID use the latest purchase `buy` saved for the
+  contract and network of that line, as the one-shot commands do. The session remembers no
+  purchase itself, so a line with another `--contract-id`, `--network`, `--config` or
+  `--state-dir` never picks up a purchase made under a different one.
+- Ctrl-C cancels a prompt (the answer is no), stops a wait for acceptance, or drops a read-only
+  command. During `buy`, `fund`, `sell`, `share`, `stop` or `recover` it asks
+  `A payment may be in progress. Exit anyway? (y/N)`. Leaving removes nothing: the purchase saved
+  before payment is still there, so check it with `annon status` before paying again.
+
+Without a terminal, with any argument such as `--json`, or in agent mode no session starts:
+`annon` prints the help and `annon shell` fails with `invalid_arguments`.
 
 Create a public configuration file and name it with `--config /path/config.json` or
 `ANNON_CONFIG`. The default is `~/.config/annon/config.json`:
@@ -53,10 +82,9 @@ On macOS, with no NEAR file or credential env value, explicitly select both
 service `near-mainnet-alice.near`, account `alice.near:ed25519:PUBLIC_KEY`.
 Other platforms use the credential JSON file or environment. No keychain enumeration occurs.
 
-Sell, buy, open, recover and stop also require a user-held random 32-byte backup secret,
-encoded as 64 lowercase hex characters in `ANNON_BACKUP_SECRET`, or in the file named by
-`--backup-secret-file` / `ANNON_BACKUP_SECRET_FILE`. Create it with a cryptographic random
-generator and keep it outside the repository. It is never derived from a wallet signature.
+Sell, buy, open, recover and stop also require a random 32-byte backup secret. It encrypts the
+local purchase, recovery and sell records and the portable backups. It is never derived from a
+wallet signature or key. See [Backup secret](#backup-secret).
 `verify` and accepted/read-only `status` need neither a wallet nor this secret. A pending Base `status` with saved state and a backup secret may send `unlock` through the configured relayer or NEAR wallet. Status can update encrypted local state and backups: expired/canceled Base payments are marked with `paymentState`, preserving the purchase, attempts and recovery key. It never deletes the purchase record.
 
 State directories are created with mode 0700 and records/outputs with 0600. Keep existing
@@ -64,8 +92,99 @@ state directories private. Purchases and recovery grants are encrypted by the SD
 encrypted backups are under `stateDir/backups`. Public headers and resource URLs are saved
 separately for later downloading. Preserve state after timeouts. Losing local state does not
 lose recovery rights: the same recovery wallet can create a fresh grant on a new device with
-a new backup secret. Keys, signed payment payloads and decrypted file contents are never
-returned in CLI/MCP results. Plaintext is written only to the explicitly named output.
+a new backup secret ([Loss](#backup-secret) explains when `init` creates one). Keys, signed payment
+payloads and decrypted file contents are never returned in CLI/MCP results. Plaintext is written only to the explicitly named output.
+
+### Backup secret
+
+Run `annon init` once, before buying, selling or enabling agent mode. It creates
+`~/.config/annon/backup-secret`: 32 random bytes as 64 lowercase hex characters and a newline,
+mode 0600, in a directory created with mode 0700. The file is written to an exclusive temporary
+file and published with a hard link, so it never appears half-written and an existing file is
+never replaced. Running `init` again only validates the file and reports `"created": false`. An
+unsafe default is refused and never repaired: a symlink, FIFO or other non-regular file, a file not
+owned by you or with group or other permission bits, malformed content, or an `~/.config/annon`
+that is a symlink, is not owned by you, or is writable by group or others. An existing 0755
+directory is fine. Every command that reads the default applies the same checks.
+
+The location is fixed. `XDG_CONFIG_HOME`, `XDG_DATA_HOME`, `XDG_STATE_HOME`, `--config`,
+`ANNON_CONFIG` and `--state-dir` do not move it. For another private location, name an existing file with the explicit inputs below.
+
+Sources, in order, as before this file existed:
+
+1. `--backup-secret-file` (or, when the flag is absent, `ANNON_BACKUP_SECRET_FILE`), a file with the
+   64 hex characters.
+2. `ANNON_BACKUP_SECRET`, the hex value itself. Prefer a file: environment values are inherited by
+   child processes.
+3. The default file, only when neither is set.
+
+An empty value counts as unset, as before: an empty `--backup-secret-file` selects no file even when
+`ANNON_BACKUP_SECRET_FILE` is set, and moves on to `ANNON_BACKUP_SECRET`. Hex must be lowercase in
+every source; an optional `0x` prefix and surrounding whitespace are accepted. A selected source that is missing,
+unreadable or malformed fails with `backup_secret_required` (exit 2); there is no fallback to a
+later source, the default file or a new secret. `annon init` with an explicit source only validates
+it and never writes, creates or changes that file. Commands other than `init` read the secret but
+never create it, and agent mode and MCP never create it. Bare `init` accepts only `--json`,
+`--config`, `--state-dir` and `--backup-secret-file`; signer options need `--agent`.
+
+Output: stdout carries the usual single JSON result, for example
+`{"ok":true,"result":{"configured":true,"backupSecret":{"source":"default-file","path":"/home/me/.config/annon/backup-secret","created":true}}}`.
+`source` is `default-file`, `flag-file`, `env-file` or `env`; `path` is shown for files only. The
+one-time creation notice goes to stderr, also with `--json`. The secret itself is never printed, in
+results, errors or notices.
+
+**Back it up.** The secret is not part of the encrypted backups in `stateDir/backups`; copy the file
+itself, separately, to private encrypted storage. Never `cat` it or paste it into a terminal. This
+copies without displaying it and refuses an existing destination:
+
+```sh
+node --input-type=module -e '
+  import { constants } from "node:fs";
+  import { copyFile } from "node:fs/promises";
+  await copyFile(process.argv[1], process.argv[2], constants.COPYFILE_EXCL);
+' "$HOME/.config/annon/backup-secret" /mounted-private-encrypted-backup/annon-backup-secret
+```
+
+The copy keeps mode 0600 when the destination supports POSIX permissions; check it. A secret manager
+that imports files is also fine.
+
+**Restore.** On a new machine, put the saved file in a private directory (directory mode 0700, file
+mode 0600), copy the encrypted record backups separately, and select the file. Do not run `init`
+first:
+
+```sh
+export ANNON_BACKUP_SECRET_FILE=/absolute/private/restored-annon-backup-secret
+annon open /absolute/private/purchase-backup.json --url https://host.example/file --output restored-file
+```
+
+Opening one known backup proves the restore. To restore to the default location instead, create
+`~/.config/annon` with mode 0700 and copy in the other direction, still refusing an existing file:
+
+```sh
+mkdir -p -m 700 "$HOME/.config/annon"
+node --input-type=module -e '
+  import { constants } from "node:fs";
+  import { copyFile } from "node:fs/promises";
+  await copyFile(process.argv[1], process.argv[2], constants.COPYFILE_EXCL);
+' /mounted-private-encrypted-backup/annon-backup-secret "$HOME/.config/annon/backup-secret"
+```
+
+**Loss.** If the secret disappears, commands fail with `backup_secret_required` and a pending
+`status` stays pending; nothing recreates it. Restore the same bytes. Bare `init` creates a new
+secret only when both checked state locations are empty: the effective state directory and the
+default `~/.local/share/annon`, each in `records` and `backups`. If every copy is lost and you want
+to recover with a new secret, first move the whole old state, including `~/.local/share/annon`, to
+a separate private archive and keep it. Then use an empty state directory, run `init`, and run
+`recover` with the same recovery wallet. That creates a fresh grant and new records; it cannot
+decrypt the archived records or resume pending sell jobs. An operator can instead provision a
+separate secret file and select it with `ANNON_BACKUP_SECRET_FILE`. Use one secret per state
+directory.
+
+**Agents.** `init --agent` does not create or reference a backup secret. Run bare `init` before it,
+or give the agent an operator-managed file with an absolute `ANNON_BACKUP_SECRET_FILE` in the
+launcher. A launcher that sets `ANNON_BACKUP_SECRET_FILE` must point it at a file that exists; a
+missing file fails without falling back to the default. Once agent mode is active, `init` is
+refused, so provision or restore the secret outside the running agent.
 
 ## Commands
 
@@ -78,6 +197,10 @@ annon sell report.pdf --price 0.2 --split near:alice.near:10000 --wallet near --
 annon sell report.pdf --resume 0xFILE_ID --wallet near --output resumed.pay2
 annon sell report.pdf --price 0.2 --split evm:0x1111111111111111111111111111111111111111:10000 --wallet evm --base
 annon buy https://host.example/report --route near --wallet near
+annon buy https://host.example/report --route near --open report.pdf
+annon buy 2 --shop demo --open report.pdf
+annon status
+annon open 0x1a2b3c4d --output report.pdf
 annon buy offer.json --url https://host.example/report --route base --wallet evm --max-price 0.2
 annon buy https://host.example/report --route 1click --wallet solana --from-chain solana
 annon status 0xPURCHASE_ID --json
@@ -91,6 +214,29 @@ annon stop 0xFILE_ID --wallet near
 ```
 
 IDs in these commands are placeholders for full `0x` plus 64 lowercase hex digits.
+
+Fewer steps for a person (agent mode refuses all three and keeps requiring full URLs and IDs):
+
+- `buy <row> --shop <id> [--search <q>]` buys that row of the listing `catalog` prints for the same
+  `--shop` and `--search`. The CLI names the row's title and URL, then checks the file and its terms
+  as for a typed URL. A catalog can change between listing and buying, so read the terms before you
+  confirm. An offer file named like a number is written `./2`.
+- `buy --open <file>` waits up to three minutes for acceptance and then writes the opened file. It
+  refuses an existing `<file>` before paying. The result is the buy result with `state: "opened"`
+  and `opened: { output, bytes }`. If the purchase is not accepted in time it adds
+  `settlement: "pending"` and exits 4; if a status check or the open fails after payment, the result
+  still names the purchase and adds `statusError` or `openError`, and the exit code is that
+  error's. A purchase that is still `state: "uncertain"` wins over the follow-up error: the result
+  carries `statusError`, and the exit code stays 4. Nothing is paid twice: finish with `status` and
+  `open`. A 1Click buy returns its deposit
+  instructions without waiting. In a terminal, `buy` waits for acceptance even without `--open`.
+- `status` and `open --output <file>` without an ID use the latest purchase `buy` saved for the
+  configured contract and network. An ID may be shortened to a prefix of 8 or more hex digits, with
+  or without `0x`. A prefix only names purchases that `buy` or `recover` saved for the configured
+  contract and network; one that matches none of them, or more than one, is refused with
+  `purchase_required`. A purchase saved by an older version, or for another contract or network,
+  needs its full ID. For `open`, a name of 8 to 63 hex digits is always read as a prefix: write
+  such a file as `./name`.
 `sell` creates a PAY2 file; arrange hosting separately. `buy` accepts the HTTPS resource URL
 or a named file containing decoded x402 `PAYMENT-REQUIRED` JSON. An offer file requires `--url` with the independently selected resource URL; it must match the offer. It checks the public header
 and registered terms before the SDK authorizes payment. Every buy requires `--max-price`, `ANNON_MAX_PRICE` or config `maxPrice` (decimal USDC); the offer never supplies the cap. A configured cap also bounds an explicit flag. The default route is direct NEAR for
@@ -161,9 +307,23 @@ blindly retried. Raw upstream errors are intentionally suppressed to avoid leaki
 | --- | --- |
 | 0 | Command completed; buy may still require a deposit or settlement |
 | 1 | Operation failed; inspect final status and retained encrypted state before retrying |
-| 2 | Invalid arguments, configuration, wallet source or missing local input |
-| 3 | First-use contract trust required or declined |
-| 4 | `status` reports pending; acceptance has not been observed (not proof of payment failure) |
+| 2 | Invalid arguments, configuration, wallet source or missing local input; `purchase_open` when a saved purchase of the file, including an uncertain NEAR send, still blocks a new one |
+| 3 | First-use contract trust required or declined; browser approval cancelled (`cancelled`), expired (`cancelled`, or `rejected` or `wallet_error` after the last wallet failure the page reported) or declined by the wallet |
+| 4 | Not settled, and not proof of failure: `status` reports pending; `buy` returned `state: "uncertain"` (its payment may be on chain; the JSON result is unchanged and names the saved purchase); or `transaction_uncertain`: a transaction may have been sent and is not confirmed |
+
+In browser approval, once the CLI has acknowledged the page's send start, the request can only end
+as a verified transaction or as `transaction_uncertain`: a wallet failure, a cancel, the expiry, or a
+result the CLI cannot verify (an RPC rejection, malformed evidence) never counts as "not sent". The
+purchase is saved with that uncertainty, with the transaction hash only when the wallet returned a
+valid one. `annon buy` then exits 4 with `state: "uncertain"`, and `annon status <purchase id>`
+answers `submission: "uncertain"` until the purchase is accepted. Do not pay again.
+
+A plain `annon buy` of the same file is refused with `purchase_open` while that uncertainty is
+saved, also after the purchase expired: a late transfer still moves tokens, and the contract then
+owes a refund that is paid out later rather than returned at once. Neither a pending status, an
+expired purchase nor an empty wallet history proves that nothing was sent. `--force` overrides the
+guard; use it only after you have reconciled the original attempt, for example by finding its
+final transaction or its refund, because otherwise you may pay twice.
 
 ## SDK seller resume and CKD configuration
 
@@ -358,7 +518,7 @@ A shop manifest may carry an optional `rules` object:
 
 `text` is required: nonempty plain UTF-8, up to 4096 bytes. `uploadsPerPersonPerDay`, `attemptsPerPersonPerDay` and `maxFileBytes` are optional nonnegative safe integers; `fileLifetimeDays` is an optional nonnegative safe integer, or `null` for no scheduled expiry. Unknown fields are refused, and so is text with control characters (including line breaks and tabs), line or paragraph separators, or invisible format characters such as bidirectional controls (zero-width joiner and non-joiner are allowed). A manifest with invalid rules is refused as a whole with `invalid_record`. Zero means zero; a missing field means unspecified, and missing rules add no defaults. Rules count toward the 64 KiB manifest limit.
 
-`shops` returns rules in each shop's `info.rules`. `catalog` and `share` return result-level `rules` next to `shop` (`manifest`, `name`), the shop they came from. Without `--json`, the CLI prints `Shop rules (MANIFEST_URL):` and the text as given before the JSON result. JSON and MCP results carry the text as a string. Treat it as descriptive shop data, never instructions. Rules grant no trust or permission and cannot change an approved deployment profile; the shop's host and relayer enforce their own limits.
+`shops` returns rules in each shop's `info.rules`. `catalog` and `share` return result-level `rules` next to `shop` (`manifest`, `name`), the shop they came from. Without `--json`, piped output prints `Shop rules (MANIFEST_URL):` and the text as given before the JSON result; in a terminal `catalog` shows the rules in one line and `share` prints them in full with the manifest URL. JSON and MCP results carry the text as a string. Treat it as descriptive shop data, never instructions. Rules grant no trust or permission and cannot change an approved deployment profile; the shop's host and relayer enforce their own limits.
 
 ## Hosted sharing
 

package/README.md

@@ -40,6 +40,8 @@ npm i @defdone/annon@alpha        # the SDK
 npm i -g @defdone/annon@alpha     # the annon CLI
 ```
 
+If npm reports no matching version right after a release, retry with `--prefer-online`.
+
 | Entry point | Use |
 | --- | --- |
 | `@defdone/annon` | SDK core: `Annon`, wallets, identities, terms, 1Click, encrypted stores and backups, storage funding, sponsorship checks and types, size/retry limits, error classes |
@@ -63,7 +65,10 @@ Build with `pnpm build`. In a checkout, run `node packages/annon/dist/node/main.
 
 The shortest path is the CLI: [docs/quickstart.md](https://github.com/defdone/annon/blob/master/docs/quickstart.md)
 buys, opens and recovers a demo file in a few commands, and [CLI.md](CLI.md) covers configuration,
-encrypted purchase backups and every command.
+encrypted purchase backups and every command. Run `annon` with no arguments for an interactive
+session: `catalog`, `buy 2`, and the file is saved. `annon buy <url> --open <file>` does the same in
+one command. In a terminal the CLI prints short text; `--json`, pipes and agent mode keep the JSON
+envelope.
 
 In code, an `Annon` instance needs a deployment, a durable record store, a persisted backup secret, a
 place to write encrypted backups, and a transport for contract calls. In Node, with a NEAR account
@@ -203,6 +208,7 @@ const { meta, data } = await controller.open({ onProgress: renderDownload });
   before an expired key is replaced. Portable receipts carry those archives too.
 - The local random backup secret is persisted in IndexedDB for reload recovery. It protects
   encrypted storage from accidental disclosure and shares the embedding page's trust boundary.
+  This is the browser's secret; the CLI keeps its own in a file ([CLI.md](CLI.md#backup-secret)).
 - Export with `controller.exportReceipt(portableSecret)`, using a separate random 32-byte
   `newBackupSecret()` that you keep separately. Import with
   `storage.importReceipt(file, portableSecret)`. Import restores the header, resource URL and
@@ -295,6 +301,9 @@ shop-provided data: on each shop's `info` from `listShops`, and as `rules` with
 
 ## CLI browser wallet login
 
+Run `annon init` once first. It creates the CLI backup secret file that encrypts local records
+([CLI.md](CLI.md#backup-secret)); login neither creates nor exports it.
+
 ```sh
 annon login --wallet evm
 annon login --wallet near --network near:testnet
@@ -308,21 +317,44 @@ in the wallet.
 | Wallet | How | Signing supported |
 | --- | --- | --- |
 | EVM | Injected EIP-1193 wallet on Base | `personal_sign` for the SDK's authorization texts, `eth_signTypedData_v4` for the exact EIP-3009/x402 payload |
-| NEAR | Meteor Wallet (extension or web popup; mainnet and testnet) or HOT Wallet (mainnet only) through Wallet Selector, picked on the page; account-only sign-in (no `contractId`, no method list) | NEP-413 and `signAndSendTransaction`, including the required deposit `"1"` on `ft_transfer_call` |
+| NEAR | Meteor Wallet (extension or web popup; mainnet and testnet) or HOT Wallet (mainnet only) through Wallet Selector, picked on the page. NEP-413 messages are signed directly, with the account chosen in the wallet and no sign-in. Transactions take two clicks: an account-only sign-in (no `contractId`, no method list), then the transaction | NEP-413 and `signAndSendTransaction`, including the required deposit `"1"` on `ft_transfer_call` |
 
 Browser and remote EVM split-deployment transactions and browser and remote Solana signing are not
 included; the local-key adapters remain available for those workflows.
 
 **The local page.** The listener binds `127.0.0.1` on an OS-assigned port before opening the browser.
 Match the short pairing code with the terminal, and review the action, amount, recipients, file and
-chain on the page before approving in the wallet.
+chain on the page before approving in the wallet. The page shows a summary built only from the
+request the wallet signs (amounts in USDC or NEAR, receiver, account, expiry), the CLI's payment or
+listing terms apart from it with a warning if their price differs, and the raw request under
+Technical details. While a request waits, the terminal prints its expiry on stderr.
+
+- Each click opens at most one wallet window, inside that click, so the browser's pop-up blocker
+  allows it. If the wallet window closes, is blocked or declines before anything is sent, the page
+  says so and you can try again, with the same or another wallet, until the request expires.
+  Nothing is retried for you.
+- Once the page has called the wallet's send for a transaction, that request is never attempted
+  again, whatever the wallet answers, because it may already have broadcast. The request ends as
+  `transaction_uncertain` and the terminal says: "The wallet may have sent the transaction. Do not
+  pay again. Run annon status <purchase id> to check it." The page records the send start with
+  the CLI before it calls the wallet, so a reloaded page or the request's expiry cannot turn it
+  into a retryable failure, and a result the CLI cannot verify after that point also ends as
+  uncertain. `annon buy` exits 4, `annon status` reports `submission: "uncertain"`, and the saved
+  purchase blocks a plain `annon buy` of the same file (`purchase_open`). `--force` overrides it
+  only after you have reconciled the first attempt (see CLI.md).
+- The page reports only a fixed reason name (`window_closed`, `popup_blocked`, `rejected`,
+  `wallet_error`, `refused`, `send_uncertain`, `send_started` or `cancelled`) to the CLI, which
+  prints its own line for it. Cancel ends the request at once; an expired request fails with the
+  last reported reason, for example `rejected` or `wallet_error`, instead of a generic error. A
+  report never completes a request.
 
 - Host (including port), Origin and an unpredictable RAM-only capability are checked on action and
   result API calls.
 - In open mode, a same-origin POST bootstraps the capability once into the opened page, then the
   bootstrap route closes. With `--no-open`, bootstrap is disabled and the capability exists only in
   the printed URL fragment. It is never passed to the browser launcher in argv.
-- Bundled scripts, a restrictive CSP, no framing, `no-store` and `no-referrer` are enforced. The page
+- Bundled scripts and a stylesheet from the page's own origin (no inline styles, fonts or other
+  resources), a restrictive CSP, no framing, `no-store` and `no-referrer` are enforced. The page
   connects only to itself, the Wallet Selector's NEAR RPC (`free.rpc.fastnear.com` on mainnet,
   `test.rpc.fastnear.com` on testnet, fixed in the page and independent of your configured RPC) and
   HOT's relay `h4n.app`, and frames only `hot-labs.org`.
@@ -405,8 +437,11 @@ Order matters, because agent mode refuses `init`, `login` and per-call trust or
 2. Write the deployment, `maxPrice`, `workDir` and, after reviewing the contract,
    `trustContract: true` (or trust it once with a human command and `--trust-contract`). Do not set
    `agent: true` yourself.
-3. Run one `annon init --agent ...` from the examples above. It saves the signer, the daily budget
-   and `agent: true`.
+3. Run bare `annon init` to create the backup secret, or give the launcher an absolute
+   `ANNON_BACKUP_SECRET_FILE` you manage ([CLI.md](CLI.md#backup-secret)). Agent mode never creates
+   one.
+4. Run one `annon init --agent ...` from the examples above. It saves the signer, the daily budget
+   and `agent: true`. It does not create or reference a backup secret.
 
 - Agents never prompt. Missing trust, price cap or daily budget causes a refusal.
 - `allowedResources` is optional. Without it, any secure resource URL is allowed within the
@@ -447,7 +482,8 @@ Before a human payment the CLI confirms the current price, split recipients and
 and file, token and network. Browser mode shows these exact terms with each signing request for
 approval in the page and the wallet. Local and remote human signing require an explicit terminal
 confirmation. Purchase and recovery secrets still need the independent backup secret described in
-CLI.md; login does not derive one from a signature.
+[CLI.md](CLI.md#backup-secret) and created by `annon init`; login does not derive one from a
+signature.
 
 ## Remote signer, HTTP JSON v1
 
@@ -501,9 +537,10 @@ RPC. A returned transaction hash alone never proves success.
 - Definite mismatches and failed finalized transactions are rejected without saving the hash as
   `nearSubmission` evidence. Only RPC unavailability or a non-final status keeps the outcome
   uncertain.
-- If submission or finalized verification is ambiguous, the CLI returns `state: "uncertain"`,
-  `purchaseId` and `txHash`, and keeps `nearSubmission: {state:"uncertain",txHash}` in the encrypted
-  purchase backup. Check status for that saved purchase before buying again.
+- If submission or finalized verification is ambiguous, the CLI returns `state: "uncertain"` and
+  `purchaseId`, and keeps `nearSubmission: {state:"uncertain"}` in the encrypted purchase backup.
+  Both carry `txHash` only when the wallet returned a valid one. `annon buy` exits 4. Check status
+  for that saved purchase before buying again.
 - Signing errors with a known hash also expose safe hash and purchase evidence, with exit code 4.
 
 **Reference handler.** `node/signer-mock` exports `signerMock`, an authenticated HTTP

package/dist/api/annon-types.d.ts

@@ -100,9 +100,10 @@ export interface Bought {
     route: BuyRoute;
     record: PurchaseRecord;
     instructions?: Deposit;
+    /** `txHash` is absent when the wallet may have sent the transaction without returning one. */
     uncertain?: {
         purchaseId: string;
-        txHash: string;
+        txHash?: string;
     };
     payment?: string;
 }

package/dist/api/annon.js

@@ -869,11 +869,18 @@ export class Annon {
                 const next = {
                     ...record,
                     revision: record.revision + 1,
-                    nearSubmission: { state: 'uncertain', txHash: error.txHash },
+                    nearSubmission: {
+                        state: 'uncertain',
+                        ...(error.txHash ? { txHash: error.txHash } : {}),
+                    },
                 };
                 if (!(await store.compareAndSet(purchaseKey(id), record, next)))
                     throw new TransactionUncertain(error.txHash, id);
-                return { route, record: next, uncertain: { purchaseId: id, txHash: error.txHash } };
+                return {
+                    route,
+                    record: next,
+                    uncertain: { purchaseId: id, ...(error.txHash ? { txHash: error.txHash } : {}) },
+                };
             }
             return { route, record };
         }

package/dist/browser/index.d.ts

@@ -18,6 +18,6 @@ export { type CatalogEntry, type CatalogQuery, type ConfiguredShop, canonicalMan
 export { TransactionUncertain } from '../wallet/uncertain.js';
 export { type EvmWallet, FileFundingRefused, type IdentityWallet, type NearWallet, } from '../wallet/wallet.js';
 export { BROWSER_DOWNLOAD_LIMIT, type BrowserDownloadOptions, type BrowserDownloadProgress, browserDownload, } from './download.js';
-export { type BrowserOpenOptions, BrowserPurchaseController, type BrowserPurchaseRecord, type BrowserPurchaseState, type BrowserPurchaseStorage, browserAnnon, browserPurchaseStorage, type ControllerOptions, PurchaseLeaseBusy, type PurchaseProgress, type PurchaseSdk, type PurchaseTermsReview, } from './purchases.js';
+export { type BrowserOpenOptions, BrowserPurchaseController, type BrowserPurchaseRecord, type BrowserPurchaseState, type BrowserPurchaseStorage, browserAnnon, browserPurchaseStorage, type ControllerOptions, PurchaseLeaseBusy, type PurchaseProgress, type PurchaseSdk, type PurchaseTermsReview, type ReconcileOptions, type ReconcileResult, } from './purchases.js';
 export { type BrowserSaleIndex, type BrowserSellerOptions, browserSellerSpool, browserSellerStorage, createBrowserSeller, type SaleHandle, type SaleView, type SellDraft, type SellerConnection, type SellerFacade, type SellProgress, type SellQuote, type SellStep, type SellTerms, } from './selling.js';
 export { type BrowserNearProvider, type BrowserNearTransaction, BrowserWalletError, type BrowserWalletErrorCode, browserEvmWallet, browserNearWallet, browserSolanaWallet, type InjectedEvmProvider, type InjectedSolanaKey, type InjectedSolanaProvider, signNearUpload, } from './wallets.js';