@aexol/spectral 0.2.0 → 0.2.2

package/dist/commands/login.js

@@ -61,7 +61,7 @@ export async function performLogin(opts) {
 }
 export async function runLogin() {
     process.stdout.write(pc.bold("Spectral login\n"));
-    process.stdout.write(pc.dim("Authenticate against the Aexol MCP backend. Credentials are stored at ~/.spectral/config.json (chmod 600).\n\n"));
+    process.stdout.write(pc.dim(`Authenticate against the Aexol MCP backend. Credentials are stored at ${getConfigFile()} (chmod 600).\n\n`));
     const defaultUrl = process.env.SPECTRAL_MCP_URL ?? DEFAULT_API_URL;
     let apiUrl;
     let teamApiKey;

package/dist/commands/serve.js

@@ -192,7 +192,9 @@ export async function runServe(opts = {}) {
     const relay = new RelayClient({
         relayUrl,
         machineJwt: registration.record.machineJwt,
+        backendUrl,
         webSocketImpl: opts.webSocketImpl,
+        fetchImpl: opts.fetchImpl,
         logger: silent ? { log: () => { }, warn: () => { }, error: () => { } } : console,
     });
     // Wire the meta publisher now that we have both the relay socket and

package/dist/extensions/aexol-mcp.js

@@ -15,7 +15,7 @@
  * backend is unreachable we log a warning and return, leaving pi to start
  * without Aexol tools rather than crashing the whole agent.
  */
-import { getApiUrl, readConfig } from "../config.js";
+import { getApiUrl, getConfigFile, readConfig } from "../config.js";
 import { AexolMcpClient, AexolMcpError } from "../mcp-client.js";
 /**
  * Render a backend tool result into a single string for pi.
@@ -58,7 +58,7 @@ export default async function aexolMcpExtension(pi) {
     const cfg = await readConfig();
     if (!cfg) {
         // Pre-flight in cli.ts should have caught this. Logging is enough.
-        process.stderr.write("[aexol-mcp] No ~/.spectral/config.json found; Aexol tools disabled. Run `spectral login`.\n");
+        process.stderr.write(`[aexol-mcp] No config found at ${getConfigFile()}; Aexol tools disabled. Run \`spectral login\`.\n`);
         return;
     }
     const apiUrl = getApiUrl(cfg.apiUrl);

package/dist/relay/client.js

@@ -2,26 +2,30 @@
  * RelayClient — long-lived WebSocket connection to the Aexol backend's
  * `/agent-connection` endpoint.
  *
- * Responsibilities (Batch 2):
+ * Responsibilities:
  *  - Open and maintain a single WS to the relay, authenticated with the
  *    machine JWT via `Authorization: Bearer <jwt>`.
  *  - Reply `{kind:"pong"}` to backend `{kind:"ping"}`. Backend closes
  *    `4408 heartbeat-timeout` if it doesn't hear from us within 90s; we
  *    rely on the backend pings rather than emitting our own (single source
  *    of liveness, no jitter on our side).
+ *  - **Watchdog timer:** tracks `lastActivityMs` on every received frame /
+ *    ping. Every 15 s, if no activity within `WATCHDOG_MS` (120 s = 2×
+ *    backend timeout), force-closes the socket (4001 "watchdog-timeout")
+ *    and triggers a reconnect. Detects silent backend death (Docker OOM
+ *    kill, network partition without TCP RST) where the socket stays open
+ *    but no data flows.
+ *  - **Pre-reconnect health check:** before opening a new WS, does a quick
+ *    HTTP GET to `backendUrl/health` with a 5 s timeout. If the backend is
+ *    unhealthy or unreachable, skips the WS attempt and re-schedules. This
+ *    avoids a slow TCP connect timeout (up to 75 s on some platforms) when
+ *    the backend is down.
  *  - On unexpected close, reconnect forever with exponential backoff +
  *    ±20% jitter, capped at 30s. There is no "give up" state — if the
  *    machine is offline for hours, we just keep trying. Operators can
  *    `Ctrl-C` to stop.
  *  - Buffer outbound frames in a small queue while the socket is closed.
- *    Capped at 100 frames; oldest is dropped on overflow. Until Batch 3
- *    introduces relay envelopes there's nothing meaningful to send anyway,
- *    so this is mostly future-proofing.
- *
- * Out of scope for Batch 2 (Batch 3 work):
- *  - Envelope routing (`rest_request` / `subscribe` / `ws_event`). The
- *    client emits `frame` for every non-pong frame; the dispatcher in
- *    `serve.ts` (currently just an ack/echo) will own translation.
+ *    Capped at 100 frames; oldest is dropped on overflow.
  *
  * Events (typed via `RelayClientEvents`):
  *  - `open`            - connected and welcomed
@@ -42,10 +46,24 @@ const SEND_QUEUE_CAP = 100;
 const RECONNECT_SCHEDULE = [1000, 2000, 5000, 15000, 30000];
 /** ±20% jitter on each scheduled delay. */
 const JITTER_RATIO = 0.2;
+/**
+ * Watchdog interval (ms). Every `WATCHDOG_INTERVAL_MS` we check whether
+ * the socket has been silent longer than `WATCHDOG_SILENCE_MS`.
+ */
+const WATCHDOG_INTERVAL_MS = 15_000;
+/**
+ * Max silence before triggering watchdog reconnect (ms). 2× the backend's
+ * 90 s heartbeat timeout = 120 s.
+ */
+const WATCHDOG_SILENCE_MS = 120_000;
+/** HTTP timeout for the pre-reconnect health check. */
+const HEALTH_CHECK_TIMEOUT_MS = 5_000;
 export class RelayClient extends EventEmitter {
     relayUrl;
     machineJwt;
+    backendUrl;
     WS;
+    fetchImpl;
     logger;
     exit;
     ws = null;
@@ -53,11 +71,16 @@ export class RelayClient extends EventEmitter {
     reconnectAttempt = 0;
     reconnectTimer = null;
     sendQueue = [];
+    /** Timestamp of last received frame / ping — drives the watchdog. */
+    lastActivityMs = 0;
+    watchdogTimer = null;
     constructor(opts) {
         super();
         this.relayUrl = opts.relayUrl;
         this.machineJwt = opts.machineJwt;
+        this.backendUrl = opts.backendUrl;
         this.WS = opts.webSocketImpl ?? WebSocket;
+        this.fetchImpl = opts.fetchImpl ?? fetch;
         this.logger = opts.logger ?? console;
         this.exit = opts.exit ?? ((code) => process.exit(code));
     }
@@ -111,6 +134,10 @@ export class RelayClient extends EventEmitter {
             clearTimeout(this.reconnectTimer);
             this.reconnectTimer = null;
         }
+        if (this.watchdogTimer) {
+            clearInterval(this.watchdogTimer);
+            this.watchdogTimer = null;
+        }
         const ws = this.ws;
         this.ws = null;
         if (ws) {
@@ -131,7 +158,13 @@ export class RelayClient extends EventEmitter {
             headers: { Authorization: `Bearer ${this.machineJwt}` },
         });
         this.ws = ws;
+        // Seed the watchdog timer so a hanging connect handshake also triggers
+        // a timeout (no on("open") to bump activity). If the handshake succeeds
+        // quickly, `on("open")` resets this.
+        this.lastActivityMs = Date.now();
+        this.startWatchdog();
         ws.on("open", () => {
+            this.lastActivityMs = Date.now();
             this.reconnectAttempt = 0;
             // Flush any queued frames.
             const queued = this.sendQueue;
@@ -150,6 +183,7 @@ export class RelayClient extends EventEmitter {
             this.emit("open");
         });
         ws.on("message", (data) => {
+            this.lastActivityMs = Date.now();
             let parsed;
             try {
                 parsed = JSON.parse(data.toString());
@@ -182,6 +216,7 @@ export class RelayClient extends EventEmitter {
         });
         ws.on("close", (code, reason) => {
             this.ws = null;
+            this.stopWatchdog();
             const reasonStr = reason?.toString() ?? "";
             this.emit("close", { code, reason: reasonStr });
             if (this.disposed)
@@ -202,11 +237,93 @@ export class RelayClient extends EventEmitter {
             this.scheduleReconnect();
         });
     }
-    scheduleReconnect() {
+    // --- watchdog -------------------------------------------------------------
+    startWatchdog() {
+        if (this.watchdogTimer)
+            return;
+        this.watchdogTimer = setInterval(() => {
+            if (this.disposed)
+                return;
+            const elapsed = Date.now() - this.lastActivityMs;
+            if (elapsed > WATCHDOG_SILENCE_MS) {
+                this.logger.warn(`Watchdog: no relay activity for ${Math.round(elapsed / 1000)}s, forcing reconnect`);
+                const ws = this.ws;
+                this.ws = null;
+                if (ws) {
+                    try {
+                        ws.close(4001, "watchdog-timeout");
+                    }
+                    catch {
+                        // ignore
+                    }
+                }
+            }
+        }, WATCHDOG_INTERVAL_MS);
+    }
+    stopWatchdog() {
+        if (this.watchdogTimer) {
+            clearInterval(this.watchdogTimer);
+            this.watchdogTimer = null;
+        }
+    }
+    /**
+     * Pre-reconnect health check: quick HTTP GET to `<backendUrl>/health`.
+     * Returns true when the backend is reachable (or when no backendUrl is
+     * configured, which skips the check entirely). Returns false when the
+     * backend is unhealthy/down — the caller should re-schedule.
+     */
+    async healthCheck() {
+        if (!this.backendUrl)
+            return true; // no backend → no health check
+        const url = `${this.backendUrl.replace(/\/$/, "")}/health`;
+        try {
+            const ctrl = new AbortController();
+            const timeout = setTimeout(() => ctrl.abort(), HEALTH_CHECK_TIMEOUT_MS);
+            const res = await this.fetchImpl(url, {
+                method: "GET",
+                signal: ctrl.signal,
+            });
+            clearTimeout(timeout);
+            if (!res.ok) {
+                this.logger.warn(`Health check: ${url} returned ${res.status}, will retry`);
+                return false;
+            }
+            // Backend is reachable — proceed to WS.
+            return true;
+        }
+        catch (err) {
+            // AbortError (timeout), fetch error (connection refused, DNS, etc.)
+            // all mean the backend is not reachable. Log compactly and retry.
+            const msg = err?.name === "AbortError"
+                ? "timeout"
+                : (err instanceof Error ? err.message : String(err));
+            this.logger.warn(`Health check: ${url} unreachable (${msg}), will retry`);
+            return false;
+        }
+    }
+    async scheduleReconnect() {
         if (this.disposed)
             return;
         if (this.reconnectTimer)
             return;
+        // Pre-reconnect health check — avoids wasting time on a slow TCP
+        // connect when the backend is down. The health endpoint is a cheap
+        // HTTP GET; if even that fails, skip the WS attempt entirely.
+        const healthy = await this.healthCheck();
+        if (!healthy) {
+            // Backend unreachable — use a fixed 5 s retry instead of advancing
+            // the backoff schedule (this is an environment problem, not a WS
+            // handshake problem).
+            const idx = Math.min(this.reconnectAttempt, RECONNECT_SCHEDULE.length - 1);
+            const delay = RECONNECT_SCHEDULE[idx];
+            this.reconnectAttempt++;
+            this.emit("reconnect-scheduled", { delayMs: delay, attempt: this.reconnectAttempt });
+            this.reconnectTimer = setTimeout(() => {
+                this.reconnectTimer = null;
+                void this.scheduleReconnect().catch(() => { });
+            }, delay);
+            return;
+        }
         const idx = Math.min(this.reconnectAttempt, RECONNECT_SCHEDULE.length - 1);
         const base = RECONNECT_SCHEDULE[idx];
         const jitter = base * JITTER_RATIO * (Math.random() * 2 - 1);
@@ -233,7 +350,7 @@ export class RelayClient extends EventEmitter {
                 // URL, etc.) must not kill the daemon — log it and re-schedule
                 // so the backoff continues forever.
                 this.emit("error", err);
-                this.scheduleReconnect();
+                void this.scheduleReconnect().catch(() => { });
             }
         }, delay);
     }

package/dist/server/pi-bridge.js

@@ -125,6 +125,60 @@ function resolveMcpAdapterEntry() {
     }
     return null;
 }
+/**
+ * Token pricing per model (USD per 1M tokens). Matches provider list
+ * prices as of May 2026. Used to compute token cost server-side when
+ * pi's own cost field is unavailable (synthetic proxy models are
+ * registered with zero cost to avoid pi-side billing).
+ *
+ * Keys are matched as prefix substrings against modelId, so
+ * `"claude-sonnet-4"` covers both `claude-sonnet-4-20250514` and any
+ * future point-release.
+ */
+const MODEL_PRICING = [
+    // Anthropic Claude models
+    { prefix: "claude-opus-4", input: 15, output: 75, cacheWrite: 18.75, cacheRead: 1.50 },
+    { prefix: "claude-sonnet-4", input: 3, output: 15, cacheWrite: 3.75, cacheRead: 0.30 },
+    { prefix: "claude-3-5-sonnet", input: 3, output: 15, cacheWrite: 3.75, cacheRead: 0.30 },
+    { prefix: "claude-3-5-haiku", input: 0.80, output: 4, cacheWrite: 1, cacheRead: 0.08 },
+    { prefix: "claude-3-opus", input: 15, output: 75, cacheWrite: 18.75, cacheRead: 1.50 },
+    { prefix: "claude-3-sonnet", input: 3, output: 15, cacheWrite: 3.75, cacheRead: 0.30 },
+    { prefix: "claude-3-haiku", input: 0.25, output: 1.25, cacheWrite: 1.25, cacheRead: 0.025 },
+    // OpenAI models
+    { prefix: "gpt-4.1", input: 2, output: 8, cacheWrite: 8, cacheRead: 0.50 },
+    { prefix: "gpt-4o", input: 2.50, output: 10, cacheWrite: 10, cacheRead: 1.25 },
+    { prefix: "gpt-4-turbo", input: 10, output: 30, cacheWrite: 0, cacheRead: 0 },
+    { prefix: "gpt-4", input: 30, output: 60, cacheWrite: 0, cacheRead: 0 },
+    { prefix: "gpt-3.5-turbo", input: 0.50, output: 1.50, cacheWrite: 0, cacheRead: 0 },
+    { prefix: "o1", input: 15, output: 60, cacheWrite: 0, cacheRead: 0 },
+    { prefix: "o3-mini", input: 1.10, output: 4.40, cacheWrite: 0, cacheRead: 0 },
+    { prefix: "o4-mini", input: 1.10, output: 4.40, cacheWrite: 0, cacheRead: 0 },
+    // Google Gemini models
+    { prefix: "gemini-2.5-pro", input: 1.25, output: 10, cacheWrite: 0, cacheRead: 0 },
+    { prefix: "gemini-2.5-flash", input: 0.15, output: 0.60, cacheWrite: 0, cacheRead: 0 },
+    // DeepSeek models
+    { prefix: "deepseek-v3", input: 0.27, output: 1.10, cacheWrite: 0, cacheRead: 0 },
+    { prefix: "deepseek-r1", input: 0.55, output: 2.19, cacheWrite: 0, cacheRead: 0 },
+    { prefix: "deepseek/deepseek-v3", input: 0.27, output: 1.10, cacheWrite: 0, cacheRead: 0 },
+    { prefix: "deepseek/deepseek-r1", input: 0.55, output: 2.19, cacheWrite: 0, cacheRead: 0 },
+    // Meta Llama models (common via OpenRouter-compatible endpoints)
+    { prefix: "meta-llama/llama-4", input: 0.20, output: 0.80, cacheWrite: 0, cacheRead: 0 },
+    { prefix: "meta-llama/llama-3.3", input: 0.20, output: 0.50, cacheWrite: 0, cacheRead: 0 },
+];
+/** Look up pricing for a modelId. Returns null when unknown. */
+function lookupPricing(modelId) {
+    for (const entry of MODEL_PRICING) {
+        if (modelId.startsWith(entry.prefix)) {
+            return {
+                input: entry.input,
+                output: entry.output,
+                cacheWrite: entry.cacheWrite,
+                cacheRead: entry.cacheRead,
+            };
+        }
+    }
+    return null;
+}
 export class PiBridge {
     session;
     unsubscribe;
@@ -316,26 +370,30 @@ export class PiBridge {
                 apiKey: this.opts.machineJwt,
                 authHeader: true,
                 api: "anthropic-messages",
-                models: anthropicModels.map((m) => ({
-                    id: m.modelId,
-                    name: m.displayName,
-                    api: "anthropic-messages",
-                    // Pin provider/baseUrl explicitly so pi's ModelRegistry doesn't
-                    // auto-derive `provider` from a slash-prefixed id (e.g. treating
-                    // `deepseek/deepseek-v4-pro` as provider `"deepseek"`), which would
-                    // make `hasConfiguredAuth(model)` look up the wrong provider key
-                    // and surface "No API key for deepseek/...". Both must point back
-                    // at our synthetic proxy provider so auth resolves to the machine JWT.
-                    provider: SPECTRAL_PROXY_ANTHROPIC,
-                    baseUrl,
-                    reasoning: false,
-                    input: ["text", "image"],
-                    // The cost block is required by pi's typing but unused for routing;
-                    // the backend enforces real billing/limits server-side, not pi.
-                    cost: { input: 0, output: 0, cacheRead: 0, cacheWrite: 0 },
-                    contextWindow: 0,
-                    maxTokens: 0,
-                })),
+                models: anthropicModels.map((m) => {
+                    const pricing = lookupPricing(m.modelId);
+                    return {
+                        id: m.modelId,
+                        name: m.displayName,
+                        api: "anthropic-messages",
+                        // Pin provider/baseUrl explicitly so pi's ModelRegistry doesn't
+                        // auto-derive `provider` from a slash-prefixed id (e.g. treating
+                        // `deepseek/deepseek-v4-pro` as provider `"deepseek"`), which would
+                        // make `hasConfiguredAuth(model)` look up the wrong provider key
+                        // and surface "No API key for deepseek/...". Both must point back
+                        // at our synthetic proxy provider so auth resolves to the machine JWT.
+                        provider: SPECTRAL_PROXY_ANTHROPIC,
+                        baseUrl,
+                        reasoning: false,
+                        input: ["text", "image"],
+                        // Real pricing so pi can compute accurate token costs.
+                        cost: pricing
+                            ? { input: pricing.input, output: pricing.output, cacheRead: pricing.cacheRead, cacheWrite: pricing.cacheWrite }
+                            : { input: 0, output: 0, cacheRead: 0, cacheWrite: 0 },
+                        contextWindow: 0,
+                        maxTokens: 0,
+                    };
+                }),
             });
         }
         if (openaiCompatModels.length > 0) {
@@ -344,22 +402,28 @@ export class PiBridge {
                 apiKey: this.opts.machineJwt,
                 authHeader: true,
                 api: "openai-completions",
-                models: openaiCompatModels.map((m) => ({
-                    id: m.modelId,
-                    name: m.displayName,
-                    api: "openai-completions",
-                    // See anthropic batch above for rationale — without these, pi
-                    // auto-derives `provider` from slash-prefixed ids like
-                    // `deepseek/deepseek-v4-pro` or `meta-llama/llama-3.3-70b-instruct`,
-                    // breaking auth lookup against our synthetic proxy provider.
-                    provider: SPECTRAL_PROXY_OPENAI,
-                    baseUrl,
-                    reasoning: false,
-                    input: ["text", "image"],
-                    cost: { input: 0, output: 0, cacheRead: 0, cacheWrite: 0 },
-                    contextWindow: 0,
-                    maxTokens: 0,
-                })),
+                models: openaiCompatModels.map((m) => {
+                    const pricing = lookupPricing(m.modelId);
+                    return {
+                        id: m.modelId,
+                        name: m.displayName,
+                        api: "openai-completions",
+                        // See anthropic batch above for rationale — without these, pi
+                        // auto-derives `provider` from slash-prefixed ids like
+                        // `deepseek/deepseek-v4-pro` or `meta-llama/llama-3.3-70b-instruct`,
+                        // breaking auth lookup against our synthetic proxy provider.
+                        provider: SPECTRAL_PROXY_OPENAI,
+                        baseUrl,
+                        reasoning: false,
+                        input: ["text", "image"],
+                        // Real pricing so pi can compute accurate token costs.
+                        cost: pricing
+                            ? { input: pricing.input, output: pricing.output, cacheRead: pricing.cacheRead, cacheWrite: pricing.cacheWrite }
+                            : { input: 0, output: 0, cacheRead: 0, cacheWrite: 0 },
+                        contextWindow: 0,
+                        maxTokens: 0,
+                    };
+                }),
             });
         }
         // Built-in UserModel entries — custom models registered by the team.
@@ -373,18 +437,23 @@ export class PiBridge {
                 apiKey: this.opts.machineJwt,
                 authHeader: true,
                 api: "openai-completions",
-                models: userModelEntries.map((m) => ({
-                    id: m.modelId,
-                    name: m.displayName,
-                    api: "openai-completions",
-                    provider: SPECTRAL_PROXY_USER_MODEL,
-                    baseUrl,
-                    reasoning: false,
-                    input: ["text", "image"],
-                    cost: { input: 0, output: 0, cacheRead: 0, cacheWrite: 0 },
-                    contextWindow: 0,
-                    maxTokens: 0,
-                })),
+                models: userModelEntries.map((m) => {
+                    const pricing = lookupPricing(m.modelId);
+                    return {
+                        id: m.modelId,
+                        name: m.displayName,
+                        api: "openai-completions",
+                        provider: SPECTRAL_PROXY_USER_MODEL,
+                        baseUrl,
+                        reasoning: false,
+                        input: ["text", "image"],
+                        cost: pricing
+                            ? { input: pricing.input, output: pricing.output, cacheRead: pricing.cacheRead, cacheWrite: pricing.cacheWrite }
+                            : { input: 0, output: 0, cacheRead: 0, cacheWrite: 0 },
+                        contextWindow: 0,
+                        maxTokens: 0,
+                    };
+                }),
             });
         }
     }
@@ -651,6 +720,26 @@ export class PiBridge {
                 const endEvent = { type: "message_end", messageId };
                 this.pending.wireEvents.push(endEvent);
                 this.opts.emit(endEvent);
+                // Emit token usage for this assistant message. pi provides token
+                // counts via ev.message.usage; cost is computed from the model's
+                // configured pricing (or null when unavailable).
+                const usage = ev.message.usage;
+                if (usage) {
+                    const usageEvent = {
+                        type: "token_usage",
+                        messageId,
+                        usage: {
+                            inputTokens: usage.input ?? 0,
+                            outputTokens: usage.output ?? 0,
+                            cacheReadTokens: usage.cacheRead ?? 0,
+                            cacheWriteTokens: usage.cacheWrite ?? 0,
+                            totalTokens: usage.totalTokens ?? 0,
+                            cost: usage.cost?.total ?? null,
+                        },
+                    };
+                    this.pending.wireEvents.push(usageEvent);
+                    this.opts.emit(usageEvent);
+                }
                 // Defer persistence: keep `this.pending` alive so tool events that
                 // arrive after `message_end` (pi fires tool_execution_* events
                 // BETWEEN messages) are buffered into `pending.wireEvents`. We store

package/dist/server/session-stream.js

@@ -42,6 +42,12 @@ import { generateSessionTitle, isDefaultTitle, } from "./title-generator.js";
 const DEFAULT_BRIDGE_FACTORY = (args) => new PiBridge(args);
 /** Safety limit for autonomous loop iterations per session. */
 const MAX_LOOP_ITERATIONS = 100;
+/**
+ * Number of accumulated wire events before flushing the in-flight turn
+ * to SQLite. Batch-persisting means a server crash mid-turn only loses
+ * at most the last `BATCH_FLUSH_INTERVAL` events, not the entire turn.
+ */
+const BATCH_FLUSH_INTERVAL = 10;
 /** Marker the agent emits in its response to signal the task is complete. */
 const LOOP_DONE_MARKER = "<LOOP_DONE>";
 export class SessionStreamManager {
@@ -361,6 +367,10 @@ export class SessionStreamManager {
         // instead of hanging. Also prevents the next prompt() from waiting on
         // a dead bridge's ready promise.
         stream.startError = new Error("Turn cancelled");
+        // Clear batch-persist tracking so the next turn doesn't accidentally
+        // flush events against a stale messageId.
+        stream.currentMessageId = null;
+        stream.lastFlushedEventCount = 0;
         // Broadcast agent_end so all subscribers close their open turn and
         // re-enable their composers.
         if (stream.currentTurn) {
@@ -385,6 +395,9 @@ export class SessionStreamManager {
         if (!stream)
             return;
         stream.loopActive = false;
+        // Flush the last batch of in-flight events before tearing down, so a
+        // shutdown / GC doesn't lose events that haven't hit the interval yet.
+        this.flushInFlightTurn(stream);
         try {
             stream.bridge.dispose();
         }
@@ -460,6 +473,8 @@ export class SessionStreamManager {
             startError: null,
             subscribers: new Set(),
             currentTurn: null,
+            currentMessageId: null,
+            lastFlushedEventCount: 0,
             loopActive: false,
             loopIterationCount: 0,
             loopOriginalPrompt: null,
@@ -523,6 +538,33 @@ export class SessionStreamManager {
             if (event.type === "text_delta") {
                 stream.currentTurn.assistantText += event.delta;
             }
+            // Track message lifecycle for batch persistence.
+            if (event.type === "message_start") {
+                stream.currentMessageId = event.messageId;
+                stream.lastFlushedEventCount = 0;
+                // Stub-insert so the server can recover this message on restart even
+                // if it crashes before the first batch flush. `INSERT OR REPLACE`
+                // ensures the final `onAssistantMessageComplete` write wins.
+                try {
+                    this.store.appendMessage(stream.sessionId, {
+                        id: event.messageId,
+                        role: "assistant",
+                        content: "",
+                        eventsJsonl: "",
+                        createdAt: Date.now(),
+                    });
+                }
+                catch (err) {
+                    console.error(`[spectral] error: batch-persist stub insert failed: ${err instanceof Error ? err.message : String(err)}`);
+                }
+            }
+            // Batch-persist: flush accumulated events to SQLite every N events so a
+            // server crash mid-turn only loses the last batch, not the entire turn.
+            if (stream.currentMessageId &&
+                stream.currentTurn &&
+                stream.currentTurn.events.length - stream.lastFlushedEventCount >= BATCH_FLUSH_INTERVAL) {
+                this.flushInFlightTurn(stream);
+            }
         }
         // Broadcast first, then maybe close out the turn. agent_end clears the
         // buffer because by that point the assistant message is already in
@@ -530,6 +572,12 @@ export class SessionStreamManager {
         // which fires before agent_end).
         this.broadcast(stream, event);
         if (event.type === "agent_end") {
+            // Final flush + clear batch-persist tracking. `onAssistantMessageComplete`
+            // has already written the authoritative final row to SQLite (it fires on
+            // `message_end`, which precedes `agent_end`), so the staged row is already
+            // replaced with complete data. We just zero out the in-memory trackers.
+            stream.currentMessageId = null;
+            stream.lastFlushedEventCount = 0;
             const finishedTurn = stream.currentTurn;
             stream.currentTurn = null;
             // Fire-and-forget auto-title generation. Runs only once per session
@@ -584,10 +632,48 @@ export class SessionStreamManager {
             // An error event arriving outside a turn (or bubbling out of one) —
             // discard partial buffer to avoid replaying half a turn that the
             // client has already shown an error for. The error event itself is
-            // still broadcast above.
+            // still broadcast above. Also clear batch-persist tracking so the
+            // next `message_start` starts a fresh sequence.
+            stream.currentMessageId = null;
+            stream.lastFlushedEventCount = 0;
             stream.currentTurn = null;
         }
     }
+    /**
+     * Flush the current in-flight turn's events to SQLite for crash recovery.
+     * Only the events accumulated since the last flush are written — we append
+     * them to the already-stored JSONL via INSERT OR REPLACE. Called every
+     * `BATCH_FLUSH_INTERVAL` events from `handleBridgeEvent`.
+     *
+     * Errors are caught, logged, and swallowed: batch persistence is a
+     * best-effort hardening, never a failure path that should block the stream.
+     */
+    flushInFlightTurn(stream) {
+        const turn = stream.currentTurn;
+        const messageId = stream.currentMessageId;
+        if (!turn || !messageId)
+            return;
+        const newEvents = turn.events.slice(stream.lastFlushedEventCount);
+        if (newEvents.length === 0)
+            return;
+        try {
+            // Build JSONL from all events (already-flushed + new) so the row is
+            // always a complete, self-consistent snapshot. Older batches are
+            // included so history rehydration doesn't need to stitch fragments.
+            const eventsJsonl = turn.events.map((e) => JSON.stringify(e)).join("\n");
+            this.store.appendMessage(stream.sessionId, {
+                id: messageId,
+                role: "assistant",
+                content: turn.assistantText,
+                eventsJsonl,
+                createdAt: turn.startedAt,
+            });
+            stream.lastFlushedEventCount = turn.events.length;
+        }
+        catch (err) {
+            console.error(`[spectral] error: batch-persist flush failed: ${err instanceof Error ? err.message : String(err)}`);
+        }
+    }
     /**
      * Auto-title the session if it's still wearing the default title and we
      * haven't already attempted generation in this process. Fire-and-forget
@@ -706,6 +792,7 @@ function isReplayable(event) {
         event.type === "tool_call" ||
         event.type === "tool_result" ||
         event.type === "message_end" ||
+        event.type === "token_usage" ||
         event.type === "error");
 }
 function snapshotTurn(turn) {

package/dist/server/storage.js

@@ -29,6 +29,7 @@ import Database from "better-sqlite3";
 import { randomUUID } from "node:crypto";
 import { mkdirSync, readFileSync } from "node:fs";
 import { dirname, join } from "node:path";
+import { getConfigDir } from "../config.js";
 import { stripJsoncComments } from "../studio-binding.js";
 /**
  * Schema version. Bump + the on-open migration drops & recreates every table.
@@ -262,7 +263,7 @@ export class SessionStore {
         this.stmtDeleteSession = this.db.prepare(`DELETE FROM sessions WHERE id = ?`);
         this.stmtListMessages = this.db.prepare(`SELECT id, session_id, role, content, events_jsonl, images_json, created_at
        FROM messages WHERE session_id = ? ORDER BY created_at ASC, id ASC`);
-        this.stmtAppendMessage = this.db.prepare(`INSERT INTO messages (id, session_id, role, content, events_jsonl, images_json, created_at)
+        this.stmtAppendMessage = this.db.prepare(`INSERT OR REPLACE INTO messages (id, session_id, role, content, events_jsonl, images_json, created_at)
        VALUES (?, ?, ?, ?, ?, ?, ?)`);
         this.stmtTouchSession = this.db.prepare(`UPDATE sessions SET updated_at = ? WHERE id = ?`);
         this.stmtRenameSession = this.db.prepare(`UPDATE sessions SET title = ?, updated_at = ? WHERE id = ?`);
@@ -527,7 +528,7 @@ export function preflightSqlite(dbPath) {
             ok: false,
             error: `Failed to load native sqlite module (${msg}).\n` +
                 `  This usually means the native binary couldn't be built for your Node.js version.\n` +
-                `  Try: cd ~/.spectral && npm rebuild better-sqlite3\n` +
+                `  Try: cd ${getConfigDir()} && npm rebuild better-sqlite3\n` +
                 `  Or reinstall: npm install -g @aexol/spectral`,
         };
     }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@aexol/spectral",
-  "version": "0.2.0",
+  "version": "0.2.2",
   "description": "Always-on coding agent for Aexol — branded pi wrapper with relay-based browser access.",
   "type": "module",
   "private": false,