astrocode-workflow 0.4.0 → 0.4.2

package/dist/src/workflow/baton.js

@@ -0,0 +1,166 @@
+import { clampLines, normalizeNewlines, stripCodeFences } from "../shared/text";
+import { z, ZodError } from "zod";
+export const ASTRO_JSON_BEGIN = "<!-- ASTRO_JSON_BEGIN -->";
+export const ASTRO_JSON_END = "<!-- ASTRO_JSON_END -->";
+export const StageKeySchema = z.enum(["frame", "plan", "spec", "implement", "review", "verify", "close"]);
+export const AstroJsonSchema = z.object({
+    schema_version: z.number().int().default(1),
+    run_id: z.string().optional(),
+    story_key: z.string().optional(),
+    stage_key: StageKeySchema,
+    status: z.enum(["ok", "blocked", "failed"]).default("ok"),
+    summary: z.string().default(""),
+    decisions: z.array(z.string()).default([]),
+    next_actions: z.array(z.string()).default([]),
+    tasks: z.array(z.object({
+        title: z.string(),
+        description: z.string().optional(),
+        complexity: z.number().int().min(1).max(10).optional(),
+        subtasks: z.array(z.string()).optional(),
+    })).default([]),
+    files: z.array(z.object({
+        path: z.string(),
+        kind: z.string().default("file"),
+        notes: z.string().optional(),
+    })).default([]),
+    evidence: z.array(z.object({
+        path: z.string(),
+        kind: z.string().default("evidence"),
+        notes: z.string().optional(),
+    })).default([]),
+    new_stories: z.array(z.object({
+        title: z.string(),
+        body_md: z.string().optional(),
+        priority: z.number().int().optional(),
+    })).default([]),
+    questions: z.array(z.string()).default([]),
+    metrics: z.record(z.string(), z.union([z.number(), z.string()])).default({}),
+});
+export function parseStageOutputText(text) {
+    const norm = normalizeNewlines(text ?? "").trim();
+    const beginIdx = norm.indexOf(ASTRO_JSON_BEGIN);
+    const endIdx = norm.indexOf(ASTRO_JSON_END);
+    let baton_md = "";
+    let jsonRaw = "";
+    let fallbackUsed = false;
+    if (beginIdx === -1 || endIdx === -1 || endIdx <= beginIdx) {
+        // Enhanced fallback: scan for any JSON object in the text
+        const jsonMatch = norm.match(/\{[\s\S]*\}/);
+        if (jsonMatch) {
+            try {
+                const parsed = JSON.parse(jsonMatch[0]);
+                const astroJson = AstroJsonSchema.parse(parsed);
+                return {
+                    baton_md: norm.replace(jsonMatch[0], "").trim(),
+                    astro_json: astroJson,
+                    astro_json_raw: jsonMatch[0],
+                    error: null
+                };
+            }
+            catch (e) {
+                // JSON found but invalid, continue to marker error
+            }
+        }
+        // Fallback: if no markers, check if the entire text is JSON
+        try {
+            const parsed = JSON.parse(norm);
+            const astroJson = AstroJsonSchema.parse(parsed);
+            return {
+                baton_md: "",
+                astro_json: astroJson,
+                astro_json_raw: norm,
+                error: null
+            };
+        }
+        catch (e) {
+            // Not JSON, proceed with marker error
+        }
+        // If no JSON found, create a default structure from the text
+        const defaultJson = {
+            schema_version: 1,
+            stage_key: "frame", // Default, will be overridden by actual stage_key
+            status: "ok",
+            summary: norm.trim() || "Stage completed without structured output",
+            decisions: [],
+            next_actions: [],
+            tasks: [],
+            files: [],
+            evidence: [],
+            new_stories: [],
+            questions: [],
+            metrics: {}
+        };
+        return {
+            baton_md: "",
+            astro_json: defaultJson,
+            astro_json_raw: JSON.stringify(defaultJson, null, 2),
+            error: null
+        };
+    }
+    const before = norm.slice(0, beginIdx).trim();
+    jsonRaw = norm.slice(beginIdx + ASTRO_JSON_BEGIN.length, endIdx).trim();
+    const after = norm.slice(endIdx + ASTRO_JSON_END.length).trim();
+    baton_md = [before, after].filter(Boolean).join("\n\n").trim();
+    try {
+        const cleaned = stripCodeFences(jsonRaw).trim();
+        const parsed = JSON.parse(cleaned);
+        const astroJson = AstroJsonSchema.parse(parsed);
+        return { baton_md, astro_json: astroJson, astro_json_raw: cleaned, error: null };
+    }
+    catch (e) {
+        if (e instanceof ZodError) {
+            return {
+                baton_md,
+                astro_json: null,
+                astro_json_raw: jsonRaw,
+                error: `Schema validation failed: ${e.message}. Ensure JSON conforms to ASTRO schema with required fields like stage_key, status, etc.`,
+            };
+        }
+        else {
+            return {
+                baton_md: norm,
+                astro_json: null,
+                astro_json_raw: null,
+                error: `JSON parsing failed: ${String(e)}. Ensure valid JSON syntax between ${ASTRO_JSON_BEGIN} and ${ASTRO_JSON_END} markers.`,
+            };
+        }
+    }
+}
+export function buildBatonSummary(opts) {
+    const { config, stage_key, astro_json, baton_md } = opts;
+    const maxLines = config.context_compaction.baton_summary_max_lines;
+    const lines = [];
+    lines.push(`# ${stage_key} — Summary`);
+    if (astro_json?.summary) {
+        lines.push("", astro_json.summary.trim());
+    }
+    else {
+        // Fallback: first non-empty paragraph
+        const paras = baton_md.split(/\n\n+/).map((p) => p.trim()).filter(Boolean);
+        if (paras[0])
+            lines.push("", paras[0]);
+    }
+    const addList = (title, items) => {
+        if (!items.length)
+            return;
+        lines.push("", `## ${title}`);
+        for (const it of items.slice(0, 12))
+            lines.push(`- ${it}`);
+    };
+    addList("Decisions", astro_json?.decisions ?? []);
+    addList("Next actions", astro_json?.next_actions ?? []);
+    const files = astro_json?.files ?? [];
+    if (files.length) {
+        lines.push("", "## Files");
+        for (const f of files.slice(0, 15))
+            lines.push(`- \`${f.path}\` (${f.kind})${f.notes ? ` — ${f.notes}` : ""}`);
+    }
+    const evidence = astro_json?.evidence ?? [];
+    if (evidence.length) {
+        lines.push("", "## Evidence");
+        for (const ev of evidence.slice(0, 15))
+            lines.push(`- \`${ev.path}\` (${ev.kind})${ev.notes ? ` — ${ev.notes}` : ""}`);
+    }
+    const out = lines.join("\n").trim();
+    return clampLines(out, maxLines);
+}

package/dist/src/workflow/context.d.ts

@@ -0,0 +1,20 @@
+import type { AstrocodeConfig } from "../config/schema";
+import type { SqliteDb } from "../state/db";
+import type { RunRow, StageRunRow, StoryRow } from "../state/types";
+export declare function getRun(db: SqliteDb, runId: string): RunRow | null;
+export declare function getStory(db: SqliteDb, storyKey: string): StoryRow | null;
+export declare function listStageRuns(db: SqliteDb, runId: string): StageRunRow[];
+/**
+ * Check if a context snapshot is stale by comparing DB timestamps
+ */
+export declare function isContextSnapshotStale(snapshotText: string, db: SqliteDb, maxAgeSeconds?: number): boolean;
+/**
+ * Add staleness indicator to context snapshot if needed
+ */
+export declare function addStalenessIndicator(snapshotText: string, db: SqliteDb, maxAgeSeconds?: number): string;
+export declare function buildContextSnapshot(opts: {
+    db: SqliteDb;
+    config: AstrocodeConfig;
+    run_id: string;
+    next_action?: string;
+}): string;

package/dist/src/workflow/context.js

@@ -0,0 +1,113 @@
+import { clampLines } from "../shared/text";
+export function getRun(db, runId) {
+    const row = db.prepare("SELECT * FROM runs WHERE run_id = ?").get(runId);
+    return row ?? null;
+}
+export function getStory(db, storyKey) {
+    const row = db.prepare("SELECT * FROM stories WHERE story_key = ?").get(storyKey);
+    return row ?? null;
+}
+export function listStageRuns(db, runId) {
+    return db
+        .prepare("SELECT * FROM stage_runs WHERE run_id = ? ORDER BY stage_index ASC")
+        .all(runId);
+}
+function statusIcon(status) {
+    switch (status) {
+        case "completed":
+            return "✅";
+        case "running":
+            return "🟦";
+        case "failed":
+            return "⛔";
+        case "skipped":
+            return "⏭️";
+        case "pending":
+        default:
+            return "⬜";
+    }
+}
+/**
+ * Check if a context snapshot is stale by comparing DB timestamps
+ */
+export function isContextSnapshotStale(snapshotText, db, maxAgeSeconds = 300) {
+    // Extract run_id from snapshot
+    const runIdMatch = snapshotText.match(/Run: `([^`]+)`/);
+    if (!runIdMatch)
+        return true; // Can't validate without run_id
+    const runId = runIdMatch[1];
+    // Extract snapshot's claimed updated_at
+    const snapshotUpdatedMatch = snapshotText.match(/updated: ([^\)]+)\)/);
+    if (!snapshotUpdatedMatch)
+        return true; // Fallback to age-based check
+    try {
+        const snapshotUpdatedAt = snapshotUpdatedMatch[1];
+        const currentRun = db.prepare("SELECT updated_at FROM runs WHERE run_id = ?").get(runId);
+        if (!currentRun?.updated_at)
+            return true; // Run doesn't exist
+        // Compare timestamps - if DB is newer than snapshot claims, snapshot is stale
+        const snapshotTime = new Date(snapshotUpdatedAt).getTime();
+        const currentTime = new Date(currentRun.updated_at).getTime();
+        return currentTime > snapshotTime;
+    }
+    catch (error) {
+        // Fallback to age-based staleness if parsing fails
+        const timestampMatch = snapshotText.match(/generated: (\d{4}-\d{2}-\d{2}T\d{2}:\d{2}:\d{2}\.\d{3}Z)/);
+        if (!timestampMatch)
+            return false;
+        const generatedAt = new Date(timestampMatch[1]);
+        const now = new Date();
+        const ageSeconds = (now.getTime() - generatedAt.getTime()) / 1000;
+        return ageSeconds > maxAgeSeconds;
+    }
+}
+/**
+ * Add staleness indicator to context snapshot if needed
+ */
+export function addStalenessIndicator(snapshotText, db, maxAgeSeconds = 300) {
+    if (isContextSnapshotStale(snapshotText, db, maxAgeSeconds)) {
+        return snapshotText.replace(/# Astrocode Context \(generated: ([^\)]+)\)/, "# Astrocode Context (generated: $1) ⚠️ STALE - DB state has changed");
+    }
+    return snapshotText;
+}
+export function buildContextSnapshot(opts) {
+    const { db, config, run_id, next_action } = opts;
+    const run = getRun(db, run_id);
+    if (!run)
+        return `Run not found: ${run_id}`;
+    const story = getStory(db, run.story_key);
+    const stageRuns = listStageRuns(db, run_id);
+    const lines = [];
+    // Add timestamps for staleness checking
+    const now = new Date();
+    const timestamp = now.toISOString();
+    lines.push(`# Astrocode Context (generated: ${timestamp})`);
+    lines.push(`- Run: \`${run.run_id}\`  Status: **${run.status}** (updated: ${run.updated_at})`);
+    if (run.current_stage_key)
+        lines.push(`- Current stage: \`${run.current_stage_key}\``);
+    if (next_action)
+        lines.push(`- Next action: ${next_action}`);
+    if (story) {
+        lines.push(`- Story: \`${story.story_key}\` — ${story.title}`);
+        if (story.body_md?.trim()) {
+            const first = story.body_md.trim().split(/\n\n+/)[0]?.trim();
+            if (first)
+                lines.push(`- Story summary: ${first}`);
+        }
+    }
+    lines.push(``, `## Pipeline`);
+    for (const s of stageRuns) {
+        lines.push(`- ${statusIcon(s.status)} \`${s.stage_key}\` (${s.status})`);
+    }
+    const completed = stageRuns.filter((s) => s.status === "completed" && (s.summary_md ?? "").trim());
+    const lastSummaries = completed.slice(-config.context_compaction.snapshot_after_stage_count);
+    if (lastSummaries.length) {
+        lines.push(``, `## Recent stage summaries`);
+        for (const s of lastSummaries) {
+            lines.push(``, `### ${s.stage_key}`);
+            lines.push((s.summary_md ?? "").trim());
+        }
+    }
+    const out = lines.join("\n").trim();
+    return clampLines(out, config.context_compaction.snapshot_max_lines);
+}

package/dist/src/workflow/directives.d.ts

@@ -0,0 +1,39 @@
+import type { AstrocodeConfig } from "../config/schema";
+import type { StageKey } from "../state/types";
+export type DirectiveKind = "continue" | "stage" | "blocked" | "repair";
+export type BuiltDirective = {
+    kind: DirectiveKind;
+    title: string;
+    body: string;
+    hash: string;
+};
+export declare function directiveHash(body: string): string;
+export declare function buildContinueDirective(opts: {
+    config: AstrocodeConfig;
+    run_id: string;
+    stage_key: string | null;
+    next_action: string;
+    context_snapshot_md: string;
+}): BuiltDirective;
+export declare function buildBlockedDirective(opts: {
+    config?: AstrocodeConfig;
+    run_id: string;
+    stage_key: string;
+    question: string;
+    context_snapshot_md: string;
+}): BuiltDirective;
+export declare function buildRepairDirective(opts: {
+    config?: AstrocodeConfig;
+    report_md: string;
+}): BuiltDirective;
+export declare function buildStageDirective(opts: {
+    config: AstrocodeConfig;
+    stage_key: StageKey;
+    run_id: string;
+    story_key: string;
+    story_title: string;
+    stage_agent_name: string;
+    stage_goal: string;
+    stage_constraints: string[];
+    context_snapshot_md: string;
+}): BuiltDirective;

package/dist/src/workflow/directives.js

@@ -0,0 +1,137 @@
+import { sha256Hex } from "../shared/hash";
+import { clampChars, normalizeNewlines } from "../shared/text";
+function getInjectMaxChars(config) {
+    // Deterministic fallback for older configs.
+    const v = config?.context_compaction?.inject_max_chars;
+    return typeof v === "number" && Number.isFinite(v) && v > 0 ? v : 12000;
+}
+export function directiveHash(body) {
+    // Stable hash to dedupe: normalize newlines + trim
+    const norm = normalizeNewlines(body).trim();
+    return sha256Hex(norm);
+}
+function finalizeBody(body, maxChars) {
+    // Normalize first, clamp second, trim last => hash/body match exactly.
+    const norm = normalizeNewlines(body);
+    const clamped = clampChars(norm, maxChars);
+    return clamped.trim();
+}
+export function buildContinueDirective(opts) {
+    const { config, run_id, stage_key, next_action, context_snapshot_md } = opts;
+    const maxChars = getInjectMaxChars(config);
+    const body = finalizeBody([
+        `[SYSTEM DIRECTIVE: ASTROCODE — CONTINUE]`,
+        ``,
+        `This directive is injected by the Astro agent to continue the workflow.`,
+        ``,
+        `Run: \`${run_id}\`${stage_key ? `  Stage: \`${stage_key}\`` : ""}`,
+        ``,
+        `Next action: ${next_action}`,
+        ``,
+        `Rules:`,
+        `- Do not stop early. Keep going until the run is completed, failed, or blocked.`,
+        `- Prefer tools over prose.`,
+        `- If blocked, ask exactly ONE question and stop.`,
+        ``,
+        `Context snapshot:`,
+        (context_snapshot_md ?? "").trim(),
+    ].join("\n"), maxChars);
+    return {
+        kind: "continue",
+        title: "ASTROCODE — CONTINUE",
+        body,
+        hash: directiveHash(body),
+    };
+}
+export function buildBlockedDirective(opts) {
+    const { config, run_id, stage_key, question, context_snapshot_md } = opts;
+    const maxChars = getInjectMaxChars(config);
+    const body = finalizeBody([
+        `[SYSTEM DIRECTIVE: ASTROCODE — BLOCKED]`,
+        ``,
+        `This directive is injected by the Astro agent indicating the workflow is blocked.`,
+        ``,
+        `Run: \`${run_id}\`  Stage: \`${stage_key}\``,
+        ``,
+        `You are blocked. Ask the user exactly ONE question (below), then stop.`,
+        ``,
+        `Question: ${question}`,
+        ``,
+        `Context snapshot:`,
+        (context_snapshot_md ?? "").trim(),
+    ].join("\n"), maxChars);
+    return {
+        kind: "blocked",
+        title: "ASTROCODE — BLOCKED",
+        body,
+        hash: directiveHash(body),
+    };
+}
+export function buildRepairDirective(opts) {
+    const maxChars = getInjectMaxChars(opts.config);
+    const body = finalizeBody([
+        `[SYSTEM DIRECTIVE: ASTROCODE — REPAIR]`,
+        ``,
+        `This directive is injected by the Astro agent after performing a repair pass.`,
+        ``,
+        `Astrocode performed a repair pass. Summarize in <= 10 lines and continue.`,
+        ``,
+        `Repair report:`,
+        (opts.report_md ?? "").trim(),
+    ].join("\n"), maxChars);
+    return {
+        kind: "repair",
+        title: "ASTROCODE — REPAIR",
+        body,
+        hash: directiveHash(body),
+    };
+}
+export function buildStageDirective(opts) {
+    const { config, stage_key, run_id, story_key, story_title, stage_agent_name, stage_goal, stage_constraints, context_snapshot_md, } = opts;
+    const maxChars = getInjectMaxChars(config);
+    const stageKeyUpper = String(stage_key).toUpperCase();
+    const constraintsBlock = Array.isArray(stage_constraints) && stage_constraints.length
+        ? ["", "Constraints:", ...stage_constraints.map((c) => `- ${c}`)].join("\n")
+        : "";
+    const body = finalizeBody([
+        `[SYSTEM DIRECTIVE: ASTROCODE — STAGE_${stageKeyUpper}]`,
+        ``,
+        `This directive is injected by the Astro agent to delegate the stage task.`,
+        ``,
+        `You are: \`${stage_agent_name}\``,
+        `Run: \`${run_id}\``,
+        `Story: \`${story_key}\` — ${story_title}`,
+        ``,
+        `Stage goal: ${stage_goal}`,
+        constraintsBlock,
+        ``,
+        `Output contract (strict):`,
+        `1) Baton markdown (short, structured)`,
+        `2) ASTRO JSON between markers:`,
+        `   <!-- ASTRO_JSON_BEGIN -->`,
+        `   {`,
+        `     "schema_version": 1,`,
+        `     "stage_key": "${stage_key}",`,
+        `     "status": "ok",`,
+        `     "...": "..."`,
+        `   }`,
+        `   <!-- ASTRO_JSON_END -->`,
+        ``,
+        `ASTRO JSON requirements:`,
+        `- stage_key must be "${stage_key}"`,
+        `- status must be "ok" | "blocked" | "failed"`,
+        `- include summary + next_actions`,
+        `- include files/evidence paths when relevant`,
+        ``,
+        `If blocked: ask exactly ONE question and stop.`,
+        ``,
+        `Context snapshot:`,
+        (context_snapshot_md ?? "").trim(),
+    ].join("\n"), maxChars);
+    return {
+        kind: "stage",
+        title: `ASTROCODE — STAGE_${stageKeyUpper}`,
+        body,
+        hash: directiveHash(body),
+    };
+}

package/dist/src/workflow/repair.d.ts

@@ -0,0 +1,8 @@
+import type { AstrocodeConfig } from "../config/schema";
+import type { SqliteDb } from "../state/db";
+export type RepairReport = {
+    actions: string[];
+    warnings: string[];
+};
+export declare function repairState(db: SqliteDb, config: AstrocodeConfig): RepairReport;
+export declare function formatRepairReport(report: RepairReport): string;

package/dist/src/workflow/repair.js

@@ -0,0 +1,99 @@
+import { nowISO } from "../shared/time";
+import { newEventId, newStageRunId } from "../state/ids";
+function push(report, line) {
+    report.actions.push(line);
+}
+function warn(report, line) {
+    report.warnings.push(line);
+}
+export function repairState(db, config) {
+    const report = { actions: [], warnings: [] };
+    const now = nowISO();
+    // 1) Multiple running runs -> abort extras (keep most recent started_at)
+    const running = db
+        .prepare("SELECT * FROM runs WHERE status='running' ORDER BY started_at DESC, created_at DESC")
+        .all();
+    if (running.length > 1) {
+        const keep = running[0];
+        for (const r of running.slice(1)) {
+            db.prepare("UPDATE runs SET status='aborted', error_text=?, completed_at=?, updated_at=? WHERE run_id=?").run("repair: multiple running runs", now, now, r.run_id);
+            // unlock story
+            db.prepare("UPDATE stories SET state='approved', in_progress=0, locked_by_run_id=NULL, locked_at=NULL, updated_at=? WHERE story_key=?").run(now, r.story_key);
+            db.prepare("INSERT INTO events (event_id, run_id, stage_key, type, body_json, created_at) VALUES (?, ?, NULL, 'run.aborted', ?, ?)").run(newEventId(), r.run_id, JSON.stringify({ reason: "repair: multiple running runs" }), now);
+            push(report, `Aborted extra running run ${r.run_id} (kept ${keep.run_id})`);
+        }
+    }
+    // 2) Fix story locks for the active run
+    const active = db.prepare("SELECT * FROM runs WHERE status='running' ORDER BY started_at DESC LIMIT 1").get();
+    if (active) {
+        const story = db.prepare("SELECT * FROM stories WHERE story_key=?").get(active.story_key);
+        if (!story) {
+            warn(report, `Active run ${active.run_id} references missing story ${active.story_key}`);
+        }
+        else {
+            if (story.locked_by_run_id !== active.run_id || story.in_progress !== 1 || story.state !== "in_progress") {
+                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(active.run_id, now, now, story.story_key);
+                push(report, `Repaired story lock for ${story.story_key} to run ${active.run_id}`);
+            }
+        }
+        // 3) Ensure stage_runs exist for pipeline
+        const pipeline = JSON.parse(active.pipeline_stages_json ?? "[]");
+        const stageRuns = db
+            .prepare("SELECT * FROM stage_runs WHERE run_id=? ORDER BY stage_index ASC")
+            .all(active.run_id);
+        if (stageRuns.length < pipeline.length) {
+            const existingKeys = new Set(stageRuns.map((s) => s.stage_key));
+            const insert = db.prepare("INSERT INTO stage_runs (stage_run_id, run_id, stage_key, stage_index, status, created_at, updated_at) VALUES (?, ?, ?, ?, 'pending', ?, ?)");
+            pipeline.forEach((key, idx) => {
+                if (!existingKeys.has(key)) {
+                    insert.run(newStageRunId(), active.run_id, key, idx, now, now);
+                    push(report, `Inserted missing stage_run ${key} for run ${active.run_id}`);
+                }
+            });
+        }
+        // 4) If current_stage_key missing, set to first incomplete
+        const refreshed = db
+            .prepare("SELECT * FROM stage_runs WHERE run_id=? ORDER BY stage_index ASC")
+            .all(active.run_id);
+        const cur = refreshed.find((s) => s.status !== "completed" && s.status !== "skipped");
+        if (cur && active.current_stage_key !== cur.stage_key) {
+            db.prepare("UPDATE runs SET current_stage_key=?, updated_at=? WHERE run_id=?").run(cur.stage_key, now, active.run_id);
+            push(report, `Set run.current_stage_key to ${cur.stage_key} for ${active.run_id}`);
+        }
+    }
+    // 5) Orphaned story locks (in_progress=1 but no running run)
+    const lockedStories = db
+        .prepare("SELECT * FROM stories WHERE in_progress=1")
+        .all();
+    for (const s of lockedStories) {
+        const run = s.locked_by_run_id
+            ? db.prepare("SELECT * FROM runs WHERE run_id=?").get(s.locked_by_run_id)
+            : undefined;
+        if (!run || run.status !== "running") {
+            db.prepare("UPDATE stories SET in_progress=0, locked_by_run_id=NULL, locked_at=NULL, updated_at=? WHERE story_key=?").run(now, s.story_key);
+            // Keep state conservative: if it was in_progress but no run, revert to approved.
+            db.prepare("UPDATE stories SET state='approved', updated_at=? WHERE story_key=? AND state='in_progress'").run(now, s.story_key);
+            push(report, `Cleared orphaned lock on story ${s.story_key}`);
+        }
+    }
+    if (!report.actions.length && !report.warnings.length) {
+        report.actions.push("No repairs needed.");
+    }
+    // Event marker
+    db.prepare("INSERT INTO events (event_id, run_id, stage_key, type, body_json, created_at) VALUES (?, NULL, NULL, 'repair.completed', ?, ?)").run(newEventId(), JSON.stringify({ actions: report.actions, warnings: report.warnings, schema: config.db.schema_version_required }), now);
+    return report;
+}
+export function formatRepairReport(report) {
+    const lines = [];
+    lines.push("# Astrocode repair report");
+    lines.push("");
+    lines.push("## Actions");
+    for (const a of report.actions)
+        lines.push(`- ${a}`);
+    if (report.warnings.length) {
+        lines.push("", "## Warnings");
+        for (const w of report.warnings)
+            lines.push(`- ${w}`);
+    }
+    return lines.join("\n").trim();
+}

package/dist/src/workflow/state-machine.d.ts

@@ -0,0 +1,86 @@
+import type { AstrocodeConfig } from "../config/schema";
+import type { SqliteDb } from "../state/db";
+import type { RunRow, StageKey, StageRunRow, StoryRow } from "../state/types";
+export declare const EVENT_TYPES: {
+    readonly RUN_STARTED: "run.started";
+    readonly RUN_COMPLETED: "run.completed";
+    readonly RUN_FAILED: "run.failed";
+    readonly RUN_ABORTED: "run.aborted";
+    readonly RUN_GENESIS_PLANNING_ATTACHED: "run.genesis_planning_attached";
+    readonly STAGE_STARTED: "stage.started";
+    readonly WORKFLOW_PROCEED: "workflow.proceed";
+};
+export type UiEmitEvent = {
+    kind: "stage_started";
+    run_id: string;
+    stage_key: StageKey;
+    agent_name?: string;
+} | {
+    kind: "run_completed";
+    run_id: string;
+    story_key: string;
+} | {
+    kind: "run_failed";
+    run_id: string;
+    story_key: string;
+    stage_key: StageKey;
+    error_text: string;
+};
+export type UiEmit = (e: UiEmitEvent) => void;
+/**
+ * PLANNING-FIRST REDESIGN
+ * ----------------------
+ * Never mutate story title/body.
+ *
+ * Deterministic trigger:
+ * - config.workflow.genesis_planning:
+ *    - "off"             => never attach directive
+ *    - "first_story_only"=> only when story_key === "S-0001"
+ *    - "always"          => attach for every run
+ *
+ * Contract: DB is already initialized before workflow is used:
+ * - schema tables exist
+ * - repo_state singleton row (id=1) exists
+ *
+ * IMPORTANT: Do NOT call withTx() in here. The caller owns transaction boundaries.
+ */
+export type NextAction = {
+    kind: "idle";
+    reason: "no_approved_stories";
+} | {
+    kind: "start_run";
+    story_key: string;
+} | {
+    kind: "delegate_stage";
+    run_id: string;
+    stage_key: StageKey;
+    stage_run_id: string;
+} | {
+    kind: "await_stage_completion";
+    run_id: string;
+    stage_key: StageKey;
+    stage_run_id: string;
+} | {
+    kind: "complete_run";
+    run_id: string;
+} | {
+    kind: "failed";
+    run_id: string;
+    stage_key: StageKey;
+    error_text: string;
+};
+export declare function getActiveRun(db: SqliteDb): RunRow | null;
+export declare function getStory(db: SqliteDb, storyKey: string): StoryRow | null;
+export declare function getStageRuns(db: SqliteDb, runId: string): StageRunRow[];
+export declare function getCurrentStageRun(stageRuns: StageRunRow[]): StageRunRow | null;
+export declare function decideNextAction(db: SqliteDb, config: AstrocodeConfig): NextAction;
+export declare function createRunForStory(db: SqliteDb, config: AstrocodeConfig, storyKey: string): {
+    run_id: string;
+};
+export declare function startStage(db: SqliteDb, runId: string, stageKey: StageKey, meta?: {
+    subagent_type?: string;
+    subagent_session_id?: string;
+}, emit?: UiEmit): void;
+export declare function completeRun(db: SqliteDb, runId: string, emit?: UiEmit): void;
+export declare function failRun(db: SqliteDb, runId: string, stageKey: StageKey, errorText: string, emit?: UiEmit): void;
+export declare function abortRun(db: SqliteDb, runId: string, reason: string): void;