astrocode-workflow 0.1.8 → 0.1.11

package/dist/agents/registry.js

@@ -215,6 +215,15 @@ export function createAstroAgents(opts) {
         prompt: BASE_STAGE_PROMPT,
         permission: stageReadOnlyPermissions(),
     }, "utility");
+    // Fallback general agent for delegation failures
+    agents["General"] = mk("General", {
+        description: "General-purpose fallback agent for delegation.",
+        mode: "subagent",
+        hidden: true,
+        temperature: 0.1,
+        prompt: BASE_STAGE_PROMPT,
+        permission: stageReadOnlyPermissions(),
+    }, "utility");
     // Allow user config to disable certain agents
     for (const disabled of pluginConfig.disabled_agents) {
         delete agents[disabled];

package/dist/shared/paths.js

@@ -43,7 +43,8 @@ export function assertInsideAstro(repoRoot, filePath) {
     const abs = path.resolve(filePath);
     const astroRoot = path.resolve(path.join(repoRoot, ".astro"));
     if (!abs.startsWith(astroRoot + path.sep) && abs !== astroRoot) {
-        throw new Error(`Refusing to write outside .astro: ${filePath}`);
+        const relPath = path.relative(repoRoot, filePath);
+        throw new Error(`Refusing to write outside .astro: ${filePath} (relative: ${relPath}, astroRoot: ${astroRoot})`);
     }
     if (!abs.startsWith(absRepo + path.sep) && abs !== absRepo) {
         throw new Error(`Refusing to write outside repo root: ${filePath}`);

package/dist/state/schema.d.ts

@@ -1,2 +1,2 @@
 export declare const SCHEMA_VERSION = 2;
-export declare const SCHEMA_SQL = "\nPRAGMA foreign_keys = ON;\n\nCREATE TABLE IF NOT EXISTS repo_state (\n  id INTEGER PRIMARY KEY CHECK (id = 1),\n  schema_version INTEGER NOT NULL,\n  created_at TEXT NOT NULL,\n  updated_at TEXT NOT NULL,\n  spec_hash_before TEXT,\n  spec_hash_after TEXT,\n  last_run_id TEXT,\n  last_story_key TEXT,\n  last_event_at TEXT\n);\n\nCREATE TABLE IF NOT EXISTS settings (\n  key TEXT PRIMARY KEY,\n  value TEXT NOT NULL,\n  updated_at TEXT NOT NULL\n);\n\nCREATE TABLE IF NOT EXISTS epics (\n  epic_key TEXT PRIMARY KEY,\n  title TEXT NOT NULL,\n  body_md TEXT NOT NULL DEFAULT '',\n  state TEXT NOT NULL DEFAULT 'active',\n  priority INTEGER NOT NULL DEFAULT 0,\n  created_at TEXT NOT NULL,\n  updated_at TEXT NOT NULL\n);\n\nCREATE TABLE IF NOT EXISTS story_drafts (\n  draft_id TEXT PRIMARY KEY,\n  title TEXT NOT NULL,\n  body_md TEXT NOT NULL DEFAULT '',\n  meta_json TEXT NOT NULL DEFAULT '{}',\n  created_at TEXT NOT NULL,\n  updated_at TEXT NOT NULL\n);\n\nCREATE TABLE IF NOT EXISTS story_keyseq (\n  id INTEGER PRIMARY KEY CHECK (id = 1),\n  next_story_num INTEGER NOT NULL\n);\n\nCREATE TABLE IF NOT EXISTS stories (\n  story_key TEXT PRIMARY KEY,\n  epic_key TEXT,\n  title TEXT NOT NULL,\n  body_md TEXT NOT NULL DEFAULT '',\n  state TEXT NOT NULL DEFAULT 'queued', -- queued|approved|in_progress|done|blocked|archived\n  priority INTEGER NOT NULL DEFAULT 0,\n  approved_at TEXT,\n  locked_by_run_id TEXT,\n  locked_at TEXT,\n  in_progress INTEGER NOT NULL DEFAULT 0,\n  created_at TEXT NOT NULL,\n  updated_at TEXT NOT NULL,\n  FOREIGN KEY (epic_key) REFERENCES epics(epic_key)\n);\n\nCREATE TABLE IF NOT EXISTS runs (\n  run_id TEXT PRIMARY KEY,\n  story_key TEXT NOT NULL,\n  status TEXT NOT NULL DEFAULT 'created', -- created|running|completed|failed|aborted\n  pipeline_stages_json TEXT NOT NULL DEFAULT '[]',\n  current_stage_key TEXT,\n  created_at TEXT NOT NULL,\n  started_at TEXT,\n  completed_at TEXT,\n  updated_at TEXT NOT NULL,\n  error_text TEXT,\n  FOREIGN KEY (story_key) REFERENCES stories(story_key)\n);\n\nCREATE TABLE IF NOT EXISTS stage_runs (\n  stage_run_id TEXT PRIMARY KEY,\n  run_id TEXT NOT NULL,\n  stage_key TEXT NOT NULL,\n  stage_index INTEGER NOT NULL,\n  status TEXT NOT NULL DEFAULT 'pending', -- pending|running|completed|failed|skipped\n  subagent_type TEXT,\n  subagent_session_id TEXT,\n  started_at TEXT,\n  completed_at TEXT,\n  updated_at TEXT NOT NULL,\n  baton_path TEXT,\n  summary_md TEXT,\n  output_json TEXT,\n  error_text TEXT,\n  FOREIGN KEY (run_id) REFERENCES runs(run_id)\n);\n\nCREATE TABLE IF NOT EXISTS artifacts (\n  artifact_id TEXT PRIMARY KEY,\n  run_id TEXT,\n  stage_key TEXT,\n  type TEXT NOT NULL, -- plan|baton|evidence|diff|log|summary|commit|tool_output|snapshot\n  path TEXT NOT NULL,\n  sha256 TEXT,\n  meta_json TEXT NOT NULL DEFAULT '{}',\n  created_at TEXT NOT NULL,\n  FOREIGN KEY (run_id) REFERENCES runs(run_id)\n);\n\nCREATE TABLE IF NOT EXISTS tool_runs (\n  tool_run_id TEXT PRIMARY KEY,\n  run_id TEXT,\n  stage_key TEXT,\n  tool_name TEXT NOT NULL,\n  args_json TEXT NOT NULL DEFAULT '{}',\n  output_summary TEXT NOT NULL DEFAULT '',\n  output_artifact_id TEXT,\n  created_at TEXT NOT NULL,\n  FOREIGN KEY (run_id) REFERENCES runs(run_id)\n);\n\nCREATE TABLE IF NOT EXISTS events (\n  event_id TEXT PRIMARY KEY,\n  run_id TEXT,\n  stage_key TEXT,\n  type TEXT NOT NULL,\n  body_json TEXT NOT NULL DEFAULT '{}',\n  created_at TEXT NOT NULL,\n  FOREIGN KEY (run_id) REFERENCES runs(run_id)\n);\n\nCREATE TABLE IF NOT EXISTS injects (\n  inject_id TEXT PRIMARY KEY,\n  type TEXT NOT NULL DEFAULT 'note',\n  title TEXT NOT NULL,\n  body_md TEXT NOT NULL,\n  tags_json TEXT NOT NULL DEFAULT '[]',\n  scope TEXT NOT NULL DEFAULT 'repo', -- repo|run:<id>|story:<key>|global\n  source TEXT NOT NULL DEFAULT 'user', -- user|tool|agent|import\n  priority INTEGER NOT NULL DEFAULT 50,\n  expires_at TEXT,\n  sha256 TEXT,\n  created_at TEXT NOT NULL,\n  updated_at TEXT NOT NULL\n);\n\nCREATE TABLE IF NOT EXISTS running_batches (\n  batch_id TEXT PRIMARY KEY,\n  run_id TEXT,\n  session_id TEXT,\n  status TEXT NOT NULL DEFAULT 'running', -- running|completed|failed|aborted\n  created_at TEXT NOT NULL,\n  updated_at TEXT NOT NULL,\n  FOREIGN KEY (run_id) REFERENCES runs(run_id)\n);\n\nCREATE TABLE IF NOT EXISTS workflow_metrics (\n  metric_id TEXT PRIMARY KEY,\n  run_id TEXT,\n  stage_key TEXT,\n  name TEXT NOT NULL,\n  value_num REAL,\n  value_text TEXT,\n  created_at TEXT NOT NULL,\n  FOREIGN KEY (run_id) REFERENCES runs(run_id)\n);\n\nCREATE TABLE IF NOT EXISTS template_intents (\n  intent_key TEXT PRIMARY KEY,\n  body_md TEXT NOT NULL,\n  updated_at TEXT NOT NULL\n);\n\n-- vNext tables\n\nCREATE TABLE IF NOT EXISTS story_relations (\n  parent_story_key TEXT NOT NULL,\n  child_story_key TEXT NOT NULL,\n  relation_type TEXT NOT NULL DEFAULT 'split',\n  reason TEXT NOT NULL DEFAULT '',\n  created_at TEXT NOT NULL,\n  PRIMARY KEY (parent_story_key, child_story_key),\n  FOREIGN KEY (parent_story_key) REFERENCES stories(story_key),\n  FOREIGN KEY (child_story_key) REFERENCES stories(story_key)\n);\n\nCREATE TABLE IF NOT EXISTS continuations (\n  continuation_id INTEGER PRIMARY KEY AUTOINCREMENT,\n  session_id TEXT NOT NULL,\n  run_id TEXT,\n  directive_hash TEXT NOT NULL,\n  kind TEXT NOT NULL, -- continue|stage|blocked|repair\n  reason TEXT NOT NULL DEFAULT '',\n  created_at TEXT NOT NULL,\n  FOREIGN KEY (run_id) REFERENCES runs(run_id)\n);\n\nCREATE INDEX IF NOT EXISTS idx_continuations_session_created ON continuations(session_id, created_at DESC);\nCREATE INDEX IF NOT EXISTS idx_continuations_run_created ON continuations(run_id, created_at DESC);\n\nCREATE TABLE IF NOT EXISTS context_snapshots (\n  snapshot_id TEXT PRIMARY KEY,\n  run_id TEXT NOT NULL,\n  stage_key TEXT NOT NULL,\n  summary_md TEXT NOT NULL,\n  created_at TEXT NOT NULL,\n  FOREIGN KEY (run_id) REFERENCES runs(run_id)\n);\n\nCREATE INDEX IF NOT EXISTS idx_context_snapshots_run_created ON context_snapshots(run_id, created_at DESC);\n\nCREATE TABLE IF NOT EXISTS agent_sessions (\n  session_id TEXT PRIMARY KEY,\n  parent_session_id TEXT,\n  agent_name TEXT NOT NULL,\n  run_id TEXT,\n  stage_key TEXT,\n  status TEXT NOT NULL DEFAULT 'active',\n  created_at TEXT NOT NULL,\n  updated_at TEXT NOT NULL\n);\n\n-- Indexes\n\nCREATE INDEX IF NOT EXISTS idx_stories_state ON stories(state);\nCREATE INDEX IF NOT EXISTS idx_runs_story ON runs(story_key);\nCREATE INDEX IF NOT EXISTS idx_runs_status ON runs(status);\nCREATE INDEX IF NOT EXISTS idx_stage_runs_run ON stage_runs(run_id, stage_index);\nCREATE INDEX IF NOT EXISTS idx_artifacts_run_stage ON artifacts(run_id, stage_key, created_at DESC);\nCREATE INDEX IF NOT EXISTS idx_events_run ON events(run_id, created_at DESC);\nCREATE INDEX IF NOT EXISTS idx_tool_runs_run ON tool_runs(run_id, created_at DESC);\nCREATE INDEX IF NOT EXISTS idx_injects_scope_priority ON injects(scope, priority DESC, created_at DESC);\n\n-- Stronger invariants (SQLite partial indexes)\n-- Only one run may be 'running' at a time (single-repo harness by default).\nCREATE UNIQUE INDEX IF NOT EXISTS uniq_single_running_run\n  ON runs(status)\n  WHERE status = 'running';\n\n-- Only one story may be in_progress=1 at a time (pairs with single running run).\nCREATE UNIQUE INDEX IF NOT EXISTS uniq_single_in_progress_story\n  ON stories(in_progress)\n  WHERE in_progress = 1;\n\n";
+export declare const SCHEMA_SQL = "\nPRAGMA foreign_keys = ON;\n\nCREATE TABLE IF NOT EXISTS repo_state (\n  id INTEGER PRIMARY KEY CHECK (id = 1),\n  schema_version INTEGER NOT NULL,\n  created_at TEXT NOT NULL,\n  updated_at TEXT NOT NULL,\n  spec_hash_before TEXT,\n  spec_hash_after TEXT,\n  last_run_id TEXT,\n  last_story_key TEXT,\n  last_event_at TEXT\n);\n\nCREATE TABLE IF NOT EXISTS settings (\n  key TEXT PRIMARY KEY,\n  value TEXT NOT NULL,\n  updated_at TEXT NOT NULL\n);\n\nCREATE TABLE IF NOT EXISTS epics (\n  epic_key TEXT PRIMARY KEY,\n  title TEXT NOT NULL,\n  body_md TEXT NOT NULL DEFAULT '',\n  state TEXT NOT NULL DEFAULT 'active',\n  priority INTEGER NOT NULL DEFAULT 0,\n  created_at TEXT NOT NULL,\n  updated_at TEXT NOT NULL\n);\n\nCREATE TABLE IF NOT EXISTS story_drafts (\n  draft_id TEXT PRIMARY KEY,\n  title TEXT NOT NULL,\n  body_md TEXT NOT NULL DEFAULT '',\n  meta_json TEXT NOT NULL DEFAULT '{}',\n  created_at TEXT NOT NULL,\n  updated_at TEXT NOT NULL\n);\n\nCREATE TABLE IF NOT EXISTS story_keyseq (\n  id INTEGER PRIMARY KEY CHECK (id = 1),\n  next_story_num INTEGER NOT NULL\n);\n\nCREATE TABLE IF NOT EXISTS stories (\n  story_key TEXT PRIMARY KEY,\n  epic_key TEXT,\n  title TEXT NOT NULL,\n  body_md TEXT NOT NULL DEFAULT '',\n  state TEXT NOT NULL DEFAULT 'queued', -- queued|approved|in_progress|done|blocked|archived\n  priority INTEGER NOT NULL DEFAULT 0,\n  approved_at TEXT,\n  locked_by_run_id TEXT,\n  locked_at TEXT,\n  in_progress INTEGER NOT NULL DEFAULT 0,\n  created_at TEXT NOT NULL,\n  updated_at TEXT NOT NULL,\n  FOREIGN KEY (epic_key) REFERENCES epics(epic_key)\n);\n\nCREATE TABLE IF NOT EXISTS runs (\n  run_id TEXT PRIMARY KEY,\n  story_key TEXT NOT NULL,\n  status TEXT NOT NULL DEFAULT 'created', -- created|running|completed|failed|aborted\n  pipeline_stages_json TEXT NOT NULL DEFAULT '[]',\n  current_stage_key TEXT,\n  created_at TEXT NOT NULL,\n  started_at TEXT,\n  completed_at TEXT,\n  updated_at TEXT NOT NULL,\n  error_text TEXT,\n  FOREIGN KEY (story_key) REFERENCES stories(story_key)\n);\n\nCREATE TABLE IF NOT EXISTS stage_runs (\n  stage_run_id TEXT PRIMARY KEY,\n  run_id TEXT NOT NULL,\n  stage_key TEXT NOT NULL,\n  stage_index INTEGER NOT NULL,\n  status TEXT NOT NULL DEFAULT 'pending', -- pending|running|completed|failed|skipped\n  created_at TEXT NOT NULL,\n  subagent_type TEXT,\n  subagent_session_id TEXT,\n  started_at TEXT,\n  completed_at TEXT,\n  updated_at TEXT NOT NULL,\n  baton_path TEXT,\n  summary_md TEXT,\n  output_json TEXT,\n  error_text TEXT,\n  FOREIGN KEY (run_id) REFERENCES runs(run_id)\n);\n\nCREATE TABLE IF NOT EXISTS artifacts (\n  artifact_id TEXT PRIMARY KEY,\n  run_id TEXT,\n  stage_key TEXT,\n  type TEXT NOT NULL, -- plan|baton|evidence|diff|log|summary|commit|tool_output|snapshot\n  path TEXT NOT NULL,\n  sha256 TEXT,\n  meta_json TEXT NOT NULL DEFAULT '{}',\n  created_at TEXT NOT NULL,\n  FOREIGN KEY (run_id) REFERENCES runs(run_id)\n);\n\nCREATE TABLE IF NOT EXISTS tool_runs (\n  tool_run_id TEXT PRIMARY KEY,\n  run_id TEXT,\n  stage_key TEXT,\n  tool_name TEXT NOT NULL,\n  args_json TEXT NOT NULL DEFAULT '{}',\n  output_summary TEXT NOT NULL DEFAULT '',\n  output_artifact_id TEXT,\n  created_at TEXT NOT NULL,\n  FOREIGN KEY (run_id) REFERENCES runs(run_id)\n);\n\nCREATE TABLE IF NOT EXISTS events (\n  event_id TEXT PRIMARY KEY,\n  run_id TEXT,\n  stage_key TEXT,\n  type TEXT NOT NULL,\n  body_json TEXT NOT NULL DEFAULT '{}',\n  created_at TEXT NOT NULL,\n  FOREIGN KEY (run_id) REFERENCES runs(run_id)\n);\n\nCREATE TABLE IF NOT EXISTS injects (\n  inject_id TEXT PRIMARY KEY,\n  type TEXT NOT NULL DEFAULT 'note',\n  title TEXT NOT NULL,\n  body_md TEXT NOT NULL,\n  tags_json TEXT NOT NULL DEFAULT '[]',\n  scope TEXT NOT NULL DEFAULT 'repo', -- repo|run:<id>|story:<key>|global\n  source TEXT NOT NULL DEFAULT 'user', -- user|tool|agent|import\n  priority INTEGER NOT NULL DEFAULT 50,\n  expires_at TEXT,\n  sha256 TEXT,\n  created_at TEXT NOT NULL,\n  updated_at TEXT NOT NULL\n);\n\nCREATE TABLE IF NOT EXISTS running_batches (\n  batch_id TEXT PRIMARY KEY,\n  run_id TEXT,\n  session_id TEXT,\n  status TEXT NOT NULL DEFAULT 'running', -- running|completed|failed|aborted\n  created_at TEXT NOT NULL,\n  updated_at TEXT NOT NULL,\n  FOREIGN KEY (run_id) REFERENCES runs(run_id)\n);\n\nCREATE TABLE IF NOT EXISTS workflow_metrics (\n  metric_id TEXT PRIMARY KEY,\n  run_id TEXT,\n  stage_key TEXT,\n  name TEXT NOT NULL,\n  value_num REAL,\n  value_text TEXT,\n  created_at TEXT NOT NULL,\n  FOREIGN KEY (run_id) REFERENCES runs(run_id)\n);\n\nCREATE TABLE IF NOT EXISTS template_intents (\n  intent_key TEXT PRIMARY KEY,\n  body_md TEXT NOT NULL,\n  updated_at TEXT NOT NULL\n);\n\n-- vNext tables\n\nCREATE TABLE IF NOT EXISTS story_relations (\n  parent_story_key TEXT NOT NULL,\n  child_story_key TEXT NOT NULL,\n  relation_type TEXT NOT NULL DEFAULT 'split',\n  reason TEXT NOT NULL DEFAULT '',\n  created_at TEXT NOT NULL,\n  PRIMARY KEY (parent_story_key, child_story_key),\n  FOREIGN KEY (parent_story_key) REFERENCES stories(story_key),\n  FOREIGN KEY (child_story_key) REFERENCES stories(story_key)\n);\n\nCREATE TABLE IF NOT EXISTS continuations (\n  continuation_id INTEGER PRIMARY KEY AUTOINCREMENT,\n  session_id TEXT NOT NULL,\n  run_id TEXT,\n  directive_hash TEXT NOT NULL,\n  kind TEXT NOT NULL, -- continue|stage|blocked|repair\n  reason TEXT NOT NULL DEFAULT '',\n  created_at TEXT NOT NULL,\n  FOREIGN KEY (run_id) REFERENCES runs(run_id)\n);\n\nCREATE INDEX IF NOT EXISTS idx_continuations_session_created ON continuations(session_id, created_at DESC);\nCREATE INDEX IF NOT EXISTS idx_continuations_run_created ON continuations(run_id, created_at DESC);\n\nCREATE TABLE IF NOT EXISTS context_snapshots (\n  snapshot_id TEXT PRIMARY KEY,\n  run_id TEXT NOT NULL,\n  stage_key TEXT NOT NULL,\n  summary_md TEXT NOT NULL,\n  created_at TEXT NOT NULL,\n  FOREIGN KEY (run_id) REFERENCES runs(run_id)\n);\n\nCREATE INDEX IF NOT EXISTS idx_context_snapshots_run_created ON context_snapshots(run_id, created_at DESC);\n\nCREATE TABLE IF NOT EXISTS agent_sessions (\n  session_id TEXT PRIMARY KEY,\n  parent_session_id TEXT,\n  agent_name TEXT NOT NULL,\n  run_id TEXT,\n  stage_key TEXT,\n  status TEXT NOT NULL DEFAULT 'active',\n  created_at TEXT NOT NULL,\n  updated_at TEXT NOT NULL\n);\n\n-- Indexes\n\nCREATE INDEX IF NOT EXISTS idx_stories_state ON stories(state);\nCREATE INDEX IF NOT EXISTS idx_runs_story ON runs(story_key);\nCREATE INDEX IF NOT EXISTS idx_runs_status ON runs(status);\nCREATE INDEX IF NOT EXISTS idx_stage_runs_run ON stage_runs(run_id, stage_index);\nCREATE INDEX IF NOT EXISTS idx_artifacts_run_stage ON artifacts(run_id, stage_key, created_at DESC);\nCREATE INDEX IF NOT EXISTS idx_events_run ON events(run_id, created_at DESC);\nCREATE INDEX IF NOT EXISTS idx_tool_runs_run ON tool_runs(run_id, created_at DESC);\nCREATE INDEX IF NOT EXISTS idx_injects_scope_priority ON injects(scope, priority DESC, created_at DESC);\n\n-- Stronger invariants (SQLite partial indexes)\n-- Only one run may be 'running' at a time (single-repo harness by default).\nCREATE UNIQUE INDEX IF NOT EXISTS uniq_single_running_run\n  ON runs(status)\n  WHERE status = 'running';\n\n-- Only one story may be in_progress=1 at a time (pairs with single running run).\nCREATE UNIQUE INDEX IF NOT EXISTS uniq_single_in_progress_story\n  ON stories(in_progress)\n  WHERE in_progress = 1;\n\n";

package/dist/state/schema.js

@@ -85,6 +85,7 @@ CREATE TABLE IF NOT EXISTS stage_runs (
   stage_key TEXT NOT NULL,
   stage_index INTEGER NOT NULL,
   status TEXT NOT NULL DEFAULT 'pending', -- pending|running|completed|failed|skipped
+  created_at TEXT NOT NULL,
   subagent_type TEXT,
   subagent_session_id TEXT,
   started_at TEXT,

package/dist/state/types.d.ts

@@ -34,6 +34,7 @@ export type StageRunRow = {
     stage_key: StageKey;
     stage_index: number;
     status: StageStatus;
+    created_at: string;
     subagent_type: string | null;
     subagent_session_id: string | null;
     started_at: string | null;

package/dist/tools/stage.js

@@ -21,6 +21,42 @@ function ensureStageMatches(run, stage_key) {
         throw new Error(`Stage mismatch: run.current_stage_key=${run.current_stage_key} but got stage_key=${stage_key}`);
     }
 }
+function splitTasksIntoStories(db, tasks, run, now, newStoryKeys, relationReason) {
+    for (const task of tasks) {
+        const complexity = task.complexity ?? 5;
+        const subtasks = task.subtasks ?? [];
+        if (subtasks.length > 0) {
+            // Split into subtasks
+            console.log(`[Astrocode] Splitting task "${task.title}" into ${subtasks.length} subtasks`);
+            for (const subtask of subtasks) {
+                const key = insertStory(db, {
+                    title: `${task.title}: ${subtask}`,
+                    body_md: task.description ?? "",
+                    priority: Math.max(1, 10 - complexity),
+                    state: "queued",
+                    epic_key: run.story_key
+                });
+                newStoryKeys.push(key);
+                console.log(`[Astrocode] Created story ${key} for subtask`);
+                db.prepare("INSERT INTO story_relations (parent_story_key, child_story_key, relation_type, reason, created_at) VALUES (?, ?, ?, ?, ?)").run(run.story_key, key, "split", relationReason, now);
+            }
+        }
+        else if (complexity > 6) {
+            // Split complex tasks
+            console.log(`[Astrocode] Splitting complex task "${task.title}" (complexity ${complexity})`);
+            const key = insertStory(db, {
+                title: task.title,
+                body_md: task.description ?? "",
+                priority: Math.max(1, 10 - complexity),
+                state: "queued",
+                epic_key: run.story_key
+            });
+            newStoryKeys.push(key);
+            console.log(`[Astrocode] Created story ${key} for complex task`);
+            db.prepare("INSERT INTO story_relations (parent_story_key, child_story_key, relation_type, reason, created_at) VALUES (?, ?, ?, ?, ?)").run(run.story_key, key, "split", relationReason, now);
+        }
+    }
+}
 export function createAstroStageStartTool(opts) {
     const { config, db } = opts;
     return tool({
@@ -86,6 +122,13 @@ export function createAstroStageCompleteTool(opts) {
             if (parsed.astro_json.stage_key !== sk) {
                 return `❌ Stage Key Mismatch: ASTRO JSON has stage_key="${parsed.astro_json.stage_key}" but expected "${sk}". Update the JSON to match the current stage.`;
             }
+            // Context validation (warnings, not errors)
+            if (parsed.astro_json.run_id && parsed.astro_json.run_id !== rid) {
+                console.warn(`[Astrocode] ⚠️ Run ID mismatch in baton: expected "${rid}", got "${parsed.astro_json.run_id}". Proceeding anyway.`);
+            }
+            if (parsed.astro_json.story_key && parsed.astro_json.story_key !== run.story_key) {
+                console.warn(`[Astrocode] ⚠️ Story key mismatch in baton: expected "${run.story_key}", got "${parsed.astro_json.story_key}". Proceeding anyway.`);
+            }
             // Evidence requirement
             const evidenceRequired = (sk === "verify" && config.workflow.evidence_required.verify) ||
                 (sk === "implement" && config.workflow.evidence_required.implement);
@@ -163,46 +206,13 @@ export function createAstroStageCompleteTool(opts) {
                     for (const ns of parsed.astro_json.new_stories) {
                         const key = insertStory(db, { title: ns.title, body_md: ns.body_md ?? "", priority: ns.priority ?? 0, state: "queued" });
                         newStoryKeys.push(key);
-                        db.prepare("INSERT INTO story_relations (relation_id, parent_key, child_key, relation_type, created_at) VALUES (?, ?, ?, ?, ?)").run(newId("rel"), run.story_key, key, relation_reason, now);
+                        db.prepare("INSERT INTO story_relations (parent_story_key, child_story_key, relation_type, reason, created_at) VALUES (?, ?, ?, ?, ?)").run(run.story_key, key, "split", relation_reason, now);
                     }
                 }
                 // Automatic story splitting for complex tasks
                 if (allow_new_stories && parsed.astro_json.tasks?.length) {
                     console.log(`[Astrocode] Splitting ${parsed.astro_json.tasks.length} tasks into stories`);
-                    for (const task of parsed.astro_json.tasks) {
-                        const complexity = task.complexity ?? 5;
-                        const subtasks = task.subtasks ?? [];
-                        if (subtasks.length > 0) {
-                            // Split into subtasks
-                            console.log(`[Astrocode] Splitting task "${task.title}" into ${subtasks.length} subtasks`);
-                            for (const subtask of subtasks) {
-                                const key = insertStory(db, {
-                                    title: `${task.title}: ${subtask}`,
-                                    body_md: task.description ?? "",
-                                    priority: Math.max(1, 10 - complexity),
-                                    state: "queued",
-                                    epic_key: run.story_key
-                                });
-                                newStoryKeys.push(key);
-                                console.log(`[Astrocode] Created story ${key} for subtask`);
-                                db.prepare("INSERT INTO story_relations (relation_id, parent_key, child_key, relation_type, created_at) VALUES (?, ?, ?, ?, ?)").run(newId("rel"), run.story_key, key, "split from implement", now);
-                            }
-                        }
-                        else if (complexity > 6) {
-                            // Split complex tasks
-                            console.log(`[Astrocode] Splitting complex task "${task.title}" (complexity ${complexity})`);
-                            const key = insertStory(db, {
-                                title: task.title,
-                                body_md: task.description ?? "",
-                                priority: Math.max(1, 10 - complexity),
-                                state: "queued",
-                                epic_key: run.story_key
-                            });
-                            newStoryKeys.push(key);
-                            console.log(`[Astrocode] Created story ${key} for complex task`);
-                            db.prepare("INSERT INTO story_relations (relation_id, parent_key, child_key, relation_type, created_at) VALUES (?, ?, ?, ?, ?)").run(newId("rel"), run.story_key, key, "split from implement", now);
-                        }
-                    }
+                    splitTasksIntoStories(db, parsed.astro_json.tasks, run, now, newStoryKeys, "split from stage output");
                 }
                 // Skip spec stage if spec already exists
                 if (sk === "plan" && next === "spec") {
@@ -216,35 +226,12 @@ export function createAstroStageCompleteTool(opts) {
                 }
                 // Split stories during implementation if tasks are identified
                 if (sk === "implement" && allow_new_stories && parsed.astro_json.tasks?.length) {
-                    for (const task of parsed.astro_json.tasks) {
-                        const complexity = task.complexity ?? 5;
-                        const subtasks = task.subtasks ?? [];
-                        if (subtasks.length > 0) {
-                            // Split into subtasks
-                            for (const subtask of subtasks) {
-                                const key = insertStory(db, {
-                                    title: `${task.title}: ${subtask}`,
-                                    body_md: task.description ?? "",
-                                    priority: Math.max(1, 10 - complexity),
-                                    state: "queued",
-                                    epic_key: run.story_key
-                                });
-                                newStoryKeys.push(key);
-                                db.prepare("INSERT INTO story_relations (relation_id, parent_key, child_key, relation_type, created_at) VALUES (?, ?, ?, ?, ?)").run(newId("rel"), run.story_key, key, "split from implement", now);
-                            }
-                        }
-                        else if (complexity > 6) {
-                            // Split complex tasks
-                            const key = insertStory(db, {
-                                title: task.title,
-                                body_md: task.description ?? "",
-                                priority: Math.max(1, 10 - complexity),
-                                state: "queued",
-                                epic_key: run.story_key
-                            });
-                            newStoryKeys.push(key);
-                            db.prepare("INSERT INTO story_relations (relation_id, parent_key, child_key, relation_type, created_at) VALUES (?, ?, ?, ?, ?)").run(newId("rel"), run.story_key, key, "split from implement", now);
-                        }
+                    splitTasksIntoStories(db, parsed.astro_json.tasks, run, now, newStoryKeys, "split from implement");
+                }
+                // Validate blocked status includes questions
+                if (parsed.astro_json.status === "blocked") {
+                    if (!parsed.astro_json.questions || parsed.astro_json.questions.length === 0) {
+                        return { ok: false, next_stage: null, new_stories: newStoryKeys, error: "Blocked status requires questions[] array to be non-empty. Add clarifying questions for user input." };
                     }
                 }
                 if (parsed.astro_json.status !== "ok") {

package/dist/tools/workflow.js

@@ -17,7 +17,12 @@ const STAGE_TO_AGENT_MAP = {
     verify: "Verify",
     close: "Close"
 };
-function resolveAgentName(stageKey) {
+function resolveAgentName(stageKey, config) {
+    // Use configurable agent names from config, fallback to hardcoded map, then General
+    const agentNames = config.agents?.stage_agent_names;
+    if (agentNames && agentNames[stageKey]) {
+        return agentNames[stageKey];
+    }
     return STAGE_TO_AGENT_MAP[stageKey] || "General";
 }
 function stageGoal(stage, cfg) {
@@ -124,16 +129,23 @@ export function createAstroWorkflowProceedTool(opts) {
                     const run = db.prepare("SELECT * FROM runs WHERE run_id=?").get(active.run_id);
                     const story = db.prepare("SELECT * FROM stories WHERE story_key=?").get(run.story_key);
                     // Mark stage started + set subagent_type to the stage agent.
-                    let agentName = resolveAgentName(next.stage_key);
+                    let agentName = resolveAgentName(next.stage_key, config);
                     console.log(`[Astrocode] Resolving agent for ${next.stage_key}: ${agentName}`);
                     console.log(`[Astrocode] Available agents:`, Object.keys(config.agent || {}));
-                    // Validate agent availability
+                    // Validate agent availability with fallback chain
                     const systemConfig = config;
                     if (!systemConfig.agent || !systemConfig.agent[agentName]) {
                         console.warn(`[Astrocode] Agent ${agentName} not found in config. Falling back to General.`);
                         console.warn(`[Astrocode] Agent check: config.agent exists: ${!!systemConfig.agent}, agentName in config: ${systemConfig.agent ? agentName in systemConfig.agent : 'N/A'}`);
-                        // Fallback to General
                         agentName = "General";
+                        // Second fallback to orchestrator if General also unavailable
+                        if (!systemConfig.agent || !systemConfig.agent[agentName]) {
+                            console.warn(`[Astrocode] General agent also unavailable. Falling back to orchestrator.`);
+                            agentName = config.agents?.orchestrator_name || "Astro";
+                            if (!systemConfig.agent || !systemConfig.agent[agentName]) {
+                                throw new Error(`Critical: No agents available for delegation. Primary: ${resolveAgentName(next.stage_key, config)}, General, Orchestrator: ${agentName}`);
+                            }
+                        }
                     }
                     console.log(`[Astrocode] Delegating stage ${next.stage_key} to agent: ${agentName}`);
                     withTx(db, () => {

package/dist/workflow/baton.js

@@ -1,5 +1,5 @@
 import { clampLines, normalizeNewlines, stripCodeFences } from "../shared/text";
-import { z } from "zod";
+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"]);
@@ -59,12 +59,22 @@ export function parseStageOutputText(text) {
         return { baton_md: baton, astro_json: astroJson, astro_json_raw: cleaned, error: null };
     }
     catch (e) {
-        return {
-            baton_md: baton,
-            astro_json: null,
-            astro_json_raw: jsonRaw,
-            error: `Failed to parse ASTRO JSON: ${String(e)}`,
-        };
+        if (e instanceof ZodError) {
+            return {
+                baton_md: baton,
+                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) {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "astrocode-workflow",
-  "version": "0.1.8",
+  "version": "0.1.11",
   "type": "module",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",
@@ -18,7 +18,7 @@
   "dependencies": {
     "@opencode-ai/plugin": "^1.1.19",
     "@opencode-ai/sdk": "^1.1.19",
-    "astrocode-workflow": "^0.1.3",
+    "astrocode-workflow": "^0.1.8",
     "jsonc-parser": "^3.2.0",
     "zod": "4.1.8"
   },

package/src/agents/registry.ts

@@ -301,6 +301,20 @@ export function createAstroAgents(opts: {
     "utility"
   );
 
+  // Fallback general agent for delegation failures
+  agents["General"] = mk(
+    "General",
+    {
+      description: "General-purpose fallback agent for delegation.",
+      mode: "subagent",
+      hidden: true,
+      temperature: 0.1,
+      prompt: BASE_STAGE_PROMPT,
+      permission: stageReadOnlyPermissions(),
+    },
+    "utility"
+  );
+
   // Allow user config to disable certain agents
   for (const disabled of pluginConfig.disabled_agents) {
     delete agents[disabled];

package/src/shared/paths.ts

@@ -62,7 +62,8 @@ export function assertInsideAstro(repoRoot: string, filePath: string) {
   const abs = path.resolve(filePath);
   const astroRoot = path.resolve(path.join(repoRoot, ".astro"));
   if (!abs.startsWith(astroRoot + path.sep) && abs !== astroRoot) {
-    throw new Error(`Refusing to write outside .astro: ${filePath}`);
+    const relPath = path.relative(repoRoot, filePath);
+    throw new Error(`Refusing to write outside .astro: ${filePath} (relative: ${relPath}, astroRoot: ${astroRoot})`);
   }
   if (!abs.startsWith(absRepo + path.sep) && abs !== absRepo) {
     throw new Error(`Refusing to write outside repo root: ${filePath}`);

package/src/state/schema.ts

@@ -87,6 +87,7 @@ CREATE TABLE IF NOT EXISTS stage_runs (
   stage_key TEXT NOT NULL,
   stage_index INTEGER NOT NULL,
   status TEXT NOT NULL DEFAULT 'pending', -- pending|running|completed|failed|skipped
+  created_at TEXT NOT NULL,
   subagent_type TEXT,
   subagent_session_id TEXT,
   started_at TEXT,

package/src/state/types.ts

@@ -38,6 +38,7 @@ export type StageRunRow = {
   stage_key: StageKey;
   stage_index: number;
   status: StageStatus;
+  created_at: string;
   subagent_type: string | null;
   subagent_session_id: string | null;
   started_at: string | null;

package/src/tools/stage.ts

@@ -26,6 +26,65 @@ function ensureStageMatches(run: any, stage_key: StageKey) {
   }
 }
 
+function splitTasksIntoStories(
+  db: SqliteDb,
+  tasks: any[],
+  run: any,
+  now: string,
+  newStoryKeys: string[],
+  relationReason: string
+) {
+  for (const task of tasks) {
+    const complexity = task.complexity ?? 5;
+    const subtasks = task.subtasks ?? [];
+    if (subtasks.length > 0) {
+      // Split into subtasks
+      console.log(`[Astrocode] Splitting task "${task.title}" into ${subtasks.length} subtasks`);
+      for (const subtask of subtasks) {
+        const key = insertStory(db, {
+          title: `${task.title}: ${subtask}`,
+          body_md: task.description ?? "",
+          priority: Math.max(1, 10 - complexity),
+          state: "queued",
+          epic_key: run.story_key
+        });
+        newStoryKeys.push(key);
+        console.log(`[Astrocode] Created story ${key} for subtask`);
+        db.prepare(
+          "INSERT INTO story_relations (parent_story_key, child_story_key, relation_type, reason, created_at) VALUES (?, ?, ?, ?, ?)"
+        ).run(
+          run.story_key,
+          key,
+          "split",
+          relationReason,
+          now
+        );
+      }
+    } else if (complexity > 6) {
+      // Split complex tasks
+      console.log(`[Astrocode] Splitting complex task "${task.title}" (complexity ${complexity})`);
+      const key = insertStory(db, {
+        title: task.title,
+        body_md: task.description ?? "",
+        priority: Math.max(1, 10 - complexity),
+        state: "queued",
+        epic_key: run.story_key
+      });
+      newStoryKeys.push(key);
+      console.log(`[Astrocode] Created story ${key} for complex task`);
+      db.prepare(
+        "INSERT INTO story_relations (parent_story_key, child_story_key, relation_type, reason, created_at) VALUES (?, ?, ?, ?, ?)"
+      ).run(
+        run.story_key,
+        key,
+        "split",
+        relationReason,
+        now
+      );
+    }
+  }
+}
+
 export function createAstroStageStartTool(opts: { ctx: any; config: AstrocodeConfig; db: SqliteDb }): ToolDefinition {
   const { config, db } = opts;
 
@@ -97,9 +156,17 @@ export function createAstroStageCompleteTool(opts: { ctx: any; config: Astrocode
          return `❌ JSON Parse Error: ${parsed.error ?? "ASTRO JSON missing"}. Ensure output includes <!-- ASTRO_JSON_BEGIN -->{...}<!-- ASTRO_JSON_END --> markers with valid JSON.`;
        }
 
-       if (parsed.astro_json.stage_key !== sk) {
-         return `❌ Stage Key Mismatch: ASTRO JSON has stage_key="${parsed.astro_json.stage_key}" but expected "${sk}". Update the JSON to match the current stage.`;
-       }
+        if (parsed.astro_json.stage_key !== sk) {
+          return `❌ Stage Key Mismatch: ASTRO JSON has stage_key="${parsed.astro_json.stage_key}" but expected "${sk}". Update the JSON to match the current stage.`;
+        }
+
+        // Context validation (warnings, not errors)
+        if (parsed.astro_json.run_id && parsed.astro_json.run_id !== rid) {
+          console.warn(`[Astrocode] ⚠️ Run ID mismatch in baton: expected "${rid}", got "${parsed.astro_json.run_id}". Proceeding anyway.`);
+        }
+        if (parsed.astro_json.story_key && parsed.astro_json.story_key !== run.story_key) {
+          console.warn(`[Astrocode] ⚠️ Story key mismatch in baton: expected "${run.story_key}", got "${parsed.astro_json.story_key}". Proceeding anyway.`);
+        }
 
       // Evidence requirement
       const evidenceRequired =
@@ -211,11 +278,11 @@ export function createAstroStageCompleteTool(opts: { ctx: any; config: Astrocode
             const key = insertStory(db, { title: ns.title, body_md: ns.body_md ?? "", priority: ns.priority ?? 0, state: "queued" });
             newStoryKeys.push(key);
             db.prepare(
-              "INSERT INTO story_relations (relation_id, parent_key, child_key, relation_type, created_at) VALUES (?, ?, ?, ?, ?)"
+              "INSERT INTO story_relations (parent_story_key, child_story_key, relation_type, reason, created_at) VALUES (?, ?, ?, ?, ?)"
             ).run(
-              newId("rel"),
               run.story_key,
               key,
+              "split",
               relation_reason,
               now
             );
@@ -225,55 +292,7 @@ export function createAstroStageCompleteTool(opts: { ctx: any; config: Astrocode
         // Automatic story splitting for complex tasks
         if (allow_new_stories && parsed.astro_json.tasks?.length) {
           console.log(`[Astrocode] Splitting ${parsed.astro_json.tasks.length} tasks into stories`);
-          for (const task of parsed.astro_json.tasks) {
-            const complexity = task.complexity ?? 5;
-            const subtasks = task.subtasks ?? [];
-            if (subtasks.length > 0) {
-              // Split into subtasks
-              console.log(`[Astrocode] Splitting task "${task.title}" into ${subtasks.length} subtasks`);
-              for (const subtask of subtasks) {
-                const key = insertStory(db, {
-                  title: `${task.title}: ${subtask}`,
-                  body_md: task.description ?? "",
-                  priority: Math.max(1, 10 - complexity),
-                  state: "queued",
-                  epic_key: run.story_key
-                });
-                newStoryKeys.push(key);
-                console.log(`[Astrocode] Created story ${key} for subtask`);
-                db.prepare(
-                  "INSERT INTO story_relations (relation_id, parent_key, child_key, relation_type, created_at) VALUES (?, ?, ?, ?, ?)"
-                ).run(
-                  newId("rel"),
-                  run.story_key,
-                  key,
-                  "split from implement",
-                  now
-                );
-              }
-            } else if (complexity > 6) {
-              // Split complex tasks
-              console.log(`[Astrocode] Splitting complex task "${task.title}" (complexity ${complexity})`);
-              const key = insertStory(db, {
-                title: task.title,
-                body_md: task.description ?? "",
-                priority: Math.max(1, 10 - complexity),
-                state: "queued",
-                epic_key: run.story_key
-              });
-              newStoryKeys.push(key);
-              console.log(`[Astrocode] Created story ${key} for complex task`);
-              db.prepare(
-                "INSERT INTO story_relations (relation_id, parent_key, child_key, relation_type, created_at) VALUES (?, ?, ?, ?, ?)"
-              ).run(
-                newId("rel"),
-                run.story_key,
-                key,
-                "split from implement",
-                now
-              );
-            }
-          }
+          splitTasksIntoStories(db, parsed.astro_json.tasks, run, now, newStoryKeys, "split from stage output");
         }
 
         // Skip spec stage if spec already exists
@@ -289,50 +308,13 @@ export function createAstroStageCompleteTool(opts: { ctx: any; config: Astrocode
 
         // Split stories during implementation if tasks are identified
         if (sk === "implement" && allow_new_stories && parsed.astro_json.tasks?.length) {
-          for (const task of parsed.astro_json.tasks) {
-            const complexity = task.complexity ?? 5;
-            const subtasks = task.subtasks ?? [];
-            if (subtasks.length > 0) {
-              // Split into subtasks
-              for (const subtask of subtasks) {
-                const key = insertStory(db, {
-                  title: `${task.title}: ${subtask}`,
-                  body_md: task.description ?? "",
-                  priority: Math.max(1, 10 - complexity),
-                  state: "queued",
-                  epic_key: run.story_key
-                });
-                newStoryKeys.push(key);
-                db.prepare(
-                  "INSERT INTO story_relations (relation_id, parent_key, child_key, relation_type, created_at) VALUES (?, ?, ?, ?, ?)"
-                ).run(
-                  newId("rel"),
-                  run.story_key,
-                  key,
-                  "split from implement",
-                  now
-                );
-              }
-            } else if (complexity > 6) {
-              // Split complex tasks
-              const key = insertStory(db, {
-                title: task.title,
-                body_md: task.description ?? "",
-                priority: Math.max(1, 10 - complexity),
-                state: "queued",
-                epic_key: run.story_key
-              });
-              newStoryKeys.push(key);
-              db.prepare(
-                "INSERT INTO story_relations (relation_id, parent_key, child_key, relation_type, created_at) VALUES (?, ?, ?, ?, ?)"
-              ).run(
-                newId("rel"),
-                run.story_key,
-                key,
-                "split from implement",
-                now
-              );
-            }
+          splitTasksIntoStories(db, parsed.astro_json.tasks, run, now, newStoryKeys, "split from implement");
+        }
+
+        // Validate blocked status includes questions
+        if (parsed.astro_json.status === "blocked") {
+          if (!parsed.astro_json.questions || parsed.astro_json.questions.length === 0) {
+            return { ok: false as const, next_stage: null as StageKey | null, new_stories: newStoryKeys, error: "Blocked status requires questions[] array to be non-empty. Add clarifying questions for user input." };
           }
         }
 

package/src/tools/workflow.ts

@@ -22,7 +22,12 @@ const STAGE_TO_AGENT_MAP: Record<string, string> = {
   close: "Close"
 };
 
-function resolveAgentName(stageKey: string): string {
+function resolveAgentName(stageKey: StageKey, config: AstrocodeConfig): string {
+  // Use configurable agent names from config, fallback to hardcoded map, then General
+  const agentNames = config.agents?.stage_agent_names;
+  if (agentNames && agentNames[stageKey]) {
+    return agentNames[stageKey];
+  }
   return STAGE_TO_AGENT_MAP[stageKey] || "General";
 }
 
@@ -151,18 +156,25 @@ export function createAstroWorkflowProceedTool(opts: { ctx: any; config: Astroco
           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);
+          let agentName = resolveAgentName(next.stage_key, config);
 
           console.log(`[Astrocode] Resolving agent for ${next.stage_key}: ${agentName}`);
           console.log(`[Astrocode] Available agents:`, Object.keys((config as any).agent || {}));
 
-          // Validate agent availability
+          // Validate agent availability with fallback chain
           const systemConfig = config as any;
           if (!systemConfig.agent || !systemConfig.agent[agentName]) {
             console.warn(`[Astrocode] Agent ${agentName} not found in config. Falling back to General.`);
             console.warn(`[Astrocode] Agent check: config.agent exists: ${!!systemConfig.agent}, agentName in config: ${systemConfig.agent ? agentName in systemConfig.agent : 'N/A'}`);
-            // Fallback to General
             agentName = "General";
+            // Second fallback to orchestrator if General also unavailable
+            if (!systemConfig.agent || !systemConfig.agent[agentName]) {
+              console.warn(`[Astrocode] General agent also unavailable. Falling back to orchestrator.`);
+              agentName = config.agents?.orchestrator_name || "Astro";
+              if (!systemConfig.agent || !systemConfig.agent[agentName]) {
+                throw new Error(`Critical: No agents available for delegation. Primary: ${resolveAgentName(next.stage_key, config)}, General, Orchestrator: ${agentName}`);
+              }
+            }
           }
 
           console.log(`[Astrocode] Delegating stage ${next.stage_key} to agent: ${agentName}`);

package/src/workflow/baton.ts

@@ -1,7 +1,7 @@
 import { tool } from "@opencode-ai/plugin/tool";
 import type { AstrocodeConfig } from "../config/schema";
 import { clampLines, normalizeNewlines, stripCodeFences } from "../shared/text";
-import { z } from "zod";
+import { z, ZodError } from "zod";
 
 export const ASTRO_JSON_BEGIN = "<!-- ASTRO_JSON_BEGIN -->";
 export const ASTRO_JSON_END = "<!-- ASTRO_JSON_END -->";
@@ -95,12 +95,21 @@ export function parseStageOutputText(text: string): ParsedStageOutput {
     const astroJson = AstroJsonSchema.parse(parsed);
     return { baton_md: baton, astro_json: astroJson, astro_json_raw: cleaned, error: null };
   } catch (e) {
-    return {
-      baton_md: baton,
-      astro_json: null,
-      astro_json_raw: jsonRaw,
-      error: `Failed to parse ASTRO JSON: ${String(e)}`,
-    };
+    if (e instanceof ZodError) {
+      return {
+        baton_md: baton,
+        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.`,
+      };
+    }
   }
 }