astrocode-workflow 0.4.0 → 0.4.1

package/src/state/schema.ts

@@ -4,7 +4,7 @@
 //
 // Source of truth: SQLite file at .astro/astro.db
 
-export const SCHEMA_VERSION = 2;
+export const SCHEMA_VERSION = 3; // v3: Added advisory lock support + database constraints
 
 export const SCHEMA_SQL = `
 PRAGMA foreign_keys = ON;
@@ -235,6 +235,13 @@ CREATE INDEX IF NOT EXISTS idx_artifacts_run_stage ON artifacts(run_id, stage_ke
 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;

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

@@ -0,0 +1,111 @@
+// src/state/workflow-repo-lock.ts
+import type { acquireRepoLock } from "./repo-lock";
+
+type RepoLockAcquire = typeof acquireRepoLock;
+
+type Held = {
+  release: () => void;
+  depth: number;
+};
+
+const HELD_BY_KEY = new Map<string, Held>();
+
+function key(lockPath: string, sessionId?: string) {
+  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<T>(
+  deps: { acquireRepoLock: RepoLockAcquire },
+  opts: {
+    lockPath: string;
+    repoRoot: string;
+    sessionId?: string;
+    owner?: string;
+    fn: () => Promise<T>;
+    advisory?: boolean; // If true, warn instead of error on contention
+  }
+): Promise<T> {
+  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: { release: () => void } | null = 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: any) {
+    // 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: any) {
+        // 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: 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/src/tools/health.ts

@@ -0,0 +1,128 @@
+// 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 { 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;
+
+  return tool({
+    description: "Check Astrocode health: DB status, locks, schema, active runs, recent events.",
+    args: {},
+    execute: async () => {
+      const lines: string[] = [];
+      const repoRoot = (ctx as any).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 as any).pid || "unknown"}`);
+      lines.push(`- Repo: ${repoRoot}`);
+      lines.push(`- DB Path: ${fullDbPath}`);
+
+      // Lock status
+      const lockPath = `${repoRoot}/.astro/astro.lock`;
+      try {
+        if (fs.existsSync(lockPath)) {
+          const lockContent = fs.readFileSync(lockPath, "utf8").trim();
+          const parts = lockContent.split(" ");
+          if (parts.length >= 2) {
+            const pid = parseInt(parts[0]);
+            const startedAt = parts[1];
+
+            // Check if PID is still running
+            try {
+              (process as any).kill(pid, 0); // Signal 0 just checks if process exists
+              lines.push(`- Lock: HELD by PID ${pid} (started ${startedAt})`);
+            } catch {
+              lines.push(`- Lock: STALE (PID ${pid} not running, started ${startedAt})`);
+              lines.push(`  → Run: rm "${lockPath}"`);
+            }
+          } else {
+            lines.push(`- Lock: MALFORMED (${lockContent})`);
+          }
+        } else {
+          lines.push(`- Lock: NONE (no lock file)`);
+        }
+      } catch (e) {
+        lines.push(`- Lock: ERROR (${String(e)})`);
+      }
+
+      // 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() as any[];
+
+        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`);
+      lines.push(`✅ Lock file checked`);
+
+      if (walExists || shmExists) {
+        lines.push(`⚠️ WAL/SHM files present - indicates unclean shutdown or active transaction`);
+      }
+
+      return lines.join("\n");
+    },
+  });
+}

package/src/tools/index.ts

@@ -12,6 +12,10 @@ import { createAstroStageStartTool, createAstroStageCompleteTool, createAstroSta
 import { createAstroArtifactPutTool, createAstroArtifactListTool, createAstroArtifactGetTool } from "./artifacts";
 import { createAstroInjectPutTool, createAstroInjectListTool, createAstroInjectSearchTool, createAstroInjectGetTool, createAstroInjectEligibleTool, createAstroInjectDebugDueTool } from "./injects";
 import { createAstroRepairTool } from "./repair";
+import { createAstroHealthTool } from "./health";
+import { createAstroResetTool } from "./reset";
+import { createAstroMetricsTool } from "./metrics";
+import { createAstroLockStatusTool } from "./lock";
 
 import { AgentConfig } from "@opencode-ai/sdk";
 
@@ -35,9 +39,13 @@ export function createAstroTools(opts: CreateAstroToolsOptions): Record<string,
 
   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 });
+    // 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 });
+     tools.astro_lock_status = createAstroLockStatusTool({ ctx });
 
    // Recovery tool - available even in limited mode to allow DB initialization
    tools.astro_init = createAstroInitTool({ ctx, config, runtime });
@@ -100,6 +108,10 @@ export function createAstroTools(opts: CreateAstroToolsOptions): Record<string,
     ["_astro_inject_eligible", "astro_inject_eligible"],
     ["_astro_inject_debug_due", "astro_inject_debug_due"],
     ["_astro_repair", "astro_repair"],
+     ["_astro_health", "astro_health"],
+     ["_astro_reset", "astro_reset"],
+     ["_astro_metrics", "astro_metrics"],
+     ["_astro_lock_status", "astro_lock_status"],
   ];
 
   // Only add aliases for tools that exist

package/src/tools/init.ts

@@ -8,6 +8,7 @@ import { getAstroPaths, ensureAstroDirs } from "../shared/paths";
 import { nowISO } from "../shared/time";
 import { sha256Hex } from "../shared/hash";
 
+
 type RuntimeState = {
   db: SqliteDb | null;
   limitedMode: boolean;
@@ -29,14 +30,14 @@ export function createAstroInitTool(opts: { ctx: any; config: AstrocodeConfig; r
     },
     execute: async ({ ensure_spec, spec_placeholder }) => {
       const repoRoot = ctx.directory as string;
-      const paths = getAstroPaths(repoRoot, config.db.path);
-      ensureAstroDirs(paths);
+          const paths = getAstroPaths(repoRoot, config.db.path);
+          ensureAstroDirs(paths);
 
-      const hadDbAlready = !!runtime.db;
-      let db: SqliteDb | null = runtime.db;
-      let publishedToRuntime = false;
+          const hadDbAlready = !!runtime.db;
+          let db: SqliteDb | null = runtime.db;
+          let publishedToRuntime = false;
 
-      try {
+          try {
         if (!db) {
           try {
             db = openSqlite(paths.dbPath, { busyTimeoutMs: config.db.busy_timeout_ms });

package/src/tools/lock.ts

@@ -0,0 +1,75 @@
+import path from "node:path";
+import { tool, type ToolDefinition } from "@opencode-ai/plugin/tool";
+import { getLockStatus, tryRemoveStaleLock } from "../state/repo-lock";
+
+export function createAstroLockStatusTool(opts: { ctx: any }): ToolDefinition {
+  const { ctx } = opts;
+
+  return tool({
+    description: "Check Astrocode lock status and attempt repair. Shows diagnostics (PID, age, session) and can remove stale/dead locks.",
+    args: {
+      attempt_repair: tool.schema.boolean().default(false).describe("If true, attempt to remove stale or dead locks"),
+    },
+    execute: async ({ attempt_repair }) => {
+      const repoRoot = ctx.directory as string;
+      const lockPath = path.join(repoRoot, ".astro", "astro.lock");
+
+      const status = getLockStatus(lockPath);
+
+      if (!status.exists) {
+        return "✅ No lock file found. Repository is unlocked.";
+      }
+
+      const lines: string[] = [];
+      lines.push("# Astrocode Lock Status");
+      lines.push("");
+      lines.push("## Lock Details");
+      lines.push(`- **Path**: ${status.path}`);
+      lines.push(`- **PID**: ${status.pid} (${status.pidAlive ? '🟢 ALIVE' : '🔴 DEAD'})`);
+      lines.push(`- **Age**: ${status.ageMs ? Math.floor(status.ageMs / 1000) : '?'}s`);
+      lines.push(`- **Status**: ${status.isStale ? '⚠️ STALE' : '✅ FRESH'}`);
+      if (status.sessionId) lines.push(`- **Session**: ${status.sessionId}`);
+      if (status.owner) lines.push(`- **Owner**: ${status.owner}`);
+      if (status.instanceId) lines.push(`- **Instance**: ${status.instanceId.substring(0, 8)}...`);
+      if (status.leaseId) lines.push(`- **Lease**: ${status.leaseId.substring(0, 8)}...`);
+      if (status.createdAt) lines.push(`- **Created**: ${status.createdAt}`);
+      if (status.updatedAt) lines.push(`- **Updated**: ${status.updatedAt}`);
+      if (status.repoRoot) lines.push(`- **Repo**: ${status.repoRoot}`);
+      lines.push(`- **Version**: ${status.version ?? 'unknown'}`);
+      lines.push("");
+
+      if (attempt_repair) {
+        lines.push("## Repair Attempt");
+        const result = tryRemoveStaleLock(lockPath);
+
+        if (result.removed) {
+          lines.push(`✅ **Lock removed**: ${result.reason}`);
+          lines.push("");
+          lines.push("The repository is now unlocked and ready for use.");
+        } else {
+          lines.push(`⚠️ **Lock NOT removed**: ${result.reason}`);
+          lines.push("");
+          lines.push("**Recommendations**:");
+          lines.push("- If the owning process has crashed, wait 30 seconds for automatic stale detection");
+          lines.push("- If the process is still running, wait for it to complete");
+          lines.push("- As a last resort, manually stop the process and run this tool again with attempt_repair=true");
+        }
+      } else {
+        lines.push("## Recommendations");
+        if (!status.pidAlive) {
+          lines.push("🔧 **Action Required**: Lock belongs to dead process. Run with `attempt_repair=true` to remove it.");
+        } else if (status.isStale) {
+          lines.push("🔧 **Action Suggested**: Lock is stale (not updated recently). Run with `attempt_repair=true` to remove it.");
+        } else {
+          lines.push("✅ Lock is active and healthy. The owning process is running normally.");
+          lines.push("");
+          lines.push("If you believe this is incorrect:");
+          lines.push("- Wait 30 seconds and check again (automatic stale detection)");
+          lines.push("- Run with `attempt_repair=true` only if you're certain the process has crashed");
+        }
+      }
+
+      return lines.join("\n");
+    },
+  });
+}

package/src/tools/metrics.ts

@@ -0,0 +1,71 @@
+// src/tools/metrics.ts
+import { tool, type ToolDefinition } from "@opencode-ai/plugin/tool";
+import { metrics } from "../shared/metrics";
+
+type CreateAstroMetricsToolOptions = {
+  ctx: any;
+  config: any;
+};
+
+export function createAstroMetricsTool(opts: CreateAstroMetricsToolOptions): ToolDefinition {
+  return tool({
+    description: "Get performance metrics for Astrocode operations including transaction times, injection success rates, and error statistics.",
+    args: {},
+    execute: async () => {
+      return runMetricsTool();
+    },
+  });
+}
+
+function runMetricsTool(): string {
+  const stats = metrics.getMetrics();
+  const txStats = metrics.getTransactionStats();
+  const injectionStats = metrics.getInjectionStats();
+
+  let output = "# Astrocode Performance Metrics\n\n";
+
+  // Transaction Stats
+  if (txStats) {
+    output += "## Database Transactions\n\n";
+    output += `**Total:** ${txStats.total}\n`;
+    output += `**Success Rate:** ${(txStats.successRate * 100).toFixed(1)}% (${txStats.successful}/${txStats.total})\n`;
+    output += `**Average Duration:** ${txStats.avgDuration.toFixed(2)}ms\n`;
+    output += `**Duration Range:** ${txStats.minDuration}ms - ${txStats.maxDuration}ms\n`;
+    output += `**Average Nesting Depth:** ${txStats.avgNestedDepth.toFixed(1)}\n\n`;
+  } else {
+    output += "## Database Transactions\n\nNo transaction data available.\n\n";
+  }
+
+  // Injection Stats
+  if (injectionStats) {
+    output += "## UI Injections\n\n";
+    output += `**Total:** ${injectionStats.total}\n`;
+    output += `**Success Rate:** ${(injectionStats.successRate * 100).toFixed(1)}% (${injectionStats.successful}/${injectionStats.total})\n`;
+    output += `**Average Attempts:** ${injectionStats.avgAttempts.toFixed(1)}\n`;
+    output += `**Total Retries:** ${injectionStats.totalRetries}\n`;
+    output += `**Average Duration:** ${injectionStats.avgDuration.toFixed(2)}ms\n\n`;
+  } else {
+    output += "## UI Injections\n\nNo injection data available.\n\n";
+  }
+
+  // Recent Errors
+  if (stats.errors.length > 0) {
+    output += "## Recent Errors\n\n";
+    const recentErrors = stats.errors.slice(-10); // Last 10 errors
+    for (const error of recentErrors) {
+      const timestamp = new Date(error.timestamp).toISOString();
+      output += `- **[${error.type}]** ${timestamp}: ${error.message}\n`;
+    }
+    output += "\n";
+  } else {
+    output += "## Recent Errors\n\nNo errors recorded.\n\n";
+  }
+
+  // Raw Data Summary
+  output += "## Data Summary\n\n";
+  output += `**Transactions Tracked:** ${stats.transactions.length}\n`;
+  output += `**Injections Tracked:** ${stats.injections.length}\n`;
+  output += `**Errors Recorded:** ${stats.errors.length}\n`;
+
+  return output;
+}

package/src/tools/repair.ts

@@ -1,3 +1,4 @@
+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";
@@ -5,27 +6,64 @@ import { withTx } from "../state/db";
 import { repairState, formatRepairReport } from "../workflow/repair";
 import { putArtifact } from "../workflow/artifacts";
 import { nowISO } from "../shared/time";
+import { getLockStatus, tryRemoveStaleLock } from "../state/repo-lock";
+
 
 export function createAstroRepairTool(opts: { ctx: any; config: AstrocodeConfig; db: SqliteDb }): ToolDefinition {
   const { ctx, config, db } = opts;
 
   return tool({
-    description: "Repair Astrocode invariants and recover from inconsistent DB state. Writes a repair report artifact.",
+    description: "Repair Astrocode invariants and recover from inconsistent DB state. Also checks and repairs lock files. Writes a repair report artifact.",
     args: {
       write_report_artifact: tool.schema.boolean().default(true),
+      repair_lock: tool.schema.boolean().default(true).describe("Attempt to remove stale/dead lock files"),
     },
-    execute: async ({ write_report_artifact }) => {
+    execute: async ({ write_report_artifact, repair_lock }) => {
       const repoRoot = ctx.directory as string;
+      const lockPath = path.join(repoRoot, ".astro", "astro.lock");
+
+      // First, check and repair lock if requested
+      const lockLines: string[] = [];
+      const lockStatus = getLockStatus(lockPath);
+
+      if (lockStatus.exists) {
+        lockLines.push("## Lock Status");
+        lockLines.push(`- Lock found: ${lockPath}`);
+        lockLines.push(`- PID: ${lockStatus.pid} (${lockStatus.pidAlive ? 'alive' : 'dead'})`);
+        lockLines.push(`- Age: ${lockStatus.ageMs ? Math.floor(lockStatus.ageMs / 1000) : '?'}s`);
+        lockLines.push(`- Status: ${lockStatus.isStale ? 'stale' : 'fresh'}`);
+
+        if (repair_lock) {
+          const result = tryRemoveStaleLock(lockPath);
+          if (result.removed) {
+            lockLines.push(`- **Removed**: ${result.reason}`);
+          } else {
+            lockLines.push(`- **Not removed**: ${result.reason}`);
+          }
+        } else {
+          if (!lockStatus.pidAlive || lockStatus.isStale) {
+            lockLines.push(`- **Recommendation**: Run with repair_lock=true to remove this ${!lockStatus.pidAlive ? 'dead' : 'stale'} lock`);
+          }
+        }
+        lockLines.push("");
+      }
+
+      // Then repair database state
       const report = withTx(db, () => repairState(db, config));
-      const md = formatRepairReport(report);
+      const dbMd = formatRepairReport(report);
+
+      // Combine lock and DB repair
+      const fullMd = lockLines.length > 0
+        ? `# Astrocode Repair Report\n\n${lockLines.join("\n")}\n${dbMd.replace(/^# Astrocode repair report\n*/i, "")}`
+        : dbMd;
 
       if (write_report_artifact) {
         const rel = `.astro/repair/repair_${nowISO().replace(/[:.]/g, "-")}.md`;
-        const a = putArtifact({ repoRoot, db, run_id: null, stage_key: null, type: "log", rel_path: rel, content: md, meta: { kind: "repair" } });
-        return md + `\n\nReport saved: ${rel} (artifact=${a.artifact_id})`;
+        const a = putArtifact({ repoRoot, db, run_id: null, stage_key: null, type: "log", rel_path: rel, content: fullMd, meta: { kind: "repair" } });
+        return fullMd + `\n\nReport saved: ${rel} (artifact=${a.artifact_id})`;
       }
 
-      return md;
+      return fullMd;
     },
   });
 }

package/src/tools/reset.ts

@@ -0,0 +1,100 @@
+// 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 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;
+
+  return tool({
+    description: "Reset Astrocode database: safely delete all DB files and WAL/SHM after killing concurrent processes.",
+    args: {
+      confirm: tool.schema.string().default("").describe("Type 'RESET' to confirm destructive operation"),
+    },
+    execute: async ({ confirm }) => {
+      if (confirm !== "RESET") {
+        return [
+          "❌ Reset cancelled - confirmation required",
+          "",
+          "This operation will:",
+          "- Delete .astro/astro.db",
+          "- Delete .astro/astro.db-wal (if exists)",
+          "- Delete .astro/astro.db-shm (if exists)",
+          "- Lose all workflow data, stories, runs, artifacts",
+          "",
+          "To confirm: astro_reset(confirm=\"RESET\")",
+        ].join("\n");
+      }
+
+      const repoRoot = (ctx as any).directory || process.cwd();
+      const dbPath = config.db?.path || ".astro/astro.db";
+      const fullDbPath = path.resolve(repoRoot, dbPath);
+
+      const lines: string[] = [];
+      lines.push("🗑️ Astrocode Database Reset");
+      lines.push(`- Repo: ${repoRoot}`);
+      lines.push(`- Target: ${fullDbPath}`);
+
+      // Check for lock file
+      const lockPath = `${repoRoot}/.astro/astro.lock`;
+      if (fs.existsSync(lockPath)) {
+        try {
+          const lockContent = fs.readFileSync(lockPath, "utf8").trim();
+          const pid = parseInt(lockContent.split(" ")[0]);
+
+          lines.push(`- Lock file found for PID ${pid}`);
+
+          // Try to kill the process
+          try {
+            (process as any).kill(pid, 'SIGTERM');
+            lines.push(`- Sent SIGTERM to PID ${pid}, waiting 2s...`);
+            await new Promise(resolve => setTimeout(resolve, 2000));
+          } catch (e) {
+            lines.push(`- Could not kill PID ${pid}: ${String(e)}`);
+          }
+        } catch (e) {
+          lines.push(`- Error reading lock file: ${String(e)}`);
+        }
+      }
+
+      // Delete DB files
+      const filesToDelete = [
+        fullDbPath,
+        `${fullDbPath}-wal`,
+        `${fullDbPath}-shm`,
+        lockPath,
+      ];
+
+      let deletedCount = 0;
+      for (const filePath of filesToDelete) {
+        try {
+          if (fs.existsSync(filePath)) {
+            fs.unlinkSync(filePath);
+            lines.push(`- Deleted: ${path.relative(repoRoot, filePath)}`);
+            deletedCount++;
+          } else {
+            lines.push(`- Skipped: ${path.relative(repoRoot, filePath)} (not found)`);
+          }
+        } catch (e) {
+          lines.push(`- Failed to delete ${path.relative(repoRoot, filePath)}: ${String(e)}`);
+        }
+      }
+
+      lines.push(``);
+      if (deletedCount > 0) {
+        lines.push(`✅ Reset complete - ${deletedCount} files deleted`);
+        lines.push(``);
+        lines.push(`Next steps:`);
+        lines.push(`1. Run: astro_init`);
+        lines.push(`2. Run: astro_status`);
+        lines.push(`3. Import your stories and restart workflow`);
+      } else {
+        lines.push(`ℹ️ No files found to delete`);
+      }
+
+      return lines.join("\n");
+    },
+  });
+}

package/src/tools/stage.ts

@@ -14,6 +14,7 @@ import { failRun, getActiveRun, getStageRuns, startStage, completeRun } from "..
 import { newEventId, newId } from "../state/ids";
 import { insertStory } from "../workflow/story-helpers";
 
+
 function nextStageKey(pipeline: StageKey[], current: StageKey): StageKey | null {
   const i = pipeline.indexOf(current);
   if (i === -1) return null;

package/src/tools/status.ts

@@ -3,6 +3,7 @@ import type { AstrocodeConfig } from "../config/schema";
 import type { SqliteDb } from "../state/db";
 import { decideNextAction, getActiveRun, getStageRuns, getStory } from "../workflow/state-machine";
 
+
 function statusIcon(status: string): string {
   switch (status) {
     case "running":
@@ -36,7 +37,7 @@ function stageIcon(status: string): string {
 }
 
 export function createAstroStatusTool(opts: { ctx: any; config: AstrocodeConfig; db?: SqliteDb | null }): ToolDefinition {
-  const { config, db } = opts;
+  const { ctx, config, db } = opts;
 
   return tool({
     description: "Show a compact Astrocode status dashboard: active run/stage, pipeline, story board counts, and next action.",