@palmyr/cli 1.8.2 → 1.8.3

package/README.md

@@ -112,18 +112,28 @@ from a single 12-word mnemonic. Wallets are created locally; the seed never leav
 
 ### Creating a wallet
 
+Wallet creation **requires** a recoverable passphrase fallback (the env var keeps the phrase out of shell history) — or an explicit `--session-only` opt-out for ephemeral wallets you're OK losing on reboot / keyring change / host migration.
+
 ```bash
-# Unmanaged: one command, ready to sign
-palmyr wallet create --name agent-prod
+# Recommended — env-var passphrase fallback (durable across reboots and machines)
+PALMYR_WALLET_PASSPHRASE="your-passphrase" palmyr wallet create --name agent-prod
 
-# Managed: prints a setup link to send to a human
-palmyr wallet create --name treasury --managed
+# Equivalent — flag form (less safe, ends up in shell history)
+palmyr wallet create --name agent-prod --passphrase "your-passphrase"
+
+# Managed: same passphrase rules; also prints a setup link to send to a human
+PALMYR_WALLET_PASSPHRASE="..." palmyr wallet create --name treasury --managed
 
 # Single-chain: skip the other chain's account
-palmyr wallet create --name sol-only --solana
-palmyr wallet create --name base-only --base
+PALMYR_WALLET_PASSPHRASE="..." palmyr wallet create --name sol-only --solana
+PALMYR_WALLET_PASSPHRASE="..." palmyr wallet create --name base-only --base
+
+# OPT OUT — bound to this machine's OS keychain, NOT recoverable from the JSON file alone
+palmyr wallet create --name throwaway --session-only
 ```
 
+On a TTY without env or flag, the CLI prompts twice with confirmation; non-TTY callers (CI, agents) must provide one of the three knobs above or get a clear error.
+
 By default a wallet derives both Solana and Base/EVM accounts. Pass `--solana` or `--base` (not both) to materialize only one side. The mnemonic always derives both — `--solana` / `--base` controls *which addresses are surfaced and stored*, not which keys exist cryptographically.
 
 The managed flow returns a one-time URL. The recipient opens it in a browser, registers a WebAuthn passkey, and sets spending limits. From that point on, transactions inside the limit sign instantly; transactions over the limit emit an `approvalUrl` that the human visits to authenticate and approve.
@@ -162,7 +172,9 @@ palmyr wallet import --mnemonic "..." --name from-backup --tag restored --solana
 
 ### Durable recovery — passphrase fallback
 
-By default a wallet is **session-only**: the mnemonic is encrypted with a random session secret stored in your OS credential store (DPAPI / Keychain / `secret-tool`). That secret does not survive a different OS user, a fresh install, or a headless box without an unlocked keyring. Two ways to add a durable scrypt-derived passphrase that decrypts on any machine:
+Wallets created with a passphrase store **two** decryption blobs: one keyed by the OS-keychain session secret (fast, local), one keyed by scrypt(passphrase, salt) (durable). Decryption tries the keychain first, then falls back to `PALMYR_WALLET_PASSPHRASE`. That second blob is what lets the wallet survive a reboot, OS-keychain password change, fresh OS install, or copy to another machine.
+
+Session-only wallets (`--session-only`) **only** have the keychain blob and are NOT recoverable from the JSON file alone. If you have legacy session-only wallets and still have access to the original machine, add a fallback retroactively:
 
 ```bash
 # At create time — env var preferred (keeps the phrase out of shell history)
@@ -426,8 +438,8 @@ All wallet operations except `addresses`, `api-key`, `config`, and `request-appr
 
 | Command | Network | Notes |
 |---|---|---|
-| `palmyr wallet create [--name N] [--managed] [--solana\|--base] [--tag T] [--count N] [--name-prefix P] [--passphrase P]` | local *(server only if `--managed`)* | New wallet. Stores session secret in OS credential store. `--count > 1` bulk-creates N unmanaged wallets under a required `--tag` (max 500/call, batched DPAPI seal on Windows). `--solana` / `--base` materializes only one chain. `--passphrase` (or `PALMYR_WALLET_PASSPHRASE` env) also seals the mnemonic with scrypt so the wallet survives OS-keychain loss. |
-| `palmyr wallet import --mnemonic "..." [--name N] [--managed] [--solana\|--base] [--tag T] [--passphrase P]` | local | Restore from BIP-39. Same chain / tag / passphrase flags as `create`. |
+| `palmyr wallet create [--name N] [--managed] [--solana\|--base] [--tag T] [--count N] [--name-prefix P] (--passphrase P \| PALMYR_WALLET_PASSPHRASE env \| --session-only)` | local *(server only if `--managed`)* | New wallet. **Requires** either a passphrase (recoverable across reboot / OS-keychain loss / host migration) or explicit `--session-only` opt-out. On TTY without env/flag, prompts twice. Stores keychain secret + (with passphrase) a scrypt-sealed `owner_crypto` blob. `--count > 1` bulk-creates N unmanaged wallets under a required `--tag` (max 500/call, batched DPAPI seal on Windows). |
+| `palmyr wallet import --mnemonic "..." [--name N] [--managed] [--solana\|--base] [--tag T] (--passphrase P \| PALMYR_WALLET_PASSPHRASE env \| --session-only)` | local | Restore from BIP-39. Same passphrase rules as `create` — re-importing on a new machine to recover from keychain loss should always set a passphrase so you don't get trapped again. |
 | `palmyr wallet rekey <ID> --passphrase P` | local | Add (or rotate) the scrypt passphrase fallback on an existing wallet. Wallet must be decryptable right now (session secret still works, or `--current-passphrase` provided). Run on the original machine, then `PALMYR_WALLET_PASSPHRASE` decrypts the wallet anywhere. |
 | `palmyr wallet list [--tag T]` | local | Lists wallets in the local vault. `--tag` filters to one folder. |
 | `palmyr wallet info <ID>` | local | Show one wallet (id, name, addresses, mode, tag). |
@@ -803,10 +815,11 @@ Config is stored in `~/.palmyr/config.json`. Environment variables override file
 
 The payment chain is resolved in this order:
 
-1. The `--chain` flag passed to `wallet use`, persisted as `defaultPayChain`.
-2. `PALMYR_PAY_CHAIN` environment variable.
-3. `defaultChain` in config.
-4. `solana` as the final default.
+1. `--chain` flag on the command itself (e.g. `wallet pay-preflight --chain base`).
+2. `defaultPayChain` in `~/.palmyr/config.json` — set by `palmyr wallet use <ID> --chain <chain>`.
+3. `solana` as the final default.
+
+(Earlier versions of this doc listed `PALMYR_PAY_CHAIN` and `defaultChain` as fallbacks — neither is read by the current pay path. `defaultChain` is legacy keyfile-flow state and `saveConfig` strips it from vault-only configs.)
 
 If the server doesn't offer the chosen chain for an endpoint, the CLI errors loudly. There is no silent fallback — the assumption is that an agent should know which chain it pays from.
 
@@ -856,7 +869,7 @@ The CLI uses distinct exit codes so scripts and agents can branch on failure mod
 - **Keys never leave the machine.** `wallet create` and `wallet import` never transmit seed material to the server. Even managed wallets register only the wallet ID and the derived public addresses with the server.
 - **Encryption at rest.** The wallet file is AES-256-GCM with the session secret as the key. The session secret is generated on wallet creation and never stored on disk in plaintext.
 - **OS credential store.** Session secrets live in DPAPI (Windows), Keychain (macOS), or `secret-tool` (libsecret on Linux). If none is available the CLI errors rather than falling back to plaintext.
-- **Optional passphrase fallback.** Create with `--passphrase` (or `PALMYR_WALLET_PASSPHRASE` env), or migrate with `wallet rekey`, to add a second AES-256-GCM blob keyed by scrypt(passphrase, random salt). Lets the wallet decrypt on a different machine / user / headless box where the OS keychain isn't reachable. Decryption tries the OS session secret first, then falls back to the env/flag passphrase.
+- **Recoverable by default.** `wallet create` and `wallet import` require a scrypt passphrase fallback (via `--passphrase` or `PALMYR_WALLET_PASSPHRASE`) or an explicit `--session-only` opt-out. The passphrase blob is a second AES-256-GCM ciphertext keyed by scrypt(passphrase, random salt) and lets the wallet decrypt on a different machine / user / headless box where the OS keychain isn't reachable. Decryption tries the OS session secret first, then falls back to the env/flag passphrase. Session-only wallets are bound to this machine's OS keychain — explicit opt-in for ephemeral use only.
 - **Bidirectional vault integrity.** On every load, the CLI checks that every account stored in the wallet file is still derivable from the seed, **and** that every account derivable from the seed is still in the file. Either direction failing returns exit code `7`.
 - **Pre-flight validation.** Endpoints that are easy to fail (bad pubkey for an inbox, malformed E.164 for SMS, unsupported destination country) are validated **before** the x402 paywall, so you don't pay for requests that were never going to succeed.
 - **No `--no-verify`.** Hooks, signatures, and webhooks are always verified.

package/dist/cli.js

@@ -209,6 +209,22 @@ function subcommandHelp(command, subcommand, options) {
     }
     console.log();
 }
+/**
+ * Loud, single-shot warning printed when `--session-only` was chosen. Goes to
+ * stderr so JSON on stdout stays clean. Caller supplies the write fn so we
+ * route through the right stream in agent vs TTY mode.
+ *
+ * Why this is here: 1.8.2 and earlier defaulted to session-only without
+ * warning. A user lost three wallets to a routine keyring change on a
+ * headless box because the JSON file alone is mathematically useless without
+ * the keychain secret. 1.8.3 makes the choice explicit; this warning is the
+ * reminder for anyone who picks the foot-gun anyway.
+ */
+function emitSessionOnlyWarning(write) {
+    write(`\n  ${t.warn}⚠  session-only wallet — NOT recoverable from the JSON file alone.${t.reset}\n`);
+    write(`     Reboot, OS-keychain password change, or host copy permanently breaks decryption.\n`);
+    write(`     Back up the mnemonic externally, or run \`palmyr wallet rekey <id> --passphrase <p>\` later.\n\n`);
+}
 // ─── Subcommand help definitions ───
 const WALLET_HELP = {
     create: [
@@ -219,7 +235,8 @@ const WALLET_HELP = {
         { flag: '--tag <name>', desc: 'Folder-like grouping tag', hint: 'e.g. palmyr-demo — required with --count' },
         { flag: '--count <N>', desc: 'Bulk-create N wallets in one call (1-500)', hint: 'unmanaged only; requires --tag' },
         { flag: '--name-prefix <p>', desc: 'Bulk name prefix; suffixed `-001..-N`', hint: 'default: same as --tag' },
-        { flag: '--passphrase <p>', desc: 'Also seal the mnemonic with this passphrase (≥8 chars) for durable recovery', hint: 'or PALMYR_WALLET_PASSPHRASE env (env preferred — keeps phrase out of shell history)' },
+        { flag: '--passphrase <p>', desc: 'Seal the mnemonic with this passphrase (≥8 chars) for durable recovery across reboot / OS-keychain loss / host migration', hint: 'or PALMYR_WALLET_PASSPHRASE env (env preferred — keeps phrase out of shell history). Interactive prompt on TTY when neither set.' },
+        { flag: '--session-only', desc: 'OPT OUT of the passphrase fallback. Wallet is bound to this machine\'s OS keychain — dies on reboot/keyring loss/migration.', hint: 'use only for ephemeral / throwaway wallets where loss is acceptable' },
     ],
     import: [
         { flag: '--mnemonic <words>', desc: 'BIP-39 mnemonic phrase (required)' },
@@ -228,7 +245,8 @@ const WALLET_HELP = {
         { flag: '--solana', desc: 'Materialize the Solana account only' },
         { flag: '--base', desc: 'Materialize the Base/EVM account only' },
         { flag: '--tag <name>', desc: 'Assign a tag at import time' },
-        { flag: '--passphrase <p>', desc: 'Also seal the mnemonic with this passphrase (≥8 chars) for durable recovery', hint: 'or PALMYR_WALLET_PASSPHRASE env (env preferred)' },
+        { flag: '--passphrase <p>', desc: 'Seal the mnemonic with this passphrase (≥8 chars) for durable recovery', hint: 'or PALMYR_WALLET_PASSPHRASE env (env preferred). Interactive prompt on TTY when neither set.' },
+        { flag: '--session-only', desc: 'OPT OUT of the passphrase fallback. Wallet is bound to this machine\'s OS keychain.', hint: 'use only for ephemeral / throwaway wallets' },
     ],
     rekey: [
         { flag: '<WALLET_ID>', desc: 'Wallet ID or name (positional or --id)' },
@@ -2210,10 +2228,37 @@ async function main() {
                         const chains = (wantSol && !wantBase) ? ['solana']
                             : (wantBase && !wantSol) ? ['base']
                                 : ['solana', 'base'];
-                        // Optional passphrase fallback — seals the mnemonic with scrypt so
-                        // PALMYR_WALLET_PASSPHRASE can decrypt on a different machine / user /
-                        // headless box where the OS credential-store secret isn't reachable.
-                        const passphrase = flags.passphrase || process.env.PALMYR_WALLET_PASSPHRASE || undefined;
+                        // Passphrase resolution — recoverable-by-default.
+                        // Three paths:
+                        //   1. `--passphrase <p>` or `PALMYR_WALLET_PASSPHRASE` env → seal with scrypt
+                        //   2. `--session-only` → explicit opt-out, OS-keychain-only (warned)
+                        //   3. nothing + TTY → interactive prompt
+                        //   4. nothing + non-TTY → error with the three options
+                        // Session-only wallets are recoverable ONLY from this machine's OS
+                        // keychain; reboot / keyring change / host migration breaks them
+                        // permanently. We pushed agents into that foot-gun in 1.8.2 and
+                        // earlier; 1.8.3 forces the choice up front.
+                        const sessionOnly = !!flags['session-only'];
+                        let passphrase = flags.passphrase || process.env.PALMYR_WALLET_PASSPHRASE || undefined;
+                        if (passphrase && sessionOnly) {
+                            err('Pass either --passphrase / PALMYR_WALLET_PASSPHRASE OR --session-only, not both.', EXIT.BAD_INPUT);
+                        }
+                        if (!passphrase && !sessionOnly) {
+                            if (process.stdin.isTTY) {
+                                const { promptNewPassphrase } = await import('./passphrase-prompt.js');
+                                if (!AGENT_MODE)
+                                    process.stderr.write('\n  Wallet creation needs a passphrase fallback so the wallet survives a reboot / OS-keychain change / host migration.\n' +
+                                        '  (Re-run with --session-only to opt out — ephemeral wallets only.)\n\n');
+                                passphrase = await promptNewPassphrase('vault wallet');
+                            }
+                            else {
+                                err('Wallet creation requires a recoverable passphrase fallback OR an explicit opt-out:\n\n' +
+                                    '  PALMYR_WALLET_PASSPHRASE="<phrase>" palmyr wallet create [...]   # recommended (env keeps phrase out of shell history)\n' +
+                                    '  palmyr wallet create --passphrase "<phrase>" [...]               # equivalent\n' +
+                                    '  palmyr wallet create --session-only [...]                        # OPT OUT — wallet dies with this machine\'s OS keychain\n\n' +
+                                    'Session-only wallets are NOT recoverable from the JSON file alone — reboot, keyring change, or host copy renders them unusable.', EXIT.BAD_INPUT);
+                            }
+                        }
                         // ─── Bulk path ───
                         if (count > 1) {
                             if (isManaged)
@@ -2227,17 +2272,36 @@ async function main() {
                             const { storeSecretsBatch } = await import('./credential-store.js');
                             // Progress to stderr so JSON on stdout stays clean
                             if (!AGENT_MODE)
-                                process.stderr.write(`creating ${count} wallets under tag "${tagRaw}"${passphrase ? ' (+ passphrase fallback)' : ''}...\n`);
+                                process.stderr.write(`creating ${count} wallets under tag "${tagRaw}"${passphrase ? ' (+ passphrase fallback)' : ' (session-only)'}...\n`);
                             const results = createLocalWalletsBatch(prefix, count, 'unmanaged', { tag: tagRaw, chains, passphrase });
                             if (!AGENT_MODE)
                                 process.stderr.write(`sealing ${count} session secrets in OS credential store...\n`);
-                            storeSecretsBatch(results.map(r => ({ account: r.id, secret: r.sessionSecret })));
-                            log(`wallet create: ${count} wallets under tag "${tagRaw}" (chains=${chains.join(',')}${passphrase ? ', passphrase=set' : ''})`);
+                            // Keychain failure is non-fatal IFF a passphrase fallback was
+                            // written — the wallets are still recoverable via the env var.
+                            let keychainStoreWarning = null;
+                            try {
+                                storeSecretsBatch(results.map(r => ({ account: r.id, secret: r.sessionSecret })));
+                            }
+                            catch (e) {
+                                if (passphrase) {
+                                    keychainStoreWarning = e?.message || 'keychain store failed';
+                                    if (!AGENT_MODE)
+                                        process.stderr.write(`  warning: OS keychain unavailable (${keychainStoreWarning}); wallets remain decryptable via PALMYR_WALLET_PASSPHRASE\n`);
+                                }
+                                else {
+                                    throw e;
+                                }
+                            }
+                            if (sessionOnly && !AGENT_MODE)
+                                emitSessionOnlyWarning(process.stderr.write.bind(process.stderr));
+                            log(`wallet create: ${count} wallets under tag "${tagRaw}" (chains=${chains.join(',')}, mode=${passphrase ? 'passphrase' : 'session-only'}${keychainStoreWarning ? ', keychain=failed' : ''})`);
                             if (AGENT_MODE) {
                                 print({
                                     count: results.length,
                                     tag: tagRaw,
                                     chains,
+                                    recoverable: !!passphrase,
+                                    ...(keychainStoreWarning ? { keychainWarning: keychainStoreWarning } : {}),
                                     wallets: results.map(r => ({
                                         id: r.id,
                                         name: r.name,
@@ -2253,6 +2317,7 @@ async function main() {
                                 console.log(`\n  ${t.success}✔${t.reset} Created ${count} wallets under tag ${t.accent}${tagRaw}${t.reset}`);
                                 console.log(`  ${t.muted}chains:${t.reset} ${chains.join(', ')}`);
                                 console.log(`  ${t.muted}names: ${t.reset}${results[0].name} … ${results[results.length - 1].name}`);
+                                console.log(`  ${t.muted}recoverable:${t.reset} ${passphrase ? 'yes (passphrase fallback set)' : 'NO — session-only'}`);
                                 console.log(`\n  ${t.muted}List them:    ${t.reset}palmyr wallet list --tag ${tagRaw}`);
                                 console.log(`  ${t.muted}Delete all:   ${t.reset}palmyr wallet tag-delete ${tagRaw} --confirm\n`);
                             }
@@ -2265,10 +2330,26 @@ async function main() {
                         // Create locally — no server needed for the key material
                         const { createLocalWallet } = await import('./vault.js');
                         const w = createLocalWallet(name, mode, { tag: tagRaw, chains, passphrase });
-                        // Store session secret in OS credential store
+                        // Store session secret in OS credential store. Keychain failure is
+                        // non-fatal when a passphrase fallback was written.
                         const { storeSecret } = await import('./credential-store.js');
-                        storeSecret(w.id, w.sessionSecret);
-                        log(`wallet create: ${w.id} (${mode}${tagRaw ? `, tag=${tagRaw}` : ''}, chains=${chains.join(',')})`);
+                        let keychainStoreWarning = null;
+                        try {
+                            storeSecret(w.id, w.sessionSecret);
+                        }
+                        catch (e) {
+                            if (passphrase) {
+                                keychainStoreWarning = e?.message || 'keychain store failed';
+                                if (!AGENT_MODE)
+                                    process.stderr.write(`  warning: OS keychain unavailable (${keychainStoreWarning}); wallet remains decryptable via PALMYR_WALLET_PASSPHRASE\n`);
+                            }
+                            else {
+                                throw e;
+                            }
+                        }
+                        if (sessionOnly && !AGENT_MODE)
+                            emitSessionOnlyWarning(process.stderr.write.bind(process.stderr));
+                        log(`wallet create: ${w.id} (${mode}${tagRaw ? `, tag=${tagRaw}` : ''}, chains=${chains.join(',')}, mode=${passphrase ? 'passphrase' : 'session-only'}${keychainStoreWarning ? ', keychain=failed' : ''})`);
                         // For managed wallets, register metadata with the server to get a setup link
                         let setupLink;
                         if (isManaged) {
@@ -2312,7 +2393,7 @@ async function main() {
                             }
                         }
                         else {
-                            print({ ...w, setupLink });
+                            print({ ...w, setupLink, recoverable: !!passphrase, ...(keychainStoreWarning ? { keychainWarning: keychainStoreWarning } : {}) });
                         }
                         break;
                     }
@@ -2328,13 +2409,52 @@ async function main() {
                         const chains = (wantSol && !wantBase) ? ['solana']
                             : (wantBase && !wantSol) ? ['base']
                                 : ['solana', 'base'];
-                        const passphrase = flags.passphrase || process.env.PALMYR_WALLET_PASSPHRASE || undefined;
+                        // Same recoverability gate as `create`. Import is even more
+                        // commonly run on a "new machine" after losing access on the
+                        // original — going session-only here would re-trap the user in
+                        // the same hole they're recovering from.
+                        const importSessionOnly = !!flags['session-only'];
+                        let importPassphrase = flags.passphrase || process.env.PALMYR_WALLET_PASSPHRASE || undefined;
+                        if (importPassphrase && importSessionOnly) {
+                            err('Pass either --passphrase / PALMYR_WALLET_PASSPHRASE OR --session-only, not both.', EXIT.BAD_INPUT);
+                        }
+                        if (!importPassphrase && !importSessionOnly) {
+                            if (process.stdin.isTTY) {
+                                const { promptNewPassphrase } = await import('./passphrase-prompt.js');
+                                if (!AGENT_MODE)
+                                    process.stderr.write('\n  Import needs a passphrase fallback so the wallet survives a reboot / OS-keychain change / host migration.\n' +
+                                        '  (Re-run with --session-only to opt out — ephemeral wallets only.)\n\n');
+                                importPassphrase = await promptNewPassphrase('vault wallet');
+                            }
+                            else {
+                                err('Wallet import requires a recoverable passphrase fallback OR an explicit opt-out:\n\n' +
+                                    '  PALMYR_WALLET_PASSPHRASE="<phrase>" palmyr wallet import --mnemonic "..."   # recommended\n' +
+                                    '  palmyr wallet import --mnemonic "..." --passphrase "<phrase>"               # equivalent\n' +
+                                    '  palmyr wallet import --mnemonic "..." --session-only                        # OPT OUT — wallet dies with this machine\'s OS keychain', EXIT.BAD_INPUT);
+                            }
+                        }
                         const { importLocalWallet } = await import('./vault.js');
-                        const w = importLocalWallet(name, mnemonic, mode, { tag: tagRaw, chains, passphrase });
-                        // Store session secret
+                        const w = importLocalWallet(name, mnemonic, mode, { tag: tagRaw, chains, passphrase: importPassphrase });
+                        // Store session secret. Keychain failure is non-fatal when a
+                        // passphrase fallback was written.
                         const { storeSecret } = await import('./credential-store.js');
-                        storeSecret(w.id, w.sessionSecret);
-                        log(`wallet import: ${w.id}${passphrase ? ' (+ passphrase fallback)' : ''}`);
+                        let importKeychainWarning = null;
+                        try {
+                            storeSecret(w.id, w.sessionSecret);
+                        }
+                        catch (e) {
+                            if (importPassphrase) {
+                                importKeychainWarning = e?.message || 'keychain store failed';
+                                if (!AGENT_MODE)
+                                    process.stderr.write(`  warning: OS keychain unavailable (${importKeychainWarning}); wallet remains decryptable via PALMYR_WALLET_PASSPHRASE\n`);
+                            }
+                            else {
+                                throw e;
+                            }
+                        }
+                        if (importSessionOnly && !AGENT_MODE)
+                            emitSessionOnlyWarning(process.stderr.write.bind(process.stderr));
+                        log(`wallet import: ${w.id} (mode=${importPassphrase ? 'passphrase' : 'session-only'}${importKeychainWarning ? ', keychain=failed' : ''})`);
                         if (!AGENT_MODE) {
                             render(React.createElement(WalletCreateScreen, {
                                 version: VERSION,
@@ -2347,7 +2467,7 @@ async function main() {
                             }));
                         }
                         else {
-                            print(w);
+                            print({ ...w, recoverable: !!importPassphrase, ...(importKeychainWarning ? { keychainWarning: importKeychainWarning } : {}) });
                         }
                         break;
                     }
@@ -2517,9 +2637,13 @@ async function main() {
                         const msg = flags.msg || flags.message;
                         if (!chain || !msg)
                             err('--chain and --msg required');
-                        // Sign locally — no server needed
+                        // Sign locally — no server needed.
+                        // Read the same passphrase channel as pay / export / rekey so a
+                        // passphrase-backed wallet signs from any machine the env var
+                        // reaches (was missing in 1.8.2 — inconsistent with other commands).
+                        const signPass = flags.passphrase || process.env.PALMYR_WALLET_PASSPHRASE || undefined;
                         const { signMessageLocal } = await import('./vault.js');
-                        const data = signMessageLocal(walletId, chain, msg);
+                        const data = signMessageLocal(walletId, chain, msg, signPass);
                         return print({ success: true, ...data });
                         render(React.createElement(SuccessScreen, {
                             version: VERSION,
@@ -6575,12 +6699,18 @@ async function main() {
                 const { join } = await import('path');
                 const vaultDir = process.env.PALMYR_WALLET_PATH || join(homedir(), '.palmyr', 'wallet');
                 const { isCredentialStoreAvailable } = await import('./credential-store.js');
+                const { hasLegacyKeyfileWallet } = await import('./config.js');
+                // `defaultChain` is legacy keyfile-flow state — only show it when a
+                // keyfile wallet is actually configured. The functional field is
+                // `payChain` (renamed from the misleadingly-similar `defaultPayChain`
+                // disk key), which the x402 pay path reads.
+                const showLegacyChain = hasLegacyKeyfileWallet(cfg);
                 const configData = {
                     api: cfg.api,
-                    defaultChain: cfg.defaultChain,
                     setupDone: cfg.setupDone,
+                    ...(showLegacyChain ? { legacyKeyfileChain: cfg.defaultChain || 'solana' } : {}),
                     defaultPayWalletId: cfg.defaultPayWalletId || null,
-                    defaultPayChain: cfg.defaultPayChain || 'solana',
+                    payChain: cfg.defaultPayChain || 'solana',
                     vaultPath: vaultDir,
                     credentialStore: isCredentialStoreAvailable() ? 'available' : 'unavailable',
                     configPath: join(homedir(), '.palmyr', 'config.json'),
@@ -6611,21 +6741,67 @@ async function main() {
                 const { listVaultWallets } = await import('./vault.js');
                 const wallets = listVaultWallets();
                 checks.push({ name: 'Local wallets', status: wallets.length > 0 ? 'pass' : 'warn', detail: `${wallets.length} wallet(s) found` });
-                // 4. Session secrets present for wallets
+                // 4. Decryption readiness for each wallet — tri-state.
+                //
+                //   pass  → wallet has keychain secret, OR has a passphrase fallback
+                //           AND PALMYR_WALLET_PASSPHRASE is set
+                //   warn  → has passphrase fallback but env unset (recoverable, but
+                //           the next command will fail until env is set)
+                //   fail  → session-only AND keychain secret is gone (unrecoverable
+                //           from this machine — needs mnemonic re-import or
+                //           rekey-on-original)
                 const { retrieveSecret } = await import('./credential-store.js');
-                let secretsOk = 0, secretsMissing = 0;
+                const { hasPassphraseFallback } = await import('./vault.js');
+                const envSet = !!process.env.PALMYR_WALLET_PASSPHRASE;
+                let keychainOk = 0;
+                let needsEnv = 0;
+                let unrecoverable = [];
                 for (const w of wallets) {
-                    if (retrieveSecret(w.id))
-                        secretsOk++;
-                    else
-                        secretsMissing++;
+                    if (retrieveSecret(w.id)) {
+                        keychainOk++;
+                        continue;
+                    }
+                    let hasFallback = false;
+                    try {
+                        hasFallback = hasPassphraseFallback(w.id);
+                    }
+                    catch { }
+                    if (hasFallback) {
+                        needsEnv++;
+                    }
+                    else {
+                        unrecoverable.push(w.name || w.id.slice(0, 8));
+                    }
                 }
                 if (wallets.length > 0) {
-                    checks.push({
-                        name: 'Session secrets',
-                        status: secretsMissing === 0 ? 'pass' : 'fail',
-                        detail: secretsMissing === 0 ? `All ${secretsOk} wallet(s) have secrets stored` : `${secretsMissing} wallet(s) missing session secret`,
-                    });
+                    if (unrecoverable.length > 0) {
+                        checks.push({
+                            name: 'Wallet decryption',
+                            status: 'fail',
+                            detail: `${unrecoverable.length} session-only wallet(s) UNRECOVERABLE from this machine — keychain secret missing and no passphrase fallback (${unrecoverable.slice(0, 3).join(', ')}${unrecoverable.length > 3 ? ', …' : ''}). Recover by importing the mnemonic here, or running \`palmyr wallet rekey <id> --passphrase <p>\` on the original machine.`,
+                        });
+                    }
+                    else if (needsEnv > 0 && !envSet) {
+                        checks.push({
+                            name: 'Wallet decryption',
+                            status: 'warn',
+                            detail: `${needsEnv} wallet(s) need PALMYR_WALLET_PASSPHRASE to decrypt (keychain secret missing, passphrase fallback present). Set the env var to unblock pay / sign / export.`,
+                        });
+                    }
+                    else if (needsEnv > 0) {
+                        checks.push({
+                            name: 'Wallet decryption',
+                            status: 'pass',
+                            detail: `${keychainOk} via OS keychain, ${needsEnv} via PALMYR_WALLET_PASSPHRASE (env set)`,
+                        });
+                    }
+                    else {
+                        checks.push({
+                            name: 'Wallet decryption',
+                            status: 'pass',
+                            detail: `All ${keychainOk} wallet(s) have keychain secrets`,
+                        });
+                    }
                 }
                 // 5. API connectivity
                 try {