astrocode-workflow 0.1.53 → 0.1.56

package/dist/config/schema.d.ts

@@ -172,6 +172,12 @@ export declare const AstrocodeConfigSchema: z.ZodDefault<z.ZodObject<{
             idle_prompt_ms: z.ZodOptional<z.ZodDefault<z.ZodNumber>>;
         }, z.core.$strip>>>;
     }, z.core.$strip>>>;
+    inject: z.ZodOptional<z.ZodDefault<z.ZodObject<{
+        enabled: z.ZodOptional<z.ZodDefault<z.ZodBoolean>>;
+        scope_allowlist: z.ZodOptional<z.ZodDefault<z.ZodArray<z.ZodString>>>;
+        type_allowlist: z.ZodOptional<z.ZodDefault<z.ZodArray<z.ZodString>>>;
+        max_per_turn: z.ZodOptional<z.ZodDefault<z.ZodNumber>>;
+    }, z.core.$strip>>>;
 }, z.core.$strip>>;
 export type AstrocodeConfig = z.infer<typeof AstrocodeConfigSchema>;
 export {};

package/dist/config/schema.js

@@ -161,6 +161,15 @@ const GitSchema = z.object({
     commit_message_template: z.string().default("astro: {{story_key}} {{title}}"),
     persist_diff_artifacts: z.boolean().default(true),
 }).partial().default({});
+const InjectSchema = z
+    .object({
+    enabled: z.boolean().default(true),
+    scope_allowlist: z.array(z.string()).default(["repo", "global"]),
+    type_allowlist: z.array(z.string()).default(["note", "policy"]),
+    max_per_turn: z.number().int().positive().default(5),
+})
+    .partial()
+    .default({});
 const UiSchema = z
     .object({
     toasts: ToastsSchema,
@@ -196,4 +205,5 @@ export const AstrocodeConfigSchema = z.object({
     permissions: PermissionsSchema,
     git: GitSchema,
     ui: UiSchema,
+    inject: InjectSchema,
 }).partial().default({});

package/dist/hooks/inject-provider.d.ts

@@ -0,0 +1,14 @@
+import type { AstrocodeConfig } from "../config/schema";
+import type { SqliteDb } from "../state/db";
+type ChatMessageInput = {
+    sessionID: string;
+    agent: string;
+};
+export declare function createInjectProvider(opts: {
+    ctx: any;
+    config: AstrocodeConfig;
+    db: SqliteDb;
+}): {
+    onChatMessage(input: ChatMessageInput): Promise<void>;
+};
+export {};

package/dist/hooks/inject-provider.js

@@ -0,0 +1,112 @@
+import { selectEligibleInjects } from "../tools/injects";
+import { injectChatPrompt } from "../ui/inject";
+import { nowISO } from "../shared/time";
+export function createInjectProvider(opts) {
+    const { ctx, config, db } = opts;
+    // Cache to avoid re-injecting the same injects repeatedly
+    const injectedCache = new Map();
+    function shouldSkipInject(injectId, nowMs) {
+        const lastInjected = injectedCache.get(injectId);
+        if (!lastInjected)
+            return false;
+        // Skip if injected within the last 5 minutes (configurable?)
+        const cooldownMs = 5 * 60 * 1000;
+        return nowMs - lastInjected < cooldownMs;
+    }
+    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 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,
+        });
+        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)) {
+                skippedDeduped++;
+                continue;
+            }
+            // Format as injection message
+            const formattedText = `[Inject: ${inject.title}]\n\n${inject.body_md}`;
+            await injectChatPrompt({
+                ctx,
+                sessionId,
+                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 {
+        async onChatMessage(input) {
+            if (!config.inject?.enabled)
+                return;
+            // Inject eligible injects before processing the user's message
+            await injectEligibleInjects(input.sessionID);
+        },
+    };
+}

package/dist/index.js

@@ -5,6 +5,7 @@ import { getAstroPaths, ensureAstroDirs } from "./shared/paths";
 import { createAstroTools } from "./tools";
 import { createContinuationEnforcer } from "./hooks/continuation-enforcer";
 import { createToolOutputTruncatorHook } from "./hooks/tool-output-truncator";
+import { createInjectProvider } from "./hooks/inject-provider";
 import { createToastManager } from "./ui/toasts";
 import { createAstroAgents } from "./agents/registry";
 const Astrocode = async (ctx) => {
@@ -21,6 +22,7 @@ const Astrocode = async (ctx) => {
     let configHandler = null;
     let continuation = null;
     let truncatorHook = null;
+    let injectProvider = null;
     let toasts = null;
     try {
         db = openSqlite(paths.dbPath, { busyTimeoutMs: pluginConfig.db.busy_timeout_ms });
@@ -31,6 +33,7 @@ const Astrocode = async (ctx) => {
         tools = createAstroTools({ ctx, config: pluginConfig, db, agents });
         continuation = createContinuationEnforcer({ ctx, config: pluginConfig, db });
         truncatorHook = createToolOutputTruncatorHook({ ctx, config: pluginConfig, db });
+        injectProvider = createInjectProvider({ ctx, config: pluginConfig, db });
         toasts = createToastManager({ ctx, throttleMs: pluginConfig.ui.toasts.throttle_ms });
     }
     catch (e) {
@@ -46,6 +49,7 @@ const Astrocode = async (ctx) => {
         tools = createAstroTools({ ctx, config: pluginConfig, db, agents });
         continuation = null;
         truncatorHook = null;
+        injectProvider = null;
         toasts = null;
     }
     return {
@@ -80,6 +84,9 @@ const Astrocode = async (ctx) => {
             }
         },
         "chat.message": async (input, output) => {
+            if (injectProvider && !pluginConfig.disabled_hooks.includes("inject-provider")) {
+                await injectProvider.onChatMessage(input);
+            }
             if (continuation && !pluginConfig.disabled_hooks.includes("continuation-enforcer")) {
                 await continuation.onChatMessage(input);
             }

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

@@ -21,3 +21,33 @@ export declare function createAstroInjectSearchTool(opts: {
     config: AstrocodeConfig;
     db: SqliteDb;
 }): ToolDefinition;
+export type InjectRow = {
+    inject_id: string;
+    type: string;
+    title: string;
+    body_md: string;
+    tags_json: string;
+    scope: string;
+    source: string;
+    priority: number;
+    expires_at: string | null;
+    sha256: string;
+    created_at: string;
+    updated_at: string;
+};
+export declare function selectEligibleInjects(db: SqliteDb, opts: {
+    nowIso: string;
+    scopeAllowlist: string[];
+    typeAllowlist: string[];
+    limit?: number;
+}): InjectRow[];
+export declare function createAstroInjectEligibleTool(opts: {
+    ctx: any;
+    config: AstrocodeConfig;
+    db: SqliteDb;
+}): ToolDefinition;
+export declare function createAstroInjectDebugDueTool(opts: {
+    ctx: any;
+    config: AstrocodeConfig;
+    db: SqliteDb;
+}): ToolDefinition;

package/dist/tools/injects.js

@@ -97,3 +97,122 @@ export function createAstroInjectSearchTool(opts) {
         },
     });
 }
+export function selectEligibleInjects(db, opts) {
+    const { nowIso, scopeAllowlist, typeAllowlist, limit = 50 } = opts;
+    // Build placeholders safely
+    const scopeQs = scopeAllowlist.map(() => "?").join(", ");
+    const typeQs = typeAllowlist.map(() => "?").join(", ");
+    const sql = `
+    SELECT *
+    FROM injects
+    WHERE (expires_at IS NULL OR expires_at > ?)
+      AND scope IN (${scopeQs})
+      AND type IN (${typeQs})
+    ORDER BY priority DESC, updated_at DESC
+    LIMIT ?
+  `;
+    const params = [nowIso, ...scopeAllowlist, ...typeAllowlist, limit];
+    return db.prepare(sql).all(...params);
+}
+export function createAstroInjectEligibleTool(opts) {
+    const { db } = opts;
+    return tool({
+        description: "Debug: show which injects are eligible right now for injection.",
+        args: {
+            scopes_json: tool.schema.string().default('["repo","global"]'),
+            types_json: tool.schema.string().default('["note","policy"]'),
+            limit: tool.schema.number().int().positive().default(50),
+        },
+        execute: async ({ scopes_json, types_json, limit }) => {
+            const now = nowISO();
+            const scopes = JSON.parse(scopes_json);
+            const types = JSON.parse(types_json);
+            const rows = selectEligibleInjects(db, {
+                nowIso: now,
+                scopeAllowlist: scopes,
+                typeAllowlist: types,
+                limit,
+            });
+            return JSON.stringify({ now, count: rows.length, rows }, null, 2);
+        },
+    });
+}
+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,22 +9,48 @@ 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 = {
-    frame: "frame",
-    plan: "plan",
-    spec: "spec",
-    implement: "implement",
-    review: "review",
-    verify: "verify",
-    close: "close"
+export const STAGE_TO_AGENT_MAP = {
+    frame: "Frame",
+    plan: "Plan",
+    spec: "Spec",
+    implement: "Implement",
+    review: "Review",
+    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.53",
+  "version": "0.1.56",
   "type": "module",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",

package/src/config/schema.ts

@@ -194,6 +194,16 @@ const GitSchema = z.object({
   persist_diff_artifacts: z.boolean().default(true),
 }).partial().default({});
 
+const InjectSchema = z
+  .object({
+    enabled: z.boolean().default(true),
+    scope_allowlist: z.array(z.string()).default(["repo", "global"]),
+    type_allowlist: z.array(z.string()).default(["note", "policy"]),
+    max_per_turn: z.number().int().positive().default(5),
+  })
+  .partial()
+  .default({});
+
 const UiSchema = z
   .object({
     toasts: ToastsSchema,
@@ -232,6 +242,7 @@ export const AstrocodeConfigSchema = z.object({
   permissions: PermissionsSchema,
   git: GitSchema,
   ui: UiSchema,
+  inject: InjectSchema,
 }).partial().default({});
 
 export type AstrocodeConfig = z.infer<typeof AstrocodeConfigSchema>;

package/src/hooks/inject-provider.ts

@@ -0,0 +1,146 @@
+import type { AstrocodeConfig } from "../config/schema";
+import type { SqliteDb } from "../state/db";
+import { selectEligibleInjects } from "../tools/injects";
+import { injectChatPrompt } from "../ui/inject";
+import { nowISO } from "../shared/time";
+
+type ChatMessageInput = {
+  sessionID: string;
+  agent: string;
+};
+
+export function createInjectProvider(opts: {
+  ctx: any;
+  config: AstrocodeConfig;
+  db: SqliteDb;
+}) {
+  const { ctx, config, db } = opts;
+
+  // Cache to avoid re-injecting the same injects repeatedly
+  const injectedCache = new Map<string, number>();
+
+  function shouldSkipInject(injectId: string, nowMs: number): boolean {
+    const lastInjected = injectedCache.get(injectId);
+    if (!lastInjected) return false;
+
+    // Skip if injected within the last 5 minutes (configurable?)
+    const cooldownMs = 5 * 60 * 1000;
+    return nowMs - lastInjected < cooldownMs;
+  }
+
+  function markInjected(injectId: string, nowMs: number) {
+    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 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,
+    });
+
+    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)) {
+        skippedDeduped++;
+        continue;
+      }
+
+      // Format as injection message
+      const formattedText = `[Inject: ${inject.title}]\n\n${inject.body_md}`;
+
+      await injectChatPrompt({
+        ctx,
+        sessionId,
+        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 {
+    async onChatMessage(input: ChatMessageInput) {
+      if (!config.inject?.enabled) return;
+
+      // Inject eligible injects before processing the user's message
+      await injectEligibleInjects(input.sessionID);
+    },
+  };
+}

package/src/index.ts

@@ -6,6 +6,7 @@ import { getAstroPaths, ensureAstroDirs } from "./shared/paths";
 import { createAstroTools } from "./tools";
 import { createContinuationEnforcer } from "./hooks/continuation-enforcer";
 import { createToolOutputTruncatorHook } from "./hooks/tool-output-truncator";
+import { createInjectProvider } from "./hooks/inject-provider";
 import { createToastManager } from "./ui/toasts";
 import { createAstroAgents } from "./agents/registry";
 import { info, warn } from "./shared/log";
@@ -25,10 +26,11 @@ const Astrocode: Plugin = async (ctx) => {
 
   let db: any = null;
   let tools: any = null;
-  let configHandler: any = null;
-  let continuation: any = null;
-  let truncatorHook: any = null;
-  let toasts: any = null;
+    let configHandler: any = null;
+    let continuation: any = null;
+    let truncatorHook: any = null;
+    let injectProvider: any = null;
+    let toasts: any = null;
 
   try {
 
@@ -41,6 +43,7 @@ const Astrocode: Plugin = async (ctx) => {
     tools = createAstroTools({ ctx, config: pluginConfig, db, agents });
     continuation = createContinuationEnforcer({ ctx, config: pluginConfig, db });
     truncatorHook = createToolOutputTruncatorHook({ ctx, config: pluginConfig, db });
+    injectProvider = createInjectProvider({ ctx, config: pluginConfig, db });
     toasts = createToastManager({ ctx, throttleMs: pluginConfig.ui.toasts.throttle_ms });
   } catch (e) {
     // Database initialization failed - setup limited mode
@@ -58,6 +61,7 @@ const Astrocode: Plugin = async (ctx) => {
     tools = createAstroTools({ ctx, config: pluginConfig, db, agents });
     continuation = null;
     truncatorHook = null;
+    injectProvider = null;
     toasts = null;
   }
 
@@ -102,6 +106,9 @@ const Astrocode: Plugin = async (ctx) => {
     },
 
     "chat.message": async (input: any, output: any) => {
+      if (injectProvider && !pluginConfig.disabled_hooks.includes("inject-provider")) {
+        await injectProvider.onChatMessage(input);
+      }
       if (continuation && !pluginConfig.disabled_hooks.includes("continuation-enforcer")) {
         await continuation.onChatMessage(input);
       }

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

@@ -106,3 +106,159 @@ export function createAstroInjectSearchTool(opts: { ctx: any; config: AstrocodeC
     },
   });
 }
+
+export type InjectRow = {
+  inject_id: string;
+  type: string;
+  title: string;
+  body_md: string;
+  tags_json: string;
+  scope: string;
+  source: string;
+  priority: number;
+  expires_at: string | null;
+  sha256: string;
+  created_at: string;
+  updated_at: string;
+};
+
+export function selectEligibleInjects(db: SqliteDb, opts: {
+  nowIso: string;
+  scopeAllowlist: string[];
+  typeAllowlist: string[];
+  limit?: number;
+}): InjectRow[] {
+  const { nowIso, scopeAllowlist, typeAllowlist, limit = 50 } = opts;
+
+  // Build placeholders safely
+  const scopeQs = scopeAllowlist.map(() => "?").join(", ");
+  const typeQs = typeAllowlist.map(() => "?").join(", ");
+
+  const sql = `
+    SELECT *
+    FROM injects
+    WHERE (expires_at IS NULL OR expires_at > ?)
+      AND scope IN (${scopeQs})
+      AND type IN (${typeQs})
+    ORDER BY priority DESC, updated_at DESC
+    LIMIT ?
+  `;
+
+  const params = [nowIso, ...scopeAllowlist, ...typeAllowlist, limit];
+  return db.prepare(sql).all(...params) as InjectRow[];
+}
+
+export function createAstroInjectEligibleTool(opts: { ctx: any; config: AstrocodeConfig; db: SqliteDb }): ToolDefinition {
+  const { db } = opts;
+
+  return tool({
+    description: "Debug: show which injects are eligible right now for injection.",
+    args: {
+      scopes_json: tool.schema.string().default('["repo","global"]'),
+      types_json: tool.schema.string().default('["note","policy"]'),
+      limit: tool.schema.number().int().positive().default(50),
+    },
+    execute: async ({ scopes_json, types_json, limit }) => {
+      const now = nowISO();
+      const scopes = JSON.parse(scopes_json) as string[];
+      const types = JSON.parse(types_json) as string[];
+
+      const rows = selectEligibleInjects(db, {
+        nowIso: now,
+        scopeAllowlist: scopes,
+        typeAllowlist: types,
+        limit,
+      });
+
+      return JSON.stringify({ now, count: rows.length, rows }, null, 2);
+    },
+  });
+}
+
+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,23 +13,50 @@ 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> = {
-  frame: "frame",
-  plan: "plan",
-  spec: "spec",
-  implement: "implement",
-  review: "review",
-  verify: "verify",
-  close: "close"
+export const STAGE_TO_AGENT_MAP: Record<string, string> = {
+  frame: "Frame",
+  plan: "Plan",
+  spec: "Spec",
+  implement: "Implement",
+  review: "Review",
+  verify: "Verify",
+  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();