astrocode-workflow 0.4.4 → 0.4.6

package/src/tools/artifacts.ts

@@ -2,12 +2,12 @@ import fs from "node:fs";
 import path from "node:path";
 import { tool, type ToolDefinition } from "@opencode-ai/plugin/tool";
 import type { AstrocodeConfig } from "../config/schema";
-import type { SqliteDb } from "../state/db";
+import type { RuntimeState } from "../state/types";
 import { getAstroPaths } from "../shared/paths";
 import { putArtifact, listArtifacts, getArtifact } from "../workflow/artifacts";
 
-export function createAstroArtifactPutTool(opts: { ctx: any; config: AstrocodeConfig; db: SqliteDb }): ToolDefinition {
-  const { ctx, db } = opts;
+export function createAstroArtifactPutTool(opts: { ctx: any; config: AstrocodeConfig; runtime: RuntimeState }): ToolDefinition {
+  const { ctx, runtime } = opts;
 
   return tool({
     description: "Write an artifact file under .astro and record it in the DB.",
@@ -20,6 +20,9 @@ export function createAstroArtifactPutTool(opts: { ctx: any; config: AstrocodeCo
       meta_json: tool.schema.string().default("{}"),
     },
     execute: async ({ run_id, stage_key, type, rel_path, content, meta_json }) => {
+      const { db } = runtime;
+      if (!db) return "⚠️ Astrocode not initialized. Run **astro_init** first.";
+
       const repoRoot = ctx.directory as string;
       const meta = JSON.parse(meta_json || "{}") as Record<string, unknown>;
 
@@ -39,8 +42,8 @@ export function createAstroArtifactPutTool(opts: { ctx: any; config: AstrocodeCo
   });
 }
 
-export function createAstroArtifactListTool(opts: { ctx: any; config: AstrocodeConfig; db: SqliteDb }): ToolDefinition {
-  const { db } = opts;
+export function createAstroArtifactListTool(opts: { ctx: any; config: AstrocodeConfig; runtime: RuntimeState }): ToolDefinition {
+  const { runtime } = opts;
 
   return tool({
     description: "List artifacts (optionally filtered by run_id, stage_key, type).",
@@ -50,14 +53,17 @@ export function createAstroArtifactListTool(opts: { ctx: any; config: AstrocodeC
       type: tool.schema.string().optional(),
     },
     execute: async ({ run_id, stage_key, type }) => {
+      const { db } = runtime;
+      if (!db) return "⚠️ Astrocode not initialized. Run **astro_init** first.";
+
       const rows = listArtifacts(db, { run_id, stage_key, type });
       return JSON.stringify(rows, null, 2);
     },
   });
 }
 
-export function createAstroArtifactGetTool(opts: { ctx: any; config: AstrocodeConfig; db: SqliteDb }): ToolDefinition {
-  const { ctx, config, db } = opts;
+export function createAstroArtifactGetTool(opts: { ctx: any; config: AstrocodeConfig; runtime: RuntimeState }): ToolDefinition {
+  const { ctx, runtime } = opts;
 
   return tool({
     description: "Get artifact metadata (and optionally file contents).",
@@ -67,6 +73,9 @@ export function createAstroArtifactGetTool(opts: { ctx: any; config: AstrocodeCo
       max_body_chars: tool.schema.number().int().positive().default(50_000),
     },
     execute: async ({ artifact_id, include_body, max_body_chars }) => {
+      const { db } = runtime;
+      if (!db) return "⚠️ Astrocode not initialized. Run **astro_init** first.";
+
       const row = getArtifact(db, artifact_id);
       if (!row) throw new Error(`Artifact not found: ${artifact_id}`);
 

package/src/tools/health.ts

@@ -1,14 +1,14 @@
 // src/tools/health.ts
 import { tool, type ToolDefinition } from "@opencode-ai/plugin/tool";
 import type { AstrocodeConfig } from "../config/schema";
-import type { SqliteDb } from "../state/db";
+import type { RuntimeState } from "../state/types";
 import { getSchemaVersion } from "../state/db";
 import { getActiveRun } from "../workflow/state-machine";
 import fs from "node:fs";
 import path from "node:path";
 
-export function createAstroHealthTool(opts: { ctx: any; config: AstrocodeConfig; db: SqliteDb }): ToolDefinition {
-  const { ctx, config, db } = opts;
+export function createAstroHealthTool(opts: { ctx: any; config: AstrocodeConfig; runtime: RuntimeState }): ToolDefinition {
+  const { ctx, config, runtime } = opts;
 
   return tool({
     description: "Check Astrocode health: DB status, locks, schema, active runs, recent events.",
@@ -30,13 +30,24 @@ export function createAstroHealthTool(opts: { ctx: any; config: AstrocodeConfig;
       const walExists = fs.existsSync(`${fullDbPath}-wal`);
       const shmExists = fs.existsSync(`${fullDbPath}-shm`);
 
-      lines.push(`- DB Files:`);
-      lines.push(`  - Main: ${dbExists ? "EXISTS" : "MISSING"}`);
-      lines.push(`  - WAL: ${walExists ? "EXISTS" : "MISSING"}`);
-      lines.push(`  - SHM: ${shmExists ? "EXISTS" : "MISSING"}`);
+      lines.push(`## Database File`);
+      lines.push(`- Exists: ${dbExists ? "✅" : "❌"}`);
+      lines.push(`- WAL Mode Active: ${walExists ? "YES" : "NO"}`);
 
-      if (!dbExists) {
-        lines.push(`- STATUS: DB MISSING - run astro_init first`);
+      if (dbExists) {
+        const stats = fs.statSync(fullDbPath);
+        lines.push(`- Size: ${Math.round(stats.size / 1024)} KB`);
+        lines.push(`- Last Modified: ${stats.mtime.toISOString()}`);
+      }
+
+      const { db } = runtime;
+
+      if (!db) {
+        lines.push(``, `## Status`);
+        lines.push(`❌ DB not connected (Limited Mode)`);
+        if (runtime.limitedModeReason) {
+          lines.push(`- Reason: ${runtime.limitedModeReason.code}`);
+        }
         return lines.join("\n");
       }
 
@@ -46,8 +57,6 @@ export function createAstroHealthTool(opts: { ctx: any; config: AstrocodeConfig;
         lines.push(`- Schema Version: ${schemaVersion}`);
       } catch (e) {
         lines.push(`- Schema Version: ERROR (${String(e)})`);
-        lines.push(`- STATUS: DB CORRUPTED`);
-        return lines.join("\n");
       }
 
       // Active run
@@ -59,7 +68,7 @@ export function createAstroHealthTool(opts: { ctx: any; config: AstrocodeConfig;
           lines.push(`  - Stage: ${activeRun.current_stage_key || "none"}`);
           lines.push(`  - Started: ${activeRun.started_at}`);
         } else {
-          lines.push(`- Active Run: NONE`);
+          lines.push(`- Active Run: *(none)*`);
         }
       } catch (e) {
         lines.push(`- Active Run: ERROR (${String(e)})`);
@@ -90,7 +99,7 @@ export function createAstroHealthTool(opts: { ctx: any; config: AstrocodeConfig;
       lines.push(`✅ Schema valid`);
 
       if (walExists || shmExists) {
-        lines.push(`⚠️ WAL/SHM files present - indicates unclean shutdown or active transaction`);
+        lines.push(`ℹ️ SQLite temporary files present (normal during active use)`);
       }
 
       return lines.join("\n");

package/src/tools/index.ts

@@ -33,53 +33,45 @@ type CreateAstroToolsOptions = {
 
 export function createAstroTools(opts: CreateAstroToolsOptions): Record<string, ToolDefinition> {
   const { ctx, config, agents, runtime } = opts;
-  const { db } = runtime;
-  const hasDatabase = db !== null; // Source of truth: DB availability
 
   const tools: Record<string, ToolDefinition> = {};
 
-    // Always available tools (work without database - guaranteed DB-independent)
-     tools.astro_status = createAstroStatusTool({ ctx, config });
-     tools.astro_spec_get = createAstroSpecGetTool({ ctx, config });
-     tools.astro_health = createAstroHealthTool({ ctx, config, db });
-     tools.astro_reset = createAstroResetTool({ ctx, config, db });
-      tools.astro_metrics = createAstroMetricsTool({ ctx, config });
+  // Always available tools (work without database - guaranteed DB-independent)
+  tools.astro_status = createAstroStatusTool({ ctx, config, runtime });
+  tools.astro_spec_get = createAstroSpecGetTool({ ctx, config });
+  tools.astro_health = createAstroHealthTool({ ctx, config, runtime });
+  tools.astro_reset = createAstroResetTool({ ctx, config, runtime });
+  tools.astro_metrics = createAstroMetricsTool({ ctx, config });
 
-   // Recovery tool - available even in limited mode to allow DB initialization
-   tools.astro_init = createAstroInitTool({ ctx, config, runtime });
+  // Recovery tool - available even in limited mode to allow DB initialization
+  tools.astro_init = createAstroInitTool({ ctx, config, runtime });
 
   // Database-dependent tools
-  if (hasDatabase) {
-    // Ensure agents are available for workflow tools that require them
-    if (!agents) {
-      throw new Error("astro_workflow_proceed requires agents to be provided in normal mode.");
-    }
-
-    tools.astro_story_queue = createAstroStoryQueueTool({ ctx, config, db });
-    tools.astro_story_approve = createAstroStoryApproveTool({ ctx, config, db });
-    tools.astro_story_board = createAstroStoryBoardTool({ ctx, config, db });
-    tools.astro_story_set_state = createAstroStorySetStateTool({ ctx, config, db });
-    tools.astro_spec_set = createAstroSpecSetTool({ ctx, config, db });
-    tools.astro_run_get = createAstroRunGetTool({ ctx, config, db });
-    tools.astro_run_abort = createAstroRunAbortTool({ ctx, config, db });
-    tools.astro_workflow_proceed = createAstroWorkflowProceedTool({ ctx, config, db, agents });
-    tools.astro_stage_start = createAstroStageStartTool({ ctx, config, db });
-    tools.astro_stage_complete = createAstroStageCompleteTool({ ctx, config, db });
-    tools.astro_stage_fail = createAstroStageFailTool({ ctx, config, db });
-    tools.astro_stage_reset = createAstroStageResetTool({ ctx, config, db });
-    tools.astro_artifact_put = createAstroArtifactPutTool({ ctx, config, db });
-    tools.astro_artifact_list = createAstroArtifactListTool({ ctx, config, db });
-    tools.astro_artifact_get = createAstroArtifactGetTool({ ctx, config, db });
-    tools.astro_inject_put = createAstroInjectPutTool({ ctx, config, db });
-    tools.astro_inject_list = createAstroInjectListTool({ ctx, config, db });
-    tools.astro_inject_search = createAstroInjectSearchTool({ ctx, config, db });
-    tools.astro_inject_get = createAstroInjectGetTool({ ctx, config, db });
-    tools.astro_inject_eligible = createAstroInjectEligibleTool({ ctx, config, db });
-    tools.astro_inject_debug_due = createAstroInjectDebugDueTool({ ctx, config, db });
-    tools.astro_repair = createAstroRepairTool({ ctx, config, db });
-  }
+  // We register these even if runtime.db is null, so they can become active if astro_init succeeds in-process.
+  // The tools themselves must handle the missing DB case gracefully (returning "not initialized").
+  tools.astro_story_queue = createAstroStoryQueueTool({ ctx, config, runtime });
+  tools.astro_story_approve = createAstroStoryApproveTool({ ctx, config, runtime });
+  tools.astro_story_board = createAstroStoryBoardTool({ ctx, config, runtime });
+  tools.astro_story_set_state = createAstroStorySetStateTool({ ctx, config, runtime });
+  tools.astro_spec_set = createAstroSpecSetTool({ ctx, config, runtime });
+  tools.astro_run_get = createAstroRunGetTool({ ctx, config, runtime });
+  tools.astro_run_abort = createAstroRunAbortTool({ ctx, config, runtime });
+  tools.astro_workflow_proceed = createAstroWorkflowProceedTool({ ctx, config, runtime, agents });
+  tools.astro_stage_start = createAstroStageStartTool({ ctx, config, runtime });
+  tools.astro_stage_complete = createAstroStageCompleteTool({ ctx, config, runtime });
+  tools.astro_stage_fail = createAstroStageFailTool({ ctx, config, runtime });
+  tools.astro_stage_reset = createAstroStageResetTool({ ctx, config, runtime });
+  tools.astro_artifact_put = createAstroArtifactPutTool({ ctx, config, runtime });
+  tools.astro_artifact_list = createAstroArtifactListTool({ ctx, config, runtime });
+  tools.astro_artifact_get = createAstroArtifactGetTool({ ctx, config, runtime });
+  tools.astro_inject_put = createAstroInjectPutTool({ ctx, config, runtime });
+  tools.astro_inject_list = createAstroInjectListTool({ ctx, config, runtime });
+  tools.astro_inject_search = createAstroInjectSearchTool({ ctx, config, runtime });
+  tools.astro_inject_get = createAstroInjectGetTool({ ctx, config, runtime });
+  tools.astro_inject_eligible = createAstroInjectEligibleTool({ ctx, config, runtime });
+  tools.astro_inject_debug_due = createAstroInjectDebugDueTool({ ctx, config, runtime });
+  tools.astro_repair = createAstroRepairTool({ ctx, config, runtime });
 
-  // Create aliases for backward compatibility
   const aliases: Array<[string, string]> = [
     ["_astro_init", "astro_init"],
     ["_astro_status", "astro_status"],

package/src/tools/injects.ts

@@ -1,6 +1,6 @@
 import { tool, type ToolDefinition } from "@opencode-ai/plugin/tool";
 import type { AstrocodeConfig } from "../config/schema";
-import type { SqliteDb } from "../state/db";
+import type { RuntimeState } from "../state/types";
 import { withTx } from "../state/db";
 import { nowISO } from "../shared/time";
 import { sha256Hex } from "../shared/hash";
@@ -54,8 +54,8 @@ function newInjectId(): string {
   return `inj_${Date.now()}_${Math.random().toString(16).slice(2)}`;
 }
 
-export function createAstroInjectPutTool(opts: { ctx: any; config: AstrocodeConfig; db: SqliteDb }): ToolDefinition {
-  const { db } = opts;
+export function createAstroInjectPutTool(opts: { ctx: any; config: AstrocodeConfig; runtime: RuntimeState }): ToolDefinition {
+  const { runtime } = opts;
 
   return tool({
     description: "Create/update an inject (note/policy) stored in the DB. Useful for persistent rules.",
@@ -71,6 +71,9 @@ export function createAstroInjectPutTool(opts: { ctx: any; config: AstrocodeConf
       expires_at: tool.schema.string().nullable().optional(),
     },
     execute: async ({ inject_id, type, title, body_md, tags_json, scope, source, priority, expires_at }) => {
+      const { db } = runtime;
+      if (!db) return "⚠️ Astrocode not initialized. Run **astro_init** first.";
+
       const id = inject_id ?? newInjectId();
       const now = nowISO();
       const sha = sha256Hex(body_md);
@@ -132,8 +135,8 @@ export function createAstroInjectPutTool(opts: { ctx: any; config: AstrocodeConf
   });
 }
 
-export function createAstroInjectListTool(opts: { ctx: any; config: AstrocodeConfig; db: SqliteDb }): ToolDefinition {
-  const { db } = opts;
+export function createAstroInjectListTool(opts: { ctx: any; config: AstrocodeConfig; runtime: RuntimeState }): ToolDefinition {
+  const { runtime } = opts;
 
   return tool({
     description: "List injects (optionally filtered by scope/type).",
@@ -143,6 +146,9 @@ export function createAstroInjectListTool(opts: { ctx: any; config: AstrocodeCon
       limit: tool.schema.number().int().positive().default(50),
     },
     execute: async ({ scope, type, limit }) => {
+      const { db } = runtime;
+      if (!db) return "⚠️ Astrocode not initialized. Run **astro_init** first.";
+
       const where: string[] = [];
       const params: any[] = [];
 
@@ -172,8 +178,8 @@ export function createAstroInjectListTool(opts: { ctx: any; config: AstrocodeCon
   });
 }
 
-export function createAstroInjectGetTool(opts: { ctx: any; config: AstrocodeConfig; db: SqliteDb }): ToolDefinition {
-  const { db } = opts;
+export function createAstroInjectGetTool(opts: { ctx: any; config: AstrocodeConfig; runtime: RuntimeState }): ToolDefinition {
+  const { runtime } = opts;
 
   return tool({
     description: "Get an inject by id (full body).",
@@ -181,6 +187,9 @@ export function createAstroInjectGetTool(opts: { ctx: any; config: AstrocodeConf
       inject_id: tool.schema.string().min(1),
     },
     execute: async ({ inject_id }) => {
+      const { db } = runtime;
+      if (!db) return "⚠️ Astrocode not initialized. Run **astro_init** first.";
+
       const row = db.prepare("SELECT * FROM injects WHERE inject_id=?").get(inject_id) as any;
       if (!row) throw new Error(`Inject not found: ${inject_id}`);
       return JSON.stringify(row, null, 2);
@@ -188,8 +197,8 @@ export function createAstroInjectGetTool(opts: { ctx: any; config: AstrocodeConf
   });
 }
 
-export function createAstroInjectSearchTool(opts: { ctx: any; config: AstrocodeConfig; db: SqliteDb }): ToolDefinition {
-  const { db } = opts;
+export function createAstroInjectSearchTool(opts: { ctx: any; config: AstrocodeConfig; runtime: RuntimeState }): ToolDefinition {
+  const { runtime } = opts;
 
   return tool({
     description: "Search injects by query substring over title/body/tags. Returns matches ordered by priority/recency.",
@@ -199,6 +208,9 @@ export function createAstroInjectSearchTool(opts: { ctx: any; config: AstrocodeC
       limit: tool.schema.number().int().positive().default(20),
     },
     execute: async ({ q, scope, limit }) => {
+      const { db } = runtime;
+      if (!db) return "⚠️ Astrocode not initialized. Run **astro_init** first.";
+
       const like = `%${q}%`;
       const where: string[] = ["(title LIKE ? OR body_md LIKE ? OR tags_json LIKE ?)"];
       const params: any[] = [like, like, like];
@@ -238,7 +250,7 @@ export type InjectRow = {
 };
 
 export function selectEligibleInjects(
-  db: SqliteDb,
+  db: any,
   opts: {
     nowIso: string;
     scopeAllowlist: string[];
@@ -273,8 +285,8 @@ export function selectEligibleInjects(
   return db.prepare(sql).all(...params) as InjectRow[];
 }
 
-export function createAstroInjectEligibleTool(opts: { ctx: any; config: AstrocodeConfig; db: SqliteDb }): ToolDefinition {
-  const { db } = opts;
+export function createAstroInjectEligibleTool(opts: { ctx: any; config: AstrocodeConfig; runtime: RuntimeState }): ToolDefinition {
+  const { runtime } = opts;
 
   return tool({
     description: "Debug: show which injects are eligible right now for injection.",
@@ -284,6 +296,9 @@ export function createAstroInjectEligibleTool(opts: { ctx: any; config: Astrocod
       limit: tool.schema.number().int().positive().default(50),
     },
     execute: async ({ scopes_json, types_json, limit }) => {
+      const { db } = runtime;
+      if (!db) return "⚠️ Astrocode not initialized. Run **astro_init** first.";
+
       const now = nowISO();
       const scopes = parseJsonStringArray("scopes_json", scopes_json);
       const types = parseJsonStringArray("types_json", types_json);
@@ -303,8 +318,8 @@ export function createAstroInjectEligibleTool(opts: { ctx: any; config: Astrocod
   });
 }
 
-export function createAstroInjectDebugDueTool(opts: { ctx: any; config: AstrocodeConfig; db: SqliteDb }): ToolDefinition {
-  const { db } = opts;
+export function createAstroInjectDebugDueTool(opts: { ctx: any; config: AstrocodeConfig; runtime: RuntimeState }): ToolDefinition {
+  const { runtime } = opts;
 
   return tool({
     description: "Debug: show comprehensive injection diagnostics - why injects were selected/skipped.",
@@ -313,6 +328,9 @@ export function createAstroInjectDebugDueTool(opts: { ctx: any; config: Astrocod
       types_json: tool.schema.string().default('["note","policy"]'),
     },
     execute: async ({ scopes_json, types_json }) => {
+      const { db } = runtime;
+      if (!db) return "⚠️ Astrocode not initialized. Run **astro_init** first.";
+
       const now = nowISO();
       const nowMs = Date.parse(now);
 

package/src/tools/metrics.ts

@@ -1,13 +1,10 @@
 // src/tools/metrics.ts
 import { tool, type ToolDefinition } from "@opencode-ai/plugin/tool";
+import type { AstrocodeConfig } from "../config/schema";
+import type { RuntimeState } from "../state/types";
 import { metrics } from "../shared/metrics";
 
-type CreateAstroMetricsToolOptions = {
-  ctx: any;
-  config: any;
-};
-
-export function createAstroMetricsTool(opts: CreateAstroMetricsToolOptions): ToolDefinition {
+export function createAstroMetricsTool(opts: { ctx: any; config: AstrocodeConfig; runtime?: RuntimeState }): ToolDefinition {
   return tool({
     description: "Get performance metrics for Astrocode operations including transaction times, injection success rates, and error statistics.",
     args: {},

package/src/tools/repair.ts

@@ -1,15 +1,14 @@
-import path from "node:path";
 import { tool, type ToolDefinition } from "@opencode-ai/plugin/tool";
 import type { AstrocodeConfig } from "../config/schema";
-import type { SqliteDb } from "../state/db";
+import type { RuntimeState } from "../state/types";
 import { withTx } from "../state/db";
 import { repairState, formatRepairReport } from "../workflow/repair";
 import { putArtifact } from "../workflow/artifacts";
 import { nowISO } from "../shared/time";
 
 
-export function createAstroRepairTool(opts: { ctx: any; config: AstrocodeConfig; db: SqliteDb }): ToolDefinition {
-  const { ctx, config, db } = opts;
+export function createAstroRepairTool(opts: { ctx: any; config: AstrocodeConfig; runtime: RuntimeState }): ToolDefinition {
+  const { ctx, config, runtime } = opts;
 
   return tool({
     description: "Repair Astrocode invariants and recover from inconsistent DB state. Writes a repair report artifact.",
@@ -17,6 +16,11 @@ export function createAstroRepairTool(opts: { ctx: any; config: AstrocodeConfig;
       write_report_artifact: tool.schema.boolean().default(true),
     },
     execute: async ({ write_report_artifact }) => {
+      const { db } = runtime;
+      if (!db) {
+        return "⚠️ Cannot run repair: Astrocode is not initialized. Run **astro_init** first.";
+      }
+
       const repoRoot = ctx.directory as string;
 
       // Repair database state

package/src/tools/reset.ts

@@ -1,12 +1,12 @@
 // src/tools/reset.ts
 import { tool, type ToolDefinition } from "@opencode-ai/plugin/tool";
 import type { AstrocodeConfig } from "../config/schema";
-import type { SqliteDb } from "../state/db";
+import type { RuntimeState } from "../state/types";
 import fs from "node:fs";
 import path from "node:path";
 
-export function createAstroResetTool(opts: { ctx: any; config: AstrocodeConfig; db: SqliteDb }): ToolDefinition {
-  const { ctx, config, db } = opts;
+export function createAstroResetTool(opts: { ctx: any; config: AstrocodeConfig; runtime: RuntimeState }): ToolDefinition {
+  const { ctx, config, runtime } = opts;
 
   return tool({
     description: "Reset Astrocode database: safely delete all DB files and WAL/SHM after killing concurrent processes.",
@@ -28,6 +28,14 @@ export function createAstroResetTool(opts: { ctx: any; config: AstrocodeConfig;
         ].join("\n");
       }
 
+      // Close DB connection if open
+      if (runtime.db) {
+        try {
+          runtime.db.close();
+        } catch { /* ignore */ }
+        runtime.db = null;
+      }
+
       const repoRoot = (ctx as any).directory || process.cwd();
       const dbPath = config.db?.path || ".astro/astro.db";
       const fullDbPath = path.resolve(repoRoot, dbPath);

package/src/tools/run.ts

@@ -1,10 +1,10 @@
 import { tool, type ToolDefinition } from "@opencode-ai/plugin/tool";
 import type { AstrocodeConfig } from "../config/schema";
-import type { SqliteDb } from "../state/db";
+import type { RuntimeState } from "../state/types";
 import { abortRun, getActiveRun, getStageRuns, getStory } from "../workflow/state-machine";
 
-export function createAstroRunGetTool(opts: { ctx: any; config: AstrocodeConfig; db: SqliteDb }): ToolDefinition {
-  const { db } = opts;
+export function createAstroRunGetTool(opts: { ctx: any; config: AstrocodeConfig; runtime: RuntimeState }): ToolDefinition {
+  const { runtime } = opts;
 
   return tool({
     description: "Get run details (and stage run statuses). Defaults to active run if run_id omitted.",
@@ -13,6 +13,9 @@ export function createAstroRunGetTool(opts: { ctx: any; config: AstrocodeConfig;
       include_stage_summaries: tool.schema.boolean().default(false),
     },
     execute: async ({ run_id, include_stage_summaries }) => {
+      const { db } = runtime;
+      if (!db) return "⚠️ Astrocode not initialized. Run **astro_init** first.";
+
       const active = getActiveRun(db);
       const rid = run_id ?? active?.run_id;
       if (!rid) return "No active run.";
@@ -42,8 +45,8 @@ export function createAstroRunGetTool(opts: { ctx: any; config: AstrocodeConfig;
   });
 }
 
-export function createAstroRunAbortTool(opts: { ctx: any; config: AstrocodeConfig; db: SqliteDb }): ToolDefinition {
-  const { db } = opts;
+export function createAstroRunAbortTool(opts: { ctx: any; config: AstrocodeConfig; runtime: RuntimeState }): ToolDefinition {
+  const { runtime } = opts;
 
   return tool({
     description: "Abort a run and unlock its story (returns story to approved). Defaults to active run if run_id omitted.",
@@ -52,6 +55,9 @@ export function createAstroRunAbortTool(opts: { ctx: any; config: AstrocodeConfi
       reason: tool.schema.string().default("aborted by user"),
     },
     execute: async ({ run_id, reason }) => {
+      const { db } = runtime;
+      if (!db) return "⚠️ Astrocode not initialized. Run **astro_init** first.";
+
       const active = getActiveRun(db);
       const rid = run_id ?? active?.run_id;
       if (!rid) return "No active run to abort.";

package/src/tools/spec.ts

@@ -2,7 +2,7 @@ import fs from "node:fs";
 import path from "node:path";
 import { tool, type ToolDefinition } from "@opencode-ai/plugin/tool";
 import type { AstrocodeConfig } from "../config/schema";
-import type { SqliteDb } from "../state/db";
+import type { RuntimeState } from "../state/types";
 import { getAstroPaths, ensureAstroDirs } from "../shared/paths";
 import { nowISO } from "../shared/time";
 import { sha256Hex } from "../shared/hash";
@@ -25,8 +25,8 @@ export function createAstroSpecGetTool(opts: { ctx: any; config: AstrocodeConfig
   });
 }
 
-export function createAstroSpecSetTool(opts: { ctx: any; config: AstrocodeConfig; db: SqliteDb }): ToolDefinition {
-  const { ctx, config, db } = opts;
+export function createAstroSpecSetTool(opts: { ctx: any; config: AstrocodeConfig; runtime: RuntimeState }): ToolDefinition {
+  const { ctx, config, runtime } = opts;
 
   return tool({
     description: "Set/replace the project spec at .astro/spec.md and record its hash in the DB.",
@@ -34,8 +34,9 @@ export function createAstroSpecSetTool(opts: { ctx: any; config: AstrocodeConfig
       spec_md: tool.schema.string().min(1),
     },
     execute: async ({ spec_md }) => {
+      const { db } = runtime;
       if (!db) {
-        return "❌ Database not available. Cannot track spec hash. Astrocode is running in limited mode.";
+        return "❌ Database not available. Cannot track spec hash. Astrocode is running in limited mode. Run **astro_init** first.";
       }
 
       const repoRoot = ctx.directory as string;

package/src/tools/stage.ts

@@ -2,7 +2,7 @@ import path from "node:path";
 import fs from "node:fs";
 import { tool, type ToolDefinition } from "@opencode-ai/plugin/tool";
 import type { AstrocodeConfig } from "../config/schema";
-import type { SqliteDb } from "../state/db";
+import type { RuntimeState } from "../state/types";
 import { withTx } from "../state/db";
 import type { StageKey, StageRunRow } from "../state/types";
 import { buildBatonSummary, parseStageOutputText } from "../workflow/baton";
@@ -28,7 +28,7 @@ function ensureStageMatches(run: any, stage_key: StageKey) {
 }
 
 function splitTasksIntoStories(
-  db: SqliteDb,
+  db: any,
   tasks: any[],
   run: any,
   now: string,
@@ -82,8 +82,8 @@ function splitTasksIntoStories(
   }
 }
 
-export function createAstroStageStartTool(opts: { ctx: any; config: AstrocodeConfig; db: SqliteDb }): ToolDefinition {
-  const { config, db } = opts;
+export function createAstroStageStartTool(opts: { ctx: any; config: AstrocodeConfig; runtime: RuntimeState }): ToolDefinition {
+  const { runtime } = opts;
 
   return tool({
     description: "Start a stage for a run (sets stage_run.status=running). Usually called by astro_workflow_proceed.",
@@ -94,6 +94,9 @@ export function createAstroStageStartTool(opts: { ctx: any; config: AstrocodeCon
       subagent_session_id: tool.schema.string().optional(),
     },
     execute: async ({ run_id, stage_key, subagent_type, subagent_session_id }) => {
+      const { db } = runtime;
+      if (!db) return "⚠️ Astrocode not initialized. Run **astro_init** first.";
+
       const active = getActiveRun(db);
       const rid = run_id ?? active?.run_id;
       if (!rid) throw new Error("No active run and no run_id provided.");
@@ -111,8 +114,8 @@ export function createAstroStageStartTool(opts: { ctx: any; config: AstrocodeCon
   });
 }
 
-export function createAstroStageCompleteTool(opts: { ctx: any; config: AstrocodeConfig; db: SqliteDb }): ToolDefinition {
-  const { ctx, config, db } = opts;
+export function createAstroStageCompleteTool(opts: { ctx: any; config: AstrocodeConfig; runtime: RuntimeState }): ToolDefinition {
+  const { ctx, config, runtime } = opts;
 
   return tool({
     description:
@@ -128,6 +131,9 @@ export function createAstroStageCompleteTool(opts: { ctx: any; config: Astrocode
       relation_reason: tool.schema.string().default("split from stage output"),
     },
     execute: async ({ run_id, stage_key, output_text, allow_new_stories, relation_reason }) => {
+      const { db } = runtime;
+      if (!db) return "⚠️ Astrocode not initialized. Run **astro_init** first.";
+
       const repoRoot = ctx.directory as string;
       const paths = getAstroPaths(repoRoot, config.db.path);
       ensureAstroDirs(paths);
@@ -396,8 +402,8 @@ Ensure JSON has required fields (stage_key, status) and valid syntax.`;
   });
 }
 
-export function createAstroStageFailTool(opts: { ctx: any; config: AstrocodeConfig; db: SqliteDb }): ToolDefinition {
-  const { db } = opts;
+export function createAstroStageFailTool(opts: { ctx: any; config: AstrocodeConfig; runtime: RuntimeState }): ToolDefinition {
+  const { runtime } = opts;
 
   return tool({
     description: "Manually fail a stage and mark run failed.",
@@ -407,6 +413,9 @@ export function createAstroStageFailTool(opts: { ctx: any; config: AstrocodeConf
       error_text: tool.schema.string().min(1),
     },
     execute: async ({ run_id, stage_key, error_text }) => {
+      const { db } = runtime;
+      if (!db) return "⚠️ Astrocode not initialized. Run **astro_init** first.";
+
       const active = getActiveRun(db);
       const rid = run_id ?? active?.run_id;
       if (!rid) throw new Error("No active run and no run_id provided.");
@@ -439,8 +448,8 @@ export function createAstroStageFailTool(opts: { ctx: any; config: AstrocodeConf
   });
 }
 
-export function createAstroStageResetTool(opts: { ctx: any; config: AstrocodeConfig; db: SqliteDb }): ToolDefinition {
-  const { db } = opts;
+export function createAstroStageResetTool(opts: { ctx: any; config: AstrocodeConfig; runtime: RuntimeState }): ToolDefinition {
+  const { runtime } = opts;
 
   return tool({
     description:
@@ -451,6 +460,9 @@ export function createAstroStageResetTool(opts: { ctx: any; config: AstrocodeCon
       note: tool.schema.string().default("reset by user"),
     },
     execute: async ({ run_id, stage_key, note }) => {
+      const { db } = runtime;
+      if (!db) return "⚠️ Astrocode not initialized. Run **astro_init** first.";
+
       const run = db.prepare("SELECT * FROM runs WHERE run_id=?").get(run_id) as any;
       if (!run) throw new Error(`Run not found: ${run_id}`);