astrocode-workflow 0.4.0 → 0.4.2

package/dist/src/state/schema.js

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

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

@@ -0,0 +1,71 @@
+export type StoryState = "queued" | "approved" | "in_progress" | "done" | "blocked" | "archived";
+export type RunStatus = "created" | "running" | "completed" | "failed" | "aborted";
+export type StageStatus = "pending" | "running" | "completed" | "failed" | "skipped";
+export type StageKey = "frame" | "plan" | "spec" | "implement" | "review" | "verify" | "close";
+export type StoryRow = {
+    story_key: string;
+    epic_key: string | null;
+    title: string;
+    body_md: string;
+    state: StoryState;
+    priority: number;
+    approved_at: string | null;
+    locked_by_run_id: string | null;
+    locked_at: string | null;
+    in_progress: 0 | 1;
+    created_at: string;
+    updated_at: string;
+};
+export type RunRow = {
+    run_id: string;
+    story_key: string;
+    status: RunStatus;
+    pipeline_stages_json: string;
+    current_stage_key: string | null;
+    created_at: string;
+    started_at: string | null;
+    completed_at: string | null;
+    updated_at: string;
+    error_text: string | null;
+};
+export type StageRunRow = {
+    stage_run_id: string;
+    run_id: string;
+    stage_key: StageKey;
+    stage_index: number;
+    status: StageStatus;
+    created_at: string;
+    subagent_type: string | null;
+    subagent_session_id: string | null;
+    started_at: string | null;
+    completed_at: string | null;
+    updated_at: string;
+    baton_path: string | null;
+    summary_md: string | null;
+    output_json: string | null;
+    error_text: string | null;
+};
+export type ArtifactRow = {
+    artifact_id: string;
+    run_id: string | null;
+    stage_key: string | null;
+    type: string;
+    path: string;
+    sha256: string | null;
+    meta_json: string;
+    created_at: string;
+};
+export type InjectRow = {
+    inject_id: string;
+    type: string;
+    title: string;
+    body_md: string;
+    tags_json: string;
+    scope: string;
+    source: string;
+    priority: number;
+    expires_at: string | null;
+    sha256: string | null;
+    created_at: string;
+    updated_at: string;
+};

package/dist/src/state/types.js

@@ -0,0 +1 @@
+export {};

package/dist/src/state/workflow-repo-lock.d.ts

@@ -0,0 +1,23 @@
+import type { acquireRepoLock } from "./repo-lock";
+type RepoLockAcquire = typeof acquireRepoLock;
+/**
+ * Acquire ONCE per workflow/session in this process.
+ * Nested calls reuse the same held lock (no reacquire, no churn).
+ *
+ * ADVISORY LOCK MODE:
+ * - Creates lock file to signal other sessions
+ * - If lock held by another session: WARN and proceed anyway
+ * - Database constraints provide actual safety (single running run)
+ * - Better UX: no blocking, just helpful warnings
+ */
+export declare function workflowRepoLock<T>(deps: {
+    acquireRepoLock: RepoLockAcquire;
+}, opts: {
+    lockPath: string;
+    repoRoot: string;
+    sessionId?: string;
+    owner?: string;
+    fn: () => Promise<T>;
+    advisory?: boolean;
+}): Promise<T>;
+export {};

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

@@ -0,0 +1,83 @@
+const HELD_BY_KEY = new Map();
+function key(lockPath, sessionId) {
+    return `${lockPath}::${sessionId ?? ""}`;
+}
+/**
+ * Acquire ONCE per workflow/session in this process.
+ * Nested calls reuse the same held lock (no reacquire, no churn).
+ *
+ * ADVISORY LOCK MODE:
+ * - Creates lock file to signal other sessions
+ * - If lock held by another session: WARN and proceed anyway
+ * - Database constraints provide actual safety (single running run)
+ * - Better UX: no blocking, just helpful warnings
+ */
+export async function workflowRepoLock(deps, opts) {
+    const k = key(opts.lockPath, opts.sessionId);
+    const existing = HELD_BY_KEY.get(k);
+    if (existing) {
+        existing.depth += 1;
+        try {
+            return await opts.fn();
+        }
+        finally {
+            existing.depth -= 1;
+            if (existing.depth <= 0) {
+                HELD_BY_KEY.delete(k);
+                existing.release();
+            }
+        }
+    }
+    // IMPORTANT: this is tuned for "hold for whole workflow".
+    let handle = null;
+    try {
+        handle = await deps.acquireRepoLock({
+            lockPath: opts.lockPath,
+            repoRoot: opts.repoRoot,
+            sessionId: opts.sessionId,
+            owner: opts.owner,
+            retryMs: opts.advisory ? 1000 : 30_000, // Advisory: fail fast, hard: wait longer
+            staleMs: 30_000, // Reduced from 2 minutes to 30 seconds for faster stale lock recovery
+            heartbeatMs: 200,
+            minWriteMs: 800,
+            pollMs: 20,
+            pollMaxMs: 250,
+        });
+    }
+    catch (err) {
+        // Lock acquisition failed - check if advisory mode
+        if (opts.advisory) {
+            // Advisory mode: warn and proceed without lock
+            // eslint-disable-next-line no-console
+            console.warn(`⚠️  [Astrocode] Another session may be active. Proceeding anyway (advisory lock mode).`);
+            // eslint-disable-next-line no-console
+            console.warn(`    ${err.message}`);
+            // Proceed without lock - database constraints will ensure safety
+            try {
+                return await opts.fn();
+            }
+            catch (dbErr) {
+                // Check if this is a concurrency error
+                if (dbErr.message?.includes('UNIQUE constraint') || dbErr.message?.includes('SQLITE_BUSY')) {
+                    throw new Error(`Another session is actively working on this story. Database prevented concurrent modification. ` +
+                        `Please wait for the other session to complete, or work on a different story.`);
+                }
+                throw dbErr;
+            }
+        }
+        // Hard lock mode: propagate error
+        throw err;
+    }
+    const held = { release: handle.release, depth: 1 };
+    HELD_BY_KEY.set(k, held);
+    try {
+        return await opts.fn();
+    }
+    finally {
+        held.depth -= 1;
+        if (held.depth <= 0) {
+            HELD_BY_KEY.delete(k);
+            held.release();
+        }
+    }
+}

package/dist/src/tools/artifacts.d.ts

@@ -0,0 +1,18 @@
+import { type ToolDefinition } from "@opencode-ai/plugin/tool";
+import type { AstrocodeConfig } from "../config/schema";
+import type { SqliteDb } from "../state/db";
+export declare function createAstroArtifactPutTool(opts: {
+    ctx: any;
+    config: AstrocodeConfig;
+    db: SqliteDb;
+}): ToolDefinition;
+export declare function createAstroArtifactListTool(opts: {
+    ctx: any;
+    config: AstrocodeConfig;
+    db: SqliteDb;
+}): ToolDefinition;
+export declare function createAstroArtifactGetTool(opts: {
+    ctx: any;
+    config: AstrocodeConfig;
+    db: SqliteDb;
+}): ToolDefinition;

package/dist/src/tools/artifacts.js

@@ -0,0 +1,71 @@
+import fs from "node:fs";
+import path from "node:path";
+import { tool } from "@opencode-ai/plugin/tool";
+import { putArtifact, listArtifacts, getArtifact } from "../workflow/artifacts";
+export function createAstroArtifactPutTool(opts) {
+    const { ctx, db } = opts;
+    return tool({
+        description: "Write an artifact file under .astro and record it in the DB.",
+        args: {
+            run_id: tool.schema.string().nullable().optional(),
+            stage_key: tool.schema.string().nullable().optional(),
+            type: tool.schema.string().default("log"),
+            rel_path: tool.schema.string().min(1),
+            content: tool.schema.string().default(""),
+            meta_json: tool.schema.string().default("{}"),
+        },
+        execute: async ({ run_id, stage_key, type, rel_path, content, meta_json }) => {
+            const repoRoot = ctx.directory;
+            const meta = JSON.parse(meta_json || "{}");
+            const res = putArtifact({
+                repoRoot,
+                db,
+                run_id: run_id ?? null,
+                stage_key: stage_key ?? null,
+                type,
+                rel_path,
+                content,
+                meta,
+            });
+            return `✅ Wrote artifact ${res.artifact_id} (${type}) at ${rel_path} (sha256=${res.sha256})`;
+        },
+    });
+}
+export function createAstroArtifactListTool(opts) {
+    const { db } = opts;
+    return tool({
+        description: "List artifacts (optionally filtered by run_id, stage_key, type).",
+        args: {
+            run_id: tool.schema.string().optional(),
+            stage_key: tool.schema.string().optional(),
+            type: tool.schema.string().optional(),
+        },
+        execute: async ({ run_id, stage_key, type }) => {
+            const rows = listArtifacts(db, { run_id, stage_key, type });
+            return JSON.stringify(rows, null, 2);
+        },
+    });
+}
+export function createAstroArtifactGetTool(opts) {
+    const { ctx, config, db } = opts;
+    return tool({
+        description: "Get artifact metadata (and optionally file contents).",
+        args: {
+            artifact_id: tool.schema.string().min(1),
+            include_body: tool.schema.boolean().default(false),
+            max_body_chars: tool.schema.number().int().positive().default(50_000),
+        },
+        execute: async ({ artifact_id, include_body, max_body_chars }) => {
+            const row = getArtifact(db, artifact_id);
+            if (!row)
+                throw new Error(`Artifact not found: ${artifact_id}`);
+            if (!include_body)
+                return JSON.stringify(row, null, 2);
+            const repoRoot = ctx.directory;
+            const abs = path.join(repoRoot, row.path);
+            const body = fs.existsSync(abs) ? fs.readFileSync(abs, "utf-8") : "(missing file)";
+            const clipped = body.length > max_body_chars ? body.slice(0, max_body_chars) + "\n…(truncated)" : body;
+            return JSON.stringify({ ...row, body: clipped }, null, 2);
+        },
+    });
+}

package/dist/src/tools/health.d.ts

@@ -0,0 +1,8 @@
+import { type ToolDefinition } from "@opencode-ai/plugin/tool";
+import type { AstrocodeConfig } from "../config/schema";
+import type { SqliteDb } from "../state/db";
+export declare function createAstroHealthTool(opts: {
+    ctx: any;
+    config: AstrocodeConfig;
+    db: SqliteDb;
+}): ToolDefinition;

package/dist/src/tools/health.js

@@ -0,0 +1,88 @@
+// src/tools/health.ts
+import { tool } from "@opencode-ai/plugin/tool";
+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) {
+    const { ctx, config, db } = opts;
+    return tool({
+        description: "Check Astrocode health: DB status, locks, schema, active runs, recent events.",
+        args: {},
+        execute: async () => {
+            const lines = [];
+            const repoRoot = ctx.directory || process.cwd();
+            const dbPath = config.db?.path || ".astro/astro.db";
+            const fullDbPath = path.resolve(repoRoot, dbPath);
+            // System info
+            lines.push("# Astrocode Health Check");
+            lines.push(`- PID: ${process.pid || "unknown"}`);
+            lines.push(`- Repo: ${repoRoot}`);
+            lines.push(`- DB Path: ${fullDbPath}`);
+            // DB file status
+            const dbExists = fs.existsSync(fullDbPath);
+            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"}`);
+            if (!dbExists) {
+                lines.push(`- STATUS: DB MISSING - run astro_init first`);
+                return lines.join("\n");
+            }
+            // Schema version
+            try {
+                const schemaVersion = getSchemaVersion(db);
+                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
+            try {
+                const activeRun = getActiveRun(db);
+                if (activeRun) {
+                    lines.push(`- Active Run: ${activeRun.run_id} (${activeRun.status})`);
+                    lines.push(`  - Story: ${activeRun.story_key}`);
+                    lines.push(`  - Stage: ${activeRun.current_stage_key || "none"}`);
+                    lines.push(`  - Started: ${activeRun.started_at}`);
+                }
+                else {
+                    lines.push(`- Active Run: NONE`);
+                }
+            }
+            catch (e) {
+                lines.push(`- Active Run: ERROR (${String(e)})`);
+            }
+            // Recent events
+            try {
+                const events = db.prepare(`
+          SELECT event_id, run_id, stage_key, type, created_at
+          FROM events
+          ORDER BY created_at DESC
+          LIMIT 10
+        `).all();
+                lines.push(`- Recent Events (${events.length}):`);
+                for (const event of events) {
+                    const stage = event.stage_key ? `/${event.stage_key}` : "";
+                    lines.push(`  - ${event.created_at}: ${event.type} (${event.run_id || "global"}${stage})`);
+                }
+            }
+            catch (e) {
+                lines.push(`- Recent Events: ERROR (${String(e)})`);
+            }
+            // Status summary
+            lines.push(``);
+            lines.push(`## Status`);
+            lines.push(`✅ DB accessible`);
+            lines.push(`✅ Schema valid`);
+            if (walExists || shmExists) {
+                lines.push(`⚠️ WAL/SHM files present - indicates unclean shutdown or active transaction`);
+            }
+            return lines.join("\n");
+        },
+    });
+}

package/dist/src/tools/index.d.ts

@@ -0,0 +1,20 @@
+import type { ToolDefinition } from "@opencode-ai/plugin/tool";
+import type { AstrocodeConfig } from "../config/schema";
+import type { SqliteDb } from "../state/db";
+import { AgentConfig } from "@opencode-ai/sdk";
+type RuntimeState = {
+    db: SqliteDb | null;
+    limitedMode: boolean;
+    limitedModeReason: null | {
+        code: "db_init_failed" | "schema_too_old" | "schema_downgrade" | "schema_migration_failed";
+        details: any;
+    };
+};
+type CreateAstroToolsOptions = {
+    ctx: any;
+    config: AstrocodeConfig;
+    agents?: Record<string, AgentConfig>;
+    runtime: RuntimeState;
+};
+export declare function createAstroTools(opts: CreateAstroToolsOptions): Record<string, ToolDefinition>;
+export {};