astrocode-workflow 0.4.0 → 0.4.2

package/dist/src/state/repo-lock.js

@@ -0,0 +1,580 @@
+// src/state/repo-lock.ts
+import fs from "node:fs";
+import path from "node:path";
+import crypto from "node:crypto";
+const LOCK_VERSION = 2;
+// Process-stable identifier for this Node process instance.
+const PROCESS_INSTANCE_ID = crypto.randomUUID();
+// Hard guardrails against garbage/corruption.
+const MAX_LOCK_BYTES = 64 * 1024; // 64KB; lock file should be tiny.
+// How many times we’ll attempt "atomic-ish replace" before giving up.
+const ATOMIC_REPLACE_RETRIES = 3;
+function nowISO() {
+    return new Date().toISOString();
+}
+function sleep(ms) {
+    return new Promise((r) => setTimeout(r, ms));
+}
+/**
+ * PID existence check:
+ * - EPERM => process exists but we can't signal it (treat as alive)
+ * - ESRCH => process does not exist (dead)
+ */
+function isPidAlive(pid) {
+    try {
+        process.kill(pid, 0);
+        return true;
+    }
+    catch (err) {
+        const code = err?.code;
+        if (code === "EPERM")
+            return true;
+        if (code === "ESRCH")
+            return false;
+        // Unknown: conservative = don't evict.
+        return true;
+    }
+}
+function parseISOToMs(iso) {
+    const t = Date.parse(iso);
+    if (Number.isNaN(t))
+        return null;
+    return t;
+}
+function isStaleByAge(existing, staleMs) {
+    const updatedMs = parseISOToMs(existing.updated_at);
+    if (updatedMs === null)
+        return true;
+    return Date.now() - updatedMs > staleMs;
+}
+function safeUnlink(p) {
+    try {
+        fs.unlinkSync(p);
+    }
+    catch {
+        // ignore
+    }
+}
+/**
+ * Reads & validates lock file defensively.
+ * Supports both v2 JSON format and legacy PID-only format for compatibility.
+ * Returns null on any parse/validation failure.
+ */
+function readLock(lockPath) {
+    try {
+        const st = fs.statSync(lockPath);
+        if (!st.isFile())
+            return null;
+        if (st.size <= 0 || st.size > MAX_LOCK_BYTES)
+            return null;
+        const raw = fs.readFileSync(lockPath, "utf8").trim();
+        // Try v2 JSON first
+        try {
+            const parsed = JSON.parse(raw);
+            if (parsed && typeof parsed === "object" && parsed.v === LOCK_VERSION) {
+                if (typeof parsed.pid !== "number")
+                    return null;
+                if (typeof parsed.created_at !== "string")
+                    return null;
+                if (typeof parsed.updated_at !== "string")
+                    return null;
+                if (typeof parsed.repo_root !== "string")
+                    return null;
+                if (typeof parsed.instance_id !== "string")
+                    return null;
+                if (typeof parsed.lease_id !== "string")
+                    return null;
+                if (parsed.session_id !== undefined && typeof parsed.session_id !== "string")
+                    return null;
+                if (parsed.owner !== undefined && typeof parsed.owner !== "string")
+                    return null;
+                return parsed;
+            }
+        }
+        catch {
+            // Not JSON, try legacy format
+        }
+        // Legacy format: just PID as number string
+        const legacyPid = parseInt(raw, 10);
+        if (Number.isNaN(legacyPid) || legacyPid <= 0)
+            return null;
+        // Convert legacy to v2 format
+        const now = nowISO();
+        const leaseId = crypto.randomUUID();
+        return {
+            v: LOCK_VERSION,
+            pid: legacyPid,
+            created_at: now, // Approximate
+            updated_at: now,
+            repo_root: "", // Unknown, will be filled by caller
+            instance_id: PROCESS_INSTANCE_ID, // Assume same instance
+            session_id: undefined,
+            lease_id: leaseId,
+            owner: "legacy-lock",
+        };
+    }
+    catch {
+        return null;
+    }
+}
+/**
+ * Best-effort directory fsync:
+ * Helps durability on crash for some filesystems (mostly POSIX).
+ * On platforms where opening a directory fails, we ignore.
+ */
+function fsyncDirBestEffort(dirPath) {
+    try {
+        const fd = fs.openSync(dirPath, "r");
+        try {
+            fs.fsyncSync(fd);
+        }
+        finally {
+            fs.closeSync(fd);
+        }
+    }
+    catch {
+        // ignore (not portable)
+    }
+}
+/**
+ * "Atomic-ish" replace:
+ * - Write temp file
+ * - Try rename over target (POSIX generally atomic)
+ * - Windows can fail if target exists/locked; fallback to unlink+rename (not atomic, but best-effort)
+ * - Best-effort directory fsync after rename
+ */
+function writeLockAtomicish(lockPath, lock) {
+    const dir = path.dirname(lockPath);
+    fs.mkdirSync(dir, { recursive: true });
+    const tmp = `${lockPath}.${process.pid}.${Date.now()}.${crypto.randomUUID()}.tmp`;
+    const body = JSON.stringify(lock); // compact JSON to reduce IO
+    fs.writeFileSync(tmp, body, "utf8");
+    let lastErr = null;
+    for (let i = 0; i < ATOMIC_REPLACE_RETRIES; i++) {
+        try {
+            fs.renameSync(tmp, lockPath);
+            fsyncDirBestEffort(dir);
+            return;
+        }
+        catch (err) {
+            lastErr = err;
+            const code = err?.code;
+            // Common Windows-ish cases where rename over existing fails.
+            if (code === "EEXIST" || code === "EPERM" || code === "ENOTEMPTY") {
+                safeUnlink(lockPath);
+                continue;
+            }
+            // If tmp vanished somehow, stop.
+            if (code === "ENOENT")
+                break;
+            continue;
+        }
+    }
+    safeUnlink(tmp);
+    if (lastErr)
+        throw lastErr;
+    throw new Error(`Failed to replace lock file: ${lockPath}`);
+}
+/**
+ * Atomic "create if not exists" using exclusive open.
+ */
+function tryCreateExclusiveFile(filePath, contentsUtf8) {
+    fs.mkdirSync(path.dirname(filePath), { recursive: true });
+    try {
+        const fd = fs.openSync(filePath, "wx");
+        try {
+            fs.writeFileSync(fd, contentsUtf8, "utf8");
+            fs.fsyncSync(fd);
+        }
+        finally {
+            fs.closeSync(fd);
+        }
+        fsyncDirBestEffort(path.dirname(filePath));
+        return true;
+    }
+    catch (err) {
+        if (err?.code === "EEXIST")
+            return false;
+        throw err;
+    }
+}
+function tryCreateRepoLockExclusive(lockPath, lock) {
+    return tryCreateExclusiveFile(lockPath, JSON.stringify(lock));
+}
+const ACTIVE_LOCKS = new Map();
+function cacheKey(lockPath, sessionId) {
+    return `${lockPath}::${sessionId ?? ""}`;
+}
+/**
+ * Heartbeat loop:
+ * - setTimeout (not setInterval) to avoid backlog drift under load
+ * - Minimizes writes by enforcing minWriteMs
+ * - ABA-safe: only refreshes if lock matches our lease_id and process identity
+ * - Avoids unnecessary writes if lock already has a recent updated_at
+ */
+function startHeartbeat(opts) {
+    let stopped = false;
+    let lastWriteAt = 0;
+    let timer = null;
+    const tick = () => {
+        if (stopped)
+            return;
+        const now = Date.now();
+        const shouldAttempt = now - lastWriteAt >= opts.minWriteMs;
+        if (shouldAttempt) {
+            try {
+                const existing = readLock(opts.lockPath);
+                if (existing &&
+                    existing.lease_id === opts.leaseId &&
+                    existing.pid === process.pid &&
+                    existing.instance_id === PROCESS_INSTANCE_ID) {
+                    const updatedMs = parseISOToMs(existing.updated_at);
+                    const isFresh = updatedMs !== null && now - updatedMs < opts.minWriteMs;
+                    if (!isFresh) {
+                        writeLockAtomicish(opts.lockPath, {
+                            ...existing,
+                            updated_at: nowISO(),
+                            repo_root: opts.repoRoot,
+                            session_id: opts.sessionId ?? existing.session_id,
+                            owner: opts.owner ?? existing.owner,
+                        });
+                        lastWriteAt = now;
+                    }
+                    else {
+                        lastWriteAt = now;
+                    }
+                }
+            }
+            catch (err) {
+                // Heartbeat write failed - don't propagate, just reschedule
+                // Lock will become stale if heartbeat continues failing
+                // eslint-disable-next-line no-console
+                console.warn("[Astrocode] Heartbeat write error:", err);
+            }
+        }
+        timer = setTimeout(tick, opts.heartbeatMs);
+        timer.unref?.();
+    };
+    tick();
+    return () => {
+        stopped = true;
+        if (timer)
+            clearTimeout(timer);
+    };
+}
+/**
+ * Shutdown cleanup:
+ * Best-effort release on normal termination signals.
+ */
+let EXIT_HOOK_INSTALLED = false;
+function installExitHookOnce() {
+    if (EXIT_HOOK_INSTALLED)
+        return;
+    EXIT_HOOK_INSTALLED = true;
+    const cleanup = () => {
+        for (const [key, h] of ACTIVE_LOCKS.entries()) {
+            try {
+                ACTIVE_LOCKS.delete(key);
+                h.heartbeatStop();
+                h.releaseOnce();
+            }
+            catch {
+                // ignore
+            }
+        }
+    };
+    process.once("exit", cleanup);
+    process.once("SIGINT", () => {
+        cleanup();
+        process.exit(130);
+    });
+    process.once("SIGTERM", () => {
+        cleanup();
+        process.exit(143);
+    });
+    process.once("uncaughtException", (err) => {
+        // eslint-disable-next-line no-console
+        console.error("[Astrocode] Uncaught Exception, cleaning up locks:", err);
+        cleanup();
+        process.exit(1);
+    });
+    process.once("unhandledRejection", (reason) => {
+        // eslint-disable-next-line no-console
+        console.error("[Astrocode] Unhandled Rejection, cleaning up locks:", reason);
+        cleanup();
+        process.exit(1);
+    });
+}
+/**
+ * Acquire a repo-scoped lock with:
+ * - ✅ process-local caching + refcount (efficient repeated tool calls)
+ * - ✅ heartbeat lease + stale recovery
+ * - ✅ atomic create (`wx`) + portable replace fallback
+ * - ✅ dead PID eviction + stale eviction
+ * - ✅ no live takeover (even same session) to avoid concurrency stomps
+ * - ✅ ABA-safe release via lease_id fencing
+ * - ✅ exponential backoff + jitter to reduce FS churn
+ */
+export async function acquireRepoLock(opts) {
+    installExitHookOnce();
+    const { lockPath, repoRoot, sessionId, owner } = opts;
+    const retryMs = opts.retryMs ?? 8000;
+    const pollBaseMs = opts.pollMs ?? 20;
+    const pollMaxMs = opts.pollMaxMs ?? 250;
+    const heartbeatMs = opts.heartbeatMs ?? 200;
+    const minWriteMs = opts.minWriteMs ?? 800;
+    // Ensure stale is comfortably above minWriteMs to prevent false-stale under load.
+    const staleMs = Math.max(opts.staleMs ?? 2 * 60 * 1000, minWriteMs * 8);
+    // ✅ Fast path: reuse cached handle in the same process/session.
+    const key = cacheKey(lockPath, sessionId);
+    const cached = ACTIVE_LOCKS.get(key);
+    if (cached) {
+        cached.refCount += 1;
+        return {
+            release: () => {
+                cached.refCount -= 1;
+                if (cached.refCount <= 0) {
+                    ACTIVE_LOCKS.delete(key);
+                    cached.heartbeatStop();
+                    cached.releaseOnce();
+                }
+            },
+        };
+    }
+    const myPid = process.pid;
+    const startedAt = Date.now();
+    let pollMs = pollBaseMs;
+    while (true) {
+        const existing = readLock(lockPath);
+        // No lock (or unreadable/invalid) -> try create.
+        if (!existing) {
+            const now = nowISO();
+            const leaseId = crypto.randomUUID();
+            const candidate = {
+                v: LOCK_VERSION,
+                pid: myPid,
+                created_at: now,
+                updated_at: now,
+                repo_root: repoRoot,
+                instance_id: PROCESS_INSTANCE_ID,
+                session_id: sessionId,
+                lease_id: leaseId,
+                owner,
+            };
+            const created = tryCreateRepoLockExclusive(lockPath, candidate);
+            if (created) {
+                const heartbeatStop = startHeartbeat({
+                    lockPath,
+                    repoRoot,
+                    sessionId,
+                    owner,
+                    leaseId,
+                    heartbeatMs,
+                    minWriteMs,
+                });
+                const releaseOnce = () => {
+                    const cur = readLock(lockPath);
+                    if (!cur)
+                        return;
+                    // ABA-safe
+                    if (cur.lease_id !== leaseId)
+                        return;
+                    // Strict identity: only exact process instance can delete.
+                    if (cur.pid !== myPid)
+                        return;
+                    if (cur.instance_id !== PROCESS_INSTANCE_ID)
+                        return;
+                    safeUnlink(lockPath);
+                    fsyncDirBestEffort(path.dirname(lockPath));
+                };
+                const handle = {
+                    key,
+                    lockPath,
+                    sessionId,
+                    leaseId,
+                    refCount: 1,
+                    heartbeatStop,
+                    releaseOnce,
+                };
+                ACTIVE_LOCKS.set(key, handle);
+                return {
+                    release: () => {
+                        const h = ACTIVE_LOCKS.get(key);
+                        if (!h)
+                            return;
+                        h.refCount -= 1;
+                        if (h.refCount <= 0) {
+                            ACTIVE_LOCKS.delete(key);
+                            h.heartbeatStop();
+                            h.releaseOnce();
+                        }
+                    },
+                };
+            }
+            // Race lost; reset backoff and loop.
+            pollMs = pollBaseMs;
+            continue;
+        }
+        // Re-entrant by SAME PROCESS IDENTITY (pid+instance), or legacy lock with same PID.
+        if (existing.pid === myPid && (existing.instance_id === PROCESS_INSTANCE_ID || existing.owner === "legacy-lock")) {
+            const leaseId = crypto.randomUUID();
+            writeLockAtomicish(lockPath, {
+                ...existing,
+                v: LOCK_VERSION,
+                updated_at: nowISO(),
+                repo_root: repoRoot,
+                instance_id: PROCESS_INSTANCE_ID, // Upgrade legacy
+                session_id: sessionId ?? existing.session_id,
+                owner: owner ?? existing.owner,
+                lease_id: leaseId,
+            });
+            const heartbeatStop = startHeartbeat({
+                lockPath,
+                repoRoot,
+                sessionId: sessionId ?? existing.session_id,
+                owner: owner ?? existing.owner,
+                leaseId,
+                heartbeatMs,
+                minWriteMs,
+            });
+            const releaseOnce = () => {
+                const cur = readLock(lockPath);
+                if (!cur)
+                    return;
+                if (cur.lease_id !== leaseId)
+                    return;
+                if (cur.pid !== myPid)
+                    return;
+                if (cur.instance_id !== PROCESS_INSTANCE_ID)
+                    return;
+                safeUnlink(lockPath);
+                fsyncDirBestEffort(path.dirname(lockPath));
+            };
+            const handle = {
+                key,
+                lockPath,
+                sessionId,
+                leaseId,
+                refCount: 1,
+                heartbeatStop,
+                releaseOnce,
+            };
+            ACTIVE_LOCKS.set(key, handle);
+            return {
+                release: () => {
+                    const h = ACTIVE_LOCKS.get(key);
+                    if (!h)
+                        return;
+                    h.refCount -= 1;
+                    if (h.refCount <= 0) {
+                        ACTIVE_LOCKS.delete(key);
+                        h.heartbeatStop();
+                        h.releaseOnce();
+                    }
+                },
+            };
+        }
+        // 🚫 No live takeover (even same session).
+        // We only evict dead/stale locks.
+        const pidAlive = isPidAlive(existing.pid);
+        const staleByAge = isStaleByAge(existing, staleMs);
+        if (!pidAlive || staleByAge) {
+            safeUnlink(lockPath);
+            fsyncDirBestEffort(path.dirname(lockPath));
+            pollMs = pollBaseMs;
+            continue;
+        }
+        // Alive and not us -> bounded wait with exponential backoff + jitter.
+        if (Date.now() - startedAt > retryMs) {
+            const ownerBits = [
+                `pid=${existing.pid}`,
+                existing.session_id ? `session=${existing.session_id}` : null,
+                existing.owner ? `owner=${existing.owner}` : null,
+                `updated_at=${existing.updated_at}`,
+                sessionId && existing.session_id === sessionId ? `(same-session waiting)` : null,
+            ]
+                .filter(Boolean)
+                .join(" ");
+            throw new Error(`Astrocode lock is already held (${lockPath}). ${ownerBits}. ` +
+                `Close other opencode processes or wait.`);
+        }
+        const jitter = Math.floor(Math.random() * Math.min(12, pollMs));
+        await sleep(pollMs + jitter);
+        pollMs = Math.min(pollMaxMs, Math.floor(pollMs * 1.35));
+    }
+}
+/**
+ * Helper wrapper: always releases lock.
+ */
+export async function withRepoLock(opts) {
+    const handle = await acquireRepoLock({
+        lockPath: opts.lockPath,
+        repoRoot: opts.repoRoot,
+        sessionId: opts.sessionId,
+        owner: opts.owner,
+    });
+    try {
+        return await opts.fn();
+    }
+    finally {
+        handle.release();
+    }
+}
+/**
+ * Get lock file status and diagnostics.
+ * Returns detailed information about the current lock state.
+ */
+export function getLockStatus(lockPath, staleMs = 30_000) {
+    const existing = readLock(lockPath);
+    if (!existing) {
+        return {
+            exists: false,
+            path: lockPath,
+        };
+    }
+    const updatedMs = parseISOToMs(existing.updated_at);
+    const ageMs = updatedMs !== null ? Date.now() - updatedMs : undefined;
+    const pidAlive = isPidAlive(existing.pid);
+    const isStale = isStaleByAge(existing, staleMs);
+    return {
+        exists: true,
+        path: lockPath,
+        pid: existing.pid,
+        pidAlive,
+        instanceId: existing.instance_id,
+        sessionId: existing.session_id,
+        owner: existing.owner,
+        leaseId: existing.lease_id,
+        createdAt: existing.created_at,
+        updatedAt: existing.updated_at,
+        ageMs,
+        isStale,
+        repoRoot: existing.repo_root,
+        version: existing.v,
+    };
+}
+/**
+ * Attempt to remove a lock file if it's safe to do so.
+ * Only removes locks with dead PIDs or stale timestamps.
+ * Returns true if lock was removed, false if lock is still held.
+ */
+export function tryRemoveStaleLock(lockPath, staleMs = 30_000) {
+    const existing = readLock(lockPath);
+    if (!existing) {
+        return { removed: false, reason: "No lock file found" };
+    }
+    const pidAlive = isPidAlive(existing.pid);
+    const isStale = isStaleByAge(existing, staleMs);
+    if (!pidAlive) {
+        safeUnlink(lockPath);
+        fsyncDirBestEffort(path.dirname(lockPath));
+        return { removed: true, reason: `Dead PID ${existing.pid}` };
+    }
+    if (isStale) {
+        safeUnlink(lockPath);
+        fsyncDirBestEffort(path.dirname(lockPath));
+        const ageSeconds = Math.floor((Date.now() - (parseISOToMs(existing.updated_at) ?? 0)) / 1000);
+        return { removed: true, reason: `Stale lock (${ageSeconds}s old, threshold ${staleMs / 1000}s)` };
+    }
+    return { removed: false, reason: `Lock is active (PID ${existing.pid} alive, age ${Math.floor((Date.now() - (parseISOToMs(existing.updated_at) ?? 0)) / 1000)}s)` };
+}

package/dist/src/state/schema.d.ts

@@ -0,0 +1,2 @@
+export declare const SCHEMA_VERSION = 3;
+export declare const SCHEMA_SQL = "\nPRAGMA foreign_keys = ON;\n\nCREATE TABLE IF NOT EXISTS repo_state (\n  id INTEGER PRIMARY KEY CHECK (id = 1),\n  schema_version INTEGER NOT NULL,\n  created_at TEXT NOT NULL,\n  updated_at TEXT NOT NULL,\n  spec_hash_before TEXT,\n  spec_hash_after TEXT,\n  last_run_id TEXT,\n  last_story_key TEXT,\n  last_event_at TEXT\n);\n\nCREATE TABLE IF NOT EXISTS settings (\n  key TEXT PRIMARY KEY,\n  value TEXT NOT NULL,\n  updated_at TEXT NOT NULL\n);\n\nCREATE TABLE IF NOT EXISTS epics (\n  epic_key TEXT PRIMARY KEY,\n  title TEXT NOT NULL,\n  body_md TEXT NOT NULL DEFAULT '',\n  state TEXT NOT NULL DEFAULT 'active',\n  priority INTEGER NOT NULL DEFAULT 0,\n  created_at TEXT NOT NULL,\n  updated_at TEXT NOT NULL\n);\n\nCREATE TABLE IF NOT EXISTS story_drafts (\n  draft_id TEXT PRIMARY KEY,\n  title TEXT NOT NULL,\n  body_md TEXT NOT NULL DEFAULT '',\n  meta_json TEXT NOT NULL DEFAULT '{}',\n  created_at TEXT NOT NULL,\n  updated_at TEXT NOT NULL\n);\n\nCREATE TABLE IF NOT EXISTS story_keyseq (\n  id INTEGER PRIMARY KEY CHECK (id = 1),\n  next_story_num INTEGER NOT NULL\n);\n\nCREATE TABLE IF NOT EXISTS stories (\n  story_key TEXT PRIMARY KEY,\n  epic_key TEXT,\n  title TEXT NOT NULL,\n  body_md TEXT NOT NULL DEFAULT '',\n  state TEXT NOT NULL DEFAULT 'queued', -- queued|approved|in_progress|done|blocked|archived\n  priority INTEGER NOT NULL DEFAULT 0,\n  approved_at TEXT,\n  locked_by_run_id TEXT,\n  locked_at TEXT,\n  in_progress INTEGER NOT NULL DEFAULT 0,\n  created_at TEXT NOT NULL,\n  updated_at TEXT NOT NULL,\n  FOREIGN KEY (epic_key) REFERENCES epics(epic_key)\n);\n\nCREATE TABLE IF NOT EXISTS runs (\n  run_id TEXT PRIMARY KEY,\n  story_key TEXT NOT NULL,\n  status TEXT NOT NULL DEFAULT 'created', -- created|running|completed|failed|aborted\n  pipeline_stages_json TEXT NOT NULL DEFAULT '[]',\n  current_stage_key TEXT,\n  created_at TEXT NOT NULL,\n  started_at TEXT,\n  completed_at TEXT,\n  updated_at TEXT NOT NULL,\n  error_text TEXT,\n  FOREIGN KEY (story_key) REFERENCES stories(story_key)\n);\n\nCREATE TABLE IF NOT EXISTS stage_runs (\n  stage_run_id TEXT PRIMARY KEY,\n  run_id TEXT NOT NULL,\n  stage_key TEXT NOT NULL,\n  stage_index INTEGER NOT NULL,\n  status TEXT NOT NULL DEFAULT 'pending', -- pending|running|completed|failed|skipped\n  created_at TEXT NOT NULL,\n  subagent_type TEXT,\n  subagent_session_id TEXT,\n  started_at TEXT,\n  completed_at TEXT,\n  updated_at TEXT NOT NULL,\n  baton_path TEXT,\n  summary_md TEXT,\n  output_json TEXT,\n  error_text TEXT,\n  FOREIGN KEY (run_id) REFERENCES runs(run_id)\n);\n\nCREATE TABLE IF NOT EXISTS artifacts (\n  artifact_id TEXT PRIMARY KEY,\n  run_id TEXT,\n  stage_key TEXT,\n  type TEXT NOT NULL, -- plan|baton|evidence|diff|log|summary|commit|tool_output|snapshot\n  path TEXT NOT NULL,\n  sha256 TEXT,\n  meta_json TEXT NOT NULL DEFAULT '{}',\n  created_at TEXT NOT NULL,\n  FOREIGN KEY (run_id) REFERENCES runs(run_id)\n);\n\nCREATE TABLE IF NOT EXISTS tool_runs (\n  tool_run_id TEXT PRIMARY KEY,\n  run_id TEXT,\n  stage_key TEXT,\n  tool_name TEXT NOT NULL,\n  args_json TEXT NOT NULL DEFAULT '{}',\n  output_summary TEXT NOT NULL DEFAULT '',\n  output_artifact_id TEXT,\n  created_at TEXT NOT NULL,\n  FOREIGN KEY (run_id) REFERENCES runs(run_id)\n);\n\nCREATE TABLE IF NOT EXISTS events (\n  event_id TEXT PRIMARY KEY,\n  run_id TEXT,\n  stage_key TEXT,\n  type TEXT NOT NULL,\n  body_json TEXT NOT NULL DEFAULT '{}',\n  created_at TEXT NOT NULL,\n  FOREIGN KEY (run_id) REFERENCES runs(run_id)\n);\n\nCREATE TABLE IF NOT EXISTS injects (\n  inject_id TEXT PRIMARY KEY,\n  type TEXT NOT NULL DEFAULT 'note',\n  title TEXT NOT NULL,\n  body_md TEXT NOT NULL,\n  tags_json TEXT NOT NULL DEFAULT '[]',\n  scope TEXT NOT NULL DEFAULT 'repo', -- repo|run:<id>|story:<key>|global\n  source TEXT NOT NULL DEFAULT 'user', -- user|tool|agent|import\n  priority INTEGER NOT NULL DEFAULT 50,\n  expires_at TEXT,\n  sha256 TEXT,\n  created_at TEXT NOT NULL,\n  updated_at TEXT NOT NULL\n);\n\nCREATE TABLE IF NOT EXISTS running_batches (\n  batch_id TEXT PRIMARY KEY,\n  run_id TEXT,\n  session_id TEXT,\n  status TEXT NOT NULL DEFAULT 'running', -- running|completed|failed|aborted\n  created_at TEXT NOT NULL,\n  updated_at TEXT NOT NULL,\n  FOREIGN KEY (run_id) REFERENCES runs(run_id)\n);\n\nCREATE TABLE IF NOT EXISTS workflow_metrics (\n  metric_id TEXT PRIMARY KEY,\n  run_id TEXT,\n  stage_key TEXT,\n  name TEXT NOT NULL,\n  value_num REAL,\n  value_text TEXT,\n  created_at TEXT NOT NULL,\n  FOREIGN KEY (run_id) REFERENCES runs(run_id)\n);\n\nCREATE TABLE IF NOT EXISTS template_intents (\n  intent_key TEXT PRIMARY KEY,\n  body_md TEXT NOT NULL,\n  updated_at TEXT NOT NULL\n);\n\n-- vNext tables\n\nCREATE TABLE IF NOT EXISTS story_relations (\n  parent_story_key TEXT NOT NULL,\n  child_story_key TEXT NOT NULL,\n  relation_type TEXT NOT NULL DEFAULT 'split',\n  reason TEXT NOT NULL DEFAULT '',\n  created_at TEXT NOT NULL,\n  PRIMARY KEY (parent_story_key, child_story_key),\n  FOREIGN KEY (parent_story_key) REFERENCES stories(story_key),\n  FOREIGN KEY (child_story_key) REFERENCES stories(story_key)\n);\n\nCREATE TABLE IF NOT EXISTS continuations (\n  continuation_id INTEGER PRIMARY KEY AUTOINCREMENT,\n  session_id TEXT NOT NULL,\n  run_id TEXT,\n  directive_hash TEXT NOT NULL,\n  kind TEXT NOT NULL, -- continue|stage|blocked|repair\n  reason TEXT NOT NULL DEFAULT '',\n  created_at TEXT NOT NULL,\n  FOREIGN KEY (run_id) REFERENCES runs(run_id)\n);\n\nCREATE INDEX IF NOT EXISTS idx_continuations_session_created ON continuations(session_id, created_at DESC);\nCREATE INDEX IF NOT EXISTS idx_continuations_run_created ON continuations(run_id, created_at DESC);\n\nCREATE TABLE IF NOT EXISTS context_snapshots (\n  snapshot_id TEXT PRIMARY KEY,\n  run_id TEXT NOT NULL,\n  stage_key TEXT NOT NULL,\n  summary_md TEXT NOT NULL,\n  created_at TEXT NOT NULL,\n  FOREIGN KEY (run_id) REFERENCES runs(run_id)\n);\n\nCREATE INDEX IF NOT EXISTS idx_context_snapshots_run_created ON context_snapshots(run_id, created_at DESC);\n\nCREATE TABLE IF NOT EXISTS agent_sessions (\n  session_id TEXT PRIMARY KEY,\n  parent_session_id TEXT,\n  agent_name TEXT NOT NULL,\n  run_id TEXT,\n  stage_key TEXT,\n  status TEXT NOT NULL DEFAULT 'active',\n  created_at TEXT NOT NULL,\n  updated_at TEXT NOT NULL\n);\n\n-- Indexes\n\nCREATE INDEX IF NOT EXISTS idx_stories_state ON stories(state);\nCREATE INDEX IF NOT EXISTS idx_runs_story ON runs(story_key);\nCREATE INDEX IF NOT EXISTS idx_runs_status ON runs(status);\nCREATE INDEX IF NOT EXISTS idx_stage_runs_run ON stage_runs(run_id, stage_index);\nCREATE INDEX IF NOT EXISTS idx_artifacts_run_stage ON artifacts(run_id, stage_key, created_at DESC);\nCREATE INDEX IF NOT EXISTS idx_events_run ON events(run_id, created_at DESC);\nCREATE INDEX IF NOT EXISTS idx_tool_runs_run ON tool_runs(run_id, created_at DESC);\nCREATE INDEX IF NOT EXISTS idx_injects_scope_priority ON injects(scope, priority DESC, created_at DESC);\n\n-- CONSTRAINT: Only one running run at a time (partial unique index)\n-- This provides database-level safety when using advisory locks\nCREATE UNIQUE INDEX IF NOT EXISTS idx_single_running_run ON runs(status) WHERE status = 'running';\n\n-- CONSTRAINT: Only one run can lock a story at a time (partial unique index)\nCREATE UNIQUE INDEX IF NOT EXISTS idx_single_story_lock ON stories(in_progress) WHERE in_progress = 1;\nCREATE INDEX IF NOT EXISTS idx_injects_scope_type_priority_updated ON injects(scope, type, priority DESC, updated_at DESC);\nCREATE INDEX IF NOT EXISTS idx_injects_expires ON injects(expires_at) WHERE expires_at IS NOT NULL;\nCREATE INDEX IF NOT EXISTS idx_injects_sha256 ON injects(sha256) WHERE sha256 IS NOT NULL;\n\n-- Stronger invariants (SQLite partial indexes)\n-- Only one run may be 'running' at a time (single-repo harness by default).\nCREATE UNIQUE INDEX IF NOT EXISTS uniq_single_running_run\n  ON runs(status)\n  WHERE status = 'running';\n\n-- Only one story may be in_progress=1 at a time (pairs with single running run).\nCREATE UNIQUE INDEX IF NOT EXISTS uniq_single_in_progress_story\n  ON stories(in_progress)\n  WHERE in_progress = 1;\n\n";