astrocode-workflow 0.1.55 → 0.1.56

package/dist/hooks/inject-provider.js

@@ -16,24 +16,76 @@ export function createInjectProvider(opts) {
     function markInjected(injectId, nowMs) {
         injectedCache.set(injectId, nowMs);
     }
+    function getInjectionDiagnostics(nowIso, scopeAllowlist, typeAllowlist) {
+        // Get ALL injects to analyze filtering
+        const allInjects = db.prepare("SELECT * FROM injects").all();
+        let total = allInjects.length;
+        let selected = 0;
+        let skippedExpired = 0;
+        let skippedScope = 0;
+        let skippedType = 0;
+        let eligibleIds = [];
+        for (const inject of allInjects) {
+            // Check expiration
+            if (inject.expires_at && inject.expires_at <= nowIso) {
+                skippedExpired++;
+                continue;
+            }
+            // Check scope
+            if (!scopeAllowlist.includes(inject.scope)) {
+                skippedScope++;
+                continue;
+            }
+            // Check type
+            if (!typeAllowlist.includes(inject.type)) {
+                skippedType++;
+                continue;
+            }
+            // This inject is eligible
+            selected++;
+            eligibleIds.push(inject.inject_id);
+        }
+        return {
+            now: nowIso,
+            scopes_considered: scopeAllowlist,
+            types_considered: typeAllowlist,
+            total_injects: total,
+            selected_eligible: selected,
+            skipped: {
+                expired: skippedExpired,
+                scope: skippedScope,
+                type: skippedType,
+            },
+            eligible_ids: eligibleIds,
+        };
+    }
     async function injectEligibleInjects(sessionId) {
         const now = nowISO();
         const nowMs = Date.now();
-        // Get eligible injects - use allowlists from config or defaults
+        // Get allowlists from config or defaults
         const scopeAllowlist = config.inject?.scope_allowlist ?? ["repo", "global"];
         const typeAllowlist = config.inject?.type_allowlist ?? ["note", "policy"];
+        // Get diagnostic data
+        const diagnostics = getInjectionDiagnostics(now, scopeAllowlist, typeAllowlist);
         const eligibleInjects = selectEligibleInjects(db, {
             nowIso: now,
             scopeAllowlist,
             typeAllowlist,
             limit: config.inject?.max_per_turn ?? 5,
         });
-        if (eligibleInjects.length === 0)
+        let injected = 0;
+        let skippedDeduped = 0;
+        if (eligibleInjects.length === 0) {
+            // Log when no injects are eligible
+            console.log(`[Astrocode:inject] ${now} selected=${diagnostics.selected_eligible} injected=0 skipped={expired:${diagnostics.skipped.expired} scope:${diagnostics.skipped.scope} type:${diagnostics.skipped.type} deduped:0}`);
             return;
+        }
         // Inject each eligible inject, skipping recently injected ones
         for (const inject of eligibleInjects) {
-            if (shouldSkipInject(inject.inject_id, nowMs))
+            if (shouldSkipInject(inject.inject_id, nowMs)) {
+                skippedDeduped++;
                 continue;
+            }
             // Format as injection message
             const formattedText = `[Inject: ${inject.title}]\n\n${inject.body_md}`;
             await injectChatPrompt({
@@ -42,8 +94,11 @@ export function createInjectProvider(opts) {
                 text: formattedText,
                 agent: "Astrocode"
             });
+            injected++;
             markInjected(inject.inject_id, nowMs);
         }
+        // Log diagnostic summary
+        console.log(`[Astrocode:inject] ${now} selected=${diagnostics.selected_eligible} injected=${injected} skipped={expired:${diagnostics.skipped.expired} scope:${diagnostics.skipped.scope} type:${diagnostics.skipped.type} deduped:${skippedDeduped}}`);
     }
     // Public hook handlers
     return {

package/dist/tools/index.js

@@ -6,7 +6,7 @@ import { createAstroRunGetTool, createAstroRunAbortTool } from "./run";
 import { createAstroWorkflowProceedTool } from "./workflow";
 import { createAstroStageStartTool, createAstroStageCompleteTool, createAstroStageFailTool, createAstroStageResetTool } from "./stage";
 import { createAstroArtifactPutTool, createAstroArtifactListTool, createAstroArtifactGetTool } from "./artifacts";
-import { createAstroInjectPutTool, createAstroInjectListTool, createAstroInjectSearchTool, createAstroInjectGetTool } from "./injects";
+import { createAstroInjectPutTool, createAstroInjectListTool, createAstroInjectSearchTool, createAstroInjectGetTool, createAstroInjectEligibleTool, createAstroInjectDebugDueTool } from "./injects";
 import { createAstroRepairTool } from "./repair";
 export function createAstroTools(opts) {
     const { ctx, config, db, agents } = opts;
@@ -39,6 +39,8 @@ export function createAstroTools(opts) {
         tools.astro_inject_list = createAstroInjectListTool({ ctx, config, db });
         tools.astro_inject_search = createAstroInjectSearchTool({ ctx, config, db });
         tools.astro_inject_get = createAstroInjectGetTool({ ctx, config, db });
+        tools.astro_inject_eligible = createAstroInjectEligibleTool({ ctx, config, db });
+        tools.astro_inject_debug_due = createAstroInjectDebugDueTool({ ctx, config, db });
         tools.astro_repair = createAstroRepairTool({ ctx, config, db });
     }
     else {

package/dist/tools/injects.d.ts

@@ -46,3 +46,8 @@ export declare function createAstroInjectEligibleTool(opts: {
     config: AstrocodeConfig;
     db: SqliteDb;
 }): ToolDefinition;
+export declare function createAstroInjectDebugDueTool(opts: {
+    ctx: any;
+    config: AstrocodeConfig;
+    db: SqliteDb;
+}): ToolDefinition;

package/dist/tools/injects.js

@@ -137,3 +137,82 @@ export function createAstroInjectEligibleTool(opts) {
         },
     });
 }
+export function createAstroInjectDebugDueTool(opts) {
+    const { db } = opts;
+    return tool({
+        description: "Debug: show comprehensive injection diagnostics - why injects were selected/skipped.",
+        args: {
+            scopes_json: tool.schema.string().default('["repo","global"]'),
+            types_json: tool.schema.string().default('["note","policy"]'),
+        },
+        execute: async ({ scopes_json, types_json }) => {
+            const now = nowISO();
+            const scopes = JSON.parse(scopes_json);
+            const types = JSON.parse(types_json);
+            // Get ALL injects to analyze filtering
+            const allInjects = db.prepare("SELECT * FROM injects").all();
+            let total = allInjects.length;
+            let selected = 0;
+            let skippedExpired = 0;
+            let skippedScope = 0;
+            let skippedType = 0;
+            const excludedReasons = [];
+            const selectedInjects = [];
+            for (const inject of allInjects) {
+                const reasons = [];
+                // Check expiration
+                if (inject.expires_at && inject.expires_at <= now) {
+                    reasons.push("expired");
+                    skippedExpired++;
+                }
+                // Check scope
+                if (!scopes.includes(inject.scope)) {
+                    reasons.push("scope");
+                    skippedScope++;
+                }
+                // Check type
+                if (!types.includes(inject.type)) {
+                    reasons.push("type");
+                    skippedType++;
+                }
+                if (reasons.length > 0) {
+                    excludedReasons.push({
+                        inject_id: inject.inject_id,
+                        title: inject.title,
+                        reasons: reasons,
+                        scope: inject.scope,
+                        type: inject.type,
+                        expires_at: inject.expires_at,
+                    });
+                }
+                else {
+                    selected++;
+                    selectedInjects.push({
+                        inject_id: inject.inject_id,
+                        title: inject.title,
+                        scope: inject.scope,
+                        type: inject.type,
+                        expires_at: inject.expires_at,
+                    });
+                }
+            }
+            return JSON.stringify({
+                now,
+                scopes_considered: scopes,
+                types_considered: types,
+                summary: {
+                    total_injects: total,
+                    selected_eligible: selected,
+                    excluded_total: total - selected,
+                    skipped_breakdown: {
+                        expired: skippedExpired,
+                        scope: skippedScope,
+                        type: skippedType,
+                    }
+                },
+                selected_injects: selectedInjects,
+                excluded_injects: excludedReasons,
+            }, null, 2);
+        },
+    });
+}

package/dist/tools/workflow.d.ts

@@ -1,6 +1,9 @@
 import { type ToolDefinition } from "@opencode-ai/plugin/tool";
 import type { AstrocodeConfig } from "../config/schema";
 import type { SqliteDb } from "../state/db";
+import type { StageKey } from "../state/types";
+export declare const STAGE_TO_AGENT_MAP: Record<string, string>;
+export declare function resolveAgentName(stageKey: StageKey, config: AstrocodeConfig, agents?: any, warnings?: string[]): string;
 import { AgentConfig } from "@opencode-ai/sdk";
 export declare function createAstroWorkflowProceedTool(opts: {
     ctx: any;

package/dist/tools/workflow.js

@@ -9,7 +9,7 @@ import { newEventId } from "../state/ids";
 import { debug } from "../shared/log";
 import { createToastManager } from "../ui/toasts";
 // Agent name mapping for case-sensitive resolution
-const STAGE_TO_AGENT_MAP = {
+export const STAGE_TO_AGENT_MAP = {
     frame: "Frame",
     plan: "Plan",
     spec: "Spec",
@@ -18,13 +18,39 @@ const STAGE_TO_AGENT_MAP = {
     verify: "Verify",
     close: "Close"
 };
-function resolveAgentName(stageKey, config) {
+export function resolveAgentName(stageKey, config, agents, warnings) {
     // Use configurable agent names from config, fallback to hardcoded map, then General
     const agentNames = config.agents?.stage_agent_names;
+    let candidate;
     if (agentNames && agentNames[stageKey]) {
-        return agentNames[stageKey];
+        candidate = agentNames[stageKey];
     }
-    return STAGE_TO_AGENT_MAP[stageKey] || "General";
+    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, cfg) {
     switch (stage) {
@@ -99,6 +125,7 @@ export function createAstroWorkflowProceedTool(opts) {
             const sessionId = ctx.sessionID;
             const steps = Math.min(max_steps, config.workflow.loop_max_steps_hard_cap);
             const actions = [];
+            const warnings = [];
             const startedAt = nowISO();
             for (let i = 0; i < steps; i++) {
                 const next = decideNextAction(db, config);
@@ -172,7 +199,7 @@ 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, config);
+                    let agentName = resolveAgentName(next.stage_key, config, agents, warnings);
                     // Validate agent availability with fallback chain
                     const systemConfig = config;
                     // Check both the system config agent map (if present) OR the local agents map passed to the tool
@@ -197,7 +224,7 @@ export function createAstroWorkflowProceedTool(opts) {
                         // Skip General fallback for stage agents to avoid malformed output
                         agentName = config.agents?.orchestrator_name || "Astro";
                         if (!agentExists(agentName)) {
-                            throw new Error(`Critical: No agents available for delegation. Primary: ${resolveAgentName(next.stage_key, config)}, Orchestrator: ${agentName}`);
+                            throw new Error(`Critical: No agents available for delegation. Primary: ${resolveAgentName(next.stage_key, config, agents, warnings)}, Orchestrator: ${agentName}`);
                         }
                     }
                     withTx(db, () => {
@@ -291,6 +318,11 @@ export function createAstroWorkflowProceedTool(opts) {
             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();
         },
     });

package/dist/workflow/context.d.ts

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

package/dist/workflow/context.js

@@ -27,6 +27,49 @@ function statusIcon(status) {
             return "⬜";
     }
 }
+/**
+ * Check if a context snapshot is stale by comparing DB timestamps
+ */
+export function isContextSnapshotStale(snapshotText, db, maxAgeSeconds = 300) {
+    // Extract run_id from snapshot
+    const runIdMatch = snapshotText.match(/Run: `([^`]+)`/);
+    if (!runIdMatch)
+        return true; // Can't validate without run_id
+    const runId = runIdMatch[1];
+    // Extract snapshot's claimed updated_at
+    const snapshotUpdatedMatch = snapshotText.match(/updated: ([^\)]+)\)/);
+    if (!snapshotUpdatedMatch)
+        return true; // Fallback to age-based check
+    try {
+        const snapshotUpdatedAt = snapshotUpdatedMatch[1];
+        const currentRun = db.prepare("SELECT updated_at FROM runs WHERE run_id = ?").get(runId);
+        if (!currentRun?.updated_at)
+            return true; // Run doesn't exist
+        // Compare timestamps - if DB is newer than snapshot claims, snapshot is stale
+        const snapshotTime = new Date(snapshotUpdatedAt).getTime();
+        const currentTime = new Date(currentRun.updated_at).getTime();
+        return currentTime > snapshotTime;
+    }
+    catch (error) {
+        // Fallback to age-based staleness if parsing fails
+        const timestampMatch = snapshotText.match(/generated: (\d{4}-\d{2}-\d{2}T\d{2}:\d{2}:\d{2}\.\d{3}Z)/);
+        if (!timestampMatch)
+            return false;
+        const generatedAt = new Date(timestampMatch[1]);
+        const now = new Date();
+        const ageSeconds = (now.getTime() - generatedAt.getTime()) / 1000;
+        return ageSeconds > maxAgeSeconds;
+    }
+}
+/**
+ * Add staleness indicator to context snapshot if needed
+ */
+export function addStalenessIndicator(snapshotText, db, maxAgeSeconds = 300) {
+    if (isContextSnapshotStale(snapshotText, db, maxAgeSeconds)) {
+        return snapshotText.replace(/# Astrocode Context \(generated: ([^\)]+)\)/, "# Astrocode Context (generated: $1) ⚠️ STALE - DB state has changed");
+    }
+    return snapshotText;
+}
 export function buildContextSnapshot(opts) {
     const { db, config, run_id, next_action } = opts;
     const run = getRun(db, run_id);
@@ -35,8 +78,11 @@ export function buildContextSnapshot(opts) {
     const story = getStory(db, run.story_key);
     const stageRuns = listStageRuns(db, run_id);
     const lines = [];
-    lines.push(`# Astrocode Context`);
-    lines.push(`- Run: \`${run.run_id}\`  Status: **${run.status}**`);
+    // Add timestamps for staleness checking
+    const now = new Date();
+    const timestamp = now.toISOString();
+    lines.push(`# Astrocode Context (generated: ${timestamp})`);
+    lines.push(`- Run: \`${run.run_id}\`  Status: **${run.status}** (updated: ${run.updated_at})`);
     if (run.current_stage_key)
         lines.push(`- Current stage: \`${run.current_stage_key}\``);
     if (next_action)

package/package.json

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

package/src/hooks/inject-provider.ts

@@ -32,14 +32,67 @@ export function createInjectProvider(opts: {
     injectedCache.set(injectId, nowMs);
   }
 
+  function getInjectionDiagnostics(nowIso: string, scopeAllowlist: string[], typeAllowlist: string[]): any {
+    // Get ALL injects to analyze filtering
+    const allInjects = db.prepare("SELECT * FROM injects").all() as any[];
+
+    let total = allInjects.length;
+    let selected = 0;
+    let skippedExpired = 0;
+    let skippedScope = 0;
+    let skippedType = 0;
+    let eligibleIds: string[] = [];
+
+    for (const inject of allInjects) {
+      // Check expiration
+      if (inject.expires_at && inject.expires_at <= nowIso) {
+        skippedExpired++;
+        continue;
+      }
+
+      // Check scope
+      if (!scopeAllowlist.includes(inject.scope)) {
+        skippedScope++;
+        continue;
+      }
+
+      // Check type
+      if (!typeAllowlist.includes(inject.type)) {
+        skippedType++;
+        continue;
+      }
+
+      // This inject is eligible
+      selected++;
+      eligibleIds.push(inject.inject_id);
+    }
+
+    return {
+      now: nowIso,
+      scopes_considered: scopeAllowlist,
+      types_considered: typeAllowlist,
+      total_injects: total,
+      selected_eligible: selected,
+      skipped: {
+        expired: skippedExpired,
+        scope: skippedScope,
+        type: skippedType,
+      },
+      eligible_ids: eligibleIds,
+    };
+  }
+
   async function injectEligibleInjects(sessionId: string) {
     const now = nowISO();
     const nowMs = Date.now();
 
-    // Get eligible injects - use allowlists from config or defaults
+    // Get allowlists from config or defaults
     const scopeAllowlist = config.inject?.scope_allowlist ?? ["repo", "global"];
     const typeAllowlist = config.inject?.type_allowlist ?? ["note", "policy"];
 
+    // Get diagnostic data
+    const diagnostics = getInjectionDiagnostics(now, scopeAllowlist, typeAllowlist);
+
     const eligibleInjects = selectEligibleInjects(db, {
       nowIso: now,
       scopeAllowlist,
@@ -47,11 +100,21 @@ export function createInjectProvider(opts: {
       limit: config.inject?.max_per_turn ?? 5,
     });
 
-    if (eligibleInjects.length === 0) return;
+    let injected = 0;
+    let skippedDeduped = 0;
+
+    if (eligibleInjects.length === 0) {
+      // Log when no injects are eligible
+      console.log(`[Astrocode:inject] ${now} selected=${diagnostics.selected_eligible} injected=0 skipped={expired:${diagnostics.skipped.expired} scope:${diagnostics.skipped.scope} type:${diagnostics.skipped.type} deduped:0}`);
+      return;
+    }
 
     // Inject each eligible inject, skipping recently injected ones
     for (const inject of eligibleInjects) {
-      if (shouldSkipInject(inject.inject_id, nowMs)) continue;
+      if (shouldSkipInject(inject.inject_id, nowMs)) {
+        skippedDeduped++;
+        continue;
+      }
 
       // Format as injection message
       const formattedText = `[Inject: ${inject.title}]\n\n${inject.body_md}`;
@@ -63,8 +126,12 @@ export function createInjectProvider(opts: {
         agent: "Astrocode"
       });
 
+      injected++;
       markInjected(inject.inject_id, nowMs);
     }
+
+    // Log diagnostic summary
+    console.log(`[Astrocode:inject] ${now} selected=${diagnostics.selected_eligible} injected=${injected} skipped={expired:${diagnostics.skipped.expired} scope:${diagnostics.skipped.scope} type:${diagnostics.skipped.type} deduped:${skippedDeduped}}`);
   }
 
   // Public hook handlers

package/src/tools/index.ts

@@ -10,7 +10,7 @@ import { createAstroRunGetTool, createAstroRunAbortTool } from "./run";
 import { createAstroWorkflowProceedTool } from "./workflow";
 import { createAstroStageStartTool, createAstroStageCompleteTool, createAstroStageFailTool, createAstroStageResetTool } from "./stage";
 import { createAstroArtifactPutTool, createAstroArtifactListTool, createAstroArtifactGetTool } from "./artifacts";
-import { createAstroInjectPutTool, createAstroInjectListTool, createAstroInjectSearchTool, createAstroInjectGetTool } from "./injects";
+import { createAstroInjectPutTool, createAstroInjectListTool, createAstroInjectSearchTool, createAstroInjectGetTool, createAstroInjectEligibleTool, createAstroInjectDebugDueTool } from "./injects";
 import { createAstroRepairTool } from "./repair";
 
 import { AgentConfig } from "@opencode-ai/sdk";
@@ -50,6 +50,8 @@ export function createAstroTools(opts: { ctx: any; config: AstrocodeConfig; db:
     tools.astro_inject_list = createAstroInjectListTool({ ctx, config, db });
     tools.astro_inject_search = createAstroInjectSearchTool({ ctx, config, db });
     tools.astro_inject_get = createAstroInjectGetTool({ ctx, config, db });
+    tools.astro_inject_eligible = createAstroInjectEligibleTool({ ctx, config, db });
+    tools.astro_inject_debug_due = createAstroInjectDebugDueTool({ ctx, config, db });
     tools.astro_repair = createAstroRepairTool({ ctx, config, db });
   } else {
     // Limited mode tools - provide helpful messages instead of failing

package/src/tools/injects.ts

@@ -174,3 +174,91 @@ export function createAstroInjectEligibleTool(opts: { ctx: any; config: Astrocod
     },
   });
 }
+
+export function createAstroInjectDebugDueTool(opts: { ctx: any; config: AstrocodeConfig; db: SqliteDb }): ToolDefinition {
+  const { db } = opts;
+
+  return tool({
+    description: "Debug: show comprehensive injection diagnostics - why injects were selected/skipped.",
+    args: {
+      scopes_json: tool.schema.string().default('["repo","global"]'),
+      types_json: tool.schema.string().default('["note","policy"]'),
+    },
+    execute: async ({ scopes_json, types_json }) => {
+      const now = nowISO();
+      const scopes = JSON.parse(scopes_json) as string[];
+      const types = JSON.parse(types_json) as string[];
+
+      // Get ALL injects to analyze filtering
+      const allInjects = db.prepare("SELECT * FROM injects").all() as any[];
+
+      let total = allInjects.length;
+      let selected = 0;
+      let skippedExpired = 0;
+      let skippedScope = 0;
+      let skippedType = 0;
+      const excludedReasons: any[] = [];
+      const selectedInjects: any[] = [];
+
+      for (const inject of allInjects) {
+        const reasons: string[] = [];
+
+        // Check expiration
+        if (inject.expires_at && inject.expires_at <= now) {
+          reasons.push("expired");
+          skippedExpired++;
+        }
+
+        // Check scope
+        if (!scopes.includes(inject.scope)) {
+          reasons.push("scope");
+          skippedScope++;
+        }
+
+        // Check type
+        if (!types.includes(inject.type)) {
+          reasons.push("type");
+          skippedType++;
+        }
+
+        if (reasons.length > 0) {
+          excludedReasons.push({
+            inject_id: inject.inject_id,
+            title: inject.title,
+            reasons: reasons,
+            scope: inject.scope,
+            type: inject.type,
+            expires_at: inject.expires_at,
+          });
+        } else {
+          selected++;
+          selectedInjects.push({
+            inject_id: inject.inject_id,
+            title: inject.title,
+            scope: inject.scope,
+            type: inject.type,
+            expires_at: inject.expires_at,
+          });
+        }
+      }
+
+      return JSON.stringify({
+        now,
+        scopes_considered: scopes,
+        types_considered: types,
+        summary: {
+          total_injects: total,
+          selected_eligible: selected,
+          excluded_total: total - selected,
+          skipped_breakdown: {
+            expired: skippedExpired,
+            scope: skippedScope,
+            type: skippedType,
+          }
+        },
+        selected_injects: selectedInjects,
+        excluded_injects: excludedReasons,
+      }, null, 2);
+    },
+  });
+}

package/src/tools/workflow.ts

@@ -13,7 +13,7 @@ import { debug } from "../shared/log";
 import { createToastManager } from "../ui/toasts";
 
 // Agent name mapping for case-sensitive resolution
-const STAGE_TO_AGENT_MAP: Record<string, string> = {
+export const STAGE_TO_AGENT_MAP: Record<string, string> = {
   frame: "Frame",
   plan: "Plan",
   spec: "Spec",
@@ -23,13 +23,40 @@ const STAGE_TO_AGENT_MAP: Record<string, string> = {
   close: "Close"
 };
 
-function resolveAgentName(stageKey: StageKey, config: AstrocodeConfig): string {
+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]) {
-    return 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 STAGE_TO_AGENT_MAP[stageKey] || "General";
+
+  return candidate;
 }
 
 function stageGoal(stage: StageKey, cfg: AstrocodeConfig): string {
@@ -123,6 +150,7 @@ export function createAstroWorkflowProceedTool(opts: { ctx: any; config: Astroco
       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++) {
@@ -212,7 +240,7 @@ 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, config);
+          let agentName = resolveAgentName(next.stage_key, config, agents, warnings);
 
           // Validate agent availability with fallback chain
           const systemConfig = config as any;
@@ -239,7 +267,7 @@ export function createAstroWorkflowProceedTool(opts: { ctx: any; config: Astroco
              // Skip General fallback for stage agents to avoid malformed output
              agentName = config.agents?.orchestrator_name || "Astro";
              if (!agentExists(agentName)) {
-               throw new Error(`Critical: No agents available for delegation. Primary: ${resolveAgentName(next.stage_key, config)}, Orchestrator: ${agentName}`);
+                throw new Error(`Critical: No agents available for delegation. Primary: ${resolveAgentName(next.stage_key, config, agents, warnings)}, Orchestrator: ${agentName}`);
              }
            }
 
@@ -355,6 +383,11 @@ export function createAstroWorkflowProceedTool(opts: { ctx: any; config: Astroco
       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();
     },
   });

package/src/workflow/context.ts

@@ -35,6 +35,57 @@ function statusIcon(status: string): string {
   }
 }
 
+/**
+ * Check if a context snapshot is stale by comparing DB timestamps
+ */
+export function isContextSnapshotStale(snapshotText: string, db: SqliteDb, maxAgeSeconds: number = 300): boolean {
+  // Extract run_id from snapshot
+  const runIdMatch = snapshotText.match(/Run: `([^`]+)`/);
+  if (!runIdMatch) return true; // Can't validate without run_id
+
+  const runId = runIdMatch[1];
+
+  // Extract snapshot's claimed updated_at
+  const snapshotUpdatedMatch = snapshotText.match(/updated: ([^\)]+)\)/);
+  if (!snapshotUpdatedMatch) return true; // Fallback to age-based check
+
+  try {
+    const snapshotUpdatedAt = snapshotUpdatedMatch[1];
+    const currentRun = db.prepare("SELECT updated_at FROM runs WHERE run_id = ?").get(runId) as { updated_at?: string };
+
+    if (!currentRun?.updated_at) return true; // Run doesn't exist
+
+    // Compare timestamps - if DB is newer than snapshot claims, snapshot is stale
+    const snapshotTime = new Date(snapshotUpdatedAt).getTime();
+    const currentTime = new Date(currentRun.updated_at).getTime();
+
+    return currentTime > snapshotTime;
+  } catch (error) {
+    // Fallback to age-based staleness if parsing fails
+    const timestampMatch = snapshotText.match(/generated: (\d{4}-\d{2}-\d{2}T\d{2}:\d{2}:\d{2}\.\d{3}Z)/);
+    if (!timestampMatch) return false;
+
+    const generatedAt = new Date(timestampMatch[1]);
+    const now = new Date();
+    const ageSeconds = (now.getTime() - generatedAt.getTime()) / 1000;
+
+    return ageSeconds > maxAgeSeconds;
+  }
+}
+
+/**
+ * Add staleness indicator to context snapshot if needed
+ */
+export function addStalenessIndicator(snapshotText: string, db: SqliteDb, maxAgeSeconds: number = 300): string {
+  if (isContextSnapshotStale(snapshotText, db, maxAgeSeconds)) {
+    return snapshotText.replace(
+      /# Astrocode Context \(generated: ([^\)]+)\)/,
+      "# Astrocode Context (generated: $1) ⚠️ STALE - DB state has changed"
+    );
+  }
+  return snapshotText;
+}
+
 export function buildContextSnapshot(opts: {
   db: SqliteDb;
   config: AstrocodeConfig;
@@ -52,8 +103,11 @@ export function buildContextSnapshot(opts: {
 
   const lines: string[] = [];
 
-  lines.push(`# Astrocode Context`);
-  lines.push(`- Run: \`${run.run_id}\`  Status: **${run.status}**`);
+  // Add timestamps for staleness checking
+  const now = new Date();
+  const timestamp = now.toISOString();
+  lines.push(`# Astrocode Context (generated: ${timestamp})`);
+  lines.push(`- Run: \`${run.run_id}\`  Status: **${run.status}** (updated: ${run.updated_at})`);
   if (run.current_stage_key) lines.push(`- Current stage: \`${run.current_stage_key}\``);
   if (next_action) lines.push(`- Next action: ${next_action}`);
 

package/src/workflow/directives.ts

@@ -2,6 +2,7 @@ import type { AstrocodeConfig } from "../config/schema";
 import { sha256Hex } from "../shared/hash";
 import { clampChars, normalizeNewlines } from "../shared/text";
 import type { StageKey } from "../state/types";
+import { addStalenessIndicator } from "./context";
 
 export type DirectiveKind = "continue" | "stage" | "blocked" | "repair";
 
@@ -77,8 +78,8 @@ export function buildBlockedDirective(opts: {
       ``,
       `Question: ${question}`,
       ``,
-      `Context snapshot:`,
-      context_snapshot_md.trim(),
+        `Context snapshot:`,
+        context_snapshot_md.trim(),
     ].join("\n")
   ).trim();