specrails-desktop 2.0.0

package/docs/tracking-cost.md

@@ -0,0 +1,155 @@
+# Tracking cost
+
+specrails-desktop records every AI CLI invocation it spawns — both Claude and Codex — and surfaces the totals on one Analytics page per project. This guide walks through what's tracked, what's not, and how to read the dashboard.
+
+## What gets tracked
+
+Six surfaces, all per-project:
+
+| Surface | What it captures |
+|---------|------------------|
+| **`job`** | Every rail run (the Architect → Developer → Reviewer → Ship pipeline, plus Ultracode and Batch runs) |
+| **`quick-spec`** | One-shot Quick spec generation (including a Quick-mode Contract Refine run) |
+| **`explore-spec`** | Every Explore conversation turn (including the Explore Contract Refine run) |
+| **`ai-edit`** | The **AI Edit / Refine** overlay (refining an agent or a ticket) |
+| **`smash`** | SMASH runs that break an epic spec into sub-specs |
+| **`file-summary`** | Code-explorer AI summaries of individual files |
+
+Each invocation row carries: provider (Claude or Codex), model, status, started/finished timestamps, duration (wall clock + API-only), tokens (in / out / cache read / cache create), total USD cost, turn count, and — when applicable — the ticket and conversation IDs it touched.
+
+> Cost averages exclude `failed`/`aborted` rows, but those rows still count toward the total run count and the failure rate.
+
+## Claude vs Codex cost
+
+Claude cost is **provider-billed and authoritative** — the figure comes straight from the CLI.
+
+Codex has no native cost field, so the app **estimates** its cost from a local rate-card (`server/pricing.ts`). Estimated rows are flagged: they render with a `~` tilde in the raw table and feed an "includes ~$X estimated" footnote in the Hero. On multi-provider projects, a **Provider breakdown** card splits spend by engine so you can see authoritative vs estimated at a glance.
+
+## What's NOT tracked (intentionally)
+
+- **Sidebar chat** — the general-purpose chat panel in the right sidebar. It spawns an AI process but isn't pipeline work, so the app excludes it from analytics by design.
+- **Setup wizard** — the install/enrich flow when you add a project. It *does* spawn an AI CLI (a genuine model invocation), but it's an interactive one-time wizard rather than a repeatable pipeline job, so it's deliberately left uninstrumented.
+
+If you want the absolute total of what an engine has cost you, your provider's own console (e.g. the Anthropic console for Claude) is the source of truth.
+
+## The Analytics page
+
+Open **Analytics** from the project right sidebar.
+
+### Sticky filter header
+
+- **Period** — `7d`, `30d`, `90d`, or `All`. (There's no 24-hour or custom-range option here — the custom calendar range lives on Desktop Analytics, below.)
+- **Surface** — chips for `All` plus each of the six surfaces (Jobs, Explore, Quick, Refine, SMASH, File summaries). All are included by default; toggle chips to narrow the view.
+- **Engine** — provider chips (Claude / Codex) that appear **only on multi-provider projects**, letting you filter by engine.
+
+The period and surface filters are URL-synced, so you can share or bookmark a view.
+
+### Hero burn meter
+
+The big number at the top is total spend in the selected period, with:
+
+- a `% vs prev` delta (the same period length ending where the previous interval ended),
+- the invocation count and total token count,
+- a per-surface cost breakdown bar with a legend (cost + count per surface),
+- and, when any rows are estimated, an "includes ~$X estimated" footnote.
+
+When the project has zero invocations in the period (e.g. you just started), the Hero shows "Tracking started YYYY-MM-DD" — the date of the first invocation ever recorded. There's no historical backfill; tracking begins at that first row.
+
+### Provider breakdown
+
+On multi-provider projects, a dedicated card splits total spend between Claude and Codex. It's hidden on single-provider projects.
+
+### Daily stacked timeline
+
+A daily bar chart for the period, stacked by surface. Days with zero activity are zero-filled so the x-axis stays regular.
+
+Surface colours are consistent across the whole page:
+
+- `job` → blue (`accent-info`)
+- `quick-spec` → purple (`accent-secondary`)
+- `explore-spec` → highlight (`accent-highlight`)
+- `ai-edit` → green (`accent-success`)
+- `smash` → highlight (`accent-highlight`)
+- `file-summary` → yellow (`accent-warning`)
+
+### Quick vs Explore card
+
+Share-of-spend between Quick spec generation and Explore conversations, with a small sparkline. If Explore has fewer than 5 runs in the period, a CTA nudges you to try it.
+
+### Top models
+
+The top 10 models used in the period with their share of spend. Click a row to filter the rest of the page by that model.
+
+### Cost-vs-turns scatter
+
+A scatter plot of the last 500 invocations: x = turns, y = cost. Handy for spotting the outlier "this Explore session burned 4×" runs.
+
+### Top tickets
+
+The top 10 tickets by total spend across all surfaces, ranked by cost. Two special cases compete for those slots:
+
+- **Deleted tickets** appear individually, one per ticket (e.g. `deleted ticket #42`) — invocations whose `ticket_id` no longer resolves.
+- **Unattributed** is a single synthetic bucket for invocations with no `ticket_id` (mostly mid-Explore turns before commit).
+
+Neither is pinned — they show up only when they rank into the top 10.
+
+### Raw invocations table
+
+At the bottom of the page. It loads up to 100 rows in one batch and shows a "Showing first N of M matching rows" note when there are more. Secondary filters scoped to the table only (a narrower date range, status, and minimum cost) let you drill in.
+
+Columns: **Surface, Ticket, Cost, Turns, Tokens, Model, Status, Started.**
+
+A few rendering details to know:
+
+- Contract Refine invocations show as **Contract Layer** in the Surface column and "Contract Layer refinement" in the Ticket column.
+- Uncommitted Explore turns show a provisional, italicised title derived from the first user message — these are tickets that aren't committed yet.
+
+## Per-ticket spending
+
+Inside any spec's detail modal there's a one-line spending summary just below the title:
+
+```
+$0.42 · 3 turns · 4m 12s active · 2 jobs + 1 explore
+```
+
+The breakdown segment is a **count** of invocations per surface, not a cost split. Clicking the line opens Analytics filtered to that ticket (`?ticketId=<id>` in the URL).
+
+## Exports
+
+Top-right of the Analytics page → the **Export** dropdown. Four options:
+
+| Export | Format | What's included |
+|--------|--------|-----------------|
+| **Summary CSV** | Multi-section CSV | Totals, daily timeline, by-surface, by-model, top tickets |
+| **Summary JSON** | JSON | Same data, structured |
+| **Raw CSV** | CSV | One row per invocation, capped at 10,000 rows |
+| **Raw JSON** | JSON | Same |
+
+Filename patterns differ by mode: Summary exports use `<project-slug>-analytics-<period>-<YYYY-MM-DD>.{csv,json}`; Raw exports use `<project-slug>-invocations-<period>[-<surface>]-<YYYY-MM-DD>.{csv,json}` — the optional `-<surface>` segment appears only on raw exports.
+
+Raw exports above 10,000 rows append a `# truncated_at=N of M` comment line. If you need more, narrow the period or surface filter first.
+
+Exports use the standard `fetch → Blob → URL.createObjectURL → anchor.click()` pattern, so they work the same in the Tauri desktop webview as in a browser. On failure a sonner `Export failed` toast surfaces.
+
+## Setting a budget
+
+Open **Settings** from the project right sidebar → the **Budget** card:
+
+- **Daily budget (USD)** — the app auto-pauses the queue when the day's spend (the sum of completed-job cost since midnight) exceeds this. New rail launches queue rather than start; in-flight jobs aren't killed.
+- **Per-job cost alert (USD)** — emits an alert when a single job exceeds this amount.
+
+Leave either field blank to disable that limit.
+
+When the daily budget is hit, a dismissible banner appears across the project pages ("Daily budget exceeded — … Queue is paused.") and the queue stays paused server-side. Resume by raising the budget, clearing it, or waiting for the counter to reset at midnight (it counts completed-job cost since the start of the current calendar day, not a rolling 24-hour window).
+
+See [Customising the app](customizing.md#budget) for the full setup.
+
+## App-wide analytics
+
+For the cross-project view, open **Analytics** from the Arc sidebar on the left. Desktop Analytics is a separate page with its own blocks — KPI cards, a cost timeline, and per-project breakdowns — rolled up across all your registered projects. It also offers a custom calendar date range that the per-project page doesn't.
+
+## Where to go next
+
+- [Customising the app](customizing.md) — set the budget, configure notifications.
+- [Creating specs](creating-specs.md) — every spec you create adds rows to your analytics.
+- [Using Codex](codex.md) — how cost works when you run a project on Codex.

package/package.json

@@ -0,0 +1,82 @@
+{
+  "name": "specrails-desktop",
+  "version": "2.0.0",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/fjpulidop/specrails-desktop.git"
+  },
+  "engines": {
+    "node": ">=20.0.0"
+  },
+  "bin": {
+    "specrails-desktop": "cli/dist/specrails-desktop.js"
+  },
+  "files": [
+    "cli/dist",
+    "server/dist",
+    "client/dist",
+    "docs",
+    ".claude/commands/specrails"
+  ],
+  "scripts": {
+    "dev": "concurrently \"npm run dev:server\" \"npm run dev:client\"",
+    "dev:server": "tsx watch server/index.ts",
+    "dev:client": "cd client && npm run dev",
+    "dev:desktop": "tauri dev",
+    "build:server": "node -e \"require('fs').rmSync('server/dist',{recursive:true,force:true})\" && tsc --project tsconfig.json",
+    "build:cli": "tsc --project tsconfig.cli.json",
+    "build": "npm run build:server && cd client && npm run build && cd .. && npm run build:cli",
+    "build:sidecar": "node scripts/build-sidecar.mjs",
+    "build:desktop": "npm run build:server && cd client && npm run build && cd .. && npm run build:sidecar && tauri build",
+    "assemble-runtimes": "node scripts/assemble-runtimes-local.mjs",
+    "build:desktop:local": "npm run assemble-runtimes && npm run build:desktop",
+    "generate-icons": "tauri icon src-tauri/icons/icon.svg",
+    "typecheck": "tsc --noEmit && tsc -p tsconfig.cli.json --noEmit && cd client && tsc --noEmit",
+    "check-core-compat": "tsx scripts/check-core-compat.ts",
+    "test": "vitest run && tsx scripts/check-core-compat.ts",
+    "test:watch": "vitest",
+    "test:coverage": "vitest run --coverage",
+    "test:client": "cd client && npx vitest run",
+    "test:all": "vitest run && cd client && npx vitest run",
+    "ci": "npm run typecheck && npm run check-core-compat && npm run test:coverage && cd client && npm run test:coverage"
+  },
+  "dependencies": {
+    "@homebridge/ciao": "^1.3.9",
+    "@tailwindcss/typography": "^0.5.19",
+    "ajv": "^8.17.1",
+    "better-sqlite3": "^12.8.0",
+    "chokidar": "^5.0.0",
+    "cross-spawn": "^7.0.6",
+    "diff": "^9.0.0",
+    "express": "^5.2.1",
+    "multer": "^2.1.1",
+    "node-pty": "^1.0.0",
+    "pdf-parse": "^2.4.5",
+    "playwright": "^1.60.0",
+    "read-excel-file": "^9.0.6",
+    "selfsigned": "^5.5.0",
+    "tree-kill": "^1.2.2",
+    "ws": "^8.16.0"
+  },
+  "devDependencies": {
+    "@tauri-apps/cli": "^2.0.0",
+    "@types/better-sqlite3": "^7.6.0",
+    "@types/chokidar": "^1.7.5",
+    "@types/cross-spawn": "^6.0.6",
+    "@types/diff": "^7.0.2",
+    "@types/express": "^5.0.6",
+    "@types/multer": "^2.1.0",
+    "@types/node": "^25.5.0",
+    "@types/pdf-parse": "^1.1.5",
+    "@types/supertest": "^7.2.0",
+    "@types/ws": "^8.5.0",
+    "@vitest/coverage-v8": "^4.1.0",
+    "concurrently": "^9.2.1",
+    "esbuild": "^0.28.0",
+    "supertest": "^7.2.2",
+    "tsx": "^4.7.0",
+    "typescript": "^5.4.0",
+    "vitest": "^4.1.0"
+  }
+}

package/server/dist/agent-generator.js

@@ -0,0 +1,232 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.generateCustomAgent = generateCustomAgent;
+exports.testCustomAgent = testCustomAgent;
+const readline_1 = require("readline");
+const crypto_1 = require("crypto");
+const cli_prompt_1 = require("./util/cli-prompt");
+/**
+ * Generate a draft `custom-*.md` body by spawning a one-shot claude
+ * invocation with an agent-authoring system prompt. Resolves with the full
+ * response text after the child process closes; rejects on non-zero exit or
+ * spawn error.
+ *
+ * Hard cap on the child: 90 seconds wall-clock. Callers should also set a
+ * timeout on their fetch/HTTP layer for safety.
+ */
+async function generateCustomAgent(cwd, opts) {
+    const systemPrompt = [
+        'You are a specrails agent-authoring assistant.',
+        '',
+        'Your task: given a short description of what the user wants, produce a COMPLETE',
+        'Markdown file for a specrails custom agent. The file MUST be valid input for',
+        'Claude Code: YAML frontmatter between `---` separators, followed by the agent body.',
+        '',
+        'Required frontmatter fields:',
+        '  - name: the exact agent id (starts with `custom-`, lowercase, kebab-case)',
+        '  - description: one sentence saying when this agent should run (include tag hints in square brackets)',
+        '  - model: one of `sonnet`, `opus`, `haiku`',
+        '  - color: one of `blue`, `green`, `red`, `yellow`, `purple`, `cyan`',
+        '  - memory: `project`',
+        '',
+        'Body sections (use `#` headings): Identity, Mission, Workflow protocol, Personality.',
+        'Personality block: bullet list of tone, risk_tolerance, detail_level, focus_areas.',
+        '',
+        'Be concise. No conversational preamble. Output ONLY the Markdown file — no code',
+        'fences, no explanations. Start at `---`.',
+    ].join('\n');
+    const userPrompt = [
+        `Generate a custom agent with id "${opts.name}".`,
+        '',
+        'Description of what it should do:',
+        opts.description,
+    ].join('\n');
+    return new Promise((resolve, reject) => {
+        const child = (0, cli_prompt_1.spawnClaude)([
+            '--dangerously-skip-permissions',
+            '--output-format',
+            'stream-json',
+            '--verbose',
+            '--append-system-prompt',
+            systemPrompt,
+            '-p',
+            userPrompt,
+        ], {
+            env: process.env,
+            stdio: ['ignore', 'pipe', 'pipe'],
+            cwd,
+        });
+        let collected = '';
+        const killer = setTimeout(() => {
+            try {
+                child.kill('SIGTERM');
+            }
+            catch { /* ignore */ }
+            reject(new Error('agent generation timed out after 90s'));
+        }, 90_000);
+        const reader = (0, readline_1.createInterface)({ input: child.stdout, crlfDelay: Infinity });
+        reader.on('line', (line) => {
+            let parsed;
+            try {
+                parsed = JSON.parse(line);
+            }
+            catch {
+                return;
+            }
+            if (!parsed || typeof parsed !== 'object')
+                return;
+            // Claude stream-json format: {type:"assistant", message:{content:[{type:"text", text:"..."}]}}
+            const p = parsed;
+            const message = p.message;
+            const content = message?.content;
+            if (Array.isArray(content)) {
+                for (const block of content) {
+                    if (block && typeof block === 'object' && block.type === 'text') {
+                        const text = block.text;
+                        if (typeof text === 'string')
+                            collected += text;
+                    }
+                }
+            }
+        });
+        let stderr = '';
+        child.stderr.on('data', (chunk) => { stderr += chunk.toString(); });
+        child.on('error', (err) => {
+            clearTimeout(killer);
+            reject(err);
+        });
+        child.on('close', (code) => {
+            clearTimeout(killer);
+            if (code !== 0) {
+                reject(new Error(`claude exited with code ${code}${stderr ? `: ${stderr.slice(-500)}` : ''}`));
+                return;
+            }
+            const trimmed = collected.trim();
+            if (!trimmed) {
+                reject(new Error('claude returned empty output'));
+                return;
+            }
+            resolve(trimmed);
+        });
+    });
+}
+/**
+ * Smoke-test a draft custom agent. Strips the frontmatter, uses the agent body
+ * as a claude system prompt, and runs the sample task as the user prompt. Does
+ * not touch the filesystem or register the agent anywhere — purely sandboxed.
+ *
+ * Returns the full assistant output plus token usage and duration for the
+ * Studio's Test pane and the agent_tests table.
+ *
+ * Hard cap: 120 seconds wall-clock, 4000-token configurable ceiling (callers
+ * can override via `tokenCeiling`).
+ */
+async function testCustomAgent(cwd, opts) {
+    const tokenCeiling = opts.tokenCeiling ?? 4000;
+    // Strip YAML frontmatter so we feed only the agent's instructions.
+    const body = opts.draftBody.replace(/^---\r?\n[\s\S]*?\r?\n---\r?\n?/, '').trim();
+    if (!body) {
+        throw new Error('agent body is empty after stripping frontmatter');
+    }
+    const systemPrompt = [
+        'You are acting as the agent described below. Follow its Identity, Mission,',
+        'Workflow protocol, and Personality. Respond to the user task using those',
+        'instructions. Do NOT preface your response; produce only the agent output.',
+        '',
+        '--- agent instructions ---',
+        body,
+        '--- end agent instructions ---',
+    ].join('\n');
+    const draftHash = (0, crypto_1.createHash)('sha256').update(opts.draftBody).digest('hex').slice(0, 16);
+    const started = Date.now();
+    return new Promise((resolve, reject) => {
+        const child = (0, cli_prompt_1.spawnClaude)([
+            '--dangerously-skip-permissions',
+            '--output-format',
+            'stream-json',
+            '--verbose',
+            '--append-system-prompt',
+            systemPrompt,
+            '-p',
+            opts.sampleTask,
+        ], {
+            env: process.env,
+            stdio: ['ignore', 'pipe', 'pipe'],
+            cwd,
+        });
+        let collected = '';
+        let tokensIn = 0;
+        let tokensOut = 0;
+        let truncated = false;
+        const killer = setTimeout(() => {
+            try {
+                child.kill('SIGTERM');
+            }
+            catch { /* ignore */ }
+            reject(new Error('test agent run timed out after 120s'));
+        }, 120_000);
+        const reader = (0, readline_1.createInterface)({ input: child.stdout, crlfDelay: Infinity });
+        reader.on('line', (line) => {
+            let parsed;
+            try {
+                parsed = JSON.parse(line);
+            }
+            catch {
+                return;
+            }
+            if (!parsed || typeof parsed !== 'object')
+                return;
+            const p = parsed;
+            // Text blocks
+            const message = p.message;
+            const content = message?.content;
+            if (Array.isArray(content)) {
+                for (const block of content) {
+                    if (block && typeof block === 'object' && block.type === 'text') {
+                        const text = block.text;
+                        if (typeof text === 'string')
+                            collected += text;
+                    }
+                }
+            }
+            // Usage in result / stop events
+            const usage = (p.usage ?? message?.usage);
+            if (usage) {
+                if (typeof usage.input_tokens === 'number')
+                    tokensIn += usage.input_tokens;
+                if (typeof usage.output_tokens === 'number')
+                    tokensOut += usage.output_tokens;
+            }
+            // Enforce token ceiling
+            if (tokensIn + tokensOut >= tokenCeiling && !truncated) {
+                truncated = true;
+                try {
+                    child.kill('SIGTERM');
+                }
+                catch { /* ignore */ }
+            }
+        });
+        let stderr = '';
+        child.stderr.on('data', (chunk) => { stderr += chunk.toString(); });
+        child.on('error', (err) => {
+            clearTimeout(killer);
+            reject(err);
+        });
+        child.on('close', (code) => {
+            clearTimeout(killer);
+            const durationMs = Date.now() - started;
+            if (!truncated && code !== 0 && !collected) {
+                reject(new Error(`claude exited with code ${code}${stderr ? `: ${stderr.slice(-500)}` : ''}`));
+                return;
+            }
+            resolve({
+                output: truncated
+                    ? collected + `\n\n[… output truncated after reaching ${tokenCeiling}-token ceiling]`
+                    : collected,
+                tokens: tokensIn + tokensOut,
+                durationMs,
+                draftHash,
+            });
+        });
+    });
+}

package/server/dist/agent-refine-db.js

@@ -0,0 +1,124 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.createRefineSession = createRefineSession;
+exports.getRefineSession = getRefineSession;
+exports.listRefineSessionsForAgent = listRefineSessionsForAgent;
+exports.updateRefineSession = updateRefineSession;
+exports.deleteRefineSession = deleteRefineSession;
+exports.pruneStaleRefineSessions = pruneStaleRefineSessions;
+function rowToSession(row) {
+    let history = [];
+    try {
+        const parsed = JSON.parse(row.history_json);
+        if (Array.isArray(parsed))
+            history = parsed;
+    }
+    catch {
+        // corrupted — start fresh
+    }
+    return {
+        id: row.id,
+        agent_id: row.agent_id,
+        session_id: row.session_id,
+        base_version: row.base_version,
+        base_body_hash: row.base_body_hash,
+        draft_body: row.draft_body,
+        history,
+        phase: row.phase,
+        status: row.status,
+        auto_test: row.auto_test === 0 ? 0 : 1,
+        last_test_at: row.last_test_at,
+        last_test_hash: row.last_test_hash,
+        created_at: row.created_at,
+        updated_at: row.updated_at,
+    };
+}
+function createRefineSession(db, input) {
+    const now = Date.now();
+    db.prepare(`INSERT INTO agent_refine_sessions
+      (id, agent_id, session_id, base_version, base_body_hash, draft_body,
+       history_json, phase, status, auto_test, last_test_at, last_test_hash,
+       created_at, updated_at)
+     VALUES (?, ?, NULL, ?, ?, NULL, '[]', 'idle', 'idle', ?, NULL, NULL, ?, ?)`).run(input.id, input.agentId, input.baseVersion, input.baseBodyHash, input.autoTest ? 1 : 0, now, now);
+    return getRefineSession(db, input.id);
+}
+function getRefineSession(db, id) {
+    const row = db
+        .prepare(`SELECT * FROM agent_refine_sessions WHERE id = ?`)
+        .get(id);
+    if (!row)
+        return undefined;
+    return rowToSession(row);
+}
+function listRefineSessionsForAgent(db, agentId) {
+    const rows = db
+        .prepare(`SELECT * FROM agent_refine_sessions WHERE agent_id = ? ORDER BY updated_at DESC`)
+        .all(agentId);
+    return rows.map(rowToSession);
+}
+function updateRefineSession(db, id, patch) {
+    const fields = [];
+    const values = [];
+    if (Object.prototype.hasOwnProperty.call(patch, 'session_id')) {
+        fields.push('session_id = ?');
+        values.push(patch.session_id);
+    }
+    if (Object.prototype.hasOwnProperty.call(patch, 'draft_body')) {
+        fields.push('draft_body = ?');
+        values.push(patch.draft_body);
+    }
+    if (patch.history !== undefined) {
+        fields.push('history_json = ?');
+        values.push(JSON.stringify(patch.history));
+    }
+    if (patch.phase !== undefined) {
+        fields.push('phase = ?');
+        values.push(patch.phase);
+    }
+    if (patch.status !== undefined) {
+        fields.push('status = ?');
+        values.push(patch.status);
+    }
+    if (patch.auto_test !== undefined) {
+        fields.push('auto_test = ?');
+        values.push(patch.auto_test);
+    }
+    if (Object.prototype.hasOwnProperty.call(patch, 'last_test_at')) {
+        fields.push('last_test_at = ?');
+        values.push(patch.last_test_at);
+    }
+    if (Object.prototype.hasOwnProperty.call(patch, 'last_test_hash')) {
+        fields.push('last_test_hash = ?');
+        values.push(patch.last_test_hash);
+    }
+    if (fields.length === 0)
+        return;
+    fields.push('updated_at = ?');
+    values.push(Date.now());
+    values.push(id);
+    db.prepare(`UPDATE agent_refine_sessions SET ${fields.join(', ')} WHERE id = ?`).run(...values);
+}
+function deleteRefineSession(db, id) {
+    db.prepare(`DELETE FROM agent_refine_sessions WHERE id = ?`).run(id);
+}
+/**
+ * Startup retention prune (per design D11):
+ * - Delete cancelled/error sessions older than 24h
+ * - Mark stuck streaming sessions (>24h since update) as error, then delete
+ * - Retain ready/applied sessions indefinitely
+ *
+ * Returns the number of rows removed.
+ */
+function pruneStaleRefineSessions(db, now = Date.now()) {
+    const cutoff = now - 24 * 60 * 60 * 1000;
+    // Mark stuck streaming sessions as error first so any UI rehydrates with a
+    // sane state. Preserve `updated_at` so the DELETE below still matches them.
+    db.prepare(`UPDATE agent_refine_sessions
+     SET status = 'error'
+     WHERE status = 'streaming' AND updated_at < ?`).run(cutoff);
+    const res = db
+        .prepare(`DELETE FROM agent_refine_sessions
+       WHERE status IN ('cancelled', 'error', 'idle') AND updated_at < ?`)
+        .run(cutoff);
+    return Number(res.changes ?? 0);
+}