astrocode-workflow 0.1.58 → 0.2.0

package/dist/hooks/tool-output-truncator.js

@@ -13,7 +13,8 @@ function pickMaxChars(toolName, cfg) {
     return cfg.truncation.max_chars_default;
 }
 export function createToolOutputTruncatorHook(opts) {
-    const { ctx, config, db } = opts;
+    const { ctx, config, runtime } = opts;
+    const { db } = runtime;
     return async function toolExecuteAfter(input, output) {
         if (!config.truncation.enabled)
             return;

package/dist/index.js

@@ -1,6 +1,6 @@
 import { loadAstrocodeConfig } from "./config/loader";
 import { createConfigHandler } from "./config/config-handler";
-import { openSqlite, configurePragmas, ensureSchema } from "./state/db";
+import { openSqlite, configurePragmas, ensureSchema, getSchemaVersion } from "./state/db";
 import { getAstroPaths, ensureAstroDirs } from "./shared/paths";
 import { createAstroTools } from "./tools";
 import { createContinuationEnforcer } from "./hooks/continuation-enforcer";
@@ -8,106 +8,289 @@ import { createToolOutputTruncatorHook } from "./hooks/tool-output-truncator";
 import { createInjectProvider } from "./hooks/inject-provider";
 import { createToastManager } from "./ui/toasts";
 import { createAstroAgents } from "./agents/registry";
+import { info, warn } from "./shared/log";
+// Safe config cloning with structuredClone preference (fallback for older Node versions)
+// CONTRACT: Config is guaranteed JSON-serializable (enforced by loadAstrocodeConfig validation)
+const cloneConfig = (v) => {
+    // Prefer structuredClone when available (keeps more types)
+    if (typeof globalThis.structuredClone === "function") {
+        return globalThis.structuredClone(v);
+    }
+    // Fallback: JSON clone (safe since config is validated as JSON-serializable)
+    return JSON.parse(JSON.stringify(v));
+};
+// Minimal config defaults for limited-mode fallback
+const applyMinimalConfigDefaults = (cfg) => {
+    if (!cfg || typeof cfg !== "object")
+        return;
+    if (!Array.isArray(cfg.disabled_hooks))
+        cfg.disabled_hooks = [];
+    if (!cfg.ui || typeof cfg.ui !== "object")
+        cfg.ui = {};
+    if (!cfg.ui.toasts || typeof cfg.ui.toasts !== "object")
+        cfg.ui.toasts = { enabled: false };
+    if (typeof cfg.ui.toasts.enabled !== "boolean")
+        cfg.ui.toasts.enabled = false;
+};
 const Astrocode = async (ctx) => {
+    if (!ctx.directory || typeof ctx.directory !== "string") {
+        throw new Error("Astrocode requires ctx.directory to be a string repo root.");
+    }
     const repoRoot = ctx.directory;
     // Always load config first - this provides defaults even in limited mode
-    let pluginConfig = loadAstrocodeConfig(repoRoot);
-    // Create agents for registration
-    const agents = createAstroAgents({ pluginConfig });
+    let pluginConfig;
+    try {
+        pluginConfig = loadAstrocodeConfig(repoRoot);
+    }
+    catch (e) {
+        warn(`Config loading failed, using minimal defaults.`, { err: e });
+        // Fallback to minimal safe defaults when config loading fails
+        pluginConfig = {
+            disabled_hooks: [],
+            disabled_agents: [],
+            determinism: { mode: "on", strict_stage_order: true },
+            db: {
+                path: ".astro/astro.db",
+                busy_timeout_ms: 5000,
+                pragmas: {},
+                schema_version_required: 2,
+                allow_auto_migrate: true,
+                fail_on_downgrade: true,
+            },
+            ui: {
+                toasts: { enabled: true, throttle_ms: 1500, show_run_started: true, show_stage_started: true, show_stage_completed: true, show_stage_failed: true, show_run_completed: true, show_auto_continue: true },
+            },
+            agents: {
+                orchestrator_name: "Astro",
+                stage_agent_names: { frame: "Frame", plan: "Plan", spec: "Spec", implement: "Implement", review: "Review", verify: "Verify", close: "Close" },
+                librarian_name: "Librarian",
+                explore_name: "Explore",
+                qa_name: "QA",
+                agent_variant_overrides: {},
+            },
+            workflow: {
+                default_mode: "step",
+                default_max_steps: 10,
+                loop_max_steps_hard_cap: 100,
+                evidence_required: { verify: false },
+            },
+            permissions: { enforce_task_tool_restrictions: false, deny_delegate_task_in_subagents: false },
+        };
+    }
     // Always ensure .astro directories exist, even in limited mode
     const paths = getAstroPaths(repoRoot, pluginConfig.db.path);
     ensureAstroDirs(paths);
     let db = null;
-    let tools = null;
-    let configHandler = null;
+    let agents = undefined;
+    let configHandler = async () => {
+        throw new Error("ConfigHandler called before initialization");
+    };
     let continuation = null;
     let truncatorHook = null;
     let injectProvider = null;
-    let toasts = null;
+    let toastManager = null;
+    let limitedModeReason = null;
+    let limitedMode = false;
+    // Phase 1: Database initialization (only DB-related operations)
     try {
         db = openSqlite(paths.dbPath, { busyTimeoutMs: pluginConfig.db.busy_timeout_ms });
         configurePragmas(db, pluginConfig.db.pragmas);
-        ensureSchema(db, { allowAutoMigrate: pluginConfig.db.allow_auto_migrate, failOnDowngrade: pluginConfig.db.fail_on_downgrade });
-        // Database initialized successfully
-        configHandler = createConfigHandler({ pluginConfig });
-        tools = createAstroTools({ ctx, config: pluginConfig, db, agents });
-        continuation = createContinuationEnforcer({ ctx, config: pluginConfig, db });
-        truncatorHook = createToolOutputTruncatorHook({ ctx, config: pluginConfig, db });
-        injectProvider = createInjectProvider({ ctx, config: pluginConfig, db });
-        toasts = createToastManager({ ctx, throttleMs: pluginConfig.ui.toasts.throttle_ms });
+        // Policy enforced in harness; db layer is mechanics only (migration + structural schema creation)
+        ensureSchema(db, { allowAutoMigrate: pluginConfig.db.allow_auto_migrate });
+        // Harness-exclusive: enforce schema version requirement
+        // Explicitly enforce schema version requirement (harness-level policy)
+        const required = pluginConfig.db.schema_version_required;
+        let current = getSchemaVersion(db);
+        if (current < required) {
+            if (!pluginConfig.db.allow_auto_migrate) {
+                // Migration disabled - enter limited mode
+                limitedModeReason = { code: "schema_too_old", details: { current, required } };
+                warn("Entering limited mode (schema too old, migration disabled).", {
+                    dbPath: paths.dbPath,
+                    schemaCurrent: current,
+                    schemaRequired: required,
+                    failOnDowngrade: pluginConfig.db.fail_on_downgrade,
+                    allowAutoMigrate: pluginConfig.db.allow_auto_migrate,
+                });
+                db.close?.();
+                db = null;
+            }
+            else {
+                // Migration allowed - re-run ensureSchema (idempotent) in case first call failed
+                ensureSchema(db, { allowAutoMigrate: true });
+                current = getSchemaVersion(db);
+                if (current < required) {
+                    // Migration failed - enter limited mode
+                    limitedModeReason = { code: "schema_migration_failed", details: { current, required } };
+                    warn("Entering limited mode (schema migration failed).", {
+                        dbPath: paths.dbPath,
+                        schemaCurrent: current,
+                        schemaRequired: required,
+                        failOnDowngrade: pluginConfig.db.fail_on_downgrade,
+                        allowAutoMigrate: pluginConfig.db.allow_auto_migrate,
+                    });
+                    db.close?.();
+                    db = null;
+                }
+            }
+        }
+        else if (current > required && pluginConfig.db.fail_on_downgrade) {
+            limitedModeReason = { code: "schema_downgrade", details: { current, required } };
+            warn("Entering limited mode (schema downgrade).", {
+                dbPath: paths.dbPath,
+                schemaCurrent: current,
+                schemaRequired: required,
+                failOnDowngrade: pluginConfig.db.fail_on_downgrade,
+                allowAutoMigrate: pluginConfig.db.allow_auto_migrate,
+            });
+            db.close?.();
+            db = null;
+        }
     }
     catch (e) {
-        // Database initialization failed - setup limited mode
-        // Reload config to ensure all defaults are present
-        pluginConfig = loadAstrocodeConfig(repoRoot);
-        // Modify config for limited mode
-        pluginConfig.disabled_hooks = [...(pluginConfig.disabled_hooks || []), "continuation-enforcer", "tool-output-truncator"];
-        pluginConfig.ui.toasts.enabled = false;
-        // Create limited functionality
+        // True database initialization failure - enter limited mode
+        warn(`Database initialization failed. Entering limited mode with reduced functionality.`, { err: e });
+        // Clean up partially-opened database connection
+        if (db && typeof db.close === "function") {
+            try {
+                db.close();
+            }
+            catch (closeErr) {
+                // Ignore close errors during cleanup
+            }
+        }
         db = null;
-        configHandler = createConfigHandler({ pluginConfig });
-        tools = createAstroTools({ ctx, config: pluginConfig, db, agents });
+        limitedModeReason = { code: "db_init_failed", details: e };
+    }
+    // Derive limited mode flag once for single source of truth
+    limitedMode = db === null;
+    // Single runtime state object for downstream components
+    const runtime = { db, limitedMode, limitedModeReason };
+    // Phase 2: Component initialization (based on DB availability)
+    if (!limitedMode) {
+        // Normal mode: DB available, create all components
+        try {
+            agents = createAstroAgents({ pluginConfig });
+            // Database initialized successfully
+            info("Database initialized successfully. Plugin ready.");
+            configHandler = createConfigHandler({ pluginConfig });
+            continuation = createContinuationEnforcer({ ctx, config: pluginConfig, runtime });
+            truncatorHook = createToolOutputTruncatorHook({ ctx, config: pluginConfig, runtime });
+            injectProvider = createInjectProvider({ ctx, config: pluginConfig, runtime });
+            toastManager = createToastManager({ ctx, throttleMs: pluginConfig.ui.toasts.throttle_ms });
+        }
+        catch (e) {
+            // Component failure with working DB → fail plugin boot
+            const err = e instanceof Error ? e : new Error(String(e));
+            throw new Error("Plugin initialization failed after successful database setup", { cause: err });
+        }
+    }
+    else {
+        // Limited mode: DB unavailable, create minimal components
+        // Clone the already-loaded config to avoid mutating shared state, then apply limited mode overrides
+        pluginConfig = cloneConfig(pluginConfig);
+        // Apply limited-mode config overrides BEFORE creating any components
+        pluginConfig.disabled_hooks = Array.from(new Set([...(pluginConfig.disabled_hooks || []), "continuation-enforcer", "tool-output-truncator", "inject-provider"]));
+        pluginConfig.ui.toasts.enabled = false;
+        // Show one-shot limited mode notification via logging (keeps toast policy consistent)
+        const reasonMessage = limitedModeReason ?
+            (limitedModeReason.code === "db_init_failed" ? "Database initialization failed. Check native deps or run astro_init." :
+                limitedModeReason.code === "schema_too_old" ? "Database schema too old and migration disabled." :
+                    limitedModeReason.code === "schema_downgrade" ? "Database schema newer than plugin (downgrade detected)." :
+                        limitedModeReason.code === "schema_migration_failed" ? "Database schema migration failed." :
+                            "Database unavailable.") :
+            "Database unavailable.";
+        warn(`Astrocode: Limited Mode - ${reasonMessage}`, { dbPath: paths.dbPath });
+        // Create limited functionality (no global toast manager since toasts are disabled)
+        try {
+            configHandler = createConfigHandler({ pluginConfig });
+        }
+        catch (e) {
+            warn("Limited Mode: config handler unavailable", { err: e });
+            configHandler = async (config) => {
+                applyMinimalConfigDefaults(config);
+            };
+        }
         continuation = null;
         truncatorHook = null;
         injectProvider = null;
-        toasts = null;
+        toastManager = null; // No global toast manager in limited mode
     }
+    // Helper for hook enablement checks (config is now finalized)
+    const hookEnabled = (key) => !pluginConfig.disabled_hooks?.includes(key);
+    // Create tools once with final state (limited mode gets DB-safe tool implementations)
+    const tools = createAstroTools({ ctx, config: pluginConfig, agents, runtime });
     return {
-        name: "Astrocode",
+        name: "astrocode-harness",
         // Register agents
         agents,
         // Merge agents + slash commands into system config
         config: configHandler,
         // Register tools
-        tool: createAstroTools({ ctx, config: pluginConfig, db, agents }),
+        tool: tools,
         // Limit created subagents from spawning more subagents (OMO-style).
         "tool.execute.before": async (input, output) => {
             if (!pluginConfig.permissions.enforce_task_tool_restrictions)
                 return;
-            if (input.tool !== "task")
+            if (input?.tool !== "task")
                 return;
-            output.args = output.args ?? {};
-            const toolsMap = { ...(output.args.tools ?? {}) };
+            const baseArgs = (output && typeof output === "object" ? output.args : undefined) ?? {};
+            const baseTools = (baseArgs && typeof baseArgs === "object" && baseArgs.tools && typeof baseArgs.tools === "object")
+                ? baseArgs.tools
+                : {};
+            const nextTools = { ...baseTools };
             if (pluginConfig.permissions.deny_delegate_task_in_subagents) {
-                toolsMap.delegate_task = false;
+                nextTools.delegate_task = false;
+            }
+            const nextArgs = { ...baseArgs, tools: nextTools };
+            // Back-compat: mutate if possible
+            if (output && typeof output === "object" && !Object.isFrozen(output)) {
+                output.args = nextArgs;
             }
-            output.args.tools = toolsMap;
+            // Forward-compat: return conservative merge
+            if (output && typeof output === "object") {
+                return { ...output, args: nextArgs };
+            }
+            return { args: nextArgs };
         },
         "tool.execute.after": async (input, output) => {
             // Truncate huge tool outputs to artifacts
-            if (truncatorHook && !pluginConfig.disabled_hooks.includes("tool-output-truncator")) {
-                await truncatorHook(input, output);
+            if (truncatorHook && hookEnabled("tool-output-truncator")) {
+                await truncatorHook(input, output ?? null);
             }
             // Schedule continuation (do not immediately spam)
-            if (continuation && !pluginConfig.disabled_hooks.includes("continuation-enforcer")) {
+            if (continuation && hookEnabled("continuation-enforcer")) {
                 await continuation.onToolAfter(input);
             }
+            return output;
         },
         "chat.message": async (input, output) => {
-            if (injectProvider && !pluginConfig.disabled_hooks.includes("inject-provider")) {
+            if (injectProvider && hookEnabled("inject-provider")) {
                 await injectProvider.onChatMessage(input);
             }
-            if (continuation && !pluginConfig.disabled_hooks.includes("continuation-enforcer")) {
+            if (continuation && hookEnabled("continuation-enforcer")) {
                 await continuation.onChatMessage(input);
             }
             return output;
         },
         event: async (input) => {
-            if (continuation && !pluginConfig.disabled_hooks.includes("continuation-enforcer")) {
+            if (continuation && hookEnabled("continuation-enforcer")) {
                 await continuation.onEvent(input);
             }
         },
         // Best-effort cleanup
         close: async () => {
-            try {
-                db.close();
-            }
-            catch {
-                // ignore
+            if (db && typeof db.close === "function") {
+                try {
+                    db.close();
+                }
+                catch {
+                    // ignore
+                }
             }
-            if (toasts && pluginConfig.ui.toasts.enabled) {
+            if (toastManager && pluginConfig.ui.toasts.enabled) {
                 try {
-                    await toasts.show({ title: "Astrocode", message: "Plugin closed", variant: "info" });
+                    await toastManager.show({ title: "Astrocode", message: "Plugin closed", variant: "info" });
                 }
                 catch {
                     // ignore

package/dist/state/adapters/index.d.ts

@@ -18,9 +18,11 @@ export interface DatabaseAdapter {
         busyTimeoutMs?: number;
     }): DatabaseConnection;
 }
-export declare class MockDatabaseAdapter implements DatabaseAdapter {
+export declare class NullAdapter implements DatabaseAdapter {
     isAvailable(): boolean;
-    open(): DatabaseConnection;
+    open(path: string, opts?: {
+        busyTimeoutMs?: number;
+    }): DatabaseConnection;
 }
 export declare class BunSqliteAdapter implements DatabaseAdapter {
     isAvailable(): boolean;

package/dist/state/adapters/index.js

@@ -1,21 +1,10 @@
-import { warn } from "../../shared/log";
-// Mock adapter for when no database is available
-export class MockDatabaseAdapter {
+// Null adapter for when no database driver is available
+export class NullAdapter {
     isAvailable() {
-        return true; // Mock is always available
+        return false;
     }
-    open() {
-        warn("Using mock database - no persistence available");
-        return {
-            pragma: () => { },
-            exec: () => { },
-            prepare: () => ({
-                run: () => ({ changes: 0, lastInsertRowid: null }),
-                get: () => null,
-                all: () => []
-            }),
-            close: () => { }
-        };
+    open(path, opts) {
+        throw new Error("No SQLite driver available");
     }
 }
 // Bun SQLite adapter - singleton pattern to avoid multiple initializations
@@ -92,7 +81,7 @@ export class BetterSqliteAdapter {
             db.pragma(`busy_timeout = ${opts.busyTimeoutMs}`);
         }
         return {
-            pragma: (sql) => db.pragma(sql.replace('PRAGMA ', '')),
+            pragma: (sql) => db.pragma(sql),
             exec: (sql) => db.exec(sql),
             prepare: (sql) => db.prepare(sql),
             close: () => db.close()
@@ -103,17 +92,24 @@ export class BetterSqliteAdapter {
 export function createDatabaseAdapter() {
     const isBun = typeof globalThis.Bun !== 'undefined';
     if (isBun) {
-        const adapter = new BunSqliteAdapter();
-        if (adapter.isAvailable()) {
-            return adapter;
-        }
-        throw new Error("Bun runtime detected but bun:sqlite not available");
+        // Prefer bun:sqlite in Bun runtime
+        const bunAdapter = new BunSqliteAdapter();
+        if (bunAdapter.isAvailable())
+            return bunAdapter;
+        // Fallback to better-sqlite3
+        const betterAdapter = new BetterSqliteAdapter();
+        if (betterAdapter.isAvailable())
+            return betterAdapter;
     }
     else {
-        const adapter = new BetterSqliteAdapter();
-        if (adapter.isAvailable()) {
-            return adapter;
-        }
-        throw new Error("Node.js runtime detected but better-sqlite3 not available");
+        // Prefer better-sqlite3 in Node.js
+        const betterAdapter = new BetterSqliteAdapter();
+        if (betterAdapter.isAvailable())
+            return betterAdapter;
+        // Fallback to bun:sqlite (rare but possible)
+        const bunAdapter = new BunSqliteAdapter();
+        if (bunAdapter.isAvailable())
+            return bunAdapter;
     }
+    return new NullAdapter();
 }

package/dist/state/db.d.ts

@@ -3,15 +3,13 @@ export type SqliteDb = DatabaseConnection;
 export declare function openSqlite(dbPath: string, opts?: {
     busyTimeoutMs?: number;
 }): SqliteDb;
-export declare function configurePragmas(db: SqliteDb, pragmas: {
-    journal_mode?: "WAL" | "DELETE";
-    synchronous?: "NORMAL" | "FULL" | "OFF";
-    foreign_keys?: boolean;
-    temp_store?: "DEFAULT" | "MEMORY" | "FILE";
-}): void;
+export declare function configurePragmas(db: SqliteDb, pragmas: Record<string, any>): void;
 /** BEGIN IMMEDIATE transaction helper. */
-export declare function withTx<T>(db: SqliteDb, fn: () => T): T;
+export declare function withTx<T>(db: SqliteDb, fn: () => T, opts?: {
+    require?: boolean;
+}): T;
+export declare function getSchemaVersion(db: SqliteDb): number;
 export declare function ensureSchema(db: SqliteDb, opts?: {
     allowAutoMigrate?: boolean;
-    failOnDowngrade?: boolean;
+    silent?: boolean;
 }): void;

package/dist/state/db.js

@@ -1,21 +1,42 @@
+// src/state/db.ts
 import fs from "node:fs";
 import path from "node:path";
 import { SCHEMA_SQL, SCHEMA_VERSION } from "./schema";
 import { nowISO } from "../shared/time";
-import { info } from "../shared/log";
+import { info, warn } from "../shared/log";
 import { createDatabaseAdapter } from "./adapters";
 /** Ensure directory exists for a file path. */
 function ensureParentDir(filePath) {
     const dir = path.dirname(filePath);
     fs.mkdirSync(dir, { recursive: true });
 }
+function tableExists(db, tableName) {
+    try {
+        const row = db
+            .prepare("SELECT name FROM sqlite_master WHERE type='table' AND name=?")
+            .get(tableName);
+        return row?.name === tableName;
+    }
+    catch {
+        return false;
+    }
+}
 export function openSqlite(dbPath, opts) {
     ensureParentDir(dbPath);
     const adapter = createDatabaseAdapter();
-    const db = adapter.open(dbPath, opts);
-    return db;
+    if (!adapter.isAvailable()) {
+        throw new Error("No SQLite driver available (adapter unavailable).");
+    }
+    return adapter.open(dbPath, opts);
 }
 export function configurePragmas(db, pragmas) {
+    if (!pragmas || typeof pragmas !== "object")
+        return;
+    const known = new Set(["journal_mode", "synchronous", "foreign_keys", "temp_store"]);
+    for (const k of Object.keys(pragmas)) {
+        if (!known.has(k))
+            warn(`[Astrocode] Unknown pragma ignored: ${k}`);
+    }
     if (pragmas.journal_mode)
         db.pragma(`journal_mode = ${pragmas.journal_mode}`);
     if (pragmas.synchronous)
@@ -26,10 +47,12 @@ export function configurePragmas(db, pragmas) {
         db.pragma(`temp_store = ${pragmas.temp_store}`);
 }
 /** BEGIN IMMEDIATE transaction helper. */
-export function withTx(db, fn) {
+export function withTx(db, fn, opts) {
     const adapter = createDatabaseAdapter();
-    if (!adapter.isAvailable()) {
-        // No database available, just run the function
+    const available = adapter.isAvailable();
+    if (!available) {
+        if (opts?.require)
+            throw new Error("Database adapter unavailable; transaction required.");
         return fn();
     }
     db.exec("BEGIN IMMEDIATE");
@@ -48,50 +71,88 @@ export function withTx(db, fn) {
         throw e;
     }
 }
-export function ensureSchema(db, opts) {
-    const adapter = createDatabaseAdapter();
-    if (!adapter.isAvailable()) {
-        // Silent skip for mock adapter
-        return;
+export function getSchemaVersion(db) {
+    try {
+        const row = db
+            .prepare("SELECT schema_version FROM repo_state WHERE id = 1")
+            .get();
+        return row?.schema_version ?? 0;
     }
+    catch (e) {
+        const msg = e instanceof Error ? e.message : String(e);
+        if (msg.includes("no such table"))
+            return 0;
+        throw new Error(`Failed to read schema version: ${msg}`);
+    }
+}
+function migrateStageRunsCreatedAt(db) {
+    // v2 requires stage_runs.created_at to be meaningful; never write ''.
+    // This migration is best-effort and does not assume constraint rewrite support.
     try {
-        db.exec(SCHEMA_SQL);
-        // Migrations for existing databases
-        // Add created_at to stage_runs if missing (introduced in schema version 2)
-        try {
-            const columns = db.prepare("PRAGMA table_info(stage_runs)").all();
-            const hasCreatedAt = columns.some(col => col.name === 'created_at');
-            if (!hasCreatedAt) {
-                db.exec("ALTER TABLE stage_runs ADD COLUMN created_at TEXT NOT NULL DEFAULT ''");
-                info("[Astrocode] Added created_at column to stage_runs table");
-            }
-        }
-        catch (e) {
-            // Column might already exist or table doesn't exist, ignore
-        }
-        const row = db.prepare("SELECT schema_version FROM repo_state WHERE id = 1").get();
-        if (!row) {
-            const now = nowISO();
-            db.prepare("INSERT INTO repo_state (id, schema_version, created_at, updated_at) VALUES (1, ?, ?, ?)").run(SCHEMA_VERSION, now, now);
-            // Initialize story key seq
-            db.prepare("INSERT OR IGNORE INTO story_keyseq (id, next_story_num) VALUES (1, 1)").run();
+        const cols = db.prepare("PRAGMA table_info(stage_runs)").all();
+        const hasCreatedAt = cols.some((c) => c.name === "created_at");
+        if (hasCreatedAt)
             return;
-        }
-        const currentVersion = row.schema_version ?? 0;
-        if (currentVersion === SCHEMA_VERSION)
-            return;
-        if (currentVersion > SCHEMA_VERSION && (opts?.failOnDowngrade ?? true)) {
-            throw new Error(`Astrocode DB schema_version ${currentVersion} is newer than this plugin (${SCHEMA_VERSION}). Refusing to downgrade.`);
-        }
-        if (currentVersion < SCHEMA_VERSION) {
-            if (!(opts?.allowAutoMigrate ?? true)) {
-                throw new Error(`Astrocode DB schema_version ${currentVersion} is older than required (${SCHEMA_VERSION}). Auto-migrate disabled.`);
+        // Add nullable column first (avoid poison defaults).
+        db.exec("ALTER TABLE stage_runs ADD COLUMN created_at TEXT");
+        const now = nowISO();
+        // Backfill using best available timestamp fields, falling back to now.
+        db.prepare(`
+      UPDATE stage_runs
+      SET created_at =
+        COALESCE(
+          NULLIF(created_at, ''),
+          NULLIF(updated_at, ''),
+          NULLIF(started_at, ''),
+          ?
+        )
+      WHERE created_at IS NULL OR created_at = ''
+    `).run(now);
+        info("[Astrocode] Added created_at column to stage_runs table (backfilled)");
+    }
+    catch (e) {
+        // Ignore: table may not exist yet, or migration already applied.
+    }
+}
+export function ensureSchema(db, opts) {
+    try {
+        return withTx(db, () => {
+            db.exec(SCHEMA_SQL);
+            // Deterministic assertions: if these fail, bootstrap is broken.
+            if (!tableExists(db, "repo_state"))
+                throw new Error("Schema missing required table repo_state after SCHEMA_SQL");
+            if (!tableExists(db, "story_keyseq"))
+                throw new Error("Schema missing required table story_keyseq after SCHEMA_SQL");
+            // Ensure required singleton rows exist.
+            db.prepare("INSERT OR IGNORE INTO story_keyseq (id, next_story_num) VALUES (1, 1)").run();
+            // Migrations for existing DBs.
+            migrateStageRunsCreatedAt(db);
+            const row = db
+                .prepare("SELECT schema_version FROM repo_state WHERE id = 1")
+                .get();
+            if (!row) {
+                const now = nowISO();
+                db.prepare("INSERT INTO repo_state (id, schema_version, created_at, updated_at) VALUES (1, ?, ?, ?)").run(SCHEMA_VERSION, now, now);
+                return;
             }
-            // Additive schema: SCHEMA_SQL already created new tables/indexes if missing.
-            db.prepare("UPDATE repo_state SET schema_version = ?, updated_at = ? WHERE id = 1").run(SCHEMA_VERSION, nowISO());
-        }
+            const currentVersion = row.schema_version ?? 0;
+            if (currentVersion === SCHEMA_VERSION)
+                return;
+            if (currentVersion > SCHEMA_VERSION) {
+                // Newer schema - no action (policy enforcement elsewhere).
+                return;
+            }
+            if (currentVersion < SCHEMA_VERSION) {
+                if (opts?.allowAutoMigrate ?? true) {
+                    db.prepare("UPDATE repo_state SET schema_version = ?, updated_at = ? WHERE id = 1").run(SCHEMA_VERSION, nowISO());
+                }
+            }
+        }, { require: true });
     }
     catch (e) {
-        // Schema operations might fail on mock adapter, silently ignore
+        if (opts?.silent)
+            return;
+        const msg = e instanceof Error ? e.message : String(e);
+        throw new Error(`Schema initialization failed: ${msg}`);
     }
 }