astrocode-workflow 0.1.58 → 0.2.0

package/src/workflow/state-machine.ts

@@ -1,12 +1,86 @@
+// src/workflow/state-machine.ts
 import type { AstrocodeConfig } from "../config/schema";
-import fs from "node:fs";
-import path from "node:path";
 import type { SqliteDb } from "../state/db";
+import { withTx } from "../state/db";
 import type { RunRow, StageKey, StageRunRow, StoryRow } from "../state/types";
 import { nowISO } from "../shared/time";
 import { newEventId, newRunId, newStageRunId } from "../state/ids";
 import { warn } from "../shared/log";
+import { sha256Hex } from "../shared/hash";
+import { SCHEMA_VERSION } from "../state/schema";
+import type { ToastOptions } from "../ui/toasts";
+import { injectChatPrompt } from "../ui/inject";
+
+export const EVENT_TYPES = {
+  RUN_STARTED: "run.started",
+  RUN_COMPLETED: "run.completed",
+  RUN_FAILED: "run.failed",
+  RUN_ABORTED: "run.aborted",
+  RUN_GENESIS_PLANNING_ATTACHED: "run.genesis_planning_attached",
+  STAGE_STARTED: "stage.started",
+  WORKFLOW_PROCEED: "workflow.proceed",
+} as const;
+
+/**
+ * UI HOOKS
+ * --------
+ * This workflow module is DB-first. UI emission is optional and happens AFTER the DB tx commits.
+ *
+ * Contract:
+ * - If you pass ui.ctx + ui.sessionId, we will inject a visible chat message deterministically.
+ * - If you pass ui.toast, we will also toast (throttling is handled by the toast manager).
+ */
+export type WorkflowUi = {
+  ctx: any;
+  sessionId: string;
+  agentName?: string; // label for injected chat messages
+  toast?: (t: ToastOptions) => Promise<void>;
+};
+
+async function emitUi(ui: WorkflowUi | undefined, text: string, toast?: ToastOptions): Promise<void> {
+  if (!ui) return;
+
+  // Prefer toast (if provided) AND also inject chat (for audit trail / visibility).
+  // If you want toast-only, pass a toast function and omit ctx/sessionId.
+  if (toast && ui.toast) {
+    try {
+      await ui.toast(toast);
+    } catch {
+      // non-fatal
+    }
+  }
 
+  try {
+    await injectChatPrompt({
+      ctx: ui.ctx,
+      sessionId: ui.sessionId,
+      text,
+      agent: ui.agentName ?? "Astro",
+    });
+  } catch {
+    // non-fatal (workflow correctness is DB-based)
+  }
+}
+
+function tableExists(db: SqliteDb, tableName: string): boolean {
+  try {
+    const row = db
+      .prepare("SELECT name FROM sqlite_master WHERE type='table' AND name=?")
+      .get(tableName) as { name?: string } | undefined;
+    return row?.name === tableName;
+  } catch {
+    return false;
+  }
+}
+
+/**
+ * PLANNING-FIRST REDESIGN
+ * ----------------------
+ * - Never mutate story title/body.
+ * - Planning-first becomes a run-scoped inject stored in `injects` (scope = run:<run_id>).
+ * - Trigger is deterministic via config.workflow.genesis_planning:
+ *    - "off" | "first_story_only" | "always"
+ */
 export type NextAction =
   | { kind: "idle"; reason: "no_approved_stories" }
   | { kind: "start_run"; story_key: string }
@@ -53,9 +127,7 @@ export function decideNextAction(db: SqliteDb, config: AstrocodeConfig): NextAct
   const stageRuns = getStageRuns(db, activeRun.run_id);
   const current = getCurrentStageRun(stageRuns);
 
-  if (!current) {
-    return { kind: "complete_run", run_id: activeRun.run_id };
-  }
+  if (!current) return { kind: "complete_run", run_id: activeRun.run_id };
 
   if (current.status === "pending") {
     return { kind: "delegate_stage", run_id: activeRun.run_id, stage_key: current.stage_key, stage_run_id: current.stage_run_id };
@@ -69,149 +141,295 @@ export function decideNextAction(db: SqliteDb, config: AstrocodeConfig): NextAct
     return { kind: "failed", run_id: activeRun.run_id, stage_key: current.stage_key, error_text: current.error_text ?? "stage failed" };
   }
 
-  // Should never happen: other statuses are handled above
-  warn("Unexpected stage status in decideNextAction", { status: current.status, stage_key: current.stage_key });
+  warn("Unexpected stage status in decideNextAction", { status: current.status, stage_key: current.status });
   return { kind: "await_stage_completion", run_id: activeRun.run_id, stage_key: current.stage_key, stage_run_id: current.stage_run_id };
 }
 
-function isInitialStory(db: SqliteDb, storyKey: string): boolean {
-  // Check if this story has no parent relations (is top-level)
-  const relations = db.prepare("SELECT COUNT(*) as count FROM story_relations WHERE child_story_key=?").get(storyKey) as { count: number };
-  return relations.count === 0;
+function getPipelineFromConfig(config: AstrocodeConfig): StageKey[] {
+  const pipeline = (config as any)?.workflow?.pipeline as StageKey[] | undefined;
+  if (!Array.isArray(pipeline) || pipeline.length === 0) {
+    throw new Error("Invalid config: workflow.pipeline must be a non-empty array of stage keys.");
+  }
+  return pipeline;
 }
 
-export function createRunForStory(db: SqliteDb, config: AstrocodeConfig, storyKey: string): { run_id: string } {
-  const story = getStory(db, storyKey);
-  if (!story) throw new Error(`Story not found: ${storyKey}`);
-  if (story.state !== "approved") throw new Error(`Story must be approved to run: ${storyKey} (state=${story.state})`);
+type GenesisPlanningMode = "off" | "first_story_only" | "always";
 
-  const run_id = newRunId();
-  const now = nowISO();
-  const pipeline = config.workflow.pipeline;
+function getGenesisPlanningMode(config: AstrocodeConfig): GenesisPlanningMode {
+  const raw = (config as any)?.workflow?.genesis_planning;
+  if (raw === "off" || raw === "first_story_only" || raw === "always") return raw;
+  warn(`Invalid genesis_planning config: ${String(raw)}. Using default "first_story_only".`);
+  return "first_story_only";
+}
 
-  // Convert to genesis planning story if needed
-  const isGenesisCandidate = storyKey === 'S-0001' || isInitialStory(db, storyKey) ||
-    (story.body_md && story.body_md.length > 100 &&
-      (story.title.toLowerCase().includes('implement') || story.body_md.toLowerCase().includes('implement')));
+function shouldAttachPlanningDirective(config: AstrocodeConfig, story: StoryRow): boolean {
+  const mode = getGenesisPlanningMode(config);
+  if (mode === "off") return false;
+  if (mode === "always") return true;
+  return story.story_key === "S-0001";
+}
 
-  // Skip conversion if there are already many stories (spec already decomposed)
-  const existingStoriesCount = db.prepare("SELECT COUNT(*) as count FROM stories").get() as { count: number };
-  const alreadyDecomposed = existingStoriesCount.count > 10; // Arbitrary threshold
+function attachRunPlanningDirective(db: SqliteDb, runId: string, story: StoryRow, pipeline: StageKey[]) {
+  if (!tableExists(db, "injects")) return;
 
-  if (isGenesisCandidate && !alreadyDecomposed) {
-    const planningTitle = `Plan and decompose: ${story.title}`;
-    const planningBody = `Analyze the requirements and break down "${story.title}" into 50-200 detailed, granular implementation stories. Each story should be focused on a specific, implementable task with clear acceptance criteria.\n\nOriginal request: ${story.body_md || ''}`;
-    db.prepare("UPDATE stories SET title=?, body_md=? WHERE story_key=?").run(planningTitle, planningBody, storyKey);
+  const now = nowISO();
+  const injectId = `inj_${runId}_genesis_plan`;
+
+  const body = [
+    `# Genesis planning directive`,
+    ``,
+    `This run is configured to perform a planning/decomposition pass before implementation.`,
+    `Do not edit the origin story title/body. Create additional stories instead.`,
+    ``,
+    `## Required output`,
+    `- Produce 50–200 granular implementation stories with clear acceptance criteria.`,
+    `- Each story: single focused change, explicit done conditions, dependencies listed.`,
+    ``,
+    `## Context`,
+    `- Origin story: ${story.story_key} — ${story.title ?? ""}`,
+    `- Pipeline: ${pipeline.join(" → ")}`,
+    ``,
+  ].join("\n");
+
+  const hash = sha256Hex(body);
+
+  try {
+    db.prepare(
+      `
+      INSERT OR IGNORE INTO injects (
+        inject_id, type, title, body_md, tags_json, scope, source, priority,
+        expires_at, sha256, created_at, updated_at
+      ) VALUES (
+        ?, 'note', ?, ?, '["genesis","planning","decompose"]', ?, 'tool', 100,
+        NULL, ?, ?, ?
+      )
+    `
+    ).run(injectId, "Genesis planning: decompose into stories", body, `run:${runId}`, hash, now, now);
+
+    db.prepare(
+      "INSERT INTO events (event_id, run_id, stage_key, type, body_json, created_at) VALUES (?, ?, NULL, ?, ?, ?)"
+    ).run(newEventId(), runId, EVENT_TYPES.RUN_GENESIS_PLANNING_ATTACHED, JSON.stringify({ story_key: story.story_key, inject_id: injectId }), now);
+  } catch (e) {
+    warn("Failed to attach genesis planning inject", { run_id: runId, story_key: story.story_key, err: e });
   }
+}
 
-  // Lock story
-  db.prepare(
-    "UPDATE stories SET state='in_progress', in_progress=1, locked_by_run_id=?, locked_at=?, updated_at=? WHERE story_key=?"
-  ).run(run_id, now, now, storyKey);
+export function createRunForStory(db: SqliteDb, config: AstrocodeConfig, storyKey: string): { run_id: string } {
+  return withTx(db, () => {
+    const story = getStory(db, storyKey);
+    if (!story) throw new Error(`Story not found: ${storyKey}`);
+    if (story.state !== "approved") throw new Error(`Story must be approved to run: ${storyKey} (state=${story.state})`);
+
+    const run_id = newRunId();
+    const now = nowISO();
+    const pipeline = getPipelineFromConfig(config);
+
+    db.prepare(
+      "UPDATE stories SET state='in_progress', in_progress=1, locked_by_run_id=?, locked_at=?, updated_at=? WHERE story_key=?"
+    ).run(run_id, now, now, storyKey);
+
+    db.prepare(
+      "INSERT INTO runs (run_id, story_key, status, pipeline_stages_json, current_stage_key, created_at, started_at, updated_at) VALUES (?, ?, 'running', ?, ?, ?, ?, ?)"
+    ).run(run_id, storyKey, JSON.stringify(pipeline), pipeline[0] ?? null, now, now, now);
+
+    const insertStage = db.prepare(
+      "INSERT INTO stage_runs (stage_run_id, run_id, stage_key, stage_index, status, created_at, updated_at) VALUES (?, ?, ?, ?, 'pending', ?, ?)"
+    );
+    pipeline.forEach((stageKey, idx) => {
+      insertStage.run(newStageRunId(), run_id, stageKey, idx, now, now);
+    });
+
+    db.prepare(
+      "INSERT INTO events (event_id, run_id, stage_key, type, body_json, created_at) VALUES (?, ?, NULL, ?, ?, ?)"
+    ).run(newEventId(), run_id, EVENT_TYPES.RUN_STARTED, JSON.stringify({ story_key: storyKey, pipeline }), now);
+
+    if (shouldAttachPlanningDirective(config, story)) {
+      attachRunPlanningDirective(db, run_id, story, pipeline);
+    }
+
+    db.prepare(`
+      INSERT INTO repo_state (id, schema_version, created_at, updated_at, last_run_id, last_story_key, last_event_at)
+      VALUES (1, ?, ?, ?, ?, ?, ?)
+      ON CONFLICT(id) DO UPDATE SET
+        last_run_id=excluded.last_run_id,
+        last_story_key=excluded.last_story_key,
+        last_event_at=excluded.last_event_at,
+        updated_at=excluded.updated_at
+    `).run(SCHEMA_VERSION, now, now, run_id, storyKey, now);
+
+    return { run_id };
+  });
+}
 
-  db.prepare(
-    "INSERT INTO runs (run_id, story_key, status, pipeline_stages_json, current_stage_key, created_at, started_at, updated_at) VALUES (?, ?, 'running', ?, ?, ?, ?, ?)"
-  ).run(run_id, storyKey, JSON.stringify(pipeline), pipeline[0] ?? null, now, now, now);
+/**
+ * STAGE MOVEMENT (START) — now async so UI injection is deterministic.
+ */
+export async function startStage(
+  db: SqliteDb,
+  runId: string,
+  stageKey: StageKey,
+  meta?: { subagent_type?: string; subagent_session_id?: string; ui?: WorkflowUi }
+): Promise<void> {
+  // Do DB work inside tx, capture what we need for UI outside.
+  const payload = withTx(db, () => {
+    const now = nowISO();
+
+    const run = db.prepare("SELECT * FROM runs WHERE run_id=?").get(runId) as RunRow | undefined;
+    if (!run) throw new Error(`Run not found: ${runId}`);
+    if (run.status !== "running") throw new Error(`Run is not running: ${runId} (status=${run.status})`);
+
+    const stage = db.prepare("SELECT * FROM stage_runs WHERE run_id=? AND stage_key=?").get(runId, stageKey) as StageRunRow | undefined;
+    if (!stage) throw new Error(`Stage run not found: ${runId}/${stageKey}`);
+    if (stage.status !== "pending") throw new Error(`Stage is not pending: ${stageKey} (status=${stage.status})`);
+
+    db.prepare(
+      "UPDATE stage_runs SET status='running', started_at=?, updated_at=?, subagent_type=COALESCE(?, subagent_type), subagent_session_id=COALESCE(?, subagent_session_id) WHERE stage_run_id=?"
+    ).run(now, now, meta?.subagent_type ?? null, meta?.subagent_session_id ?? null, stage.stage_run_id);
+
+    db.prepare("UPDATE runs SET current_stage_key=?, updated_at=? WHERE run_id=?").run(stageKey, now, runId);
+
+    db.prepare(
+      "INSERT INTO events (event_id, run_id, stage_key, type, body_json, created_at) VALUES (?, ?, ?, ?, ?, ?)"
+    ).run(newEventId(), runId, stageKey, EVENT_TYPES.STAGE_STARTED, JSON.stringify({ subagent_type: meta?.subagent_type ?? null }), now);
+
+    db.prepare("UPDATE repo_state SET last_event_at=?, updated_at=? WHERE id=1").run(now, now);
+
+    const story = db.prepare("SELECT story_key, title FROM stories WHERE story_key=?").get(run.story_key) as any;
+
+    return {
+      now,
+      story_key: run.story_key,
+      story_title: story?.title ?? "",
+    };
+  });
 
-  // Stage runs
-  const insertStage = db.prepare(
-    "INSERT INTO stage_runs (stage_run_id, run_id, stage_key, stage_index, status, updated_at) VALUES (?, ?, ?, ?, 'pending', ?)"
+  // Deterministic UI emission AFTER commit (never inside tx).
+  await emitUi(
+    meta?.ui,
+    [
+      `🟦 Stage started`,
+      `- Run: \`${runId}\``,
+      `- Stage: \`${stageKey}\``,
+      `- Story: \`${payload.story_key}\` — ${payload.story_title || "(untitled)"}`,
+    ].join("\n"),
+    {
+      title: "Stage started",
+      message: `${stageKey} (${payload.story_key})`,
+      variant: "info",
+      durationMs: 2500,
+    }
   );
+}
 
-  pipeline.forEach((stageKey, idx) => {
-    insertStage.run(newStageRunId(), run_id, stageKey, idx, now);
-  });
+/**
+ * STAGE CLOSED (RUN COMPLETED) — now async so UI injection is deterministic.
+ */
+export async function completeRun(db: SqliteDb, runId: string, ui?: WorkflowUi): Promise<void> {
+  const payload = withTx(db, () => {
+    const now = nowISO();
 
-  // Event
-  db.prepare(
-    "INSERT INTO events (event_id, run_id, stage_key, type, body_json, created_at) VALUES (?, ?, NULL, 'run.started', ?, ?)"
-  ).run(newEventId(), run_id, JSON.stringify({ story_key: storyKey, pipeline }), now);
+    const run = db.prepare("SELECT * FROM runs WHERE run_id=?").get(runId) as RunRow | undefined;
+    if (!run) throw new Error(`Run not found: ${runId}`);
+    if (run.status !== "running") throw new Error(`Run not running: ${runId} (status=${run.status})`);
 
-  db.prepare("UPDATE repo_state SET last_run_id=?, last_story_key=?, last_event_at=?, updated_at=? WHERE id=1").run(run_id, storyKey, now, now);
+    const stageRuns = getStageRuns(db, runId);
+    const incomplete = stageRuns.find((s) => s.status !== "completed" && s.status !== "skipped");
+    if (incomplete) throw new Error(`Cannot complete run: stage ${incomplete.stage_key} is ${incomplete.status}`);
 
-  return { run_id };
-}
+    db.prepare("UPDATE runs SET status='completed', completed_at=?, updated_at=?, current_stage_key=NULL WHERE run_id=?").run(now, now, runId);
 
-export function startStage(db: SqliteDb, runId: string, stageKey: StageKey, meta?: { subagent_type?: string; subagent_session_id?: string }) {
-  const now = nowISO();
+    db.prepare(
+      "UPDATE stories SET state='done', in_progress=0, locked_by_run_id=NULL, locked_at=NULL, updated_at=? WHERE story_key=?"
+    ).run(now, run.story_key);
 
-  // Ensure run is running
-  const run = db.prepare("SELECT * FROM runs WHERE run_id=?").get(runId) as RunRow | undefined;
-  if (!run) throw new Error(`Run not found: ${runId}`);
-  if (run.status !== "running") throw new Error(`Run is not running: ${runId} (status=${run.status})`);
+    db.prepare(
+      "INSERT INTO events (event_id, run_id, stage_key, type, body_json, created_at) VALUES (?, ?, NULL, ?, ?, ?)"
+    ).run(newEventId(), runId, EVENT_TYPES.RUN_COMPLETED, JSON.stringify({ story_key: run.story_key }), now);
 
-  const stage = db
-    .prepare("SELECT * FROM stage_runs WHERE run_id=? AND stage_key=?")
-    .get(runId, stageKey) as StageRunRow | undefined;
-  if (!stage) throw new Error(`Stage run not found: ${runId}/${stageKey}`);
-  if (stage.status !== "pending") throw new Error(`Stage is not pending: ${stageKey} (status=${stage.status})`);
+    db.prepare("UPDATE repo_state SET last_event_at=?, updated_at=? WHERE id=1").run(now, now);
 
-  db.prepare(
-    "UPDATE stage_runs SET status='running', started_at=?, updated_at=?, subagent_type=COALESCE(?, subagent_type), subagent_session_id=COALESCE(?, subagent_session_id) WHERE stage_run_id=?"
-  ).run(now, now, meta?.subagent_type ?? null, meta?.subagent_session_id ?? null, stage.stage_run_id);
+    const story = db.prepare("SELECT story_key, title FROM stories WHERE story_key=?").get(run.story_key) as any;
 
-  db.prepare("UPDATE runs SET current_stage_key=?, updated_at=? WHERE run_id=?").run(stageKey, now, runId);
+    return { now, story_key: run.story_key, story_title: story?.title ?? "" };
+  });
 
-  db.prepare(
-    "INSERT INTO events (event_id, run_id, stage_key, type, body_json, created_at) VALUES (?, ?, ?, 'stage.started', ?, ?)"
-  ).run(newEventId(), runId, stageKey, JSON.stringify({ subagent_type: meta?.subagent_type ?? null }), now);
+  await emitUi(
+    ui,
+    [
+      `✅ Run completed`,
+      `- Run: \`${runId}\``,
+      `- Story: \`${payload.story_key}\` — ${payload.story_title || "(untitled)"}`,
+    ].join("\n"),
+    {
+      title: "Run completed",
+      message: `${payload.story_key} — done`,
+      variant: "success",
+      durationMs: 3000,
+    }
+  );
 }
 
-export function completeRun(db: SqliteDb, runId: string) {
-  const now = nowISO();
-  const run = db.prepare("SELECT * FROM runs WHERE run_id=?").get(runId) as RunRow | undefined;
-  if (!run) throw new Error(`Run not found: ${runId}`);
-  if (run.status !== "running") throw new Error(`Run not running: ${runId} (status=${run.status})`);
+/**
+ * STAGE CLOSED (RUN FAILED) — now async so UI injection is deterministic.
+ */
+export async function failRun(db: SqliteDb, runId: string, stageKey: StageKey, errorText: string, ui?: WorkflowUi): Promise<void> {
+  const payload = withTx(db, () => {
+    const now = nowISO();
 
-  // Ensure all stages completed/skipped
-  const stageRuns = getStageRuns(db, runId);
-  const incomplete = stageRuns.find((s) => s.status !== "completed" && s.status !== "skipped");
-  if (incomplete) throw new Error(`Cannot complete run: stage ${incomplete.stage_key} is ${incomplete.status}`);
+    const run = db.prepare("SELECT * FROM runs WHERE run_id=?").get(runId) as RunRow | undefined;
+    if (!run) throw new Error(`Run not found: ${runId}`);
 
-  db.prepare("UPDATE runs SET status='completed', completed_at=?, updated_at=?, current_stage_key=NULL WHERE run_id=?").run(now, now, runId);
-  db.prepare(
-    "UPDATE stories SET state='done', in_progress=0, locked_by_run_id=NULL, locked_at=NULL, updated_at=? WHERE story_key=?"
-  ).run(now, run.story_key);
+    db.prepare("UPDATE runs SET status='failed', error_text=?, updated_at=?, completed_at=? WHERE run_id=?").run(errorText, now, now, runId);
 
-  db.prepare(
-    "INSERT INTO events (event_id, run_id, stage_key, type, body_json, created_at) VALUES (?, ?, NULL, 'run.completed', ?, ?)"
-  ).run(newEventId(), runId, JSON.stringify({ story_key: run.story_key }), now);
+    db.prepare(
+      "UPDATE stories SET state='blocked', in_progress=0, locked_by_run_id=NULL, locked_at=NULL, updated_at=? WHERE story_key=?"
+    ).run(now, run.story_key);
 
-  db.prepare("UPDATE repo_state SET last_event_at=?, updated_at=? WHERE id=1").run(now, now);
-}
+    db.prepare(
+      "INSERT INTO events (event_id, run_id, stage_key, type, body_json, created_at) VALUES (?, ?, ?, ?, ?, ?)"
+    ).run(newEventId(), runId, stageKey, EVENT_TYPES.RUN_FAILED, JSON.stringify({ error_text: errorText }), now);
 
-export function failRun(db: SqliteDb, runId: string, stageKey: StageKey, errorText: string) {
-  const now = nowISO();
-  const run = db.prepare("SELECT * FROM runs WHERE run_id=?").get(runId) as RunRow | undefined;
-  if (!run) throw new Error(`Run not found: ${runId}`);
+    db.prepare("UPDATE repo_state SET last_event_at=?, updated_at=? WHERE id=1").run(now, now);
 
-  db.prepare("UPDATE runs SET status='failed', error_text=?, updated_at=?, completed_at=? WHERE run_id=?").run(errorText, now, now, runId);
-  db.prepare(
-    "UPDATE stories SET state='blocked', in_progress=0, locked_by_run_id=NULL, locked_at=NULL, updated_at=? WHERE story_key=?"
-  ).run(now, run.story_key);
+    const story = db.prepare("SELECT story_key, title FROM stories WHERE story_key=?").get(run.story_key) as any;
 
-  db.prepare(
-    "INSERT INTO events (event_id, run_id, stage_key, type, body_json, created_at) VALUES (?, ?, ?, 'run.failed', ?, ?)"
-  ).run(newEventId(), runId, stageKey, JSON.stringify({ error_text: errorText }), now);
+    return { now, story_key: run.story_key, story_title: story?.title ?? "" };
+  });
 
-  db.prepare("UPDATE repo_state SET last_event_at=?, updated_at=? WHERE id=1").run(now, now);
+  await emitUi(
+    ui,
+    [
+      `⛔ Run failed`,
+      `- Run: \`${runId}\``,
+      `- Stage: \`${stageKey}\``,
+      `- Story: \`${payload.story_key}\` — ${payload.story_title || "(untitled)"}`,
+      `- Error: ${errorText}`,
+    ].join("\n"),
+    {
+      title: "Run failed",
+      message: `${stageKey}: ${errorText}`,
+      variant: "error",
+      durationMs: 4500,
+    }
+  );
 }
 
 export function abortRun(db: SqliteDb, runId: string, reason: string) {
-  const now = nowISO();
-  const run = db.prepare("SELECT * FROM runs WHERE run_id=?").get(runId) as RunRow | undefined;
-  if (!run) throw new Error(`Run not found: ${runId}`);
+  return withTx(db, () => {
+    const now = nowISO();
+    const run = db.prepare("SELECT * FROM runs WHERE run_id=?").get(runId) as RunRow | undefined;
+    if (!run) throw new Error(`Run not found: ${runId}`);
 
-  db.prepare("UPDATE runs SET status='aborted', error_text=?, updated_at=?, completed_at=? WHERE run_id=?").run(reason, now, now, runId);
+    db.prepare("UPDATE runs SET status='aborted', error_text=?, updated_at=?, completed_at=? WHERE run_id=?").run(reason, now, now, runId);
 
-  // Unlock story back to approved so it can be re-run.
-  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, run.story_key);
+    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, run.story_key);
 
-  db.prepare(
-    "INSERT INTO events (event_id, run_id, stage_key, type, body_json, created_at) VALUES (?, ?, NULL, 'run.aborted', ?, ?)"
-  ).run(newEventId(), runId, JSON.stringify({ reason }), now);
+    db.prepare(
+      "INSERT INTO events (event_id, run_id, stage_key, type, body_json, created_at) VALUES (?, ?, NULL, ?, ?, ?)"
+    ).run(newEventId(), runId, EVENT_TYPES.RUN_ABORTED, JSON.stringify({ reason }), now);
 
-  db.prepare("UPDATE repo_state SET last_event_at=?, updated_at=? WHERE id=1").run(now, now);
+    db.prepare("UPDATE repo_state SET last_event_at=?, updated_at=? WHERE id=1").run(now, now);
+  });
 }