specrails-desktop 2.0.0

package/server/dist/desktop-analytics.js

@@ -0,0 +1,156 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.getDesktopAnalytics = getDesktopAnalytics;
+exports.getDesktopRecentJobs = getDesktopRecentJobs;
+exports.getDesktopTodayStats = getDesktopTodayStats;
+function resolveBounds(opts) {
+    const now = new Date();
+    const toISO = (d) => d.toISOString().slice(0, 10);
+    if (opts.period === 'all') {
+        return { current: { from: null, to: null }, label: 'All time' };
+    }
+    if (opts.period === 'custom') {
+        // B42: from/to are unvalidated query params. A malformed date flows into
+        // buildWhere's `new Date(bounds.to).toISOString()` and throws an unhandled
+        // RangeError ("Invalid time value") → 500. Drop any unparseable bound (and
+        // fall back to all-time when neither is valid) instead of crashing.
+        const validFrom = opts.from && !Number.isNaN(Date.parse(opts.from)) ? opts.from : null;
+        const validTo = opts.to && !Number.isNaN(Date.parse(opts.to)) ? opts.to : null;
+        return {
+            current: { from: validFrom, to: validTo },
+            label: validFrom || validTo ? `${validFrom ?? '…'} to ${validTo ?? '…'}` : 'All time',
+        };
+    }
+    const days = opts.period === '7d' ? 7 : opts.period === '30d' ? 30 : 90;
+    const from = toISO(new Date(now.getTime() - days * 86400000));
+    const to = toISO(now);
+    const label = opts.period === '7d' ? 'Last 7 days'
+        : opts.period === '30d' ? 'Last 30 days'
+            : 'Last 90 days';
+    return { current: { from, to }, label };
+}
+function buildWhere(bounds) {
+    if (!bounds.from && !bounds.to)
+        return { clause: '', params: [] };
+    if (bounds.from && bounds.to) {
+        const nextDay = new Date(new Date(bounds.to).getTime() + 86400000).toISOString().slice(0, 10);
+        return { clause: 'WHERE started_at >= ? AND started_at < ?', params: [bounds.from, nextDay] };
+    }
+    if (bounds.from)
+        return { clause: 'WHERE started_at >= ?', params: [bounds.from] };
+    const nextDay = new Date(new Date(bounds.to).getTime() + 86400000).toISOString().slice(0, 10);
+    return { clause: 'WHERE started_at < ?', params: [nextDay] };
+}
+function queryProjectKpi(db, clause, params) {
+    return db.prepare(`
+    SELECT
+      COALESCE(SUM(total_cost_usd), 0) as totalCostUsd,
+      COUNT(*) as totalJobs,
+      SUM(CASE WHEN status = 'completed' THEN 1 ELSE 0 END) as successCount,
+      AVG(CASE WHEN duration_ms IS NOT NULL THEN duration_ms END) as avgDurationMs
+    FROM jobs ${clause}
+  `).get(...params);
+}
+function queryProjectTimeline(db, clause, params) {
+    return db.prepare(`
+    SELECT
+      strftime('%Y-%m-%d', started_at) as date,
+      COALESCE(SUM(total_cost_usd), 0) as costUsd
+    FROM jobs ${clause}
+    GROUP BY date
+    ORDER BY date ASC
+  `).all(...params);
+}
+// ─── Main export ──────────────────────────────────────────────────────────────
+function getDesktopAnalytics(registry, opts) {
+    const { current, label } = resolveBounds(opts);
+    const { clause, params } = buildWhere(current);
+    const today = new Date().toISOString().slice(0, 10);
+    const tomorrow = new Date(Date.now() + 86400000).toISOString().slice(0, 10);
+    const todayClause = 'WHERE started_at >= ? AND started_at < ?';
+    const todayParams = [today, tomorrow];
+    const contexts = registry.listContexts();
+    let totalCostUsd = 0;
+    let totalJobs = 0;
+    let totalSuccess = 0;
+    let costToday = 0;
+    let jobsToday = 0;
+    const projectBreakdown = [];
+    const timelineMap = new Map();
+    // Iterate sequentially to avoid SQLite contention
+    for (const ctx of contexts) {
+        const kpi = queryProjectKpi(ctx.db, clause, params);
+        const todayKpi = queryProjectKpi(ctx.db, todayClause, todayParams);
+        const timeline = queryProjectTimeline(ctx.db, clause, params);
+        totalCostUsd += kpi.totalCostUsd;
+        totalJobs += kpi.totalJobs;
+        totalSuccess += kpi.successCount;
+        costToday += todayKpi.totalCostUsd;
+        jobsToday += todayKpi.totalJobs;
+        projectBreakdown.push({
+            projectId: ctx.project.id,
+            projectName: ctx.project.name,
+            totalCostUsd: kpi.totalCostUsd,
+            totalJobs: kpi.totalJobs,
+            successRate: kpi.totalJobs > 0 ? kpi.successCount / kpi.totalJobs : 0,
+            avgDurationMs: kpi.avgDurationMs,
+        });
+        for (const row of timeline) {
+            timelineMap.set(row.date, (timelineMap.get(row.date) ?? 0) + row.costUsd);
+        }
+    }
+    // Build sorted cost timeline
+    const costTimeline = Array.from(timelineMap.entries())
+        .sort(([a], [b]) => a.localeCompare(b))
+        .map(([date, costUsd]) => ({ date, costUsd }));
+    // Sort projects by cost descending
+    projectBreakdown.sort((a, b) => b.totalCostUsd - a.totalCostUsd);
+    return {
+        period: { label, from: current.from, to: current.to },
+        kpi: {
+            totalCostUsd,
+            totalJobs,
+            successRate: totalJobs > 0 ? totalSuccess / totalJobs : 0,
+            costToday,
+            jobsToday,
+        },
+        projectBreakdown,
+        costTimeline,
+    };
+}
+function getDesktopRecentJobs(registry, limit = 10) {
+    const all = [];
+    for (const ctx of registry.listContexts()) {
+        const rows = ctx.db.prepare(`
+      SELECT id, command, started_at, finished_at, status, total_cost_usd
+      FROM jobs
+      ORDER BY started_at DESC
+      LIMIT ?
+    `).all(limit);
+        for (const row of rows) {
+            all.push({ ...row, projectId: ctx.project.id, projectName: ctx.project.name });
+        }
+    }
+    return all
+        .sort((a, b) => b.started_at.localeCompare(a.started_at))
+        .slice(0, limit);
+}
+function getDesktopTodayStats(registry) {
+    const today = new Date().toISOString().slice(0, 10);
+    const tomorrow = new Date(Date.now() + 86400000).toISOString().slice(0, 10);
+    const clause = 'WHERE started_at >= ? AND started_at < ?';
+    const params = [today, tomorrow];
+    let costToday = 0;
+    let jobsToday = 0;
+    for (const ctx of registry.listContexts()) {
+        const row = ctx.db.prepare(`
+      SELECT
+        COALESCE(SUM(total_cost_usd), 0) as costToday,
+        COUNT(*) as jobsToday
+      FROM jobs ${clause}
+    `).get(...params);
+        costToday += row.costToday;
+        jobsToday += row.jobsToday;
+    }
+    return { costToday, jobsToday };
+}

package/server/dist/desktop-db.js

@@ -0,0 +1,456 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.getDesktopDbPath = getDesktopDbPath;
+exports.initDesktopDb = initDesktopDb;
+exports.listProjects = listProjects;
+exports.getProject = getProject;
+exports.getProjectBySlug = getProjectBySlug;
+exports.getProjectByPath = getProjectByPath;
+exports.addProject = addProject;
+exports.removeProject = removeProject;
+exports.touchProject = touchProject;
+exports.getDesktopSetting = getDesktopSetting;
+exports.setDesktopSetting = setDesktopSetting;
+exports.setProjectSetupSession = setProjectSetupSession;
+exports.getProjectSetupSession = getProjectSetupSession;
+exports.clearProjectSetupSession = clearProjectSetupSession;
+exports.listAgents = listAgents;
+exports.getAgent = getAgent;
+exports.getAgentBySlug = getAgentBySlug;
+exports.addAgent = addAgent;
+exports.updateAgent = updateAgent;
+exports.findAgentByCurrentJobId = findAgentByCurrentJobId;
+exports.clearAgentJob = clearAgentJob;
+exports.listWebhooks = listWebhooks;
+exports.listWebhooksForProject = listWebhooksForProject;
+exports.getWebhook = getWebhook;
+exports.addWebhook = addWebhook;
+exports.updateWebhook = updateWebhook;
+exports.removeWebhook = removeWebhook;
+const fs_1 = __importDefault(require("fs"));
+const path_1 = __importDefault(require("path"));
+const os_1 = __importDefault(require("os"));
+const better_sqlite3_1 = __importDefault(require("better-sqlite3"));
+const secure_fs_1 = require("./util/secure-fs");
+function parseProviders(raw, primary) {
+    if (raw) {
+        try {
+            const parsed = JSON.parse(raw);
+            if (Array.isArray(parsed) && parsed.length > 0 && parsed.every((x) => typeof x === 'string')) {
+                return parsed;
+            }
+        }
+        catch {
+            /* fall through to single-provider fallback */
+        }
+    }
+    return [primary];
+}
+function mapProjectRow(raw) {
+    if (!raw)
+        return undefined;
+    const provider = (raw.provider ?? 'claude');
+    return { ...raw, provider, providers: parseProviders(raw.providers, provider) };
+}
+// ─── Desktop DB path ──────────────────────────────────────────────────────────
+function getDesktopDbPath() {
+    return path_1.default.join(os_1.default.homedir(), '.specrails', 'desktop.sqlite');
+}
+/**
+ * Rebrand migration (Specrails Hub → Specrails Desktop): when the legacy
+ * `hub.sqlite` exists next to the requested `desktop.sqlite` and the new file
+ * does not exist yet, rename it (plus any `-wal`/`-shm` siblings) so user data
+ * is preserved across the rename. Legacy filename allowed here only —
+ * migration/compat code.
+ */
+function migrateLegacyDbFile(dbPath) {
+    if (dbPath === ':memory:')
+        return;
+    if (path_1.default.basename(dbPath) !== 'desktop.sqlite')
+        return;
+    const legacyPath = path_1.default.join(path_1.default.dirname(dbPath), 'hub.sqlite'); // legacy (pre-rebrand) filename
+    try {
+        if (fs_1.default.existsSync(legacyPath) && !fs_1.default.existsSync(dbPath)) {
+            fs_1.default.renameSync(legacyPath, dbPath);
+            for (const suffix of ['-wal', '-shm']) {
+                if (fs_1.default.existsSync(legacyPath + suffix)) {
+                    fs_1.default.renameSync(legacyPath + suffix, dbPath + suffix);
+                }
+            }
+        }
+    }
+    catch (err) {
+        console.warn('[desktop-db] could not migrate legacy hub.sqlite:', err);
+    }
+}
+function getProjectDbPath(slug) {
+    return path_1.default.join(os_1.default.homedir(), '.specrails', 'projects', slug, 'jobs.sqlite');
+}
+// ─── Schema migrations ────────────────────────────────────────────────────────
+// NOTE: existing migrations below intentionally keep the legacy `hub_settings`
+// table name — they are append-only history and must stay byte-identical for
+// already-migrated databases. Migration 13 renames the table to
+// `desktop_settings`; fresh databases run 1→13 in order and converge on the
+// new name. Legacy identifiers allowed here only — migration/compat code.
+function applyDesktopMigrations(db) {
+    db.exec(`
+    CREATE TABLE IF NOT EXISTS schema_migrations (
+      version     INTEGER PRIMARY KEY,
+      applied_at  TEXT NOT NULL DEFAULT (datetime('now'))
+    );
+  `);
+    const appliedVersions = new Set(db.prepare('SELECT version FROM schema_migrations').all()
+        .map((r) => r.version));
+    const migrations = [
+        // Migration 1: projects and hub_settings tables
+        () => {
+            db.exec(`
+        CREATE TABLE IF NOT EXISTS projects (
+          id           TEXT PRIMARY KEY,
+          slug         TEXT NOT NULL UNIQUE,
+          name         TEXT NOT NULL,
+          path         TEXT NOT NULL UNIQUE,
+          db_path      TEXT NOT NULL,
+          added_at     TEXT NOT NULL DEFAULT (datetime('now')),
+          last_seen_at TEXT NOT NULL DEFAULT (datetime('now'))
+        );
+
+        CREATE INDEX IF NOT EXISTS idx_projects_slug ON projects(slug);
+        CREATE INDEX IF NOT EXISTS idx_projects_path ON projects(path);
+
+        CREATE TABLE IF NOT EXISTS hub_settings (
+          key   TEXT PRIMARY KEY,
+          value TEXT NOT NULL
+        );
+      `);
+        },
+        // Migration 2: agents table
+        () => {
+            db.exec(`
+        CREATE TABLE IF NOT EXISTS agents (
+          id                 TEXT PRIMARY KEY,
+          slug               TEXT NOT NULL UNIQUE,
+          name               TEXT NOT NULL,
+          role               TEXT,
+          status             TEXT NOT NULL DEFAULT 'idle',
+          current_job_id     TEXT,
+          last_heartbeat_at  TEXT,
+          config             TEXT,
+          created_at         TEXT NOT NULL DEFAULT (datetime('now'))
+        );
+
+        CREATE INDEX IF NOT EXISTS idx_agents_slug ON agents(slug);
+        CREATE INDEX IF NOT EXISTS idx_agents_current_job_id ON agents(current_job_id);
+      `);
+        },
+        // Migration 3: add provider column to projects
+        () => {
+            db.exec(`ALTER TABLE projects ADD COLUMN provider TEXT NOT NULL DEFAULT 'claude'`);
+        },
+        // Migration 4: webhooks table
+        () => {
+            db.exec(`
+        CREATE TABLE IF NOT EXISTS webhooks (
+          id         TEXT PRIMARY KEY,
+          project_id TEXT REFERENCES projects(id) ON DELETE CASCADE,
+          url        TEXT NOT NULL,
+          secret     TEXT NOT NULL DEFAULT '',
+          events     TEXT NOT NULL DEFAULT '["job.completed","job.failed"]',
+          enabled    INTEGER NOT NULL DEFAULT 1,
+          created_at TEXT NOT NULL DEFAULT (datetime('now')),
+          updated_at TEXT NOT NULL DEFAULT (datetime('now'))
+        );
+
+        CREATE INDEX IF NOT EXISTS idx_webhooks_project_id ON webhooks(project_id);
+      `);
+        },
+        // Migration 5: seed terminal-settings defaults under reserved settings keys.
+        // Idempotent — uses INSERT OR IGNORE so re-running never overwrites a user's
+        // chosen value. See server/terminal-settings.ts for the typed access layer.
+        () => {
+            const seed = db.prepare('INSERT OR IGNORE INTO hub_settings (key, value) VALUES (?, ?)');
+            seed.run('terminal.fontFamily', "'DM Mono', 'JetBrains Mono', ui-monospace, Menlo, monospace");
+            seed.run('terminal.fontSize', '12');
+            seed.run('terminal.renderMode', 'auto');
+            seed.run('terminal.copyOnSelect', 'false');
+            seed.run('terminal.shellIntegrationEnabled', 'true');
+            seed.run('terminal.notifyOnCompletion', 'true');
+            seed.run('terminal.imageRendering', 'true');
+            seed.run('terminal.longCommandThresholdMs', '60000');
+        },
+        // Migration 6: seed browserShortcutUrl default for the new Browser shortcut button.
+        () => {
+            db.prepare('INSERT OR IGNORE INTO hub_settings (key, value) VALUES (?, ?)').run('terminal.browserShortcutUrl', 'https://specrails.dev');
+        },
+        // Migration 7: seed quickScript default for the Quick Script shortcut button.
+        // Uses the OS username so the default greets you by name.
+        () => {
+            let username = 'friend';
+            try {
+                username = os_1.default.userInfo().username || 'friend';
+            }
+            catch { /* keep fallback */ }
+            const value = `echo "Wake up, ${username} (edit this snippet in settings to help your local development)"`;
+            db.prepare('INSERT OR IGNORE INTO hub_settings (key, value) VALUES (?, ?)').run('terminal.quickScript', value);
+        },
+        // Migration 8: seed default ui_theme for the app-wide theme system.
+        // Allow-list enforced at the route layer (server/desktop-router.ts) and the
+        // client (client/src/lib/themes.ts).
+        () => {
+            db.prepare('INSERT OR IGNORE INTO hub_settings (key, value) VALUES (?, ?)').run('ui_theme', 'specrails');
+        },
+        // Migration 9: seed code-explorer app settings — summary language + monthly
+        // budget cap. Enforced by FileSummaryManager + desktop-router.
+        () => {
+            const seed = db.prepare('INSERT OR IGNORE INTO hub_settings (key, value) VALUES (?, ?)');
+            seed.run('summary_language', 'en');
+            seed.run('summary_monthly_budget_usd', '5.00');
+        },
+        // Migration 10: multi-provider per project. Add a `providers` JSON-array
+        // column alongside the existing primary `provider` column and backfill it
+        // from the current single provider so legacy projects become
+        // providers=["<provider>"] (length 1 → behaves exactly as before).
+        () => {
+            db.exec(`ALTER TABLE projects ADD COLUMN providers TEXT NOT NULL DEFAULT '[]'`);
+            db.exec(`UPDATE projects SET providers = json_array(provider) WHERE providers IS NULL OR providers = '[]'`);
+        },
+        // Migration 11: self-heal the `providers` column. An earlier WIP of the
+        // multi-provider feature also numbered a migration #10 but used different
+        // column names (`installed_engines` / `default_engine`). On a DB that ran
+        // that variant, version 10 is already recorded so Migration 10 above is
+        // skipped and `providers` is missing — addProject's INSERT then fails. This
+        // higher-numbered migration is guarded by a column check so it is a no-op on
+        // fresh DBs (where #10 already added the column) and repairs the orphaned-
+        // WIP DBs, backfilling from `installed_engines` when present else `provider`.
+        () => {
+            const cols = db.prepare('PRAGMA table_info(projects)').all().map((c) => c.name);
+            if (!cols.includes('providers')) {
+                db.exec(`ALTER TABLE projects ADD COLUMN providers TEXT NOT NULL DEFAULT '[]'`);
+            }
+            const hasInstalledEngines = cols.includes('installed_engines');
+            const rows = db.prepare(`SELECT id, provider, providers${hasInstalledEngines ? ', installed_engines' : ''} FROM projects`).all();
+            const upd = db.prepare('UPDATE projects SET providers = ? WHERE id = ?');
+            for (const r of rows) {
+                if (r.providers && r.providers !== '[]')
+                    continue;
+                let value = null;
+                if (hasInstalledEngines && r.installed_engines) {
+                    try {
+                        const parsed = JSON.parse(r.installed_engines);
+                        if (Array.isArray(parsed) && parsed.length > 0)
+                            value = JSON.stringify(parsed);
+                    }
+                    catch {
+                        /* fall through to provider-based backfill */
+                    }
+                }
+                if (!value)
+                    value = JSON.stringify([r.provider ?? 'claude']);
+                upd.run(value, r.id);
+            }
+        },
+        // Migration 12: mobile companion devices. Each paired phone/tablet gets a
+        // hashed per-device bearer token (never the master server token), scoped to
+        // `companion`, bound to the gateway cert fingerprint active at pair time
+        // (rotating the cert revokes every device), with a sliding-expiry last_seen
+        // and a one-tap revoke (revoked_at). See server/mobile/* for the gateway.
+        () => {
+            db.exec(`
+        CREATE TABLE IF NOT EXISTS mobile_devices (
+          id               TEXT PRIMARY KEY,
+          name             TEXT NOT NULL,
+          platform         TEXT NOT NULL,
+          token_hash       TEXT NOT NULL,
+          scopes           TEXT NOT NULL DEFAULT 'companion',
+          cert_fingerprint TEXT NOT NULL,
+          created_at       TEXT NOT NULL DEFAULT (datetime('now')),
+          last_seen_at     TEXT,
+          last_ip          TEXT,
+          revoked_at       TEXT
+        );
+
+        CREATE INDEX IF NOT EXISTS idx_mobile_devices_token ON mobile_devices(token_hash);
+      `);
+        },
+        // Migration 13: Specrails Hub → Specrails Desktop rebrand. Renames the
+        // legacy `hub_settings` table to `desktop_settings` (guard: skip if a
+        // future code path ever created `desktop_settings` directly), migrates the
+        // `hub_daily_budget_usd` settings key to `desktop_daily_budget_usd`, and
+        // rewrites stored webhook event subscriptions from
+        // `hub_daily_budget_exceeded` to `desktop_daily_budget_exceeded`.
+        // Legacy identifiers allowed here only — migration/compat code.
+        () => {
+            const tables = db.prepare("SELECT name FROM sqlite_master WHERE type='table'").all()
+                .map((t) => t.name);
+            if (tables.includes('hub_settings') && !tables.includes('desktop_settings')) {
+                db.exec('ALTER TABLE hub_settings RENAME TO desktop_settings');
+            }
+            db.prepare("UPDATE OR IGNORE desktop_settings SET key = 'desktop_daily_budget_usd' WHERE key = 'hub_daily_budget_usd'").run();
+            const hooks = db.prepare("SELECT id, events FROM webhooks WHERE events LIKE '%hub_daily_budget_exceeded%'").all();
+            const upd = db.prepare('UPDATE webhooks SET events = ? WHERE id = ?');
+            for (const h of hooks) {
+                upd.run(h.events.split('hub_daily_budget_exceeded').join('desktop_daily_budget_exceeded'), h.id);
+            }
+        },
+    ];
+    for (let i = 0; i < migrations.length; i++) {
+        const version = i + 1;
+        if (!appliedVersions.has(version)) {
+            migrations[i]();
+            db.prepare('INSERT OR IGNORE INTO schema_migrations (version) VALUES (?)').run(version);
+        }
+    }
+}
+// ─── Public API ───────────────────────────────────────────────────────────────
+function initDesktopDb(dbPath = getDesktopDbPath()) {
+    const dir = path_1.default.dirname(dbPath);
+    fs_1.default.mkdirSync(dir, { recursive: true });
+    if (dbPath !== ':memory:')
+        (0, secure_fs_1.secureDir)(dir); // H-13: owner-only ~/.specrails
+    // Rebrand compat: pick up a pre-rename hub.sqlite before opening.
+    migrateLegacyDbFile(dbPath);
+    const db = new better_sqlite3_1.default(dbPath);
+    db.pragma('journal_mode = WAL');
+    db.pragma('foreign_keys = ON');
+    applyDesktopMigrations(db);
+    // H-13: desktop.sqlite stores webhook HMAC secrets in plaintext — restrict it
+    // (and its WAL sidecars) to owner read/write.
+    if (dbPath !== ':memory:')
+        (0, secure_fs_1.secureDbFile)(dbPath);
+    return db;
+}
+function listProjects(db) {
+    return db.prepare('SELECT * FROM projects ORDER BY added_at ASC').all().map((r) => mapProjectRow(r));
+}
+function getProject(db, id) {
+    return mapProjectRow(db.prepare('SELECT * FROM projects WHERE id = ?').get(id));
+}
+function getProjectBySlug(db, slug) {
+    return mapProjectRow(db.prepare('SELECT * FROM projects WHERE slug = ?').get(slug));
+}
+function getProjectByPath(db, projectPath) {
+    return mapProjectRow(db.prepare('SELECT * FROM projects WHERE path = ?').get(projectPath));
+}
+function addProject(db, project) {
+    const dbPath = getProjectDbPath(project.slug);
+    const providers = project.providers && project.providers.length > 0
+        ? project.providers
+        : [project.provider ?? 'claude'];
+    // Primary provider = explicit override, else the first selected provider.
+    const provider = project.provider ?? providers[0];
+    db.prepare(`
+    INSERT INTO projects (id, slug, name, path, db_path, provider, providers)
+    VALUES (?, ?, ?, ?, ?, ?, ?)
+  `).run(project.id, project.slug, project.name, project.path, dbPath, provider, JSON.stringify(providers));
+    return getProject(db, project.id);
+}
+function removeProject(db, id) {
+    db.prepare('DELETE FROM projects WHERE id = ?').run(id);
+}
+function touchProject(db, id) {
+    db.prepare("UPDATE projects SET last_seen_at = datetime('now') WHERE id = ?").run(id);
+}
+function getDesktopSetting(db, key) {
+    const row = db.prepare('SELECT value FROM desktop_settings WHERE key = ?').get(key);
+    return row?.value;
+}
+function setDesktopSetting(db, key, value) {
+    db.prepare('INSERT OR REPLACE INTO desktop_settings (key, value) VALUES (?, ?)').run(key, value);
+}
+// ─── Setup session persistence ────────────────────────────────────────────────
+function setProjectSetupSession(db, projectId, sessionId) {
+    setDesktopSetting(db, `setup_session:${projectId}`, sessionId);
+}
+function getProjectSetupSession(db, projectId) {
+    return getDesktopSetting(db, `setup_session:${projectId}`);
+}
+function clearProjectSetupSession(db, projectId) {
+    db.prepare('DELETE FROM desktop_settings WHERE key = ?').run(`setup_session:${projectId}`);
+}
+// ─── Agent CRUD ───────────────────────────────────────────────────────────────
+function listAgents(db) {
+    return db.prepare('SELECT * FROM agents ORDER BY created_at ASC').all();
+}
+function getAgent(db, id) {
+    return db.prepare('SELECT * FROM agents WHERE id = ?').get(id);
+}
+function getAgentBySlug(db, slug) {
+    return db.prepare('SELECT * FROM agents WHERE slug = ?').get(slug);
+}
+function addAgent(db, agent) {
+    db.prepare(`
+    INSERT INTO agents (id, slug, name, role, config)
+    VALUES (?, ?, ?, ?, ?)
+  `).run(agent.id, agent.slug, agent.name, agent.role ?? null, agent.config ?? null);
+    return db.prepare('SELECT * FROM agents WHERE id = ?').get(agent.id);
+}
+// B72: column names are interpolated into the SET clause below. TS restricts the
+// keys at compile time, but a runtime caller passing an attacker-influenced
+// object would otherwise inject SQL via the key. Gate on an explicit allow-list.
+const UPDATABLE_AGENT_COLUMNS = new Set([
+    'name', 'role', 'status', 'current_job_id', 'last_heartbeat_at', 'config',
+]);
+function updateAgent(db, id, updates) {
+    const fields = Object.keys(updates)
+        .filter((f) => UPDATABLE_AGENT_COLUMNS.has(f));
+    if (fields.length === 0)
+        return getAgent(db, id);
+    const setClauses = fields.map((f) => `${f} = ?`).join(', ');
+    const values = fields.map((f) => updates[f] ?? null);
+    db.prepare(`UPDATE agents SET ${setClauses} WHERE id = ?`).run(...values, id);
+    return db.prepare('SELECT * FROM agents WHERE id = ?').get(id);
+}
+function findAgentByCurrentJobId(db, jobId) {
+    return db.prepare('SELECT * FROM agents WHERE current_job_id = ?').get(jobId);
+}
+function clearAgentJob(db, jobId) {
+    db.prepare("UPDATE agents SET status = 'idle', current_job_id = NULL WHERE current_job_id = ? AND status != 'idle'").run(jobId);
+}
+function listWebhooks(db) {
+    return db.prepare('SELECT * FROM webhooks ORDER BY created_at ASC').all();
+}
+function listWebhooksForProject(db, projectId) {
+    return db.prepare('SELECT * FROM webhooks WHERE enabled = 1 AND (project_id IS NULL OR project_id = ?) ORDER BY created_at ASC').all(projectId);
+}
+function getWebhook(db, id) {
+    return db.prepare('SELECT * FROM webhooks WHERE id = ?').get(id);
+}
+function addWebhook(db, webhook) {
+    const events = JSON.stringify(webhook.events ?? ['job.completed', 'job.failed']);
+    db.prepare(`
+    INSERT INTO webhooks (id, project_id, url, secret, events)
+    VALUES (?, ?, ?, ?, ?)
+  `).run(webhook.id, webhook.projectId ?? null, webhook.url, webhook.secret ?? '', events);
+    return db.prepare('SELECT * FROM webhooks WHERE id = ?').get(webhook.id);
+}
+function updateWebhook(db, id, updates) {
+    const fields = [];
+    const values = [];
+    if (updates.url !== undefined) {
+        fields.push('url = ?');
+        values.push(updates.url);
+    }
+    if (updates.secret !== undefined) {
+        fields.push('secret = ?');
+        values.push(updates.secret);
+    }
+    if (updates.events !== undefined) {
+        fields.push('events = ?');
+        values.push(JSON.stringify(updates.events));
+    }
+    if (updates.enabled !== undefined) {
+        fields.push('enabled = ?');
+        values.push(updates.enabled ? 1 : 0);
+    }
+    if (fields.length === 0)
+        return getWebhook(db, id);
+    fields.push("updated_at = datetime('now')");
+    db.prepare(`UPDATE webhooks SET ${fields.join(', ')} WHERE id = ?`).run(...values, id);
+    return db.prepare('SELECT * FROM webhooks WHERE id = ?').get(id);
+}
+function removeWebhook(db, id) {
+    db.prepare('DELETE FROM webhooks WHERE id = ?').run(id);
+}