astrocode-workflow 0.2.0 → 0.3.0

package/src/tools/workflow.ts.backup

@@ -0,0 +1,681 @@
+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 { buildContextSnapshot } from "../workflow/context";
+import { decideNextAction, createRunForStory, startStage, completeRun, getActiveRun, EVENT_TYPES } from "../workflow/state-machine";
+import { buildStageDirective, directiveHash } from "../workflow/directives";
+import { injectChatPrompt } from "../ui/inject";
+import { nowISO } from "../shared/time";
+import { newEventId } from "../state/ids";
+import { debug } from "../shared/log";
+import { createToastManager } from "../ui/toasts";
+
+// Agent name mapping for case-sensitive resolution
+export const STAGE_TO_AGENT_MAP: Record<string, string> = {
+  frame: "Frame",
+  plan: "Plan",
+  spec: "Spec",
+  implement: "Implement",
+  review: "Review",
+  verify: "Verify",
+  close: "Close"
+};
+
+export function resolveAgentName(stageKey: StageKey, config: AstrocodeConfig, agents?: any, warnings?: string[]): string {
+  // Use configurable agent names from config, fallback to hardcoded map, then General
+  const agentNames = config.agents?.stage_agent_names;
+  let candidate: string;
+
+  if (agentNames && agentNames[stageKey]) {
+    candidate = agentNames[stageKey];
+  } else {
+    candidate = STAGE_TO_AGENT_MAP[stageKey] || "General";
+  }
+
+  // Validate that the agent actually exists in the registry
+  if (agents && !agents[candidate]) {
+    const warning = `Agent "${candidate}" not found in registry for stage "${stageKey}". Falling back to General.`;
+    if (warnings) {
+      warnings.push(warning);
+    } else {
+      console.warn(`[Astrocode] ${warning}`);
+    }
+    candidate = "General";
+  }
+
+  // Final guard: ensure General exists, fallback to built-in "general" if not
+  if (agents && !agents[candidate]) {
+    const finalWarning = `Critical: General agent not found in registry. Falling back to built-in "general".`;
+    if (warnings) {
+      warnings.push(finalWarning);
+    } else {
+      console.warn(`[Astrocode] ${finalWarning}`);
+    }
+    return "general"; // built-in, guaranteed by OpenCode
+  }
+
+  return candidate;
+}
+
+function stageGoal(stage: StageKey, cfg: AstrocodeConfig): string {
+  switch (stage) {
+    case "frame":
+      return "Define scope, constraints, and an unambiguous Definition of Done.";
+    case "plan":
+      return `Create 50-200 detailed implementation stories, each focused on a specific, implementable task. Break down every component into separate stories with clear acceptance criteria.`;
+    case "spec":
+      return "Produce minimal spec/contract: interfaces, invariants, acceptance checks.";
+    case "implement":
+      return "Implement the spec with minimal changes, referencing diffs and evidence as artifacts.";
+    case "review":
+      return "Review implementation for correctness, risks, and alignment with spec.";
+    case "verify":
+      return "Run verification commands and produce evidence artifacts.";
+    case "close":
+      return "Summarize outcome and confirm acceptance criteria, leaving clear breadcrumbs.";
+  }
+}
+
+function stageConstraints(stage: StageKey, cfg: AstrocodeConfig): string[] {
+  const common = [
+    "Do not narrate prompts.",
+    "Keep baton markdown short and structured.",
+    "If blocked: ask exactly ONE question and stop.",
+  ];
+
+  if (stage === "plan") {
+    common.push(`Create 50-200 stories; each story must be implementable in 2-8 hours with clear acceptance criteria.`);
+  }
+  if (stage === "verify" && cfg.workflow.evidence_required.verify) {
+    common.push("Evidence required: ASTRO JSON must include evidence[] paths.");
+  }
+  return common;
+}
+
+function agentNameForStage(stage: StageKey, cfg: AstrocodeConfig): string {
+  return cfg.agents.stage_agent_names[stage];
+}
+
+function buildDelegationPrompt(opts: {
+  stageDirective: string;
+  run_id: string;
+  stage_key: StageKey;
+  stage_agent_name: string;
+}): string {
+  const { stageDirective, run_id, stage_key, stage_agent_name } = opts;
+  const stageUpper = stage_key.toUpperCase();
+
+  const prompt = [
+    `[SYSTEM DIRECTIVE: ASTROCODE — DELEGATE_STAGE_${stageUpper}]`,
+    ``,
+    `Do this now, in order:`,
+    `1) Call the **task** tool to delegate to subagent \`${stage_agent_name}\`.`,
+    `   - Pass this exact prompt text to the subagent (copy/paste):`,
+    ``,
+    stageDirective,
+    ``,
+    `2) When the subagent returns, immediately call **astro_stage_complete** with:`,
+    `   - run_id = "${run_id}"`,
+    `   - stage_key = "${stage_key}"`,
+    `   - output_text = (the FULL subagent response text)`,
+    ``,
+    `3) Then call **astro_workflow_proceed** again (mode=step).`,
+    ``,
+    `Important: do NOT do any stage work yourself in orchestrator mode.`,
+  ].join("\n").trim();
+
+  // Debug log the delegation prompt to troubleshoot agent output issues
+  debug(`Delegating stage ${stage_key} to agent ${stage_agent_name}`, { prompt_length: prompt.length });
+
+  return prompt;
+}
+
+import { AgentConfig } from "@opencode-ai/sdk";
+
+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 });
+
+  return tool({
+    description:
+      "Deterministic harness: advances the DB-driven pipeline by one step (or loops bounded). Stops when LLM work is required (delegation/await).",
+    args: {
+      mode: tool.schema.enum(["step", "loop"]).default(config.workflow.default_mode),
+      max_steps: tool.schema.number().int().positive().default(config.workflow.default_max_steps),
+    },
+    execute: async ({ mode, max_steps }) => {
+      const sessionId = (ctx as any).sessionID as string | undefined;
+      const steps = Math.min(max_steps, config.workflow.loop_max_steps_hard_cap);
+
+      const actions: string[] = [];
+      const warnings: string[] = [];
+      const startedAt = nowISO();
+
+      for (let i = 0; i < steps; i++) {
+        const next = decideNextAction(db, config);
+
+        if (next.kind === "idle") {
+          actions.push("idle: no approved stories");
+          break;
+        }
+
+        if (next.kind === "start_run") {
+          // NOTE: createRunForStory owns its own tx (state-machine.ts).
+          const { run_id } = 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);
+          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" });
+          }
+
+          // ✅ 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 (mode === "step") break;
+          continue;
+        }
+
+        if (next.kind === "delegate_stage") {
+          const active = getActiveRun(db);
+          if (!active) throw new Error("Invariant: delegate_stage but no active run.");
+
+          const run = db.prepare("SELECT * FROM runs WHERE run_id=?").get(active.run_id) as any;
+          const story = db.prepare("SELECT * FROM stories WHERE story_key=?").get(run.story_key) as any;
+
+          let agentName = resolveAgentName(next.stage_key, config, agents, warnings);
+
+          const agentExists = (name: string) => {
+            if (agents && agents[name]) return true;
+            const knownStageAgents = ["Frame", "Plan", "Spec", "Implement", "Review", "Verify", "Close", "General", "Astro", "general"];
+            if (knownStageAgents.includes(name)) return true;
+            return false;
+          };
+
+          if (!agentExists(agentName)) {
+            const originalAgent = agentName;
+            console.warn(`[Astrocode] Agent ${agentName} not found. Falling back to orchestrator.`);
+            agentName = config.agents?.orchestrator_name || "Astro";
+            if (!agentExists(agentName)) {
+              console.warn(`[Astrocode] Orchestrator ${agentName} not available. Falling back to General.`);
+              agentName = "General";
+              if (!agentExists(agentName)) {
+                throw new Error(
+                  `Critical: No agents available for delegation. Primary: ${originalAgent}, Orchestrator: ${config.agents?.orchestrator_name || "Astro"}, General: unavailable`
+                );
+              }
+            }
+          }
+
+          // 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}`);
+          }
+
+          const context = buildContextSnapshot({
+            db,
+            config,
+            run_id: active.run_id,
+            next_action: `delegate stage ${next.stage_key}`,
+          });
+
+          const stageDirective = buildStageDirective({
+            config,
+            stage_key: next.stage_key,
+            run_id: active.run_id,
+            story_key: run.story_key,
+            story_title: story?.title ?? "(missing)",
+            stage_agent_name: agentName,
+            stage_goal: stageGoal(next.stage_key, config),
+            stage_constraints: stageConstraints(next.stage_key, config),
+            context_snapshot_md: context,
+          }).body;
+
+          const delegatePrompt = buildDelegationPrompt({
+            stageDirective,
+            run_id: active.run_id,
+            stage_key: next.stage_key,
+            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)}`);
+          }
+
+          // Visible injection so user can see state
+          if (sessionId) {
+            await injectChatPrompt({ ctx, sessionId, text: delegatePrompt, agent: "Astro" });
+
+            const continueMessage = [
+              `[SYSTEM DIRECTIVE: ASTROCODE — AWAIT_STAGE_COMPLETION]`,
+              ``,
+              `Stage \`${next.stage_key}\` delegated to \`${agentName}\`.`,
+              ``,
+              `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.`,
+            ].join("\n");
+
+            await injectChatPrompt({ ctx, sessionId, text: continueMessage, agent: "Astro" });
+          }
+
+          actions.push(`delegated stage ${next.stage_key} via ${agentName}`);
+
+          // Stop here; subagent needs to run.
+          break;
+        }
+
+        if (next.kind === "await_stage_completion") {
+          actions.push(`await stage completion: ${next.stage_key}`);
+
+          if (sessionId) {
+            const context = buildContextSnapshot({
+              db,
+              config,
+              run_id: next.run_id,
+              next_action: `complete stage ${next.stage_key}`,
+            });
+
+            const prompt = [
+              `[SYSTEM DIRECTIVE: ASTROCODE — AWAIT_STAGE_OUTPUT]`,
+              ``,
+              `Run \`${next.run_id}\` is waiting for stage \`${next.stage_key}\` output.`,
+              `If you have the subagent output, call astro_stage_complete with output_text=the FULL output.`,
+              ``,
+              `Context snapshot:`,
+              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)}`);
+            }
+
+            await injectChatPrompt({ ctx, sessionId, text: prompt, agent: "Astro" });
+          }
+
+          break;
+        }
+
+        if (next.kind === "failed") {
+          actions.push(`failed: ${next.stage_key} — ${next.error_text}`);
+
+          if (sessionId) {
+            await injectChatPrompt({
+              ctx,
+              sessionId,
+              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;
+      }
+
+      // 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)}`);
+      }
+
+      const active = getActiveRun(db);
+      const lines: string[] = [];
+      lines.push(`# astro_workflow_proceed`);
+      lines.push(`- mode: ${mode}`);
+      lines.push(`- steps requested: ${max_steps} (cap=${steps})`);
+      if (active) lines.push(`- active run: \`${active.run_id}\` (stage=${active.current_stage_key ?? "?"})`);
+      lines.push(``, `## Actions`);
+      for (const a of actions) lines.push(`- ${a}`);
+
+      if (warnings.length > 0) {
+        lines.push(``, `## Warnings`);
+        for (const w of warnings) lines.push(`⚠️ ${w}`);
+      }
+
+      return lines.join("\n").trim();
+    },
+  });
+}
+
+        if (next.kind === "start_run") {
+          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 (mode === "step") break;
+          continue;
+        }
+
+        if (next.kind === "complete_run") {
+          withTx(db, () => completeRun(db, next.run_id));
+          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" });
+          }
+
+          // Inject continuation directive for workflow resumption
+          if (sessionId) {
+            const continueDirective = [
+              `[SYSTEM DIRECTIVE: ASTROCODE — CONTINUE]`,
+              ``,
+              `Run ${next.run_id} completed successfully.`,
+              ``,
+              `The Clara Forms implementation run has finished all stages. The spec has been analyzed and decomposed into prioritized implementation stories.`,
+              ``,
+              `Next actions: Review the generated stories and approve the next one to continue development.`,
+            ].join("\n");
+
+            await injectChatPrompt({
+              ctx,
+              sessionId,
+              text: continueDirective,
+              agent: "Astro"
+            });
+
+            actions.push(`injected continuation directive for completed run ${next.run_id}`);
+          }
+
+          // Check for next approved story to start
+          const nextStory = db.prepare(
+            "SELECT story_key, title FROM stories WHERE state = 'approved' ORDER BY priority DESC, created_at ASC LIMIT 1"
+          ).get() as { story_key: string; title: string } | undefined;
+
+          if (nextStory && sessionId) {
+            const nextDirective = [
+              `[SYSTEM DIRECTIVE: ASTROCODE — START_NEXT_STORY]`,
+              ``,
+              `The previous run completed successfully. Start the next approved story.`,
+              ``,
+              `Next Story: ${nextStory.story_key} — ${nextStory.title}`,
+              ``,
+              `Action: Call astro_story_approve with story_key="${nextStory.story_key}" to start it, or select a different story.`,
+            ].join("\n");
+
+            await injectChatPrompt({
+              ctx,
+              sessionId,
+              text: nextDirective,
+              agent: "Astro"
+            });
+
+            actions.push(`injected directive to start next story ${nextStory.story_key}`);
+          }
+
+          if (mode === "step") break;
+          continue;
+        }
+
+        if (next.kind === "delegate_stage") {
+          const active = getActiveRun(db);
+          if (!active) throw new Error("Invariant: delegate_stage but no active run.");
+          const run = db.prepare("SELECT * FROM runs WHERE run_id=?").get(active.run_id) as any;
+          const story = db.prepare("SELECT * FROM stories WHERE story_key=?").get(run.story_key) as any;
+
+          // Mark stage started + set subagent_type to the stage agent.
+          let agentName = resolveAgentName(next.stage_key, config, agents, warnings);
+
+          // Validate agent availability with fallback chain
+          const systemConfig = config as any;
+          // Check both the system config agent map (if present) OR the local agents map passed to the tool
+          const agentExists = (name: string) => {
+             // Check local agents map first (populated from src/index.ts)
+             if (agents && agents[name]) {
+               return true;
+             }
+             // Check system config agent map
+             if (systemConfig.agent && systemConfig.agent[name]) {
+               return true;
+             }
+             // For known stage agents, assume they exist (they are system-provided subagents)
+             const knownStageAgents = ["Frame", "Plan", "Spec", "Implement", "Review", "Verify", "Close"];
+             if (knownStageAgents.includes(name)) {
+               return true;
+             }
+             return false;
+          };
+
+            if (!agentExists(agentName)) {
+              const originalAgent = agentName;
+              console.warn(`[Astrocode] Agent ${agentName} not found in config. Falling back to orchestrator.`);
+              // First fallback: orchestrator
+              agentName = config.agents?.orchestrator_name || "Astro";
+              if (!agentExists(agentName)) {
+                console.warn(`[Astrocode] Orchestrator ${agentName} not available. Falling back to General.`);
+                // Final fallback: General (guaranteed to exist)
+                agentName = "General";
+                if (!agentExists(agentName)) {
+                  throw new Error(`Critical: No agents available for delegation. Primary: ${originalAgent}, Orchestrator: ${config.agents?.orchestrator_name || "Astro"}, General: unavailable`);
+                }
+              }
+            }
+
+          withTx(db, () => {
+            startStage(db, active.run_id, next.stage_key, { subagent_type: agentName });
+
+            // Log delegation observability
+            if (config.debug?.telemetry?.enabled) {
+              // eslint-disable-next-line no-console
+              console.log(`[Astrocode:delegate] run_id=${active.run_id} stage=${next.stage_key} agent=${agentName} fallback=${agentName !== resolveAgentName(next.stage_key, config, agents) ? 'yes' : 'no'}`);
+            }
+          });
+
+          if (config.ui.toasts.enabled && config.ui.toasts.show_stage_started) {
+            await toasts.show({ title: "Astrocode", message: `Stage started: ${next.stage_key}`, variant: "info" });
+          }
+
+          const context = buildContextSnapshot({ db, config, run_id: active.run_id, next_action: `delegate stage ${next.stage_key}` });
+
+          const stageDirective = buildStageDirective({
+            config,
+            stage_key: next.stage_key,
+            run_id: active.run_id,
+            story_key: run.story_key,
+            story_title: story?.title ?? "(missing)",
+            stage_agent_name: agentName,
+            stage_goal: stageGoal(next.stage_key, config),
+            stage_constraints: stageConstraints(next.stage_key, config),
+            context_snapshot_md: context,
+          }).body;
+
+          const delegatePrompt = buildDelegationPrompt({
+            stageDirective,
+            run_id: active.run_id,
+            stage_key: next.stage_key,
+            stage_agent_name: agentName,
+          });
+
+          // Record in continuations as a stage directive (dedupe by hash)
+          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);
+          }
+
+           // Visible injection so user can see state
+           if (sessionId) {
+             await injectChatPrompt({ ctx, sessionId, text: delegatePrompt, agent: "Astro" });
+
+             // Inject continuation guidance
+             const continueMessage = [
+               `[SYSTEM DIRECTIVE: ASTROCODE — AWAIT_STAGE_COMPLETION]`,
+               ``,
+               `Stage ${next.stage_key} delegated to ${agentName}.`,
+               ``,
+               `When ${agentName} completes, call:`,
+               `astro_stage_complete(run_id="${active.run_id}", stage_key="${next.stage_key}", output_text="[paste subagent output here]")`,
+               ``,
+               `This advances the workflow.`,
+             ].join("\n");
+
+             await injectChatPrompt({ ctx, sessionId, text: continueMessage, agent: "Astro" });
+           }
+
+           actions.push(`delegated stage ${next.stage_key} via ${agentName}`);
+
+          // Stop here; subagent needs to run.
+          break;
+        }
+
+        if (next.kind === "await_stage_completion") {
+          actions.push(`await stage completion: ${next.stage_key}`);
+          // Optionally nudge with a short directive
+          if (sessionId) {
+            const context = buildContextSnapshot({ db, config, run_id: next.run_id, next_action: `complete stage ${next.stage_key}` });
+            const prompt = [
+              `[SYSTEM DIRECTIVE: ASTROCODE — AWAIT_STAGE_OUTPUT]`,
+              ``,
+              `Run ${next.run_id} is waiting for stage ${next.stage_key} output.`,
+              `If you have the subagent output, call astro_stage_complete with output_text=the FULL output.`,
+              ``,
+              `Context snapshot:`,
+              context,
+            ].join("\n").trim();
+            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" });
+          }
+          break;
+        }
+
+        if (next.kind === "failed") {
+          actions.push(`failed: ${next.stage_key} — ${next.error_text}`);
+          break;
+        }
+
+        // safety
+        actions.push(`unhandled next action: ${(next as any).kind}`);
+        break;
+      }
+
+      // 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[] = [];
+      lines.push(`# astro_workflow_proceed`);
+      lines.push(`- mode: ${mode}`);
+      lines.push(`- steps requested: ${max_steps} (cap=${steps})`);
+      if (active) lines.push(`- active run: \`${active.run_id}\` (stage=${active.current_stage_key ?? "?"})`);
+      lines.push(``, `## Actions`);
+      for (const a of actions) lines.push(`- ${a}`);
+
+      if (warnings.length > 0) {
+        lines.push(``, `## Warnings`);
+        for (const w of warnings) lines.push(`⚠️ ${w}`);
+      }
+
+      return lines.join("\n").trim();
+    },
+  });
+}