astrocode-workflow 0.3.0 → 0.3.2

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

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

package/dist/src/tools/run.js

@@ -0,0 +1,54 @@
+import { tool } from "@opencode-ai/plugin/tool";
+import { abortRun, getActiveRun, getStageRuns, getStory } from "../workflow/state-machine";
+export function createAstroRunGetTool(opts) {
+    const { db } = opts;
+    return tool({
+        description: "Get run details (and stage run statuses). Defaults to active run if run_id omitted.",
+        args: {
+            run_id: tool.schema.string().optional(),
+            include_stage_summaries: tool.schema.boolean().default(false),
+        },
+        execute: async ({ run_id, include_stage_summaries }) => {
+            const active = getActiveRun(db);
+            const rid = run_id ?? active?.run_id;
+            if (!rid)
+                return "No active run.";
+            const run = db.prepare("SELECT * FROM runs WHERE run_id=?").get(rid);
+            if (!run)
+                throw new Error(`Run not found: ${rid}`);
+            const story = getStory(db, run.story_key);
+            const stages = getStageRuns(db, rid);
+            const lines = [];
+            lines.push(`# Run ${rid}`);
+            lines.push(`- Status: **${run.status}**`);
+            lines.push(`- Story: \`${run.story_key}\` — ${story?.title ?? "(missing)"}`);
+            lines.push(`- Current stage: \`${run.current_stage_key ?? "?"}\``);
+            lines.push("", "## Stages");
+            for (const s of stages) {
+                lines.push(`- \`${s.stage_key}\` (${s.status})`);
+                if (include_stage_summaries && s.summary_md) {
+                    lines.push(`  - summary: ${s.summary_md.split("\n")[0].slice(0, 120)}${s.summary_md.length > 120 ? "…" : ""}`);
+                }
+            }
+            return lines.join("\n").trim();
+        },
+    });
+}
+export function createAstroRunAbortTool(opts) {
+    const { db } = opts;
+    return tool({
+        description: "Abort a run and unlock its story (returns story to approved). Defaults to active run if run_id omitted.",
+        args: {
+            run_id: tool.schema.string().optional(),
+            reason: tool.schema.string().default("aborted by user"),
+        },
+        execute: async ({ run_id, reason }) => {
+            const active = getActiveRun(db);
+            const rid = run_id ?? active?.run_id;
+            if (!rid)
+                return "No active run to abort.";
+            abortRun(db, rid, reason);
+            return `🛑 Aborted run ${rid}. Reason: ${reason}`;
+        },
+    });
+}

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

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

package/dist/src/tools/spec.js

@@ -0,0 +1,44 @@
+import fs from "node:fs";
+import path from "node:path";
+import { tool } from "@opencode-ai/plugin/tool";
+import { getAstroPaths, ensureAstroDirs } from "../shared/paths";
+import { nowISO } from "../shared/time";
+import { sha256Hex } from "../shared/hash";
+export function createAstroSpecGetTool(opts) {
+    const { ctx, config } = opts;
+    return tool({
+        description: "Get current project spec stored at .astro/spec.md",
+        args: {},
+        execute: async () => {
+            const repoRoot = ctx.directory;
+            const paths = getAstroPaths(repoRoot, config.db.path);
+            ensureAstroDirs(paths);
+            if (!fs.existsSync(paths.specPath))
+                return "No spec found at .astro/spec.md (run astro_init or astro_spec_set).";
+            const md = fs.readFileSync(paths.specPath, "utf-8");
+            return md;
+        },
+    });
+}
+export function createAstroSpecSetTool(opts) {
+    const { ctx, config, db } = opts;
+    return tool({
+        description: "Set/replace the project spec at .astro/spec.md and record its hash in the DB.",
+        args: {
+            spec_md: tool.schema.string().min(1),
+        },
+        execute: async ({ spec_md }) => {
+            if (!db) {
+                return "❌ Database not available. Cannot track spec hash. Astrocode is running in limited mode.";
+            }
+            const repoRoot = ctx.directory;
+            const paths = getAstroPaths(repoRoot, config.db.path);
+            ensureAstroDirs(paths);
+            fs.writeFileSync(paths.specPath, spec_md);
+            const h = sha256Hex(spec_md);
+            const now = nowISO();
+            db.prepare("UPDATE repo_state SET spec_hash_after=?, updated_at=? WHERE id=1").run(h, now);
+            return `✅ Spec updated (${path.relative(repoRoot, paths.specPath)}). sha256=${h}`;
+        },
+    });
+}

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

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

package/dist/src/tools/stage.js

@@ -0,0 +1,371 @@
+import path from "node:path";
+import fs from "node:fs";
+import { tool } from "@opencode-ai/plugin/tool";
+import { withTx } from "../state/db";
+import { buildBatonSummary, parseStageOutputText } from "../workflow/baton";
+import { buildContextSnapshot } from "../workflow/context";
+import { putArtifact } from "../workflow/artifacts";
+import { nowISO } from "../shared/time";
+import { getAstroPaths, ensureAstroDirs, toPosix } from "../shared/paths";
+import { failRun, getActiveRun, getStageRuns, startStage, completeRun } from "../workflow/state-machine";
+import { newEventId, newId } from "../state/ids";
+import { insertStory } from "../workflow/story-helpers";
+function nextStageKey(pipeline, current) {
+    const i = pipeline.indexOf(current);
+    if (i === -1)
+        return null;
+    return pipeline[i + 1] ?? null;
+}
+function ensureStageMatches(run, stage_key) {
+    if (run.current_stage_key && run.current_stage_key !== stage_key) {
+        throw new Error(`Stage mismatch: run.current_stage_key=${run.current_stage_key} but got stage_key=${stage_key}`);
+    }
+}
+function splitTasksIntoStories(db, tasks, run, now, newStoryKeys, relationReason) {
+    for (const task of tasks) {
+        const complexity = task.complexity ?? 5;
+        const subtasks = task.subtasks ?? [];
+        if (subtasks.length > 0) {
+            // Split into subtasks
+            for (const subtask of subtasks) {
+                const key = insertStory(db, {
+                    title: `${task.title}: ${subtask}`,
+                    body_md: task.description ?? "",
+                    priority: Math.max(1, 10 - complexity),
+                    state: "queued",
+                    epic_key: run.story_key
+                });
+                newStoryKeys.push(key);
+                db.prepare("INSERT INTO story_relations (parent_story_key, child_story_key, relation_type, reason, created_at) VALUES (?, ?, ?, ?, ?)").run(run.story_key, key, "split", relationReason, now);
+            }
+        }
+        else if (complexity > 6) {
+            // Split complex tasks
+            const key = insertStory(db, {
+                title: task.title,
+                body_md: task.description ?? "",
+                priority: Math.max(1, 10 - complexity),
+                state: "queued",
+                epic_key: run.story_key
+            });
+            newStoryKeys.push(key);
+            db.prepare("INSERT INTO story_relations (parent_story_key, child_story_key, relation_type, reason, created_at) VALUES (?, ?, ?, ?, ?)").run(run.story_key, key, "split", relationReason, now);
+        }
+    }
+}
+export function createAstroStageStartTool(opts) {
+    const { config, db } = opts;
+    return tool({
+        description: "Start a stage for a run (sets stage_run.status=running). Usually called by astro_workflow_proceed.",
+        args: {
+            run_id: tool.schema.string().optional(),
+            stage_key: tool.schema.enum(["frame", "plan", "spec", "implement", "review", "verify", "close"]).optional(),
+            subagent_type: tool.schema.string().optional(),
+            subagent_session_id: tool.schema.string().optional(),
+        },
+        execute: async ({ run_id, stage_key, subagent_type, subagent_session_id }) => {
+            const active = getActiveRun(db);
+            const rid = run_id ?? active?.run_id;
+            if (!rid)
+                throw new Error("No active run and no run_id provided.");
+            const run = db.prepare("SELECT * FROM runs WHERE run_id=?").get(rid);
+            if (!run)
+                throw new Error(`Run not found: ${rid}`);
+            const sk = (stage_key ?? run.current_stage_key);
+            if (!sk)
+                throw new Error("No stage_key provided and run.current_stage_key is null.");
+            startStage(db, rid, sk, { subagent_type, subagent_session_id });
+            return `🟦 Started stage ${sk} for run ${rid}`;
+        },
+    });
+}
+export function createAstroStageCompleteTool(opts) {
+    const { ctx, config, db } = opts;
+    return tool({
+        description: "Complete a stage from stage-agent output text. Writes baton artifacts, updates stage_runs, advances pipeline, and can auto-queue split stories.",
+        args: {
+            run_id: tool.schema.string().optional(),
+            stage_key: tool.schema.enum(["frame", "plan", "spec", "implement", "review", "verify", "close"]).optional(),
+            // Pass FULL stage-agent message text. This tool parses baton + ASTRO JSON markers.
+            output_text: tool.schema.string().min(1),
+            allow_new_stories: tool.schema.boolean().default(true),
+            relation_reason: tool.schema.string().default("split from stage output"),
+        },
+        execute: async ({ run_id, stage_key, output_text, allow_new_stories, relation_reason }) => {
+            const repoRoot = ctx.directory;
+            const paths = getAstroPaths(repoRoot, config.db.path);
+            ensureAstroDirs(paths);
+            const active = getActiveRun(db);
+            const rid = run_id ?? active?.run_id;
+            if (!rid)
+                return "❌ No active run found. Start a run first.";
+            const run = db.prepare("SELECT * FROM runs WHERE run_id=?").get(rid);
+            if (!run)
+                return `❌ Run not found: ${rid}`;
+            const sk = (stage_key ?? run.current_stage_key);
+            if (!sk)
+                return "❌ No stage_key provided and run has no current stage.";
+            const stageRow = db.prepare("SELECT * FROM stage_runs WHERE run_id=? AND stage_key=?").get(rid, sk);
+            if (!stageRow)
+                return `❌ Stage run not found: ${rid}/${sk}`;
+            if (stageRow.status !== "running") {
+                return `❌ Stage ${sk} is not running (status=${stageRow.status}). Start it first with astro_stage_start.`;
+            }
+            const parsed = parseStageOutputText(output_text);
+            if (parsed.error || !parsed.astro_json) {
+                return `❌ JSON Parse Error: ${parsed.error ?? "ASTRO JSON missing"}.
+
+Expected format:
+1) Narrative summary (optional)
+2) Valid JSON between markers:
+<!-- ASTRO_JSON_BEGIN -->
+{
+  "schema_version": 1,
+  "stage_key": "${sk}",
+  "status": "ok",
+  "summary": "Brief summary",
+  "decisions": [],
+  "next_actions": [],
+  "tasks": [{"title": "Task name", "complexity": 3}],
+  "files": [{"path": "file.js", "kind": "file"}],
+  "evidence": [{"path": "test.js", "kind": "evidence"}],
+  "new_stories": [{"title": "Story title", "body_md": "Description"}],
+  "questions": [],
+  "metrics": {}
+}
+<!-- ASTRO_JSON_END -->
+
+Ensure JSON has required fields (stage_key, status) and valid syntax.`;
+            }
+            // Override stage_key to match the expected stage (agents sometimes get this wrong)
+            parsed.astro_json.stage_key = sk;
+            // Context validation (warnings, not errors)
+            if (parsed.astro_json.run_id && parsed.astro_json.run_id !== rid) {
+                console.warn(`[Astrocode] ⚠️ Run ID mismatch in baton: expected "${rid}", got "${parsed.astro_json.run_id}". Proceeding anyway.`);
+            }
+            if (parsed.astro_json.story_key && parsed.astro_json.story_key !== run.story_key) {
+                console.warn(`[Astrocode] ⚠️ Story key mismatch in baton: expected "${run.story_key}", got "${parsed.astro_json.story_key}". Proceeding anyway.`);
+            }
+            // Evidence requirement
+            const evidenceRequired = (sk === "verify" && config.workflow.evidence_required.verify) ||
+                (sk === "implement" && config.workflow.evidence_required.implement);
+            if (evidenceRequired && (parsed.astro_json.evidence ?? []).length === 0) {
+                return `❌ Evidence is required for stage ${sk} but ASTRO JSON evidence[] is empty. Please provide evidence files.`;
+            }
+            const batonSummary = buildBatonSummary({ config, stage_key: sk, astro_json: parsed.astro_json, baton_md: parsed.baton_md });
+            const now = nowISO();
+            const pipeline = JSON.parse(run.pipeline_stages_json ?? "[]");
+            let next = nextStageKey(pipeline, sk);
+            const stageDirRel = toPosix(path.join(".astro", "runs", rid, sk));
+            const batonRel = toPosix(path.join(stageDirRel, config.artifacts.baton_filename));
+            const summaryRel = toPosix(path.join(stageDirRel, config.artifacts.baton_summary_filename));
+            const jsonRel = toPosix(path.join(stageDirRel, config.artifacts.baton_json_filename));
+            const created = [];
+            const result = withTx(db, () => {
+                // Persist artifacts
+                if (config.artifacts.write_full_baton_md) {
+                    const a = putArtifact({
+                        repoRoot,
+                        db,
+                        run_id: rid,
+                        stage_key: sk,
+                        type: "baton",
+                        rel_path: batonRel,
+                        content: parsed.baton_md,
+                        meta: { stage_key: sk },
+                    });
+                    created.push({ artifact_id: a.artifact_id, path: batonRel });
+                }
+                if (config.artifacts.write_baton_summary_md) {
+                    const a = putArtifact({
+                        repoRoot,
+                        db,
+                        run_id: rid,
+                        stage_key: sk,
+                        type: "summary",
+                        rel_path: summaryRel,
+                        content: batonSummary,
+                        meta: { stage_key: sk },
+                    });
+                    created.push({ artifact_id: a.artifact_id, path: summaryRel });
+                }
+                if (config.artifacts.write_baton_output_json) {
+                    const a = putArtifact({
+                        repoRoot,
+                        db,
+                        run_id: rid,
+                        stage_key: sk,
+                        type: "baton",
+                        rel_path: jsonRel,
+                        content: JSON.stringify(parsed.astro_json, null, 2),
+                        meta: { stage_key: sk, schema_version: parsed.astro_json.schema_version },
+                    });
+                    created.push({ artifact_id: a.artifact_id, path: jsonRel });
+                }
+                // Update stage_runs row
+                db.prepare("UPDATE stage_runs SET status=?, completed_at=?, updated_at=?, baton_path=?, summary_md=?, output_json=?, error_text=NULL WHERE stage_run_id=?").run(parsed.astro_json.status === "ok" ? "completed" : "failed", now, now, batonRel, batonSummary, parsed.astro_json_raw ?? JSON.stringify(parsed.astro_json), stageRow.stage_run_id);
+                // stage event
+                db.prepare("INSERT INTO events (event_id, run_id, stage_key, type, body_json, created_at) VALUES (?, ?, ?, ?, ?, ?)").run(newEventId(), rid, sk, parsed.astro_json.status === "ok" ? "stage.completed" : parsed.astro_json.status === "blocked" ? "stage.blocked" : "stage.failed", JSON.stringify({ artifacts: created, metrics: parsed.astro_json.metrics ?? {} }), now);
+                // Metrics
+                if (parsed.astro_json.metrics && typeof parsed.astro_json.metrics === "object") {
+                    const ins = db.prepare("INSERT INTO workflow_metrics (metric_id, run_id, stage_key, name, value_num, value_text, created_at) VALUES (?, ?, ?, ?, ?, ?, ?)");
+                    for (const [k, v] of Object.entries(parsed.astro_json.metrics)) {
+                        const metricId = `metric_${Date.now()}_${Math.random().toString(16).slice(2)}`;
+                        if (typeof v === "number")
+                            ins.run(metricId, rid, sk, k, v, null, now);
+                        else
+                            ins.run(metricId, rid, sk, k, null, String(v), now);
+                    }
+                }
+                // New stories (split)
+                const newStoryKeys = [];
+                if (allow_new_stories && parsed.astro_json.new_stories?.length) {
+                    for (const ns of parsed.astro_json.new_stories) {
+                        const key = insertStory(db, { title: ns.title, body_md: ns.body_md ?? "", priority: ns.priority ?? 0, state: "queued" });
+                        newStoryKeys.push(key);
+                        db.prepare("INSERT INTO story_relations (parent_story_key, child_story_key, relation_type, reason, created_at) VALUES (?, ?, ?, ?, ?)").run(run.story_key, key, "split", relation_reason, now);
+                    }
+                }
+                // Automatic story splitting for complex tasks
+                if (allow_new_stories && parsed.astro_json.tasks?.length) {
+                    splitTasksIntoStories(db, parsed.astro_json.tasks, run, now, newStoryKeys, "split from stage output");
+                }
+                // Skip spec stage if spec already exists
+                if (sk === "plan" && next === "spec") {
+                    const specPath = path.join(repoRoot, ".astro", "spec.md");
+                    if (fs.existsSync(specPath) && fs.statSync(specPath).size > 100) {
+                        // Skip spec
+                        const specIndex = pipeline.indexOf("spec");
+                        db.prepare("INSERT INTO stage_runs (stage_run_id, run_id, stage_key, stage_index, status, created_at, updated_at) VALUES (?, ?, ?, ?, ?, ?, ?)")
+                            .run(newId("stage"), rid, "spec", specIndex, "skipped", now, now);
+                        next = "implement";
+                    }
+                }
+                // Split stories during implementation if tasks are identified
+                if (sk === "implement" && allow_new_stories && parsed.astro_json.tasks?.length) {
+                    splitTasksIntoStories(db, parsed.astro_json.tasks, run, now, newStoryKeys, "split from implement");
+                }
+                // Validate blocked status includes questions
+                if (parsed.astro_json.status === "blocked") {
+                    if (!parsed.astro_json.questions || parsed.astro_json.questions.length === 0) {
+                        return { ok: false, next_stage: null, new_stories: newStoryKeys, error: "Blocked status requires questions[] array to be non-empty. Add clarifying questions for user input." };
+                    }
+                }
+                if (parsed.astro_json.status !== "ok") {
+                    const err = parsed.astro_json.status === "blocked"
+                        ? `blocked: ${(parsed.astro_json.questions?.[0] ?? "needs input")}`
+                        : `failed: ${(parsed.astro_json.summary ?? "stage failed")}`;
+                    // Mark run failed (also unlocks story)
+                    failRun(db, rid, sk, err);
+                    return { ok: false, next_stage: null, new_stories: newStoryKeys, error: err };
+                }
+                // Advance run.current_stage_key
+                if (next) {
+                    db.prepare("UPDATE runs SET current_stage_key=?, updated_at=? WHERE run_id=?").run(next, now, rid);
+                }
+                else {
+                    db.prepare("UPDATE runs SET current_stage_key=NULL, updated_at=? WHERE run_id=?").run(now, rid);
+                }
+                // If last stage, complete run
+                const stageRuns = getStageRuns(db, rid);
+                const incomplete = stageRuns.find((s) => s.status !== "completed" && s.status !== "skipped");
+                if (!incomplete) {
+                    completeRun(db, rid);
+                    return { ok: true, next_stage: null, new_stories: newStoryKeys, completed_run: true };
+                }
+                return { ok: true, next_stage: next, new_stories: newStoryKeys, completed_run: false };
+            });
+            const context = buildContextSnapshot({ db, config, run_id: rid });
+            const lines = [];
+            if (result.ok) {
+                lines.push(`✅ Stage ${sk} completed for run ${rid}.`);
+            }
+            else {
+                lines.push(`⛔ Stage ${sk} ended with status ${parsed.astro_json.status} for run ${rid}.`);
+                lines.push(`Reason: ${result.error}`);
+            }
+            lines.push(``, `Artifacts:`);
+            for (const a of created)
+                lines.push(`- ${a.path} (id=${a.artifact_id})`);
+            if (result.new_stories?.length) {
+                lines.push(``, `New stories queued: ${result.new_stories.map((k) => `\`${k}\``).join(", ")}`);
+            }
+            if (result.ok) {
+                if (result.completed_run) {
+                    lines.push(``, `🎉 Run completed.`);
+                }
+                else if (result.next_stage) {
+                    lines.push(``, `Next stage: \`${result.next_stage}\``);
+                }
+            }
+            lines.push(``, `Context snapshot (post-update):`);
+            lines.push(context);
+            return lines.join("\n").trim();
+        },
+    });
+}
+export function createAstroStageFailTool(opts) {
+    const { db } = opts;
+    return tool({
+        description: "Manually fail a stage and mark run failed.",
+        args: {
+            run_id: tool.schema.string().optional(),
+            stage_key: tool.schema.enum(["frame", "plan", "spec", "implement", "review", "verify", "close"]).optional(),
+            error_text: tool.schema.string().min(1),
+        },
+        execute: async ({ run_id, stage_key, error_text }) => {
+            const active = getActiveRun(db);
+            const rid = run_id ?? active?.run_id;
+            if (!rid)
+                throw new Error("No active run and no run_id provided.");
+            const run = db.prepare("SELECT * FROM runs WHERE run_id=?").get(rid);
+            if (!run)
+                throw new Error(`Run not found: ${rid}`);
+            const sk = (stage_key ?? run.current_stage_key);
+            if (!sk)
+                throw new Error("No stage_key provided and run.current_stage_key is null.");
+            // Update stage_run row too
+            const now = nowISO();
+            const stageRow = db.prepare("SELECT * FROM stage_runs WHERE run_id=? AND stage_key=?").get(rid, sk);
+            if (!stageRow)
+                throw new Error(`Stage run not found: ${rid}/${sk}`);
+            withTx(db, () => {
+                db.prepare("UPDATE stage_runs SET status='failed', completed_at=?, updated_at=?, error_text=? WHERE stage_run_id=?").run(now, now, error_text, stageRow.stage_run_id);
+                db.prepare("INSERT INTO events (event_id, run_id, stage_key, type, body_json, created_at) VALUES (?, ?, ?, 'stage.failed', ?, ?)").run(newEventId(), rid, sk, JSON.stringify({ error_text }), now);
+                failRun(db, rid, sk, error_text);
+            });
+            return `⛔ Failed stage ${sk} and marked run ${rid} failed: ${error_text}`;
+        },
+    });
+}
+export function createAstroStageResetTool(opts) {
+    const { db } = opts;
+    return tool({
+        description: "Admin: reset a stage (and later stages) back to pending for a run. Re-opens run as running. Use carefully.",
+        args: {
+            run_id: tool.schema.string(),
+            stage_key: tool.schema.enum(["frame", "plan", "spec", "implement", "review", "verify", "close"]),
+            note: tool.schema.string().default("reset by user"),
+        },
+        execute: async ({ run_id, stage_key, note }) => {
+            const run = db.prepare("SELECT * FROM runs WHERE run_id=?").get(run_id);
+            if (!run)
+                throw new Error(`Run not found: ${run_id}`);
+            const now = nowISO();
+            const pipeline = JSON.parse(run.pipeline_stages_json ?? "[]");
+            const idx = pipeline.indexOf(stage_key);
+            if (idx === -1)
+                throw new Error(`Stage ${stage_key} not in pipeline for run ${run_id}`);
+            withTx(db, () => {
+                // Reset selected stage + later stages
+                db.prepare("UPDATE stage_runs SET status='pending', started_at=NULL, completed_at=NULL, baton_path=NULL, summary_md=NULL, output_json=NULL, error_text=NULL, subagent_session_id=NULL, updated_at=? WHERE run_id=? AND stage_index>=?").run(now, run_id, idx);
+                // Re-open run
+                db.prepare("UPDATE runs SET status='running', error_text=NULL, completed_at=NULL, current_stage_key=?, updated_at=? WHERE run_id=?").run(stage_key, now, run_id);
+                // Re-lock story
+                db.prepare("UPDATE stories SET state='in_progress', in_progress=1, locked_by_run_id=?, locked_at=COALESCE(locked_at, ?), updated_at=? WHERE story_key=?").run(run_id, now, now, run.story_key);
+                db.prepare("INSERT INTO events (event_id, run_id, stage_key, type, body_json, created_at) VALUES (?, ?, ?, 'stage.reset', ?, ?)").run(newEventId(), run_id, stage_key, JSON.stringify({ note }), now);
+            });
+            return `🔄 Reset stage ${stage_key} (and later) for run ${run_id}.`;
+        },
+    });
+}

package/dist/src/tools/status.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 createAstroStatusTool(opts: {
+    ctx: any;
+    config: AstrocodeConfig;
+    db?: SqliteDb | null;
+}): ToolDefinition;

package/dist/src/tools/status.js

@@ -0,0 +1,125 @@
+import { tool } from "@opencode-ai/plugin/tool";
+import { decideNextAction, getActiveRun, getStageRuns, getStory } from "../workflow/state-machine";
+function statusIcon(status) {
+    switch (status) {
+        case "running":
+            return "🟦";
+        case "completed":
+            return "✅";
+        case "failed":
+            return "⛔";
+        case "aborted":
+            return "🛑";
+        case "created":
+            return "🆕";
+        default:
+            return "⬜";
+    }
+}
+function stageIcon(status) {
+    switch (status) {
+        case "completed":
+            return "✅";
+        case "running":
+            return "🟦";
+        case "failed":
+            return "⛔";
+        case "skipped":
+            return "⏭️";
+        default:
+            return "⬜";
+    }
+}
+export function createAstroStatusTool(opts) {
+    const { config, db } = opts;
+    return tool({
+        description: "Show a compact Astrocode status dashboard: active run/stage, pipeline, story board counts, and next action.",
+        args: {
+            include_board: tool.schema.boolean().default(true),
+            include_recent_events: tool.schema.boolean().default(false),
+        },
+        execute: async ({ include_board, include_recent_events }) => {
+            if (!db) {
+                return [
+                    `⚠️ Astrocode not initialized.`,
+                    ``,
+                    `- Reason: Database not available`,
+                    ``,
+                    `Next: run **astro_init**, then restart the agent/runtime, then run /astro-status.`,
+                ].join("\n");
+            }
+            try {
+                const active = getActiveRun(db);
+                const lines = [];
+                lines.push(`# Astrocode Status`);
+                if (!active) {
+                    lines.push(`- Active run: *(none)*`);
+                    const next = decideNextAction(db, config);
+                    if (next.kind === "idle")
+                        lines.push(`- Next: ${next.reason === "no_approved_stories" ? "No approved stories." : "Idle."}`);
+                    if (include_board) {
+                        const counts = db.prepare("SELECT state, COUNT(*) as c FROM stories GROUP BY state ORDER BY state").all();
+                        lines.push(``, `## Story board`);
+                        for (const row of counts)
+                            lines.push(`- ${row.state}: ${row.c}`);
+                    }
+                    return lines.join("\n");
+                }
+                const story = getStory(db, active.story_key);
+                const stageRuns = getStageRuns(db, active.run_id);
+                lines.push(`- Active run: \`${active.run_id}\` ${statusIcon(active.status)} **${active.status}**`);
+                lines.push(`- Story: \`${active.story_key}\` — ${story?.title ?? "(missing)"}  (${story?.state ?? "?"})`);
+                lines.push(`- Current stage: \`${active.current_stage_key ?? "?"}\``);
+                lines.push(``, `## Pipeline`);
+                for (const s of stageRuns)
+                    lines.push(`- ${stageIcon(s.status)} \`${s.stage_key}\` (${s.status})`);
+                const next = decideNextAction(db, config);
+                lines.push(``, `## Next`, `- ${next.kind}`);
+                if (next.kind === "await_stage_completion") {
+                    lines.push(`- Awaiting output for stage \`${next.stage_key}\`. When you have it, call **astro_stage_complete** with the stage output text.`);
+                }
+                else if (next.kind === "delegate_stage") {
+                    lines.push(`- Need to run stage \`${next.stage_key}\`. Use **astro_workflow_proceed** (or delegate to the matching stage agent).`);
+                }
+                else if (next.kind === "complete_run") {
+                    lines.push(`- All stages done. Run can be completed via **astro_workflow_proceed**.`);
+                }
+                else if (next.kind === "failed") {
+                    lines.push(`- Run failed at \`${next.stage_key}\`: ${next.error_text}`);
+                }
+                if (include_board) {
+                    const counts = db.prepare("SELECT state, COUNT(*) as c FROM stories GROUP BY state ORDER BY state").all();
+                    lines.push(``, `## Story board`);
+                    for (const row of counts)
+                        lines.push(`- ${row.state}: ${row.c}`);
+                }
+                if (include_recent_events) {
+                    const evs = db.prepare("SELECT created_at, type, run_id, stage_key FROM events ORDER BY created_at DESC LIMIT 10").all();
+                    lines.push(``, `## Recent events`);
+                    for (const e of evs)
+                        lines.push(`- ${e.created_at} — ${e.type}${e.run_id ? ` (run=${e.run_id})` : ""}${e.stage_key ? ` stage=${e.stage_key}` : ""}`);
+                }
+                return lines.join("\n");
+            }
+            catch (e) {
+                const msg = e instanceof Error ? e.message : String(e);
+                if (msg.includes("no such table") || msg.includes("no such column")) {
+                    return [
+                        `⚠️ Astrocode not initialized.`,
+                        ``,
+                        `- Reason: Database present but schema is not initialized or is incompatible`,
+                        `- Error: ${msg}`,
+                        ``,
+                        `Next: run **astro_init**, then restart the agent/runtime, then run /astro-status.`,
+                    ].join("\n");
+                }
+                return [
+                    `# Astrocode Status`,
+                    ``,
+                    `⛔ Database error.`,
+                    `Error: ${msg}`,
+                ].join("\n");
+            }
+        },
+    });
+}