@telora/factory 0.4.5

package/dist/crash-resolution.d.ts

@@ -0,0 +1,34 @@
+/**
+ * Per-entity recovery actions for factory crash recovery.
+ *
+ * Performs recovery actions for each type of orphaned entity found during
+ * crash detection:
+ *   - WIP-commit uncommitted changes in orphaned worktrees
+ *   - Reset factory_sessions stuck in 'running' to 'failed'
+ *   - Reset factory_instances stuck in 'building'/'gating' to 'paused'
+ *   - Create escalations for paused instances
+ *   - Reset orphaned execution units to 'idle'
+ *
+ * Runs after config init and before the poll loop starts, so the factory
+ * starts in a clean, known state.
+ */
+import type { FactoryConfig } from './types.js';
+import { type RecoveryResult } from './crash-detection.js';
+/**
+ * Run full crash recovery on factory orchestrator startup.
+ *
+ * Should be called after config init and API client setup, but before
+ * the poll loop starts. Safe to call multiple times -- idempotent by
+ * design. A second run with no crashed state finds nothing to recover.
+ *
+ * Recovery steps:
+ * 1. Scan for orphaned worktrees and WIP-commit uncommitted changes.
+ * 2. Reset factory_sessions stuck in 'running' to 'failed'.
+ * 3. Reset factory_instances stuck in 'building'/'gating' to 'paused'.
+ * 4. Create escalations for paused instances.
+ *
+ * @param config - Factory configuration.
+ * @returns      A RecoveryResult summarizing all actions taken.
+ */
+export declare function recoverFromCrash(config: FactoryConfig): Promise<RecoveryResult>;
+//# sourceMappingURL=crash-resolution.d.ts.map

package/dist/crash-resolution.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"crash-resolution.d.ts","sourceRoot":"","sources":["../src/crash-resolution.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;GAaG;AAEH,OAAO,KAAK,EAAE,aAAa,EAAmB,MAAM,YAAY,CAAC;AAMjE,OAAO,EAIL,KAAK,cAAc,EACpB,MAAM,sBAAsB,CAAC;AAoU9B;;;;;;;;;;;;;;;GAeG;AACH,wBAAsB,gBAAgB,CAAC,MAAM,EAAE,aAAa,GAAG,OAAO,CAAC,cAAc,CAAC,CA4FrF"}

package/dist/crash-resolution.js

@@ -0,0 +1,382 @@
+/**
+ * Per-entity recovery actions for factory crash recovery.
+ *
+ * Performs recovery actions for each type of orphaned entity found during
+ * crash detection:
+ *   - WIP-commit uncommitted changes in orphaned worktrees
+ *   - Reset factory_sessions stuck in 'running' to 'failed'
+ *   - Reset factory_instances stuck in 'building'/'gating' to 'paused'
+ *   - Create escalations for paused instances
+ *   - Reset orphaned execution units to 'idle'
+ *
+ * Runs after config init and before the poll loop starts, so the factory
+ * starts in a clean, known state.
+ */
+import { commitWip } from './git-factory.js';
+import { updateInstanceStatus, getActiveInstances } from './queries/instances.js';
+import { updateFactorySession } from './queries/sessions.js';
+import { createFactoryEscalation } from './queries/escalations.js';
+import { getExecutionUnitsByInstance, updateExecutionUnit } from './queries/execution-units.js';
+import { scanFactoryWorktrees, } from './crash-detection.js';
+// ============================================================================
+// Recovery: orphaned worktrees
+// ============================================================================
+/**
+ * WIP-commit any uncommitted changes in orphaned factory worktrees.
+ *
+ * This preserves in-flight work that was not committed before the crash.
+ * The worktrees are left in place -- they will be reused when the instance
+ * resumes (after being reset to 'paused').
+ */
+function recoverOrphanedWorktrees(orphans) {
+    let wipCommitsCreated = 0;
+    const actions = [];
+    for (const orphan of orphans) {
+        const label = orphan.branchName ?? 'unknown-branch';
+        try {
+            const sha = commitWip(orphan.worktreePath, `crash-recovery: ${label}`);
+            if (sha) {
+                wipCommitsCreated++;
+                actions.push({
+                    type: 'worktree_wip_committed',
+                    entityId: orphan.worktreePath,
+                    description: `WIP commit ${sha.slice(0, 8)} created for orphaned worktree (branch: ${label})`,
+                });
+                console.log(`[crash-recovery] WIP commit ${sha.slice(0, 8)} for orphaned worktree: ${orphan.worktreePath}`);
+            }
+            else {
+                console.log(`[crash-recovery] Orphaned worktree has no uncommitted changes: ${orphan.worktreePath}`);
+            }
+        }
+        catch (err) {
+            console.warn(`[crash-recovery] Failed to WIP-commit orphaned worktree ${orphan.worktreePath}: ` +
+                `${err instanceof Error ? err.message : String(err)}`);
+        }
+    }
+    return { wipCommitsCreated, actions };
+}
+// ============================================================================
+// Recovery: stale sessions
+// ============================================================================
+/**
+ * Reset factory sessions stuck in 'running' or 'starting' status to 'failed'.
+ *
+ * After a crash, any sessions that were 'running' are no longer actually
+ * running -- their processes died with the orchestrator. We query the API
+ * for all instances that might have active sessions and reset them.
+ */
+async function recoverStaleSessions(config) {
+    const sessionsReset = 0;
+    const actions = [];
+    const errors = [];
+    // We need to find sessions stuck in 'running' status. Since we don't have
+    // a direct "get all running sessions" query, we use getActiveSessionsForInstance
+    // for each instance that might have stale sessions. We get the instances from
+    // the pending query (which returns instances that aren't in terminal states).
+    //
+    // However, getPendingInstances only returns 'pending' status. For crash
+    // recovery we need instances in 'building' and 'gating' states too.
+    // Those will be handled via the instance recovery below, which also
+    // resets their sessions. But we still want a catch-all for any sessions
+    // that might be orphaned.
+    //
+    // The approach: reset sessions for instances we know about from worktree
+    // scanning. The instance recovery step will handle the rest.
+    // Note: Session reset for specific instances happens in recoverStuckInstances.
+    // This function serves as documentation of the strategy. The actual per-instance
+    // session reset is co-located with the instance status reset for atomicity.
+    void config; // Config may be used in future for direct session queries
+    return { sessionsReset, actions, errors };
+}
+// ============================================================================
+// Recovery: stuck instances
+// ============================================================================
+/**
+ * Find and recover factory instances stuck in 'building' or 'gating' status.
+ *
+ * After an unclean shutdown, these instances had active processing that
+ * was interrupted. We:
+ * 1. Reset their status to 'paused'.
+ * 2. Mark their active sessions as 'failed'.
+ * 3. Create an escalation to notify the human operator.
+ */
+async function recoverStuckInstances(config) {
+    let instancesPaused = 0;
+    let sessionsReset = 0;
+    let escalationsCreated = 0;
+    const actions = [];
+    const errors = [];
+    // Query non-terminal instances (designing, planning, building, paused) and
+    // filter for those stuck in active processing states after the crash.
+    let instances;
+    try {
+        instances = await getActiveInstances(config.productId);
+    }
+    catch (err) {
+        const msg = `Failed to query instances for crash recovery: ${err instanceof Error ? err.message : String(err)}`;
+        console.warn(`[crash-recovery] ${msg}`);
+        errors.push(msg);
+        return { instancesPaused, sessionsReset, escalationsCreated, actions, errors };
+    }
+    // Filter for instances that are stuck in active processing states
+    // Note: 'gating' was removed as an instance-level status -- gates run
+    // inline per work unit during the 'building' phase.
+    const stuckStatuses = new Set(['building']);
+    const stuckInstances = instances.filter((inst) => stuckStatuses.has(inst.status));
+    if (stuckInstances.length === 0) {
+        console.log('[crash-recovery] No stuck instances found in building status');
+        return { instancesPaused, sessionsReset, escalationsCreated, actions, errors };
+    }
+    console.log(`[crash-recovery] Found ${stuckInstances.length} instance(s) stuck in building/gating status`);
+    for (const instance of stuckInstances) {
+        // Step 1: Reset active sessions to 'failed'
+        try {
+            const { getActiveSessionsForInstance } = await import('./queries/sessions.js');
+            const activeSessions = await getActiveSessionsForInstance(instance.id);
+            for (const session of activeSessions) {
+                try {
+                    await updateFactorySession(session.id, {
+                        status: 'failed',
+                        endedAt: new Date().toISOString(),
+                    });
+                    sessionsReset++;
+                    actions.push({
+                        type: 'session_reset',
+                        entityId: session.id,
+                        description: `Session reset from '${session.status}' to 'failed' (instance ${instance.id}, crash recovery)`,
+                    });
+                }
+                catch (err) {
+                    const msg = `Failed to reset session ${session.id}: ${err instanceof Error ? err.message : String(err)}`;
+                    console.warn(`[crash-recovery] ${msg}`);
+                    errors.push(msg);
+                }
+            }
+        }
+        catch (err) {
+            const msg = `Failed to query sessions for instance ${instance.id}: ${err instanceof Error ? err.message : String(err)}`;
+            console.warn(`[crash-recovery] ${msg}`);
+            errors.push(msg);
+        }
+        // Step 2: Reset instance status to 'paused'
+        try {
+            await updateInstanceStatus(instance.id, 'paused', {
+                escalationReason: 'Unclean shutdown recovery',
+                escalationMessage: `Factory orchestrator crashed or was killed while instance was in '${instance.status}' status. ` +
+                    'Instance has been paused for manual review. Active sessions have been marked as failed. ' +
+                    'Resume or cancel this instance from the control panel.',
+                escalatedAt: new Date().toISOString(),
+            });
+            instancesPaused++;
+            actions.push({
+                type: 'instance_paused',
+                entityId: instance.id,
+                description: `Instance reset from '${instance.status}' to 'paused' (crash recovery)`,
+            });
+            console.log(`[crash-recovery] Instance ${instance.id} reset: ${instance.status} -> paused`);
+        }
+        catch (err) {
+            const msg = `Failed to pause instance ${instance.id}: ${err instanceof Error ? err.message : String(err)}`;
+            console.error(`[crash-recovery] ${msg}`);
+            errors.push(msg);
+            continue; // Skip escalation if we couldn't even pause the instance
+        }
+        // Step 3: Create escalation
+        try {
+            await createFactoryEscalation(instance.id, 'Unclean shutdown: factory orchestrator crashed', `Instance was in '${instance.status}' status when the factory orchestrator shut down unexpectedly. ` +
+                `The instance has been paused and its active sessions marked as failed. ` +
+                `Please review the instance state and either resume or cancel it.`);
+            escalationsCreated++;
+            actions.push({
+                type: 'escalation_created',
+                entityId: instance.id,
+                description: `Escalation created for instance paused during crash recovery (was '${instance.status}')`,
+            });
+            console.log(`[crash-recovery] Created escalation for instance ${instance.id}`);
+        }
+        catch (err) {
+            const msg = `Failed to create escalation for instance ${instance.id}: ${err instanceof Error ? err.message : String(err)}`;
+            console.warn(`[crash-recovery] ${msg}`);
+            errors.push(msg);
+        }
+    }
+    return { instancesPaused, sessionsReset, escalationsCreated, actions, errors };
+}
+// ============================================================================
+// Recovery: orphaned execution units
+// ============================================================================
+/**
+ * Reset execution units stuck in 'assigned' or 'running' status to 'idle'.
+ *
+ * After a crash, these units had active sessions that died with the daemon.
+ * We query ALL active (non-terminal) instances and reset their orphaned units.
+ * This runs BEFORE instance adoption so the scheduler sees clean state.
+ */
+async function recoverOrphanedExecutionUnits(config) {
+    let executionUnitsReset = 0;
+    const actions = [];
+    const errors = [];
+    let instances;
+    try {
+        instances = await getActiveInstances(config.productId);
+    }
+    catch (err) {
+        const msg = `Failed to query instances for execution unit recovery: ${err instanceof Error ? err.message : String(err)}`;
+        console.warn(`[crash-recovery] ${msg}`);
+        errors.push(msg);
+        return { executionUnitsReset, actions, errors };
+    }
+    // Only building instances have execution units
+    const buildingInstances = instances.filter((inst) => inst.status === 'building');
+    if (buildingInstances.length === 0) {
+        console.log('[crash-recovery] No building instances found -- skipping execution unit recovery');
+        return { executionUnitsReset, actions, errors };
+    }
+    for (const instance of buildingInstances) {
+        let units;
+        try {
+            units = await getExecutionUnitsByInstance(instance.id);
+        }
+        catch (err) {
+            const msg = `Failed to query execution units for instance ${instance.id}: ${err instanceof Error ? err.message : String(err)}`;
+            console.warn(`[crash-recovery] ${msg}`);
+            errors.push(msg);
+            continue;
+        }
+        const orphanedUnits = units.filter((u) => u.status === 'assigned' || u.status === 'running');
+        for (const unit of orphanedUnits) {
+            try {
+                await updateExecutionUnit(unit.id, {
+                    status: 'idle',
+                    assignedStrategyId: null,
+                    claudeSessionId: null,
+                    assignedAt: null,
+                });
+                executionUnitsReset++;
+                actions.push({
+                    type: 'execution_unit_reset',
+                    entityId: unit.id,
+                    description: `Execution unit reset from '${unit.status}' to 'idle' ` +
+                        `(instance ${instance.id}, slot ${unit.slotIndex}, crash recovery)`,
+                });
+                console.log(`[crash-recovery] Reset execution unit ${unit.id} (slot ${unit.slotIndex}) ` +
+                    `from '${unit.status}' to 'idle' (instance ${instance.id})`);
+            }
+            catch (err) {
+                const msg = `Failed to reset execution unit ${unit.id}: ${err instanceof Error ? err.message : String(err)}`;
+                console.warn(`[crash-recovery] ${msg}`);
+                errors.push(msg);
+            }
+        }
+    }
+    if (executionUnitsReset > 0) {
+        console.log(`[crash-recovery] Reset ${executionUnitsReset} orphaned execution unit(s) to idle`);
+    }
+    else {
+        console.log('[crash-recovery] No orphaned execution units found');
+    }
+    return { executionUnitsReset, actions, errors };
+}
+// ============================================================================
+// Main recovery orchestrator
+// ============================================================================
+/**
+ * Run full crash recovery on factory orchestrator startup.
+ *
+ * Should be called after config init and API client setup, but before
+ * the poll loop starts. Safe to call multiple times -- idempotent by
+ * design. A second run with no crashed state finds nothing to recover.
+ *
+ * Recovery steps:
+ * 1. Scan for orphaned worktrees and WIP-commit uncommitted changes.
+ * 2. Reset factory_sessions stuck in 'running' to 'failed'.
+ * 3. Reset factory_instances stuck in 'building'/'gating' to 'paused'.
+ * 4. Create escalations for paused instances.
+ *
+ * @param config - Factory configuration.
+ * @returns      A RecoveryResult summarizing all actions taken.
+ */
+export async function recoverFromCrash(config) {
+    console.log('[crash-recovery] Starting factory crash recovery scan...');
+    const result = {
+        orphanedWorktreesFound: 0,
+        wipCommitsCreated: 0,
+        sessionsReset: 0,
+        instancesPaused: 0,
+        escalationsCreated: 0,
+        executionUnitsReset: 0,
+        actions: [],
+        errors: [],
+    };
+    // Step 1: Scan for orphaned worktrees and WIP-commit uncommitted changes
+    try {
+        const orphans = scanFactoryWorktrees(config);
+        result.orphanedWorktreesFound = orphans.length;
+        if (orphans.length > 0) {
+            console.log(`[crash-recovery] Found ${orphans.length} worktree(s) in factory-worktrees directory`);
+            const worktreeResult = recoverOrphanedWorktrees(orphans);
+            result.wipCommitsCreated = worktreeResult.wipCommitsCreated;
+            result.actions.push(...worktreeResult.actions);
+        }
+        else {
+            console.log('[crash-recovery] No orphaned factory worktrees found');
+        }
+    }
+    catch (err) {
+        const msg = `Failed during worktree scan: ${err instanceof Error ? err.message : String(err)}`;
+        console.error(`[crash-recovery] ${msg}`);
+        result.errors.push(msg);
+    }
+    // Step 2: Reset stale sessions (catch-all for sessions not tied to instances)
+    try {
+        const sessionResult = await recoverStaleSessions(config);
+        result.sessionsReset += sessionResult.sessionsReset;
+        result.actions.push(...sessionResult.actions);
+        result.errors.push(...sessionResult.errors);
+    }
+    catch (err) {
+        const msg = `Failed during stale session recovery: ${err instanceof Error ? err.message : String(err)}`;
+        console.error(`[crash-recovery] ${msg}`);
+        result.errors.push(msg);
+    }
+    // Step 3: Reset orphaned execution units (assigned/running -> idle)
+    // This runs BEFORE instance adoption so the scheduler sees clean state.
+    try {
+        const euResult = await recoverOrphanedExecutionUnits(config);
+        result.executionUnitsReset = euResult.executionUnitsReset;
+        result.actions.push(...euResult.actions);
+        result.errors.push(...euResult.errors);
+    }
+    catch (err) {
+        const msg = `Failed during execution unit recovery: ${err instanceof Error ? err.message : String(err)}`;
+        console.error(`[crash-recovery] ${msg}`);
+        result.errors.push(msg);
+    }
+    // Step 4: Reset stuck instances (building/gating -> paused) and their sessions
+    try {
+        const instanceResult = await recoverStuckInstances(config);
+        result.instancesPaused = instanceResult.instancesPaused;
+        result.sessionsReset += instanceResult.sessionsReset;
+        result.escalationsCreated = instanceResult.escalationsCreated;
+        result.actions.push(...instanceResult.actions);
+        result.errors.push(...instanceResult.errors);
+    }
+    catch (err) {
+        const msg = `Failed during stuck instance recovery: ${err instanceof Error ? err.message : String(err)}`;
+        console.error(`[crash-recovery] ${msg}`);
+        result.errors.push(msg);
+    }
+    // Summary
+    console.log(`[crash-recovery] Factory recovery complete: ` +
+        `${result.orphanedWorktreesFound} worktree(s) found, ` +
+        `${result.wipCommitsCreated} WIP commit(s), ` +
+        `${result.sessionsReset} session(s) reset, ` +
+        `${result.executionUnitsReset} execution unit(s) reset, ` +
+        `${result.instancesPaused} instance(s) paused, ` +
+        `${result.escalationsCreated} escalation(s) created`);
+    if (result.errors.length > 0) {
+        console.warn(`[crash-recovery] ${result.errors.length} non-fatal error(s) during recovery`);
+    }
+    return result;
+}
+//# sourceMappingURL=crash-resolution.js.map

package/dist/crash-resolution.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"crash-resolution.js","sourceRoot":"","sources":["../src/crash-resolution.ts"],"names":[],"mappings":"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"}

package/dist/escalation.d.ts

@@ -0,0 +1,150 @@
+/**
+ * Factory instance escalation and stuck detection.
+ *
+ * Handles escalation when resource limits are hit or the factory gets stuck.
+ * Pauses the instance and signals the human via the agent_escalations table.
+ *
+ * Stuck detection identifies when the same gate is failing N consecutive
+ * times with the same error pattern, indicating the builder is unable to
+ * make progress.
+ *
+ * Resume support: when a human resolves the escalation, the instance can
+ * transition from 'paused' back to 'building' via resumeInstance().
+ */
+import type { FactoryBlueprint, FactoryInstanceState, FactoryGateResult } from './types.js';
+/** Configuration for escalation behavior. */
+export interface EscalationConfig {
+    /**
+     * Number of consecutive gate failures with the same error pattern
+     * before triggering a stuck escalation. Defaults to 3.
+     */
+    stuckThreshold: number;
+}
+/** Result of a stuck detection check for a strategy. */
+export interface StuckDetectionResult {
+    /** Whether the strategy appears to be stuck. */
+    isStuck: boolean;
+    /** The strategy ID. */
+    strategyId: string;
+    /** The repeated gate type (if stuck). */
+    gateType: string | null;
+    /** The repeated error pattern (if stuck). */
+    errorPattern: string | null;
+    /** Number of consecutive failures with the same pattern. */
+    consecutiveFailures: number;
+}
+/** Trigger fired when resource limits (token budget, wall clock, etc.) are exceeded. */
+export declare const TRIGGER_RESOURCE_LIMIT_EXCEEDED = "resource_limit_exceeded";
+/** Trigger fired when a builder appears stuck (same gate failure repeated). */
+export declare const TRIGGER_BUILDER_STUCK = "builder_stuck";
+/** Trigger fired when a work unit exhausts all gate retry iterations. */
+export declare const TRIGGER_GATE_FAILURE_EXHAUSTED = "gate_failure_exhausted";
+/** Trigger fired when strategy-level gate evaluation fails. */
+export declare const TRIGGER_STRATEGY_GATE_FAILED = "strategy_gate_failed";
+/**
+ * Escalate a factory instance.
+ *
+ * Sets the instance status to 'paused', records the escalation reason
+ * and message on the instance record, and creates an escalation entry
+ * in the agent_escalations table to signal the human.
+ *
+ * @param instanceId - The factory instance UUID.
+ * @param reason     - Short reason for the escalation (e.g. "token_budget_exceeded").
+ * @param message    - Detailed human-readable message describing the situation.
+ * @param config     - Optional escalation configuration overrides.
+ * @param sessionId  - Optional session ID to link the escalation to.
+ */
+export declare function escalateInstance(instanceId: string, reason: string, message: string, config?: Partial<EscalationConfig>, sessionId?: string | null): Promise<void>;
+/**
+ * Escalate a factory instance using its in-memory state.
+ *
+ * Attempts a workflow-governed transition from the current status to
+ * 'paused'. If the workflow allows it (or no workflow exists), updates
+ * in-memory state and persists the escalation.
+ */
+export declare function escalateInstanceState(state: FactoryInstanceState, reason: string, message: string, config?: Partial<EscalationConfig>, sessionId?: string | null): Promise<void>;
+/**
+ * Resume a paused factory instance.
+ *
+ * Attempts a workflow-governed transition from 'paused' back to 'building'
+ * and clears the escalation fields. This is called when a human resolves
+ * the escalation and wants the factory to continue.
+ *
+ * @param instanceId - The factory instance UUID.
+ * @param state      - The in-memory instance state (if available).
+ */
+export declare function resumeInstance(instanceId: string, state?: FactoryInstanceState): Promise<void>;
+/**
+ * Check whether a given trigger name is configured in the blueprint's
+ * escalation triggers list.
+ *
+ * If the trigger is in the list, the scenario should cause a pause+escalate.
+ * If not, the scenario should cause an immediate failure.
+ *
+ * @param blueprint - The factory blueprint with escalationTriggers config.
+ * @param triggerName - The trigger name to check (e.g. TRIGGER_RESOURCE_LIMIT_EXCEEDED).
+ * @returns true if the trigger should cause an escalation.
+ */
+export declare function shouldEscalate(blueprint: FactoryBlueprint, triggerName: string): boolean;
+/**
+ * Route an escalation-worthy event to either pause+escalate or immediate failure.
+ *
+ * If the trigger name is in the blueprint's escalationTriggers list, pauses
+ * the instance and creates an escalation. Otherwise, calls the onFail callback
+ * to fail the instance immediately.
+ *
+ * @param state       - The in-memory instance state.
+ * @param triggerName - The trigger category (e.g. TRIGGER_RESOURCE_LIMIT_EXCEEDED).
+ * @param reason      - Short reason for the escalation.
+ * @param message     - Detailed human-readable message.
+ * @param onFail      - Callback invoked when the trigger is not configured for escalation.
+ * @param config      - Optional escalation configuration overrides.
+ */
+export declare function escalateOrFail(state: FactoryInstanceState, triggerName: string, reason: string, message: string, onFail: () => void | Promise<void>, config?: Partial<EscalationConfig>, sessionId?: string | null): Promise<void>;
+/**
+ * Detect whether any strategies in an instance appear to be stuck.
+ *
+ * A strategy is considered "stuck" when the same gate has failed N
+ * consecutive times (where N is the stuckThreshold) with the same
+ * error pattern. This indicates the builder is unable to make progress
+ * despite retries.
+ *
+ * Gate results are grouped by strategy_id and analyzed per-strategy.
+ *
+ * @param instanceState - The in-memory state of the factory instance.
+ * @param config        - Optional escalation configuration overrides.
+ * @returns Array of stuck detection results (one per stuck strategy).
+ */
+export declare function detectStuckStrategies(instanceState: FactoryInstanceState, config?: Partial<EscalationConfig>): Promise<StuckDetectionResult[]>;
+/**
+ * Check stuck detection and escalate or fail based on blueprint triggers.
+ *
+ * Convenience function that combines detectStuckStrategies() with
+ * escalateOrFail(). Returns true if the instance was escalated or failed.
+ *
+ * @param onFail - Callback invoked when TRIGGER_BUILDER_STUCK is not in
+ *                 escalationTriggers and the instance should fail instead.
+ */
+export declare function checkAndEscalateIfStuck(state: FactoryInstanceState, onFail: () => void | Promise<void>, config?: Partial<EscalationConfig>): Promise<boolean>;
+/**
+ * Analyze gate results for a single strategy to detect stuck patterns.
+ *
+ * Looks at the most recent gate results in reverse chronological order.
+ * If N consecutive failed results have the same gate type and normalized
+ * error output, the strategy is considered stuck.
+ */
+export declare function analyzeGateResultsForStuck(strategyId: string, gateResults: FactoryGateResult[], threshold: number): StuckDetectionResult;
+/**
+ * Normalize an error output string for pattern comparison.
+ *
+ * Applies the following normalizations:
+ *   - Trims whitespace
+ *   - Collapses multiple whitespace to single space
+ *   - Truncates to ERROR_PATTERN_MAX_LENGTH characters
+ *   - Returns empty string for null/undefined input
+ *
+ * This allows comparing error outputs that differ only in timestamps,
+ * line numbers, or minor formatting variations.
+ */
+export declare function normalizeErrorPattern(output: string | null): string;
+//# sourceMappingURL=escalation.d.ts.map

package/dist/escalation.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"escalation.d.ts","sourceRoot":"","sources":["../src/escalation.ts"],"names":[],"mappings":"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"}