@blockrun/franklin 3.15.88 → 3.15.89

package/dist/agent/context.js

@@ -5,6 +5,7 @@
 import fs from 'node:fs';
 import path from 'node:path';
 import { execSync } from 'node:child_process';
+import { BLOCKRUN_DIR } from '../config.js';
 import { getWalletAddress as getBaseWalletAddress } from '@blockrun/llm';
 import { Keypair } from '@solana/web3.js';
 import bs58 from 'bs58';
@@ -92,7 +93,7 @@ Go straight to the point. Lead with the action, not the reasoning. Do not restat
 
 The exception: a single short sentence between tool calls is fine when it tells the user something they would otherwise miss — a finding ("Build passes — moving on to tests."), a course correction ("That approach won't work — switching to X."), or a one-line status before a long-running operation. One sentence per update is enough.
 
-**No internal-language leakage.** Always write your visible response in the same language the user is using. If your private reasoning happens in a different language (English while the user writes Chinese, Korean while the user writes Chinese, etc.), do NOT let phrases from that language appear in the user-facing text. The user should never see a stray "좋아", "OK now", or "Alright" in the middle of a Chinese reply.
+**No internal-language leakage.** Always write your visible response in the same language the user is using. If your private reasoning happens in a different language than the user's message, do NOT let phrases from that language appear in the user-facing text. The user should never see a stray "d'accord", "OK now", or "Alright" in the middle of a reply written in another language.
 
 Focus text output on:
 - Decisions that need the user's input
@@ -159,6 +160,19 @@ After delivering results, if a better data source exists, add one line at the en
 Do NOT check access before acting. Do NOT explain what you tried. Just deliver, then tip.`;
 }
 function getWalletKnowledgeSection() {
+    // Read the panel URL persisted by startPanelBackground (start.ts) so we
+    // surface the actual bound port — the panel auto-increments past 3100
+    // when the default is taken (e.g. a second franklin running). Falls back
+    // to the canonical default when the file is missing (panel disabled or
+    // never started this session).
+    let panelUrl = 'http://localhost:3100';
+    try {
+        const persisted = fs.readFileSync(path.join(BLOCKRUN_DIR, 'panel-url'), 'utf8').trim();
+        if (persisted.startsWith('http://') || persisted.startsWith('https://')) {
+            panelUrl = persisted;
+        }
+    }
+    catch { /* fall through to default */ }
     return `# Wallet Storage (answer "where is my wallet" directly — no searching)
 Franklin stores wallet keys in ~/.blockrun/. When the user asks about wallet location, answer from this map — do not grep or scan.
 
@@ -178,7 +192,32 @@ Franklin stores wallet keys in ~/.blockrun/. When the user asks about wallet loc
   - Use \`franklin stats\` / \`franklin content list\` instead of parsing files when the user asks "how much did I spend".
 - Programmatic access: import { getWalletAddress, getOrCreateWallet, getOrCreateSolanaWallet } from '@blockrun/llm'
 
-When the user asks about "my wallet" without qualifier, default to Base (it's the primary chain shown at launch). Only mention Solana if the chain file says solana or the user explicitly asks.`;
+When the user asks about "my wallet" without qualifier, default to Base (it's the primary chain shown at launch). Only mention Solana if the chain file says solana or the user explicitly asks.
+
+## Funding the wallet ("how do I deposit / recharge / fund / top up", in any language)
+
+When the user asks about depositing or funding USDC — in any language — do not describe the steps in chat. **Open the panel wallet page directly in their browser** using Bash, then confirm in chat what you opened and which chain is active.
+
+The exact wallet URL for this session:
+
+  ${panelUrl}/#wallet
+
+Bash command to open it (macOS \`open\`, Linux \`xdg-open\`, Windows \`start\`):
+
+  open ${panelUrl}/#wallet
+
+That page is where the deposit address, QR code, live balance, chain switcher, and back-up controls all live. The user lands on it instead of you reciting steps.
+
+After running \`open\`:
+- Tell the user one line: "Opened the wallet page — \`${panelUrl}/#wallet\`. Active chain: <base|solana>."
+- Read the active chain from ~/.blockrun/payment-chain so they know which network to send USDC on.
+- Mention USDC is the only accepted token; ETH/SOL on their own won't settle x402 calls.
+
+Hard rules:
+- Do NOT print the private key in chat. The panel reveals it behind a click.
+- Do NOT invent a \`franklin deposit\` CLI flow — there isn't one; the panel IS the funding surface.
+- Do NOT hand-craft a different localhost port; the URL above tracks the actual bound port (3100 might have been taken; the panel could be on 3101+).
+- If \`open\` fails (e.g. no GUI on a remote box), fall back to giving them the URL as plain text and tell them to paste it into a browser.`;
 }
 function getBlockRunApiSection() {
     return `# BlockRun Gateway API (the network you live on)

package/dist/agent/llm.d.ts

@@ -116,6 +116,15 @@ export declare class ModelClient {
     private cachedBaseWallet;
     private cachedSolanaWallet;
     private walletCacheTime;
+    /**
+     * USDC actually charged on the most recent x402 settlement, parsed
+     * from `details.amount` (micro-USDC → USD). Reset to 0 at the start
+     * of every `streamCompletion`, written by `signBasePayment` /
+     * `signSolanaPayment`. Callers read it via `getLastPaidUsd()` after
+     * the stream completes so franklin-stats.json records the real wallet
+     * charge instead of a token-catalog estimate.
+     */
+    private lastPaidUsd;
     private static WALLET_CACHE_TTL;
     constructor(opts: LLMClientOptions);
     /**
@@ -132,6 +141,13 @@ export declare class ModelClient {
      * default model.
      */
     private resolveVirtualModel;
+    /**
+     * USDC actually charged for the most recent stream. 0 if no payment
+     * was made (free model / cached / pre-stream error). Callers should
+     * read this after the stream finishes — before that it carries the
+     * value from a previous call.
+     */
+    getLastPaidUsd(): number;
     streamCompletion(request: ModelRequest, signal?: AbortSignal): AsyncGenerator<StreamChunk>;
     private parseNonStreamingMessage;
     /**

package/dist/agent/llm.js

@@ -5,6 +5,7 @@
  */
 import { getOrCreateWallet, getOrCreateSolanaWallet, createPaymentPayload, createSolanaPaymentPayload, parsePaymentRequired, extractPaymentDetails, solanaKeyToBytes, SOLANA_NETWORK, } from '@blockrun/llm';
 import { USER_AGENT } from '../config.js';
+import { appendSettlementRow } from '../stats/cost-log.js';
 import { routeRequest, parseRoutingProfile } from '../router/index.js';
 import { ThinkTagStripper } from './think-tag-stripper.js';
 import { isNemotronProseModel, stripNemotronProse } from './nemotron-prose-stripper.js';
@@ -28,6 +29,19 @@ function parseTimeoutEnv(name) {
     const parsed = raw ? Number.parseInt(raw, 10) : NaN;
     return Number.isFinite(parsed) && parsed >= 0 ? parsed : null;
 }
+/**
+ * Convert an x402 `details.amount` field (USDC in micro-units, 6 decimals)
+ * to a USD float. Mirrors the SDK's `appendCostLog` math so the agent
+ * loop, the proxy, and `cost_log.jsonl` all agree to the cent.
+ */
+function paymentAmountToUsd(amount) {
+    if (amount === undefined || amount === null)
+        return 0;
+    const n = typeof amount === 'string' ? parseFloat(amount) : amount;
+    if (!Number.isFinite(n))
+        return 0;
+    return n / 1e6;
+}
 /**
  * Replace Unicode box-drawing characters with their ASCII equivalents.
  *
@@ -284,6 +298,15 @@ export class ModelClient {
     cachedBaseWallet = null;
     cachedSolanaWallet = null;
     walletCacheTime = 0;
+    /**
+     * USDC actually charged on the most recent x402 settlement, parsed
+     * from `details.amount` (micro-USDC → USD). Reset to 0 at the start
+     * of every `streamCompletion`, written by `signBasePayment` /
+     * `signSolanaPayment`. Callers read it via `getLastPaidUsd()` after
+     * the stream completes so franklin-stats.json records the real wallet
+     * charge instead of a token-catalog estimate.
+     */
+    lastPaidUsd = 0;
     static WALLET_CACHE_TTL = 30 * 60 * 1000; // 30 min TTL
     constructor(opts) {
         this.apiUrl = opts.apiUrl;
@@ -329,7 +352,19 @@ export class ModelClient {
         };
         return FALLBACKS[model] || 'nvidia/qwen3-coder-480b';
     }
+    /**
+     * USDC actually charged for the most recent stream. 0 if no payment
+     * was made (free model / cached / pre-stream error). Callers should
+     * read this after the stream finishes — before that it carries the
+     * value from a previous call.
+     */
+    getLastPaidUsd() {
+        return this.lastPaidUsd;
+    }
     async *streamCompletion(request, signal) {
+        // Reset the per-call charge tracker. signBasePayment / signSolanaPayment
+        // will set it when the gateway demands a 402 settlement.
+        this.lastPaidUsd = 0;
         // Resolve virtual models before any API call
         const resolvedModel = this.resolveVirtualModel(request.model);
         if (resolvedModel !== request.model) {
@@ -463,7 +498,7 @@ export class ModelClient {
             if (response.status === 402) {
                 if (this.debug)
                     console.error('[franklin] Payment required — signing...');
-                const paymentHeader = await this.signPayment(response);
+                const paymentHeader = await this.signPayment(response, request.model);
                 if (!paymentHeader) {
                     yield { kind: 'error', payload: { message: 'Payment signing failed' } };
                     return;
@@ -525,7 +560,7 @@ export class ModelClient {
                         signal: requestController.signal,
                     }), requestController, createModelTimeoutError('request', request.model, requestTimeoutMs), requestTimeoutMs);
                     if (response.status === 402) {
-                        const paymentHeader = await this.signPayment(response);
+                        const paymentHeader = await this.signPayment(response, request.model);
                         if (!paymentHeader) {
                             yield { kind: 'error', payload: { message: 'Payment signing failed' } };
                             return;
@@ -918,17 +953,17 @@ export class ModelClient {
         return { content: collected, usage, stopReason };
     }
     // ─── Payment ───────────────────────────────────────────────────────────
-    async signPayment(response) {
+    async signPayment(response, model) {
         try {
             if (this.chain === 'solana') {
-                return await this.signSolanaPayment(response);
+                return await this.signSolanaPayment(response, model);
             }
-            return await this.signBasePayment(response);
+            return await this.signBasePayment(response, model);
         }
         catch (err) {
             const msg = err.message || '';
             if (msg.includes('insufficient') || msg.includes('balance')) {
-                console.error(`[franklin] Insufficient USDC balance. Run 'franklin balance' to check.`);
+                console.error(`[franklin] Insufficient USDC balance. Open http://localhost:3100/#wallet to deposit (or run 'franklin balance').`);
             }
             else if (this.debug) {
                 console.error('[franklin] Payment error:', msg);
@@ -939,7 +974,7 @@ export class ModelClient {
             return null;
         }
     }
-    async signBasePayment(response) {
+    async signBasePayment(response, model) {
         // Refresh wallet cache after TTL to pick up balance/key changes
         if (!this.cachedBaseWallet || (Date.now() - this.walletCacheTime > ModelClient.WALLET_CACHE_TTL)) {
             const w = getOrCreateWallet();
@@ -954,6 +989,18 @@ export class ModelClient {
             throw new Error('No payment requirements in 402 response');
         const paymentRequired = parsePaymentRequired(paymentHeader);
         const details = extractPaymentDetails(paymentRequired);
+        this.lastPaidUsd = paymentAmountToUsd(details.amount);
+        // Mirror the SDK's appendCostLog write so cost_log.jsonl becomes a
+        // true wallet-truth ledger covering both SDK helper traffic AND the
+        // agent's main LLM stream (which uses this signer, not the SDK).
+        // Match SDK schema (model/wallet/network/client_kind) so every row
+        // is independently queryable.
+        appendSettlementRow('/v1/messages', this.lastPaidUsd, {
+            model,
+            wallet: wallet.address,
+            network: details.network || 'base-mainnet',
+            client_kind: 'AgentClient',
+        });
         const payload = await createPaymentPayload(wallet.privateKey, wallet.address, details.recipient, details.amount, details.network || 'eip155:8453', {
             resourceUrl: details.resource?.url || this.apiUrl,
             resourceDescription: details.resource?.description || 'BlockRun AI API call',
@@ -962,7 +1009,7 @@ export class ModelClient {
         });
         return { 'PAYMENT-SIGNATURE': payload };
     }
-    async signSolanaPayment(response) {
+    async signSolanaPayment(response, model) {
         if (!this.cachedSolanaWallet || (Date.now() - this.walletCacheTime > ModelClient.WALLET_CACHE_TTL)) {
             const w = await getOrCreateSolanaWallet();
             this.walletCacheTime = Date.now();
@@ -975,6 +1022,13 @@ export class ModelClient {
             throw new Error('No payment requirements in 402 response');
         const paymentRequired = parsePaymentRequired(paymentHeader);
         const details = extractPaymentDetails(paymentRequired, SOLANA_NETWORK);
+        this.lastPaidUsd = paymentAmountToUsd(details.amount);
+        appendSettlementRow('/v1/messages', this.lastPaidUsd, {
+            model,
+            wallet: wallet.address,
+            network: details.network || 'solana-mainnet',
+            client_kind: 'AgentClient',
+        });
         const secretBytes = await solanaKeyToBytes(wallet.privateKey);
         const feePayer = details.extra?.feePayer || details.recipient;
         const payload = await createSolanaPaymentPayload(secretBytes, wallet.address, details.recipient, details.amount, feePayer, {

package/dist/agent/loop.js

@@ -1543,16 +1543,25 @@ export async function interactiveSession(config, getUserInput, onEvent, onAbortR
                 contextPct: Math.round(contextUsagePct),
             });
             // Record usage for stats tracking (franklin stats command).
+            // Prefer the real x402 charge from the gateway over a token-catalog
+            // estimate. The estimate is wrong any time the gateway applies
+            // promo pricing, prompt-cache discounts, or per-call flat fees
+            // (verified 2026-05-09 against cost_log.jsonl: token-based
+            // estimate said $34.79 across the same calls the wallet only
+            // paid $2.24 for — a 15× drift). estimateCost only fills in
+            // when no payment was made (free model / cached / pre-stream
+            // failure), where the gateway charge is genuinely 0.
+            //
             // Pass the fallback flag so franklin-stats.json's totalFallbacks +
             // per-model fallbackCount stay in sync with the audit log a few
             // lines below — same `turnFailedModels.size > 0` predicate, same
-            // turn. Without this, stats showed 0 fallbacks across 5150 real
-            // requests on a machine that visibly hit fallback paths in
-            // franklin-debug.log; `franklin insights` was therefore useless
-            // for spotting a hot routing chain.
-            const costEstimate = estimateCost(resolvedModel, inputTokens, usage.outputTokens, 1);
+            // turn.
+            const paidUsd = client.getLastPaidUsd();
+            const callCost = paidUsd > 0
+                ? paidUsd
+                : estimateCost(resolvedModel, inputTokens, usage.outputTokens, 1);
             const llmLatencyMs = Date.now() - llmCallStartedAt;
-            recordUsage(resolvedModel, inputTokens, usage.outputTokens, costEstimate, llmLatencyMs, turnFailedModels.size > 0);
+            recordUsage(resolvedModel, inputTokens, usage.outputTokens, callCost, llmLatencyMs, turnFailedModels.size > 0);
             // ── Circuit breakers: prevent infinite-loop wallet drain ──
             // Per-turn $-cap was removed in v3.11.0 — runaway loops are caught by
             // MAX_TOOL_CALLS_PER_TURN (25) and MAX_TINY_RESPONSES (2) above; the
@@ -1579,7 +1588,7 @@ export async function interactiveSession(config, getUserInput, onEvent, onAbortR
             else {
                 consecutiveTinyResponses = 0;
             }
-            recordSessionUsage(resolvedModel, inputTokens, usage.outputTokens, costEstimate, routingTier);
+            recordSessionUsage(resolvedModel, inputTokens, usage.outputTokens, callCost, routingTier);
             // Capture tool names invoked in this assistant turn. The AuditEntry
             // interface has had a `toolCalls?: string[]` slot since 3.15.11, but
             // nothing populated it — verified 2026-05-04 in a real Opus session
@@ -1602,7 +1611,7 @@ export async function interactiveSession(config, getUserInput, onEvent, onAbortR
                 model: resolvedModel,
                 inputTokens,
                 outputTokens: usage.outputTokens,
-                costUsd: costEstimate,
+                costUsd: callCost,
                 // Any failed model this turn means the model that finally
                 // succeeded was a fallback. Without this, audit log read 0%
                 // fallbacks across 4k entries — useless for diagnosing whether
@@ -1617,11 +1626,11 @@ export async function interactiveSession(config, getUserInput, onEvent, onAbortR
             // Accumulate session-level totals for session meta
             sessionInputTokens += inputTokens;
             sessionOutputTokens += usage.outputTokens;
-            sessionCostUsd += costEstimate;
-            turnCostUsd += costEstimate;
+            sessionCostUsd += callCost;
+            turnCostUsd += callCost;
             const opusCost = (inputTokens / 1_000_000) * OPUS_PRICING.input
                 + (usage.outputTokens / 1_000_000) * OPUS_PRICING.output;
-            sessionSavedVsOpus += Math.max(0, opusCost - costEstimate);
+            sessionSavedVsOpus += Math.max(0, opusCost - callCost);
             // ── Max-spend guard ──
             // Session-level cost ceiling. Batch/scripted callers pass this to bound a
             // single run ("spend at most $0.50 for today's digest"); interactive

package/dist/agent/optimize.js

@@ -77,33 +77,68 @@ export function budgetToolResults(history) {
                 budgeted.push(part);
                 continue;
             }
-            const content = typeof part.content === 'string' ? part.content : JSON.stringify(part.content);
-            const size = content.length;
-            // Per-tool cap
+            // Decompose tool_result content. Two shapes are valid per
+            // CapabilityOutcome (types.ts:38): a bare string OR an array of
+            // text + image segments. Pre-fix, we collapsed array content to
+            // JSON.stringify(content), which made base64 image bytes count
+            // toward the char budget — a 275KB image would tip past the 32K
+            // cap, the whole content array (including the image block) got
+            // replaced with a truncated text preview, and the image was
+            // destroyed before reaching the wire. Verified 2026-05-10 from a
+            // gateway log (sonnet-4.6, ~21K input tokens — would have been
+            // ~150K with the image present): the tool_result body was a
+            // 2KB self-referential string starting with "[Output truncated:
+            // 275,952 chars → 2000 preview]\n\n[{\"type\":\"text\"…". Vision
+            // hallucinated everything in that session.
+            //
+            // Fix: only the TEXT segments count toward MAX_TOOL_RESULT_CHARS.
+            // Image segments pass through untouched. If text is over budget,
+            // truncate ONLY the text — keep the image array alongside.
+            const isArrayContent = Array.isArray(part.content);
+            const textBlocks = isArrayContent
+                ? part.content.filter((b) => b.type === 'text')
+                : [];
+            const imageBlocks = isArrayContent
+                ? part.content.filter((b) => b.type === 'image')
+                : [];
+            const textOnly = isArrayContent
+                ? textBlocks.map(b => b.text).join('\n')
+                : part.content;
+            const size = textOnly.length;
+            // Per-tool cap (text-only — images stay)
             if (size > MAX_TOOL_RESULT_CHARS) {
                 modified = true;
                 // Truncate at line boundary for cleaner output
-                let preview = content.slice(0, PREVIEW_CHARS);
+                let preview = textOnly.slice(0, PREVIEW_CHARS);
                 const lastNewline = preview.lastIndexOf('\n');
                 if (lastNewline > PREVIEW_CHARS * 0.5) {
                     preview = preview.slice(0, lastNewline);
                 }
+                const truncatedText = `[Output truncated: ${size.toLocaleString()} chars → ${PREVIEW_CHARS} preview]\n\n${preview}\n\n... (${size - PREVIEW_CHARS} chars omitted)`;
                 budgeted.push({
                     type: 'tool_result',
                     tool_use_id: part.tool_use_id,
-                    content: `[Output truncated: ${size.toLocaleString()} chars → ${PREVIEW_CHARS} preview]\n\n${preview}\n\n... (${size - PREVIEW_CHARS} chars omitted)`,
+                    content: imageBlocks.length > 0
+                        ? [{ type: 'text', text: truncatedText }, ...imageBlocks]
+                        : truncatedText,
                     is_error: part.is_error,
                 });
                 messageTotal += PREVIEW_CHARS + 200;
                 continue;
             }
-            // Per-message aggregate cap — once exceeded, truncate remaining results
+            // Per-message aggregate cap — once exceeded, truncate remaining results.
+            // Same rule: drop only the text payload; images survive so multi-image
+            // tool flows aren't silently broken when a single chatty text result
+            // pushes the message over the cap.
             if (messageTotal + size > MAX_TOOL_RESULTS_PER_MESSAGE_CHARS) {
                 modified = true;
+                const placeholder = `[Output omitted: message budget exceeded (${MAX_TOOL_RESULTS_PER_MESSAGE_CHARS / 1000}K chars/msg)]`;
                 budgeted.push({
                     type: 'tool_result',
                     tool_use_id: part.tool_use_id,
-                    content: `[Output omitted: message budget exceeded (${MAX_TOOL_RESULTS_PER_MESSAGE_CHARS / 1000}K chars/msg)]`,
+                    content: imageBlocks.length > 0
+                        ? [{ type: 'text', text: placeholder }, ...imageBlocks]
+                        : placeholder,
                     is_error: part.is_error,
                 });
                 messageTotal = MAX_TOOL_RESULTS_PER_MESSAGE_CHARS;

package/dist/commands/panel.js

@@ -2,7 +2,10 @@
  * franklin panel — launch the local web dashboard.
  */
 import chalk from 'chalk';
+import fs from 'node:fs';
+import path from 'node:path';
 import { createPanelServer } from '../panel/server.js';
+import { BLOCKRUN_DIR } from '../config.js';
 export async function panelCommand(options) {
     const requestedPort = parseInt(options.port || '3100', 10);
     // Handle port-in-use by trying up to 20 subsequent ports silently.
@@ -25,9 +28,20 @@ export async function panelCommand(options) {
         // 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', () => {
+            const url = `http://localhost:${port}`;
+            // Mirror what start.ts does for the auto-panel — persist the bound
+            // URL so any concurrent `franklin start` agent can read /#wallet
+            // off the same file. Without this, a user who disables panel
+            // autostart and runs `franklin panel` separately would still get
+            // the hardcoded 3100 default in the agent prompt.
+            try {
+                fs.mkdirSync(BLOCKRUN_DIR, { recursive: true });
+                fs.writeFileSync(path.join(BLOCKRUN_DIR, 'panel-url'), url, 'utf8');
+            }
+            catch { /* best-effort */ }
             console.log('');
             console.log(chalk.bold('  Franklin Panel'));
-            console.log(chalk.dim(`  http://localhost:${port}`) +
+            console.log(chalk.dim(`  ${url}`) +
                 (port !== requestedPort ? chalk.yellow(`  (fell back from ${requestedPort})`) : ''));
             console.log('');
             console.log(chalk.dim('  Press Ctrl+C to stop.'));
@@ -35,7 +49,7 @@ export async function panelCommand(options) {
             // Try to open browser
             const open = process.platform === 'darwin' ? 'open' : process.platform === 'win32' ? 'start' : 'xdg-open';
             import('node:child_process').then(({ exec }) => {
-                exec(`${open} http://localhost:${port}`);
+                exec(`${open} ${url}`);
             }).catch(() => { });
         });
         // Graceful shutdown

package/dist/commands/start.js

@@ -1,6 +1,8 @@
 import chalk from 'chalk';
+import fs from 'node:fs';
+import path from 'node:path';
 import { getOrCreateWallet, getOrCreateSolanaWallet } from '@blockrun/llm';
-import { loadChain, API_URLS } from '../config.js';
+import { BLOCKRUN_DIR, loadChain, API_URLS } from '../config.js';
 import { retryFetchBalance } from './balance-retry.js';
 import { flushStats, loadStats } from '../stats/tracker.js';
 import { OPUS_PRICING, MODEL_PRICING } from '../pricing.js';
@@ -647,7 +649,18 @@ async function startPanelBackground(startPort) {
                 });
                 server.listen(port, '127.0.0.1', () => {
                     server.unref?.();
-                    resolve(`http://localhost:${port}`);
+                    const url = `http://localhost:${port}`;
+                    // Persist the bound URL so the agent context (assembled per-turn)
+                    // can point users at /#wallet for funding without baking in the
+                    // 3100 default — the panel auto-increments past EADDRINUSE.
+                    // Best-effort write: a stale file from a crashed run is harmless,
+                    // since the user just sees a dead link.
+                    try {
+                        fs.mkdirSync(BLOCKRUN_DIR, { recursive: true });
+                        fs.writeFileSync(path.join(BLOCKRUN_DIR, 'panel-url'), url, 'utf8');
+                    }
+                    catch { /* best-effort */ }
+                    resolve(url);
                 });
             };
             tryListen(startPort, 0);

package/dist/learnings/extractor.js

@@ -21,7 +21,7 @@ const VALID_CATEGORIES = new Set([
 const EXTRACTION_PROMPT = `You are analyzing a conversation between a user and an AI coding agent. Extract user preferences, behavioral patterns, and project knowledge that would help personalize future interactions.
 
 Analyze for:
-1. Language — what language does the user write in? (English, Chinese, mixed?)
+1. Language — what language does the user write in? (English, another language, mixed?)
 2. Model preferences — did they switch models or express a preference?
 3. Coding style — did they correct the agent's code style? (naming, formatting, conventions)
 4. Communication — are they terse or verbose? Do they want explanations or just code?

package/dist/proxy/server.js

@@ -1,6 +1,7 @@
 import http from 'node:http';
 import { getOrCreateWallet, getOrCreateSolanaWallet, createPaymentPayload, createSolanaPaymentPayload, parsePaymentRequired, extractPaymentDetails, solanaKeyToBytes, SOLANA_NETWORK, } from '@blockrun/llm';
 import { recordUsage } from '../stats/tracker.js';
+import { appendSettlementRow } from '../stats/cost-log.js';
 import { appendAudit } from '../stats/audit.js';
 import { buildFallbackChain, DEFAULT_FALLBACK_CONFIG, ROUTING_PROFILES, } from './fallback.js';
 import { routeRequest, parseRoutingProfile, } from '../router/index.js';
@@ -430,6 +431,11 @@ export function createProxy(options) {
                 };
                 let response;
                 let finalModel = requestModel;
+                // Real x402 charge for the call that ultimately succeeded. 0 when
+                // no payment was needed (free model / cached). Fed into recordUsage
+                // and appendAudit below so franklin-stats.json reflects what the
+                // wallet actually paid, not a token-catalog estimate.
+                let paidUsd = 0;
                 const requestTimeoutMs = effectiveRequestTimeoutMs;
                 // Use fallback chain if enabled
                 if (fallbackEnabled && body && requestPath.includes('messages')) {
@@ -457,6 +463,7 @@ export function createProxy(options) {
                     // Use the body with the correct fallback model for payment
                     body = result.bodyUsed;
                     usedFallback = result.fallbackUsed;
+                    paidUsd = result.paidUsd;
                     // Skip the success log when the request originated from a test
                     // fixture, even if the fallback ended on a real model. Verified
                     // on a real machine: 5 spurious "↺ Fallback successful: using
@@ -473,7 +480,7 @@ export function createProxy(options) {
                     }
                 }
                 else {
-                    response = await fetchModelAttempt(targetUrl, requestInit, body, requestModel, {
+                    const attempt = await fetchModelAttempt(targetUrl, requestInit, body, requestModel, {
                         method: req.method || 'POST',
                         headers,
                         chain,
@@ -481,6 +488,8 @@ export function createProxy(options) {
                         solanaWallet,
                         timeoutMs: requestTimeoutMs,
                     });
+                    response = attempt.response;
+                    paidUsd = attempt.paidUsd;
                 }
                 const responseHeaders = {};
                 response.headers.forEach((v, k) => {
@@ -569,7 +578,13 @@ export function createProxy(options) {
                                     if (outputTokens > 0) {
                                         trackOutputTokens(finalModel, outputTokens);
                                         const latencyMs = Date.now() - requestStartTime;
-                                        const cost = estimateCost(finalModel, inputTokens, outputTokens);
+                                        // Real x402 charge wins over the token-catalog estimate.
+                                        // estimateCost only fills in for the no-payment path
+                                        // (free models / cached) so stats stay non-null there.
+                                        const cost = paidUsd > 0
+                                            ? paidUsd
+                                            : estimateCost(finalModel, inputTokens, outputTokens);
+                                        const costSource = paidUsd > 0 ? 'charged' : 'estimated';
                                         recordUsage(finalModel, inputTokens, outputTokens, cost, latencyMs, usedFallback);
                                         appendAudit({
                                             ts: Date.now(),
@@ -582,7 +597,7 @@ export function createProxy(options) {
                                             source: 'proxy',
                                         });
                                         if (options.debug)
-                                            logger.debug(`[franklin] recorded: model=${finalModel} in=${inputTokens} out=${outputTokens} cost=$${cost.toFixed(4)} fallback=${usedFallback}`);
+                                            logger.debug(`[franklin] recorded: model=${finalModel} in=${inputTokens} out=${outputTokens} cost=$${cost.toFixed(4)} (${costSource}) fallback=${usedFallback}`);
                                     }
                                 }
                                 res.end();
@@ -609,7 +624,10 @@ export function createProxy(options) {
                             trackOutputTokens(finalModel, outputTokens);
                             const inputTokens = parsed.usage?.input_tokens || 0;
                             const latencyMs = Date.now() - requestStartTime;
-                            const cost = estimateCost(finalModel, inputTokens, outputTokens);
+                            const cost = paidUsd > 0
+                                ? paidUsd
+                                : estimateCost(finalModel, inputTokens, outputTokens);
+                            const costSource = paidUsd > 0 ? 'charged' : 'estimated';
                             recordUsage(finalModel, inputTokens, outputTokens, cost, latencyMs, usedFallback);
                             appendAudit({
                                 ts: Date.now(),
@@ -622,7 +640,7 @@ export function createProxy(options) {
                                 source: 'proxy',
                             });
                             if (options.debug)
-                                logger.debug(`[franklin] recorded: model=${finalModel} in=${inputTokens} out=${outputTokens} cost=$${cost.toFixed(4)} fallback=${usedFallback}`);
+                                logger.debug(`[franklin] recorded: model=${finalModel} in=${inputTokens} out=${outputTokens} cost=$${cost.toFixed(4)} (${costSource}) fallback=${usedFallback}`);
                         }
                     }
                     catch {
@@ -645,16 +663,17 @@ export function createProxy(options) {
     return server;
 }
 async function fetchModelAttempt(url, init, body, model, payment) {
-    let response = await fetchWithTimeout(url, { ...init, body: body || undefined }, payment.timeoutMs, `Proxy request for ${model}`);
+    const response = await fetchWithTimeout(url, { ...init, body: body || undefined }, payment.timeoutMs, `Proxy request for ${model}`);
+    // Non-402 path: free model or cached response — no payment, paidUsd = 0.
     if (response.status !== 402)
-        return response;
+        return { response, paidUsd: 0 };
     if (payment.chain === 'solana' && payment.solanaWallet) {
         return handleSolanaPayment(response, url, payment.method, payment.headers, body, payment.solanaWallet.privateKey, payment.solanaWallet.address, payment.timeoutMs, model);
     }
     if (payment.baseWallet) {
         return handleBasePayment(response, url, payment.method, payment.headers, body, payment.baseWallet.privateKey, payment.baseWallet.address, payment.timeoutMs, model);
     }
-    return response;
+    return { response, paidUsd: 0 };
 }
 /**
  * Try each fallback model as a full x402 attempt:
@@ -670,7 +689,7 @@ async function fetchWithPaymentFallback(url, init, originalBody, config, payment
         const body = replaceModelInBody(originalBody, model);
         try {
             attempts++;
-            const response = await fetchModelAttempt(url, init, body, model, payment);
+            const { response, paidUsd } = await fetchModelAttempt(url, init, body, model, payment);
             if (!config.retryOn.includes(response.status)) {
                 return {
                     response,
@@ -679,6 +698,7 @@ async function fetchWithPaymentFallback(url, init, originalBody, config, payment
                     fallbackUsed: i > 0,
                     attemptsCount: attempts,
                     failedModels,
+                    paidUsd,
                 };
             }
             try {
@@ -719,17 +739,24 @@ function sleep(ms) {
 async function handleBasePayment(response, url, method, headers, body, privateKey, fromAddress, timeoutMs = getProxyRequestTimeoutMs(), model = 'unknown') {
     const paymentHeader = await extractPaymentHeader(response);
     if (!paymentHeader) {
-        throw new Error('402 Payment Required — wallet may need funding. Run: franklin balance');
+        throw new Error('402 Payment Required — wallet may need funding. Open http://localhost:3100/#wallet to deposit USDC (or run: franklin balance)');
     }
     const paymentRequired = parsePaymentRequired(paymentHeader);
     const details = extractPaymentDetails(paymentRequired);
+    const paidUsd = paymentAmountToUsd(details.amount);
+    appendSettlementRow(extractEndpointPath(url), paidUsd, {
+        model,
+        wallet: fromAddress,
+        network: details.network || 'base-mainnet',
+        client_kind: 'ProxyClient',
+    });
     const paymentPayload = await createPaymentPayload(privateKey, fromAddress, details.recipient, details.amount, details.network || 'eip155:8453', {
         resourceUrl: details.resource?.url || url,
         resourceDescription: details.resource?.description || 'BlockRun AI API call',
         maxTimeoutSeconds: details.maxTimeoutSeconds || 300,
         extra: details.extra,
     });
-    return fetchWithTimeout(url, {
+    const paid = await fetchWithTimeout(url, {
         method,
         headers: {
             ...headers,
@@ -737,6 +764,7 @@ async function handleBasePayment(response, url, method, headers, body, privateKe
         },
         body: body || undefined,
     }, timeoutMs, `Paid proxy request for ${model}`);
+    return { response: paid, paidUsd };
 }
 // ======================================================================
 // Solana payment handler
@@ -744,10 +772,17 @@ async function handleBasePayment(response, url, method, headers, body, privateKe
 async function handleSolanaPayment(response, url, method, headers, body, privateKey, fromAddress, timeoutMs = getProxyRequestTimeoutMs(), model = 'unknown') {
     const paymentHeader = await extractPaymentHeader(response);
     if (!paymentHeader) {
-        throw new Error('402 Payment Required — wallet may need funding. Run: franklin balance');
+        throw new Error('402 Payment Required — wallet may need funding. Open http://localhost:3100/#wallet to deposit USDC (or run: franklin balance)');
     }
     const paymentRequired = parsePaymentRequired(paymentHeader);
     const details = extractPaymentDetails(paymentRequired, SOLANA_NETWORK);
+    const paidUsd = paymentAmountToUsd(details.amount);
+    appendSettlementRow(extractEndpointPath(url), paidUsd, {
+        model,
+        wallet: fromAddress,
+        network: details.network || 'solana-mainnet',
+        client_kind: 'ProxyClient',
+    });
     const secretKey = await solanaKeyToBytes(privateKey);
     const feePayer = details.extra?.feePayer || details.recipient;
     const paymentPayload = await createSolanaPaymentPayload(secretKey, fromAddress, details.recipient, details.amount, feePayer, {
@@ -756,7 +791,7 @@ async function handleSolanaPayment(response, url, method, headers, body, private
         maxTimeoutSeconds: details.maxTimeoutSeconds || 300,
         extra: details.extra,
     });
-    return fetchWithTimeout(url, {
+    const paid = await fetchWithTimeout(url, {
         method,
         headers: {
             ...headers,
@@ -764,6 +799,35 @@ async function handleSolanaPayment(response, url, method, headers, body, private
         },
         body: body || undefined,
     }, timeoutMs, `Paid proxy request for ${model}`);
+    return { response: paid, paidUsd };
+}
+/**
+ * Extract just the path portion of a URL — `https://api.blockrun.ai/v1/messages`
+ * → `/v1/messages`. Used as the `endpoint` field in `cost_log.jsonl` so
+ * proxy entries match the SDK's path-only convention. Falls back to the
+ * raw input if URL parsing throws (defensive — better to log a weird
+ * string than skip the row).
+ */
+function extractEndpointPath(url) {
+    try {
+        return new URL(url).pathname || url;
+    }
+    catch {
+        return url;
+    }
+}
+/**
+ * Convert an x402 `details.amount` field (USDC in micro-units, 6 decimals)
+ * to a USD float. Mirrors the SDK's `appendCostLog` math so the proxy and
+ * `cost_log.jsonl` agree to the cent.
+ */
+function paymentAmountToUsd(amount) {
+    if (amount === undefined || amount === null)
+        return 0;
+    const n = typeof amount === 'string' ? parseFloat(amount) : amount;
+    if (!Number.isFinite(n))
+        return 0;
+    return n / 1e6;
 }
 export function classifyRequest(body) {
     try {

package/dist/social/a11y.d.ts

@@ -51,4 +51,4 @@ export declare function extractArticleBlocks(tree: string): Array<{
  * This doubles as the "this is a tweet" signal in social-bot — the only link
  * inside an article block with this label shape is the permalink to the tweet.
  */
-export declare const X_TIME_LINK_PATTERN = "(?:Jan|Feb|Mar|Apr|May|Jun|Jul|Aug|Sep|Oct|Nov|Dec)\\s+\\d+(?:,?\\s+\\d{4})?|\\d+[smhd]|\\d+\\s+(?:second|minute|hour|day|week|month|year)s?\\s+ago|just now|now|yesterday|\\d{1,2}:\\d{2}\\s*[AaPp][Mm]|\\d{4}\\u5e74\\d{1,2}\\u6708\\d{1,2}\\u65e5";
+export declare const X_TIME_LINK_PATTERN = "(?:Jan|Feb|Mar|Apr|May|Jun|Jul|Aug|Sep|Oct|Nov|Dec)\\s+\\d+(?:,?\\s+\\d{4})?|\\d+[smhd]|\\d+\\s+(?:second|minute|hour|day|week|month|year)s?\\s+ago|just now|now|yesterday|\\d{1,2}:\\d{2}\\s*[AaPp][Mm]|\\d{4}\\p{Script=Han}\\d{1,2}\\p{Script=Han}\\d{1,2}\\p{Script=Han}";

package/dist/social/a11y.js

@@ -23,7 +23,7 @@
  * @returns       Array of ref ids like ["0-0", "1-3"] in document order
  */
 export function findRefs(tree, role, label = '.*') {
-    const re = new RegExp(`\\[(\\d+-\\d+)\\]\\s+${escapeRegex(role)}:\\s*${label}`, 'g');
+    const re = new RegExp(`\\[(\\d+-\\d+)\\]\\s+${escapeRegex(role)}:\\s*(?:${label})`, 'gu');
     const out = [];
     let m;
     while ((m = re.exec(tree)) !== null) {
@@ -36,7 +36,7 @@ export function findRefs(tree, role, label = '.*') {
  * (ref) and the visible text (label) in one pass.
  */
 export function findRefsWithLabels(tree, role, label = '.*') {
-    const re = new RegExp(`\\[(\\d+-\\d+)\\]\\s+${escapeRegex(role)}:\\s*(${label})`, 'g');
+    const re = new RegExp(`\\[(\\d+-\\d+)\\]\\s+${escapeRegex(role)}:\\s*(${label})`, 'gu');
     const out = [];
     let m;
     while ((m = re.exec(tree)) !== null) {
@@ -87,11 +87,8 @@ export function extractArticleBlocks(tree) {
 //   "Mar 16", "Apr 12, 2026", "5h", "5m", "2d", "30s", "just now", "now"
 //   "31 seconds ago", "35 minutes ago", "4 hours ago" (full-word format)
 //   "Yesterday", "Apr 12", "12:30 AM"
-//   CJK-locale date markers (year/month/day in Chinese-locale rendering of
-//   tweet timestamps). Encoded via Unicode escapes to keep the source file
-//   ASCII-clean per the English-only-source policy:
-//     U+5E74 = year marker, U+6708 = month marker, U+65E5 = day marker.
-export const X_TIME_LINK_PATTERN = '(?:Jan|Feb|Mar|Apr|May|Jun|Jul|Aug|Sep|Oct|Nov|Dec)\\s+\\d+(?:,?\\s+\\d{4})?|\\d+[smhd]|\\d+\\s+(?:second|minute|hour|day|week|month|year)s?\\s+ago|just now|now|yesterday|\\d{1,2}:\\d{2}\\s*[AaPp][Mm]|\\d{4}\\u5e74\\d{1,2}\\u6708\\d{1,2}\\u65e5';
+//   Locale-rendered numeric dates separated by Han-script date markers
+export const X_TIME_LINK_PATTERN = '(?:Jan|Feb|Mar|Apr|May|Jun|Jul|Aug|Sep|Oct|Nov|Dec)\\s+\\d+(?:,?\\s+\\d{4})?|\\d+[smhd]|\\d+\\s+(?:second|minute|hour|day|week|month|year)s?\\s+ago|just now|now|yesterday|\\d{1,2}:\\d{2}\\s*[AaPp][Mm]|\\d{4}\\p{Script=Han}\\d{1,2}\\p{Script=Han}\\d{1,2}\\p{Script=Han}';
 function escapeRegex(s) {
     return s.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
 }

package/dist/social/browser.js

@@ -78,6 +78,54 @@ export function serializeAxTree(root) {
     walk(root, 0);
     return { tree: lines.join('\n'), refs };
 }
+function cdpStringValue(v) {
+    if (v === undefined || v === null)
+        return '';
+    if (typeof v === 'string')
+        return v;
+    return String(v);
+}
+function cdpNodesToAxTree(nodes) {
+    if (!nodes || nodes.length === 0)
+        return null;
+    const byId = new Map();
+    const childSet = new Set();
+    for (const n of nodes) {
+        byId.set(n.nodeId, n);
+        if (n.childIds)
+            for (const cid of n.childIds)
+                childSet.add(cid);
+    }
+    // The root has no parent (or no entry pointing at it as a child).
+    const root = nodes.find((n) => !n.parentId && !childSet.has(n.nodeId)) ??
+        nodes.find((n) => !n.parentId) ??
+        nodes[0];
+    const seen = new Set();
+    function build(node) {
+        if (seen.has(node.nodeId))
+            return null;
+        seen.add(node.nodeId);
+        const ax = {
+            role: cdpStringValue(node.role?.value),
+            name: cdpStringValue(node.name?.value),
+            value: cdpStringValue(node.value?.value),
+            description: cdpStringValue(node.description?.value),
+            children: [],
+        };
+        if (node.childIds) {
+            for (const cid of node.childIds) {
+                const child = byId.get(cid);
+                if (!child)
+                    continue;
+                const built = build(child);
+                if (built)
+                    ax.children.push(built);
+            }
+        }
+        return ax;
+    }
+    return build(root);
+}
 /**
  * Franklin's social browser driver. Lazy-imports playwright-core so the
  * rest of the CLI stays fast to start.
@@ -144,10 +192,21 @@ export class SocialBrowser {
      */
     async snapshot() {
         this.requirePage();
-        // Playwright's accessibility snapshot returns a full AX tree
-        // page.accessibility was removed from Playwright types in v1.46 but still works at runtime
-        // eslint-disable-next-line @typescript-eslint/no-explicit-any
-        const axRoot = await this.page.accessibility.snapshot({ interestingOnly: false });
+        // page.accessibility was removed from playwright-core (gone by 1.59).
+        // Calling it threw `Cannot read properties of undefined (reading 'snapshot')`
+        // in production (failures.jsonl entries 1776662596215 / 1776662608060).
+        // The supported replacement is the CDP Accessibility domain, which still
+        // ships with Chromium-based browsers.
+        const cdp = await this.page.context().newCDPSession(this.page);
+        let axRoot;
+        try {
+            // eslint-disable-next-line @typescript-eslint/no-explicit-any
+            const result = (await cdp.send('Accessibility.getFullAXTree'));
+            axRoot = cdpNodesToAxTree(result?.nodes);
+        }
+        finally {
+            await cdp.detach().catch(() => { });
+        }
         if (!axRoot)
             return '';
         const { tree, refs } = serializeAxTree(axRoot);

package/dist/stats/cost-log.d.ts

@@ -1,24 +1,26 @@
 /**
- * Reader for `~/.blockrun/cost_log.jsonl` — the SDK-owned ledger of every
- * settled x402 payment.
+ * Reader (and limited writer) for `~/.blockrun/cost_log.jsonl` — the
+ * append-only ledger of every settled x402 payment.
  *
- * Franklin's own `franklin-stats.json` and `franklin-audit.jsonl` only
- * capture calls that pass through specific code paths (the main agent
- * loop and the proxy). Helper LLM calls (analyzeTurn, prefetchForIntent,
- * compaction, evaluator, verification, MoA, subagent, learning extraction,
- * etc.) all settle x402 payments through the SDK — those payments DO get
- * recorded in cost_log.jsonl by `@blockrun/llm` itself, but Franklin's
- * stats infra had been ignoring this file entirely.
+ * History: this file was originally SDK-only territory. `@blockrun/llm`'s
+ * internal `appendCostLog` writes one line per micropayment when callers
+ * use SDK helper methods (modal sandbox, prediction market, exa, etc.).
+ * But Franklin's main LLM stream — both the in-process agent loop
+ * (`src/agent/llm.ts`) and the proxy server (`src/proxy/server.ts`) —
+ * have **their own** x402 signers that bypass the SDK entirely. Verified
+ * 2026-05-09 on a real machine: a single paid agent turn dropped the
+ * wallet by $0.001 and updated `franklin-stats.json` correctly, but
+ * cost_log.jsonl gained zero entries. So cost_log was never the
+ * "wallet truth" it advertised — it was an SDK-subset.
  *
- * Verified 2026-05-06 against a real machine: cost_log.jsonl is written
- * by the SDK with snake_case keys (`cost_usd`, `ts` in unix seconds with
- * subsecond precision — Python convention) and Franklin's reads/writes
- * use camelCase + ms. This module bridges the format gap so stats /
- * insights / `franklin balance` can surface the wallet-truth total
- * alongside the recorded total.
+ * Fix (2026-05-09): expose `appendSettlementRow` so the agent and proxy
+ * signers can write the same shape the SDK does. The format contract
+ * (snake_case `cost_usd`, `ts` in unix seconds with subsecond precision,
+ * one JSON object per line) is preserved exactly so both writers
+ * interleave cleanly. Order in the file follows wall-clock arrival.
  *
- * Responsibility: read-only. We never write or trim cost_log.jsonl —
- * the SDK owns it.
+ * Responsibility: read + append-only write. We never trim or rotate
+ * cost_log.jsonl — that contract still belongs to the SDK / hygiene.
  */
 export interface SettlementRow {
     /** Endpoint path that was paid for, e.g. `/v1/chat/completions`. */
@@ -61,6 +63,39 @@ interface ReadOptions {
  * is only created on the first paid call.
  */
 export declare function loadSdkSettlements(opts?: ReadOptions): SettlementRow[];
+/**
+ * Optional metadata fields the SDK writes alongside `endpoint` / `cost_usd`.
+ * Adding these to agent + proxy entries keeps cost_log.jsonl uniformly
+ * queryable (group by model, filter by wallet, etc.). Verified 2026-05-10
+ * against a real cost_log: the SDK writes
+ *   {endpoint, cost_usd, model, wallet, network, client_kind}
+ * Without these on agent rows you can't tell which model burned a $0.001
+ * — the row is just `/v1/messages: 0.001`. With them, every line is a
+ * complete forensic record.
+ */
+export interface SettlementMeta {
+    model?: string;
+    wallet?: string;
+    network?: string;
+    client_kind?: string;
+}
+/**
+ * Append one settlement row to ~/.blockrun/cost_log.jsonl in the same
+ * shape `@blockrun/llm`'s internal `appendCostLog` writes. Best-effort:
+ * silently swallows fs errors so a logging failure never breaks the
+ * paid call that just succeeded. Costs <= 0 are treated as no-op (no
+ * point logging $0 — the file's purpose is "what was actually paid").
+ *
+ * Honors FRANKLIN_NO_AUDIT=1 the same way `appendAudit` and `recordUsage`
+ * do, so test runs (test/e2e.mjs sets this) don't pollute the user's
+ * real cost_log. Verified 2026-05-10 on a real machine: two
+ * `/v1/messages: $0.000001` rows leaked into the user's cost_log from
+ * a paid e2e run because this gate was missing — paid e2e was hitting
+ * the real gateway with a real wallet, but the test framework expected
+ * NO writes to land. Restoring the gate keeps cost_log a clean ledger
+ * of REAL traffic.
+ */
+export declare function appendSettlementRow(endpoint: string, costUsd: number, meta?: SettlementMeta): void;
 /** Aggregate the SDK ledger into a single summary object. */
 export declare function summarizeSdkSettlements(opts?: ReadOptions): SettlementSummary;
 export {};

package/dist/stats/cost-log.js

@@ -1,24 +1,26 @@
 /**
- * Reader for `~/.blockrun/cost_log.jsonl` — the SDK-owned ledger of every
- * settled x402 payment.
+ * Reader (and limited writer) for `~/.blockrun/cost_log.jsonl` — the
+ * append-only ledger of every settled x402 payment.
  *
- * Franklin's own `franklin-stats.json` and `franklin-audit.jsonl` only
- * capture calls that pass through specific code paths (the main agent
- * loop and the proxy). Helper LLM calls (analyzeTurn, prefetchForIntent,
- * compaction, evaluator, verification, MoA, subagent, learning extraction,
- * etc.) all settle x402 payments through the SDK — those payments DO get
- * recorded in cost_log.jsonl by `@blockrun/llm` itself, but Franklin's
- * stats infra had been ignoring this file entirely.
+ * History: this file was originally SDK-only territory. `@blockrun/llm`'s
+ * internal `appendCostLog` writes one line per micropayment when callers
+ * use SDK helper methods (modal sandbox, prediction market, exa, etc.).
+ * But Franklin's main LLM stream — both the in-process agent loop
+ * (`src/agent/llm.ts`) and the proxy server (`src/proxy/server.ts`) —
+ * have **their own** x402 signers that bypass the SDK entirely. Verified
+ * 2026-05-09 on a real machine: a single paid agent turn dropped the
+ * wallet by $0.001 and updated `franklin-stats.json` correctly, but
+ * cost_log.jsonl gained zero entries. So cost_log was never the
+ * "wallet truth" it advertised — it was an SDK-subset.
  *
- * Verified 2026-05-06 against a real machine: cost_log.jsonl is written
- * by the SDK with snake_case keys (`cost_usd`, `ts` in unix seconds with
- * subsecond precision — Python convention) and Franklin's reads/writes
- * use camelCase + ms. This module bridges the format gap so stats /
- * insights / `franklin balance` can surface the wallet-truth total
- * alongside the recorded total.
+ * Fix (2026-05-09): expose `appendSettlementRow` so the agent and proxy
+ * signers can write the same shape the SDK does. The format contract
+ * (snake_case `cost_usd`, `ts` in unix seconds with subsecond precision,
+ * one JSON object per line) is preserved exactly so both writers
+ * interleave cleanly. Order in the file follows wall-clock arrival.
  *
- * Responsibility: read-only. We never write or trim cost_log.jsonl —
- * the SDK owns it.
+ * Responsibility: read + append-only write. We never trim or rotate
+ * cost_log.jsonl — that contract still belongs to the SDK / hygiene.
  */
 import fs from 'node:fs';
 import path from 'node:path';
@@ -79,6 +81,54 @@ export function loadSdkSettlements(opts) {
     }
     return rows;
 }
+/**
+ * Append one settlement row to ~/.blockrun/cost_log.jsonl in the same
+ * shape `@blockrun/llm`'s internal `appendCostLog` writes. Best-effort:
+ * silently swallows fs errors so a logging failure never breaks the
+ * paid call that just succeeded. Costs <= 0 are treated as no-op (no
+ * point logging $0 — the file's purpose is "what was actually paid").
+ *
+ * Honors FRANKLIN_NO_AUDIT=1 the same way `appendAudit` and `recordUsage`
+ * do, so test runs (test/e2e.mjs sets this) don't pollute the user's
+ * real cost_log. Verified 2026-05-10 on a real machine: two
+ * `/v1/messages: $0.000001` rows leaked into the user's cost_log from
+ * a paid e2e run because this gate was missing — paid e2e was hitting
+ * the real gateway with a real wallet, but the test framework expected
+ * NO writes to land. Restoring the gate keeps cost_log a clean ledger
+ * of REAL traffic.
+ */
+export function appendSettlementRow(endpoint, costUsd, meta) {
+    if (process.env.FRANKLIN_NO_AUDIT === '1' || process.env.FRANKLIN_NO_PERSIST === '1')
+        return;
+    if (!Number.isFinite(costUsd) || costUsd <= 0)
+        return;
+    if (typeof endpoint !== 'string' || endpoint.length === 0)
+        return;
+    try {
+        fs.mkdirSync(path.dirname(getCostLogPath()), { recursive: true });
+    }
+    catch { /* best-effort */ }
+    // Match SDK conventions exactly: snake_case keys, ts in unix seconds
+    // with subsecond precision (Python convention — divide ms epoch by 1e3
+    // so the SDK reader and our reader agree on the timestamp).
+    const entry = {
+        ts: Date.now() / 1e3,
+        endpoint,
+        cost_usd: costUsd,
+    };
+    if (meta?.model)
+        entry.model = meta.model;
+    if (meta?.wallet)
+        entry.wallet = meta.wallet;
+    if (meta?.network)
+        entry.network = meta.network;
+    if (meta?.client_kind)
+        entry.client_kind = meta.client_kind;
+    try {
+        fs.appendFileSync(getCostLogPath(), JSON.stringify(entry) + '\n');
+    }
+    catch { /* best-effort */ }
+}
 /** Aggregate the SDK ledger into a single summary object. */
 export function summarizeSdkSettlements(opts) {
     const rows = loadSdkSettlements(opts);

package/dist/tools/prediction.debug.js

@@ -767,7 +767,7 @@ export const predictionMarketCapability = {
             'Default routing: ' +
             '"is there a market on X anywhere" → searchAll. ' +
             '"top wallets / who is profitable / who should I follow on Polymarket" → leaderboard. ' +
-            '"analyze this wallet / can I copy this trader / 复制交易 / show me their P&L AND positions" → run walletProfile + walletPnl + walletPositions IN PARALLEL with the same address — three $0.005 calls give the full picture for $0.015. Do not Bash-curl Polymarket directly; the agent has paid tools for this. ' +
+            '"analyze this wallet / can I copy this trader / copy trade / show me their P&L AND positions" → run walletProfile + walletPnl + walletPositions IN PARALLEL with the same address — three $0.005 calls give the full picture for $0.015. Do not Bash-curl Polymarket directly; the agent has paid tools for this. ' +
             '"what are smart traders betting on right now" → smartActivity. ' +
             '"show smart money on this specific Polymarket market" → smartMoney with conditionId. ' +
             '"should I bet on X" → run searchPolymarket + searchKalshi in parallel and compare implied probabilities — divergence is the signal.',

package/dist/ui/app.js

@@ -309,7 +309,7 @@ function InputBox({ input, setInput, onSubmit, model, balance, chain, walletTail
                             const m = balance.match(/\$([\d.]+)/);
                             const num = m ? parseFloat(m[1]) : null;
                             if (num !== null && num < 0.50) {
-                                return _jsxs(_Fragment, { children: [_jsx(Text, { color: "red", bold: true, children: balance }), _jsx(Text, { color: "red", children: " \u26A0 low \u2014 fund wallet or /model free" })] });
+                                return _jsxs(_Fragment, { children: [_jsx(Text, { color: "red", bold: true, children: balance }), _jsx(Text, { color: "red", children: " \u26A0 low \u2014 deposit at http://localhost:3100/#wallet or /model free" })] });
                             }
                             if (num !== null && num < 1.00) {
                                 return _jsx(Text, { color: "yellow", children: balance });

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@blockrun/franklin",
-  "version": "3.15.88",
+  "version": "3.15.89",
   "description": "Franklin — The AI agent with a wallet. Spends USDC autonomously to get real work done. Pay per action, no subscriptions.",
   "type": "module",
   "exports": {