@blockrun/franklin 3.9.6 → 3.10.1

package/dist/panel/server.js

@@ -15,6 +15,10 @@ import { loadLearnings } from '../learnings/store.js';
 import { readAudit } from '../stats/audit.js';
 import { snapshot as marketsSnapshot } from '../trading/providers/telemetry.js';
 import { describeWiring } from '../trading/providers/registry.js';
+import { listTasks, readTaskMeta, readTaskEvents, } from '../tasks/store.js';
+import { reconcileLostTasks } from '../tasks/lost-detection.js';
+import { taskLogPath } from '../tasks/paths.js';
+import { isTerminalTaskStatus } from '../tasks/types.js';
 import { getHTML } from './html.js';
 const sseClients = new Set();
 function json(res, data, status = 200) {
@@ -380,6 +384,129 @@ export function createPanelServer(port) {
                     json(res, learnings);
                     return;
                 }
+                // ─── Tasks ─────────────────────────────────────────────────────────
+                // Background tasks dispatched via the Detach tool / `franklin task`.
+                // The list endpoint reconciles lost tasks (dead pids) before snapshot
+                // so the UI never displays a zombie as "running". Detail / log /
+                // events endpoints power the per-task drawer in the Tasks tab.
+                if (p === '/api/tasks') {
+                    try {
+                        reconcileLostTasks();
+                    }
+                    catch { /* best-effort */ }
+                    json(res, { tasks: listTasks() });
+                    return;
+                }
+                if (p.startsWith('/api/tasks/')) {
+                    const rest = p.slice('/api/tasks/'.length);
+                    const segments = rest.split('/');
+                    const runId = decodeURIComponent(segments[0] || '');
+                    const sub = segments[1];
+                    if (!runId) {
+                        res.writeHead(404);
+                        res.end('Not found');
+                        return;
+                    }
+                    // GET /api/tasks/:runId
+                    if (!sub) {
+                        const meta = readTaskMeta(runId);
+                        if (!meta) {
+                            res.writeHead(404);
+                            res.end('Not found');
+                            return;
+                        }
+                        json(res, meta);
+                        return;
+                    }
+                    // GET /api/tasks/:runId/log — supports Range: bytes=N- for tail polling.
+                    // Brand-new tasks may not have created log.txt yet — return empty 200
+                    // rather than 404 so the panel UI's tail loop doesn't surface noise.
+                    if (sub === 'log') {
+                        const logPath = taskLogPath(runId);
+                        let content;
+                        try {
+                            content = fs.readFileSync(logPath);
+                        }
+                        catch (err) {
+                            if (err.code === 'ENOENT') {
+                                res.writeHead(200, {
+                                    'Content-Type': 'text/plain; charset=utf-8',
+                                    'Cache-Control': 'no-store',
+                                });
+                                res.end('');
+                                return;
+                            }
+                            throw err;
+                        }
+                        const total = content.length;
+                        const range = req.headers['range'];
+                        if (typeof range === 'string') {
+                            const m = range.match(/^bytes=(\d+)-$/);
+                            if (m) {
+                                const start = Math.min(parseInt(m[1], 10), total);
+                                const slice = content.subarray(start);
+                                res.writeHead(206, {
+                                    'Content-Type': 'text/plain; charset=utf-8',
+                                    'Cache-Control': 'no-store',
+                                    'Content-Range': `bytes ${start}-${Math.max(total - 1, start)}/${total}`,
+                                });
+                                res.end(slice);
+                                return;
+                            }
+                        }
+                        res.writeHead(200, {
+                            'Content-Type': 'text/plain; charset=utf-8',
+                            'Cache-Control': 'no-store',
+                        });
+                        res.end(content);
+                        return;
+                    }
+                    // GET /api/tasks/:runId/events
+                    if (sub === 'events') {
+                        json(res, { events: readTaskEvents(runId) });
+                        return;
+                    }
+                    // POST /api/tasks/:runId/cancel — loopback only.
+                    // Sends SIGTERM to the recorded pid; the runner then writes a
+                    // `cancelled` event itself. This endpoint never mutates meta
+                    // directly to avoid racing the runner (see store.ts contract).
+                    if (sub === 'cancel' && req.method === 'POST') {
+                        if (!isLoopback(req)) {
+                            json(res, { error: 'forbidden' }, 403);
+                            return;
+                        }
+                        try {
+                            const meta = readTaskMeta(runId);
+                            if (!meta) {
+                                res.writeHead(404);
+                                res.end('Not found');
+                                return;
+                            }
+                            if (isTerminalTaskStatus(meta.status)) {
+                                json(res, { ok: false, reason: `already ${meta.status}` });
+                                return;
+                            }
+                            if (typeof meta.pid !== 'number') {
+                                json(res, { ok: false, reason: 'no pid recorded' });
+                                return;
+                            }
+                            try {
+                                process.kill(meta.pid, 'SIGTERM');
+                                json(res, { ok: true });
+                            }
+                            catch (err) {
+                                json(res, { ok: false, reason: err.message });
+                            }
+                        }
+                        catch (err) {
+                            json(res, { ok: false, reason: err.message });
+                        }
+                        return;
+                    }
+                    res.writeHead(404);
+                    res.end('Not found');
+                    return;
+                }
                 // 404
                 res.writeHead(404);
                 res.end('Not found');

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[];