@blockrun/franklin 3.8.34 → 3.8.36

package/README.md

@@ -398,7 +398,7 @@ That economic loop is the product.
 
 ```text
 src/
-├── index.ts           CLI entry (franklin + runcode alias)
+├── index.ts           CLI entry (franklin)
 ├── banner.ts          Ben Franklin portrait + FRANKLIN gradient text
 ├── agent/             Agent loop, LLM client, compaction, commands
 ├── tools/             20+ built-in tools (Read/Write/Edit/Bash/Glob/Grep/
@@ -480,10 +480,12 @@ cd franklin
 npm install
 npm run build
 npm test              # deterministic local tests — no API calls
-npm run test:e2e      # live e2e tests — hits real models, needs wallet
+npm run test:e2e      # live e2e tests — free smoke works unfunded; paid tools need network + funded wallet
 node dist/index.js --help
 ```
 
+For the recommended live validation order and failure triage, see [docs/live-e2e-checklist.md](docs/live-e2e-checklist.md).
+
 **Contributing:** open an issue first to discuss meaningful changes. PRs welcome on bugs, docs, new models in pricing, and new tools.
 
 ---

package/dist/agent/commands.js

@@ -289,7 +289,7 @@ const DIRECT_COMMANDS = {
         }
         const hasWallet = fs.existsSync(path.join(BLOCKRUN_DIR, 'wallet.json'))
             || fs.existsSync(path.join(BLOCKRUN_DIR, 'solana-wallet.json'));
-        checks.push(hasWallet ? '✓ wallet configured' : '⚠ no wallet — run: runcode setup');
+        checks.push(hasWallet ? '✓ wallet configured' : '⚠ no wallet — run: franklin setup');
         checks.push(fs.existsSync(path.join(BLOCKRUN_DIR, 'franklin-config.json')) || fs.existsSync(path.join(BLOCKRUN_DIR, 'runcode-config.json')) ? '✓ config file exists' : '⚠ no config — using defaults');
         // Check MCP
         const { listMcpServers } = await import('../mcp/client.js');

package/dist/agent/compact.js

@@ -434,7 +434,7 @@ function pickCompactionModel(primaryModel) {
     if (primaryModel.includes('opus') || primaryModel.includes('pro')) {
         return 'anthropic/claude-sonnet-4.6';
     }
-    if (primaryModel.includes('sonnet') || primaryModel.includes('gpt-5.4') || primaryModel.includes('gemini-2.5-pro')) {
+    if (primaryModel.includes('sonnet') || primaryModel.includes('gpt-5.4') || primaryModel.includes('gpt-5.5') || primaryModel.includes('gemini-2.5-pro')) {
         return 'anthropic/claude-haiku-4.5-20251001';
     }
     if (primaryModel.includes('haiku') || primaryModel.includes('mini') || primaryModel.includes('nano')) {

package/dist/agent/context.js

@@ -189,7 +189,7 @@ Your training data is frozen in the past. Live-world questions MUST be answered
 
 If you find yourself about to emit one of these, stop and call the tool instead. If you don't know which ticker the user means, call ExaSearch or AskUser — never deflect.
 
-**Media generation (ImageGen / VideoGen).** Pass just the user's descriptive prompt and the output path — do NOT pass \`model\`. The harness picks the right model for the requested style + budget and surfaces a cost proposal through AskUser before spending. Only pass \`model\` explicitly if the user named one specifically.`;
+**Media generation (ImageGen / VideoGen).** Pass just the user's descriptive prompt and the output path — do NOT pass \`model\`. The harness picks the right model for the requested style + budget, refines loose prompts using a 5-slot template (scene / subject / details / use case / constraints), and surfaces both the refinement and a cost proposal through AskUser before spending. If the user wants their prompt left exactly as written, prefix it with \`///\` to skip refinement. Only pass \`model\` explicitly if the user named one specifically.`;
 }
 function getTokenEfficiencySection() {
     return `# Token Efficiency

package/dist/agent/loop.js

@@ -1208,6 +1208,25 @@ export async function interactiveSession(config, getUserInput, onEvent, onAbortR
                         };
                     }
                 }
+                // Vision attachments: if a tool returned image bytes (e.g. Read on a
+                // .png), wrap them into Anthropic-native tool_result.content so
+                // vision-capable models can actually see the image. The gateway
+                // preserves these blocks end-to-end via the tool_result side channel.
+                if (result.images && result.images.length > 0) {
+                    const content = [{ type: 'text', text: result.output }];
+                    for (const img of result.images) {
+                        content.push({
+                            type: 'image',
+                            source: { type: 'base64', media_type: img.mediaType, data: img.base64 },
+                        });
+                    }
+                    return {
+                        type: 'tool_result',
+                        tool_use_id: inv.id,
+                        content,
+                        is_error: result.isError,
+                    };
+                }
                 return {
                     type: 'tool_result',
                     tool_use_id: inv.id,

package/dist/agent/media-router.d.ts

@@ -33,9 +33,35 @@ export interface MediaProposal {
         style: MediaStyle;
         priority: MediaPriority;
     };
+    /**
+     * A fuller rewrite of the user's prompt, following the 5-slot template
+     * (scene/subject/details/use-case/constraints). Null when the classifier
+     * judged the input already well-specified, or when the env opt-out is set,
+     * or when the rewrite was identical to the raw input. When non-null, the
+     * AskUser layout surfaces it as "Refined:" with a "Use ORIGINAL" option.
+     */
+    refinedPrompt: string | null;
+    refinementSummary: string;
     totalCostUsd: number;
 }
 export declare function clearMediaRouterCache(): void;
+/**
+ * Normalize a refined prompt: trim, cap length, reject obvious junk.
+ * Returns null when the value should be treated as absent (missing,
+ * non-string, empty after trim).
+ *
+ * Exported for testability — invariants matter more here than elsewhere
+ * because the output is user-visible and paid for.
+ */
+export declare function validateRefined(raw: unknown, maxChars: number): string | null;
+/**
+ * Whitespace-insensitive, case-insensitive identity check — if the
+ * classifier's "refinement" is just the input with different spacing,
+ * don't bother the user with a "Refined:" block.
+ */
+export declare function isEffectivelyIdentical(a: string, b: string): boolean;
+export declare const REFINED_PROMPT_MAX_CHARS = 500;
+export declare const REFINEMENT_SUMMARY_LIMIT = 80;
 export interface AnalyzeMediaOpts {
     kind: MediaKind;
     prompt: string;
@@ -43,6 +69,13 @@ export interface AnalyzeMediaOpts {
     quantity?: number;
     durationSeconds?: number;
     signal?: AbortSignal;
+    /**
+     * One-shot opt-out — caller stripped a `///` prefix from the user's input
+     * and wants the proposal rendered without a Refined block or Use-original
+     * option. The classifier still runs (for model selection), but the
+     * refinement is discarded at parse time.
+     */
+    skipRefine?: boolean;
 }
 /**
  * Pick the best model + alternatives for this media request. Returns null

package/dist/agent/media-router.js

@@ -16,7 +16,9 @@ import { getModelsByCategory, estimateCostUsd, defaultDurationSeconds, maxDurati
 // ─── Classifier ─────────────────────────────────────────────────────────
 const CLASSIFIER_MODEL = process.env.FRANKLIN_MEDIA_ROUTER_MODEL || 'nvidia/llama-4-maverick';
 const TIMEOUT_MS = 3_500; // slightly more lenient than the turn-analyzer — we're asking for JSON with reasoning
-const MAX_TOKENS = 256;
+const MAX_TOKENS = 384; // bumped from 256 to leave room for refined_prompt (≤500 chars) + refinement_summary (≤80)
+const REFINED_MAX_CHARS = 500;
+const REFINEMENT_SUMMARY_MAX_CHARS = 80;
 function buildSystemPrompt(kind, catalog) {
     const catalogLines = catalog.map(m => {
         const p = m.pricing;
@@ -25,7 +27,7 @@ function buildSystemPrompt(kind, catalog) {
             : `$${(p.per_second ?? 0).toFixed(2)}/s (default ${p.default_duration_seconds ?? 8}s, max ${p.max_duration_seconds ?? 8}s)`;
         return `  - ${m.id} · ${price} · ${m.description || m.name}`;
     }).join('\n');
-    return `You pick the best ${kind} model for a user's Franklin request. Output ONE LINE of compact JSON. No markdown, no code fences, no explanation.
+    return `You pick the best ${kind} model for a user's Franklin request AND refine the user's prompt. Output ONE LINE of compact JSON. No markdown, no code fences, no explanation.
 
 ## Catalog (${catalog.length} available ${kind} models)
 ${catalogLines}
@@ -34,6 +36,8 @@ ${catalogLines}
 
 {"style":"photoreal|illustration|anime|logo|concept|other",
  "priority":"cost|quality|balanced",
+ "refined_prompt":"<rewritten prompt in the user's language, <=${REFINED_MAX_CHARS} chars, or null if already well-specified>",
+ "refinement_summary":"<one short sentence, <=${REFINEMENT_SUMMARY_MAX_CHARS} chars, user-visible>",
  "recommended":{"model":"<id from catalog>","rationale":"<one sentence, <=140 chars>"},
  "cheaper":{"model":"<id from catalog | null>","rationale":"<one sentence>"},
  "premium":{"model":"<id from catalog | null>","rationale":"<one sentence>"}}
@@ -45,16 +49,33 @@ Rules:
 - Match style → model: anime/illustration prefers CogView, photoreal prefers Nano Banana Pro / Grok Imagine Pro, budget-conscious picks cheapest-acceptable.
 - One sentence rationale, user-visible.
 
+## Refinement (emit refined_prompt + refinement_summary)
+
+If the user's prompt is missing ≥3 of these 5 slots, rewrite to fill them. If it already has ≥3 covered, set refined_prompt to null and refinement_summary to "Already well-specified".
+
+  1. Scene       — location, time of day, environment, background
+  2. Subject     — primary focus (who / what), preserved EXACTLY from the user's input (no substitution)
+  3. Details     — materials, textures, lighting, camera/lens feel, composition, mood (concrete visual facts, not praise)
+  4. Use Case    — editorial photo, product mockup, UI screen, logo, storyboard frame, social-media cover, etc.
+  5. Constraints — aspect ratio, what must not drift (no watermark, preserve face, no text), hard asks
+
+Anti-slop rules:
+- Concrete visual facts ("overcast daylight", "brushed aluminum") beat vague praise ("stunning", "cinematic masterpiece").
+- Wrap literal text that must appear in the image in double quotes. Spell difficult words letter-by-letter.
+- One revision per turn — do not combine conflicting asks.
+- Natural language, not keyword-tag format.
+- refined_prompt stays in the same language as the user input. Chinese in → Chinese out.
+
 Examples:
 
 Input: "a photo of a cat on Mars, photoreal"
-Output: {"style":"photoreal","priority":"balanced","recommended":{"model":"google/nano-banana-pro","rationale":"Photoreal scenes — Nano Banana Pro has strong realism at moderate cost."},"cheaper":{"model":"google/nano-banana","rationale":"Same family, lower cost, slightly less detail."},"premium":{"model":"openai/gpt-image-2","rationale":"Best photoreal fidelity when budget allows."}}
+Output: {"style":"photoreal","priority":"balanced","refined_prompt":"Eye-level photograph of a cat standing on the rust-colored Martian surface, late-afternoon low sun casting long shadows, distant canyon rim in the background, 50mm feel, shallow depth of field, editorial photo use, no watermark.","refinement_summary":"Added scene, lighting, lens, use case, constraint.","recommended":{"model":"google/nano-banana-pro","rationale":"Photoreal scenes — Nano Banana Pro has strong realism at moderate cost."},"cheaper":{"model":"google/nano-banana","rationale":"Same family, lower cost, slightly less detail."},"premium":{"model":"openai/gpt-image-2","rationale":"Best photoreal fidelity when budget allows."}}
 
 Input: "赛博朋克风格的动漫角色"
-Output: {"style":"anime","priority":"balanced","recommended":{"model":"zai/cogview-4","rationale":"CogView-4 specializes in stylized/anime imagery."},"cheaper":{"model":"google/nano-banana","rationale":"Cheaper but less stylized."},"premium":{"model":"xai/grok-imagine-image-pro","rationale":"Premium detail for complex scenes."}}
+Output: {"style":"anime","priority":"balanced","refined_prompt":"赛博朋克风格的动漫角色，站在霓虹灯映照的雨夜街道上，身穿合成纤维夹克与金属反光饰件，头顶全息广告牌漂浮，低角度视角，强烈青粉对比，海报用，居中构图。","refinement_summary":"补全了场景、光线、材质、用途、构图。","recommended":{"model":"zai/cogview-4","rationale":"CogView-4 specializes in stylized/anime imagery."},"cheaper":{"model":"google/nano-banana","rationale":"Cheaper but less stylized."},"premium":{"model":"xai/grok-imagine-image-pro","rationale":"Premium detail for complex scenes."}}
 
 Input: "a 10-second cinematic drone shot over Tokyo at night"
-Output: {"style":"concept","priority":"quality","recommended":{"model":"bytedance/seedance-2.0","rationale":"Seedance 2.0 delivers the best cinematic quality."},"cheaper":{"model":"bytedance/seedance-2.0-fast","rationale":"Faster + cheaper, minor quality trade-off."},"premium":{"model":null,"rationale":"2.0 is already the top tier."}}
+Output: {"style":"concept","priority":"quality","refined_prompt":null,"refinement_summary":"Already well-specified.","recommended":{"model":"bytedance/seedance-2.0","rationale":"Seedance 2.0 delivers the best cinematic quality."},"cheaper":{"model":"bytedance/seedance-2.0-fast","rationale":"Faster + cheaper, minor quality trade-off."},"premium":{"model":null,"rationale":"2.0 is already the top tier."}}
 
 Output JSON only, single line.`;
 }
@@ -82,6 +103,33 @@ function validateChoice(raw, catalog) {
     const rationale = typeof raw.rationale === 'string' ? raw.rationale.slice(0, 240) : '';
     return { model, rationale };
 }
+/**
+ * Normalize a refined prompt: trim, cap length, reject obvious junk.
+ * Returns null when the value should be treated as absent (missing,
+ * non-string, empty after trim).
+ *
+ * Exported for testability — invariants matter more here than elsewhere
+ * because the output is user-visible and paid for.
+ */
+export function validateRefined(raw, maxChars) {
+    if (typeof raw !== 'string')
+        return null;
+    const trimmed = raw.trim();
+    if (trimmed.length === 0)
+        return null;
+    return trimmed.slice(0, maxChars);
+}
+/**
+ * Whitespace-insensitive, case-insensitive identity check — if the
+ * classifier's "refinement" is just the input with different spacing,
+ * don't bother the user with a "Refined:" block.
+ */
+export function isEffectivelyIdentical(a, b) {
+    const normalize = (s) => s.toLowerCase().replace(/\s+/g, ' ').trim();
+    return normalize(a) === normalize(b);
+}
+export const REFINED_PROMPT_MAX_CHARS = REFINED_MAX_CHARS;
+export const REFINEMENT_SUMMARY_LIMIT = REFINEMENT_SUMMARY_MAX_CHARS;
 /**
  * Pick the best model + alternatives for this media request. Returns null
  * on any failure path (classifier timeout, parse error, empty catalog) so
@@ -100,12 +148,18 @@ export async function analyzeMediaRequest(opts) {
     if (catalog.length === 0)
         return null;
     // Cache check — classifier output is stable for a given prompt + catalog
-    // version, so re-asking within 30s is waste.
+    // version, so re-asking within 30s is waste. Cache stores the FULL
+    // classifier response (refinement + model picks); the per-call mask for
+    // skipRefine / FRANKLIN_NO_MEDIA_PROMPT_REFINE is applied on the way out
+    // so the same cache entry serves callers with different opt-out flags.
     const quantity = Math.max(1, Math.floor(opts.quantity ?? 1));
+    const globalOptOut = process.env.FRANKLIN_NO_MEDIA_PROMPT_REFINE === '1';
+    const shouldDiscard = globalOptOut || opts.skipRefine === true;
+    const maskRefinement = (p) => shouldDiscard ? { ...p, refinedPrompt: null, refinementSummary: '' } : p;
     const key = hashKey([kind, prompt.trim().slice(0, 500), String(quantity), String(opts.durationSeconds ?? '')]);
     const hit = cache.get(key);
     if (hit && hit.expiresAt > Date.now())
-        return hit.value;
+        return maskRefinement(hit.value);
     // Call the classifier.
     const catalogMap = new Map(catalog.map(m => [m.id, m]));
     const system = buildSystemPrompt(kind, catalog);
@@ -152,6 +206,15 @@ export async function analyzeMediaRequest(opts) {
         return null;
     const cheaperChoice = validateChoice(parsed.cheaper, catalogMap);
     const premiumChoice = validateChoice(parsed.premium, catalogMap);
+    // Refinement fields. The cache stores the full classifier output; the
+    // per-call mask is applied on the way out via maskRefinement() above, so
+    // here we just normalize + discard rewrites that are effectively the
+    // same as the raw input (drift-proof).
+    let refinedPrompt = validateRefined(parsed.refined_prompt, REFINED_MAX_CHARS);
+    const refinementSummary = validateRefined(parsed.refinement_summary, REFINEMENT_SUMMARY_MAX_CHARS) ?? '';
+    if (refinedPrompt !== null && isEffectivelyIdentical(refinedPrompt, prompt)) {
+        refinedPrompt = null;
+    }
     // Build proposal with live cost estimates.
     const durationSeconds = kind === 'video'
         ? (opts.durationSeconds ?? defaultDurationSeconds(rec.model))
@@ -180,6 +243,8 @@ export async function analyzeMediaRequest(opts) {
         cheaper: toChoice(cheaperChoice),
         premium: toChoice(premiumChoice),
         intent: { style, priority },
+        refinedPrompt,
+        refinementSummary,
         totalCostUsd: recommended.estimatedCostUsd,
     };
     // Evict oldest if bounded
@@ -189,7 +254,7 @@ export async function analyzeMediaRequest(opts) {
             cache.delete(firstKey);
     }
     cache.set(key, { value: proposal, expiresAt: Date.now() + CACHE_TTL_MS });
-    return proposal;
+    return maskRefinement(proposal);
 }
 // ─── Presentation ───────────────────────────────────────────────────────
 /**
@@ -202,6 +267,13 @@ export function renderProposalForAskUser(p, userPrompt) {
     lines.push(`*Media generation proposal*`);
     lines.push('');
     lines.push(`Prompt: "${userPrompt.trim().slice(0, 200)}"`);
+    if (p.refinedPrompt) {
+        lines.push('');
+        lines.push(`Refined: ${p.refinedPrompt}`);
+        if (p.refinementSummary) {
+            lines.push(`  (${p.refinementSummary})`);
+        }
+    }
     if (p.kind === 'video' && p.durationSeconds) {
         const maxNote = p.maxDurationSeconds ? ` (max ${p.maxDurationSeconds}s)` : '';
         lines.push(`Duration: ${p.durationSeconds}s${maxNote}`);
@@ -220,11 +292,17 @@ export function renderProposalForAskUser(p, userPrompt) {
     lines.push('');
     lines.push(`  (prices include the 5% gateway fee)`);
     const options = [];
-    options.push({ id: 'recommended', label: `Continue with ${p.recommended.model}` });
+    const recLabel = p.refinedPrompt
+        ? `Continue with refined prompt + ${p.recommended.model}`
+        : `Continue with ${p.recommended.model}`;
+    options.push({ id: 'recommended', label: recLabel });
     if (p.cheaper)
         options.push({ id: 'cheaper', label: `Use cheaper (${p.cheaper.model})` });
     if (p.premium)
         options.push({ id: 'premium', label: `Use premium (${p.premium.model})` });
+    if (p.refinedPrompt) {
+        options.push({ id: 'use-raw', label: `Use ORIGINAL prompt + ${p.recommended.model}` });
+    }
     options.push({ id: 'cancel', label: 'Cancel (no charge)' });
     return { question: lines.join('\n'), options };
 }

package/dist/agent/optimize.js

@@ -29,6 +29,7 @@ const MODEL_MAX_OUTPUT = {
     'anthropic/claude-opus-4.6': 32_000,
     'anthropic/claude-sonnet-4.6': 64_000,
     'anthropic/claude-haiku-4.5-20251001': 16_384,
+    'openai/gpt-5.5': 32_768,
     'openai/gpt-5.4': 32_768,
     'openai/gpt-5-mini': 16_384,
     'google/gemini-2.5-pro': 65_536,

package/dist/agent/permissions.js

@@ -151,7 +151,16 @@ export class PermissionManager {
     }
     // ─── Internal ──────────────────────────────────────────────────────────
     loadRules() {
-        const configPath = path.join(BLOCKRUN_DIR, 'runcode-permissions.json');
+        const configPath = path.join(BLOCKRUN_DIR, 'franklin-permissions.json');
+        const legacyPath = path.join(BLOCKRUN_DIR, 'runcode-permissions.json');
+        // One-shot migration from the old name. If the user only has the legacy
+        // file, rename it so future writes/reads land on the franklin path.
+        try {
+            if (!fs.existsSync(configPath) && fs.existsSync(legacyPath)) {
+                fs.renameSync(legacyPath, configPath);
+            }
+        }
+        catch { /* best effort */ }
         try {
             if (fs.existsSync(configPath)) {
                 const raw = JSON.parse(fs.readFileSync(configPath, 'utf-8'));

package/dist/agent/tokens.js

@@ -166,6 +166,10 @@ const MODEL_CONTEXT_WINDOWS = {
     'anthropic/claude-haiku-4.5': 200_000,
     'anthropic/claude-haiku-4.5-20251001': 200_000,
     // OpenAI
+    // gpt-5.5 advertises 1.05M context at the gateway, but Franklin keeps the
+    // conservative 128k baseline matching every other gpt-5.x line — bump in
+    // a separate change once a real >128k call has been verified end-to-end.
+    'openai/gpt-5.5': 128_000,
     'openai/gpt-5.4': 128_000,
     'openai/gpt-5.4-pro': 128_000,
     'openai/gpt-5.3': 128_000,

package/dist/agent/types.d.ts

@@ -18,10 +18,21 @@ export interface ThinkingSegment {
     thinking: string;
     signature?: string;
 }
+export interface ImageSegment {
+    type: 'image';
+    source: {
+        type: 'base64';
+        media_type: string;
+        data: string;
+    } | {
+        type: 'url';
+        url: string;
+    };
+}
 export interface CapabilityOutcome {
     type: 'tool_result';
     tool_use_id: string;
-    content: string | ContentPart[];
+    content: string | Array<TextSegment | ImageSegment>;
     is_error?: boolean;
 }
 export type ContentPart = TextSegment | CapabilityInvocation | ThinkingSegment;
@@ -60,6 +71,16 @@ export interface CapabilityResult {
     };
     /** Full tool output for expandable display — separate from truncated preview. */
     fullOutput?: string;
+    /**
+     * Optional image attachments emitted by a tool (e.g. Read on a .png).
+     * The agent loop wraps these into an Anthropic-native tool_result.content
+     * array so vision-capable models can actually see the bytes instead of
+     * getting a "Binary file" stub.
+     */
+    images?: Array<{
+        mediaType: string;
+        base64: string;
+    }>;
 }
 export interface ExecutionScope {
     workingDir: string;

package/dist/commands/balance.js

@@ -30,7 +30,7 @@ export async function balanceCommand() {
     catch (err) {
         const msg = err instanceof Error ? err.message : '';
         if (msg.includes('ENOENT') || msg.includes('wallet') || msg.includes('key')) {
-            console.log(chalk.red('No wallet found. Run `runcode setup` first.'));
+            console.log(chalk.red('No wallet found. Run `franklin setup` first.'));
         }
         else {
             console.log(chalk.red(`Error checking balance: ${msg || 'unknown error'}`));

package/dist/commands/daemon.js

@@ -1,4 +1,4 @@
-import { spawn, execSync } from 'node:child_process';
+import { spawn, execFileSync, execSync } from 'node:child_process';
 import fs from 'node:fs';
 import path from 'node:path';
 import chalk from 'chalk';
@@ -42,6 +42,17 @@ function isRunning(pid) {
         return true;
     }
 }
+function findDaemonBinary() {
+    for (const name of ['franklin', 'runcode']) {
+        try {
+            return execFileSync('which', [name], { encoding: 'utf-8' }).trim();
+        }
+        catch {
+            // Try the legacy alias next.
+        }
+    }
+    return null;
+}
 export async function daemonCommand(action, options) {
     const port = parseInt(options.port || String(DEFAULT_PROXY_PORT));
     if (isNaN(port) || port < 1 || port > 65535) {
@@ -56,24 +67,20 @@ export async function daemonCommand(action, options) {
                 console.log(chalk.dim(`  Proxy: http://localhost:${port}/api`));
                 return;
             }
-            // Find runcode binary
-            let runcodeBin;
-            try {
-                runcodeBin = execSync('which runcode', { encoding: 'utf-8' }).trim();
-            }
-            catch {
-                console.log(chalk.red('runcode binary not found in PATH.'));
+            const daemonBin = findDaemonBinary();
+            if (!daemonBin) {
+                console.log(chalk.red('franklin binary not found in PATH.'));
                 return;
             }
             fs.mkdirSync(BLOCKRUN_DIR, { recursive: true });
-            const child = spawn(runcodeBin, ['proxy', '--port', String(port)], {
+            const child = spawn(daemonBin, ['proxy', '--port', String(port)], {
                 detached: true,
                 // stdout → /dev/null (banner + startup messages), stderr → log file (debug/errors only)
                 stdio: ['ignore', 'ignore', fs.openSync(LOG_FILE, 'a')],
             });
             child.unref();
             fs.writeFileSync(PID_FILE, String(child.pid));
-            console.log(chalk.green(`✓ runcode daemon started (PID ${child.pid})`));
+            console.log(chalk.green(`✓ franklin daemon started (PID ${child.pid})`));
             console.log(chalk.dim(`  Proxy: http://localhost:${port}/api`));
             console.log(chalk.dim(`  Logs:  ${LOG_FILE}`));
             break;
@@ -81,7 +88,7 @@ export async function daemonCommand(action, options) {
         case 'stop': {
             const pid = readPid();
             if (!pid) {
-                console.log(chalk.yellow('No runcode daemon found.'));
+                console.log(chalk.yellow('No franklin daemon found.'));
                 return;
             }
             if (!isRunning(pid)) {
@@ -104,7 +111,7 @@ export async function daemonCommand(action, options) {
                     fs.unlinkSync(PID_FILE);
                 }
                 catch { /* already gone */ }
-                console.log(chalk.green(`✓ runcode daemon stopped (PID ${pid})`));
+                console.log(chalk.green(`✓ franklin daemon stopped (PID ${pid})`));
             }
             catch (e) {
                 console.log(chalk.red(`Failed to stop daemon: ${e.message}`));
@@ -114,23 +121,23 @@ export async function daemonCommand(action, options) {
         case 'status': {
             const pid = readPid();
             if (!pid) {
-                console.log(chalk.dim('runcode daemon: not running'));
+                console.log(chalk.dim('franklin daemon: not running'));
                 return;
             }
             if (isRunning(pid)) {
-                console.log(chalk.green(`✓ runcode daemon running`));
+                console.log(chalk.green(`✓ franklin daemon running`));
                 console.log(`  PID:   ${chalk.bold(pid)}`);
                 console.log(`  Proxy: ${chalk.cyan(`http://localhost:${port}/api`)}`);
                 console.log(chalk.dim(`  Logs:  ${LOG_FILE}`));
             }
             else {
                 fs.unlinkSync(PID_FILE);
-                console.log(chalk.yellow('runcode daemon: not running (stale PID cleaned up)'));
+                console.log(chalk.yellow('franklin daemon: not running (stale PID cleaned up)'));
             }
             break;
         }
         default:
             console.log(chalk.red(`Unknown daemon action: ${action}`));
-            console.log('Usage: runcode daemon <start|stop|status>');
+            console.log('Usage: franklin daemon <start|stop|status>');
     }
 }

package/dist/commands/plugin.d.ts

@@ -1,7 +1,7 @@
 /**
  * Generic plugin command dispatcher.
  *
- * `runcode <plugin-id> <action>` works for ANY plugin that registers a workflow.
+ * `franklin <plugin-id> <action>` works for ANY plugin that registers a workflow.
  * Core stays plugin-agnostic — adding a new plugin requires zero changes here.
  */
 export interface PluginCommandOptions {

package/dist/commands/plugin.js

@@ -1,7 +1,7 @@
 /**
  * Generic plugin command dispatcher.
  *
- * `runcode <plugin-id> <action>` works for ANY plugin that registers a workflow.
+ * `franklin <plugin-id> <action>` works for ANY plugin that registers a workflow.
  * Core stays plugin-agnostic — adding a new plugin requires zero changes here.
  */
 import chalk from 'chalk';
@@ -49,7 +49,7 @@ export async function pluginCommand(pluginId, action, options) {
                 // No action and already configured: show stats + dry-run hint
                 const stats = getStats(workflow.id);
                 console.log(formatWorkflowStats(workflow, stats));
-                console.log(chalk.dim(`Run "runcode ${pluginId} run --dry" to preview.\n`));
+                console.log(chalk.dim(`Run "franklin ${pluginId} run --dry" to preview.\n`));
             }
             break;
         }
@@ -73,7 +73,7 @@ export async function pluginCommand(pluginId, action, options) {
         case 'leads': {
             const leads = getByAction(workflow.id, 'lead');
             if (leads.length === 0) {
-                console.log(chalk.dim(`\nNo leads found yet. Run "runcode ${pluginId} run" first.\n`));
+                console.log(chalk.dim(`\nNo leads found yet. Run "franklin ${pluginId} run" first.\n`));
                 break;
             }
             console.log(chalk.bold(`\n  LEADS (${leads.length})\n`));
@@ -94,12 +94,12 @@ export async function pluginCommand(pluginId, action, options) {
             console.log(chalk.red(`Unknown action: ${action}`));
             console.log(chalk.dim(`
 Usage:
-  runcode ${pluginId}              # show stats / first-run setup
-  runcode ${pluginId} init         # interactive setup
-  runcode ${pluginId} run          # execute workflow
-  runcode ${pluginId} run --dry    # dry run (no side effects)
-  runcode ${pluginId} stats        # show statistics
-  runcode ${pluginId} leads        # show tracked leads (if applicable)
+  franklin ${pluginId}              # show stats / first-run setup
+  franklin ${pluginId} init         # interactive setup
+  franklin ${pluginId} run          # execute workflow
+  franklin ${pluginId} run --dry    # dry run (no side effects)
+  franklin ${pluginId} stats        # show statistics
+  franklin ${pluginId} leads        # show tracked leads (if applicable)
 `));
     }
 }
@@ -166,7 +166,7 @@ async function runOnboarding(workflow, client) {
         const config = await workflow.buildConfigFromAnswers(answers, llm);
         console.log(chalk.green('  ✓ Configuration saved!\n'));
         console.log(chalk.dim(`  Config: ~/.blockrun/workflows/${workflow.id}.config.json\n`));
-        console.log(chalk.dim(`  Run "runcode ${workflow.id} run --dry" to preview.\n`));
+        console.log(chalk.dim(`  Run "franklin ${workflow.id} run --dry" to preview.\n`));
         return config;
     }
     catch (err) {

package/dist/commands/stats.d.ts

@@ -1,5 +1,5 @@
 /**
- * runcode stats command
+ * franklin stats command
  * Display usage statistics and cost savings
  */
 interface StatsOptions {

package/dist/commands/stats.js

@@ -1,5 +1,5 @@
 /**
- * runcode stats command
+ * franklin stats command
  * Display usage statistics and cost savings
  */
 import chalk from 'chalk';
@@ -90,5 +90,5 @@ export function statsCommand(options) {
         }
     }
     console.log('\n' + '─'.repeat(55));
-    console.log(chalk.gray('  Run `runcode stats --clear` to reset statistics\n'));
+    console.log(chalk.gray('  Run `franklin stats --clear` to reset statistics\n'));
 }

package/dist/index.js

@@ -38,7 +38,7 @@ program
 program
     .command('start')
     .description('Start the franklin agent')
-    .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('-m, --model <model>', 'Model to use (e.g. openai/gpt-5.5, 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)')
@@ -252,7 +252,7 @@ function parseStartFlags(argv, startIdx = 0) {
     }
     return opts;
 }
-// Handle chain shortcuts: `runcode solana` or `runcode base`
+// Handle chain shortcuts: `franklin solana` or `franklin base`
 if (firstArg === 'solana' || firstArg === 'base') {
     if (hasAnyFlag(args, HELP_FLAGS)) {
         program.parse(['node', 'franklin', 'start', '--help']);

package/dist/panel/server.js

@@ -6,8 +6,8 @@
 import http from 'node:http';
 import fs from 'node:fs';
 import path from 'node:path';
-import { BLOCKRUN_DIR, loadChain, saveChain } from '../config.js';
-import { getStatsSummary } from '../stats/tracker.js';
+import { loadChain, saveChain } from '../config.js';
+import { getStatsSummary, getStatsFilePath } from '../stats/tracker.js';
 import { generateInsights } from '../stats/insights.js';
 import { listSessions, loadSessionHistory } from '../session/storage.js';
 import { searchSessions } from '../session/search.js';
@@ -413,10 +413,11 @@ export function createPanelServer(port) {
             console.error('[panel] client error:', err.message);
         }
     });
-    // Watch stats file for changes → push to SSE clients
-    const statsFile = fs.existsSync(path.join(BLOCKRUN_DIR, 'franklin-stats.json'))
-        ? path.join(BLOCKRUN_DIR, 'franklin-stats.json')
-        : path.join(BLOCKRUN_DIR, 'runcode-stats.json');
+    // Watch stats file for changes → push to SSE clients.
+    // getStatsFilePath() also handles the runcode-stats.json → franklin-stats.json
+    // migration on first call, so users coming from the old binary keep their
+    // history without an extra cleanup step.
+    const statsFile = getStatsFilePath();
     if (fs.existsSync(statsFile)) {
         fs.watchFile(statsFile, { interval: 2000 }, () => {
             try {