@blockrun/franklin 3.9.5 → 3.10.0

package/dist/agent/context.js

@@ -174,6 +174,7 @@ function getToolPatternsSection() {
 - **Research**: WebSearch for discovery → WebFetch for specific URLs from search results. Don't WebFetch URLs you invented.
 - **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.
 
 # Grounding Before Answering
 Your training data is frozen in the past. Live-world questions MUST be answered from tool results, not memory.

package/dist/agent/llm.js

@@ -14,9 +14,18 @@ function parseTimeoutEnv(name) {
     return Number.isFinite(parsed) && parsed >= 0 ? parsed : null;
 }
 function getModelRequestTimeoutMs() {
+    // 180s budget for *time-to-headers* (the gateway flushes SSE headers only
+    // once the upstream model emits its first token). Reasoning-class models
+    // (zai/glm-*, nemotron *-reasoning, deepseek-r*, gpt-5-codex, anthropic
+    // extended-thinking) routinely take 60–120s to first token on cache-cold
+    // prompts or when the gateway is under load — the old 45s default cut
+    // those off and wasted USDC on retries that hit the same wall. 180s is
+    // generous enough for any realistic first-token latency, still bounded
+    // enough that genuinely dead requests surface within ~6 min after the
+    // single timeout retry.
     return (parseTimeoutEnv('FRANKLIN_MODEL_REQUEST_TIMEOUT_MS') ??
         parseTimeoutEnv('FRANKLIN_MODEL_IDLE_TIMEOUT_MS') ??
-        45_000);
+        180_000);
 }
 function getModelStreamIdleTimeoutMs() {
     return (parseTimeoutEnv('FRANKLIN_MODEL_STREAM_IDLE_TIMEOUT_MS') ??

package/dist/commands/task.d.ts

@@ -0,0 +1,11 @@
+/**
+ * `franklin task` CLI surface — human-facing operations on detached background
+ * tasks. Mirrors the on-disk shape under `~/.franklin/tasks/<runId>/` that the
+ * runner / store layers maintain. Subcommands grow incrementally over T10–T13:
+ *   - list    : recent tasks, newest first
+ *   - tail    : print log + status; --follow polls until terminal
+ *   - cancel  : SIGTERM the runner pid
+ *   - wait    : block until terminal, exit 0/1/2 by outcome
+ */
+import { Command } from 'commander';
+export declare function buildTaskCommand(): Command;

package/dist/commands/task.js

@@ -0,0 +1,134 @@
+/**
+ * `franklin task` CLI surface — human-facing operations on detached background
+ * tasks. Mirrors the on-disk shape under `~/.franklin/tasks/<runId>/` that the
+ * runner / store layers maintain. Subcommands grow incrementally over T10–T13:
+ *   - list    : recent tasks, newest first
+ *   - tail    : print log + status; --follow polls until terminal
+ *   - cancel  : SIGTERM the runner pid
+ *   - wait    : block until terminal, exit 0/1/2 by outcome
+ */
+import fs from 'node:fs';
+import { Command } from 'commander';
+import { listTasks, readTaskMeta } from '../tasks/store.js';
+import { reconcileLostTasks } from '../tasks/lost-detection.js';
+import { taskLogPath } from '../tasks/paths.js';
+import { isTerminalTaskStatus } from '../tasks/types.js';
+function fmtAge(ms) {
+    const s = Math.floor(ms / 1000);
+    if (s < 60)
+        return `${s}s`;
+    const m = Math.floor(s / 60);
+    if (m < 60)
+        return `${m}m`;
+    return `${Math.floor(m / 60)}h${m % 60}m`;
+}
+export function buildTaskCommand() {
+    const cmd = new Command('task').description('Manage long-running detached tasks');
+    cmd
+        .command('list')
+        .description('List recent tasks (newest first)')
+        .action(() => {
+        reconcileLostTasks();
+        const tasks = listTasks();
+        if (tasks.length === 0) {
+            console.log('No tasks. Start one via the Task agent tool.');
+            return;
+        }
+        const now = Date.now();
+        for (const t of tasks) {
+            const age = fmtAge(now - (t.lastEventAt ?? t.createdAt));
+            console.log(`${t.runId}  ${t.status.padEnd(10)}  ${age.padStart(5)}  ${t.label}`);
+        }
+    });
+    cmd
+        .command('tail <runId>')
+        .description('Print log + current status for a task')
+        .option('-f, --follow', 'Poll until task reaches terminal state')
+        .action(async (runId, opts) => {
+        const meta0 = readTaskMeta(runId);
+        if (!meta0) {
+            console.error(`No task: ${runId}`);
+            process.exit(1);
+        }
+        let printed = 0;
+        const printNew = () => {
+            try {
+                const buf = fs.readFileSync(taskLogPath(runId));
+                if (buf.length > printed) {
+                    process.stdout.write(buf.subarray(printed));
+                    printed = buf.length;
+                }
+            }
+            catch {
+                /* log not yet written */
+            }
+        };
+        printNew();
+        if (opts.follow) {
+            while (true) {
+                await new Promise((r) => setTimeout(r, 1000));
+                printNew();
+                const meta = readTaskMeta(runId);
+                if (meta && isTerminalTaskStatus(meta.status))
+                    break;
+            }
+        }
+        const meta = readTaskMeta(runId);
+        if (meta) {
+            console.log(`\n--- ${meta.status} ---`);
+            if (meta.terminalSummary)
+                console.log(meta.terminalSummary);
+        }
+    });
+    cmd
+        .command('wait <runId>')
+        .description('Block until task reaches terminal state, then exit')
+        .option('--timeout <ms>', 'Max wait, default 30 minutes', '1800000')
+        .action(async (runId, opts) => {
+        const cap = parseInt(opts.timeout, 10);
+        const t0 = Date.now();
+        while (true) {
+            const meta = readTaskMeta(runId);
+            if (!meta) {
+                console.error(`No task: ${runId}`);
+                process.exit(1);
+            }
+            if (isTerminalTaskStatus(meta.status)) {
+                console.log(`${meta.status}: ${meta.terminalSummary ?? ''}`);
+                process.exit(meta.status === 'succeeded' ? 0 : 1);
+            }
+            if (Date.now() - t0 > cap) {
+                console.error(`Timed out after ${cap}ms; task still ${meta.status}.`);
+                process.exit(2);
+            }
+            await new Promise((r) => setTimeout(r, 1000));
+        }
+    });
+    cmd
+        .command('cancel <runId>')
+        .description('Cancel a running task (SIGTERM to runner)')
+        .action((runId) => {
+        const meta = readTaskMeta(runId);
+        if (!meta) {
+            console.error(`No task: ${runId}`);
+            process.exit(1);
+        }
+        if (isTerminalTaskStatus(meta.status)) {
+            console.log(`Task already ${meta.status}.`);
+            return;
+        }
+        if (typeof meta.pid !== 'number') {
+            console.error('Task has no recorded pid (likely still queued).');
+            process.exit(1);
+        }
+        try {
+            process.kill(meta.pid, 'SIGTERM');
+            console.log(`SIGTERM sent to ${meta.pid}.`);
+        }
+        catch (err) {
+            console.error(`Could not signal pid ${meta.pid}: ${err.message}`);
+            process.exit(1);
+        }
+    });
+    return cmd;
+}

package/dist/index.js

@@ -23,6 +23,7 @@ import { daemonCommand } from './commands/daemon.js';
 import { initCommand } from './commands/init.js';
 import { uninitCommand } from './commands/uninit.js';
 import { proxyCommand } from './commands/proxy.js';
+import { buildTaskCommand } from './commands/task.js';
 import { VERSION as version } from './config.js';
 const program = new Command();
 program
@@ -215,6 +216,21 @@ program
     const { listAvailablePlugins } = await import('./commands/plugin.js');
     listAvailablePlugins();
 });
+// `franklin task <subcmd>` — human-facing CLI for detached background tasks.
+// Defined in src/commands/task.ts; subcommands: list, tail, cancel, wait.
+program.addCommand(buildTaskCommand());
+// Hidden internal subcommand — invoked by startDetachedTask via spawn(detached).
+// The underscore prefix signals "not for humans"; we still register it via
+// commander so exit codes and arg parsing stay consistent with the rest of
+// the CLI.
+program
+    .command('_task-runner <runId>')
+    .description('(internal) execute a detached task by runId')
+    .action(async (runId) => {
+    const { runDetachedTask } = await import('./tasks/runner.js');
+    const code = await runDetachedTask(runId);
+    process.exit(code);
+});
 // Default action: if no subcommand given, run 'start'
 const args = process.argv.slice(2);
 const firstArg = args[0];

package/dist/proxy/server.js

@@ -41,7 +41,13 @@ function log(...args) {
     catch { /* ignore */ }
 }
 const DEFAULT_MAX_TOKENS = 4096;
-const DEFAULT_PROXY_REQUEST_TIMEOUT_MS = 45_000;
+// 180s budget for *time-to-headers* — reasoning-class models (zai/glm-*,
+// nemotron *-reasoning, deepseek-r*, gpt-5-codex, anthropic extended-thinking)
+// routinely take 60–120s to first token on cache-cold prompts or busy
+// gateways. The old 45s default cut those off and the proxy returned a
+// failed response that downstream agents (Cline, Claude Desktop, etc.) had
+// to retry blindly.
+const DEFAULT_PROXY_REQUEST_TIMEOUT_MS = 180_000;
 const DEFAULT_PROXY_STREAM_TIMEOUT_MS = 5 * 60 * 1000;
 function parseTimeoutEnv(name, fallback) {
     const raw = process.env[name];

package/dist/tasks/lost-detection.d.ts

@@ -0,0 +1,15 @@
+/**
+ * Lost-task detection.
+ *
+ * For every task currently in `running` or `queued`, check whether its recorded
+ * pid is still alive via `process.kill(pid, 0)`. If the pid is gone, the
+ * runner crashed or was killed externally; flip status to `lost` so observers
+ * (CLI list, agent prompt) stop misreporting it as in-flight.
+ *
+ * EPERM means the pid exists but we don't have permission to signal it —
+ * treat that as alive. ESRCH (or anything else) means dead.
+ *
+ * Best-effort: PID reuse can lie. v3.10's contract is "lazy reconciliation
+ * on `task list`"; v3.11 may add a pidStartTime cross-check.
+ */
+export declare function reconcileLostTasks(now?: number): number;

package/dist/tasks/lost-detection.js

@@ -0,0 +1,51 @@
+/**
+ * Lost-task detection.
+ *
+ * For every task currently in `running` or `queued`, check whether its recorded
+ * pid is still alive via `process.kill(pid, 0)`. If the pid is gone, the
+ * runner crashed or was killed externally; flip status to `lost` so observers
+ * (CLI list, agent prompt) stop misreporting it as in-flight.
+ *
+ * EPERM means the pid exists but we don't have permission to signal it —
+ * treat that as alive. ESRCH (or anything else) means dead.
+ *
+ * Best-effort: PID reuse can lie. v3.10's contract is "lazy reconciliation
+ * on `task list`"; v3.11 may add a pidStartTime cross-check.
+ */
+import { listTasks, applyEvent } from './store.js';
+function isPidAlive(pid) {
+    try {
+        process.kill(pid, 0);
+        return true;
+    }
+    catch (err) {
+        // EPERM means it exists but we can't signal it — still alive.
+        return err.code === 'EPERM';
+    }
+}
+export function reconcileLostTasks(now = Date.now()) {
+    let n = 0;
+    for (const t of listTasks()) {
+        if (t.status !== 'running' && t.status !== 'queued')
+            continue;
+        if (typeof t.pid !== 'number')
+            continue;
+        if (isPidAlive(t.pid))
+            continue;
+        try {
+            applyEvent(t.runId, {
+                at: now,
+                kind: 'lost',
+                summary: 'Backing process not found — task may have been killed externally.',
+            });
+            n++;
+        }
+        catch (err) {
+            // Meta could vanish mid-reconcile (e.g. the task dir was deleted out from
+            // under us) — log and continue with the next task. One bad task should
+            // not abort the whole sweep.
+            process.stderr.write(`[franklin] reconcileLostTasks: skipping ${t.runId}: ${err.message}\n`);
+        }
+    }
+    return n;
+}

package/dist/tasks/paths.d.ts

@@ -0,0 +1,12 @@
+/**
+ * Per-task on-disk layout under $FRANKLIN_HOME/tasks/<runId>/.
+ *   meta.json    — single TaskRecord, atomically rewritten
+ *   events.jsonl — append-only event log
+ *   log.txt      — child process stdout/stderr
+ */
+export declare function getTasksDir(): string;
+export declare function getTaskDir(runId: string): string;
+export declare function ensureTaskDir(runId: string): string;
+export declare function taskMetaPath(runId: string): string;
+export declare function taskEventsPath(runId: string): string;
+export declare function taskLogPath(runId: string): string;

package/dist/tasks/paths.js

@@ -0,0 +1,32 @@
+/**
+ * Per-task on-disk layout under $FRANKLIN_HOME/tasks/<runId>/.
+ *   meta.json    — single TaskRecord, atomically rewritten
+ *   events.jsonl — append-only event log
+ *   log.txt      — child process stdout/stderr
+ */
+import fs from 'node:fs';
+import os from 'node:os';
+import path from 'node:path';
+function franklinHome() {
+    return process.env.FRANKLIN_HOME || path.join(os.homedir(), '.franklin');
+}
+export function getTasksDir() {
+    return path.join(franklinHome(), 'tasks');
+}
+export function getTaskDir(runId) {
+    return path.join(getTasksDir(), runId);
+}
+export function ensureTaskDir(runId) {
+    const dir = getTaskDir(runId);
+    fs.mkdirSync(dir, { recursive: true });
+    return dir;
+}
+export function taskMetaPath(runId) {
+    return path.join(getTaskDir(runId), 'meta.json');
+}
+export function taskEventsPath(runId) {
+    return path.join(getTaskDir(runId), 'events.jsonl');
+}
+export function taskLogPath(runId) {
+    return path.join(getTaskDir(runId), 'log.txt');
+}

package/dist/tasks/runner.d.ts

@@ -0,0 +1,21 @@
+/**
+ * Detached task runner. The hidden `_task-runner <runId>` subcommand of the
+ * `franklin` CLI dispatches into this module, which is what actually executes
+ * the user's command in the detached child process.
+ *
+ * Lifecycle (per task):
+ *   1. Read meta.json. Bail with exit code 2 if it's gone.
+ *   2. Open log.txt for append, record our own pid + status=running, emit
+ *      a `running` event.
+ *   3. Spawn `bash -lc <command>` with stdout/stderr piped to log.txt.
+ *   4. Heartbeat every 5s: just refresh meta.lastEventAt so observers can see
+ *      "still going."
+ *   5. On child exit (or spawn error), close the log fd, finalize meta with
+ *      exitCode + status (`succeeded` if 0, `failed` otherwise), emit a
+ *      terminal event whose summary is the last 500 chars of log.
+ *
+ * Defensive style: we re-read meta inside the heartbeat and on exit because
+ * a concurrent `franklin task cancel` (or external `rm -rf`) can vanish the
+ * task dir mid-flight. Every fs operation is best-effort.
+ */
+export declare function runDetachedTask(runId: string): Promise<number>;

package/dist/tasks/runner.js

@@ -0,0 +1,191 @@
+/**
+ * Detached task runner. The hidden `_task-runner <runId>` subcommand of the
+ * `franklin` CLI dispatches into this module, which is what actually executes
+ * the user's command in the detached child process.
+ *
+ * Lifecycle (per task):
+ *   1. Read meta.json. Bail with exit code 2 if it's gone.
+ *   2. Open log.txt for append, record our own pid + status=running, emit
+ *      a `running` event.
+ *   3. Spawn `bash -lc <command>` with stdout/stderr piped to log.txt.
+ *   4. Heartbeat every 5s: just refresh meta.lastEventAt so observers can see
+ *      "still going."
+ *   5. On child exit (or spawn error), close the log fd, finalize meta with
+ *      exitCode + status (`succeeded` if 0, `failed` otherwise), emit a
+ *      terminal event whose summary is the last 500 chars of log.
+ *
+ * Defensive style: we re-read meta inside the heartbeat and on exit because
+ * a concurrent `franklin task cancel` (or external `rm -rf`) can vanish the
+ * task dir mid-flight. Every fs operation is best-effort.
+ */
+import { spawn } from 'node:child_process';
+import fs from 'node:fs';
+import { readTaskMeta, applyEvent, writeTaskMeta } from './store.js';
+import { taskLogPath, ensureTaskDir } from './paths.js';
+const HEARTBEAT_MS = 5_000;
+const TAIL_BYTES = 500;
+function safeCloseFd(fd) {
+    try {
+        fs.closeSync(fd);
+    }
+    catch {
+        /* already closed */
+    }
+}
+function readLogTail(runId) {
+    try {
+        const buf = fs.readFileSync(taskLogPath(runId), 'utf-8');
+        return buf.slice(-TAIL_BYTES).replace(/\s+/g, ' ').trim();
+    }
+    catch {
+        return '';
+    }
+}
+export async function runDetachedTask(runId) {
+    const meta = readTaskMeta(runId);
+    if (!meta) {
+        process.stderr.write(`runner: no task ${runId}\n`);
+        return 2;
+    }
+    ensureTaskDir(runId);
+    const logFd = fs.openSync(taskLogPath(runId), 'a');
+    let logFdClosed = false;
+    const closeLog = () => {
+        if (logFdClosed)
+            return;
+        logFdClosed = true;
+        safeCloseFd(logFd);
+    };
+    const startedAt = Date.now();
+    writeTaskMeta({
+        ...meta,
+        pid: process.pid,
+        status: 'running',
+        startedAt,
+        lastEventAt: startedAt,
+    });
+    applyEvent(runId, { at: startedAt, kind: 'running', summary: 'runner started' });
+    // `finalized` guards against the rare case where the heartbeat timer
+    // already fired but its callback is still on the event-loop queue at
+    // the moment finalize() runs — without this flag, a heartbeat write
+    // could land *after* the terminal event and clobber lastEventAt /
+    // status. We flip it before clearInterval so any pending callback
+    // bails on its first line.
+    let finalized = false;
+    // Heartbeat: every 5s while child is alive, refresh lastEventAt so
+    // observers see "still going." If the meta has been deleted out from
+    // under us (someone rm'd the task dir), skip silently — no need to
+    // re-create a stub.
+    const heartbeat = setInterval(() => {
+        if (finalized)
+            return;
+        const cur = readTaskMeta(runId);
+        if (!cur)
+            return;
+        try {
+            writeTaskMeta({ ...cur, lastEventAt: Date.now() });
+        }
+        catch (err) {
+            process.stderr.write(`[franklin] runner heartbeat: ${err.message}\n`);
+        }
+    }, HEARTBEAT_MS);
+    // Best-effort finalize. Used by both the normal exit path and the spawn
+    // error path. Always closes the log fd and clears the heartbeat.
+    // If `finalized` is already true (cancel path beat us to it), bail —
+    // we would otherwise overwrite the on-disk `cancelled` terminal state
+    // with `failed` after `child.kill('SIGTERM')` causes child.on('exit').
+    const finalize = (exitCode, status, fallbackSummary) => {
+        if (finalized)
+            return;
+        finalized = true;
+        clearInterval(heartbeat);
+        closeLog();
+        const endedAt = Date.now();
+        const tail = readLogTail(runId);
+        const cur = readTaskMeta(runId);
+        if (cur) {
+            try {
+                writeTaskMeta({ ...cur, exitCode });
+            }
+            catch (err) {
+                process.stderr.write(`[franklin] runner finalize writeTaskMeta: ${err.message}\n`);
+            }
+            try {
+                applyEvent(runId, {
+                    at: endedAt,
+                    kind: status,
+                    summary: tail || fallbackSummary,
+                });
+            }
+            catch (err) {
+                process.stderr.write(`[franklin] runner finalize applyEvent: ${err.message}\n`);
+            }
+        }
+        else {
+            // Meta vanished mid-run. Nothing to finalize. Surface for ops, exit clean.
+            process.stderr.write(`[franklin] runner: meta for ${runId} disappeared before finalize\n`);
+        }
+    };
+    const child = spawn('bash', ['-lc', meta.command], {
+        cwd: meta.workingDir,
+        stdio: ['ignore', logFd, logFd],
+        env: { ...process.env, FRANKLIN_TASK_RUN_ID: runId },
+    });
+    // Cancel path: parent CLI sends SIGTERM (or user hits Ctrl-C). We must
+    // (a) flip `finalized` BEFORE the soon-to-fire child.exit handler runs so
+    //     it short-circuits and doesn't write status=failed,
+    // (b) clear the heartbeat for the same reason,
+    // (c) kill the child (SIGTERM) so the bash process actually dies,
+    // (d) applyEvent('cancelled') so the on-disk terminal state is correct,
+    // (e) close the log fd,
+    // (f) exit 130 (the canonical Ctrl-C / SIGTERM exit code) on a small delay
+    //     so any in-flight fs writes flush.
+    const onSignal = () => {
+        if (finalized)
+            return;
+        finalized = true;
+        clearInterval(heartbeat);
+        try {
+            child.kill('SIGTERM');
+        }
+        catch {
+            /* child may already be gone */
+        }
+        closeLog();
+        try {
+            applyEvent(runId, {
+                at: Date.now(),
+                kind: 'cancelled',
+                summary: 'Cancelled via SIGTERM',
+            });
+        }
+        catch (err) {
+            process.stderr.write(`[franklin] runner cancel applyEvent: ${err.message}\n`);
+        }
+        setTimeout(() => process.exit(130), 500);
+    };
+    process.on('SIGTERM', onSignal);
+    process.on('SIGINT', onSignal);
+    return await new Promise((resolve) => {
+        let resolved = false;
+        const settle = (code) => {
+            if (resolved)
+                return;
+            resolved = true;
+            resolve(code);
+        };
+        child.on('error', (err) => {
+            // Spawn itself failed — bash not on $PATH, EACCES, etc. Make sure we
+            // close the log fd, finalize the task, and exit.
+            const exitCode = 1;
+            finalize(exitCode, 'failed', `spawn error: ${err.message}`);
+            settle(exitCode);
+        });
+        child.on('exit', (code, signal) => {
+            const exitCode = typeof code === 'number' ? code : signal ? 128 : 1;
+            const status = exitCode === 0 ? 'succeeded' : 'failed';
+            finalize(exitCode, status, status === 'succeeded' ? 'completed' : `exited with code ${exitCode}`);
+            settle(exitCode);
+        });
+    });
+}

package/dist/tasks/spawn.d.ts

@@ -0,0 +1,26 @@
+/**
+ * Public spawn surface for the detached task subsystem.
+ *
+ * `startDetachedTask` is the synchronous entry point used by the `Task`
+ * agent tool and by `franklin task` callers. It writes a queued
+ * TaskRecord to disk, opens log.txt for stdout/stderr capture, then
+ * spawns `franklin _task-runner <runId>` with `detached: true` and
+ * unrefs the child so this process can exit without waiting on the
+ * task. The runner subprocess takes over from there: it spawns the
+ * actual user command, drives heartbeats, and finalizes meta on exit.
+ *
+ * Performance contract: startDetachedTask must return in <250ms. That
+ * is enforced by the integration test in test/local.mjs and is the
+ * reason all I/O here is sync — we want one fs write + one spawn, not
+ * an async chain that could be interrupted by a slow microtask.
+ *
+ * CLI path resolution (in priority order):
+ *   1. process.env.FRANKLIN_CLI_PATH — escape hatch for tests / dev.
+ *   2. <cwd>/dist/index.js — the published bundle's entry point.
+ */
+export interface StartDetachedTaskInput {
+    label: string;
+    command: string;
+    workingDir: string;
+}
+export declare function startDetachedTask(input: StartDetachedTaskInput): string;

package/dist/tasks/spawn.js

@@ -0,0 +1,72 @@
+/**
+ * Public spawn surface for the detached task subsystem.
+ *
+ * `startDetachedTask` is the synchronous entry point used by the `Task`
+ * agent tool and by `franklin task` callers. It writes a queued
+ * TaskRecord to disk, opens log.txt for stdout/stderr capture, then
+ * spawns `franklin _task-runner <runId>` with `detached: true` and
+ * unrefs the child so this process can exit without waiting on the
+ * task. The runner subprocess takes over from there: it spawns the
+ * actual user command, drives heartbeats, and finalizes meta on exit.
+ *
+ * Performance contract: startDetachedTask must return in <250ms. That
+ * is enforced by the integration test in test/local.mjs and is the
+ * reason all I/O here is sync — we want one fs write + one spawn, not
+ * an async chain that could be interrupted by a slow microtask.
+ *
+ * CLI path resolution (in priority order):
+ *   1. process.env.FRANKLIN_CLI_PATH — escape hatch for tests / dev.
+ *   2. <cwd>/dist/index.js — the published bundle's entry point.
+ */
+import { spawn } from 'node:child_process';
+import fs from 'node:fs';
+import path from 'node:path';
+import { randomUUID } from 'node:crypto';
+import { writeTaskMeta } from './store.js';
+import { taskLogPath, ensureTaskDir } from './paths.js';
+function resolveCliPath() {
+    const fromEnv = process.env.FRANKLIN_CLI_PATH;
+    if (fromEnv && fromEnv.length > 0)
+        return fromEnv;
+    return path.resolve(process.cwd(), 'dist', 'index.js');
+}
+function generateRunId() {
+    return `t_${Date.now().toString(36)}_${randomUUID().slice(0, 8)}`;
+}
+export function startDetachedTask(input) {
+    const runId = generateRunId();
+    const now = Date.now();
+    const record = {
+        runId,
+        runtime: 'detached-bash',
+        label: input.label,
+        command: input.command,
+        workingDir: input.workingDir,
+        status: 'queued',
+        createdAt: now,
+    };
+    writeTaskMeta(record);
+    ensureTaskDir(runId);
+    const cliPath = resolveCliPath();
+    const logFd = fs.openSync(taskLogPath(runId), 'a');
+    // detached + unref + ignore stdin = parent can exit immediately while
+    // the child keeps running. The runner reopens its own log handles via
+    // the inherited stdout/stderr fds, so we close ours after spawn returns.
+    const child = spawn(process.execPath, [cliPath, '_task-runner', runId], {
+        cwd: input.workingDir,
+        detached: true,
+        stdio: ['ignore', logFd, logFd],
+        env: { ...process.env, FRANKLIN_TASK_RUN_ID: runId },
+    });
+    child.unref();
+    // The child has duped the fd; closing ours frees the parent's slot.
+    // Surface unexpected errors instead of swallowing — a leaked fd here
+    // is rare but worth knowing about.
+    try {
+        fs.closeSync(logFd);
+    }
+    catch (err) {
+        process.stderr.write(`[franklin] startDetachedTask: closing log fd failed: ${err.message}\n`);
+    }
+    return runId;
+}

package/dist/tasks/store.d.ts

@@ -0,0 +1,24 @@
+/**
+ * Task persistence: meta.json (single record) + events.jsonl (append-only log).
+ *
+ * Concurrency contract: applyEvent does a read-modify-write on meta.json. It
+ * is safe to call from a single writer per task — by convention, that writer
+ * is the _task-runner subprocess. CLI commands that need to influence a
+ * running task (e.g. `franklin task cancel`) MUST signal the runner pid
+ * (SIGTERM) rather than calling applyEvent directly, otherwise the two
+ * writers race and one update is silently lost. Lost-task reconciliation
+ * is an exception — it runs only when the runner is provably dead, so
+ * there is no second writer to race with.
+ *
+ * Atomicity: writeTaskMeta uses tmp + rename; readers see either old or new
+ * meta, never partial. appendTaskEvent relies on POSIX O_APPEND + PIPE_BUF
+ * atomicity (~4096 bytes); summaries should stay short. readTaskEvents is
+ * tolerant of a torn last line.
+ */
+import type { TaskRecord, TaskEventRecord } from './types.js';
+export declare function writeTaskMeta(record: TaskRecord): void;
+export declare function readTaskMeta(runId: string): TaskRecord | null;
+export declare function appendTaskEvent(runId: string, event: TaskEventRecord): void;
+export declare function readTaskEvents(runId: string): TaskEventRecord[];
+export declare function applyEvent(runId: string, event: TaskEventRecord): TaskRecord;
+export declare function listTasks(): TaskRecord[];

package/dist/tasks/store.js

@@ -0,0 +1,124 @@
+/**
+ * Task persistence: meta.json (single record) + events.jsonl (append-only log).
+ *
+ * Concurrency contract: applyEvent does a read-modify-write on meta.json. It
+ * is safe to call from a single writer per task — by convention, that writer
+ * is the _task-runner subprocess. CLI commands that need to influence a
+ * running task (e.g. `franklin task cancel`) MUST signal the runner pid
+ * (SIGTERM) rather than calling applyEvent directly, otherwise the two
+ * writers race and one update is silently lost. Lost-task reconciliation
+ * is an exception — it runs only when the runner is provably dead, so
+ * there is no second writer to race with.
+ *
+ * Atomicity: writeTaskMeta uses tmp + rename; readers see either old or new
+ * meta, never partial. appendTaskEvent relies on POSIX O_APPEND + PIPE_BUF
+ * atomicity (~4096 bytes); summaries should stay short. readTaskEvents is
+ * tolerant of a torn last line.
+ */
+import fs from 'node:fs';
+import { ensureTaskDir, taskMetaPath, taskEventsPath, getTasksDir, } from './paths.js';
+export function writeTaskMeta(record) {
+    ensureTaskDir(record.runId);
+    const target = taskMetaPath(record.runId);
+    const tmp = `${target}.tmp`;
+    fs.writeFileSync(tmp, JSON.stringify(record, null, 2));
+    try {
+        fs.renameSync(tmp, target);
+    }
+    catch (err) {
+        try {
+            fs.unlinkSync(tmp);
+        }
+        catch { /* may not exist */ }
+        throw err;
+    }
+}
+export function readTaskMeta(runId) {
+    let raw;
+    try {
+        raw = fs.readFileSync(taskMetaPath(runId), 'utf-8');
+    }
+    catch (err) {
+        if (err.code === 'ENOENT')
+            return null;
+        // Surface unexpected I/O errors instead of pretending the task doesn't exist.
+        throw err;
+    }
+    try {
+        return JSON.parse(raw);
+    }
+    catch (err) {
+        process.stderr.write(`[franklin] meta.json corrupt for ${runId}: ${err.message}\n`);
+        return null;
+    }
+}
+export function appendTaskEvent(runId, event) {
+    ensureTaskDir(runId);
+    fs.appendFileSync(taskEventsPath(runId), JSON.stringify(event) + '\n');
+}
+export function readTaskEvents(runId) {
+    let raw;
+    try {
+        raw = fs.readFileSync(taskEventsPath(runId), 'utf-8');
+    }
+    catch (err) {
+        if (err.code === 'ENOENT')
+            return [];
+        throw err;
+    }
+    // Per-line tolerance: a torn last line (concurrent appendFileSync over PIPE_BUF)
+    // would otherwise discard the whole log. Mirror storage.ts:loadSessionHistory.
+    const out = [];
+    for (const line of raw.split('\n')) {
+        if (!line.trim())
+            continue;
+        try {
+            out.push(JSON.parse(line));
+        }
+        catch { /* skip torn / corrupt line */ }
+    }
+    return out;
+}
+export function applyEvent(runId, event) {
+    const cur = readTaskMeta(runId);
+    if (!cur)
+        throw new Error(`applyEvent: no task ${runId}`);
+    const next = { ...cur };
+    next.lastEventAt = event.at;
+    if (event.summary !== undefined)
+        next.progressSummary = event.summary;
+    if (event.kind === 'running' && next.status === 'queued') {
+        next.status = 'running';
+        next.startedAt = event.at;
+    }
+    else if (event.kind !== 'progress' && event.kind !== 'running') {
+        // event.kind is now narrowed to terminal statuses
+        next.status = event.kind;
+        next.endedAt = event.at;
+        if (event.summary !== undefined)
+            next.terminalSummary = event.summary;
+    }
+    appendTaskEvent(runId, event);
+    writeTaskMeta(next);
+    return next;
+}
+export function listTasks() {
+    let entries;
+    try {
+        entries = fs.readdirSync(getTasksDir(), { withFileTypes: true });
+    }
+    catch {
+        return [];
+    }
+    const out = [];
+    for (const ent of entries) {
+        // Skip junk like .DS_Store — only real per-task subdirectories are valid.
+        if (!ent.isDirectory())
+            continue;
+        const meta = readTaskMeta(ent.name);
+        if (meta)
+            out.push(meta);
+    }
+    out.sort((a, b) => b.createdAt - a.createdAt);
+    return out;
+}

package/dist/tasks/types.d.ts

@@ -0,0 +1,32 @@
+/**
+ * Task subsystem types. Mirrors openclaw/openclaw src/tasks/task-registry.types.ts
+ * with channel/delivery fields stripped — Franklin is CLI-first single-user.
+ */
+export type TaskStatus = 'queued' | 'running' | 'succeeded' | 'failed' | 'timed_out' | 'cancelled' | 'lost';
+export type TaskRuntime = 'detached-bash';
+export type TaskTerminalOutcome = 'succeeded' | 'blocked';
+export type TaskEventKind = Exclude<TaskStatus, 'queued'> | 'progress';
+export interface TaskEventRecord {
+    at: number;
+    kind: TaskEventKind;
+    summary?: string;
+}
+export interface TaskRecord {
+    runId: string;
+    runtime: TaskRuntime;
+    label: string;
+    command: string;
+    workingDir: string;
+    pid?: number;
+    status: TaskStatus;
+    createdAt: number;
+    startedAt?: number;
+    endedAt?: number;
+    lastEventAt?: number;
+    exitCode?: number;
+    error?: string;
+    progressSummary?: string;
+    terminalSummary?: string;
+    terminalOutcome?: TaskTerminalOutcome;
+}
+export declare function isTerminalTaskStatus(s: TaskStatus): boolean;

package/dist/tasks/types.js

@@ -0,0 +1,14 @@
+/**
+ * Task subsystem types. Mirrors openclaw/openclaw src/tasks/task-registry.types.ts
+ * with channel/delivery fields stripped — Franklin is CLI-first single-user.
+ */
+const TERMINAL = new Set([
+    'succeeded',
+    'failed',
+    'timed_out',
+    'cancelled',
+    'lost',
+]);
+export function isTerminalTaskStatus(s) {
+    return TERMINAL.has(s);
+}

package/dist/tools/detach.d.ts

@@ -0,0 +1,9 @@
+/**
+ * Detach capability — start a detached background Bash command.
+ *
+ * Returns immediately with a runId. The command continues even if Franklin
+ * exits or the user closes their terminal. Manage running tasks with
+ * `franklin task list / tail / wait / cancel`.
+ */
+import type { CapabilityHandler } from '../agent/types.js';
+export declare const detachCapability: CapabilityHandler;

package/dist/tools/detach.js

@@ -0,0 +1,53 @@
+/**
+ * Detach capability — start a detached background Bash command.
+ *
+ * Returns immediately with a runId. The command continues even if Franklin
+ * exits or the user closes their terminal. Manage running tasks with
+ * `franklin task list / tail / wait / cancel`.
+ */
+import { startDetachedTask } from '../tasks/spawn.js';
+async function execute(input, ctx) {
+    const { label, command } = input;
+    if (typeof label !== 'string' || label.length === 0) {
+        return { output: 'Error: label is required (non-empty string)', isError: true };
+    }
+    if (typeof command !== 'string' || command.length === 0) {
+        return { output: 'Error: command is required (non-empty string)', isError: true };
+    }
+    const runId = startDetachedTask({ label, command, workingDir: ctx.workingDir });
+    return {
+        output: `Detached task started.\n` +
+            `runId: ${runId}\n` +
+            `label: ${label}\n` +
+            `command: ${command}\n\n` +
+            `Inspect with:\n` +
+            `  franklin task tail ${runId} --follow\n` +
+            `  franklin task wait ${runId}\n` +
+            `  franklin task cancel ${runId}\n`,
+    };
+}
+export const detachCapability = {
+    spec: {
+        name: 'Detach',
+        description: "Run a Bash command as a detached background job. Returns immediately " +
+            "with a runId. The command continues even if Franklin exits or the user " +
+            "closes their terminal. Use this for any iteration over more than ~20 " +
+            "items, large data fetches, paginated API loops, or anything you'd " +
+            "otherwise loop on turn-by-turn (which would burn turns and trip " +
+            "timeouts). The agent's job is to design and orchestrate, not to be " +
+            "the for-loop. Pair with a script that writes a checkpoint file so " +
+            "progress survives restarts. Tail logs with `franklin task tail " +
+            "<runId> --follow` and check completion with `franklin task wait " +
+            "<runId>`.",
+        input_schema: {
+            type: 'object',
+            properties: {
+                label: { type: 'string', description: 'Short human-readable label, e.g. "scrape stargazers"' },
+                command: { type: 'string', description: 'Bash command to run. Will be executed via `bash -lc`.' },
+            },
+            required: ['label', 'command'],
+        },
+    },
+    execute,
+    concurrent: true,
+};

package/dist/tools/index.d.ts

@@ -11,6 +11,7 @@ import { grepCapability } from './grep.js';
 import { webFetchCapability } from './webfetch.js';
 import { webSearchCapability } from './websearch.js';
 import { taskCapability } from './task.js';
+import { detachCapability } from './detach.js';
 /**
  * Reset module-level tool state that would otherwise leak between sessions
  * when the same process runs `interactiveSession()` more than once (library
@@ -19,5 +20,5 @@ import { taskCapability } from './task.js';
 export declare function resetToolSessionState(): void;
 /** All capabilities available to the Franklin agent (excluding sub-agent, which needs config). */
 export declare const allCapabilities: CapabilityHandler[];
-export { readCapability, writeCapability, editCapability, bashCapability, globCapability, grepCapability, webFetchCapability, webSearchCapability, taskCapability, };
+export { readCapability, writeCapability, editCapability, bashCapability, globCapability, grepCapability, webFetchCapability, webSearchCapability, taskCapability, detachCapability, };
 export { createSubAgentCapability } from './subagent.js';

package/dist/tools/index.js

@@ -12,6 +12,7 @@ import { grepCapability } from './grep.js';
 import { webFetchCapability, clearSessionState as clearWebFetchSessionState } from './webfetch.js';
 import { webSearchCapability } from './websearch.js';
 import { taskCapability } from './task.js';
+import { detachCapability } from './detach.js';
 import { createImageGenCapability } from './imagegen.js';
 import { createVideoGenCapability } from './videogen.js';
 import { createMusicGenCapability } from './musicgen.js';
@@ -125,6 +126,7 @@ export const allCapabilities = [
     webFetchCapability,
     webSearchCapability,
     taskCapability,
+    detachCapability,
     defaultImageGenCapability,
     defaultVideoGenCapability,
     defaultMusicGenCapability,
@@ -143,5 +145,5 @@ export const allCapabilities = [
     webhookPostCapability,
     walletCapability,
 ];
-export { readCapability, writeCapability, editCapability, bashCapability, globCapability, grepCapability, webFetchCapability, webSearchCapability, taskCapability, };
+export { readCapability, writeCapability, editCapability, bashCapability, globCapability, grepCapability, webFetchCapability, webSearchCapability, taskCapability, detachCapability, };
 export { createSubAgentCapability } from './subagent.js';

package/dist/tools/tool-categories.js

@@ -23,6 +23,10 @@ export const CORE_TOOL_NAMES = new Set([
     'Edit',
     // Shell execution — needed for running tests, builds, scripts.
     'Bash',
+    // Detached background execution — bash-adjacent: spawns a long-running
+    // command that survives Franklin exiting. Belongs in core so the agent
+    // can offload >20-item iteration without first activating a meta-tool.
+    'Detach',
     // Search — code exploration is table stakes.
     'Grep',
     'Glob',

package/package.json

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