astrocode-workflow 0.0.1

package/dist/tools/injects.js

@@ -0,0 +1,99 @@
+import { tool } from "@opencode-ai/plugin/tool";
+import { nowISO } from "../shared/time";
+import { sha256Hex } from "../shared/hash";
+function newInjectId() {
+    return `inj_${Date.now()}_${Math.random().toString(16).slice(2)}`;
+}
+export function createAstroInjectPutTool(opts) {
+    const { db } = opts;
+    return tool({
+        description: "Create/update an inject (note/policy) stored in the DB. Useful for persistent rules.",
+        args: {
+            inject_id: tool.schema.string().optional(),
+            type: tool.schema.string().default("note"),
+            title: tool.schema.string().min(1),
+            body_md: tool.schema.string().min(1),
+            tags_json: tool.schema.string().default("[]"),
+            scope: tool.schema.string().default("repo"),
+            source: tool.schema.string().default("user"),
+            priority: tool.schema.number().int().default(50),
+            expires_at: tool.schema.string().nullable().optional(),
+        },
+        execute: async ({ inject_id, type, title, body_md, tags_json, scope, source, priority, expires_at }) => {
+            const id = inject_id ?? newInjectId();
+            const now = nowISO();
+            const sha = sha256Hex(body_md);
+            const existing = db.prepare("SELECT inject_id FROM injects WHERE inject_id=?").get(id);
+            if (existing) {
+                db.prepare("UPDATE injects SET type=?, title=?, body_md=?, tags_json=?, scope=?, source=?, priority=?, expires_at=?, sha256=?, updated_at=? WHERE inject_id=?").run(type, title, body_md, tags_json, scope, source, priority, expires_at ?? null, sha, now, id);
+                return `✅ Updated inject ${id}: ${title}`;
+            }
+            db.prepare("INSERT INTO injects (inject_id, type, title, body_md, tags_json, scope, source, priority, expires_at, sha256, created_at, updated_at) VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?)").run(id, type, title, body_md, tags_json, scope, source, priority, expires_at ?? null, sha, now, now);
+            return `✅ Created inject ${id}: ${title}`;
+        },
+    });
+}
+export function createAstroInjectListTool(opts) {
+    const { db } = opts;
+    return tool({
+        description: "List injects (optionally filtered by scope/type).",
+        args: {
+            scope: tool.schema.string().optional(),
+            type: tool.schema.string().optional(),
+            limit: tool.schema.number().int().positive().default(50),
+        },
+        execute: async ({ scope, type, limit }) => {
+            const where = [];
+            const params = [];
+            if (scope) {
+                where.push("scope = ?");
+                params.push(scope);
+            }
+            if (type) {
+                where.push("type = ?");
+                params.push(type);
+            }
+            const sql = `SELECT inject_id, type, title, scope, priority, created_at, updated_at FROM injects ${where.length ? "WHERE " + where.join(" AND ") : ""} ORDER BY priority DESC, updated_at DESC LIMIT ?`;
+            const rows = db.prepare(sql).all(...params, limit);
+            return JSON.stringify(rows, null, 2);
+        },
+    });
+}
+export function createAstroInjectGetTool(opts) {
+    const { db } = opts;
+    return tool({
+        description: "Get an inject by id (full body).",
+        args: {
+            inject_id: tool.schema.string().min(1),
+        },
+        execute: async ({ inject_id }) => {
+            const row = db.prepare("SELECT * FROM injects WHERE inject_id=?").get(inject_id);
+            if (!row)
+                throw new Error(`Inject not found: ${inject_id}`);
+            return JSON.stringify(row, null, 2);
+        },
+    });
+}
+export function createAstroInjectSearchTool(opts) {
+    const { db } = opts;
+    return tool({
+        description: "Search injects by query substring over title/body/tags. Returns matches ordered by priority/recency.",
+        args: {
+            q: tool.schema.string().min(1),
+            scope: tool.schema.string().optional(),
+            limit: tool.schema.number().int().positive().default(20),
+        },
+        execute: async ({ q, scope, limit }) => {
+            const like = `%${q}%`;
+            const where = ["(title LIKE ? OR body_md LIKE ? OR tags_json LIKE ?)"];
+            const params = [like, like, like];
+            if (scope) {
+                where.push("scope = ?");
+                params.push(scope);
+            }
+            const sql = `SELECT inject_id, type, title, scope, priority, updated_at FROM injects WHERE ${where.join(" AND ")} ORDER BY priority DESC, updated_at DESC LIMIT ?`;
+            const rows = db.prepare(sql).all(...params, limit);
+            return JSON.stringify(rows, null, 2);
+        },
+    });
+}

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

package/dist/tools/repair.js

@@ -0,0 +1,25 @@
+import { tool } from "@opencode-ai/plugin/tool";
+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) {
+    const { ctx, config, db } = opts;
+    return tool({
+        description: "Repair Astrocode invariants and recover from inconsistent DB state. Writes a repair report artifact.",
+        args: {
+            write_report_artifact: tool.schema.boolean().default(true),
+        },
+        execute: async ({ write_report_artifact }) => {
+            const repoRoot = ctx.directory;
+            const report = withTx(db, () => repairState(db, config));
+            const md = formatRepairReport(report);
+            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})`;
+            }
+            return md;
+        },
+    });
+}

package/dist/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/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/tools/spec.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 createAstroSpecGetTool(opts: {
+    ctx: any;
+    config: AstrocodeConfig;
+    db: SqliteDb;
+}): ToolDefinition;
+export declare function createAstroSpecSetTool(opts: {
+    ctx: any;
+    config: AstrocodeConfig;
+    db: SqliteDb;
+}): ToolDefinition;

package/dist/tools/spec.js

@@ -0,0 +1,41 @@
+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, db } = 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 }) => {
+            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/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/tools/stage.js

@@ -0,0 +1,284 @@
+import path from "node:path";
+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 } 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}`);
+    }
+}
+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)
+                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.");
+            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}`);
+            if (stageRow.status !== "running") {
+                throw new Error(`Stage ${sk} is not running (status=${stageRow.status}). Start it first.`);
+            }
+            const parsed = parseStageOutputText(output_text);
+            if (parsed.error || !parsed.astro_json)
+                throw new Error(parsed.error ?? "ASTRO JSON missing");
+            if (parsed.astro_json.stage_key !== sk) {
+                throw new Error(`ASTRO JSON stage_key mismatch: expected ${sk}, got ${parsed.astro_json.stage_key}`);
+            }
+            // 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) {
+                throw new Error(`Evidence is required for stage ${sk} but ASTRO JSON evidence[] is empty.`);
+            }
+            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 ?? "[]");
+            const 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 OR IGNORE INTO story_relations (parent_story_key, child_story_key, relation_type, reason, created_at) VALUES (?, ?, 'split', ?, ?)").run(run.story_key, key, relation_reason, now);
+                    }
+                }
+                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/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;
+}): ToolDefinition;