ftown-bridge 0.11.2 → 0.13.0

package/dist/loop-schedule.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"loop-schedule.js","sourceRoot":"","sources":["../src/loop-schedule.ts"],"names":[],"mappings":"AAAA,OAAO,UAAU,MAAM,aAAa,CAAC;AAIrC;;;;;;;GAOG;AACH,MAAM,UAAU,cAAc,CAAC,QAAsB,EAAE,MAAc;IACnE,IAAI,QAAQ,CAAC,IAAI,KAAK,UAAU;QAAE,OAAO,MAAM,GAAG,IAAI,CAAC,GAAG,CAAC,IAAI,EAAE,QAAQ,CAAC,OAAO,CAAC,CAAC;IACnF,MAAM,EAAE,GAAG,UAAU,CAAC,eAAe,CAAC,QAAQ,CAAC,UAAU,EAAE;QACzD,WAAW,EAAE,IAAI,IAAI,CAAC,MAAM,CAAC;QAC7B,EAAE,EAAE,QAAQ,CAAC,EAAE;KAChB,CAAC,CAAC;IACH,OAAO,EAAE,CAAC,IAAI,EAAE,CAAC,MAAM,EAAE,CAAC,OAAO,EAAE,CAAC;AACtC,CAAC;AAED;;;;;;GAMG;AACH,MAAM,UAAU,KAAK,CAAC,IAAU,EAAE,KAAa;IAC7C,IAAI,IAAI,CAAC,eAAe;QAAE,OAAO,IAAI,CAAC,CAAC,0CAA0C;IACjF,IAAI,CAAC,IAAI,CAAC,OAAO;QAAE,OAAO,KAAK,CAAC;IAChC,IAAI,CAAC,IAAI,CAAC,SAAS;QAAE,OAAO,KAAK,CAAC;IAClC,OAAO,IAAI,CAAC,KAAK,CAAC,IAAI,CAAC,SAAS,CAAC,IAAI,KAAK,CAAC;AAC7C,CAAC"}

package/dist/loop-scheduler.d.ts

@@ -0,0 +1,148 @@
+import { type LoopRuntimeMutator } from './loop-store.js';
+import type { CreateFtownSessionInput } from './create-ftown-session.js';
+import type { RemoveFtownSessionOptions } from './remove-ftown-session.js';
+import type { Loop, LoopRunRecord, Session } from './types.js';
+/** Base tick cadence; also the finalize grace so a just-spawned PTY is not mistaken for exited. */
+export declare const LOOP_TICK_INTERVAL_MS = 30000;
+export interface FlightResult {
+    stdout: string;
+    stderr: string;
+    exitCode: number;
+}
+/** Preflight/postflight primitive: promisified child_process.exec (captures exit code + timeout). */
+export type RunFlight = (command: string, cwd: string | undefined, timeoutMs?: number, extraEnv?: Record<string, string>) => Promise<FlightResult>;
+/** In-process flight spawn — wraps createFtownSession(sessionDeps, input) in index.ts. */
+export type SpawnSession = (input: CreateFtownSessionInput) => Promise<Session>;
+/** In-process run removal — wraps removeFtownSession({store,runner,centrifugo,userId}, id, opts) in index.ts. */
+export type RemoveSession = (id: string, options?: RemoveFtownSessionOptions) => Promise<Session | null>;
+export interface SchedulerStore {
+    loadSession(id: string): Promise<Session | null>;
+    loadTerminalLog(id: string): Promise<string>;
+    listSessions(): Promise<Session[]>;
+}
+export interface SchedulerRunner {
+    isRunning(id: string): boolean;
+    stop(id: string): boolean;
+}
+export interface SchedulerCentrifugo {
+    publishLoopUpdate(userId: string, loop: Loop): Promise<void>;
+}
+export interface LoopStoreApi {
+    listLoops(): Loop[];
+    /** Fresh-read → mutate scheduler-owned fields → save; null when deleted concurrently. */
+    mutateLoopRuntime(id: string, fn: LoopRuntimeMutator): Loop | null;
+}
+export interface LoopRunRecordStoreApi {
+    upsertLoopRunRecord(record: LoopRunRecord): LoopRunRecord;
+    pruneLoopRunRecords(loopId: string, keep: number | null, preserveIds?: Iterable<string | undefined>): void;
+}
+export interface SchedulerDeps {
+    store: SchedulerStore;
+    runner: SchedulerRunner;
+    centrifugo: SchedulerCentrifugo;
+    userId: string;
+    /** Built in index.ts as (input) => createFtownSession(sessionDeps, input) — the direct in-process call. */
+    spawnSession: SpawnSession;
+    /** Built in index.ts as (id, opts) => removeFtownSession({store,runner,centrifugo,userId}, id, opts). */
+    removeSession: RemoveSession;
+    /** Loop persistence. Defaults to the real ~/.ftown/loops.json store. */
+    loops?: LoopStoreApi;
+    /** Durable loop-run log persistence. Defaults to the real ~/.ftown/loop-runs.json store. */
+    runRecords?: LoopRunRecordStoreApi;
+    /** Flight runner. Defaults to the exec-based runFlightCommand. */
+    runFlight?: RunFlight;
+    /** Clock seam. Defaults to Date.now. */
+    now?: () => number;
+}
+/**
+ * Runs child_process.exec and normalizes the result to { stdout, stderr,
+ * exitCode }. Never rejects — the exit code is the signal (a timeout maps to
+ * 124, any other failure to the real exit code or 1).
+ *
+ * The hard budget is enforced by SIGKILL on the whole process GROUP, NOT by
+ * exec's built-in `timeout`. exec's timeout only sends SIGTERM to the spawned
+ * `/bin/sh`; a detached grandchild that keeps the stdout pipe open, or a child
+ * that traps SIGTERM, would keep the exec callback from ever firing — and since
+ * the scheduler awaits every flight inside a single re-entrancy-guarded tick,
+ * ONE such flight would wedge the entire scheduler permanently. Spawning
+ * `detached` makes the child its own group leader, so `kill(-pid, SIGKILL)`
+ * takes down the whole tree and the flight can never exceed its budget.
+ */
+export declare function runFlightCommand(command: string, cwd: string | undefined, timeoutMs?: number, extraEnv?: Record<string, string>): Promise<FlightResult>;
+/**
+ * The scheduled-loops engine. On each 30s tick it FINALIZES each loop's
+ * in-flight run(s) (Phase A) before deciding whether to FIRE a new one
+ * (Phase B). All side effects go through injected collaborators so it is
+ * unit-testable without a live bridge, real fs or real timers (mirrors
+ * workflow-runner.ts).
+ *
+ * Persistence rule: the scheduler NEVER writes a whole detached Loop back
+ * across an await. Every runtime-field change goes through
+ * store.mutateLoopRuntime (fresh-read → mutate → save), so a loop deleted or
+ * user-edited during a long flight is neither resurrected nor clobbered.
+ */
+export declare class LoopScheduler {
+    private readonly store;
+    private readonly runner;
+    private readonly centrifugo;
+    private readonly userId;
+    private readonly spawnSession;
+    private readonly removeSession;
+    private readonly loops;
+    private readonly runRecords;
+    private readonly runFlight;
+    private readonly now;
+    /** Re-entrancy guard: tick N+1 never overlaps N. */
+    private tickRunning;
+    /** Set once start() runs (after reconcileOnStart). kick() no-ops before this so an
+     *  early run_loop_now cannot trigger an un-reconciled tick that stampedes overdue loops. */
+    private started;
+    /** Per-loop in-memory fire lock, shared by tick + run_loop_now/kick. */
+    private readonly firingLoops;
+    /** loopId -> (runSessionId -> fire-time ms). Every run THIS process spawned, so under
+     *  overlapPolicy:'allow' each concurrent run is finalized/postflighted/maxRuntime-checked
+     *  independently — not just the newest. Rebuilt lazily from the persisted primary on restart. */
+    private readonly inFlight;
+    private timer;
+    constructor(deps: SchedulerDeps);
+    start(): void;
+    stop(): void;
+    /** Immediate, guarded, out-of-band tick (used by run_loop_now). No-op until start()
+     *  has run, so a kick that races startup cannot fire before reconcileOnStart. */
+    kick(): void;
+    /** Drop scheduler tracking for a deleted loop and stop any run it left alive, so a
+     *  just-deleted loop never leaks a live AI session with nothing left to finalize it. */
+    onLoopDeleted(loop: Loop): void;
+    /**
+     * Missed-schedule policy, run once before the first tick: for every loop whose
+     * nextRunAt is missing or already past, recompute it from now (skip missed
+     * occurrences; never stampede overdue loops). runNowRequested is preserved so a
+     * manual override survives a restart and still fires on the first tick. A loop
+     * with a corrupt persisted schedule is skipped here (logged) and reported as an
+     * error on its first fire.
+     */
+    reconcileOnStart(now?: number): Promise<void>;
+    tick(now?: number): Promise<void>;
+    private processLoop;
+    /** Phase A: finalize each in-flight run once its PTY is confirmed gone (past grace)
+     *  or over its per-run maxRuntime budget. Under 'allow' this walks every tracked run,
+     *  not just the newest, so none is orphaned. */
+    private finalizePhase;
+    /** Seed the persisted primary run into in-memory tracking after a restart (when this
+     *  process has spawned nothing yet for the loop), so a run left 'running' by a prior
+     *  process is still finalized. */
+    private ensureTracked;
+    private track;
+    /** Phase B: fire the loop if due, honoring the per-loop lock and the overlap policy. */
+    private firePhase;
+    /** Advance the schedule up front (so failures/skips never stampede), then preflight → flight. */
+    private fireLoop;
+    /** Resolve one finished run to ok/error, update the loop badge (only if this is the
+     *  loop's tracked/latest run), then run postflight + retention for it. */
+    private finalizeRun;
+    private runPostflight;
+    /** Keep the newest N run-sessions for this loop; prune older finished ones. */
+    private pruneRuns;
+    private persist;
+    private publish;
+}

package/dist/loop-scheduler.js

@@ -0,0 +1,534 @@
+import { spawn } from 'node:child_process';
+import { computeNextRun, isDue } from './loop-schedule.js';
+import { pruneLoopRunRecords, recordForSession, skippedRunRecord, upsertLoopRunRecord, } from './loop-run-store.js';
+import { listLoops, mutateLoopRuntime } from './loop-store.js';
+/** Base tick cadence; also the finalize grace so a just-spawned PTY is not mistaken for exited. */
+export const LOOP_TICK_INTERVAL_MS = 30_000;
+const iso = (ms) => new Date(ms).toISOString();
+/**
+ * Runs child_process.exec and normalizes the result to { stdout, stderr,
+ * exitCode }. Never rejects — the exit code is the signal (a timeout maps to
+ * 124, any other failure to the real exit code or 1).
+ *
+ * The hard budget is enforced by SIGKILL on the whole process GROUP, NOT by
+ * exec's built-in `timeout`. exec's timeout only sends SIGTERM to the spawned
+ * `/bin/sh`; a detached grandchild that keeps the stdout pipe open, or a child
+ * that traps SIGTERM, would keep the exec callback from ever firing — and since
+ * the scheduler awaits every flight inside a single re-entrancy-guarded tick,
+ * ONE such flight would wedge the entire scheduler permanently. Spawning
+ * `detached` makes the child its own group leader, so `kill(-pid, SIGKILL)`
+ * takes down the whole tree and the flight can never exceed its budget.
+ */
+export function runFlightCommand(command, cwd, timeoutMs = 30_000, extraEnv) {
+    const env = extraEnv ? { ...process.env, ...extraEnv } : process.env;
+    const MAX_CAPTURE = 1024 * 1024;
+    return new Promise((resolve) => {
+        let settled = false;
+        let stdout = '';
+        let stderr = '';
+        let exitCode = null;
+        let killedByTimeout = false;
+        let exitGrace;
+        // Own process group (detached ⇒ the sh is its own group leader) so the hard
+        // timeout can SIGKILL the WHOLE tree, including a grandchild that outlived
+        // its parent's SIGTERM or kept the stdout pipe open. This is what stops one
+        // runaway flight from wedging the awaiting tick forever.
+        const child = spawn('/bin/sh', ['-c', command], {
+            cwd: cwd ?? process.cwd(),
+            env,
+            detached: true,
+        });
+        const settle = () => {
+            if (settled)
+                return;
+            settled = true;
+            clearTimeout(hardTimer);
+            clearTimeout(exitGrace);
+            // Release the pipe read-ends so a still-open grandchild write-end cannot
+            // keep the bridge's event loop (or the test runner) alive after we return.
+            child.stdout?.destroy();
+            child.stderr?.destroy();
+            child.unref?.();
+            resolve({ stdout, stderr, exitCode: killedByTimeout ? 124 : (exitCode ?? 1) });
+        };
+        const recordExit = (code, signal) => {
+            if (exitCode === null)
+                exitCode = typeof code === 'number' ? code : signal ? 1 : 0;
+        };
+        child.stdout?.on('data', (d) => {
+            if (stdout.length < MAX_CAPTURE)
+                stdout += d.toString('utf8');
+        });
+        child.stderr?.on('data', (d) => {
+            if (stderr.length < MAX_CAPTURE)
+                stderr += d.toString('utf8');
+        });
+        child.on('error', () => {
+            if (exitCode === null)
+                exitCode = 1;
+            settle();
+        });
+        // Settle on 'exit' (the shell terminated), NOT 'close' (all stdio closed):
+        // a backgrounded/detached grandchild keeps the pipe open, so 'close' may
+        // never come. 'close' still wins the race when it fires first (full stdout);
+        // otherwise a short grace after 'exit' lets the parent's own output flush.
+        child.on('exit', (code, signal) => {
+            recordExit(code, signal);
+            exitGrace = setTimeout(settle, 150);
+            exitGrace.unref?.();
+        });
+        child.on('close', (code, signal) => {
+            recordExit(code, signal);
+            settle();
+        });
+        const hardTimer = setTimeout(() => {
+            killedByTimeout = true;
+            if (child.pid) {
+                try {
+                    process.kill(-child.pid, 'SIGKILL'); // whole process group
+                }
+                catch {
+                    try {
+                        child.kill('SIGKILL');
+                    }
+                    catch {
+                        /* already gone */
+                    }
+                }
+            }
+            settle();
+        }, timeoutMs);
+        hardTimer.unref?.();
+    });
+}
+/** Byte-accurate tail: keep the last `maxBytes` of a (possibly huge) terminal log. */
+function truncateTail(text, maxBytes) {
+    const buf = Buffer.from(text, 'utf8');
+    if (buf.length <= maxBytes)
+        return text;
+    return buf.subarray(buf.length - maxBytes).toString('utf8');
+}
+/**
+ * Resolve a finished run to ok/error. ONLY a cleanly `completed` run is 'ok';
+ * a missing record (removed/lost) OR a store status still stuck at
+ * running/pending at finalize time (the process died without a clean status
+ * transition) is a crash ⇒ 'error'. Never reports a crashed run as success.
+ */
+function resolveRunStatus(run) {
+    return run?.status === 'completed' ? 'ok' : 'error';
+}
+/**
+ * The scheduled-loops engine. On each 30s tick it FINALIZES each loop's
+ * in-flight run(s) (Phase A) before deciding whether to FIRE a new one
+ * (Phase B). All side effects go through injected collaborators so it is
+ * unit-testable without a live bridge, real fs or real timers (mirrors
+ * workflow-runner.ts).
+ *
+ * Persistence rule: the scheduler NEVER writes a whole detached Loop back
+ * across an await. Every runtime-field change goes through
+ * store.mutateLoopRuntime (fresh-read → mutate → save), so a loop deleted or
+ * user-edited during a long flight is neither resurrected nor clobbered.
+ */
+export class LoopScheduler {
+    store;
+    runner;
+    centrifugo;
+    userId;
+    spawnSession;
+    removeSession;
+    loops;
+    runRecords;
+    runFlight;
+    now;
+    /** Re-entrancy guard: tick N+1 never overlaps N. */
+    tickRunning = false;
+    /** Set once start() runs (after reconcileOnStart). kick() no-ops before this so an
+     *  early run_loop_now cannot trigger an un-reconciled tick that stampedes overdue loops. */
+    started = false;
+    /** Per-loop in-memory fire lock, shared by tick + run_loop_now/kick. */
+    firingLoops = new Set();
+    /** loopId -> (runSessionId -> fire-time ms). Every run THIS process spawned, so under
+     *  overlapPolicy:'allow' each concurrent run is finalized/postflighted/maxRuntime-checked
+     *  independently — not just the newest. Rebuilt lazily from the persisted primary on restart. */
+    inFlight = new Map();
+    timer;
+    constructor(deps) {
+        this.store = deps.store;
+        this.runner = deps.runner;
+        this.centrifugo = deps.centrifugo;
+        this.userId = deps.userId;
+        this.spawnSession = deps.spawnSession;
+        this.removeSession = deps.removeSession;
+        this.loops = deps.loops ?? { listLoops, mutateLoopRuntime };
+        this.runRecords = deps.runRecords ?? { upsertLoopRunRecord, pruneLoopRunRecords };
+        this.runFlight = deps.runFlight ?? runFlightCommand;
+        this.now = deps.now ?? (() => Date.now());
+    }
+    start() {
+        this.started = true;
+        if (this.timer)
+            return;
+        this.timer = setInterval(() => {
+            void this.tick();
+        }, LOOP_TICK_INTERVAL_MS);
+    }
+    stop() {
+        if (this.timer) {
+            clearInterval(this.timer);
+            this.timer = undefined;
+        }
+    }
+    /** Immediate, guarded, out-of-band tick (used by run_loop_now). No-op until start()
+     *  has run, so a kick that races startup cannot fire before reconcileOnStart. */
+    kick() {
+        if (!this.started)
+            return;
+        if (!this.tickRunning)
+            void this.tick();
+    }
+    /** Drop scheduler tracking for a deleted loop and stop any run it left alive, so a
+     *  just-deleted loop never leaks a live AI session with nothing left to finalize it. */
+    onLoopDeleted(loop) {
+        const ids = new Set();
+        const tracked = this.inFlight.get(loop.id);
+        if (tracked)
+            for (const id of tracked.keys())
+                ids.add(id);
+        if (loop.lastStatus === 'running' && loop.lastSessionId)
+            ids.add(loop.lastSessionId);
+        for (const id of ids) {
+            if (this.runner.isRunning(id))
+                this.runner.stop(id);
+        }
+        this.inFlight.delete(loop.id);
+    }
+    /**
+     * Missed-schedule policy, run once before the first tick: for every loop whose
+     * nextRunAt is missing or already past, recompute it from now (skip missed
+     * occurrences; never stampede overdue loops). runNowRequested is preserved so a
+     * manual override survives a restart and still fires on the first tick. A loop
+     * with a corrupt persisted schedule is skipped here (logged) and reported as an
+     * error on its first fire.
+     */
+    async reconcileOnStart(now = this.now()) {
+        for (const loop of this.loops.listLoops()) {
+            try {
+                const overdue = loop.nextRunAt ? Date.parse(loop.nextRunAt) <= now : true;
+                if (!overdue)
+                    continue;
+                const nextRunMs = computeNextRun(loop.schedule, now); // may throw on a corrupt cron
+                await this.persist(loop.id, (l) => {
+                    l.nextRunAt = iso(nextRunMs);
+                    l.updatedAt = iso(now);
+                });
+            }
+            catch (err) {
+                console.error(`[LoopScheduler] reconcile failed for loop ${loop.id}:`, err);
+            }
+        }
+    }
+    async tick(now = this.now()) {
+        if (this.tickRunning)
+            return; // tick N+1 never overlaps N
+        this.tickRunning = true;
+        try {
+            for (const loop of this.loops.listLoops()) {
+                try {
+                    await this.processLoop(loop, now);
+                }
+                catch (err) {
+                    // One bad loop must not kill the tick (mirrors resurrectSessions).
+                    console.error(`[LoopScheduler] loop ${loop.id} failed:`, err);
+                }
+            }
+        }
+        finally {
+            this.tickRunning = false;
+        }
+    }
+    async processLoop(loop, now) {
+        await this.finalizePhase(loop, now); // Phase A — finalize before fire
+        await this.firePhase(loop, now); // Phase B
+    }
+    /** Phase A: finalize each in-flight run once its PTY is confirmed gone (past grace)
+     *  or over its per-run maxRuntime budget. Under 'allow' this walks every tracked run,
+     *  not just the newest, so none is orphaned. */
+    async finalizePhase(loop, now) {
+        this.ensureTracked(loop);
+        const tracked = this.inFlight.get(loop.id);
+        if (!tracked || tracked.size === 0)
+            return;
+        // Snapshot: finalizeRun mutates the map while we iterate.
+        for (const [runId, startedMs] of [...tracked]) {
+            const running = this.runner.isRunning(runId);
+            const elapsed = now - startedMs;
+            if (running && loop.maxRuntimeMs && elapsed > loop.maxRuntimeMs) {
+                this.runner.stop(runId);
+                await this.finalizeRun(loop, now, runId, true);
+            }
+            else if (!running && elapsed >= LOOP_TICK_INTERVAL_MS) {
+                await this.finalizeRun(loop, now, runId, false);
+            }
+            // else: still running, or still inside the grace window — leave it.
+        }
+    }
+    /** Seed the persisted primary run into in-memory tracking after a restart (when this
+     *  process has spawned nothing yet for the loop), so a run left 'running' by a prior
+     *  process is still finalized. */
+    ensureTracked(loop) {
+        if (loop.lastStatus !== 'running' || !loop.lastSessionId)
+            return;
+        const existing = this.inFlight.get(loop.id);
+        if (existing && existing.size > 0)
+            return; // already tracking this process's run(s)
+        const parsed = Date.parse(loop.lastRunAt ?? '');
+        const startedMs = Number.isNaN(parsed) ? this.now() : parsed;
+        const map = existing ?? new Map();
+        map.set(loop.lastSessionId, startedMs);
+        this.inFlight.set(loop.id, map);
+    }
+    track(loopId, sessionId, startedMs) {
+        const map = this.inFlight.get(loopId) ?? new Map();
+        map.set(sessionId, startedMs);
+        this.inFlight.set(loopId, map);
+    }
+    /** Phase B: fire the loop if due, honoring the per-loop lock and the overlap policy. */
+    async firePhase(loop, now) {
+        if (!isDue(loop, now))
+            return;
+        if (this.firingLoops.has(loop.id))
+            return;
+        // A previous run that has EXITED but was not yet finalized (still inside the
+        // grace window) must be finalized BEFORE we decide to fire. Otherwise a
+        // skip-policy loop double-fires in the grace window (isRunning is already
+        // false, so the overlap guard below misses it) and the just-finished run is
+        // orphaned — its finalize/postflight never runs.
+        if (loop.lastStatus === 'running' && loop.lastSessionId && !this.runner.isRunning(loop.lastSessionId)) {
+            await this.finalizeRun(loop, now, loop.lastSessionId, false);
+            const fresh = this.loops.listLoops().find((l) => l.id === loop.id);
+            if (!fresh)
+                return; // deleted during finalize
+            loop = fresh;
+        }
+        // Overlap guard: a skip-policy loop whose previous run is STILL alive advances
+        // its schedule only — no new fire, no skipCount bump (overlap-skip is not a
+        // preflight-skip).
+        if (loop.overlapPolicy === 'skip' &&
+            loop.lastStatus === 'running' &&
+            loop.lastSessionId &&
+            this.runner.isRunning(loop.lastSessionId)) {
+            await this.persist(loop.id, (l) => {
+                try {
+                    l.nextRunAt = iso(computeNextRun(l.schedule, now));
+                }
+                catch {
+                    /* corrupt schedule surfaces as an error on the fire path, not here */
+                }
+                l.runNowRequested = false;
+                l.updatedAt = iso(now);
+            });
+            return;
+        }
+        this.firingLoops.add(loop.id);
+        try {
+            await this.fireLoop(loop, now);
+        }
+        finally {
+            this.firingLoops.delete(loop.id);
+        }
+    }
+    /** Advance the schedule up front (so failures/skips never stampede), then preflight → flight. */
+    async fireLoop(loop, now) {
+        // Compute the next fire first so a persisted-corrupt schedule is reported as an
+        // error (with a bounded backoff) instead of silently re-throwing every tick.
+        let nextRunMs;
+        try {
+            nextRunMs = computeNextRun(loop.schedule, now);
+        }
+        catch (err) {
+            await this.persist(loop.id, (l) => {
+                l.lastRunAt = iso(now);
+                l.nextRunAt = iso(now + LOOP_TICK_INTERVAL_MS); // bounded backoff — no stampede
+                l.runNowRequested = false;
+                l.lastStatus = 'error';
+                l.updatedAt = iso(now);
+            });
+            console.error(`[LoopScheduler] bad schedule for loop ${loop.id}:`, err);
+            return;
+        }
+        try {
+            let preflightOut = '';
+            if (loop.preflight) {
+                const r = await this.runFlight(loop.preflight.command, loop.workdir, loop.preflight.timeoutMs);
+                preflightOut = r.stdout;
+                if (r.exitCode !== 0) {
+                    const skippedAt = iso(now);
+                    const details = [
+                        `Preflight exited with code ${r.exitCode}.`,
+                        r.stdout ? `\nstdout:\n${r.stdout}` : '',
+                        r.stderr ? `\nstderr:\n${r.stderr}` : '',
+                    ].join('');
+                    // ABORT: skip (not error), no session, no run-node.
+                    const skipped = await this.persist(loop.id, (l) => {
+                        l.lastRunAt = skippedAt;
+                        l.nextRunAt = iso(nextRunMs);
+                        l.runNowRequested = false;
+                        l.lastStatus = 'skipped';
+                        l.skipCount += 1;
+                        l.updatedAt = skippedAt;
+                    });
+                    if (skipped) {
+                        this.runRecords.upsertLoopRunRecord(skippedRunRecord(loop, skippedAt, details));
+                    }
+                    if (skipped && loop.postflight?.runOnSkip) {
+                        await this.runPostflight(loop, { status: 'skipped', sessionId: '', output: '' });
+                    }
+                    return;
+                }
+            }
+            const task = loop.task.replaceAll('{{preflight}}', preflightOut);
+            const session = await this.spawnSession({
+                shellType: loop.harness,
+                prompt: task,
+                workingDir: loop.workdir,
+                model: loop.model,
+                env: preflightOut ? { FTOWN_PREFLIGHT_OUTPUT: preflightOut } : undefined,
+                loopId: loop.id,
+                suppressBriefing: true, // no child/orchestrator briefing paragraph in the task
+                name: `${loop.name} · ${iso(now)}`,
+                // parentSessionId intentionally omitted — loopId is the sole grouping key.
+            });
+            const updated = await this.persist(loop.id, (l) => {
+                l.lastRunAt = iso(now);
+                l.nextRunAt = iso(nextRunMs);
+                l.runNowRequested = false;
+                l.lastSessionId = session.id;
+                l.lastStatus = 'running';
+                l.runCount += 1;
+                l.updatedAt = iso(now);
+            });
+            if (!updated) {
+                // The loop was deleted during preflight/spawn: do not resurrect it and do
+                // not leave an orphan run that nothing would ever finalize or prune.
+                this.runner.stop(session.id);
+                await this.removeSession(session.id).catch(() => undefined);
+                return;
+            }
+            this.runRecords.upsertLoopRunRecord(recordForSession(updated, session, iso(now)));
+            this.track(loop.id, session.id, now);
+        }
+        catch (err) {
+            // A failure after the schedule was computed: record error + persist so the
+            // loop resumes its cadence instead of stampede-retrying every tick.
+            await this.persist(loop.id, (l) => {
+                l.lastRunAt = iso(now);
+                l.nextRunAt = iso(nextRunMs);
+                l.runNowRequested = false;
+                l.lastStatus = 'error';
+                l.updatedAt = iso(now);
+            });
+            console.error(`[LoopScheduler] fire failed for loop ${loop.id}:`, err);
+        }
+    }
+    /** Resolve one finished run to ok/error, update the loop badge (only if this is the
+     *  loop's tracked/latest run), then run postflight + retention for it. */
+    async finalizeRun(loop, now, runId, forcedError) {
+        const tracked = this.inFlight.get(loop.id);
+        const startedMs = tracked?.get(runId) ?? Date.parse(loop.lastRunAt ?? iso(now));
+        if (tracked) {
+            tracked.delete(runId);
+            if (tracked.size === 0)
+                this.inFlight.delete(loop.id);
+        }
+        const run = runId ? await this.store.loadSession(runId) : null;
+        const status = forcedError ? 'error' : resolveRunStatus(run);
+        const fullOutput = runId ? await this.store.loadTerminalLog(runId) : '';
+        const output = truncateTail(fullOutput, 65_536);
+        const outputBytes = Buffer.byteLength(fullOutput, 'utf8');
+        const tailBytes = Buffer.byteLength(output, 'utf8');
+        // Only the loop's most-recently-STARTED run (lastSessionId) drives the badge;
+        // an older overlapping 'allow' run finalizes silently (still postflight +
+        // retention) without flipping the badge away from a newer run's state.
+        const updated = await this.persist(loop.id, (l) => {
+            if (l.lastSessionId === runId)
+                l.lastStatus = status;
+            l.updatedAt = iso(now);
+        });
+        void updated;
+        const baseRecord = run
+            ? recordForSession(loop, run, Number.isFinite(startedMs) ? iso(startedMs) : run.createdAt)
+            : {
+                id: runId,
+                loopId: loop.id,
+                bridgeId: loop.bridgeId,
+                sessionId: runId,
+                name: `${loop.name} · ${runId}`,
+                status,
+                startedAt: Number.isFinite(startedMs) ? iso(startedMs) : iso(now),
+                updatedAt: iso(now),
+                harness: loop.harness,
+                workdir: loop.workdir,
+                task: loop.task,
+                model: loop.model,
+                sessionStatus: undefined,
+            };
+        this.runRecords.upsertLoopRunRecord({
+            ...baseRecord,
+            status,
+            sessionStatus: run?.status,
+            errorReason: forcedError ? 'max_runtime_exceeded' : run?.errorReason,
+            updatedAt: iso(now),
+            finishedAt: iso(now),
+            durationMs: Math.max(0, now - (Number.isFinite(startedMs) ? startedMs : now)),
+            logTail: output,
+            logBytes: outputBytes,
+            logTruncated: outputBytes > tailBytes,
+        });
+        if (loop.postflight) {
+            await this.runPostflight(loop, { status, sessionId: runId, output });
+        }
+        await this.pruneRuns(loop);
+    }
+    async runPostflight(loop, ctx) {
+        if (!loop.postflight)
+            return;
+        await this.runFlight(loop.postflight.command, loop.workdir, loop.postflight.timeoutMs, {
+            FTOWN_RUN_STATUS: ctx.status,
+            FTOWN_RUN_SESSION_ID: ctx.sessionId,
+            FTOWN_RUN_OUTPUT: ctx.output,
+        });
+    }
+    /** Keep the newest N run-sessions for this loop; prune older finished ones. */
+    async pruneRuns(loop) {
+        const keep = loop.retention.autoClearAfterRuns;
+        if (keep == null)
+            return;
+        const runs = (await this.store.listSessions())
+            .filter((s) => s.loopId === loop.id)
+            .sort((a, b) => Date.parse(b.createdAt) - Date.parse(a.createdAt));
+        for (const run of runs.slice(keep)) {
+            if (this.runner.isRunning(run.id))
+                continue;
+            if (run.id === loop.lastSessionId)
+                continue;
+            await this.removeSession(run.id, { onlyIfFinished: true });
+        }
+        this.runRecords.pruneLoopRunRecords(loop.id, keep, [loop.lastSessionId, ...runs.filter((run) => this.runner.isRunning(run.id)).map((run) => run.id)]);
+    }
+    async persist(id, fn) {
+        const updated = this.loops.mutateLoopRuntime(id, fn);
+        if (updated)
+            await this.publish(updated);
+        return updated;
+    }
+    async publish(loop) {
+        try {
+            await this.centrifugo.publishLoopUpdate(this.userId, loop);
+        }
+        catch (err) {
+            // A UI-sync failure must never break the scheduler (matches session create).
+            console.error(`[LoopScheduler] Failed to publish loop update for ${loop.id}:`, err);
+        }
+    }
+}
+//# sourceMappingURL=loop-scheduler.js.map