freddie 0.0.117 → 0.0.119

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "freddie",
-  "version": "0.0.117",
+  "version": "0.0.119",
   "type": "module",
   "description": "Open JS agent harness built on pi-mono, floosie, xstate, and anentrypoint-design",
   "bin": {
@@ -27,7 +27,7 @@
     "@mariozechner/pi-ai": "^0.70.6",
     "@mariozechner/pi-coding-agent": "^0.70.6",
     "@mariozechner/pi-tui": "^0.70.6",
-    "acptoapi": "^1.0.112",
+    "acptoapi": "^1.0.114",
     "anentrypoint-design": "^0.0.140",
     "commander": "^14.0.0",
     "express": "^5.0.0",

package/plugins/gui-machines/plugin.js

@@ -0,0 +1,49 @@
+// Exposes live persisted machine snapshots over HTTP for the dashboard.
+// GET /api/machines        -> { count, kinds:{<kind>:n}, machines:[{kind,key,status,state,updated}] }
+// GET /api/machines/:kind  -> machines filtered to one kind
+// POST /api/machines/resume -> { ok, summary } : drive resumeAll() on demand
+import { list } from '../../src/machines/snapshot-store.js'
+import { registerDebug } from '../../src/observability/debug.js'
+
+// window.__debug.machines() / GET /debug/machines — live persisted machine census.
+registerDebug('machines', () => ({ note: 'GET /api/machines for live snapshots', kinds: ['agent', 'cron', 'batch', 'gateway', 'gateway-msg', 'acp', 'acp-prompt'] }))
+
+async function snapshotRows(kind = null) {
+    const rows = await list({ kind, status: null })
+    return rows.map(r => {
+        let state = null
+        try { const ps = JSON.parse(r.snapshot_json || 'null'); state = ps?.value ?? null } catch {}
+        return { kind: r.kind, key: r.key, status: r.status, state, machine_id: r.machine_id, updated: r.updated }
+    })
+}
+
+export default {
+    name: 'gui-machines', surfaces: 'gui',
+    register({ gui }) {
+        gui.route('GET', '/api/machines', async (_req, res) => {
+            try {
+                // list() does not return snapshot_json (truncated for size); re-read full per row.
+                const { db } = await import('../../src/db.js')
+                const d = await db()
+                await d.exec(`CREATE TABLE IF NOT EXISTS machine_snapshots (kind TEXT, key TEXT, schema_version INTEGER, machine_id TEXT, snapshot_json TEXT, status TEXT, updated INTEGER, PRIMARY KEY(kind,key))`)
+                const all = await d.prepare(`SELECT kind, key, machine_id, snapshot_json, status, updated FROM machine_snapshots ORDER BY updated DESC`).all()
+                const kinds = {}
+                const machines = all.map(r => {
+                    kinds[r.kind] = (kinds[r.kind] || 0) + 1
+                    let state = null
+                    try { state = JSON.parse(r.snapshot_json || 'null')?.value ?? null } catch {}
+                    return { kind: r.kind, key: r.key, status: r.status, state, machine_id: r.machine_id, updated: r.updated }
+                })
+                res.json({ count: machines.length, kinds, machines })
+            } catch (e) { res.status(500).json({ error: String(e.message || e) }) }
+        })
+        gui.route('GET', '/api/machines/:kind', async (req, res) => {
+            try { res.json({ machines: await snapshotRows(req.params.kind) }) }
+            catch (e) { res.status(500).json({ error: String(e.message || e) }) }
+        })
+        gui.route('POST', '/api/machines/resume', async (_req, res) => {
+            try { const { resumeAll } = await import('../../src/machines/resume.js'); res.json({ ok: true, summary: await resumeAll() }) }
+            catch (e) { res.status(500).json({ error: String(e.message || e) }) }
+        })
+    },
+}

package/src/acp/main.js

@@ -1,5 +1,6 @@
 import { AcpServer } from './server.js'
-export function startAcpStdio() {
+export async function startAcpStdio() {
+    try { const { resumeAll } = await import('../machines/resume.js'); await resumeAll() } catch (_) {}
     const srv = new AcpServer()
     srv.start()
     process.on('SIGINT', () => { srv.stop(); process.exit(0) })

package/src/acp/server.js

@@ -6,9 +6,26 @@ import { logger } from '../observability/log.js'
 import { Events } from './events.js'
 import { checkPermission, rememberAllow, rememberDeny } from './permissions.js'
 import { AcpSessionManager } from './session.js'
+import { createMachine, createActor } from 'xstate'
+import { persist, load, clear } from '../machines/snapshot-store.js'
 
 const log = logger('acp')
 
+// ACP server lifecycle machine: stopped -> running -> stopped. Persisted so an
+// active snapshot on boot signals the server was serving; per-prompt processing
+// is persisted separately under kind=acp-prompt so an interrupted prompt.submit
+// is observable + resumable after a restart.
+export function createAcpMachine() {
+    return createMachine({
+        id: 'freddie-acp',
+        initial: 'stopped',
+        states: {
+            stopped: { on: { START: 'running' } },
+            running: { on: { STOP: 'stopped' } },
+        },
+    })
+}
+
 const CAPABILITIES = {
     name: 'freddie', version: '0.4.0',
     methods: ['initialize', 'session.new', 'session.resume', 'session.list', 'session.end', 'prompt.submit', 'tool.list', 'permission.respond', 'shutdown'],
@@ -21,13 +38,19 @@ export class AcpServer extends EventEmitter {
         this.in = stdin; this.out = stdout; this.callLLM = callLLM
         this.sessions = new AcpSessionManager()
         this._pendingPerm = new Map()
+        this.machine = createAcpMachine()
+        this.actor = createActor(this.machine)
+        this.actor.subscribe(() => { persist('acp', 'lifecycle', this.actor.getPersistedSnapshot()).catch(() => {}) })
+        this.actor.start()
     }
+    get state() { return this.actor.getSnapshot().value }
     start() {
         const rl = readline.createInterface({ input: this.in, crlfDelay: Infinity })
         rl.on('line', (l) => this.handle(l).catch(e => this.send({ jsonrpc: '2.0', error: { message: String(e) } })))
         this.rl = rl
+        this.actor.send({ type: 'START' })
     }
-    stop() { this.rl?.close() }
+    stop() { this.rl?.close(); try { this.actor.send({ type: 'STOP' }) } catch {} }
     send(o) { this.out.write(JSON.stringify(o) + '\n') }
     async handle(line) {
         if (!line.trim()) return
@@ -75,7 +98,12 @@ const METHODS = {
         if (!srv.sessions.isActive(sessionId)) throw new Error('session not active')
         srv.sessions.appendUser(sessionId, prompt)
         Events.messageDelta((o) => srv.send(o), { sessionId, role: 'user', content: prompt })
-        const out = await runTurn({ prompt, callLLM: srv.callLLM })
+        // Persist in-flight prompt under kind=acp-prompt keyed by sessionId so a
+        // refresh mid-turn is observable + resumable (the agent snapshot for the
+        // turn itself lives under kind=agent via runTurn sessionKey).
+        await persist('acp-prompt', sessionId, { status: 'active', value: 'running', context: { sessionId, prompt } })
+        const out = await runTurn({ prompt, callLLM: srv.callLLM, sessionKey: 'acp:' + sessionId })
+        await clear('acp-prompt', sessionId)
         srv.sessions.appendAssistant(sessionId, out.result || '')
         Events.messageComplete((o) => srv.send(o), { sessionId, role: 'assistant', content: out.result || '' })
         return { result: out.result, error: out.error, iterations: out.iterations }

package/src/agent/acptoapi-bridge.js

@@ -121,7 +121,7 @@ function adaptResponse(r) {
 
 function tryParseJson(s) { try { return typeof s === 'string' ? JSON.parse(s) : (s || {}) } catch { return {} } }
 
-export async function isReachable(timeoutMs = 2000) {
+export async function isReachable(timeoutMs = 10000) {
     try {
         const controller = new AbortController()
         const timeoutId = setTimeout(() => controller.abort(), timeoutMs)

package/src/agent/machine.js

@@ -3,6 +3,8 @@ import { bootHost } from '../host/index.js'
 import { getEnabledToolSchemas } from '../toolsets.js'
 import { logger } from '../observability/log.js'
 import { resolveCallLLM } from './llm_resolver.js'
+import { createPersistentActor } from '../machines/persistent-actor.js'
+import { randomUUID } from 'node:crypto'
 
 const log = logger('agent')
 
@@ -55,7 +57,18 @@ export function createAgentMachine({ provider, model, maxIterations = 90, callLL
                     input: ({ context }) => ({ messages: context.messages, model: context.model, provider: context.provider, enabledToolsets: context.enabledToolsets, disabledToolsets: context.disabledToolsets }),
                     onDone: [
                         { guard: ({ event }) => Array.isArray(event.output?.tool_calls) && event.output.tool_calls.length > 0, target: 'tool_calls', actions: assign({ messages: ({ context, event }) => [...context.messages, { role: 'assistant', content: event.output.content || '', tool_calls: event.output.tool_calls }] }) },
-                        { target: 'done', actions: assign({ messages: ({ context, event }) => [...context.messages, { role: 'assistant', content: event.output.content || '' }], lastResult: ({ event }) => event.output.content || '' }) },
+                        { target: 'done', actions: assign({ messages: ({ context, event }) => [...context.messages, { role: 'assistant', content: event.output.content || '' }], lastResult: ({ context, event }) => {
+                            // Prefer this turn's content, but if the model ended with empty
+                            // text (it may have put its answer in an earlier turn alongside a
+                            // tool_call), fall back to the last non-empty assistant message so
+                            // the caller never gets an empty result after a successful run.
+                            if (event.output.content && event.output.content.trim()) return event.output.content;
+                            for (let i = context.messages.length - 1; i >= 0; i--) {
+                                const m = context.messages[i];
+                                if (m.role === 'assistant' && typeof m.content === 'string' && m.content.trim()) return m.content;
+                            }
+                            return event.output.content || '';
+                        } }) },
                     ],
                     onError: { target: 'done', actions: assign({ error: ({ event }) => String(event.error?.message || event.error) }) },
                 },
@@ -159,21 +172,14 @@ function mergeHookExtras(messages, r, tag) {
     return e.length ? [...messages, ...e] : messages
 }
 
-export async function runTurn({ prompt, messages = [], model, provider, callLLM, enabledToolsets, disabledToolsets, maxIterations = 90, timeoutMs = 30000, cwd, skill, witnessPath } = {}) {
-    const events = []; const h = await bootHost()
-    await h.hooks.invoke('onSessionStart', { prompt, model, provider, skill, cwd })
-    let initMessages = [...messages]; const sysParts = []
-    if (cwd) sysParts.push(`Working directory: ${cwd}. Always pass cwd="${cwd}" to bash tool calls. When reading or writing files use paths relative to this directory or absolute paths under it.`)
-    if (skill) { const sd = h.pi.skills.get(skill); if (sd?.content) sysParts.push('Skill context:\n' + sd.content) }
-    if (sysParts.length) initMessages.unshift({ role: 'user', content: sysParts.join('\n\n') })
-    const inbound = await h.hooks.invoke('onMessageInbound', { content: prompt })
-    if (inbound?.behavior === 'block') { await h.hooks.invoke('onSessionEnd', { reason: 'prompt_blocked' }); return { messages: initMessages, result: null, error: 'prompt blocked by plugsdk hook: ' + (inbound.reason || 'denied'), iterations: 0 } }
-    initMessages = mergeHookExtras(initMessages, inbound, 'onMessageInbound')
-    const machine = createAgentMachine({ model, provider, callLLM, enabledToolsets, disabledToolsets, maxIterations, events })
-    const actor = createActor(machine, { input: { messages: initMessages } }); actor.start(); actor.send({ type: 'SUBMIT', prompt })
+// Drive a started persistent agent actor to its final state, wiring timeout +
+// session-end hooks + trajectory. Shared by runTurn (fresh) and resumeTurn
+// (rehydrated from a persisted snapshot after a refresh/restart).
+async function driveAgentActor({ pa, h, events, prompt, provider, model, skill, cwd, witnessPath, timeoutMs }) {
+    const { actor } = pa
     return await new Promise((resolve, reject) => {
         let sub
-        const cleanup = () => { try { sub?.unsubscribe() } catch {} try { actor.stop() } catch {} }
+        const cleanup = () => { try { sub?.unsubscribe() } catch {} ; pa.flush().catch(() => {}).finally(() => { try { actor.stop() } catch {} }) }
         const t = setTimeout(() => { cleanup(); reject(new Error('agent turn timeout')) }, timeoutMs)
         sub = actor.subscribe(snap => { if (snap.status !== 'done') return; clearTimeout(t)
             ;(async () => {
@@ -183,8 +189,9 @@ export async function runTurn({ prompt, messages = [], model, provider, callLLM,
                 await h.hooks.invoke('onSessionEnd', { reason: out?.error ? 'error' : 'ok', iterations: out?.iterations })
                 const errorStack = out?.error ? (events.find(e => e.type === 'llm_call' && !e.ok)?.stack || null) : null
                 await writeTrajectory(out, { prompt, provider, model, skill, cwd, events, errorStack, witnessPath })
-                // Unsubscribe + stop the actor once the turn is done — a finished
-                // actor should not be left running with live subscriptions/handles.
+                // Unsubscribe, flush the final snapshot (persistent-actor clears it on
+                // the done state) + stop the actor — a finished actor should not be
+                // left running with live subscriptions/handles.
                 cleanup()
                 resolve(out)
             })().catch(e => { cleanup(); reject(e) })
@@ -192,6 +199,39 @@ export async function runTurn({ prompt, messages = [], model, provider, callLLM,
     })
 }
 
+export async function runTurn({ prompt, messages = [], model, provider, callLLM, enabledToolsets, disabledToolsets, maxIterations = 90, timeoutMs = 30000, cwd, skill, witnessPath, sessionKey } = {}) {
+    const events = []; const h = await bootHost()
+    await h.hooks.invoke('onSessionStart', { prompt, model, provider, skill, cwd })
+    let initMessages = [...messages]; const sysParts = []
+    if (cwd) sysParts.push(`Working directory: ${cwd}. Always pass cwd="${cwd}" to bash tool calls. When reading or writing files use paths relative to this directory or absolute paths under it.`)
+    if (skill) { const sd = h.pi.skills.get(skill); if (sd?.content) sysParts.push('Skill context:\n' + sd.content) }
+    if (sysParts.length) initMessages.unshift({ role: 'user', content: sysParts.join('\n\n') })
+    const inbound = await h.hooks.invoke('onMessageInbound', { content: prompt })
+    if (inbound?.behavior === 'block') { await h.hooks.invoke('onSessionEnd', { reason: 'prompt_blocked' }); return { messages: initMessages, result: null, error: 'prompt blocked by plugsdk hook: ' + (inbound.reason || 'denied'), iterations: 0 } }
+    initMessages = mergeHookExtras(initMessages, inbound, 'onMessageInbound')
+    const machine = createAgentMachine({ model, provider, callLLM, enabledToolsets, disabledToolsets, maxIterations, events })
+    // Persist the turn snapshot under kind=agent so an interrupted turn (process
+    // refresh mid-tool-call) resumes exactly where it stopped via resumeTurn.
+    const key = sessionKey || randomUUID()
+    const pa = await createPersistentActor(machine, { kind: 'agent', key, input: { messages: initMessages } })
+    pa.actor.send({ type: 'SUBMIT', prompt })
+    return await driveAgentActor({ pa, h, events, prompt, provider, model, skill, cwd, witnessPath, timeoutMs })
+}
+
+// Rehydrate an interrupted turn from its persisted snapshot and drive it to
+// completion. Returns null if no live snapshot exists for the key (already
+// completed or never persisted) — caller falls back to a fresh runTurn.
+export async function resumeTurn({ sessionKey, model, provider, callLLM, enabledToolsets, disabledToolsets, maxIterations = 90, timeoutMs = 30000, cwd, skill, witnessPath } = {}) {
+    if (!sessionKey) throw new Error('resumeTurn requires sessionKey')
+    const { load } = await import('../machines/snapshot-store.js')
+    if (!(await load('agent', sessionKey))) return null
+    const events = []; const h = await bootHost()
+    const machine = createAgentMachine({ model, provider, callLLM, enabledToolsets, disabledToolsets, maxIterations, events })
+    const pa = await createPersistentActor(machine, { kind: 'agent', key: sessionKey, input: { messages: [] } })
+    if (!pa.resumed) { await pa.forget(); return null }
+    return await driveAgentActor({ pa, h, events, prompt: '', provider, model, skill, cwd, witnessPath, timeoutMs })
+}
+
 export async function invokeCompactHooks({ trigger = 'auto', messages = [] } = {}) {
     const h = await bootHost()
     const pre = await h.hooks.invoke('onPreCompact', { trigger, messages })

package/src/batch.js

@@ -3,30 +3,94 @@ import path from 'node:path'
 import { runTurn } from './agent/machine.js'
 import { getFreddieHome } from './home.js'
 import { randomUUID } from 'node:crypto'
+import { createMachine, assign, fromPromise } from 'xstate'
+import { createPersistentActor } from './machines/persistent-actor.js'
+import { load } from './machines/snapshot-store.js'
 
-export async function runBatch({ prompts = [], concurrency = 4, model, callLLM } = {}) {
+// Run one prompt and append its result to the batch jsonl file.
+async function runOne({ job, model, callLLM, file }) {
+    let rec
+    try {
+        const out = await runTurn({ prompt: job.p, model, callLLM, timeoutMs: 60000 })
+        rec = { i: job.i, prompt: job.p, result: out.result, error: out.error }
+    } catch (e) {
+        rec = { i: job.i, prompt: job.p, error: String(e?.message || e) }
+    }
+    fs.appendFileSync(file, JSON.stringify(rec) + '\n')
+    return rec
+}
+
+// xstate batch machine. Context tracks done[] (indices completed) + results so a
+// refreshed batch resumes only the unfinished prompts. running -> running until
+// every index is done, then -> complete (final). The persisted snapshot is keyed
+// by kind=batch key=<batchId>.
+export function createBatchMachine({ prompts, concurrency, model, callLLM, file } = {}) {
+    return createMachine({
+        id: 'freddie-batch',
+        initial: 'running',
+        output: ({ context }) => ({ id: context.id, file: context.file, results: context.results }),
+        context: ({ input }) => ({
+            id: input.id, file: input.file, model: input.model, concurrency: input.concurrency,
+            prompts: input.prompts, done: input.done || [], results: input.results || new Array(input.prompts.length).fill(null),
+        }),
+        states: {
+            running: {
+                always: { guard: ({ context }) => context.done.length >= context.prompts.length, target: 'complete' },
+                invoke: {
+                    src: fromPromise(async ({ input }) => {
+                        const { context } = input
+                        const pending = context.prompts
+                            .map((p, i) => ({ i, p }))
+                            .filter(({ i }) => !context.done.includes(i))
+                            .slice(0, context.concurrency)
+                        return await Promise.all(pending.map(job => runOne({ job, model: context.model, callLLM, file: context.file })))
+                    }),
+                    input: ({ context }) => ({ context }),
+                    onDone: {
+                        target: 'running',
+                        reenter: true,
+                        actions: assign({
+                            done: ({ context, event }) => [...context.done, ...event.output.map(r => r.i)],
+                            results: ({ context, event }) => { const r = [...context.results]; for (const rec of event.output) r[rec.i] = rec; return r },
+                        }),
+                    },
+                },
+            },
+            complete: { type: 'final', output: ({ context }) => ({ id: context.id, file: context.file, results: context.results }) },
+        },
+    })
+}
+
+export async function runBatch({ prompts = [], concurrency = 4, model, callLLM, batchId } = {}) {
     if (!Array.isArray(prompts) || prompts.length === 0) throw new Error('prompts required')
-    const id = randomUUID()
+    const id = batchId || randomUUID()
     const dir = path.join(getFreddieHome(), 'batches')
     fs.mkdirSync(dir, { recursive: true })
     const file = path.join(dir, id + '.jsonl')
-    const stream = fs.createWriteStream(file, { flags: 'a' })
-    const queue = prompts.map((p, i) => ({ i, p }))
-    const results = new Array(prompts.length)
-    const workers = Array.from({ length: Math.min(concurrency, prompts.length) }, async () => {
-        while (queue.length) {
-            const job = queue.shift()
-            if (!job) break
-            try {
-                const out = await runTurn({ prompt: job.p, model, callLLM, timeoutMs: 60000 })
-                results[job.i] = { i: job.i, prompt: job.p, result: out.result, error: out.error }
-            } catch (e) {
-                results[job.i] = { i: job.i, prompt: job.p, error: String(e?.message || e) }
-            }
-            stream.write(JSON.stringify(results[job.i]) + '\n')
-        }
+    const machine = createBatchMachine({ model, callLLM })
+    const pa = await createPersistentActor(machine, { kind: 'batch', key: id, input: { id, file, model, concurrency, prompts } })
+    return await driveBatch(pa)
+}
+
+// Resume an interrupted batch from its persisted snapshot — only the prompts not
+// yet in context.done get re-run. Returns null if no live snapshot for the id.
+export async function resumeBatch({ batchId, model, callLLM } = {}) {
+    if (!batchId) throw new Error('resumeBatch requires batchId')
+    if (!(await load('batch', batchId))) return null
+    const machine = createBatchMachine({ model, callLLM })
+    const pa = await createPersistentActor(machine, { kind: 'batch', key: batchId, input: { id: batchId, file: '', model, concurrency: 4, prompts: [] } })
+    if (!pa.resumed) { await pa.forget(); return null }
+    return await driveBatch(pa)
+}
+
+function driveBatch(pa) {
+    const { actor } = pa
+    return new Promise((resolve, reject) => {
+        const sub = actor.subscribe(snap => {
+            if (snap.status !== 'done') return
+            const out = snap.output
+            pa.flush().catch(() => {}).finally(() => { try { sub.unsubscribe() } catch {}; try { actor.stop() } catch {}; resolve(out) })
+        })
+        actor.subscribe({ error: (e) => { try { sub.unsubscribe() } catch {}; reject(e) } })
     })
-    await Promise.all(workers)
-    await new Promise(r => stream.end(r))
-    return { id, file, results }
 }

package/src/cli/gateway_cli.js

@@ -4,6 +4,8 @@ import { registerBuiltinHooks } from '../gateway/builtin_hooks/index.js'
 let _gateway = null
 export async function startGateway({ port = 0, hooks = true } = {}) {
     if (_gateway) return _gateway
+    // Rehydrate interrupted agent turns / batches before the gateway starts taking traffic.
+    try { const { resumeAll } = await import('../machines/resume.js'); await resumeAll() } catch (_) {}
     const wh = await makePlatform('webhook', { port })
     const api = await makePlatform('api_server', { port: 0 })
     const gw = new Gateway({ platforms: { webhook: wh, api_server: api } })

package/src/cron/scheduler.js

@@ -2,11 +2,11 @@ import { db } from '../db.js'
 import { parseCron, matches } from './cron-parse.js'
 import { runTurn } from '../agent/machine.js'
 import { logger } from '../observability/log.js'
+import { createMachine, assign, fromPromise } from 'xstate'
+import { createPersistentActor } from '../machines/persistent-actor.js'
 
 const log = logger('cron')
 
-let _interval = null
-
 async function init() {
     const d = await db()
     await d.exec(`CREATE TABLE IF NOT EXISTS cron_jobs (id INTEGER PRIMARY KEY AUTOINCREMENT, cron TEXT NOT NULL, prompt TEXT NOT NULL, model TEXT, last_run INTEGER, created INTEGER NOT NULL, enabled INTEGER NOT NULL DEFAULT 1)`)
@@ -52,6 +52,31 @@ export async function tick(now = new Date(), { callLLM = null } = {}) {
     return fired
 }
 
+// xstate scheduler machine: idle -> ticking -> idle. The persisted snapshot
+// carries tick_count + last_tick_ms so a refreshed scheduler resumes its cadence;
+// per-job fire-state (last_run minute) lives durably in cron_jobs, so a restart
+// never double-fires a job that already ran this minute.
+export function createCronMachine({ callLLM = null, intervalMs = 30000 } = {}) {
+    return createMachine({
+        id: 'freddie-cron',
+        initial: 'idle',
+        context: ({ input }) => ({ tickCount: input?.tickCount || 0, lastTickMs: input?.lastTickMs || 0, intervalMs, lastFired: [] }),
+        states: {
+            idle: { after: { [intervalMs]: 'ticking' }, on: { TICK_NOW: 'ticking', STOP: 'stopped' } },
+            ticking: {
+                invoke: {
+                    src: fromPromise(async () => tick(new Date(), { callLLM })),
+                    onDone: { target: 'idle', actions: assign({ tickCount: ({ context }) => context.tickCount + 1, lastTickMs: () => Date.now(), lastFired: ({ event }) => (event.output || []).map(j => j.id) }) },
+                    onError: { target: 'idle', actions: ({ event }) => log.error('cron tick errored', { err: String(event.error) }) },
+                },
+            },
+            stopped: { type: 'final' },
+        },
+    })
+}
+
+// Legacy in-memory interval scheduler (kept for tests + non-resumable callers).
+let _interval = null
 export function startScheduler({ callLLM = null, intervalMs = 30000 } = {}) {
     stopScheduler()
     _interval = setInterval(() => { tick(new Date(), { callLLM }) }, intervalMs)
@@ -61,3 +86,22 @@ export function startScheduler({ callLLM = null, intervalMs = 30000 } = {}) {
 export function stopScheduler() {
     if (_interval) { clearInterval(_interval); _interval = null }
 }
+
+// Resumable scheduler: persists its machine snapshot every transition under
+// kind=cron key=scheduler. On boot resume.js rehydrates it and it continues
+// ticking. Returns the persistent-actor handle.
+let _persistentCron = null
+export async function startPersistentScheduler({ callLLM = null, intervalMs = 30000 } = {}) {
+    if (_persistentCron) return _persistentCron
+    const machine = createCronMachine({ callLLM, intervalMs })
+    _persistentCron = await createPersistentActor(machine, { kind: 'cron', key: 'scheduler', input: {} })
+    return _persistentCron
+}
+
+export async function stopPersistentScheduler() {
+    if (!_persistentCron) return
+    try { _persistentCron.actor.send({ type: 'STOP' }) } catch {}
+    await _persistentCron.flush()
+    try { _persistentCron.actor.stop() } catch {}
+    _persistentCron = null
+}

package/src/gateway/run.js

@@ -1,30 +1,68 @@
 import { logger } from '../observability/log.js'
 import { runTurn } from '../agent/machine.js'
+import { createMachine, assign, fromPromise, createActor } from 'xstate'
+import { persist, load, clear } from '../machines/snapshot-store.js'
+import { randomUUID } from 'node:crypto'
 
 const log = logger('gateway')
 
+// Gateway lifecycle machine: stopped -> starting -> running -> stopping -> stopped.
+// The running state's context tracks platform names; lifecycle is the resumable
+// shape. In-flight inbound message processing is persisted separately (per-message
+// snapshot under kind=gateway-msg) so a refresh re-drives messages whose reply was
+// never sent.
+export function createGatewayMachine({ platformNames = [] } = {}) {
+    return createMachine({
+        id: 'freddie-gateway',
+        initial: 'stopped',
+        context: ({ input }) => ({ platformNames: input?.platformNames || platformNames }),
+        states: {
+            stopped: { on: { START: 'starting' } },
+            starting: { on: { STARTED: 'running', FAIL: 'stopped' } },
+            running: { on: { STOP: 'stopping' } },
+            stopping: { on: { STOPPED: 'stopped' } },
+        },
+    })
+}
+
 export class Gateway {
     constructor({ platforms = {}, callLLM = null } = {}) {
         this.platforms = new Map()
         this.callLLM = callLLM
         this.hooks = { inbound: [], outbound: [] }
         for (const [name, adapter] of Object.entries(platforms)) this.register(name, adapter)
+        this.machine = createGatewayMachine({ platformNames: [...this.platforms.keys()] })
+        this.actor = createActor(this.machine, { input: { platformNames: [...this.platforms.keys()] } })
+        // Persist lifecycle transitions so the gateway's state is observable +
+        // resumable; an active snapshot on boot means the gateway was running.
+        this.actor.subscribe((snap) => { persist('gateway', 'lifecycle', this.actor.getPersistedSnapshot()).catch(() => {}) })
+        this.actor.start()
     }
+    get state() { return this.actor.getSnapshot().value }
     register(name, adapter) {
         this.platforms.set(name, adapter)
         adapter.on?.('message', (m) => this.handleInbound(name, m))
     }
     addHook(stage, fn) { this.hooks[stage].push(fn) }
     async start() {
+        this.actor.send({ type: 'START' })
         for (const a of this.platforms.values()) await a.start?.()
+        this.actor.send({ type: 'STARTED' })
         log.info('gateway started', { platforms: [...this.platforms.keys()] })
     }
     async stop() {
+        this.actor.send({ type: 'STOP' })
         for (const a of this.platforms.values()) await a.stop?.()
+        this.actor.send({ type: 'STOPPED' })
         log.info('gateway stopped')
     }
     async handleInbound(platform, msg) {
         log.info('inbound', { platform, from: msg.from, len: (msg.text || '').length })
+        // Persist the in-flight message under a stable key derived from platform +
+        // sender + content so a refresh mid-processing re-drives it instead of
+        // dropping it. The snapshot is cleared once the reply is sent.
+        const msgKey = msg.id || `${platform}:${msg.from}:${randomUUID()}`
+        await persist('gateway-msg', msgKey, { status: 'active', value: 'processing', context: { platform, from: msg.from, text: msg.text } })
         let cur = { ...msg, platform }
         for (const h of this.hooks.inbound) cur = (await h(cur)) || cur
         const result = await runTurn({ prompt: cur.text || '', callLLM: this.callLLM })
@@ -32,6 +70,7 @@ export class Gateway {
         for (const h of this.hooks.outbound) reply = (await h(reply)) || reply
         const adapter = this.platforms.get(platform)
         await adapter.send?.(reply)
+        await clear('gateway-msg', msgKey)
         return reply
     }
 }

package/src/host/host_helpers.js

@@ -134,7 +134,13 @@ export function makeCcLoaders(ccHost, env) {
         }
         return ccHost.plugins().length
     }
+    // gm-cc must never be auto-discovered as a cc-plugin: it ships the 24
+    // deprecated gm-* platform-variant skills under a manifest named 'gm', and the
+    // single canonical gm-skill is registered by plugins/gm-skill instead. The
+    // package extracts into node_modules under both 'gm-cc' and pnpm/bun temp dirs
+    // like '.gm-cc-<hash>', so exclude by basename prefix, not exact match.
     const CC_EXCLUDE = new Set(['gm-cc'])
+    const isExcludedCc = (base) => CC_EXCLUDE.has(base) || /^\.?gm-cc(-|$)/.test(base)
     async function loadCcFromNodeModules(startDir) {
         const seen = new Set(ccHost.plugins().map(p => p.root))
         let cur = path.resolve(startDir)
@@ -146,7 +152,7 @@ export function makeCcLoaders(ccHost, env) {
                     ? fs.readdirSync(path.join(nm, entry.name), { withFileTypes: true }).filter(e => e.isDirectory()).map(e => path.join(nm, entry.name, e.name))
                     : [path.join(nm, entry.name)]
                 for (const d of dirs) {
-                    if (seen.has(d) || !isCcPluginDir(d) || CC_EXCLUDE.has(path.basename(d))) continue
+                    if (seen.has(d) || !isCcPluginDir(d) || isExcludedCc(path.basename(d))) continue
                     seen.add(d); await useCcDir(d)
                 }
             }

package/src/machines/persistent-actor.js

@@ -0,0 +1,57 @@
+// Persistent xstate actor wrapper.
+//
+// createPersistentActor rehydrates an actor from its last persisted snapshot
+// (if any), auto-persists on every transition, and clears its snapshot the
+// moment it reaches a final/stopped state. This is the single primitive every
+// long-lived freddie subsystem uses to become resumable across a process refresh.
+import { createActor } from 'xstate'
+import { persist, load, clear } from './snapshot-store.js'
+import { logger } from '../observability/log.js'
+
+const log = logger('persistent-actor')
+
+// machine: an xstate machine. kind+key: snapshot identity. input: actor input
+// (used only on a fresh start — a rehydrated actor restores its own context).
+// onTransition: optional callback per snapshot.
+export async function createPersistentActor(machine, { kind, key, input, onTransition } = {}) {
+    if (!kind || !key) throw new Error('createPersistentActor requires kind and key')
+    const machineId = machine?.id || machine?.config?.id || null
+    const snapshot = await load(kind, key, { machineId })
+    const resumed = !!snapshot
+    const actor = snapshot
+        ? createActor(machine, { snapshot })
+        : createActor(machine, { input })
+
+    let persisting = Promise.resolve()
+    const sub = actor.subscribe((snap) => {
+        // Serialize persists so rapid consecutive transitions land last-write-wins
+        // without interleaving; the store upsert is keyed by (kind,key).
+        persisting = persisting.then(async () => {
+            try {
+                const ps = actor.getPersistedSnapshot()
+                if (snap.status === 'active') {
+                    await persist(kind, key, ps, { machineId })
+                } else {
+                    // Final/stopped: clear so a completed actor never resurrects on boot.
+                    await clear(kind, key)
+                }
+                onTransition?.(snap)
+            } catch (e) {
+                log.error('persist failed', { kind, key, err: String(e) })
+            }
+        })
+    })
+
+    if (resumed) log.info('actor resumed from snapshot', { kind, key, machineId })
+
+    actor.start()
+    return {
+        actor,
+        resumed,
+        // Await all in-flight persists then unsubscribe — call before stopping so
+        // the final snapshot state is durable.
+        async flush() { await persisting; try { sub.unsubscribe() } catch {} },
+        // Clear this actor's snapshot explicitly (e.g. on external cancel).
+        async forget() { await persisting; try { sub.unsubscribe() } catch {}; await clear(kind, key) },
+    }
+}

package/src/machines/resume.js

@@ -0,0 +1,42 @@
+// Boot-time resumability driver.
+//
+// resumeAll() is invoked on process boot (CLI + dashboard server start). It walks
+// every non-final persisted machine snapshot and rehydrates the ones that can be
+// driven to completion headlessly — interrupted agent turns and unfinished
+// batches. Lifecycle snapshots (gateway/acp) and in-flight message markers are
+// reported but not auto-driven, since they require their live host process (open
+// sockets / stdio) to resume meaningfully; resumeAll() surfaces them so the host
+// can decide.
+import { list, sweepDone } from './snapshot-store.js'
+import { logger } from '../observability/log.js'
+
+const log = logger('resume')
+
+export async function resumeAll({ driveAgents = true, driveBatches = true } = {}) {
+    // Drop any final snapshots first so they never resurrect.
+    await sweepDone()
+    const active = await list({ status: 'active' })
+    const summary = { agent: 0, batch: 0, cron: 0, gateway: 0, acp: 0, 'gateway-msg': 0, 'acp-prompt': 0, resumed: [], surfaced: [] }
+
+    for (const row of active) {
+        summary[row.kind] = (summary[row.kind] || 0) + 1
+        try {
+            if (row.kind === 'agent' && driveAgents) {
+                const { resumeTurn } = await import('../agent/machine.js')
+                resumeTurn({ sessionKey: row.key }).then(() => log.info('agent turn resumed to completion', { key: row.key })).catch(e => log.error('agent resume failed', { key: row.key, err: String(e) }))
+                summary.resumed.push({ kind: 'agent', key: row.key })
+            } else if (row.kind === 'batch' && driveBatches) {
+                const { resumeBatch } = await import('../batch.js')
+                resumeBatch({ batchId: row.key }).then(() => log.info('batch resumed to completion', { key: row.key })).catch(e => log.error('batch resume failed', { key: row.key, err: String(e) }))
+                summary.resumed.push({ kind: 'batch', key: row.key })
+            } else {
+                // Lifecycle + in-flight markers: surfaced for the host to act on.
+                summary.surfaced.push({ kind: row.kind, key: row.key, status: row.status })
+            }
+        } catch (e) {
+            log.error('resume dispatch failed', { kind: row.kind, key: row.key, err: String(e) })
+        }
+    }
+    log.info('resumeAll complete', { active: active.length, resumed: summary.resumed.length, surfaced: summary.surfaced.length })
+    return summary
+}

package/src/machines/snapshot-store.js

@@ -0,0 +1,111 @@
+// Durable xstate snapshot store — the resumability backbone.
+//
+// Every long-lived freddie machine (agent turn, cron scheduler, batch runner,
+// gateway, acp) persists its xstate snapshot here on every transition. After a
+// refresh/restart, resume.js rehydrates each non-final snapshot into a fresh
+// actor via createActor(machine, { snapshot }), so the process picks up exactly
+// where it left off.
+//
+// Storage is libsql (shared sessions.db) keyed by (kind, key). Last-write-wins
+// upsert: rapid consecutive transitions only keep the latest snapshot.
+import { db } from '../db.js'
+import { logger } from '../observability/log.js'
+
+const log = logger('snapshot-store')
+
+// Bump when the persisted-snapshot encoding or any machine definition changes
+// shape incompatibly. load() discards rows whose schema_version mismatches so a
+// stale snapshot from older code never crashes resume.
+export const SNAPSHOT_SCHEMA_VERSION = 1
+
+let _inited = false
+async function init() {
+    const d = await db()
+    if (!_inited) {
+        await d.exec(`CREATE TABLE IF NOT EXISTS machine_snapshots (
+            kind TEXT NOT NULL,
+            key TEXT NOT NULL,
+            schema_version INTEGER NOT NULL,
+            machine_id TEXT,
+            snapshot_json TEXT NOT NULL,
+            status TEXT NOT NULL,
+            updated INTEGER NOT NULL,
+            PRIMARY KEY (kind, key)
+        )`)
+        _inited = true
+    }
+    return d
+}
+
+// Persist (upsert) a snapshot. status is the actor snapshot status
+// ('active' | 'done' | 'error' | 'stopped'). machineId guards against rehydrating
+// a snapshot into a structurally different machine after a code change.
+export async function persist(kind, key, snapshot, { machineId = null } = {}) {
+    if (!kind || !key) throw new Error('persist requires kind and key')
+    const d = await init()
+    const status = snapshot?.status || 'active'
+    const json = JSON.stringify(snapshot)
+    await d.prepare(`INSERT INTO machine_snapshots (kind, key, schema_version, machine_id, snapshot_json, status, updated)
+        VALUES (?, ?, ?, ?, ?, ?, ?)
+        ON CONFLICT(kind, key) DO UPDATE SET
+            schema_version = excluded.schema_version,
+            machine_id = excluded.machine_id,
+            snapshot_json = excluded.snapshot_json,
+            status = excluded.status,
+            updated = excluded.updated`)
+        .run(kind, key, SNAPSHOT_SCHEMA_VERSION, machineId, json, status, Date.now())
+    return { kind, key, status }
+}
+
+// Load a persisted snapshot. Returns null on missing row, schema-version
+// mismatch, machine-id mismatch, or unparseable JSON — every consumer falls back
+// to a fresh actor and never throws.
+export async function load(kind, key, { machineId = null } = {}) {
+    const d = await init()
+    const row = await d.prepare(`SELECT * FROM machine_snapshots WHERE kind = ? AND key = ?`).get(kind, key)
+    if (!row) return null
+    if (Number(row.schema_version) !== SNAPSHOT_SCHEMA_VERSION) {
+        log.info('discarding stale snapshot (schema mismatch)', { kind, key, had: row.schema_version, want: SNAPSHOT_SCHEMA_VERSION })
+        await clear(kind, key)
+        return null
+    }
+    if (machineId && row.machine_id && row.machine_id !== machineId) {
+        log.info('discarding stale snapshot (machine id mismatch)', { kind, key, had: row.machine_id, want: machineId })
+        await clear(kind, key)
+        return null
+    }
+    try {
+        return JSON.parse(row.snapshot_json)
+    } catch (e) {
+        log.error('unparseable snapshot, discarding', { kind, key, err: String(e) })
+        await clear(kind, key)
+        return null
+    }
+}
+
+export async function clear(kind, key) {
+    const d = await init()
+    await d.prepare(`DELETE FROM machine_snapshots WHERE kind = ? AND key = ?`).run(kind, key)
+}
+
+// List snapshots, optionally filtered by kind. status filter defaults to
+// non-final ('active') for resume-on-boot; pass status:null for all.
+export async function list({ kind = null, status = 'active' } = {}) {
+    const d = await init()
+    let sql = `SELECT kind, key, schema_version, machine_id, status, updated FROM machine_snapshots`
+    const where = []; const args = []
+    if (kind) { where.push('kind = ?'); args.push(kind) }
+    if (status) { where.push('status = ?'); args.push(status) }
+    if (where.length) sql += ' WHERE ' + where.join(' AND ')
+    sql += ' ORDER BY updated DESC'
+    return await d.prepare(sql).all(...args)
+}
+
+// Remove all final (done/error/stopped) snapshots — a completed actor must not
+// resurrect on the next boot. Called opportunistically; final actors also clear
+// their own row on completion.
+export async function sweepDone() {
+    const d = await init()
+    const res = await d.prepare(`DELETE FROM machine_snapshots WHERE status != 'active'`).run()
+    return { removed: res.changes }
+}

package/src/web/server.js

@@ -7,6 +7,9 @@ const __dirname = path.dirname(fileURLToPath(import.meta.url))
 
 export async function createDashboard({ port = 0 } = {}) {
     const host = await bootHost()
+    // Rehydrate any interrupted machines (agent turns, batches) from their
+    // persisted snapshots; surface lifecycle markers. Non-blocking on failure.
+    try { const { resumeAll } = await import('../machines/resume.js'); await resumeAll() } catch (_) {}
     const app = express()
     app.use(express.json())
     app.use(express.static(__dirname))