@palmyr/cli 1.8.1 → 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
+
+# Equivalent — flag form (less safe, ends up in shell history)
+palmyr wallet create --name agent-prod --passphrase "your-passphrase"
 
-# Managed: prints a setup link to send to a human
-palmyr wallet create --name treasury --managed
+# 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.
@@ -160,6 +170,25 @@ palmyr wallet import --mnemonic "twelve word seed phrase ..." --name imported
 palmyr wallet import --mnemonic "..." --name from-backup --tag restored --solana
 ```
 
+### Durable recovery — passphrase fallback
+
+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)
+PALMYR_WALLET_PASSPHRASE="your-passphrase" palmyr wallet create --name agent-prod
+
+# Migrate an existing wallet — run on the original machine while the OS session secret still works
+palmyr wallet rekey <WALLET_ID> --passphrase "your-passphrase"
+
+# Recover on a new machine — copy ~/.palmyr/wallet/wallets/<id>.json over, then:
+PALMYR_WALLET_PASSPHRASE="your-passphrase" palmyr wallet info <WALLET_ID>
+```
+
+When set, the wallet file gets a second AES-256-GCM blob (`owner_crypto`, scrypt KDF on the passphrase + random salt). Decryption tries the OS session secret first, then falls back to `PALMYR_WALLET_PASSPHRASE` / `--passphrase`. Minimum length 8 chars. Re-running `wallet rekey` rotates — old passphrase stops working.
+
 ### Exporting a seed
 
 ```bash
@@ -409,8 +438,9 @@ 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]` | 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. |
-| `palmyr wallet import --mnemonic "..." [--name N] [--managed] [--solana\|--base] [--tag T]` | local | Restore from BIP-39. Same chain / tag 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). |
 | `palmyr wallet tags` | local | List all tags with wallet count, chains, and date range. |
@@ -779,16 +809,17 @@ Config is stored in `~/.palmyr/config.json`. Environment variables override file
 | `PALMYR_PAY_WALLET` | Force a specific wallet ID for x402 payment. |
 | `PALMYR_WALLET_PATH` | Override vault directory (default `~/.palmyr/wallet`). |
 | `PALMYR_KEYFILE` | Solana keyfile path (legacy single-key flow). |
-| `PALMYR_WALLET_PASSPHRASE` | Optional BIP-39 passphrase for legacy import/export. |
+| `PALMYR_WALLET_PASSPHRASE` | Vault decryption passphrase. Used when the wallet was created with `--passphrase` (or env) or migrated via `wallet rekey`. Falls back to the OS-keychain session secret when unset. |
 
 ### Chain selection during payment
 
 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.
 
@@ -838,6 +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.
+- **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,6 +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: '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)' },
@@ -227,6 +245,14 @@ 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: '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)' },
+        { flag: '--passphrase <p>', desc: 'New passphrase to seal the mnemonic with (≥8 chars)', hint: 'or PALMYR_WALLET_PASSPHRASE env; interactive prompt if neither set' },
+        { flag: '--current-passphrase <p>', desc: 'Existing passphrase, if the wallet was already rekeyed and the OS session secret is gone', hint: 'or PALMYR_WALLET_PASSPHRASE_CURRENT env' },
+        { flag: '(note)', desc: 'Run on the original machine while the OS session secret is still resolvable. Becomes the durable recovery path on any other host.' },
     ],
     tags: [
         { flag: '(no args)', desc: 'List all tags with wallet count, chains, and date range' },
@@ -2153,6 +2179,7 @@ async function main() {
                             { name: 'tag-delete', description: 'Cascade-delete every wallet under a tag', hint: 'TAG --confirm' },
                             { name: 'sign-message', description: 'Sign a message', hint: 'WALLET_ID --chain evm --msg "hello"' },
                             { name: 'export', description: 'Export mnemonic for backup', hint: 'WALLET_ID --confirm' },
+                            { name: 'rekey', description: 'Add or rotate the passphrase fallback (durable across OS-keychain loss)', hint: 'WALLET_ID --passphrase <p>' },
                             { name: 'api-key', description: 'Create agent API key', hint: 'WALLET_ID --name my-agent' },
                             { name: 'config', description: 'Get agent config', hint: 'WALLET_ID' },
                             { name: 'use', description: 'Set default pay wallet', hint: 'WALLET_ID' },
@@ -2201,6 +2228,37 @@ async function main() {
                         const chains = (wantSol && !wantBase) ? ['solana']
                             : (wantBase && !wantSol) ? ['base']
                                 : ['solana', 'base'];
+                        // 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)
@@ -2214,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}"...\n`);
-                            const results = createLocalWalletsBatch(prefix, count, 'unmanaged', { tag: tagRaw, chains });
+                                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(',')})`);
+                            // 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,
@@ -2240,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`);
                             }
@@ -2251,11 +2329,27 @@ async function main() {
                         const mode = isManaged ? 'managed' : 'unmanaged';
                         // Create locally — no server needed for the key material
                         const { createLocalWallet } = await import('./vault.js');
-                        const w = createLocalWallet(name, mode, { tag: tagRaw, chains });
-                        // Store session secret in OS credential store
+                        const w = createLocalWallet(name, mode, { tag: tagRaw, chains, passphrase });
+                        // 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) {
@@ -2299,7 +2393,7 @@ async function main() {
                             }
                         }
                         else {
-                            print({ ...w, setupLink });
+                            print({ ...w, setupLink, recoverable: !!passphrase, ...(keychainStoreWarning ? { keychainWarning: keychainStoreWarning } : {}) });
                         }
                         break;
                     }
@@ -2315,12 +2409,52 @@ async function main() {
                         const chains = (wantSol && !wantBase) ? ['solana']
                             : (wantBase && !wantSol) ? ['base']
                                 : ['solana', 'base'];
+                        // 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 });
-                        // 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}`);
+                        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,
@@ -2333,7 +2467,7 @@ async function main() {
                             }));
                         }
                         else {
-                            print(w);
+                            print({ ...w, recoverable: !!importPassphrase, ...(importKeychainWarning ? { keychainWarning: importKeychainWarning } : {}) });
                         }
                         break;
                     }
@@ -2503,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,
@@ -2629,6 +2767,43 @@ async function main() {
                         }
                         break;
                     }
+                    case 'rekey': {
+                        const walletId = positional[0] || flags.id;
+                        if (!walletId)
+                            err('Wallet ID required: palmyr wallet rekey <WALLET_ID> --passphrase <p>', EXIT.BAD_INPUT);
+                        // New passphrase: flag → env → interactive prompt (TTY only).
+                        let newPass = flags.passphrase || process.env.PALMYR_WALLET_PASSPHRASE || undefined;
+                        if (!newPass) {
+                            if (!process.stdin.isTTY)
+                                err('--passphrase or PALMYR_WALLET_PASSPHRASE required (no TTY for interactive prompt)', EXIT.BAD_INPUT);
+                            const { promptNewPassphrase } = await import('./passphrase-prompt.js');
+                            newPass = await promptNewPassphrase();
+                        }
+                        // Current passphrase is only needed if the wallet was already
+                        // passphrase-sealed and the OS session secret is gone (rare —
+                        // typically the rekey runs on the original machine where the
+                        // session secret still resolves).
+                        const currentPass = flags['current-passphrase'] || process.env.PALMYR_WALLET_PASSPHRASE_CURRENT || undefined;
+                        const { rekeyWallet } = await import('./vault.js');
+                        let result;
+                        try {
+                            result = rekeyWallet(walletId, newPass, currentPass);
+                        }
+                        catch (e) {
+                            const code = e.message?.includes('SECURITY') ? EXIT.SECURITY : EXIT.GENERAL;
+                            err(e.message, code);
+                        }
+                        log(`wallet rekey: ${result.id} (${result.rotated ? 'rotated' : 'added'})`);
+                        if (!AGENT_MODE) {
+                            const verb = result.rotated ? 'Rotated' : 'Added';
+                            console.log(`\n  ${t.success}✔${t.reset} ${verb} passphrase fallback on ${t.accent}${result.name}${t.reset}`);
+                            console.log(`  ${t.muted}Wallet now decrypts with PALMYR_WALLET_PASSPHRASE on any machine (in addition to the OS keychain on this one).${t.reset}\n`);
+                        }
+                        else {
+                            print({ success: true, ...result });
+                        }
+                        break;
+                    }
                     case 'buy': {
                         const chain = (positional[0] || 'solana').toLowerCase();
                         if (chain !== 'solana' && chain !== 'base')
@@ -6524,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'),
@@ -6560,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 {