@blockrun/franklin 3.6.24 → 3.7.1

package/dist/agent/context.js

@@ -38,6 +38,7 @@ You are an interactive agent — not a chatbot. Use the tools available to you t
 - **Search strategy**: Glob/Grep for directed searches (known file/symbol). Use Agent for open-ended exploration that may require multiple rounds.
 - **Batch bash**: chain sequential shell commands with && in a single call. Only split when you need intermediate output.
 - **AskUser discipline**: Only use AskUser when you need explicit confirmation for a destructive action (deleting files, dropping databases). NEVER use AskUser to ask what the user wants — just answer their message directly. If the request is vague, make a reasonable assumption and proceed.
+- **Greetings**: When the user sends only a greeting or filler ("hi", "hello", "hey", "ok", "thanks", "yo"), reply with ONE short plain-text sentence (e.g. "Hi — what do you want to work on?"). Do NOT call AskUser. Do NOT assume a marketing/trading/coding task. Do NOT invoke any tools.
 - Never write to /etc, /usr, ~/.ssh, ~/.aws. Don't commit secrets.`;
 }
 function getCodeStyleSection() {

package/dist/agent/loop.js

@@ -20,7 +20,7 @@ import { routeRequest, parseRoutingProfile } from '../router/index.js';
 import { recordOutcome } from '../router/local-elo.js';
 import { shouldPlan, getPlanningPrompt, getExecutorModel, isExecutorStuck, toolCallSignature } from './planner.js';
 import { shouldVerify, runVerification } from './verification.js';
-import { createSessionId, appendToSession, updateSessionMeta, pruneOldSessions, } from '../session/storage.js';
+import { createSessionId, appendToSession, updateSessionMeta, pruneOldSessions, loadSessionHistory, loadSessionMeta, } from '../session/storage.js';
 /**
  * Atomically replace all elements in a history array.
  * Safer than `history.length = 0; history.push(...)` because if push throws
@@ -226,9 +226,22 @@ export async function interactiveSession(config, getUserInput, onEvent, onAbortR
     // will keep failing until the user adds funds. Map stores failure timestamp for future TTL.
     const paymentFailedModels = new Map(); // model → timestamp
     // Plan-then-execute: session-level disable flag lives on config (set by /noplan command)
-    // Session persistence
-    const sessionId = createSessionId();
+    // Session persistence — reuse existing session ID when resuming, else create new
+    const sessionId = config.resumeSessionId || createSessionId();
     let turnCount = 0;
+    // Resume: hydrate history from the saved JSONL transcript.
+    // Sanitize to drop any orphaned tool_use / tool_result pairs from a crash.
+    if (config.resumeSessionId) {
+        const prior = loadSessionHistory(config.resumeSessionId);
+        if (prior.length > 0) {
+            const sanitized = sanitizeHistory(prior);
+            replaceHistory(history, sanitized);
+            const meta = loadSessionMeta(config.resumeSessionId);
+            if (meta) {
+                turnCount = meta.turnCount ?? 0;
+            }
+        }
+    }
     let tokenBudgetWarned = false; // Emit token budget warning at most once per session
     let lastSessionActivity = Date.now();
     let lastRoutedModel = ''; // last model chosen by router (for local elo)

package/dist/agent/types.d.ts

@@ -146,4 +146,6 @@ export interface AgentConfig {
     onModelChange?: (model: string, reason?: 'user' | 'system') => void;
     /** The user's intended model — updated by /model command, used for turn recovery */
     baseModel?: string;
+    /** Resume an existing session by ID — loads prior history and keeps appending to the same JSONL */
+    resumeSessionId?: string;
 }

package/dist/commands/panel.js

@@ -22,7 +22,9 @@ export async function panelCommand(options) {
             }
             process.exit(1);
         });
-        server.listen(port, () => {
+        // Bind to loopback only — the panel exposes wallet secrets on /api/wallet/secret
+        // and a write-capable /api/wallet/import. Never expose these on a LAN.
+        server.listen(port, '127.0.0.1', () => {
             console.log('');
             console.log(chalk.bold('  Franklin Panel'));
             console.log(chalk.dim(`  http://localhost:${port}`) +

package/dist/commands/start.d.ts

@@ -3,6 +3,10 @@ interface StartOptions {
     debug?: boolean;
     trust?: boolean;
     version?: string;
+    /** Resume: explicit session ID, or true for "most recent in cwd", or 'picker' to prompt */
+    resume?: string | boolean | 'picker';
+    /** Continue: resume most recent session matching the current working directory */
+    continue?: boolean;
 }
 export declare function startCommand(options: StartOptions): Promise<void>;
 export {};

package/dist/commands/start.js

@@ -1,7 +1,8 @@
 import chalk from 'chalk';
 import { getOrCreateWallet, getOrCreateSolanaWallet } from '@blockrun/llm';
 import { loadChain, API_URLS } from '../config.js';
-import { flushStats } from '../stats/tracker.js';
+import { flushStats, loadStats } from '../stats/tracker.js';
+import { OPUS_PRICING } from '../pricing.js';
 import { loadConfig } from './config.js';
 import { printBanner } from '../banner.js';
 import { assembleInstructions } from '../agent/context.js';
@@ -14,16 +15,58 @@ import { loadMcpConfig } from '../mcp/config.js';
 import { connectMcpServers, disconnectMcpServers } from '../mcp/client.js';
 export async function startCommand(options) {
     const version = options.version ?? '1.0.0';
+    // Early-validate explicit resume ID so a typo fails fast — before wallet
+    // creation, banner, or MCP connection. Also resolve unambiguous prefixes so
+    // users don't need to paste the full 40-char session ID.
+    if (typeof options.resume === 'string' && options.resume !== 'picker') {
+        const { resolveSessionIdInput } = await import('../ui/session-picker.js');
+        const resolved = resolveSessionIdInput(options.resume);
+        if (!resolved.ok) {
+            if (resolved.error === 'ambiguous') {
+                console.error(chalk.red(`Ambiguous session prefix: ${options.resume}`));
+                console.error(chalk.dim('Matches:'));
+                for (const c of resolved.candidates) {
+                    console.error(chalk.dim(`  ${c.id}  (${new Date(c.updatedAt).toLocaleString()})`));
+                }
+            }
+            else {
+                console.error(chalk.red(`No session found with id: ${options.resume}`));
+                console.error(chalk.dim('Run `franklin resume` to pick from a list.'));
+            }
+            process.exit(1);
+        }
+        options.resume = resolved.id;
+    }
+    // Resolve --continue early so the session's model can be inherited during
+    // model resolution below. If no matching session is found, we fall through
+    // to a fresh session (message is printed later, near the resume banner).
+    let continueResolvedId;
+    if (options.continue && !options.resume) {
+        const { findLatestSessionForDir } = await import('../ui/session-picker.js');
+        continueResolvedId = findLatestSessionForDir(process.cwd())?.id;
+    }
     const chain = loadChain();
     const apiUrl = API_URLS[chain];
     const config = loadConfig();
-    // Resolve model — default to FREE (nemotron) so users don't get surprise charges.
-    // Paid models (glm-5.1, sonnet, opus, etc.) must be opted in with --model or /model.
+    // Resolve model. Priority: explicit --model > resumed session's model > user
+    // config default > FREE default. Resuming restores the same model the user was
+    // on last time so the environment feels continuous. Explicit --model still wins
+    // so users can cheaply retry a paid session on a free model.
     let model;
     const configModel = config['default-model'];
+    let resumedSessionModel;
+    const modelSourceId = (typeof options.resume === 'string' && options.resume !== 'picker') ? options.resume
+        : continueResolvedId;
+    if (modelSourceId) {
+        const { loadSessionMeta } = await import('../session/storage.js');
+        resumedSessionModel = loadSessionMeta(modelSourceId)?.model;
+    }
     if (options.model) {
         model = resolveModel(options.model);
     }
+    else if (resumedSessionModel && resumedSessionModel !== 'unknown') {
+        model = resumedSessionModel;
+    }
     else if (configModel) {
         model = configModel;
     }
@@ -72,11 +115,17 @@ export async function startCommand(options) {
     }
     printBanner(version);
     const workDir = process.cwd();
+    // Auto-start panel in background unless explicitly disabled.
+    // Binds loopback-only (wallet secrets on /api/wallet/secret — never expose on LAN).
+    let panelUrl;
+    if (process.env.FRANKLIN_PANEL_AUTOSTART !== '0') {
+        panelUrl = await startPanelBackground(3100);
+    }
     // Session info — aligned, minimal. Model + balance live in the input bar below.
     // Full wallet address is shown so the user can copy-paste it to fund the wallet.
     console.log(chalk.dim('  Wallet:    ') + (walletAddress || chalk.yellow('not set')));
     console.log(chalk.dim('  Dir:       ') + workDir);
-    console.log(chalk.dim('  Dashboard: ') + chalk.cyan('franklin panel') + chalk.dim(' → http://localhost:3100'));
+    console.log(chalk.dim('  Dashboard: ') + (panelUrl ? chalk.cyan(panelUrl) : chalk.cyan('franklin panel') + chalk.dim(' → http://localhost:3100')));
     console.log(chalk.dim('  Help:      ') + chalk.cyan('/help'));
     console.log('');
     // Balance fetcher — used at startup and after each turn
@@ -145,6 +194,41 @@ export async function startCommand(options) {
             console.error(`[validate] ${issue.severity}: ${issue.toolName} — ${issue.issue}`);
         }
     }
+    // Resolve resume target, if requested.
+    let resumeSessionId;
+    if (options.resume || options.continue) {
+        const { pickSession } = await import('../ui/session-picker.js');
+        const { loadSessionMeta, loadSessionHistory } = await import('../session/storage.js');
+        if (typeof options.resume === 'string' && options.resume !== 'picker') {
+            // Explicit ID — already validated above
+            resumeSessionId = options.resume;
+        }
+        else if (options.continue) {
+            if (!continueResolvedId) {
+                console.error(chalk.yellow(`  No prior session found in ${workDir} — starting a new one.`));
+            }
+            else {
+                resumeSessionId = continueResolvedId;
+            }
+        }
+        else {
+            // --resume with no value → interactive picker
+            const picked = await pickSession({ workDir });
+            if (!picked) {
+                console.error(chalk.dim('  No session picked — starting a new one.'));
+            }
+            else {
+                resumeSessionId = picked;
+            }
+        }
+        if (resumeSessionId) {
+            const meta = loadSessionMeta(resumeSessionId);
+            const msgs = loadSessionHistory(resumeSessionId).length;
+            const when = meta ? new Date(meta.updatedAt).toLocaleString() : 'unknown';
+            console.log(chalk.green(`  Resuming session ${resumeSessionId.slice(0, 24)}…`));
+            console.log(chalk.dim(`  ${msgs} messages · last active ${when}\n`));
+        }
+    }
     // Agent config
     const agentConfig = {
         model,
@@ -158,6 +242,7 @@ export async function startCommand(options) {
         // Interactive TTY = default mode (prompts for Bash/Write/Edit).
         permissionMode: (options.trust || !process.stdin.isTTY) ? 'trust' : 'default',
         debug: options.debug,
+        resumeSessionId,
     };
     // Bootstrap learnings from Claude Code config on first run (async, non-blocking)
     Promise.all([
@@ -179,6 +264,7 @@ export async function startCommand(options) {
 }
 // ─── Ink UI (interactive terminal) ─────────────────────────────────────────
 async function runWithInkUI(agentConfig, model, workDir, version, walletInfo, onBalanceReady, fetchBalance) {
+    const startSnapshot = snapshotStats();
     const ui = launchInkUI({
         model,
         workDir,
@@ -246,15 +332,17 @@ async function runWithInkUI(agentConfig, model, workDir, version, walletInfo, on
         catch { /* extraction is best-effort */ }
     }
     await disconnectMcpServers();
-    // Session summary — show cost and usage before goodbye
+    // Session summary — delta vs. snapshot at session start
     try {
-        const { getStatsSummary } = await import('../stats/tracker.js');
-        const { stats, saved } = getStatsSummary();
-        if (stats.totalRequests > 0) {
-            const cost = stats.totalCostUsd.toFixed(4);
-            const savedStr = saved > 0.001 ? ` · saved $${saved.toFixed(2)} vs Opus` : '';
-            const tokens = `${(stats.totalInputTokens / 1000).toFixed(0)}k in / ${(stats.totalOutputTokens / 1000).toFixed(0)}k out`;
-            console.log(chalk.dim(`\n  Session: ${stats.totalRequests} requests · $${cost} USDC${savedStr} · ${tokens}`));
+        const delta = statsDelta(startSnapshot);
+        if (delta.requests > 0) {
+            const cost = delta.cost.toFixed(4);
+            const savedStr = delta.saved > 0.001 ? ` · saved $${delta.saved.toFixed(2)} vs Opus` : '';
+            const tokens = `${(delta.inputTokens / 1000).toFixed(0)}k in / ${(delta.outputTokens / 1000).toFixed(0)}k out`;
+            console.log(chalk.dim(`\n  Session: ${delta.requests} requests · $${cost} USDC${savedStr} · ${tokens}`));
+        }
+        else {
+            console.log(chalk.dim('\n  Session: 0 requests · no spend'));
         }
     }
     catch { /* stats unavailable */ }
@@ -265,6 +353,7 @@ async function runWithBasicUI(agentConfig, model, workDir) {
     const { TerminalUI } = await import('../ui/terminal.js');
     const ui = new TerminalUI();
     ui.printWelcome(model, workDir);
+    const startSnapshot = snapshotStats();
     let lastTerminalPrompt = '';
     try {
         await interactiveSession(agentConfig, async () => {
@@ -312,19 +401,69 @@ async function runWithBasicUI(agentConfig, model, workDir) {
     }
     // Session summary for piped mode
     try {
-        const { getStatsSummary } = await import('../stats/tracker.js');
-        const { stats, saved } = getStatsSummary();
-        if (stats.totalRequests > 0) {
-            const cost = stats.totalCostUsd.toFixed(4);
-            const savedStr = saved > 0.001 ? ` · saved $${saved.toFixed(2)} vs Opus` : '';
-            const tokens = `${(stats.totalInputTokens / 1000).toFixed(0)}k in / ${(stats.totalOutputTokens / 1000).toFixed(0)}k out`;
-            console.error(`Session: ${stats.totalRequests} requests · $${cost} USDC${savedStr} · ${tokens}`);
+        const delta = statsDelta(startSnapshot);
+        if (delta.requests > 0) {
+            const cost = delta.cost.toFixed(4);
+            const savedStr = delta.saved > 0.001 ? ` · saved $${delta.saved.toFixed(2)} vs Opus` : '';
+            const tokens = `${(delta.inputTokens / 1000).toFixed(0)}k in / ${(delta.outputTokens / 1000).toFixed(0)}k out`;
+            console.error(`Session: ${delta.requests} requests · $${cost} USDC${savedStr} · ${tokens}`);
         }
     }
     catch { /* stats unavailable */ }
     ui.printGoodbye();
     flushStats();
 }
+// ─── Panel auto-start ──────────────────────────────────────────────────────
+async function startPanelBackground(startPort) {
+    const MAX_ATTEMPTS = 20;
+    try {
+        const { createPanelServer } = await import('../panel/server.js');
+        return await new Promise((resolve) => {
+            const tryListen = (port, attempt) => {
+                const server = createPanelServer(port);
+                server.on('error', (err) => {
+                    if (err.code === 'EADDRINUSE' && attempt < MAX_ATTEMPTS) {
+                        tryListen(port + 1, attempt + 1);
+                        return;
+                    }
+                    resolve(undefined);
+                });
+                server.listen(port, '127.0.0.1', () => {
+                    server.unref?.();
+                    resolve(`http://localhost:${port}`);
+                });
+            };
+            tryListen(startPort, 0);
+        });
+    }
+    catch {
+        return undefined;
+    }
+}
+function snapshotStats() {
+    try {
+        const s = loadStats();
+        return {
+            requests: s.totalRequests,
+            cost: s.totalCostUsd,
+            inputTokens: s.totalInputTokens,
+            outputTokens: s.totalOutputTokens,
+        };
+    }
+    catch {
+        return { requests: 0, cost: 0, inputTokens: 0, outputTokens: 0 };
+    }
+}
+function statsDelta(before) {
+    const now = loadStats();
+    const requests = Math.max(0, now.totalRequests - before.requests);
+    const cost = Math.max(0, now.totalCostUsd - before.cost);
+    const inputTokens = Math.max(0, now.totalInputTokens - before.inputTokens);
+    const outputTokens = Math.max(0, now.totalOutputTokens - before.outputTokens);
+    const opusCost = (inputTokens / 1_000_000) * OPUS_PRICING.input +
+        (outputTokens / 1_000_000) * OPUS_PRICING.output;
+    return { requests, cost, inputTokens, outputTokens, saved: Math.max(0, opusCost - cost) };
+}
 async function handleSlashCommand(cmd, config, ui) {
     const parts = cmd.trim().split(/\s+/);
     const command = parts[0].toLowerCase();

package/dist/index.js

@@ -41,7 +41,16 @@ program
     .option('-m, --model <model>', 'Model to use (e.g. openai/gpt-5.4, anthropic/claude-sonnet-4.6). Default from config or claude-sonnet-4.6')
     .option('--debug', 'Enable debug logging')
     .option('--trust', 'Trust mode — skip permission prompts for all tools')
+    .option('-r, --resume [sessionId]', 'Resume a session by ID (or show picker if omitted)')
+    .option('-c, --continue', 'Continue the most recent session in this directory')
     .action((options) => startCommand({ ...options, version }));
+program
+    .command('resume [sessionId]')
+    .description('Resume a saved Franklin session (alias for: franklin --resume)')
+    .option('-m, --model <model>', 'Override the model for this session')
+    .option('--debug', 'Enable debug logging')
+    .option('--trust', 'Trust mode — skip permission prompts for all tools')
+    .action((sessionId, options) => startCommand({ ...options, version, resume: sessionId ?? 'picker' }));
 program
     .command('proxy')
     .description('Run payment proxy for Claude Code or other tools')
@@ -176,13 +185,41 @@ const args = process.argv.slice(2);
 const firstArg = args[0];
 const HELP_FLAGS = new Set(['-h', '--help']);
 const VERSION_FLAGS = new Set(['-V', '--version']);
-const START_ONLY_FLAGS = new Set(['--trust', '--debug', '-m', '--model']);
+const START_ONLY_FLAGS = new Set(['--trust', '--debug', '-m', '--model', '-r', '--resume', '-c', '--continue']);
 function hasAnyFlag(argv, flags) {
     return argv.some(arg => flags.has(arg));
 }
 function hasStartOnlyFlag(argv) {
     return argv.some(arg => START_ONLY_FLAGS.has(arg));
 }
+function parseStartFlags(argv, startIdx = 0) {
+    const opts = { version };
+    for (let i = startIdx; i < argv.length; i++) {
+        const arg = argv[i];
+        if (arg === '--trust')
+            opts.trust = true;
+        else if (arg === '--debug')
+            opts.debug = true;
+        else if ((arg === '-m' || arg === '--model') && argv[i + 1]) {
+            opts.model = argv[++i];
+        }
+        else if (arg === '-c' || arg === '--continue') {
+            opts.continue = true;
+        }
+        else if (arg === '-r' || arg === '--resume') {
+            // --resume may take an optional session id — look at next arg
+            const next = argv[i + 1];
+            if (next && !next.startsWith('-')) {
+                opts.resume = next;
+                i++;
+            }
+            else {
+                opts.resume = 'picker';
+            }
+        }
+    }
+    return opts;
+}
 // Handle chain shortcuts: `runcode solana` or `runcode base`
 if (firstArg === 'solana' || firstArg === 'base') {
     if (hasAnyFlag(args, HELP_FLAGS)) {
@@ -194,16 +231,7 @@ if (firstArg === 'solana' || firstArg === 'base') {
     }
     const { saveChain } = await import('./config.js');
     saveChain(firstArg);
-    const startOpts = { version };
-    for (let i = 1; i < args.length; i++) {
-        if (args[i] === '--trust')
-            startOpts.trust = true;
-        else if (args[i] === '--debug')
-            startOpts.debug = true;
-        else if ((args[i] === '-m' || args[i] === '--model') && args[i + 1]) {
-            startOpts.model = args[++i];
-        }
-    }
+    const startOpts = parseStartFlags(args, 1);
     await startCommand(startOpts);
     process.exit(0);
 }
@@ -219,16 +247,7 @@ else if (!firstArg || firstArg.startsWith('-')) {
         program.parse();
     }
     // No subcommand or only flags — treat as 'start' with flags
-    const startOpts = { version };
-    for (let i = 0; i < args.length; i++) {
-        if (args[i] === '--trust')
-            startOpts.trust = true;
-        else if (args[i] === '--debug')
-            startOpts.debug = true;
-        else if ((args[i] === '-m' || args[i] === '--model') && args[i + 1]) {
-            startOpts.model = args[++i];
-        }
-    }
+    const startOpts = parseStartFlags(args, 0);
     await startCommand(startOpts);
     process.exit(0);
 }

package/dist/panel/html.js

@@ -273,6 +273,63 @@ a:hover { text-decoration:underline; }
 .tab.active { display:block; }
 .empty { color:var(--text-dim); text-align:center; padding:56px 24px; font-size:13px; }
 
+/* ── Wallet page ── */
+.wallet-grid { display:grid; grid-template-columns:1.1fr 1fr; gap:14px; }
+.wallet-grid .card { display:flex; flex-direction:column; gap:10px; }
+.wallet-receive { grid-row:span 2; align-items:flex-start; }
+.wallet-address-row { display:flex; align-items:center; gap:8px; flex-wrap:wrap; width:100%; }
+.wallet-chain-pill {
+  font-size:10px; font-weight:700; letter-spacing:0.8px; text-transform:uppercase;
+  padding:3px 8px; border-radius:6px; background:oklch(0.68 0.16 260 / 18%); color:var(--brand);
+}
+.wallet-address {
+  font-family:var(--mono); font-size:12px; color:var(--text);
+  background:oklch(0 0 0 / 35%); padding:8px 10px; border-radius:8px;
+  border:1px solid var(--border); word-break:break-all; flex:1; min-width:0;
+}
+.wallet-balance-big { font-family:var(--mono); font-size:28px; font-weight:700; color:var(--gold); letter-spacing:-0.02em; }
+.wallet-qr {
+  background:#fff; padding:14px; border-radius:12px; display:inline-block;
+  box-shadow:0 10px 40px oklch(0 0 0 / 35%); min-width:220px; min-height:220px;
+}
+.wallet-qr svg { display:block; width:200px; height:200px; }
+.wallet-hint { font-size:12.5px; color:var(--text-muted); line-height:1.55; }
+.wallet-hint code { font-family:var(--mono); font-size:11.5px; color:var(--text); background:oklch(0 0 0 / 30%); padding:1px 5px; border-radius:4px; }
+.wallet-secret { position:relative; }
+.wallet-secret .wallet-key-value {
+  font-family:var(--mono); font-size:11.5px; color:var(--text);
+  background:oklch(0 0 0 / 35%); padding:10px; border-radius:8px;
+  border:1px solid var(--border-strong); word-break:break-all; display:block;
+  user-select:all;
+}
+.wallet-secret-actions { display:flex; gap:8px; margin-top:8px; }
+.wallet-import-input {
+  width:100%; min-height:70px; background:oklch(0 0 0 / 35%); color:var(--text);
+  border:1px solid var(--border); border-radius:8px; padding:10px;
+  font-family:var(--mono); font-size:12px; resize:vertical;
+}
+.wallet-import-input:focus { border-color:var(--brand); outline:none; box-shadow:0 0 0 3px oklch(0.68 0.16 260 / 14%); }
+.wallet-actions { display:flex; align-items:center; gap:10px; margin-top:4px; }
+.wallet-import-status { font-size:12px; color:var(--text-muted); }
+.wallet-import-status.ok { color:var(--success); }
+.wallet-import-status.err { color:var(--danger); }
+.wallet-steps { margin:6px 0 0 18px; color:var(--text-muted); font-size:12.5px; line-height:1.7; }
+.wallet-steps em { color:var(--text); font-style:normal; font-weight:600; }
+
+.btn {
+  font-family:var(--sans); font-size:12px; font-weight:600;
+  padding:7px 12px; border-radius:7px; border:1px solid var(--border);
+  background:oklch(1 0 0 / 4%); color:var(--text); cursor:pointer;
+  transition:background 0.15s, border-color 0.15s, transform 0.05s;
+}
+.btn:hover { background:oklch(1 0 0 / 10%); }
+.btn:active { transform:translateY(1px); }
+.btn-ghost { background:transparent; }
+.btn-warn { background:oklch(0.78 0.14 85 / 18%); color:var(--gold); border-color:oklch(0.78 0.14 85 / 35%); }
+.btn-warn:hover { background:oklch(0.78 0.14 85 / 30%); }
+.btn-danger { background:oklch(0.65 0.20 25 / 18%); color:var(--danger); border-color:oklch(0.65 0.20 25 / 35%); }
+.btn-danger:hover { background:oklch(0.65 0.20 25 / 30%); }
+
 @media (max-width:768px) {
   body { flex-direction:column; }
   .sidebar { width:100%; min-width:100%; flex-direction:row; padding:8px; overflow-x:auto; border-right:none; border-bottom:1px solid var(--border); }
@@ -280,6 +337,8 @@ a:hover { text-decoration:underline; }
   .sidebar-nav { flex-direction:row; gap:4px; padding:0; }
   .content { padding:16px; }
   .grid-4 { grid-template-columns:repeat(2,1fr); }
+  .wallet-grid { grid-template-columns:1fr; }
+  .wallet-receive { grid-row:auto; }
   .savings-hero { flex-direction:column; gap:12px; text-align:center; }
   .savings-pct { display:none; }
   .watermark { width:100%; }
@@ -308,6 +367,10 @@ a:hover { text-decoration:underline; }
       <svg viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="1.8" stroke-linecap="round" stroke-linejoin="round"><rect x="3" y="3" width="7" height="7" rx="1.5"/><rect x="14" y="3" width="7" height="7" rx="1.5"/><rect x="3" y="14" width="7" height="7" rx="1.5"/><rect x="14" y="14" width="7" height="7" rx="1.5"/></svg>
       Overview
     </button>
+    <button class="nav-item" data-tab="wallet">
+      <svg viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="1.8" stroke-linecap="round" stroke-linejoin="round"><path d="M21 12V7H5a2 2 0 0 1 0-4h14v4"/><path d="M3 5v14a2 2 0 0 0 2 2h16v-5"/><path d="M18 12a2 2 0 0 0 0 4h4v-4z"/></svg>
+      Wallet
+    </button>
     <button class="nav-item" data-tab="sessions">
       <svg viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="1.8" stroke-linecap="round" stroke-linejoin="round"><path d="M21 15a2 2 0 0 1-2 2H7l-4 4V5a2 2 0 0 1 2-2h14a2 2 0 0 1 2 2z"/></svg>
       Sessions
@@ -401,6 +464,69 @@ a:hover { text-decoration:underline; }
     </div>
   </div>
 
+  <!-- Wallet -->
+  <div class="tab" id="tab-wallet">
+    <div class="content-header">
+      <h2>Wallet</h2>
+      <p>Receive USDC, back up your key, or import an existing wallet</p>
+    </div>
+
+    <div class="wallet-grid">
+      <div class="card wallet-receive">
+        <h3>Receive USDC</h3>
+        <div class="wallet-address-row">
+          <span class="wallet-chain-pill" id="wallet-chain-pill">—</span>
+          <code class="wallet-address" id="wallet-address-full">—</code>
+          <button class="btn btn-ghost" id="wallet-copy-btn" title="Copy address">Copy</button>
+        </div>
+        <div class="wallet-balance-big" id="wallet-balance-big">—</div>
+        <div class="wallet-qr" id="wallet-qr"></div>
+        <p class="wallet-hint" id="wallet-qr-hint">Scan to send USDC to this wallet.</p>
+      </div>
+
+      <div class="card">
+        <h3>Back up your key</h3>
+        <p class="wallet-hint">
+          Your private key is the only way to access this wallet.
+          Save it somewhere safe — a password manager, encrypted note, or hardware token.
+          <strong>Never</strong> share it; anyone with the key can drain the wallet.
+        </p>
+        <div class="wallet-secret" id="wallet-secret">
+          <button class="btn btn-warn" id="wallet-reveal-btn">Reveal private key</button>
+        </div>
+        <div id="wallet-file-hint" class="wallet-hint" style="margin-top:10px"></div>
+      </div>
+
+      <div class="card">
+        <h3>Import an existing wallet</h3>
+        <p class="wallet-hint">
+          Paste a private key below to replace the current wallet.
+          <strong>This overwrites your existing wallet file.</strong>
+          Make sure the current key is backed up first, or you will lose access to any funds still on it.
+        </p>
+        <textarea id="wallet-import-input" class="wallet-import-input" placeholder="0x… (Base) or base58 key (Solana)"></textarea>
+        <div class="wallet-actions">
+          <button class="btn btn-danger" id="wallet-import-btn">Import &amp; replace</button>
+          <span class="wallet-import-status" id="wallet-import-status"></span>
+        </div>
+      </div>
+
+      <div class="card">
+        <h3>Export to another tool</h3>
+        <p class="wallet-hint">
+          Franklin stores your key in <code id="wallet-file-path">~/.blockrun/</code>.
+          To use the same wallet in MetaMask / Phantom / a hardware wallet:
+        </p>
+        <ol class="wallet-steps">
+          <li>Click <em>Reveal private key</em> above and copy it.</li>
+          <li>In your destination wallet, choose <em>Import account</em> / <em>Import private key</em>.</li>
+          <li>Paste the key. The wallet will derive the same address.</li>
+          <li>Consider deleting the local file once imported if you no longer want Franklin to spend from it.</li>
+        </ol>
+      </div>
+    </div>
+  </div>
+
   <!-- Sessions -->
   <div class="tab" id="tab-sessions">
     <div class="content-header">
@@ -589,6 +715,109 @@ async function loadLearnings() {
     }).join('');
 }
 
+async function loadWallet() {
+  const w = await api('wallet');
+  if (!w) return;
+  const addr = w.address || '';
+  document.getElementById('wallet-address-full').textContent = addr || 'not set';
+  document.getElementById('wallet-balance-big').textContent = usdBig(w.balance) + ' USDC';
+  document.getElementById('wallet-chain-pill').textContent = w.chain || '—';
+
+  // QR via server — never leak address to third parties
+  const qrBox = document.getElementById('wallet-qr');
+  const hint = document.getElementById('wallet-qr-hint');
+  if (addr && addr !== 'not set') {
+    const svg = await fetch('/api/wallet/qr?data=' + encodeURIComponent(addr)).then(r => r.ok ? r.text() : null);
+    qrBox.innerHTML = svg || '';
+    hint.textContent = w.chain === 'solana'
+      ? 'Scan to send USDC (Solana) to this address.'
+      : 'Scan to send USDC on Base to this address.';
+  } else {
+    qrBox.innerHTML = '';
+    hint.textContent = 'No wallet set yet — run: franklin setup';
+  }
+}
+
+// Copy button
+document.getElementById('wallet-copy-btn').addEventListener('click', async () => {
+  const addr = document.getElementById('wallet-address-full').textContent;
+  try {
+    await navigator.clipboard.writeText(addr);
+    const btn = document.getElementById('wallet-copy-btn');
+    const orig = btn.textContent;
+    btn.textContent = 'Copied ✓';
+    setTimeout(() => { btn.textContent = orig; }, 1400);
+  } catch { /* clipboard may be blocked — user can select manually */ }
+});
+
+// Reveal private key
+document.getElementById('wallet-reveal-btn').addEventListener('click', async () => {
+  if (!confirm('Show the private key on screen?\\n\\nAnyone who sees or records the key can drain this wallet. Make sure nobody is looking over your shoulder or recording your screen.')) return;
+  const box = document.getElementById('wallet-secret');
+  box.innerHTML = '<div class="wallet-hint">Loading…</div>';
+  try {
+    const r = await fetch('/api/wallet/secret');
+    if (!r.ok) {
+      const err = await r.json().catch(() => ({ error: 'unknown' }));
+      box.innerHTML = '<div class="wallet-hint err">Error: ' + esc(err.error || r.statusText) + '</div>';
+      return;
+    }
+    const d = await r.json();
+    box.innerHTML =
+      '<code class="wallet-key-value" id="wallet-key-value">' + esc(d.privateKey) + '</code>' +
+      '<div class="wallet-secret-actions">' +
+        '<button class="btn" id="wallet-key-copy">Copy key</button>' +
+        '<button class="btn btn-ghost" id="wallet-key-hide">Hide</button>' +
+      '</div>';
+    document.getElementById('wallet-file-hint').textContent = 'Stored at: ' + d.walletFile;
+    document.getElementById('wallet-file-path').textContent = d.walletFile;
+    document.getElementById('wallet-key-copy').addEventListener('click', async () => {
+      await navigator.clipboard.writeText(d.privateKey);
+      const btn = document.getElementById('wallet-key-copy');
+      btn.textContent = 'Copied ✓';
+      setTimeout(() => { btn.textContent = 'Copy key'; }, 1400);
+    });
+    document.getElementById('wallet-key-hide').addEventListener('click', () => {
+      box.innerHTML = '<button class="btn btn-warn" id="wallet-reveal-btn-2">Reveal private key</button>';
+      document.getElementById('wallet-reveal-btn-2').addEventListener('click',
+        () => document.getElementById('wallet-reveal-btn').click());
+    });
+  } catch (err) {
+    box.innerHTML = '<div class="wallet-hint err">Error: ' + esc(err.message) + '</div>';
+  }
+});
+
+// Import
+document.getElementById('wallet-import-btn').addEventListener('click', async () => {
+  const pk = document.getElementById('wallet-import-input').value.trim();
+  const status = document.getElementById('wallet-import-status');
+  status.className = 'wallet-import-status';
+  if (!pk) { status.textContent = 'Paste a private key first.'; return; }
+  if (!confirm('Replace the current wallet with this key?\\n\\nThis OVERWRITES your existing wallet file. Any funds on the current wallet will be inaccessible unless you already backed up its key.')) return;
+  status.textContent = 'Importing…';
+  try {
+    const r = await fetch('/api/wallet/import', {
+      method: 'POST',
+      headers: { 'Content-Type': 'application/json' },
+      body: JSON.stringify({ privateKey: pk }),
+    });
+    const d = await r.json();
+    if (!r.ok) {
+      status.textContent = 'Error: ' + (d.error || r.statusText);
+      status.className = 'wallet-import-status err';
+      return;
+    }
+    status.textContent = 'Imported ✓  New address: ' + d.address;
+    status.className = 'wallet-import-status ok';
+    document.getElementById('wallet-import-input').value = '';
+    loadWallet();
+    loadOverview();
+  } catch (err) {
+    status.textContent = 'Error: ' + err.message;
+    status.className = 'wallet-import-status err';
+  }
+});
+
 const es = new EventSource('/api/events');
 const dot = document.getElementById('dot');
 const statusEl = document.getElementById('status');
@@ -602,6 +831,7 @@ loadOverview();
 loadSessions();
 loadSocial();
 loadLearnings();
+loadWallet();
 setInterval(() => api('wallet').then(w => {
   if (w) {
     document.getElementById('balance').textContent = usdBig(w.balance) + ' USDC';

package/dist/panel/server.js

@@ -22,6 +22,32 @@ function json(res, data, status = 200) {
     });
     res.end(JSON.stringify(data));
 }
+/**
+ * Require the request to come from loopback. Wallet secret + import endpoints
+ * must never be reachable from another host — defense-in-depth on top of the
+ * 127.0.0.1 listen binding in panel.ts.
+ */
+function isLoopback(req) {
+    const addr = req.socket.remoteAddress || '';
+    return addr === '127.0.0.1' || addr === '::1' || addr === '::ffff:127.0.0.1';
+}
+async function readBody(req, maxBytes = 16 * 1024) {
+    return new Promise((resolve, reject) => {
+        let size = 0;
+        const chunks = [];
+        req.on('data', (chunk) => {
+            size += chunk.length;
+            if (size > maxBytes) {
+                reject(new Error('Request body too large'));
+                req.destroy();
+                return;
+            }
+            chunks.push(chunk);
+        });
+        req.on('end', () => resolve(Buffer.concat(chunks).toString('utf-8')));
+        req.on('error', reject);
+    });
+}
 function broadcast(data) {
     const msg = `data: ${JSON.stringify(data)}\n\n`;
     for (const client of sseClients) {
@@ -144,6 +170,116 @@ export function createPanelServer(port) {
                     }
                     return;
                 }
+                // ─── Wallet QR (SVG) ────────────────────────────────────────────────
+                // Returns an SVG QR code for a given payload (?data=...). Generated
+                // server-side so the browser never ships the wallet address to a
+                // third-party QR service. Size-bounded.
+                if (p === '/api/wallet/qr') {
+                    const data = url.searchParams.get('data') || '';
+                    if (!data || data.length > 256) {
+                        json(res, { error: 'missing or oversized data param' }, 400);
+                        return;
+                    }
+                    try {
+                        const QRCode = (await import('qrcode')).default;
+                        const svg = await QRCode.toString(data, {
+                            type: 'svg',
+                            errorCorrectionLevel: 'M',
+                            margin: 1,
+                            color: { dark: '#000000', light: '#ffffff' },
+                        });
+                        res.writeHead(200, {
+                            'Content-Type': 'image/svg+xml; charset=utf-8',
+                            'Cache-Control': 'no-store',
+                        });
+                        res.end(svg);
+                    }
+                    catch (err) {
+                        json(res, { error: err.message }, 500);
+                    }
+                    return;
+                }
+                // ─── Wallet secret (loopback only) ──────────────────────────────────
+                // Returns the private key so the user can back it up / move it.
+                // Hardened: loopback-only (belt-and-suspenders on the 127.0.0.1 bind),
+                // no-store cache header, JSON only.
+                if (p === '/api/wallet/secret') {
+                    if (!isLoopback(req)) {
+                        json(res, { error: 'forbidden' }, 403);
+                        return;
+                    }
+                    try {
+                        const chain = loadChain();
+                        const { loadWallet, loadSolanaWallet, WALLET_FILE_PATH, SOLANA_WALLET_FILE_PATH } = await import('@blockrun/llm');
+                        const privateKey = chain === 'solana' ? loadSolanaWallet() : loadWallet();
+                        if (!privateKey) {
+                            json(res, { error: 'wallet not set' }, 404);
+                            return;
+                        }
+                        res.writeHead(200, {
+                            'Content-Type': 'application/json',
+                            'Cache-Control': 'no-store',
+                        });
+                        res.end(JSON.stringify({
+                            chain,
+                            privateKey,
+                            walletFile: chain === 'solana' ? SOLANA_WALLET_FILE_PATH : WALLET_FILE_PATH,
+                        }));
+                    }
+                    catch (err) {
+                        json(res, { error: err.message }, 500);
+                    }
+                    return;
+                }
+                // ─── Wallet import (loopback only) ──────────────────────────────────
+                // Overwrites the local wallet with a user-supplied private key.
+                // Destructive — overwrites the existing wallet file without backup,
+                // so the UI warns the user. Loopback-only.
+                if (p === '/api/wallet/import' && req.method === 'POST') {
+                    if (!isLoopback(req)) {
+                        json(res, { error: 'forbidden' }, 403);
+                        return;
+                    }
+                    try {
+                        const raw = await readBody(req);
+                        const body = JSON.parse(raw);
+                        const pk = (body.privateKey || '').trim();
+                        if (!pk) {
+                            json(res, { error: 'privateKey required' }, 400);
+                            return;
+                        }
+                        const chain = loadChain();
+                        if (chain === 'solana') {
+                            const { saveSolanaWallet, setupAgentSolanaWallet } = await import('@blockrun/llm');
+                            // Basic shape check: base58 chars, reasonable length. Library validates too.
+                            if (!/^[1-9A-HJ-NP-Za-km-z]{40,120}$/.test(pk)) {
+                                json(res, { error: 'invalid Solana private key format' }, 400);
+                                return;
+                            }
+                            saveSolanaWallet(pk);
+                            const client = await setupAgentSolanaWallet({ silent: true });
+                            const address = await client.getWalletAddress();
+                            json(res, { ok: true, chain, address });
+                        }
+                        else {
+                            const { saveWallet, setupAgentWallet } = await import('@blockrun/llm');
+                            // Base: 0x + 64 hex chars
+                            const normalized = pk.startsWith('0x') ? pk : `0x${pk}`;
+                            if (!/^0x[0-9a-fA-F]{64}$/.test(normalized)) {
+                                json(res, { error: 'invalid Base private key — expected 0x + 64 hex chars' }, 400);
+                                return;
+                            }
+                            saveWallet(normalized);
+                            const client = setupAgentWallet({ silent: true });
+                            const address = client.getWalletAddress();
+                            json(res, { ok: true, chain, address });
+                        }
+                    }
+                    catch (err) {
+                        json(res, { error: err.message }, 500);
+                    }
+                    return;
+                }
                 if (p === '/api/social') {
                     const stats = getSocialStats();
                     json(res, stats);

package/dist/session/search.js

@@ -224,6 +224,6 @@ export function formatSearchResults(matches, query) {
         lines.push(`     [${m.matchedRole}] ${m.snippet}`);
         lines.push('');
     }
-    lines.push(`  Resume: franklin  (then /resume <session-id>)\n`);
+    lines.push(`  Resume: franklin --resume <session-id>   (or: franklin resume for a picker)\n`);
     return lines.join('\n');
 }

package/dist/ui/session-picker.d.ts

@@ -0,0 +1,30 @@
+/**
+ * Interactive session picker for `franklin resume`.
+ * Lists recent sessions (newest first) and returns the selected ID.
+ */
+import { type SessionMeta } from '../session/storage.js';
+/**
+ * Resolve a user-provided session identifier to a full session ID.
+ * Supports exact match and unambiguous prefix match (minimum 8 chars).
+ * Returns { ok, id } on success, or { ok, error, candidates } on failure.
+ */
+export declare function resolveSessionIdInput(input: string): {
+    ok: true;
+    id: string;
+} | {
+    ok: false;
+    error: 'not-found' | 'ambiguous';
+    candidates: SessionMeta[];
+};
+/**
+ * Find the most recent session for a given working directory.
+ * Returns null if none exists.
+ */
+export declare function findLatestSessionForDir(workDir: string): SessionMeta | null;
+/**
+ * Show an interactive session picker. Returns the selected session ID,
+ * or null if the user cancels / no sessions exist.
+ */
+export declare function pickSession(opts?: {
+    workDir?: string;
+}): Promise<string | null>;

package/dist/ui/session-picker.js

@@ -0,0 +1,129 @@
+/**
+ * Interactive session picker for `franklin resume`.
+ * Lists recent sessions (newest first) and returns the selected ID.
+ */
+import readline from 'node:readline';
+import path from 'node:path';
+import fs from 'node:fs';
+import chalk from 'chalk';
+import { listSessions } from '../session/storage.js';
+// Canonicalize a path so symlinks compare equal (e.g., /tmp vs /private/tmp on macOS).
+// Falls back to resolve() if the path no longer exists on disk.
+function canonical(p) {
+    try {
+        return fs.realpathSync(path.resolve(p));
+    }
+    catch {
+        return path.resolve(p);
+    }
+}
+function formatRelative(ts) {
+    const diff = Date.now() - ts;
+    const sec = Math.floor(diff / 1000);
+    if (sec < 60)
+        return `${sec}s ago`;
+    const min = Math.floor(sec / 60);
+    if (min < 60)
+        return `${min}m ago`;
+    const hr = Math.floor(min / 60);
+    if (hr < 24)
+        return `${hr}h ago`;
+    const day = Math.floor(hr / 24);
+    return `${day}d ago`;
+}
+function shortDir(dir) {
+    const home = process.env.HOME || '';
+    const clean = home && dir.startsWith(home) ? '~' + dir.slice(home.length) : dir;
+    return clean.length > 40 ? '…' + clean.slice(-39) : clean;
+}
+function modelShort(model) {
+    const slash = model.lastIndexOf('/');
+    return slash >= 0 ? model.slice(slash + 1) : model;
+}
+/**
+ * Resolve a user-provided session identifier to a full session ID.
+ * Supports exact match and unambiguous prefix match (minimum 8 chars).
+ * Returns { ok, id } on success, or { ok, error, candidates } on failure.
+ */
+export function resolveSessionIdInput(input) {
+    const sessions = listSessions();
+    // Exact match first
+    const exact = sessions.find((s) => s.id === input);
+    if (exact)
+        return { ok: true, id: exact.id };
+    // Prefix match — require at least 8 chars to avoid accidental collisions
+    if (input.length >= 8) {
+        const matches = sessions.filter((s) => s.id.startsWith(input));
+        if (matches.length === 1)
+            return { ok: true, id: matches[0].id };
+        if (matches.length > 1)
+            return { ok: false, error: 'ambiguous', candidates: matches };
+    }
+    return { ok: false, error: 'not-found', candidates: [] };
+}
+/**
+ * Find the most recent session for a given working directory.
+ * Returns null if none exists.
+ */
+export function findLatestSessionForDir(workDir) {
+    const target = canonical(workDir);
+    for (const s of listSessions()) {
+        if (canonical(s.workDir) === target)
+            return s;
+    }
+    return null;
+}
+/**
+ * Show an interactive session picker. Returns the selected session ID,
+ * or null if the user cancels / no sessions exist.
+ */
+export async function pickSession(opts = {}) {
+    const sessions = listSessions();
+    if (sessions.length === 0) {
+        console.error(chalk.yellow('\n  No saved sessions found.\n'));
+        return null;
+    }
+    const limit = 20;
+    const shown = sessions.slice(0, limit);
+    console.error('');
+    console.error(chalk.bold('  Resume session:\n'));
+    shown.forEach((s, i) => {
+        const num = chalk.cyan(String(i + 1).padStart(2));
+        const when = formatRelative(s.updatedAt).padEnd(8);
+        const turns = `${s.turnCount}t`.padEnd(5);
+        const model = modelShort(s.model).padEnd(20);
+        const dir = chalk.dim(shortDir(s.workDir));
+        const hereMark = opts.workDir && canonical(s.workDir) === canonical(opts.workDir)
+            ? chalk.green(' ●')
+            : '';
+        console.error(`  ${num}. ${chalk.dim(when)} ${turns} ${model} ${dir}${hereMark}`);
+    });
+    console.error('');
+    console.error(chalk.dim('  Enter a number to resume, or press Enter to cancel.'));
+    if (opts.workDir)
+        console.error(chalk.dim('  ● = matches current directory'));
+    console.error('');
+    const rl = readline.createInterface({
+        input: process.stdin,
+        output: process.stderr,
+        terminal: process.stdin.isTTY ?? false,
+    });
+    return new Promise((resolve) => {
+        rl.question(chalk.bold('  session> '), (answer) => {
+            rl.close();
+            const trimmed = answer.trim();
+            if (!trimmed) {
+                resolve(null);
+                return;
+            }
+            const num = parseInt(trimmed, 10);
+            if (!isNaN(num) && num >= 1 && num <= shown.length) {
+                resolve(shown[num - 1].id);
+                return;
+            }
+            // Allow raw ID as well
+            const match = sessions.find(s => s.id === trimmed || s.id.startsWith(trimmed));
+            resolve(match ? match.id : null);
+        });
+    });
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@blockrun/franklin",
-  "version": "3.6.24",
+  "version": "3.7.1",
   "description": "Franklin — The AI agent with a wallet. Spends USDC autonomously to get real work done. Pay per action, no subscriptions.",
   "type": "module",
   "exports": {
@@ -71,10 +71,12 @@
     "ink-spinner": "^5.0.0",
     "ink-text-input": "^6.0.0",
     "playwright-core": "^1.49.1",
+    "qrcode": "^1.5.4",
     "react": "^19.2.4"
   },
   "devDependencies": {
     "@types/node": "^22.0.0",
+    "@types/qrcode": "^1.5.6",
     "typescript": "^5.7.0"
   }
 }