@palmyr/cli 1.8.2 → 1.8.5

package/dist/cli.js

@@ -209,26 +209,42 @@ 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: [
         { flag: '--name <name>', desc: 'Wallet name', hint: 'default: "My Wallet"' },
-        { flag: '--managed', desc: 'Create managed wallet with human oversight via passkey (single-create only)' },
         { flag: '--solana', desc: 'Materialize the Solana account only', hint: 'default: both chains' },
         { flag: '--base', desc: 'Materialize the Base/EVM account only', hint: 'pair with --solana for both (default)' },
         { 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: '--count <N>', desc: 'Bulk-create N wallets in one call (1-500)', hint: '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)' },
         { flag: '--name <name>', desc: 'Wallet name', hint: 'default: "Imported Wallet"' },
-        { flag: '--managed', desc: 'Import as managed wallet' },
         { 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)' },
@@ -431,6 +447,15 @@ const PHONE_HELP = {
         { flag: '(price)', desc: '$0.02 per call' },
         { flag: '(example)', desc: 'palmyr phone messages --id PN_abc' },
     ],
+    message: [
+        { flag: '--id <MESSAGE_ID>', desc: 'SMS message id (Telnyx-supplied; positional also accepted)' },
+        { flag: '(price)', desc: '$0.005 per readback — cheap so agents can poll until delivery_status is terminal' },
+        { flag: '(example)', desc: 'palmyr phone message <message-id-from-sms-response>' },
+    ],
+    'sms-status': [
+        { flag: '<message-id>', desc: 'Alias for `palmyr phone message <id>` — readback by id' },
+        { flag: '(price)', desc: '$0.005 per readback' },
+    ],
     calls: [
         { flag: '--id <PHONE_ID>', desc: 'Phone number id to list calls for (required; positional also accepted)' },
         { flag: '(price)', desc: '$0.02 per call' },
@@ -509,7 +534,7 @@ const EMAIL_HELP = {
     create: [
         { flag: '--name <name>', desc: 'Inbox name (required)' },
         { flag: '--domain <domain>', desc: 'Wallet-owned domain to host the inbox on (optional)', hint: 'default: Palmyr-hosted domain' },
-        { flag: '--wallet <id|name>', desc: 'Wallet to own the inbox (optional)' },
+        { flag: '--wallet <id|name|sol_pubkey>', desc: 'Inbox owner — vault id/name (resolves to its Solana address) or a raw Solana pubkey. Omit to use the paying wallet.', hint: 'E2E encryption is Ed25519, so the owner must always be a Solana address — Base addresses cannot own an inbox' },
         { flag: '(price)', desc: '$2.00 per inbox provisioned' },
         { flag: '(example)', desc: 'palmyr email create --name agent --domain example.com' },
     ],
@@ -715,6 +740,283 @@ const CHAT_HELP = {
         { flag: '(example)', desc: 'palmyr chat providers --capability web_search' },
     ],
 };
+// Help tables for the two social subsystems. Their presence is what gates
+// `--help` from dispatching paid actions — see the `case 'twitter'` and
+// `case 'tiktok'` blocks below. 1.8.3 had no entries here and the
+// `case 'buy'` arm immediately called the $5 paid endpoint when a user
+// (reasonably) ran `palmyr twitter buy --help`. Every entry below MUST
+// flag the price for paid subcommands so future readers can scan it.
+const TWITTER_HELP = {
+    import: [
+        { flag: '<username>', desc: 'Twitter handle to import' },
+        { flag: '--credentials-line "..."', desc: 'login:password:email:email_pw:totp_seed:ct0:auth_token format' },
+        { flag: '--username --password ...', desc: 'Alternative: individual flags for each field' },
+        { flag: '(price)', desc: 'Free — local vault only' },
+    ],
+    list: [
+        { flag: '--local', desc: 'Skip server check; show only locally-vaulted accounts' },
+        { flag: '(price)', desc: 'Free local listing + paid lookups when --local is omitted (~$0.001 to enumerate server-side access)' },
+    ],
+    info: [
+        { flag: '<username>', desc: 'Account to inspect' },
+        { flag: '(price)', desc: 'Free — local vault read' },
+    ],
+    rename: [
+        { flag: '<old>', desc: 'Current local handle' },
+        { flag: '--to <new>', desc: 'New handle (after a real-server rename)' },
+        { flag: '(price)', desc: 'Free — local-only metadata update' },
+    ],
+    remove: [
+        { flag: '<username>', desc: 'Account to remove' },
+        { flag: '--confirm', desc: 'Required — local delete is irreversible' },
+        { flag: '(price)', desc: 'Free — local vault only' },
+    ],
+    totp: [
+        { flag: '<username>', desc: 'Account whose current TOTP code to print' },
+        { flag: '(price)', desc: 'Free — local TOTP generation' },
+    ],
+    buy: [
+        { flag: '(no args)', desc: 'Purchase the oldest ready X account from the supplier pool' },
+        { flag: '(price)', desc: '$5 USDC — paid via x402. Account auto-imported into the local vault and session primed.' },
+        { flag: '(example)', desc: 'palmyr twitter buy' },
+    ],
+    login: [
+        { flag: '<username>', desc: 'Force a fresh server-side session (browser runtime)' },
+        { flag: '(price)', desc: '$0.005 USDC' },
+    ],
+    'manual-login': [
+        { flag: '<username>', desc: 'Open a remote browser session you sign in to manually' },
+        { flag: '(price)', desc: 'Variable — server-side browser session cost' },
+    ],
+    session: [
+        { flag: '<username>', desc: 'Inspect cached server-side session status' },
+        { flag: '(price)', desc: 'Free' },
+    ],
+    post: [
+        { flag: '<username>', desc: 'Account to post from' },
+        { flag: '--body "..."', desc: 'Tweet body (required)' },
+        { flag: '(price)', desc: '$0.001 USDC per post' },
+    ],
+    reply: [
+        { flag: '<username>', desc: 'Account to reply from' },
+        { flag: '--to <url>', desc: 'Tweet URL to reply to' },
+        { flag: '--body "..."', desc: 'Reply body' },
+        { flag: '(price)', desc: '$0.001 USDC' },
+    ],
+    like: [
+        { flag: '<username>', desc: 'Account doing the like' },
+        { flag: '--tweet <url>', desc: 'Tweet to like' },
+        { flag: '(price)', desc: '$0.001 USDC' },
+    ],
+    retweet: [
+        { flag: '<username>', desc: 'Account doing the retweet' },
+        { flag: '--tweet <url>', desc: 'Tweet to retweet' },
+        { flag: '(price)', desc: '$0.001 USDC' },
+    ],
+    follow: [
+        { flag: '<username>', desc: 'Account doing the follow' },
+        { flag: '--user @handle', desc: 'User to follow' },
+        { flag: '(price)', desc: '$0.001 USDC' },
+    ],
+    unfollow: [
+        { flag: '<username>', desc: 'Account doing the unfollow' },
+        { flag: '--user @handle', desc: 'User to unfollow' },
+        { flag: '(price)', desc: '$0.001 USDC' },
+    ],
+    delete: [
+        { flag: '<username>', desc: 'Account that posted the tweet' },
+        { flag: '--tweet <url>', desc: 'Tweet to delete' },
+        { flag: '(price)', desc: '$0.001 USDC' },
+    ],
+    'list-tweets': [
+        { flag: '<username>', desc: 'Account whose timeline to fetch' },
+        { flag: '(price)', desc: '$0.001 USDC' },
+    ],
+    bio: [
+        { flag: '<username>', desc: 'Account whose bio to update' },
+        { flag: '--text "..."', desc: 'New bio (<=160 chars)' },
+        { flag: '(price)', desc: '$0.001 USDC' },
+    ],
+    name: [
+        { flag: '<username>', desc: 'Account whose display name to update' },
+        { flag: '--display "..."', desc: 'New display name' },
+        { flag: '(price)', desc: '$0.001 USDC' },
+    ],
+    location: [
+        { flag: '<username>', desc: 'Account whose location to update' },
+        { flag: '--location "..."', desc: 'New location string' },
+        { flag: '(price)', desc: '$0.001 USDC' },
+    ],
+    website: [
+        { flag: '<username>', desc: 'Account whose profile website to update' },
+        { flag: '--url https://...', desc: 'New website URL' },
+        { flag: '(price)', desc: '$0.001 USDC' },
+    ],
+    pfp: [
+        { flag: '<username>', desc: 'Account whose avatar to update' },
+        { flag: '--file pic.png', desc: 'Image file (jpeg / png)' },
+        { flag: '(price)', desc: '$0.005 USDC' },
+    ],
+    banner: [
+        { flag: '<username>', desc: 'Account whose banner to update' },
+        { flag: '--file banner.png', desc: 'Image file' },
+        { flag: '(price)', desc: '$0.005 USDC' },
+    ],
+    username: [
+        { flag: '<username>', desc: 'Current account handle' },
+        { flag: '--to <new>', desc: 'New handle' },
+        { flag: '(price)', desc: '$0.005 USDC' },
+    ],
+    transfer: [
+        { flag: '<username>', desc: 'Account to transfer' },
+        { flag: '--to <wallet>', desc: 'Destination wallet address' },
+        { flag: '--confirm', desc: 'Required — rotates password, revokes other sessions' },
+        { flag: '(price)', desc: 'Free for vaulted accounts; ~$0.01 USDC to auto-register an imported-only account first' },
+    ],
+    share: [
+        { flag: '<username>', desc: 'Account to share' },
+        { flag: '--with <wallet>', desc: 'Wallet to grant access to' },
+        { flag: '(price)', desc: 'Free for shared access (no password rotation)' },
+    ],
+    unshare: [
+        { flag: '<username>', desc: 'Account to revoke share on' },
+        { flag: '--from <wallet>', desc: 'Wallet to revoke' },
+        { flag: '--rotate', desc: 'Also rotate password so cached cookies stop working' },
+        { flag: '(price)', desc: 'Free; --rotate runs async like transfer (~30-90s)' },
+    ],
+    claim: [
+        { flag: '(no args)', desc: 'Pull every server-side X account the wallet can access into the local vault' },
+        { flag: '(price)', desc: '~$0.001 USDC per account claimed (creds-decryption fee)' },
+    ],
+    // Server-backed account registration. Without these entries, `palmyr twitter
+    // register --help` (and friends) fell through to the top-level menu instead
+    // of explaining their flags. Subcommands listed in the parent switch must
+    // always have an entry here so the help guard fires before the case body.
+    thread: [
+        { flag: '<username>', desc: 'Account to post the thread from' },
+        { flag: '--texts \'["...","..."]\'', desc: 'JSON array of tweets (in order)' },
+        { flag: '--file path.json', desc: 'Alternative: read the JSON array from a file' },
+        { flag: '(price)', desc: '$0.005 USDC' },
+    ],
+    register: [
+        { flag: '<username>', desc: 'Account handle' },
+        { flag: '--password <pw>', desc: 'Required if the account is not already in the local vault' },
+        { flag: '--login --email --totp-seed --auth-token --ct0', desc: 'Optional; auto-pulled from local vault when not passed' },
+        { flag: '--country <CC>', desc: 'Optional residency hint stored alongside the encrypted credentials' },
+        { flag: '(price)', desc: 'Free — server tests login + encrypts creds at rest. Enables scheduling.' },
+    ],
+    unregister: [
+        { flag: '<username-or-id>', desc: 'Handle or 32-char hex account id' },
+        { flag: '(price)', desc: 'Free — wipes server-side credentials, account no longer schedulable' },
+    ],
+    registered: [
+        { flag: '(no args)', desc: 'List every server-registered X account this wallet owns' },
+        { flag: '(price)', desc: 'Free' },
+    ],
+    schedule: [
+        { flag: '<username>', desc: 'Account to post from (must be `register`-ed)' },
+        { flag: '--at "ISO8601"', desc: 'When to fire (e.g. --at "2026-05-15T14:00:00Z")' },
+        { flag: '--body "..."', desc: 'Text-only post' },
+        { flag: '--texts \'["..."]\' / --file path.json', desc: 'Thread' },
+        { flag: '--image / --video / --media-json', desc: 'Media attachments' },
+        { flag: '--community <id>', desc: 'Post into an X Community' },
+        { flag: '(price)', desc: '$0.001 USDC (text) or $0.005 USDC (thread / media) — paid up front' },
+    ],
+    queue: [
+        { flag: '--status pending|in_progress|completed|failed|cancelled', desc: 'Filter by status' },
+        { flag: '--from / --to "ISO8601"', desc: 'Filter by post-at window' },
+        { flag: '--account-id <id>', desc: 'Filter to one account' },
+        { flag: '--limit <n>', desc: 'Cap result count' },
+        { flag: '(price)', desc: 'Free' },
+    ],
+    cancel: [
+        { flag: '<schedule-id>', desc: 'Id from `palmyr twitter queue`' },
+        { flag: '(price)', desc: 'Free — only cancels pending posts; in-flight ones are already settled' },
+    ],
+    status: [
+        { flag: '<username>', desc: 'Account to inspect' },
+        { flag: '(price)', desc: 'Server-side liveness/shadow-ban check (not yet wired — see `palmyr twitter session` for cached login state)' },
+    ],
+    'pool-add': [
+        { flag: '--credentials-line "..."', desc: 'Single account creds (login:pw:email:email_pw[:2fa[:ct0:auth_token]])' },
+        { flag: '--file path.txt', desc: 'Bulk: one credentials-line per row (# = comment)' },
+        { flag: '--price <USDC>', desc: 'Required — what `twitter buy` will charge per account' },
+        { flag: '--country <CC>', desc: 'Optional metadata' },
+        { flag: '--age 1y|2y|3y|...', desc: 'Optional age category metadata' },
+        { flag: '(auth)', desc: 'Admin-signed call — requires PALMYR_ADMIN_KEY' },
+        { flag: '(price)', desc: 'Free — server-side seeding by pool operator' },
+    ],
+    'pool-status': [
+        { flag: '(no args)', desc: 'Available / sold / reserved counts in the X account pool' },
+        { flag: '(auth)', desc: 'Admin-signed call — requires PALMYR_ADMIN_KEY' },
+        { flag: '(price)', desc: 'Free' },
+    ],
+};
+const TIKTOK_HELP = {
+    import: [
+        { flag: '<username>', desc: 'TikTok handle to import' },
+        { flag: '--sessionid <s> --csrf <c> --webid <w>', desc: 'Cookies from a logged-in TikTok browser' },
+        { flag: '--credentials-line "..."', desc: 'Marketplace login:pw:email:email_pw format' },
+        { flag: '(price)', desc: 'Free — local vault only' },
+    ],
+    list: [
+        { flag: '(no args)', desc: 'List all local TikTok accounts' },
+        { flag: '(price)', desc: 'Free' },
+    ],
+    info: [{ flag: '<username>', desc: 'Show one account' }, { flag: '(price)', desc: 'Free' }],
+    rename: [
+        { flag: '<old>', desc: 'Current local handle' },
+        { flag: '--to <new>', desc: 'New handle' },
+        { flag: '(price)', desc: 'Free — local-only metadata update' },
+    ],
+    remove: [
+        { flag: '<username>', desc: 'Account to delete from local vault' },
+        { flag: '--confirm', desc: 'Required' },
+        { flag: '(price)', desc: 'Free' },
+    ],
+    totp: [{ flag: '<username>', desc: 'Print current TOTP code' }, { flag: '(price)', desc: 'Free' }],
+    login: [
+        { flag: '<username>', desc: 'Validate cookies and cache the session' },
+        { flag: '(price)', desc: '$0.005 USDC' },
+    ],
+    session: [{ flag: '<username>', desc: 'Check cached session' }, { flag: '(price)', desc: 'Free' }],
+    post: [
+        { flag: '<username>', desc: 'Account to post from' },
+        { flag: '--file video.mp4', desc: 'Video file' },
+        { flag: '--caption "..."', desc: 'Caption' },
+        { flag: '(price)', desc: '$0.001 USDC' },
+    ],
+    follow: [
+        { flag: '<username>', desc: 'Account doing the follow' },
+        { flag: '--user @handle', desc: 'User to follow' },
+        { flag: '(price)', desc: '$0.001 USDC' },
+    ],
+    like: [
+        { flag: '<username>', desc: 'Account doing the like' },
+        { flag: '--video <url>', desc: 'Video URL to like' },
+        { flag: '(price)', desc: '$0.001 USDC' },
+    ],
+    delete: [
+        { flag: '<username>', desc: 'Account that posted the video' },
+        { flag: '--video <url>', desc: 'Video to delete' },
+        { flag: '(price)', desc: '$0.001 USDC' },
+    ],
+    bio: [
+        { flag: '<username>', desc: 'Account whose bio to update' },
+        { flag: '--text "..."', desc: 'New bio (<=80 chars)' },
+        { flag: '(price)', desc: '$0.001 USDC' },
+    ],
+    name: [
+        { flag: '<username>', desc: 'Account whose display name to update' },
+        { flag: '--display "..."', desc: 'New display name (<=30 chars)' },
+        { flag: '(price)', desc: '$0.001 USDC' },
+    ],
+    pfp: [
+        { flag: '<username>', desc: 'Account whose avatar to update' },
+        { flag: '--file pic.png', desc: 'Image file' },
+        { flag: '(price)', desc: '$0.005 USDC' },
+    ],
+};
 /**
  * Render a per-command menu (no subcommand given). On a TTY → Ink MenuScreen
  * with the Palmyr aesthetic. In agent mode → flat JSON listing the available
@@ -1024,6 +1326,7 @@ async function main() {
                             { name: 'release', description: 'Release a phone number', hint: '--id PHONE_ID' },
                             { name: 'sms', description: 'Send an SMS', hint: '--id ID --to +1... --body "hi"' },
                             { name: 'messages', description: 'Read SMS messages received on a number', hint: '--id PHONE_ID' },
+                            { name: 'message', description: 'Get one SMS message by id (incl. delivery status)', hint: '--id MESSAGE_ID' },
                             { name: 'call', description: 'Place a voice call', hint: '--id ID --to +1... --tts "hello"' },
                             { name: 'calls', description: 'List calls placed/received on a number', hint: '--id PHONE_ID' },
                             { name: 'call-info', description: 'Get details on a single call', hint: '--call CALL_CONTROL_ID' },
@@ -1131,6 +1434,18 @@ async function main() {
                         const data = await ao.phoneMessages(id);
                         return print(data);
                     }
+                    case 'message':
+                    case 'sms-status': {
+                        // Per-message readback. Mirrors `phone call-info` for SMS:
+                        // the Telnyx webhook updates delivery_status on the row, and this
+                        // endpoint serves it back. Useful when the immediate sms response
+                        // is 'queued' and the caller wants to confirm delivery.
+                        const messageId = flags.id || flags.message || positional[0];
+                        if (!messageId)
+                            err('Usage: palmyr phone message <message-id>');
+                        const data = await ao.phoneMessage(messageId);
+                        return print(data);
+                    }
                     case 'calls': {
                         const id = flags.id || positional[0];
                         if (!id)
@@ -1269,13 +1584,58 @@ async function main() {
                 switch (subcommand) {
                     case 'create': {
                         const name = flags.name || positional[0];
-                        const wallet = flags.wallet;
+                        const walletInput = flags.wallet;
                         const domain = flags.domain;
                         if (!name)
                             err('--name required (e.g. palmyr email create --name hello [--domain example.com])');
+                        // --wallet accepts three forms: vault id, vault name, or a raw
+                        // Solana base58 pubkey. The server only accepts a Solana pubkey
+                        // (E2E encryption is Ed25519→X25519), so resolve id/name to a
+                        // pubkey here before the request. Raw pubkeys pass through.
+                        // Doing this resolution client-side also means a Base-paying user
+                        // doesn't need a Solana wallet — their vault already has one
+                        // (single mnemonic, both chains), and we can find it without
+                        // making the server reach back for client-side keys.
+                        let walletAddress;
+                        if (walletInput) {
+                            const looksLikeSolPubkey = /^[1-9A-HJ-NP-Za-km-z]{32,44}$/.test(walletInput);
+                            if (looksLikeSolPubkey) {
+                                walletAddress = walletInput;
+                            }
+                            else {
+                                const { listVaultWallets } = await import('./vault.js');
+                                const wallets = listVaultWallets();
+                                const match = wallets.find(w => w.id === walletInput || w.name === walletInput);
+                                if (!match)
+                                    err(`--wallet "${walletInput}" did not match any vault id, name, or look like a Solana pubkey`);
+                                if (!match.solanaAddress)
+                                    err(`Wallet "${walletInput}" has no Solana address — email inboxes require one (E2E uses Ed25519). Re-create with: palmyr wallet create`);
+                                walletAddress = match.solanaAddress;
+                            }
+                        }
+                        else {
+                            // No --wallet: the server would normally default the inbox owner
+                            // to the x402 payer. That works for Solana-paid calls but
+                            // 400s on Base because the payer is an EVM address. Auto-fill
+                            // the *paying wallet's* Solana address here so a single
+                            // mnemonic-derived vault wallet works on either pay chain.
+                            const cfg = loadConfig();
+                            const payChain = (cfg.defaultPayChain || 'solana');
+                            if (payChain === 'base') {
+                                const { listVaultWallets } = await import('./vault.js');
+                                const wallets = listVaultWallets();
+                                const targetId = cfg.defaultPayWalletId || process.env.PALMYR_PAY_WALLET;
+                                const paying = (targetId && wallets.find(w => w.id === targetId)) || wallets.find(w => w.evmAddress && w.solanaAddress);
+                                if (paying?.solanaAddress)
+                                    walletAddress = paying.solanaAddress;
+                                // If no Solana address is reachable, fall through and let the
+                                // server return its actionable 400 — silent failure would be
+                                // worse than a clear error.
+                            }
+                        }
                         const spin = new Spinner();
                         spin.start('Creating inbox...');
-                        const data = await ao.emailCreate(name, wallet, domain);
+                        const data = await ao.emailCreate(name, walletAddress, domain);
                         spin.stop('Inbox created', true);
                         return print(data);
                     }
@@ -1571,6 +1931,26 @@ async function main() {
                         const localKeyPath = generatedKeyMeta?.privateKeyPath
                             || (pubkeyFile ? pubkeyFile.replace(/\.pub$/, '').replace('~', homedir()) : undefined)
                             || (explicitKeyPath ? explicitKeyPath.replace('~', homedir()) : undefined);
+                        // --ssh-key <id> uploads a server-side key but doesn't tell us where
+                        // the matching private key lives on this machine. Without
+                        // --key-path, the SSH readiness gate later silently skips and the
+                        // deploy reports `ssh: skipped` while still marking the server as
+                        // "ready" — a real foot-gun (dogfood report 2026-05-25 hit this
+                        // exact path). Be loud about it now, before anyone pays.
+                        if (sshKeyIds && !localKeyPath) {
+                            const msg = 'Warning: --ssh-key <id> uploaded the public key server-side, ' +
+                                'but no matching private key was passed to this CLI. ' +
+                                'SSH readiness cannot be verified locally — `compute wait` and the ' +
+                                'inline --wait check will skip the SSH gate. Pass ' +
+                                '`--key-path /path/to/private_key` (or `--private-key`) to ' +
+                                'enable the verification.';
+                            if (AGENT_MODE) {
+                                process.stderr.write(JSON.stringify({ event: 'warning', code: 'ssh_key_no_local_key', message: msg }) + '\n');
+                            }
+                            else {
+                                process.stderr.write(`\n${msg}\n\n`);
+                            }
+                        }
                         // Progress events to stderr — default ON in agent mode so a
                         // long deploy isn't a 10-minute silence. Pass --no-progress to
                         // opt out. Stdout still gets one final JSON object, so jq
@@ -2151,7 +2531,7 @@ async function main() {
                         subtitle: 'Non-custodial HD wallet',
                         footerLeft: 'Solana + Base wallet operations',
                         commands: [
-                            { name: 'create', description: 'Create one or many wallets', hint: '[--tag X --count 100] [--solana|--base] [--managed]' },
+                            { name: 'create', description: 'Create one or many wallets', hint: '[--tag X --count 100] [--solana|--base]' },
                             { name: 'import', description: 'Import from mnemonic', hint: '--mnemonic "..." [--tag X]' },
                             { name: 'list', description: 'List all wallets', hint: '[--tag <name>]' },
                             { name: 'info', description: 'Wallet details', hint: 'WALLET_ID' },
@@ -2165,7 +2545,6 @@ async function main() {
                             { 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' },
-                            { name: 'request-approval', description: 'Request human approval (managed)', hint: 'WALLET_ID --action limits --daily 100' },
                             { name: 'buy', description: 'Open a trading position', hint: 'solana <CA> --amount 0.5sol --thesis "..."' },
                             { name: 'cohort', description: 'Split a buy across N derived wallets with jitter (Phase 4c)', hint: 'buy <CHAIN> <CA> --total ... --split N' },
                             { name: 'template', description: 'Manage YAML strategy templates', hint: 'list | show <name> | path <name> | delete <name>' },
@@ -2210,10 +2589,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 +2633,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 +2678,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 +2691,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 +2754,7 @@ async function main() {
                             }
                         }
                         else {
-                            print({ ...w, setupLink });
+                            print({ ...w, setupLink, recoverable: !!passphrase, ...(keychainStoreWarning ? { keychainWarning: keychainStoreWarning } : {}) });
                         }
                         break;
                     }
@@ -2328,13 +2770,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 +2828,7 @@ async function main() {
                             }));
                         }
                         else {
-                            print(w);
+                            print({ ...w, recoverable: !!importPassphrase, ...(importKeychainWarning ? { keychainWarning: importKeychainWarning } : {}) });
                         }
                         break;
                     }
@@ -2517,9 +2998,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,
@@ -4854,7 +5339,12 @@ async function main() {
                     log(`auto-imported @${username} from server (${sourceLabel} → local vault)`);
                     return summary;
                 };
-                if (!subcommand) {
+                // Help guard. `palmyr twitter buy --help` MUST never dispatch to the
+                // paid `case 'buy'` below — 1.8.3 had no guard here and a real user
+                // got charged $5 for a help command. Falls back to the top-level menu
+                // when the subcommand has no per-subcommand help entry, so even an
+                // unrecognized `palmyr twitter <whatever> --help` is safe to run.
+                if (!subcommand || (flags.help && !TWITTER_HELP[subcommand])) {
                     showMenu({
                         command: 'twitter',
                         title: 'twitter',
@@ -4870,7 +5360,10 @@ async function main() {
                             { name: 'buy', description: 'Purchase an aged account (requires server supplier config)', hint: '--age 1y --country US' },
                             { name: 'login', description: 'Force a fresh server-side session (requires browser runtime)', hint: '<username>' },
                             { name: 'post', description: 'Post a tweet (requires server browser runtime)', hint: '<username> --body "..."' },
-                            { name: 'status', description: 'Check if the account is alive / shadow-banned', hint: '<username>' },
+                            // `status` is not wired yet (Phase 3). Hidden from this menu so
+                            // users don't try a command that will only error; `session`
+                            // covers the most useful subset (cached server-side login state).
+                            { name: 'session', description: 'Inspect cached server-side session for an account', hint: '<username>' },
                             { name: 'transfer', description: 'Hand an account to another wallet (rotates password; auto-registers if needed)', hint: '<username> --to <wallet> --confirm' },
                             { name: 'share', description: 'Grant another wallet shared access', hint: '<username> --with <wallet>' },
                             { name: 'unshare', description: 'Revoke a wallet’s shared access', hint: '<username> --from <wallet> [--rotate]' },
@@ -4880,6 +5373,10 @@ async function main() {
                     });
                     return;
                 }
+                if (flags.help && subcommand && TWITTER_HELP[subcommand]) {
+                    subcommandHelp('twitter', subcommand, TWITTER_HELP[subcommand]);
+                    return;
+                }
                 switch (subcommand) {
                     case 'import': {
                         // Option 1: --credentials-line "login:password:email:email_pw:2fa:ct0:auth_token"
@@ -5817,14 +6314,22 @@ async function main() {
                         return print(data);
                     }
                     case 'status': {
-                        err(`twitter status: not wired yet. Phase 3 will add it.`, EXIT.GENERAL);
+                        // `twitter status` was meant to check live shadow-ban / suspension
+                        // state via a server-side probe. That's a Phase 3 build (needs a
+                        // browser runtime on the server to render the profile). Until
+                        // then, point users at `session` for the cached login state and
+                        // `info` for vault metadata — together they cover the practical
+                        // "is this account still usable from the agent's side" question.
+                        err(`twitter status: not wired yet (Phase 3). Closest equivalents available today: ` +
+                            `\`palmyr twitter session <username>\` (cached server-side login validity) and ` +
+                            `\`palmyr twitter info <username>\` (local vault record).`, EXIT.GENERAL);
                     }
                     case 'transfer': {
                         // Hand the X account to another wallet. End-to-end one-command:
                         //   1. If the account is only in the local vault, auto-register it
                         //      with the server (uploads encrypted creds; $0.01 USDC).
                         //   2. Server rotates the password and revokes other sessions
-                        //      ($0.0001 USDC ownership proof).
+                        //      ($0.01 USDC ownership proof).
                         //   3. Atomically flips ownership in the DB.
                         // Receiver picks up the rotated credentials via `palmyr twitter
                         // list` (which now surfaces server-side accounts) and/or `claim`.
@@ -6196,7 +6701,9 @@ async function main() {
             case 'tiktok': {
                 const sv = await import('./social-vault.js');
                 const platform = 'tiktok';
-                if (!subcommand) {
+                // Same help guard as `twitter` — prevents `--help` from dispatching
+                // a paid subcommand. Same bug class lived here too in 1.8.3.
+                if (!subcommand || (flags.help && !TIKTOK_HELP[subcommand])) {
                     showMenu({
                         command: 'tiktok',
                         title: 'tiktok',
@@ -6223,6 +6730,10 @@ async function main() {
                     });
                     return;
                 }
+                if (flags.help && subcommand && TIKTOK_HELP[subcommand]) {
+                    subcommandHelp('tiktok', subcommand, TIKTOK_HELP[subcommand]);
+                    return;
+                }
                 switch (subcommand) {
                     case 'import': {
                         // Two formats:
@@ -6575,12 +7086,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 +7128,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 {