@blockrun/franklin 3.15.30 → 3.15.32

package/dist/agent/loop.js

@@ -448,7 +448,18 @@ export async function interactiveSession(config, getUserInput, onEvent, onAbortR
         persistSessionMeta();
     };
     pruneOldSessions(sessionId); // Cleanup old sessions on start, protect current
-    runDataHygiene(); // Trim ~/.blockrun/data + cost_log + remove legacy files
+    // Trim ~/.blockrun/data + cost_log + remove legacy files + sweep
+    // orphan tool-results dirs. Logs a summary if anything was actually
+    // touched — pre-3.15.31 hygiene was completely silent and the only
+    // way to verify it was running was poking disk yourself.
+    const hygieneReport = runDataHygiene();
+    const totalCleaned = hygieneReport.legacyFilesRemoved +
+        hygieneReport.dataFilesTrimmed +
+        hygieneReport.costLogRowsTrimmed +
+        hygieneReport.orphanToolResultsRemoved;
+    if (totalCleaned > 0) {
+        logger.info(`[franklin] Data hygiene: ${hygieneReport.legacyFilesRemoved} legacy, ${hygieneReport.dataFilesTrimmed} data files, ${hygieneReport.costLogRowsTrimmed} cost_log rows, ${hygieneReport.orphanToolResultsRemoved} orphan tool-results dirs cleaned`);
+    }
     persistSessionMeta();
     // Flush session meta on SIGINT/SIGTERM so mid-stream Ctrl+C doesn't
     // leave a stale .meta.json (wrong turnCount/messageCount/cost).

package/dist/agent/streaming-executor.js

@@ -7,6 +7,7 @@ import { mkdirSync, writeFileSync } from 'node:fs';
 import { join } from 'node:path';
 import { recordFailure } from '../stats/failures.js';
 import { BLOCKRUN_DIR } from '../config.js';
+import { logger } from '../logger.js';
 /** Persist a large tool result to disk and return a preview string. */
 const PERSIST_THRESHOLD = 50_000;
 const PREVIEW_SIZE = 2_000;
@@ -205,8 +206,22 @@ export class StreamingExecutor {
                     }
                 }
             }
+            // Track elapsed for slow-tool forensics. Verified 2026-05-04
+            // from a real session: a 337.6s Bash error left no trace in
+            // franklin-debug.log — the user could see the ✗ in the UI but
+            // had no post-hoc way to ask "which Bash took 5+ minutes
+            // yesterday and what did it run". 30s threshold is conservative
+            // (Read/Glob/Grep finish in <1s; only network or shell work
+            // crosses).
+            const execStart = Date.now();
             let result = await handler.execute(invocation.input, progressScope);
             this.guard?.afterExecute(invocation, result);
+            const execElapsed = Date.now() - execStart;
+            if (execElapsed >= 30_000) {
+                const status = result.isError ? 'error' : 'ok';
+                const preview = this.inputPreview(invocation) || '';
+                logger.info(`[franklin] Slow tool: ${invocation.name} ${status} after ${(execElapsed / 1000).toFixed(1)}s${preview ? ` — ${preview.slice(0, 80)}` : ''}`);
+            }
             // Persist large results to disk with preview.
             // Instead of just truncating, save the full result to disk so it can be re-read later.
             if (result.output.length > PERSIST_THRESHOLD) {
@@ -219,15 +234,22 @@ export class StreamingExecutor {
         }
         catch (err) {
             this.guard?.cancelInvocation(invocation.id);
+            const errMsg = err.message;
             recordFailure({
                 timestamp: Date.now(),
                 model: '', // not available at tool level
                 failureType: 'tool_error',
                 toolName: invocation.name,
-                errorMessage: err.message,
+                errorMessage: errMsg,
             });
+            // Always log thrown tool errors. Pre-3.15.32 these went only to
+            // failures.jsonl (which the user rarely opens) and were absent
+            // from franklin-debug.log entirely. Now `franklin logs` shows
+            // them alongside everything else.
+            const preview = this.inputPreview(invocation) || '';
+            logger.warn(`[franklin] Tool error: ${invocation.name} threw "${errMsg.slice(0, 120)}"${preview ? ` — ${preview.slice(0, 80)}` : ''}`);
             return {
-                output: `Error executing ${invocation.name}: ${err.message}`,
+                output: `Error executing ${invocation.name}: ${errMsg}`,
                 isError: true,
             };
         }

package/dist/storage/hygiene.d.ts

@@ -21,8 +21,23 @@
  * unlinkSync). Best-effort: every operation is wrapped so a single failure
  * never breaks agent boot.
  */
+/**
+ * Summary of what hygiene removed/trimmed in one pass. Returned so the
+ * caller (agent loop) can log it — silent hygiene is hard to verify
+ * without poking at disk yourself, which is exactly the kind of thing
+ * users shouldn't have to do.
+ */
+export interface HygieneReport {
+    legacyFilesRemoved: number;
+    dataFilesTrimmed: number;
+    costLogRowsTrimmed: number;
+    orphanToolResultsRemoved: number;
+}
 /**
  * Top-level entry. Call once at agent session start. Catches its own
- * errors so a bad disk never blocks startup.
+ * errors so a bad disk never blocks startup. Returns counts so callers
+ * can log a one-line summary — verified 2026-05-04 from a real session
+ * where hygiene was running silently for hours and there was no way to
+ * tell from the log whether anything was being cleaned.
  */
-export declare function runDataHygiene(): void;
+export declare function runDataHygiene(): HygieneReport;

package/dist/storage/hygiene.js

@@ -44,35 +44,46 @@ const LEGACY_FILENAMES = [
     '0xcode-stats.json',
     'runcode-debug.log',
 ];
+const ZERO_REPORT = {
+    legacyFilesRemoved: 0,
+    dataFilesTrimmed: 0,
+    costLogRowsTrimmed: 0,
+    orphanToolResultsRemoved: 0,
+};
 /**
  * Top-level entry. Call once at agent session start. Catches its own
- * errors so a bad disk never blocks startup.
+ * errors so a bad disk never blocks startup. Returns counts so callers
+ * can log a one-line summary — verified 2026-05-04 from a real session
+ * where hygiene was running silently for hours and there was no way to
+ * tell from the log whether anything was being cleaned.
  */
 export function runDataHygiene() {
+    const report = { ...ZERO_REPORT };
     try {
-        trimDataDir();
+        report.dataFilesTrimmed = trimDataDir();
     }
     catch { /* best effort */ }
     try {
-        trimCostLog();
+        report.costLogRowsTrimmed = trimCostLog();
     }
     catch { /* best effort */ }
     try {
-        removeLegacyFiles();
+        report.legacyFilesRemoved = removeLegacyFiles();
     }
     catch { /* best effort */ }
     try {
-        sweepOrphanToolResults();
+        report.orphanToolResultsRemoved = sweepOrphanToolResults();
     }
     catch { /* best effort */ }
+    return report;
 }
 function trimDataDir() {
     const dir = path.join(BLOCKRUN_DIR, 'data');
     if (!fs.existsSync(dir))
-        return;
+        return 0;
     const entries = fs.readdirSync(dir);
     if (entries.length === 0)
-        return;
+        return 0;
     const cutoff = Date.now() - DATA_DIR_MAX_AGE_MS;
     const stats = [];
     for (const name of entries) {
@@ -86,11 +97,13 @@ function trimDataDir() {
             // Best effort — skip unreadable entries.
         }
     }
+    let removed = 0;
     // Pass 1: age-based delete.
     for (const e of stats) {
         if (e.mtime < cutoff) {
             try {
                 fs.unlinkSync(path.join(dir, e.name));
+                removed++;
             }
             catch { /* ok */ }
         }
@@ -106,35 +119,42 @@ function trimDataDir() {
         for (let i = 0; i < excess; i++) {
             try {
                 fs.unlinkSync(path.join(dir, survivors[i].name));
+                removed++;
             }
             catch { /* ok */ }
         }
     }
+    return removed;
 }
 function trimCostLog() {
     const file = path.join(BLOCKRUN_DIR, 'cost_log.jsonl');
     if (!fs.existsSync(file))
-        return;
+        return 0;
     // Cheap probe — skip the full read+rewrite when the file is small.
     const stat = fs.statSync(file);
     if (stat.size < COST_LOG_PROBE_BYTES)
-        return;
+        return 0;
     const lines = fs.readFileSync(file, 'utf-8').split('\n').filter(Boolean);
     if (lines.length <= COST_LOG_MAX_ENTRIES)
-        return;
+        return 0;
+    const dropped = lines.length - COST_LOG_MAX_ENTRIES;
     const kept = lines.slice(lines.length - COST_LOG_MAX_ENTRIES);
     fs.writeFileSync(file, kept.join('\n') + '\n');
+    return dropped;
 }
 function removeLegacyFiles() {
+    let removed = 0;
     for (const name of LEGACY_FILENAMES) {
         const p = path.join(BLOCKRUN_DIR, name);
         if (!fs.existsSync(p))
             continue;
         try {
             fs.unlinkSync(p);
+            removed++;
         }
         catch { /* ok */ }
     }
+    return removed;
 }
 /**
  * `streaming-executor` writes large tool outputs to
@@ -151,7 +171,7 @@ function sweepOrphanToolResults() {
     const toolResultsDir = path.join(BLOCKRUN_DIR, 'tool-results');
     const sessionsDir = path.join(BLOCKRUN_DIR, 'sessions');
     if (!fs.existsSync(toolResultsDir))
-        return;
+        return 0;
     const knownSessionIds = new Set();
     if (fs.existsSync(sessionsDir)) {
         try {
@@ -165,7 +185,7 @@ function sweepOrphanToolResults() {
             // Best-effort — if we can't read sessions/, skip the sweep so
             // we never delete tool-results that might still belong to a
             // live session.
-            return;
+            return 0;
         }
     }
     let entries;
@@ -173,8 +193,9 @@ function sweepOrphanToolResults() {
         entries = fs.readdirSync(toolResultsDir);
     }
     catch {
-        return;
+        return 0;
     }
+    let removed = 0;
     for (const name of entries) {
         if (knownSessionIds.has(name))
             continue;
@@ -184,9 +205,11 @@ function sweepOrphanToolResults() {
             if (!stat.isDirectory())
                 continue;
             fs.rmSync(dir, { recursive: true, force: true });
+            removed++;
         }
         catch {
             // Skip — best-effort cleanup.
         }
     }
+    return removed;
 }

package/package.json

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