astrocode-workflow 0.3.0 → 0.3.1

package/dist/workflow/state-machine.js

@@ -1,10 +1,8 @@
-import { withTx } from "../state/db";
 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 { injectChatPrompt } from "../ui/inject";
 export const EVENT_TYPES = {
     RUN_STARTED: "run.started",
     RUN_COMPLETED: "run.completed",
@@ -14,31 +12,6 @@ export const EVENT_TYPES = {
     STAGE_STARTED: "stage.started",
     WORKFLOW_PROCEED: "workflow.proceed",
 };
-async function emitUi(ui, text, toast) {
-    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, tableName) {
     try {
         const row = db
@@ -90,7 +63,7 @@ export function decideNextAction(db, config) {
     if (current.status === "failed") {
         return { kind: "failed", run_id: activeRun.run_id, stage_key: current.stage_key, error_text: current.error_text ?? "stage failed" };
     }
-    warn("Unexpected stage status in decideNextAction", { status: current.status, stage_key: current.status });
+    warn("Unexpected stage status in decideNextAction", { status: current.status, stage_key: current.stage_key });
     return { kind: "await_stage_completion", run_id: activeRun.run_id, stage_key: current.stage_key, stage_run_id: current.stage_run_id };
 }
 function getPipelineFromConfig(config) {
@@ -153,149 +126,91 @@ function attachRunPlanningDirective(db, runId, story, pipeline) {
     }
 }
 export function createRunForStory(db, config, storyKey) {
-    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 };
-    });
-}
-/**
- * STAGE MOVEMENT (START) — now async so UI injection is deterministic.
- */
-export async function startStage(db, runId, stageKey, meta) {
-    // 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);
-        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);
-        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);
-        return {
-            now,
-            story_key: run.story_key,
-            story_title: story?.title ?? "",
-        };
-    });
-    // 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,
-    });
-}
-/**
- * STAGE CLOSED (RUN COMPLETED) — now async so UI injection is deterministic.
- */
-export async function completeRun(db, runId, ui) {
-    const payload = withTx(db, () => {
-        const now = nowISO();
-        const run = db.prepare("SELECT * FROM runs WHERE run_id=?").get(runId);
-        if (!run)
-            throw new Error(`Run not found: ${runId}`);
-        if (run.status !== "running")
-            throw new Error(`Run not running: ${runId} (status=${run.status})`);
-        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}`);
-        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("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);
-        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);
-        return { now, story_key: run.story_key, story_title: story?.title ?? "" };
-    });
-    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,
-    });
-}
-/**
- * STAGE CLOSED (RUN FAILED) — now async so UI injection is deterministic.
- */
-export async function failRun(db, runId, stageKey, errorText, ui) {
-    const payload = withTx(db, () => {
-        const now = nowISO();
-        const run = db.prepare("SELECT * FROM runs WHERE run_id=?").get(runId);
-        if (!run)
-            throw new Error(`Run not found: ${runId}`);
-        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);
-        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);
-        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);
-        return { now, story_key: run.story_key, story_title: story?.title ?? "" };
-    });
-    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,
+    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, now, run_id, storyKey, now);
+    return { run_id };
+}
+export function startStage(db, runId, stageKey, meta, emit) {
+    const now = nowISO();
+    const run = db.prepare("SELECT * FROM runs WHERE run_id=?").get(runId);
+    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);
+    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);
+    // ✅ Explicit wiring point (requested): stage movement
+    emit?.({ kind: "stage_started", run_id: runId, stage_key: stageKey, agent_name: meta?.subagent_type });
+}
+export function completeRun(db, runId, emit) {
+    const now = nowISO();
+    const run = db.prepare("SELECT * FROM runs WHERE run_id=?").get(runId);
+    if (!run)
+        throw new Error(`Run not found: ${runId}`);
+    if (run.status !== "running")
+        throw new Error(`Run not running: ${runId} (status=${run.status})`);
+    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}`);
+    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("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);
+    db.prepare("UPDATE repo_state SET last_event_at=?, updated_at=? WHERE id=1").run(now, now);
+    // ✅ Explicit wiring point (requested): run closed success
+    emit?.({ kind: "run_completed", run_id: runId, story_key: run.story_key });
+}
+export function failRun(db, runId, stageKey, errorText, emit) {
+    const now = nowISO();
+    const run = db.prepare("SELECT * FROM runs WHERE run_id=?").get(runId);
+    if (!run)
+        throw new Error(`Run not found: ${runId}`);
+    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);
+    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);
+    db.prepare("UPDATE repo_state SET last_event_at=?, updated_at=? WHERE id=1").run(now, now);
+    // ✅ Explicit wiring point (requested): run closed failure
+    emit?.({ kind: "run_failed", run_id: runId, story_key: run.story_key, stage_key: stageKey, error_text: errorText });
 }
 export function abortRun(db, runId, reason) {
-    return withTx(db, () => {
-        const now = nowISO();
-        const run = db.prepare("SELECT * FROM runs WHERE run_id=?").get(runId);
-        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 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(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);
-    });
+    const now = nowISO();
+    const run = db.prepare("SELECT * FROM runs WHERE run_id=?").get(runId);
+    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 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(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);
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "astrocode-workflow",
-  "version": "0.3.0",
+  "version": "0.3.1",
   "type": "module",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",

package/src/tools/workflow.ts

@@ -2,9 +2,19 @@
 import { tool, type ToolDefinition } from "@opencode-ai/plugin/tool";
 import type { AstrocodeConfig } from "../config/schema";
 import type { SqliteDb } from "../state/db";
+import { withTx } from "../state/db";
 import type { StageKey } from "../state/types";
+import type { UiEmitEvent } from "../workflow/state-machine";
 import { buildContextSnapshot } from "../workflow/context";
-import { decideNextAction, createRunForStory, startStage, completeRun, getActiveRun, EVENT_TYPES } from "../workflow/state-machine";
+import {
+  decideNextAction,
+  createRunForStory,
+  startStage,
+  completeRun,
+  failRun,
+  getActiveRun,
+  EVENT_TYPES,
+} from "../workflow/state-machine";
 import { buildStageDirective, directiveHash } from "../workflow/directives";
 import { injectChatPrompt } from "../ui/inject";
 import { nowISO } from "../shared/time";
@@ -118,10 +128,50 @@ function buildDelegationPrompt(opts: {
   ].join("\n").trim();
 
   debug(`Delegating stage ${stage_key} to agent ${stage_agent_name}`, { prompt_length: prompt.length });
-
   return prompt;
 }
 
+function buildUiMessage(e: UiEmitEvent): { title: string; message: string; variant: "info" | "success" | "error"; chatText: string } {
+  switch (e.kind) {
+    case "stage_started": {
+      const agent = e.agent_name ? ` (${e.agent_name})` : "";
+      const title = "Astrocode";
+      const message = `Stage started: ${e.stage_key}${agent}`;
+      const chatText = [
+        `[SYSTEM DIRECTIVE: ASTROCODE — STAGE_STARTED]`,
+        ``,
+        `Run: ${e.run_id}`,
+        `Stage: ${e.stage_key}${agent}`,
+      ].join("\n");
+      return { title, message, variant: "info", chatText };
+    }
+    case "run_completed": {
+      const title = "Astrocode";
+      const message = `Run completed: ${e.run_id}`;
+      const chatText = [
+        `[SYSTEM DIRECTIVE: ASTROCODE — RUN_COMPLETED]`,
+        ``,
+        `Run: ${e.run_id}`,
+        `Story: ${e.story_key}`,
+      ].join("\n");
+      return { title, message, variant: "success", chatText };
+    }
+    case "run_failed": {
+      const title = "Astrocode";
+      const message = `Run failed: ${e.run_id} (${e.stage_key})`;
+      const chatText = [
+        `[SYSTEM DIRECTIVE: ASTROCODE — RUN_FAILED]`,
+        ``,
+        `Run: ${e.run_id}`,
+        `Story: ${e.story_key}`,
+        `Stage: ${e.stage_key}`,
+        `Error: ${e.error_text}`,
+      ].join("\n");
+      return { title, message, variant: "error", chatText };
+    }
+  }
+}
+
 export function createAstroWorkflowProceedTool(opts: { ctx: any; config: AstrocodeConfig; db: SqliteDb; agents?: Record<string, AgentConfig> }): ToolDefinition {
   const { ctx, config, db, agents } = opts;
   const toasts = createToastManager({ ctx, throttleMs: config.ui.toasts.throttle_ms });
@@ -141,6 +191,10 @@ export function createAstroWorkflowProceedTool(opts: { ctx: any; config: Astroco
       const warnings: string[] = [];
       const startedAt = nowISO();
 
+      // Collect UI events emitted inside state-machine functions, then flush AFTER tx.
+      const uiEvents: UiEmitEvent[] = [];
+      const emit = (e: UiEmitEvent) => uiEvents.push(e);
+
       for (let i = 0; i < steps; i++) {
         const next = decideNextAction(db, config);
 
@@ -150,60 +204,26 @@ export function createAstroWorkflowProceedTool(opts: { ctx: any; config: Astroco
         }
 
         if (next.kind === "start_run") {
-          // NOTE: createRunForStory owns its own tx (state-machine.ts).
-          const { run_id } = createRunForStory(db, config, next.story_key);
+          // SINGLE tx boundary: caller owns tx, state-machine is pure.
+          const { run_id } = withTx(db, () => createRunForStory(db, config, next.story_key));
           actions.push(`started run ${run_id} for story ${next.story_key}`);
 
-          if (config.ui.toasts.enabled && config.ui.toasts.show_run_started) {
-            await toasts.show({ title: "Astrocode", message: `Run started (${run_id})`, variant: "success" });
-          }
-
-          if (sessionId) {
-            await injectChatPrompt({
-              ctx,
-              sessionId,
-              agent: "Astro",
-              text: [
-                `[SYSTEM DIRECTIVE: ASTROCODE — RUN_STARTED]`,
-                ``,
-                `Run started: \`${run_id}\``,
-                `Story: \`${next.story_key}\``,
-                ``,
-                `Next: call **astro_workflow_proceed** again to delegate the first stage.`,
-              ].join("\n"),
-            });
-            actions.push(`injected run started message for ${run_id}`);
-          }
-
           if (mode === "step") break;
           continue;
         }
 
         if (next.kind === "complete_run") {
-          // NOTE: completeRun owns its own tx (state-machine.ts).
-          completeRun(db, next.run_id);
+          withTx(db, () => completeRun(db, next.run_id, emit));
           actions.push(`completed run ${next.run_id}`);
 
-          if (config.ui.toasts.enabled && config.ui.toasts.show_run_completed) {
-            await toasts.show({ title: "Astrocode", message: `Run completed (${next.run_id})`, variant: "success" });
-          }
+          if (mode === "step") break;
+          continue;
+        }
 
-          // ✅ explicit injection on completeRun (requested)
-          if (sessionId) {
-            await injectChatPrompt({
-              ctx,
-              sessionId,
-              agent: "Astro",
-              text: [
-                `[SYSTEM DIRECTIVE: ASTROCODE — RUN_COMPLETED]`,
-                ``,
-                `Run \`${next.run_id}\` completed.`,
-                ``,
-                `Next: call **astro_workflow_proceed** (mode=step) to start the next approved story (if any).`,
-              ].join("\n"),
-            });
-            actions.push(`injected run completed message for ${next.run_id}`);
-          }
+        if (next.kind === "failed") {
+          // Ensure DB state reflects failure in one tx; emit UI event.
+          withTx(db, () => failRun(db, next.run_id, next.stage_key, next.error_text, emit));
+          actions.push(`failed: ${next.stage_key} — ${next.error_text}`);
 
           if (mode === "step") break;
           continue;
@@ -241,30 +261,9 @@ export function createAstroWorkflowProceedTool(opts: { ctx: any; config: Astroco
           }
 
           // NOTE: startStage owns its own tx (state-machine.ts).
-          startStage(db, active.run_id, next.stage_key, { subagent_type: agentName });
-
-          actions.push(`stage started: ${next.stage_key}`);
-
-          if (config.ui.toasts.enabled && config.ui.toasts.show_stage_started) {
-            await toasts.show({ title: "Astrocode", message: `Stage started: ${next.stage_key}`, variant: "info" });
-          }
-
-          // ✅ explicit injection on startStage (requested)
-          if (sessionId) {
-            await injectChatPrompt({
-              ctx,
-              sessionId,
-              agent: "Astro",
-              text: [
-                `[SYSTEM DIRECTIVE: ASTROCODE — STAGE_STARTED]`,
-                ``,
-                `Run: \`${active.run_id}\``,
-                `Stage: \`${next.stage_key}\``,
-                `Delegated to: \`${agentName}\``,
-              ].join("\n"),
-            });
-            actions.push(`injected stage started message for ${next.stage_key}`);
-          }
+          withTx(db, () => {
+            startStage(db, active.run_id, next.stage_key, { subagent_type: agentName }, emit);
+          });
 
           const context = buildContextSnapshot({
             db,
@@ -292,20 +291,17 @@ export function createAstroWorkflowProceedTool(opts: { ctx: any; config: Astroco
             stage_agent_name: agentName,
           });
 
-          // Best-effort: continuations table may not exist on older DBs.
-          try {
-            const h = directiveHash(delegatePrompt);
-            const now = nowISO();
-            if (sessionId) {
-              db.prepare(
-                "INSERT INTO continuations (session_id, run_id, directive_hash, kind, reason, created_at) VALUES (?, ?, ?, 'stage', ?, ?)"
-              ).run(sessionId, active.run_id, h, `delegate ${next.stage_key}`, now);
-            }
-          } catch (e) {
-            warnings.push(`continuations insert failed (non-fatal): ${String(e)}`);
+          // Record continuation (best-effort; no tx wrapper needed but safe either way)
+          const h = directiveHash(delegatePrompt);
+          const now = nowISO();
+          if (sessionId) {
+            // This assumes continuations table exists in vNext schema.
+            db.prepare(
+              "INSERT INTO continuations (session_id, run_id, directive_hash, kind, reason, created_at) VALUES (?, ?, ?, 'stage', ?, ?)"
+            ).run(sessionId, active.run_id, h, `delegate ${next.stage_key}`, now);
           }
 
-          // Visible injection so user can see state
+          // Visible injection so user can see state (awaited)
           if (sessionId) {
             await injectChatPrompt({ ctx, sessionId, text: delegatePrompt, agent: "Astro" });
 
@@ -317,7 +313,7 @@ export function createAstroWorkflowProceedTool(opts: { ctx: any; config: Astroco
               `When \`${agentName}\` completes, call:`,
               `astro_stage_complete(run_id="${active.run_id}", stage_key="${next.stage_key}", output_text="[paste subagent output here]")`,
               ``,
-              `Then run **astro_workflow_proceed** again.`,
+              `This advances the workflow.`,
             ].join("\n");
 
             await injectChatPrompt({ ctx, sessionId, text: continueMessage, agent: "Astro" });
@@ -350,15 +346,11 @@ export function createAstroWorkflowProceedTool(opts: { ctx: any; config: Astroco
               context,
             ].join("\n").trim();
 
-            try {
-              const h = directiveHash(prompt);
-              const now = nowISO();
-              db.prepare(
-                "INSERT INTO continuations (session_id, run_id, directive_hash, kind, reason, created_at) VALUES (?, ?, ?, 'continue', ?, ?)"
-              ).run(sessionId, next.run_id, h, `await ${next.stage_key}`, now);
-            } catch (e) {
-              warnings.push(`continuations insert failed (non-fatal): ${String(e)}`);
-            }
+            const h = directiveHash(prompt);
+            const now = nowISO();
+            db.prepare(
+              "INSERT INTO continuations (session_id, run_id, directive_hash, kind, reason, created_at) VALUES (?, ?, ?, 'continue', ?, ?)"
+            ).run(sessionId, next.run_id, h, `await ${next.stage_key}`, now);
 
             await injectChatPrompt({ ctx, sessionId, text: prompt, agent: "Astro" });
           }
@@ -366,44 +358,40 @@ export function createAstroWorkflowProceedTool(opts: { ctx: any; config: Astroco
           break;
         }
 
-        if (next.kind === "failed") {
-          actions.push(`failed: ${next.stage_key} — ${next.error_text}`);
+        actions.push(`unhandled next action: ${(next as any).kind}`);
+        break;
+      }
 
-          if (sessionId) {
+      // Flush UI events (toast + prompt) AFTER state transitions
+      if (uiEvents.length > 0) {
+        for (const e of uiEvents) {
+          const msg = buildUiMessage(e);
+
+          if (config.ui.toasts.enabled) {
+            await toasts.show({
+              title: msg.title,
+              message: msg.message,
+              variant: msg.variant,
+            });
+          }
+
+          if ((ctx as any)?.sessionID) {
             await injectChatPrompt({
               ctx,
-              sessionId,
+              sessionId: (ctx as any).sessionID,
+              text: msg.chatText,
               agent: "Astro",
-              text: [
-                `[SYSTEM DIRECTIVE: ASTROCODE — RUN_FAILED]`,
-                ``,
-                `Run \`${next.run_id}\` failed at stage \`${next.stage_key}\`.`,
-                `Error: ${next.error_text}`,
-              ].join("\n"),
             });
-            actions.push(`injected run failed message for ${next.run_id}`);
           }
-
-          break;
         }
 
-        actions.push(`unhandled next action: ${(next as any).kind}`);
-        break;
+        actions.push(`ui: flushed ${uiEvents.length} event(s)`);
       }
 
-      // Housekeeping event (best-effort)
-      try {
-        db.prepare(
-          "INSERT INTO events (event_id, run_id, stage_key, type, body_json, created_at) VALUES (?, NULL, NULL, ?, ?, ?)"
-        ).run(
-          newEventId(),
-          EVENT_TYPES.WORKFLOW_PROCEED,
-          JSON.stringify({ started_at: startedAt, mode, max_steps: steps, actions }),
-          nowISO()
-        );
-      } catch (e) {
-        warnings.push(`workflow.proceed event insert failed (non-fatal): ${String(e)}`);
-      }
+      // Housekeeping event
+      db.prepare(
+        "INSERT INTO events (event_id, run_id, stage_key, type, body_json, created_at) VALUES (?, NULL, NULL, ?, ?, ?)"
+      ).run(newEventId(), EVENT_TYPES.WORKFLOW_PROCEED, JSON.stringify({ started_at: startedAt, mode, max_steps: steps, actions }), nowISO());
 
       const active = getActiveRun(db);
       const lines: string[] = [];