@blockrun/franklin 3.15.68 → 3.15.69

package/dist/agent/context.js

@@ -315,6 +315,7 @@ function getToolPatternsSection() {
 - **Making changes**: Read the file → Edit with targeted replacement → verify the edit worked (Read again or run tests). Never Edit without Reading first.
 - **Running commands**: Use Bash for shell operations that have no dedicated tool. Chain commands with && when sequential. Use separate Bash calls when you need to inspect intermediate output.
 - **Research**: WebSearch for discovery → WebFetch for specific URLs from search results. Don't WebFetch URLs you invented.
+- **Comparing products / services / APIs** (e.g. "X vs Y, which is better"): start with **WebSearch / ExaSearch / WebFetch** on each vendor's docs/pricing pages. Do NOT \`curl\` the live API as a first move — third-party APIs sit behind WAFs that 401/403/"fault filter abort" on probes, and burning 10+ Bash calls cycling through auth schemes is pure waste. Only hit the live API after public docs have been read AND the user explicitly asked for a hands-on test.
 - **Complex tasks**: Use Agent to spawn sub-agents for 2+ independent research or implementation tasks. Don't do sequentially what can be done in parallel.
 - **Multiple independent lookups**: Call all tools in a single response. NEVER make sequential calls when parallel calls would work.
 - **Long-running iteration (>20 items)**: Use the **Detach** tool, not turn-by-turn loops. Write a script that iterates and persists a checkpoint file (e.g. \`./.franklin/<task>.checkpoint.json\` with cursor + processedCount), then start it via Detach — \`{ label: "scrape stargazers", command: "node fetch.mjs" }\`. Detach returns a runId immediately and the work continues even if Franklin exits. Inspect with \`franklin task tail <runId> --follow\` / \`task wait <runId>\` / \`task cancel <runId>\`. The agent's job is to design and orchestrate, not to be the for-loop. Pattern fits paginated APIs, batch enrichment, large CSV emit, anything where the loop body is deterministic.

package/dist/agent/llm.js

@@ -780,6 +780,36 @@ export class ModelClient {
                 collected.push({ type: 'text', text: currentText });
             }
         }
+        // Fallback: some non-Anthropic providers behind the gateway (e.g. zai/glm-5.1)
+        // emit `message_start` with `output_tokens: 1` as a placeholder and never
+        // send a final `message_delta` carrying the real count. The audit log
+        // then records `outputTokens: 1` for every call in the session even
+        // though the model produced rich tool_use/text content. Verified
+        // 2026-05-05 in a real session: 50 audit rows, 17 distinct multi-line
+        // bash commands, total `output_tokens` summed to 1,154 — most rows
+        // showed 1. We estimate from the collected payload byte length when
+        // the reported count is implausibly low for the actual content.
+        if (usage.outputTokens <= 1 && collected.length > 0) {
+            let bytes = 0;
+            for (const part of collected) {
+                if (part.type === 'text') {
+                    bytes += part.text?.length ?? 0;
+                }
+                else if (part.type === 'tool_use') {
+                    const tu = part;
+                    bytes += (tu.name?.length ?? 0) + JSON.stringify(tu.input ?? {}).length;
+                }
+                else if (part.type === 'thinking') {
+                    bytes += part.thinking?.length ?? 0;
+                }
+            }
+            // ~4 chars/token is a rough but standard tokenizer-agnostic rule.
+            // Only override when the estimate is noticeably larger — otherwise
+            // trust the wire value (a genuinely tiny response should stay tiny).
+            const estimated = Math.ceil(bytes / 4);
+            if (estimated > usage.outputTokens + 5)
+                usage.outputTokens = estimated;
+        }
         return { content: collected, usage, stopReason };
     }
     // ─── Payment ───────────────────────────────────────────────────────────

package/dist/agent/loop.d.ts

@@ -3,6 +3,7 @@
  * The core reasoning-action cycle: prompt → model → extract capabilities → execute → repeat.
  */
 import type { AgentConfig, ContentPart, Dialogue, StreamEvent } from './types.js';
+export declare function isExternalWallFailure(toolName: string, output: string, isError?: boolean): boolean;
 /**
  * Detect when the gateway leaked an upstream rate-limit / quota error as a
  * 200-OK text content block instead of a real HTTP error. The Anthropic

package/dist/agent/loop.js

@@ -46,6 +46,19 @@ import { createSessionId, appendToSession, updateSessionMeta, pruneOldSessions,
 function replaceHistory(target, replacement) {
     target.splice(0, target.length, ...replacement);
 }
+const EXTERNAL_WALL_FAILURE_PATTERN = /\b(?:401|403|429|5\d{2})\b|\bunauthor|\bforbid|\bWAF\b|\bcloudflare\b|\bfault filter\b|\bblocked\b|\binvalid (?:auth|api|token|key|bearer)\b/i;
+export function isExternalWallFailure(toolName, output, isError) {
+    if (toolName === 'WebFetch') {
+        return isError === true || EXTERNAL_WALL_FAILURE_PATTERN.test(output);
+    }
+    if (toolName === 'Bash') {
+        // Bash is a general-purpose local tool. Non-zero exits from tests,
+        // builds, git, etc. are useful debugging signal, not proof that the
+        // model is thrashing against an external auth/firewall wall.
+        return output.length > 0 && EXTERNAL_WALL_FAILURE_PATTERN.test(output);
+    }
+    return false;
+}
 // ─── Pushback detection ───────────────────────────────────────────────────
 // Formerly a pair of regex lists (PUSHBACK_STRONG / PUSHBACK_WEAK) plus a
 // claim-on-prior-turn check — ~70 lines of keyword heuristics. Replaced by
@@ -696,6 +709,10 @@ export async function interactiveSession(config, getUserInput, onEvent, onAbortR
         const serverErrorsByModel = new Map();
         const SERVER_ERROR_STREAK_BEFORE_SWITCH = 2;
         let compactFailures = 0;
+        // Research-bloat compaction is fire-once per turn. A later turn can hit
+        // the trigger organically after the first compact, but firing twice from
+        // the same threshold would flap on every iteration once crossed.
+        let bloatCompactedThisTurn = false;
         let maxTokensOverride;
         const turnIdleReference = lastSessionActivity;
         lastSessionActivity = Date.now();
@@ -754,6 +771,25 @@ export async function interactiveSession(config, getUserInput, onEvent, onAbortR
         // ── No-progress guardrail: kill infinite tiny-response loops ──
         let consecutiveTinyResponses = 0; // Count of consecutive calls with <10 output tokens
         const MAX_TINY_RESPONSES = 2; // Break after N tiny responses — if 2 calls return near-empty, something is wrong
+        // ── Turn cost accumulator ──
+        // Surfaced in cap-exceeded messages so the user sees what the wasted
+        // turn actually cost ("$0.05 spent before this turn was killed") instead
+        // of just "tool limit exceeded". sessionCostUsd is too coarse — it
+        // includes earlier productive turns the user got real value from.
+        let turnCostUsd = 0;
+        // ── Failed-external-call guardrail ──
+        // The signature loop guard only catches exact-input repeats. It misses
+        // "thrashing exploration": model calls Bash 17 different ways trying to
+        // fix a 401 against the same dead endpoint. Verified 2026-05-05 in a
+        // real session: glm-5.1 burned 50 calls / $0.05 trying every auth
+        // variation against api.querit.ai (Cloudflare WAF blocked them all)
+        // before the signature guard finally fired on the first exact repeat.
+        // We count consecutive Bash/WebFetch calls whose output looks like a
+        // network/auth failure; reset on any non-failed external call. Five
+        // failures in a row is a wall, not exploration.
+        let consecutiveFailedExternal = 0;
+        const MAX_CONSECUTIVE_FAILED_EXTERNAL = 5;
+        const EXTERNAL_TOOL_NAMES = new Set(['Bash', 'WebFetch']);
         // ── Turn analysis (one classifier call, drives routing + prefetch) ──
         // Single LLM pass that answers every routing-adjacent question the
         // harness needs BEFORE the main model runs: tier, ticker intent,
@@ -893,6 +929,45 @@ export async function interactiveSession(config, getUserInput, onEvent, onAbortR
                     logger.warn(`[franklin] Compaction failed (${compactFailures}/3): ${compactErr.message}`);
                 }
             }
+            // ── Research-bloat compaction (fires before context-window) ──
+            // The window-based trigger above only fires near 172K tokens for a
+            // 200K-context model. Research sessions burn money long before that:
+            // verified 2026-05-05 in a real audit, a glm-5.1 session hit
+            // $0.18 / 177 calls / 3.17M cumulative input — average per-call input
+            // grew to 17.9K because every tool result kept replaying. Top-spend
+            // session in the same log: $6.67 on gemini-2.5-flash in 121 calls,
+            // never approached its 1M-token compaction threshold. Compact here
+            // when the turn has accumulated lots of tool calls AND real spend,
+            // even though the context window isn't close to full.
+            if (!bloatCompactedThisTurn &&
+                compactFailures < 3 &&
+                turnToolCalls > 30 &&
+                turnCostUsd > 0.05) {
+                try {
+                    const beforeTokens = estimateHistoryTokens(history);
+                    const { history: compacted, compacted: didCompact } = await forceCompact(history, config.model, client, config.debug);
+                    if (didCompact) {
+                        replaceHistory(history, compacted);
+                        resetTokenAnchor();
+                        bloatCompactedThisTurn = true;
+                        const afterTokens = estimateHistoryTokens(history);
+                        const pct = beforeTokens > 0
+                            ? Math.round((1 - afterTokens / beforeTokens) * 100)
+                            : 0;
+                        onEvent({
+                            kind: 'text_delta',
+                            text: `\n*🗜 Research-bloat compact: ${turnToolCalls} tool calls / $${turnCostUsd.toFixed(4)} this turn — summarizing ~${(beforeTokens / 1000).toFixed(0)}K → ~${(afterTokens / 1000).toFixed(0)}K tokens (saved ${pct}%)*\n\n`,
+                        });
+                        logger.info(`[franklin] Research-bloat compacted at ${turnToolCalls} calls / $${turnCostUsd.toFixed(4)}: ~${afterTokens} tokens`);
+                    }
+                }
+                catch (compactErr) {
+                    // Don't increment compactFailures — that gate is for the
+                    // window-based path. A failed bloat compact just means we keep
+                    // going at the higher per-call cost; not catastrophic.
+                    logger.warn(`[franklin] Bloat compaction failed: ${compactErr.message}`);
+                }
+            }
             // Inject ultrathink instruction when mode is active
             const systemParts = [...config.systemInstructions];
             if (config.ultrathink) {
@@ -1432,6 +1507,7 @@ export async function interactiveSession(config, getUserInput, onEvent, onAbortR
             sessionInputTokens += inputTokens;
             sessionOutputTokens += usage.outputTokens;
             sessionCostUsd += costEstimate;
+            turnCostUsd += costEstimate;
             const opusCost = (inputTokens / 1_000_000) * OPUS_PRICING.input
                 + (usage.outputTokens / 1_000_000) * OPUS_PRICING.output;
             sessionSavedVsOpus += Math.max(0, opusCost - costEstimate);
@@ -1661,7 +1737,7 @@ export async function interactiveSession(config, getUserInput, onEvent, onAbortR
             }
             // ── Tool call guardrails ──
             turnToolCalls += results.length;
-            for (const [inv] of results) {
+            for (const [inv, result] of results) {
                 const name = inv.name;
                 turnToolCounts.set(name, (turnToolCounts.get(name) || 0) + 1);
                 // Track (tool, input)-signature for the loop detector below.
@@ -1674,6 +1750,16 @@ export async function interactiveSession(config, getUserInput, onEvent, onAbortR
                 if (name === 'Read' && inv.input.file_path) {
                     readFileCache.add(inv.input.file_path);
                 }
+                // Failed-external-call streak: count consecutive Bash/WebFetch calls
+                // whose output indicates a network/auth wall. Reset on any non-failed
+                // external call so legitimate retry-then-succeed paths aren't punished.
+                if (EXTERNAL_TOOL_NAMES.has(name)) {
+                    const looksFailed = isExternalWallFailure(name, typeof result.output === 'string' ? result.output : '', result.isError);
+                    if (looksFailed)
+                        consecutiveFailedExternal++;
+                    else
+                        consecutiveFailedExternal = 0;
+                }
             }
             // Refresh activity timestamp after tool execution
             lastSessionActivity = Date.now();
@@ -1807,11 +1893,17 @@ export async function interactiveSession(config, getUserInput, onEvent, onAbortR
                 toolCapWarned = true;
                 logger.warn(`[franklin] Tool call cap hit: ${turnToolCalls} calls this turn (soft cap ${MAX_TOOL_CALLS_PER_TURN}, hard cap ${HARD_TOOL_CAP})`);
             }
+            // Format spend-so-far for cap messages — surfacing the dollar amount
+            // tells the user the real impact ("$0.05 wasted") instead of just
+            // "tool limit exceeded" which doesn't convey severity.
+            const spendNote = turnCostUsd > 0
+                ? `${turnToolCalls} tool calls, $${turnCostUsd.toFixed(4)} spent this turn`
+                : `${turnToolCalls} tool calls this turn`;
             if (turnToolCalls >= HARD_TOOL_CAP) {
                 logger.error(`[franklin] Hard tool cap exceeded (${turnToolCalls}) — ending turn to prevent runaway`);
                 onEvent({
                     kind: 'text_delta',
-                    text: `\n\n⚠️ Tool call limit exceeded (${turnToolCalls}/${HARD_TOOL_CAP}). Ending turn to prevent runaway loop. Try rephrasing or use \`/model\` to switch.\n`,
+                    text: `\n\n⚠️ Runaway loop stopped: ${spendNote}, hit hard cap of ${HARD_TOOL_CAP}. Try rephrasing or use \`/model\` to switch.\n`,
                 });
                 onEvent({ kind: 'turn_done', reason: 'cap_exceeded' });
                 break;
@@ -1829,7 +1921,22 @@ export async function interactiveSession(config, getUserInput, onEvent, onAbortR
                 logger.error(`[franklin] Signature-loop hard stop: \`${toolName}\` called with identical input ${stuckSignature.count} times this turn — ending turn`);
                 onEvent({
                     kind: 'text_delta',
-                    text: `\n\n⚠️ ${toolName} called ${stuckSignature.count}× with the same input this turn — that's a real loop, not exploration. Ending turn. Rephrase what you actually need, or try \`/model\` to switch.\n`,
+                    text: `\n\n⚠️ Loop stopped: ${spendNote} before \`${toolName}\` repeated the same input ${stuckSignature.count}×. Rephrase what you need, or try \`/model\` to switch.\n`,
+                });
+                onEvent({ kind: 'turn_done', reason: 'cap_exceeded' });
+                break;
+            }
+            // Thrashing-against-a-wall hard stop (3.15.69). Catches the case
+            // where each call is structurally distinct (different headers, methods,
+            // auth schemes, query params) but every one returns 4xx/5xx/WAF.
+            // Verified 2026-05-05: glm-5.1 burned 50 calls / $0.05 cycling through
+            // ~17 curl variants against Cloudflare-blocked api.querit.ai — every
+            // input distinct so the signature guard above couldn't help.
+            if (consecutiveFailedExternal >= MAX_CONSECUTIVE_FAILED_EXTERNAL) {
+                logger.error(`[franklin] Failed-external-call streak: ${consecutiveFailedExternal} consecutive Bash/WebFetch calls returned auth/network errors — ending turn`);
+                onEvent({
+                    kind: 'text_delta',
+                    text: `\n\n⚠️ Hitting a wall: ${consecutiveFailedExternal} consecutive external calls returned auth/firewall errors (${spendNote}). The endpoint or credentials likely don't work. Try a different approach, or use \`/model\` to switch.\n`,
                 });
                 onEvent({ kind: 'turn_done', reason: 'cap_exceeded' });
                 break;

package/dist/commands/migrate.js

@@ -16,18 +16,42 @@ function detectSources() {
     const sources = [];
     const home = os.homedir();
     // ── `~/.claude/` config dir (used by several agent CLIs) ──
+    // Real Claude Code (2026 layout) writes:
+    //   ~/.claude.json                       (top-level, mcpServers + global state)
+    //   ~/.claude/CLAUDE.md                  (global instructions)
+    //   ~/.claude/projects/<slug>/<uuid>.jsonl  (one file per session)
+    //   ~/.claude/projects/<slug>/memory/*.md   (project memories)
+    // Older agents and pre-3.x Claude Code variants wrote:
+    //   ~/.claude/mcp.json
+    //   ~/.claude/history.jsonl
+    // We support both — prefer the new layout but fall back so users with
+    // legacy state still get their data imported.
     const claudeDir = path.join(home, '.claude');
-    if (fs.existsSync(claudeDir)) {
+    const claudeJson = path.join(home, '.claude.json');
+    const hasClaudeData = fs.existsSync(claudeDir) || fs.existsSync(claudeJson);
+    if (hasClaudeData) {
         const items = [];
-        // MCP servers
-        const claudeMcp = path.join(claudeDir, 'mcp.json');
-        if (fs.existsSync(claudeMcp)) {
+        // MCP servers — prefer top-level ~/.claude.json (new layout); fall back
+        // to legacy ~/.claude/mcp.json. Only add one item; whichever we find
+        // first is what migrateMcp() will read.
+        const newMcpHasServers = fileHasMcpServers(claudeJson);
+        const legacyMcp = path.join(claudeDir, 'mcp.json');
+        if (newMcpHasServers) {
             items.push({
-                label: 'MCP servers',
-                source: claudeMcp,
+                label: 'MCP servers (~/.claude.json)',
+                source: claudeJson,
                 target: path.join(BLOCKRUN_DIR, 'mcp.json'),
-                size: fileSize(claudeMcp),
-                transform: () => migrateMcp(claudeMcp),
+                size: fileSize(claudeJson),
+                transform: () => migrateMcp(claudeJson),
+            });
+        }
+        else if (fs.existsSync(legacyMcp)) {
+            items.push({
+                label: 'MCP servers (legacy ~/.claude/mcp.json)',
+                source: legacyMcp,
+                target: path.join(BLOCKRUN_DIR, 'mcp.json'),
+                size: fileSize(legacyMcp),
+                transform: () => migrateMcp(legacyMcp),
             });
         }
         // Global instructions → learnings
@@ -41,20 +65,33 @@ function detectSources() {
                 transform: () => migrateInstructions(claudeMd),
             });
         }
-        // Session history
-        const claudeHistory = path.join(claudeDir, 'history.jsonl');
-        if (fs.existsSync(claudeHistory)) {
-            const lines = countLines(claudeHistory);
+        // Session history — prefer per-project session JSONLs (new layout); fall
+        // back to legacy ~/.claude/history.jsonl. The new layout preserves session
+        // boundaries (one file = one conversation) instead of collapsing every
+        // message into a daily blob.
+        const projectsDir = path.join(claudeDir, 'projects');
+        const sessionFiles = fs.existsSync(projectsDir) ? findClaudeCodeSessionFiles(projectsDir) : [];
+        const legacyHistory = path.join(claudeDir, 'history.jsonl');
+        if (sessionFiles.length > 0) {
             items.push({
-                label: `Session history (${lines.toLocaleString()} messages)`,
-                source: claudeHistory,
+                label: `Session history (${sessionFiles.length.toLocaleString()} sessions)`,
+                source: projectsDir,
                 target: path.join(BLOCKRUN_DIR, 'sessions'),
-                size: fileSize(claudeHistory),
-                transform: () => migrateSessions(claudeHistory),
+                size: `${sessionFiles.length} files`,
+                transform: () => migrateClaudeCodeSessions(sessionFiles),
+            });
+        }
+        else if (fs.existsSync(legacyHistory)) {
+            const lines = countLines(legacyHistory);
+            items.push({
+                label: `Session history (legacy, ${lines.toLocaleString()} messages)`,
+                source: legacyHistory,
+                target: path.join(BLOCKRUN_DIR, 'sessions'),
+                size: fileSize(legacyHistory),
+                transform: () => migrateSessions(legacyHistory),
             });
         }
         // Project memory files
-        const projectsDir = path.join(claudeDir, 'projects');
         if (fs.existsSync(projectsDir)) {
             const memoryFiles = findMemoryFiles(projectsDir);
             if (memoryFiles.length > 0) {
@@ -95,7 +132,10 @@ function detectSources() {
 function migrateMcp(source) {
     const target = path.join(BLOCKRUN_DIR, 'mcp.json');
     const raw = JSON.parse(fs.readFileSync(source, 'utf-8'));
-    // Source format:  { mcpServers: { name: { command, args, env } } }
+    // Source format (Claude Code ~/.claude.json or legacy mcp.json):
+    //   { mcpServers: { name: { type?, transport?, command, args, env? } } }
+    //   ~/.claude.json wraps mcpServers among hundreds of unrelated state keys —
+    //   we only read the one field.
     // Franklin format: { mcpServers: { name: { transport, command, args, label } } }
     const servers = {};
     const skipped = [];
@@ -121,7 +161,8 @@ function migrateMcp(source) {
                 continue;
             }
             servers[name] = {
-                transport: config.transport || 'stdio',
+                // Claude Code uses `type`; older agents used `transport`. Accept both.
+                transport: config.transport || config.type || 'stdio',
                 command: config.command,
                 args: config.args || [],
                 label: name,
@@ -199,6 +240,143 @@ function migrateInstructions(source) {
         console.log(chalk.dim('    ○ No extractable preferences found'));
     }
 }
+/**
+ * Import per-session JSONL files written by current Claude Code (2026 layout).
+ * One source file = one Franklin session — we preserve session boundaries
+ * instead of mashing everything into a daily blob like the legacy importer.
+ *
+ * Source line shape:
+ *   { type: "user"|"assistant"|"attachment"|"permission-mode"|...,
+ *     message?: { role, content }, timestamp, sessionId, cwd }
+ * Target Dialogue line shape: { role, content }
+ */
+function migrateClaudeCodeSessions(sessionFiles) {
+    const sessionsDir = path.join(BLOCKRUN_DIR, 'sessions');
+    fs.mkdirSync(sessionsDir, { recursive: true });
+    let imported = 0;
+    let skipped = 0;
+    let totalTurns = 0;
+    for (const file of sessionFiles) {
+        const sessionId = path.basename(file, '.jsonl');
+        const targetJsonl = path.join(sessionsDir, `${sessionId}.jsonl`);
+        const targetMeta = path.join(sessionsDir, `${sessionId}.meta.json`);
+        // Don't re-import on a second run — the user might have already
+        // resumed and added turns to the imported session.
+        if (fs.existsSync(targetMeta)) {
+            skipped++;
+            continue;
+        }
+        let raw;
+        try {
+            raw = fs.readFileSync(file, 'utf-8');
+        }
+        catch {
+            continue;
+        }
+        const dialogues = [];
+        let firstTs = 0;
+        let lastTs = 0;
+        let workDir = os.homedir();
+        let model = 'claude-code-import';
+        for (const line of raw.split('\n')) {
+            const trimmed = line.trim();
+            if (!trimmed)
+                continue;
+            let entry;
+            try {
+                entry = JSON.parse(trimmed);
+            }
+            catch {
+                continue;
+            }
+            // Track timestamps + cwd from any line that has them.
+            const ts = entry.timestamp;
+            if (typeof ts === 'string') {
+                const t = Date.parse(ts);
+                if (Number.isFinite(t)) {
+                    if (!firstTs || t < firstTs)
+                        firstTs = t;
+                    if (t > lastTs)
+                        lastTs = t;
+                }
+            }
+            if (typeof entry.cwd === 'string' && entry.cwd)
+                workDir = entry.cwd;
+            // Only user/assistant turns become Franklin Dialogue lines. Everything
+            // else (attachments, permission-mode, summary, system) is metadata
+            // we don't replay.
+            if (entry.type !== 'user' && entry.type !== 'assistant')
+                continue;
+            const msg = entry.message;
+            if (!msg || (msg.role !== 'user' && msg.role !== 'assistant'))
+                continue;
+            if (typeof msg.model === 'string')
+                model = msg.model;
+            dialogues.push(JSON.stringify({ role: msg.role, content: msg.content }));
+        }
+        if (dialogues.length === 0) {
+            skipped++;
+            continue;
+        }
+        fs.writeFileSync(targetJsonl, dialogues.join('\n') + '\n');
+        fs.writeFileSync(targetMeta, JSON.stringify({
+            id: sessionId,
+            model,
+            workDir,
+            createdAt: firstTs || Date.now(),
+            updatedAt: lastTs || Date.now(),
+            turnCount: Math.floor(dialogues.length / 2),
+            messageCount: dialogues.length,
+            imported: true,
+        }, null, 2));
+        imported++;
+        totalTurns += dialogues.length;
+    }
+    const skipNote = skipped > 0 ? chalk.dim(` (${skipped} skipped)`) : '';
+    console.log(chalk.green(`    ✓ ${imported} session(s) imported, ${totalTurns.toLocaleString()} turns${skipNote}`));
+}
+/** Walk ~/.claude/projects/<slug>/*.jsonl — one file per Claude Code session. */
+function findClaudeCodeSessionFiles(projectsDir) {
+    const out = [];
+    let projects = [];
+    try {
+        projects = fs.readdirSync(projectsDir);
+    }
+    catch {
+        return out;
+    }
+    for (const project of projects) {
+        const projectPath = path.join(projectsDir, project);
+        let entries = [];
+        try {
+            const stat = fs.statSync(projectPath);
+            if (!stat.isDirectory())
+                continue;
+            entries = fs.readdirSync(projectPath);
+        }
+        catch {
+            continue;
+        }
+        for (const entry of entries) {
+            if (!entry.endsWith('.jsonl'))
+                continue;
+            out.push(path.join(projectPath, entry));
+        }
+    }
+    return out;
+}
+/** True iff the file is JSON with a non-empty mcpServers object. */
+function fileHasMcpServers(p) {
+    try {
+        const raw = JSON.parse(fs.readFileSync(p, 'utf-8'));
+        return !!raw && typeof raw === 'object' &&
+            !!raw.mcpServers && typeof raw.mcpServers === 'object' &&
+            Object.keys(raw.mcpServers).length > 0;
+    }
+    catch {
+        return false;
+    }
+}
 function migrateSessions(source) {
     const sessionsDir = path.join(BLOCKRUN_DIR, 'sessions');
     fs.mkdirSync(sessionsDir, { recursive: true });
@@ -231,7 +409,9 @@ function migrateSessions(source) {
         if (fs.existsSync(sessionFile))
             continue;
         fs.writeFileSync(sessionFile, msgs.join('\n') + '\n');
-        // Create metadata
+        // Create metadata. `imported: true` shields these from pruneOldSessions —
+        // a fresh import of 200+ historical sessions would otherwise be deleted
+        // on the next `franklin` launch when the agent loop prunes to 20.
         const meta = {
             id: sessionId,
             model: 'imported',
@@ -240,6 +420,7 @@ function migrateSessions(source) {
             updatedAt: Date.now(),
             turnCount: Math.floor(msgs.length / 2),
             messageCount: msgs.length,
+            imported: true,
         };
         fs.writeFileSync(path.join(sessionsDir, `${sessionId}.meta.json`), JSON.stringify(meta, null, 2));
         imported++;
@@ -340,7 +521,7 @@ export async function migrateCommand() {
     const sources = detectSources();
     if (sources.length === 0) {
         console.log(chalk.dim('  No other AI tools detected. Nothing to migrate.\n'));
-        console.log(chalk.dim('  Looked for: ~/.claude/, VS Code agent extension, editor agent configs\n'));
+        console.log(chalk.dim('  Looked for: ~/.claude.json, ~/.claude/, VS Code agent extension, editor agent configs\n'));
         return;
     }
     // Show what was found

package/dist/plugins/registry.d.ts

@@ -2,10 +2,12 @@
  * Plugin Registry — discovers, loads, and manages plugins.
  *
  * Core stays plugin-agnostic: it knows about the *interface*, not specific plugins.
- * Plugins are discovered from:
- *   1. Bundled: <franklin>/plugins-bundled/* (ships with Franklin)
+ * Plugins are discovered from (highest priority first):
+ *   1. Local dev: $FRANKLIN_PLUGINS_DIR/* (or legacy $RUNCODE_PLUGINS_DIR/*)
  *   2. User: ~/.blockrun/plugins/*
- *   3. Local dev: $FRANKLIN_PLUGINS_DIR/* (or legacy $RUNCODE_PLUGINS_DIR/*)
+ *   3. Bundled: <franklin>/dist/plugins-bundled/* (reserved for plugins
+ *      shipped inside the npm tarball — none today; social/trading/content
+ *      are native subsystems, not plugins)
  */
 import type { Plugin, PluginManifest } from '../plugin-sdk/plugin.js';
 export declare function getBundledPluginsDir(): string;

package/dist/plugins/registry.js

@@ -2,10 +2,12 @@
  * Plugin Registry — discovers, loads, and manages plugins.
  *
  * Core stays plugin-agnostic: it knows about the *interface*, not specific plugins.
- * Plugins are discovered from:
- *   1. Bundled: <franklin>/plugins-bundled/* (ships with Franklin)
+ * Plugins are discovered from (highest priority first):
+ *   1. Local dev: $FRANKLIN_PLUGINS_DIR/* (or legacy $RUNCODE_PLUGINS_DIR/*)
  *   2. User: ~/.blockrun/plugins/*
- *   3. Local dev: $FRANKLIN_PLUGINS_DIR/* (or legacy $RUNCODE_PLUGINS_DIR/*)
+ *   3. Bundled: <franklin>/dist/plugins-bundled/* (reserved for plugins
+ *      shipped inside the npm tarball — none today; social/trading/content
+ *      are native subsystems, not plugins)
  */
 import fs from 'node:fs';
 import path from 'node:path';
@@ -14,8 +16,9 @@ import os from 'node:os';
 const __dirname = path.dirname(fileURLToPath(import.meta.url));
 // ─── Plugin Discovery Paths ───────────────────────────────────────────────
 export function getBundledPluginsDir() {
-    // From dist/plugins/registry.js, plugins-bundled is at ../plugins-bundled
-    // (built from src/plugins-bundled by tsc + copy-plugin-assets)
+    // From dist/plugins/registry.js, look at sibling dist/plugins-bundled/.
+    // Empty today — the build's copy-plugin-assets script populates it from
+    // src/plugins-bundled/ if/when bundled plugins are reintroduced.
     return path.resolve(__dirname, '..', 'plugins-bundled');
 }
 export function getUserPluginsDir() {

package/dist/session/storage.d.ts

@@ -42,6 +42,15 @@ export interface SessionMeta {
      * add any tool inputs or outputs here, just the count per tool name.
      */
     toolCallCounts?: Record<string, number>;
+    /**
+     * Sessions imported from another agent (`franklin migrate`). Imports often
+     * exceed MAX_SESSIONS by an order of magnitude (a Claude Code user can
+     * easily have 200+ historical sessions); without this flag, the very
+     * next `franklin` launch would prune all but the 20 most recent and
+     * silently destroy the user's history. pruneOldSessions() skips any
+     * meta with imported=true.
+     */
+    imported?: true;
 }
 /** Get the absolute path to a session's JSONL file (for external readers like search). */
 export declare function getSessionFilePath(id: string): string;

package/dist/session/storage.js

@@ -132,6 +132,11 @@ export function updateSessionMeta(sessionId, meta) {
             ...(meta.toolCallCounts !== undefined || existing?.toolCallCounts !== undefined
                 ? { toolCallCounts: meta.toolCallCounts ?? existing?.toolCallCounts }
                 : {}),
+            // `imported` is sticky like `chain`: once set by `franklin migrate`
+            // it must survive every subsequent update so pruneOldSessions keeps
+            // shielding the session from auto-deletion. Without preservation, the
+            // first turn added via `--resume` would silently drop the flag.
+            ...(meta.imported || existing?.imported ? { imported: true } : {}),
         };
         // Atomic write: tmp file + rename. Prevents corruption when parent
         // and sub-agent update the same session meta concurrently.
@@ -234,10 +239,12 @@ export function findLatestSessionByChannel(channel) {
  * Accepts optional activeSessionId to protect from deletion.
  */
 export function pruneOldSessions(activeSessionId) {
-    const sessions = readSessionMetas(false);
-    const allSessions = readSessionMetas(true);
-    if (sessions.length > MAX_SESSIONS) {
-        const toDelete = sessions
+    // Only count native sessions toward the MAX_SESSIONS budget. Imported
+    // sessions (from `franklin migrate`) are user-owned history and must
+    // never be auto-deleted just because the user ran the agent again.
+    const native = readSessionMetas(false).filter(s => !s.imported);
+    if (native.length > MAX_SESSIONS) {
+        const toDelete = native
             .slice(MAX_SESSIONS)
             .filter(s => s.id !== activeSessionId); // Never delete active session
         for (const s of toDelete) {
@@ -251,11 +258,16 @@ export function pruneOldSessions(activeSessionId) {
             catch { /* ok */ }
         }
     }
-    // Also clean up ghost sessions (0 messages, older than 5 minutes)
+    // Also clean up ghost sessions (0 messages, older than 5 minutes).
+    // Skip imported sessions — they may legitimately have messageCount=0
+    // if the source file had only attachments/system lines.
     const fiveMinAgo = Date.now() - 5 * 60 * 1000;
+    const allSessions = readSessionMetas(true);
     for (const s of allSessions) {
         if (s.id === activeSessionId)
             continue;
+        if (s.imported)
+            continue;
         if (s.messageCount === 0 && s.createdAt < fiveMinAgo) {
             try {
                 fs.unlinkSync(sessionPath(s.id));

package/package.json

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