@iflow-mcp/jkheadley-instar 0.26.2

package/dist/core/DispatchDecisionJournal.js

@@ -0,0 +1,181 @@
+/**
+ * DispatchDecisionJournal — Dispatch-specific decision journal with query capabilities.
+ *
+ * Extends the base DecisionJournal to provide dispatch-specific logging and
+ * querying. This is the observability foundation for the Discernment Layer.
+ *
+ * Storage: Same JSONL file as DecisionJournal (decision-journal.jsonl).
+ * Dispatch entries are distinguished by `type: 'dispatch'` field.
+ *
+ * Milestone 1: Logging + querying. All entries are structural (auto-applied).
+ * Milestone 4: LLM evaluation adds contextual entries.
+ */
+import fs from 'node:fs';
+import path from 'node:path';
+import { DecisionJournal } from './DecisionJournal.js';
+import { DegradationReporter } from '../monitoring/DegradationReporter.js';
+import { maybeRotateJsonl } from '../utils/jsonl-rotation.js';
+export class DispatchDecisionJournal {
+    journalFile;
+    baseJournal;
+    constructor(stateDir) {
+        this.journalFile = path.join(stateDir, 'decision-journal.jsonl');
+        this.baseJournal = new DecisionJournal(stateDir);
+    }
+    /**
+     * Log a dispatch integration decision.
+     */
+    logDispatchDecision(entry) {
+        const full = {
+            ...entry,
+            type: 'dispatch',
+            // Map dispatchDecision to the base 'decision' field for compatibility
+            decision: `dispatch:${entry.dispatchDecision}`,
+            timestamp: new Date().toISOString(),
+        };
+        // Ensure parent directory exists (lazy creation)
+        const dir = path.dirname(this.journalFile);
+        if (!fs.existsSync(dir)) {
+            fs.mkdirSync(dir, { recursive: true });
+        }
+        maybeRotateJsonl(this.journalFile);
+        fs.appendFileSync(this.journalFile, JSON.stringify(full) + '\n');
+        return full;
+    }
+    /**
+     * Query dispatch decision entries with filtering.
+     */
+    query(options) {
+        const all = this.readDispatchEntries();
+        const cutoff = options?.days
+            ? new Date(Date.now() - options.days * 24 * 60 * 60 * 1000).toISOString()
+            : undefined;
+        let filtered = all.filter(e => {
+            if (cutoff && e.timestamp < cutoff)
+                return false;
+            if (options?.dispatchId && e.dispatchId !== options.dispatchId)
+                return false;
+            if (options?.decision && e.dispatchDecision !== options.decision)
+                return false;
+            if (options?.dispatchType && e.dispatchType !== options.dispatchType)
+                return false;
+            if (options?.evaluationMethod && e.evaluationMethod !== options.evaluationMethod)
+                return false;
+            if (options?.tag && (!e.tags || !e.tags.includes(options.tag)))
+                return false;
+            return true;
+        });
+        // Most recent first. JSONL is append-only so line index breaks ties.
+        // We tag entries with _lineIndex in readDispatchEntries for stable ordering.
+        filtered.sort((a, b) => {
+            const timeDiff = b.timestamp.localeCompare(a.timestamp);
+            if (timeDiff !== 0)
+                return timeDiff;
+            // Same timestamp: later line = more recent
+            return (b._lineIndex ?? 0) - (a._lineIndex ?? 0);
+        });
+        if (options?.limit) {
+            filtered = filtered.slice(0, options.limit);
+        }
+        return filtered;
+    }
+    /**
+     * Get the decision for a specific dispatch ID.
+     * Returns the most recent decision if multiple exist (e.g., defer then accept).
+     */
+    getDecisionForDispatch(dispatchId) {
+        const entries = this.query({ dispatchId, limit: 1 });
+        return entries[0] ?? null;
+    }
+    /**
+     * Check if a dispatch has already been decided on.
+     */
+    hasDecision(dispatchId) {
+        return this.getDecisionForDispatch(dispatchId) !== null;
+    }
+    /**
+     * Get aggregate statistics for dispatch decisions.
+     */
+    stats(options) {
+        const entries = options?.days
+            ? this.query({ days: options.days })
+            : this.readDispatchEntries();
+        if (entries.length === 0) {
+            return {
+                total: 0,
+                byDecision: {},
+                byDispatchType: {},
+                byEvaluationMethod: {},
+                acceptanceRate: 0,
+                earliest: null,
+                latest: null,
+            };
+        }
+        const byDecision = {};
+        const byDispatchType = {};
+        const byEvaluationMethod = {};
+        for (const entry of entries) {
+            byDecision[entry.dispatchDecision] = (byDecision[entry.dispatchDecision] || 0) + 1;
+            byDispatchType[entry.dispatchType] = (byDispatchType[entry.dispatchType] || 0) + 1;
+            byEvaluationMethod[entry.evaluationMethod] = (byEvaluationMethod[entry.evaluationMethod] || 0) + 1;
+        }
+        // Sort chronologically for earliest/latest
+        const sorted = [...entries].sort((a, b) => a.timestamp.localeCompare(b.timestamp));
+        const acceptCount = byDecision['accept'] || 0;
+        return {
+            total: entries.length,
+            byDecision,
+            byDispatchType,
+            byEvaluationMethod,
+            acceptanceRate: entries.length > 0 ? acceptCount / entries.length : 0,
+            earliest: sorted[0].timestamp,
+            latest: sorted[sorted.length - 1].timestamp,
+        };
+    }
+    /**
+     * Get the underlying base journal (for non-dispatch queries).
+     */
+    getBaseJournal() {
+        return this.baseJournal;
+    }
+    /**
+     * Read only dispatch-type entries from the JSONL file.
+     */
+    readDispatchEntries() {
+        if (!fs.existsSync(this.journalFile))
+            return [];
+        try {
+            const content = fs.readFileSync(this.journalFile, 'utf-8').trim();
+            if (!content)
+                return [];
+            const lines = content.split('\n');
+            const entries = [];
+            for (let i = 0; i < lines.length; i++) {
+                try {
+                    const parsed = JSON.parse(lines[i]);
+                    if (parsed.type === 'dispatch') {
+                        // Tag with line index for stable sort tiebreaking
+                        parsed._lineIndex = i;
+                        entries.push(parsed);
+                    }
+                }
+                catch {
+                    // Skip corrupt lines
+                }
+            }
+            return entries;
+        }
+        catch (error) {
+            console.error(`[DispatchDecisionJournal] Failed to read ${this.journalFile}:`, error);
+            DegradationReporter.getInstance().report({
+                feature: 'DispatchDecisionJournal.readDispatchEntries',
+                primary: 'Read dispatch decisions from JSONL',
+                fallback: 'Return empty array — no dispatch history',
+                reason: `Failed to read journal: ${error instanceof Error ? error.message : String(error)}`,
+                impact: 'Discernment Layer lacks dispatch decision data',
+            });
+            return [];
+        }
+    }
+}
+//# sourceMappingURL=DispatchDecisionJournal.js.map

package/dist/core/DispatchDecisionJournal.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"DispatchDecisionJournal.js","sourceRoot":"","sources":["../../src/core/DispatchDecisionJournal.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AAEH,OAAO,EAAE,MAAM,SAAS,CAAC;AACzB,OAAO,IAAI,MAAM,WAAW,CAAC;AAE7B,OAAO,EAAE,eAAe,EAAE,MAAM,sBAAsB,CAAC;AACvD,OAAO,EAAE,mBAAmB,EAAE,MAAM,sCAAsC,CAAC;AAC3E,OAAO,EAAE,gBAAgB,EAAE,MAAM,4BAA4B,CAAC;AAoC9D,MAAM,OAAO,uBAAuB;IAC1B,WAAW,CAAS;IACpB,WAAW,CAAkB;IAErC,YAAY,QAAgB;QAC1B,IAAI,CAAC,WAAW,GAAG,IAAI,CAAC,IAAI,CAAC,QAAQ,EAAE,wBAAwB,CAAC,CAAC;QACjE,IAAI,CAAC,WAAW,GAAG,IAAI,eAAe,CAAC,QAAQ,CAAC,CAAC;IACnD,CAAC;IAED;;OAEG;IACH,mBAAmB,CACjB,KAAqE;QAErE,MAAM,IAAI,GAA0B;YAClC,GAAG,KAAK;YACR,IAAI,EAAE,UAAU;YAChB,sEAAsE;YACtE,QAAQ,EAAE,YAAY,KAAK,CAAC,gBAAgB,EAAE;YAC9C,SAAS,EAAE,IAAI,IAAI,EAAE,CAAC,WAAW,EAAE;SACpC,CAAC;QAEF,iDAAiD;QACjD,MAAM,GAAG,GAAG,IAAI,CAAC,OAAO,CAAC,IAAI,CAAC,WAAW,CAAC,CAAC;QAC3C,IAAI,CAAC,EAAE,CAAC,UAAU,CAAC,GAAG,CAAC,EAAE,CAAC;YACxB,EAAE,CAAC,SAAS,CAAC,GAAG,EAAE,EAAE,SAAS,EAAE,IAAI,EAAE,CAAC,CAAC;QACzC,CAAC;QAED,gBAAgB,CAAC,IAAI,CAAC,WAAW,CAAC,CAAC;QACnC,EAAE,CAAC,cAAc,CAAC,IAAI,CAAC,WAAW,EAAE,IAAI,CAAC,SAAS,CAAC,IAAI,CAAC,GAAG,IAAI,CAAC,CAAC;QACjE,OAAO,IAAI,CAAC;IACd,CAAC;IAED;;OAEG;IACH,KAAK,CAAC,OAAsC;QAC1C,MAAM,GAAG,GAAG,IAAI,CAAC,mBAAmB,EAAE,CAAC;QAEvC,MAAM,MAAM,GAAG,OAAO,EAAE,IAAI;YAC1B,CAAC,CAAC,IAAI,IAAI,CAAC,IAAI,CAAC,GAAG,EAAE,GAAG,OAAO,CAAC,IAAI,GAAG,EAAE,GAAG,EAAE,GAAG,EAAE,GAAG,IAAI,CAAC,CAAC,WAAW,EAAE;YACzE,CAAC,CAAC,SAAS,CAAC;QAEd,IAAI,QAAQ,GAAG,GAAG,CAAC,MAAM,CAAC,CAAC,CAAC,EAAE;YAC5B,IAAI,MAAM,IAAI,CAAC,CAAC,SAAS,GAAG,MAAM;gBAAE,OAAO,KAAK,CAAC;YACjD,IAAI,OAAO,EAAE,UAAU,IAAI,CAAC,CAAC,UAAU,KAAK,OAAO,CAAC,UAAU;gBAAE,OAAO,KAAK,CAAC;YAC7E,IAAI,OAAO,EAAE,QAAQ,IAAI,CAAC,CAAC,gBAAgB,KAAK,OAAO,CAAC,QAAQ;gBAAE,OAAO,KAAK,CAAC;YAC/E,IAAI,OAAO,EAAE,YAAY,IAAI,CAAC,CAAC,YAAY,KAAK,OAAO,CAAC,YAAY;gBAAE,OAAO,KAAK,CAAC;YACnF,IAAI,OAAO,EAAE,gBAAgB,IAAI,CAAC,CAAC,gBAAgB,KAAK,OAAO,CAAC,gBAAgB;gBAAE,OAAO,KAAK,CAAC;YAC/F,IAAI,OAAO,EAAE,GAAG,IAAI,CAAC,CAAC,CAAC,CAAC,IAAI,IAAI,CAAC,CAAC,CAAC,IAAI,CAAC,QAAQ,CAAC,OAAO,CAAC,GAAG,CAAC,CAAC;gBAAE,OAAO,KAAK,CAAC;YAC7E,OAAO,IAAI,CAAC;QACd,CAAC,CAAC,CAAC;QAEH,qEAAqE;QACrE,6EAA6E;QAC7E,QAAQ,CAAC,IAAI,CAAC,CAAC,CAAC,EAAE,CAAC,EAAE,EAAE;YACrB,MAAM,QAAQ,GAAG,CAAC,CAAC,SAAS,CAAC,aAAa,CAAC,CAAC,CAAC,SAAS,CAAC,CAAC;YACxD,IAAI,QAAQ,KAAK,CAAC;gBAAE,OAAO,QAAQ,CAAC;YACpC,2CAA2C;YAC3C,OAAO,CAAE,CAAS,CAAC,UAAU,IAAI,CAAC,CAAC,GAAG,CAAE,CAAS,CAAC,UAAU,IAAI,CAAC,CAAC,CAAC;QACrE,CAAC,CAAC,CAAC;QAEH,IAAI,OAAO,EAAE,KAAK,EAAE,CAAC;YACnB,QAAQ,GAAG,QAAQ,CAAC,KAAK,CAAC,CAAC,EAAE,OAAO,CAAC,KAAK,CAAC,CAAC;QAC9C,CAAC;QAED,OAAO,QAAQ,CAAC;IAClB,CAAC;IAED;;;OAGG;IACH,sBAAsB,CAAC,UAAkB;QACvC,MAAM,OAAO,GAAG,IAAI,CAAC,KAAK,CAAC,EAAE,UAAU,EAAE,KAAK,EAAE,CAAC,EAAE,CAAC,CAAC;QACrD,OAAO,OAAO,CAAC,CAAC,CAAC,IAAI,IAAI,CAAC;IAC5B,CAAC;IAED;;OAEG;IACH,WAAW,CAAC,UAAkB;QAC5B,OAAO,IAAI,CAAC,sBAAsB,CAAC,UAAU,CAAC,KAAK,IAAI,CAAC;IAC1D,CAAC;IAED;;OAEG;IACH,KAAK,CAAC,OAA2B;QAC/B,MAAM,OAAO,GAAG,OAAO,EAAE,IAAI;YAC3B,CAAC,CAAC,IAAI,CAAC,KAAK,CAAC,EAAE,IAAI,EAAE,OAAO,CAAC,IAAI,EAAE,CAAC;YACpC,CAAC,CAAC,IAAI,CAAC,mBAAmB,EAAE,CAAC;QAE/B,IAAI,OAAO,CAAC,MAAM,KAAK,CAAC,EAAE,CAAC;YACzB,OAAO;gBACL,KAAK,EAAE,CAAC;gBACR,UAAU,EAAE,EAAE;gBACd,cAAc,EAAE,EAAE;gBAClB,kBAAkB,EAAE,EAAE;gBACtB,cAAc,EAAE,CAAC;gBACjB,QAAQ,EAAE,IAAI;gBACd,MAAM,EAAE,IAAI;aACb,CAAC;QACJ,CAAC;QAED,MAAM,UAAU,GAA2B,EAAE,CAAC;QAC9C,MAAM,cAAc,GAA2B,EAAE,CAAC;QAClD,MAAM,kBAAkB,GAA2B,EAAE,CAAC;QAEtD,KAAK,MAAM,KAAK,IAAI,OAAO,EAAE,CAAC;YAC5B,UAAU,CAAC,KAAK,CAAC,gBAAgB,CAAC,GAAG,CAAC,UAAU,CAAC,KAAK,CAAC,gBAAgB,CAAC,IAAI,CAAC,CAAC,GAAG,CAAC,CAAC;YACnF,cAAc,CAAC,KAAK,CAAC,YAAY,CAAC,GAAG,CAAC,cAAc,CAAC,KAAK,CAAC,YAAY,CAAC,IAAI,CAAC,CAAC,GAAG,CAAC,CAAC;YACnF,kBAAkB,CAAC,KAAK,CAAC,gBAAgB,CAAC,GAAG,CAAC,kBAAkB,CAAC,KAAK,CAAC,gBAAgB,CAAC,IAAI,CAAC,CAAC,GAAG,CAAC,CAAC;QACrG,CAAC;QAED,2CAA2C;QAC3C,MAAM,MAAM,GAAG,CAAC,GAAG,OAAO,CAAC,CAAC,IAAI,CAAC,CAAC,CAAC,EAAE,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,SAAS,CAAC,aAAa,CAAC,CAAC,CAAC,SAAS,CAAC,CAAC,CAAC;QACnF,MAAM,WAAW,GAAG,UAAU,CAAC,QAAQ,CAAC,IAAI,CAAC,CAAC;QAE9C,OAAO;YACL,KAAK,EAAE,OAAO,CAAC,MAAM;YACrB,UAAU;YACV,cAAc;YACd,kBAAkB;YAClB,cAAc,EAAE,OAAO,CAAC,MAAM,GAAG,CAAC,CAAC,CAAC,CAAC,WAAW,GAAG,OAAO,CAAC,MAAM,CAAC,CAAC,CAAC,CAAC;YACrE,QAAQ,EAAE,MAAM,CAAC,CAAC,CAAC,CAAC,SAAS;YAC7B,MAAM,EAAE,MAAM,CAAC,MAAM,CAAC,MAAM,GAAG,CAAC,CAAC,CAAC,SAAS;SAC5C,CAAC;IACJ,CAAC;IAED;;OAEG;IACH,cAAc;QACZ,OAAO,IAAI,CAAC,WAAW,CAAC;IAC1B,CAAC;IAED;;OAEG;IACK,mBAAmB;QACzB,IAAI,CAAC,EAAE,CAAC,UAAU,CAAC,IAAI,CAAC,WAAW,CAAC;YAAE,OAAO,EAAE,CAAC;QAEhD,IAAI,CAAC;YACH,MAAM,OAAO,GAAG,EAAE,CAAC,YAAY,CAAC,IAAI,CAAC,WAAW,EAAE,OAAO,CAAC,CAAC,IAAI,EAAE,CAAC;YAClE,IAAI,CAAC,OAAO;gBAAE,OAAO,EAAE,CAAC;YAExB,MAAM,KAAK,GAAG,OAAO,CAAC,KAAK,CAAC,IAAI,CAAC,CAAC;YAClC,MAAM,OAAO,GAA4B,EAAE,CAAC;YAC5C,KAAK,IAAI,CAAC,GAAG,CAAC,EAAE,CAAC,GAAG,KAAK,CAAC,MAAM,EAAE,CAAC,EAAE,EAAE,CAAC;gBACtC,IAAI,CAAC;oBACH,MAAM,MAAM,GAAG,IAAI,CAAC,KAAK,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC,CAAC;oBACpC,IAAI,MAAM,CAAC,IAAI,KAAK,UAAU,EAAE,CAAC;wBAC/B,kDAAkD;wBACjD,MAAc,CAAC,UAAU,GAAG,CAAC,CAAC;wBAC/B,OAAO,CAAC,IAAI,CAAC,MAA+B,CAAC,CAAC;oBAChD,CAAC;gBACH,CAAC;gBAAC,MAAM,CAAC;oBACP,qBAAqB;gBACvB,CAAC;YACH,CAAC;YACD,OAAO,OAAO,CAAC;QACjB,CAAC;QAAC,OAAO,KAAK,EAAE,CAAC;YACf,OAAO,CAAC,KAAK,CAAC,4CAA4C,IAAI,CAAC,WAAW,GAAG,EAAE,KAAK,CAAC,CAAC;YACtF,mBAAmB,CAAC,WAAW,EAAE,CAAC,MAAM,CAAC;gBACvC,OAAO,EAAE,6CAA6C;gBACtD,OAAO,EAAE,oCAAoC;gBAC7C,QAAQ,EAAE,0CAA0C;gBACpD,MAAM,EAAE,2BAA2B,KAAK,YAAY,KAAK,CAAC,CAAC,CAAC,KAAK,CAAC,OAAO,CAAC,CAAC,CAAC,MAAM,CAAC,KAAK,CAAC,EAAE;gBAC3F,MAAM,EAAE,gDAAgD;aACzD,CAAC,CAAC;YACH,OAAO,EAAE,CAAC;QACZ,CAAC;IACH,CAAC;CACF"}

package/dist/core/DispatchExecutor.d.ts

@@ -0,0 +1,127 @@
+/**
+ * Dispatch Executor — executes action dispatches programmatically and agentically.
+ *
+ * Two layers of execution:
+ *
+ *   Layer 1 (Programmatic): Structured actions in JSON — shell commands, file
+ *   operations, config merges. Executed mechanically without Claude.
+ *
+ *   Layer 2 (Agentic): Complex instructions that require interpretation.
+ *   Spawns a lightweight Claude session to execute them.
+ *
+ * Action dispatch content format:
+ *   The dispatch `content` field contains a JSON object with:
+ *   - description: Human-readable explanation of what this action does
+ *   - steps: Array of action steps to execute in order
+ *   - verify: Optional verification command (must exit 0 for success)
+ *   - rollback: Optional array of steps to undo on failure
+ *   - conditions: Optional preconditions (version, file existence, etc.)
+ *
+ * Step types:
+ *   - { type: "shell", command: string } — run a shell command
+ *   - { type: "file_write", path: string, content: string } — write a file
+ *   - { type: "file_patch", path: string, find: string, replace: string } — search/replace
+ *   - { type: "config_merge", path: string, merge: object } — deep merge into JSON config
+ *   - { type: "agentic", prompt: string } — spawn Claude to handle complex logic
+ *
+ * Security:
+ *   - Shell commands are run in the project directory with a 60s timeout
+ *   - File paths are resolved relative to the project directory
+ *   - Path traversal (../) is rejected
+ *   - Destructive commands (rm -rf, etc.) are blocked
+ */
+import type { SessionManager } from './SessionManager.js';
+export interface ActionStep {
+    type: 'shell' | 'file_write' | 'file_patch' | 'config_merge' | 'agentic';
+    /** Shell command to run */
+    command?: string;
+    /** File path (relative to project dir) */
+    path?: string;
+    /** Content for file_write, or replacement string for file_patch */
+    content?: string;
+    /** Search string for file_patch */
+    find?: string;
+    /** Replacement string for file_patch */
+    replace?: string;
+    /** JSON object to deep-merge for config_merge */
+    merge?: Record<string, unknown>;
+    /** Prompt for agentic execution */
+    prompt?: string;
+}
+export interface ActionPayload {
+    /** Human-readable description */
+    description: string;
+    /** Steps to execute in order */
+    steps: ActionStep[];
+    /** Optional verification command (must exit 0) */
+    verify?: string;
+    /** Optional rollback steps on failure */
+    rollback?: ActionStep[];
+    /** Optional preconditions */
+    conditions?: {
+        minVersion?: string;
+        maxVersion?: string;
+        fileExists?: string;
+        fileNotExists?: string;
+    };
+}
+export interface ExecutionResult {
+    success: boolean;
+    /** Which steps completed successfully */
+    completedSteps: number;
+    /** Total steps attempted */
+    totalSteps: number;
+    /** Human-readable summary */
+    message: string;
+    /** Output from each step */
+    stepResults: StepResult[];
+    /** Whether verification passed */
+    verified: boolean;
+    /** Whether rollback was attempted */
+    rolledBack: boolean;
+}
+export interface StepResult {
+    step: number;
+    type: string;
+    success: boolean;
+    output?: string;
+    error?: string;
+}
+export declare class DispatchExecutor {
+    private projectDir;
+    private sessionManager;
+    constructor(projectDir: string, sessionManager?: SessionManager | null);
+    /**
+     * Parse an action payload from dispatch content.
+     * Returns null if the content is not valid action JSON.
+     */
+    parseAction(content: string): ActionPayload | null;
+    /**
+     * Execute an action dispatch.
+     *
+     * 1. Check preconditions
+     * 2. Execute steps in order
+     * 3. Verify success
+     * 4. Rollback on failure (if rollback steps provided)
+     */
+    execute(payload: ActionPayload): Promise<ExecutionResult>;
+    /**
+     * Execute a single step.
+     */
+    private executeStep;
+    private runShell;
+    private writeFile;
+    private patchFile;
+    private mergeConfig;
+    private runAgentic;
+    /**
+     * Resolve a path relative to the project directory.
+     * Returns null if the path escapes the project dir.
+     */
+    private resolvePath;
+    /**
+     * Check preconditions for an action dispatch.
+     */
+    private checkConditions;
+}
+//# sourceMappingURL=DispatchExecutor.d.ts.map

package/dist/core/DispatchExecutor.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"DispatchExecutor.d.ts","sourceRoot":"","sources":["../../src/core/DispatchExecutor.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA+BG;AAKH,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,qBAAqB,CAAC;AAK1D,MAAM,WAAW,UAAU;IACzB,IAAI,EAAE,OAAO,GAAG,YAAY,GAAG,YAAY,GAAG,cAAc,GAAG,SAAS,CAAC;IACzE,2BAA2B;IAC3B,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,0CAA0C;IAC1C,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,mEAAmE;IACnE,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,mCAAmC;IACnC,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,wCAAwC;IACxC,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,iDAAiD;IACjD,KAAK,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IAChC,mCAAmC;IACnC,MAAM,CAAC,EAAE,MAAM,CAAC;CACjB;AAED,MAAM,WAAW,aAAa;IAC5B,iCAAiC;IACjC,WAAW,EAAE,MAAM,CAAC;IACpB,gCAAgC;IAChC,KAAK,EAAE,UAAU,EAAE,CAAC;IACpB,kDAAkD;IAClD,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,yCAAyC;IACzC,QAAQ,CAAC,EAAE,UAAU,EAAE,CAAC;IACxB,6BAA6B;IAC7B,UAAU,CAAC,EAAE;QACX,UAAU,CAAC,EAAE,MAAM,CAAC;QACpB,UAAU,CAAC,EAAE,MAAM,CAAC;QACpB,UAAU,CAAC,EAAE,MAAM,CAAC;QACpB,aAAa,CAAC,EAAE,MAAM,CAAC;KACxB,CAAC;CACH;AAED,MAAM,WAAW,eAAe;IAC9B,OAAO,EAAE,OAAO,CAAC;IACjB,yCAAyC;IACzC,cAAc,EAAE,MAAM,CAAC;IACvB,4BAA4B;IAC5B,UAAU,EAAE,MAAM,CAAC;IACnB,6BAA6B;IAC7B,OAAO,EAAE,MAAM,CAAC;IAChB,4BAA4B;IAC5B,WAAW,EAAE,UAAU,EAAE,CAAC;IAC1B,kCAAkC;IAClC,QAAQ,EAAE,OAAO,CAAC;IAClB,qCAAqC;IACrC,UAAU,EAAE,OAAO,CAAC;CACrB;AAED,MAAM,WAAW,UAAU;IACzB,IAAI,EAAE,MAAM,CAAC;IACb,IAAI,EAAE,MAAM,CAAC;IACb,OAAO,EAAE,OAAO,CAAC;IACjB,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,KAAK,CAAC,EAAE,MAAM,CAAC;CAChB;AAkBD,qBAAa,gBAAgB;IAC3B,OAAO,CAAC,UAAU,CAAS;IAC3B,OAAO,CAAC,cAAc,CAAwB;gBAElC,UAAU,EAAE,MAAM,EAAE,cAAc,CAAC,EAAE,cAAc,GAAG,IAAI;IAKtE;;;OAGG;IACH,WAAW,CAAC,OAAO,EAAE,MAAM,GAAG,aAAa,GAAG,IAAI;IAYlD;;;;;;;OAOG;IACG,OAAO,CAAC,OAAO,EAAE,aAAa,GAAG,OAAO,CAAC,eAAe,CAAC;IAwE/D;;OAEG;YACW,WAAW;YAiCX,QAAQ;IAmCtB,OAAO,CAAC,SAAS;IAcjB,OAAO,CAAC,SAAS;IAqBjB,OAAO,CAAC,WAAW;YAoBL,UAAU;IAyCxB;;;OAGG;IACH,OAAO,CAAC,WAAW;IAenB;;OAEG;YACW,eAAe;CAqB9B"}

package/dist/core/DispatchExecutor.js

@@ -0,0 +1,355 @@
+/**
+ * Dispatch Executor — executes action dispatches programmatically and agentically.
+ *
+ * Two layers of execution:
+ *
+ *   Layer 1 (Programmatic): Structured actions in JSON — shell commands, file
+ *   operations, config merges. Executed mechanically without Claude.
+ *
+ *   Layer 2 (Agentic): Complex instructions that require interpretation.
+ *   Spawns a lightweight Claude session to execute them.
+ *
+ * Action dispatch content format:
+ *   The dispatch `content` field contains a JSON object with:
+ *   - description: Human-readable explanation of what this action does
+ *   - steps: Array of action steps to execute in order
+ *   - verify: Optional verification command (must exit 0 for success)
+ *   - rollback: Optional array of steps to undo on failure
+ *   - conditions: Optional preconditions (version, file existence, etc.)
+ *
+ * Step types:
+ *   - { type: "shell", command: string } — run a shell command
+ *   - { type: "file_write", path: string, content: string } — write a file
+ *   - { type: "file_patch", path: string, find: string, replace: string } — search/replace
+ *   - { type: "config_merge", path: string, merge: object } — deep merge into JSON config
+ *   - { type: "agentic", prompt: string } — spawn Claude to handle complex logic
+ *
+ * Security:
+ *   - Shell commands are run in the project directory with a 60s timeout
+ *   - File paths are resolved relative to the project directory
+ *   - Path traversal (../) is rejected
+ *   - Destructive commands (rm -rf, etc.) are blocked
+ */
+import { execFile } from 'node:child_process';
+import fs from 'node:fs';
+import path from 'node:path';
+import { DegradationReporter } from '../monitoring/DegradationReporter.js';
+// ── Blocked patterns ───────────────────────────────────────────────
+const BLOCKED_COMMANDS = [
+    /\brm\s+(-rf?|--force)\s+[\/~]/,
+    /\brm\s+-rf?\s+\./,
+    /\bmkfs\b/,
+    /\bdd\s+if=/,
+    /\b(shutdown|reboot|halt)\b/,
+    /\bcurl\b.*\|\s*(sh|bash)\b/,
+    /\bwget\b.*\|\s*(sh|bash)\b/,
+    />\s*\/dev\//,
+    /\bchmod\s+777\b/,
+];
+// ── Executor ───────────────────────────────────────────────────────
+export class DispatchExecutor {
+    projectDir;
+    sessionManager;
+    constructor(projectDir, sessionManager) {
+        this.projectDir = projectDir;
+        this.sessionManager = sessionManager ?? null;
+    }
+    /**
+     * Parse an action payload from dispatch content.
+     * Returns null if the content is not valid action JSON.
+     */
+    parseAction(content) {
+        try {
+            const parsed = JSON.parse(content);
+            if (!parsed || typeof parsed !== 'object')
+                return null;
+            if (!Array.isArray(parsed.steps) || parsed.steps.length === 0)
+                return null;
+            return parsed;
+        }
+        catch {
+            // @silent-fallback-ok — malformed JSON rejected
+            return null;
+        }
+    }
+    /**
+     * Execute an action dispatch.
+     *
+     * 1. Check preconditions
+     * 2. Execute steps in order
+     * 3. Verify success
+     * 4. Rollback on failure (if rollback steps provided)
+     */
+    async execute(payload) {
+        const stepResults = [];
+        let completedSteps = 0;
+        // Check preconditions
+        if (payload.conditions) {
+            const condResult = await this.checkConditions(payload.conditions);
+            if (!condResult.met) {
+                return {
+                    success: false,
+                    completedSteps: 0,
+                    totalSteps: payload.steps.length,
+                    message: `Precondition not met: ${condResult.reason}`,
+                    stepResults: [],
+                    verified: false,
+                    rolledBack: false,
+                };
+            }
+        }
+        // Execute steps
+        for (let i = 0; i < payload.steps.length; i++) {
+            const step = payload.steps[i];
+            const result = await this.executeStep(step, i);
+            stepResults.push(result);
+            if (result.success) {
+                completedSteps++;
+            }
+            else {
+                // Step failed — attempt rollback if available
+                let rolledBack = false;
+                if (payload.rollback && payload.rollback.length > 0) {
+                    console.log(`[DispatchExecutor] Step ${i} failed, rolling back...`);
+                    for (const rbStep of payload.rollback) {
+                        await this.executeStep(rbStep, -1).catch(() => { });
+                    }
+                    rolledBack = true;
+                }
+                return {
+                    success: false,
+                    completedSteps,
+                    totalSteps: payload.steps.length,
+                    message: `Step ${i + 1} failed: ${result.error || 'Unknown error'}`,
+                    stepResults,
+                    verified: false,
+                    rolledBack,
+                };
+            }
+        }
+        // Verify if verification command is provided
+        let verified = true;
+        if (payload.verify) {
+            const verifyResult = await this.runShell(payload.verify);
+            verified = verifyResult.success;
+            if (!verified) {
+                console.log(`[DispatchExecutor] Verification failed: ${verifyResult.error}`);
+            }
+        }
+        return {
+            success: true,
+            completedSteps,
+            totalSteps: payload.steps.length,
+            message: `All ${completedSteps} steps completed${verified ? ' and verified' : ' (verification failed)'}`,
+            stepResults,
+            verified,
+            rolledBack: false,
+        };
+    }
+    /**
+     * Execute a single step.
+     */
+    async executeStep(step, index) {
+        const base = {
+            step: index,
+            type: step.type,
+        };
+        try {
+            switch (step.type) {
+                case 'shell':
+                    return { ...base, ...await this.runShell(step.command) };
+                case 'file_write':
+                    return { ...base, ...this.writeFile(step.path, step.content) };
+                case 'file_patch':
+                    return { ...base, ...this.patchFile(step.path, step.find, step.replace) };
+                case 'config_merge':
+                    return { ...base, ...this.mergeConfig(step.path, step.merge) };
+                case 'agentic':
+                    return { ...base, ...await this.runAgentic(step.prompt) };
+                default:
+                    return { ...base, success: false, error: `Unknown step type: ${step.type}` };
+            }
+        }
+        catch (err) {
+            return { ...base, success: false, error: err instanceof Error ? err.message : String(err) };
+        }
+    }
+    // ── Step implementations ─────────────────────────────────────────
+    async runShell(command) {
+        if (!command || typeof command !== 'string') {
+            return { success: false, error: 'Empty command' };
+        }
+        // Security: block dangerous commands
+        for (const pattern of BLOCKED_COMMANDS) {
+            if (pattern.test(command)) {
+                return { success: false, error: `Blocked: command matches dangerous pattern` };
+            }
+        }
+        return new Promise((resolve) => {
+            execFile('sh', ['-c', command], {
+                cwd: this.projectDir,
+                encoding: 'utf-8',
+                timeout: 60_000,
+                maxBuffer: 1024 * 1024,
+            }, (err, stdout, stderr) => {
+                if (err) {
+                    resolve({
+                        success: false,
+                        output: stdout?.trim(),
+                        error: stderr?.trim() || err.message,
+                    });
+                }
+                else {
+                    resolve({
+                        success: true,
+                        output: (stdout || '').trim(),
+                    });
+                }
+            });
+        });
+    }
+    writeFile(filePath, content) {
+        const resolved = this.resolvePath(filePath);
+        if (!resolved)
+            return { success: false, error: `Invalid path: ${filePath}` };
+        try {
+            const dir = path.dirname(resolved);
+            fs.mkdirSync(dir, { recursive: true });
+            fs.writeFileSync(resolved, content);
+            return { success: true, output: `Wrote ${content.length} bytes to ${filePath}` };
+        }
+        catch (err) {
+            return { success: false, error: err instanceof Error ? err.message : String(err) };
+        }
+    }
+    patchFile(filePath, find, replace) {
+        const resolved = this.resolvePath(filePath);
+        if (!resolved)
+            return { success: false, error: `Invalid path: ${filePath}` };
+        if (!fs.existsSync(resolved)) {
+            return { success: false, error: `File not found: ${filePath}` };
+        }
+        try {
+            const content = fs.readFileSync(resolved, 'utf-8');
+            if (!content.includes(find)) {
+                return { success: false, error: `Search string not found in ${filePath}` };
+            }
+            const patched = content.replace(find, replace);
+            fs.writeFileSync(resolved, patched);
+            return { success: true, output: `Patched ${filePath}` };
+        }
+        catch (err) {
+            return { success: false, error: err instanceof Error ? err.message : String(err) };
+        }
+    }
+    mergeConfig(filePath, merge) {
+        const resolved = this.resolvePath(filePath);
+        if (!resolved)
+            return { success: false, error: `Invalid path: ${filePath}` };
+        try {
+            let existing = {};
+            if (fs.existsSync(resolved)) {
+                existing = JSON.parse(fs.readFileSync(resolved, 'utf-8'));
+            }
+            const merged = deepMerge(existing, merge);
+            const dir = path.dirname(resolved);
+            fs.mkdirSync(dir, { recursive: true });
+            fs.writeFileSync(resolved, JSON.stringify(merged, null, 2) + '\n');
+            return { success: true, output: `Merged ${Object.keys(merge).length} keys into ${filePath}` };
+        }
+        catch (err) {
+            return { success: false, error: err instanceof Error ? err.message : String(err) };
+        }
+    }
+    async runAgentic(prompt) {
+        if (!this.sessionManager) {
+            return { success: false, error: 'SessionManager not available for agentic execution' };
+        }
+        try {
+            // Spawn a lightweight session to handle the complex dispatch
+            const sessionName = `dispatch-${Date.now().toString(36)}`;
+            const fullPrompt = [
+                'You are executing an intelligence dispatch from the Instar update system.',
+                'Follow the instructions below precisely. Report what you did.',
+                '',
+                prompt,
+            ].join('\n');
+            const tmuxSession = await this.sessionManager.spawnSession({
+                name: sessionName,
+                prompt: fullPrompt,
+                maxDurationMinutes: 10,
+                model: 'haiku',
+                jobSlug: 'dispatch-action',
+            });
+            return {
+                success: true,
+                output: `Spawned agentic session: ${tmuxSession}`,
+            };
+        }
+        catch (err) {
+            DegradationReporter.getInstance().report({
+                feature: 'DispatchExecutor.executeStep',
+                primary: 'Spawn agentic session for dispatch action',
+                fallback: 'Return error to user',
+                reason: `Why: ${err instanceof Error ? err.message : String(err)}`,
+                impact: 'Dispatch action failed — user notified but no system alert',
+            });
+            return { success: false, error: err instanceof Error ? err.message : String(err) };
+        }
+    }
+    // ── Helpers ──────────────────────────────────────────────────────
+    /**
+     * Resolve a path relative to the project directory.
+     * Returns null if the path escapes the project dir.
+     */
+    resolvePath(filePath) {
+        if (!filePath || typeof filePath !== 'string')
+            return null;
+        // Reject obvious traversal attempts
+        if (filePath.includes('..'))
+            return null;
+        if (path.isAbsolute(filePath))
+            return null;
+        const resolved = path.resolve(this.projectDir, filePath);
+        // Verify the resolved path is still inside the project dir
+        if (!resolved.startsWith(this.projectDir))
+            return null;
+        return resolved;
+    }
+    /**
+     * Check preconditions for an action dispatch.
+     */
+    async checkConditions(conditions) {
+        if (conditions.fileExists) {
+            const resolved = this.resolvePath(conditions.fileExists);
+            if (!resolved || !fs.existsSync(resolved)) {
+                return { met: false, reason: `Required file not found: ${conditions.fileExists}` };
+            }
+        }
+        if (conditions.fileNotExists) {
+            const resolved = this.resolvePath(conditions.fileNotExists);
+            if (resolved && fs.existsSync(resolved)) {
+                return { met: false, reason: `File must not exist: ${conditions.fileNotExists}` };
+            }
+        }
+        // Version conditions are checked by DispatchManager before reaching executor
+        return { met: true };
+    }
+}
+// ── Deep merge utility ─────────────────────────────────────────────
+function deepMerge(target, source) {
+    const result = { ...target };
+    for (const key of Object.keys(source)) {
+        const sourceVal = source[key];
+        const targetVal = result[key];
+        if (sourceVal && typeof sourceVal === 'object' && !Array.isArray(sourceVal) &&
+            targetVal && typeof targetVal === 'object' && !Array.isArray(targetVal)) {
+            result[key] = deepMerge(targetVal, sourceVal);
+        }
+        else {
+            result[key] = sourceVal;
+        }
+    }
+    return result;
+}
+//# sourceMappingURL=DispatchExecutor.js.map